resolution

A response object which synchronously replicates features of Promise and more

Install

npm install resolution

or

npm install -g resolution

Then import the module into your program:

var Resolution = require('resolution')

Description

A Resolution_ Object can be used as a response object (function return value)

States

It can be in one of the following states:

• pending - This means the Resolution_ Object has been initialized, but not yet resolved or rejected

• fulfilled - This means the Resolution_ Object was successful in its operation, or resolved

• rejected - This means the Resolution_ Object was unsuccessful in its operation, or rejected

Properties

The state of any Resolution_ Object can be determined multiple ways. Each Resolution_ Object has the following properties:

• state - String - The name of the current state

• pending - Boolean - True if this Resolution_ Object is in the pending state

• fulfilled - Boolean - True if this Resolution_ Object is in the fulfilled state

  • resolved will also produce the same result

• rejected - Boolean - True if this Resolution_ Object is in the rejected state

Along with being in a specific state, a Resolution_ Object also has a value associated with it.

It can be accessed with the following property:

• value - Any - The value associated with this Resolution_ Object

Types

Resolution_ Objects comes in two types: Immutable and Mutable

Immutable Resolution Objects behave precisely as Promises do, except everything is handled synchronously.

Mutable Resolution Objects behave the same Promises during initialization, but the state and value can still be modified after execution.

Comparison to Promises

Along with everything mentioned above, every Resolution_ Object has the same properties as a Promise does (and more)

Check out the Instance Methods sections of the API for more details

• Immutable Instance Methods
• Mutable Instance Methods

The Resolution_ Constructor also has the same properties that the Promise Constructor does (and more)

Check out Class Methods section of the API for more details

To see the tests proving that Resolutions_ and Promises have the same behavior, run the following from within the module directory:

npm run promise-test

or check out tests\promiseTest.js

API

• Initializing Immutable Resolution
  • Immutable Instance Methods
• Initializing Mutable Resolution
  • Mutable Instance Methods
• Class Methods

Initialize Immutable Resolutions

Back to Top

A Resolution object can be created the same way a Promise can:

• Resolution( fn )

• fn - Function - Function which will resolve or reject the Resolution. Has the following arguments:

  • resolve - Function - Function to resolve this Resolution with the given value

  • reject - Function - Function to reject this Resolution with the given value

Note :

• An error will be thrown if fn is not a function

Examples

Can be invoked with or without the new keyword

var res = Resolution(function( resolve, reject ){
  resolve( 100 );
})
//res.state = 'fulfilled'
//res.value = 100

var res = new Resolution(function( resolve, reject ){
  reject( 0 );
})
//res.state = 'rejected'
//res.value = 0

var res = Resolution(function(){})
//res.state = 'pending'
//res.value = undefined

Only the first invocation of resolve or reject will have any effect

var res = Resolution(function( resolve, reject ){
  resolve( 100 );
  reject( 0 );
})
//res.state = 'fulfilled'
//res.value = 100

Invoking resolve or reject the Resolution asynchronously will not have any effect

var res = Resolution(function( resolve, reject ){
  setTimeout(function(){
    resolve( 100 );
  },1000)
})

//Immediately:
//res.state = 'pending'
//res.value = undefined

// > 1000 ms later:
//res.state = 'pending'
//res.value = undefined

Any errors thrown during the execution of fn will automatically reject the Resolution with the error as the value

• Unless the Resolution was resolved or rejected before the error was thrown

var res = Resolution(function( resolve, reject ){
  throw new Error()
})
//res.state = 'rejected'
//res.value = Error

var res = Resolution(function( resolve, reject ){
  resolve( 100 );
  throw new Error()
})
//res.state = 'fulfilled'
//res.value = 100

A Resolution Object can also be initialized into a specific state:

• Resolution.resolve( value )

• Resolution.reject( value )

• Resolution.pending( value )

  • value - Any - The value associated with this Resolution_ Object

Examples

var res = Resolution.resolve(100)
//res.state = 'fulfilled'
//res.value = 100

var res = Resolution.reject(0)
//res.state = 'rejected'
//res.value = 0

