q-combinators
v1.0.0
Published
Functions to combine q promises, capturing lots of useful, real world patterns.
Downloads
18
Maintainers
Readme
q-combinators
Functions to combine q promises, capturing lots of useful, real world patterns used across Beamly's node.js services.
Installing
npm install q-combinators --save
API
.setPromiseImpl
All API methods below accept Q promises or any Promise/A+ implementation (e.g. bluebird or Native Promises). For backwards comptability q-combinators will use the 'Q' library internally and return Q promises by default. However if your project uses another promise implementation you can pass it to setPromiseImpl() to change this behaviour.
// use native promises
qCombinators.setPromiseImpl(global.Promise);
// use bluebird promises
qCombinators.setPromiseImpl(require('bluebird'));
.object.all
Resolves an object of promises with an object of the resultant values if all promises resolve. If any promise rejects, it rejects with the same reason
// happy path
qCombinators.object.all({
x: Q('foo'),
y: Q('bar'),
z: Q('quux')
})
.then(function(object){
// object is:
// {
// x: 'foo',
// y: 'bar',
// z: 'quux'
// }
});
// sad path
qCombinators.object.all({
x: Q.reject('foo'),
y: Q(),
z: Q()
})
.then(null, function(err){
// err is 'foo'
});
.object.allSettled
Resolves an object of promises with all results, using the same format as Q.allSettled
qCombinators.object.allSettled({
x: Q.reject('foo'),
y: Q('bar'),
z: Q('quux')
})
.then(function(object){
// object is:
// {
// x: { state: 'rejected', reason: 'foo' },
// y: { state: 'fulfilled', value: 'bar' },
// z: { state: 'fulfilled', value: 'quux' }
// }
});
.object.fulfilled
Resolves an object of promises with only the fulfilled values. If none of the promises fulfill, it fulfills with an empty object.
qCombinators.object.fulfilled({
x: Q.reject('foo'),
y: Q('bar'),
z: Q('quux')
})
.then(function(object){
// object is:
// {
// y: 'bar',
// z: 'quux'
// }
});
.object.rejected
Resolves an object of promises with only the rejected values. If none of the promises are rejected, it fulfills with an empty object.
qCombinators.object.rejected({
x: Q.reject('foo'),
y: Q('bar'),
z: Q('quux')
})
.then(function(object){
// object is:
// {
// x: 'foo'
// }
});
.object.demand
Resolves an object of promises when the 'demanded' keys contain successful promises.
If a demanded promise fails, the returned promise will also fail.
// happy path
qCombinators.object.demand({
x: Q('foo'),
y: Q.reject('bar'),
z: Q('quux')
})
.then(function(object){
// object is:
// {
// x: 'foo',
// z: 'quux'
// }
});
// sad path
demand(['x', 'y'], {
x: Q.reject('foo'),
y: Q('bar'),
z: Q('quux')
})
.fail(function(errs){
// errs is:
// {
// x: 'foo'
// }
});
.array.fulfilled
Resolves an array of promises with only the fulfilled values. If none of the promises are fulfilled, it fulfills with an empty array.
qCombinators.array.fulfilled([
Q.reject('foo'),
Q('bar'),
Q('quux')
])
.then(function(value){
// value is: ['bar', 'quux']
});
.array.rejected
Resolves an array of promises with only the rejected values. If none of the promises are rejected, it fulfills with an empty array.
qCombinators.array.rejected([
Q.reject('foo'),
Q.reject('bar'),
Q('quux')
])
.then(function(value){
// value is: ['foo', 'bar']
});
.chain
Sequentially executes an array of promise-returning functions. The equivalent of a lot of .then
chains:
var inc = function(a){ return a + 1 };
var promise1 = function(){ return Q(1) };
qCombinators.chain([promise1, inc, inc, inc])
.then(function(val){
// val === 4
});
.compose
Composes promise-producing functions into a single promise-producing function. Composes conventionally, from right to left.
In case of failure, returns the first failing promise in order of execution.
var incP = function(a){ return Q(a + 1) };
var doubleP = function(a){ return Q(a * 2) };
var doubleThenAddTwo = qCombinators.compose(inc, inc, double);
doubleThenAddTwo(5)
.then(function(val){
// val === 12
});
.fallback
Sequentially executes an array of functions which return promises, until the first promise is resolved. If all promises are rejected it itself is rejected with an array of all the failure reasons.
// happy path
qCombinators.fallback([
function() { return Q.reject('foo'); },
function() { return Q('bar'); },
function() { return Q.reject('baz'); }
])
.then(function(result){
// result is 'bar'
});
// sad path
qCombinators.fallback([
function() { return Q.reject('foo'); },
function() { return Q.reject('bar'); },
function() { return Q.reject('baz'); }
])
.fail(function(results) {
// results is:
// [
// 'foo',
// 'bar',
// 'baz'
// ]
});
.fallbackParallel
Same as .fallback, but takes an array of promises, allowing fetching results in parallel, then accepting them in preferential order.
// happy path
qCombinators.fallbackParallel([
Q.reject('foo'),
Q('bar'),
Q.reject('baz')
])
.then(function(result){
// result is 'bar'
});
// sad path
qCombinators.fallbackParallel([
Q.reject('foo'),
Q.reject('bar'),
Q.reject('baz')
])
.fail(function(results) {
// results is:
// [
// 'foo',
// 'bar',
// 'baz'
// ]
});
Contributing
Contributions are currently not being accepted.
Licensing
This project is licensed under the BSD 3-Clause license.