var res = Resolution.pending(50)
//res.state = 'pending'
//res.value = 50

Immutable Instance Methods

Back to Top

As with Promises, a Resolution_ Object can automatically invoke functions based on the *state8

• then( onResolve, onReject )

  • onResolve - Function - Function to run if this Resolution Object is resolved.

  • onReject - Function - Function to run if this Resolution Object is rejected.

For both, the input argument is the value of this Resolution Object

Returns a new Resolution Object resolved to the return value of the callback function.

• If the callback function was not invoked, then the state and value of the new Resolution Object will match this Resolution Object
• If the callback function throws an error, then the new Resolution Object will be rejected with that error.

Examples

var res = Resolution(function( resolve, reject ){
  resolve( 100 );
})
.then(function( value ){
  console.log('Resolved to ' + value);
},function( value ){
  console.log('Rejected to ' + value);
});
//Resolved to 100

var res = Resolution(function( resolve, reject ){
  reject( 0 );
})
.then(function( value ){
  console.log('Resolved to ' + value);
},function( value ){
  console.log('Rejected to ' + value);
});
//Rejected to 0

Because it returns a new Resolution Object, the then's can be chained

var res = Resolution.resolve(100)
.then(function( value ){
  return value-1;
})
.then(function( value ){
  console.log('Resolved to ' + value);
});
//Resolved to 99

var res = Resolution.resolve(100)
.then(function(){
  throw new Error()
})
.then(function( value ){
  console.log('Resolved');
},function( value ){
  console.log('Error')
});
//Error

• catch( onReject )

  • onReject - Function - Function to run if this Resolution Object is rejected.

The input argument is the value of this Resolution Object

Returns a new Resolution Object resolved to the return value of the callback function.

• If the callback function was not invoked, then the state and value of the new Resolution Object will match this Resolution Object
• If the callback function throws an error, then the new Resolution Object will be rejected with that error.

Equivalent to calling then( undefined, onReject )

Examples

var res = Resolution.reject(0)
.catch(function( value ){
  console.log('Rejected to ' + value);
});
//Rejected to 0

var res = Resolution.reject(0)
.then(function( value ){
  console.log('Resolved to ' + value);
})
.catch(function( value ){
  console.log('Rejected to ' + value);
});
//Rejected to 0

var res = Resolution.resolve(100)
.catch(function( value ){
  console.log('Rejected to ' + value);
})
.then(function( value ){
  console.log('Resolved to ' + value);
});
//Resolved to 100

var res = Resolution.resolve(100)
.then(function( value ){
  throw new Error();
})
.catch(function( value ){
  console.log('Error');
});
//Error

Initialize Mutable Resolutions

Back to Top

A Mutable Resolution Object follows the same principals as an Immutable Resolution Object when initializing.

See here for Initializing Immutable Resolutions

• Resolution.Mutable( fn )

The only difference between a Mutable Resolution and Immutable Resolution Objects during initialization is that the state of a Mutable Resolution Object can be set more than once or asynchronously.

var res = Resolution.Mutable(function( resolve, reject ){
    resolve(100);
    reject(0);
})
//res.state = 'rejected'
//res.value = 0

var res = Resolution.Mutable(function( resolve, reject ){
    setTimeout(function(){
        resolve( 100 );
    },1000);
})

//Immediately:
//res.state = 'pending'
//res.value = undefined

// > 1000 ms later:
//res.state = 'fulfilled'
//res.value = 1000

And as with Immutable Resolution Objects, Mutable Resolution Objects can be initialized in a specific state

• Resolution.Mutable.resolve( value )

• Resolution.Mutable.reject( value )

• Resolution.Mutable.pending( value )

  • value - Any - The value associated with this Resolution_ Object

Mutable Instance Methods

Back to Top

A Mutable Resolution Object also contains then and catch (described here)

Note that then and catch are invoked immediately based on the state of the Resolution Object as that instant.

If the state later changes, these will not be retroactively invoked.

To have callbacks be invoked upon a state change, use the on method (see below)

Mutable Resolution Objects contain the following additional methods:

• resolve( value )

  • To resolve this Resolution with the given value

• reject( value )

  • To reject this Resolution with the given value

• reset( value )

  • To reset this Resolution to pending with the given value

If no value is provided, then the current value of this Resolution will not change

var res = Resolution.Mutable.resolve( 100 );
//res.state = 'fulfilled'
//res.value = 100

res.reject( 0 );
//res.state = 'rejected'
//res.value = 0

res.reset( 50 );
//res.state = 'pending'
//res.value = 50

res.resolve();
//res.state = 'fulfilled'
//res.value = 50

Callbacks can also be connected to the state of the Mutable Resolution Object

• on( which, fn[, once ])

* `which` - _String_   - Name of the state change function to connect the callback `fn` to
  *  Either `'resolve'`, `'reject'`, or `'reset'`

* `fn`    - _Function_ - The Callback Function to run whenever the desired state change function is called
  * Input argument is the **value** of this **Resolution**

* `once`  - _Boolean_  - Whether the `fn` should only be called one time

Examples

var res = Resolution.Mutable.pending( 100 );

res.on('resolve', function( data ){
  console.log('Always : ' + data)
})

res.on('resolve', function( data ){
  console.log('Once : ' + data)
}, true)

res.resolve(100);
//Always : 100
//Once : 100

res.resolve(50);
//Always : 50

Class Methods

Back to Top

Just like Promises, the Resolution Class has some methods to handle arrays (or other iterable objects) of Resolution Objects

• all( iterable )

  • iterable - iterable - Object to iterate through

Returns a new Resolution Object that is:

• rejected if no iterable object was provided
  • value will be an Error
• resolved if there are no pending or rejected Resolution Objects in the iterable
  • value will be array of consisting of all values (or Resolution Object values) in the array
• rejected if there are any rejected Resolution Objects in the iterable
  • value will be the value of the first rejected Resolution in the iterable
• pending if there are any pending Resolution Objects in the iterable
  • value will be undefined

Examples

var res = Resolution.all()
//res.state = 'rejected'
//res.value = Error

var res = Resolution.all([])
//res.state = 'fulfilled'
//res.value = []

var res = Resolution.all([Resolution.resolve(100),50])
//res.state = 'fulfilled'
//res.value = [100,50]

var res = Resolution.all([Resolution.resolve(100),Resolution.reject(0)])
//res.state = 'rejected'
//res.value = 0

var res = Resolution.all([Resolution.resolve(100),Resolution.pending(50)])
//res.state = 'pending'
//res.value = undefined

• race( iterable )

  • iterable - iterable - Object to iterate through

Returns a new Resolution Object that is:

• rejected with an Error if no iterable object was provided
• resolved if the first element in the iterable that is not a pending Resolution Object in the iterable is also not a rejected Resolution Object
  • value is the value of that element
• rejected if the first element in the iterable that is not a pending Resolution Object in the iterable is a rejected Resolution Object
  • value is the value of that rejected Resolution Object
• pending with undefined if the iterable is empty or every element in the iterable is a pending Resolution Object

Examples

var res = Resolution.race()
//res.state = 'rejected'
//res.value = Error

var res = Resolution.race([])
//res.state = 'pending'
//res.value = undefined

var res = Resolution.race([Resolution.pending(50)])
//res.state = 'pending'
//res.value = undefined

var res = Resolution.race([Resolution.resolve(100),50])
//res.state = 'fulfilled'
//res.value = 100

var res = Resolution.race([50,Resolution.resolve(100)])
//res.state = 'fulfilled'
//res.value = 50

var res = Resolution.race([Resolution.resolve(100),Resolution.reject(0)])
//res.state = 'fulfilled'
//res.value = 100

var res = Resolution.race([Resolution.reject(0),Resolution.resolve(100)])
//res.state = 'rejected'
//res.value = 0

var res = Resolution.race([Resolution.pending(50),Resolution.resolve(100)])
//res.state = 'fulfilled'
//res.value = 100

License

MIT