Promise based micro-library with functional methods.
Promise based micro-library that extends v8 native promises with functional and helper methods. This library has zero dependencies, which makes it perfect for embedding in simple scripts. If you are using this in larger projects, you may want to take a look at Bluebird.
Additional examples are available in tests.
Convert a method that takes a callback into one that returns a promise.
const fs = require("fs");
const P = require("extends-promise");
const readfile = P.promisify(fs.readfile);
readfile("./some-file.txt").then(console.log);Helper method to promisify all methods on an object.
const o = P.promisifyAll({
add : (x, y, cb) => cb(null, x + y),
addOne : (x, cb) => cb(null, x + 1)
});
o.addAsync(1, 2).then(console.log);
o.addOneAsync(2).then(console.log);Optionally, you can choose a suffix to append instead of "Async". Choosing an empty string will overwrite the original method. You may also provide a filter method that will filter the methods on the object that will be promisified. This can be useful if some of the methods are synchronous and should not be promisified.
// Defaults
{
suffix : "Async",
filter : (name, method, obj) => true
}Similar to a synchronous try {} block but, for promises. The result of P.try will always be a promise even if the method returned or threw synchronously.
P
.try(() => {
const r = Math.floor(Math.random() * 5);
switch (r) {
case 0: return 0;
case 1: return P.resolve(1);
default: throw new Error("Something bad happened!");
}
})
.then(console.log)
.catch(console.error);Creates a method from the provided function that will always return a promise. Similar to P.try, but returns a method instead of invoking one. It will also accept arguments and maintain the this context.
const Calc = {
add : P.method(function add(x, y) {
return x + y;
})
};
Calc
.add(1, 2)
.then(console.log);Ad-hoc conversion from a callback to a promise. Also, useful for promisifying methods where the callback is not the last argument.
const P = require("extends-promise");
P
.fromCallback(cb => {
setTimeout(() => cb(null, "Hello, World!"), 1000);
})
.then(console.log);Creates a promise along with distinct resolve and reject methods. This is handy
if you need a promise placeholder or need to promisify something non-standard. In most
cases you are better off with new P((resolve, reject) => {}) or P.promisify. Beware of
the deferred anti-pattern.
const P = require("extends-promise");
const deferred = P.defer();
deferred.promise.then(console.log);
deferred.resolve("Hello, World!");const P = require("extends-promise");
const deferred = P.defer();
deferred.promise.catch(console.error);
deferred.reject(new Error("Goodbye, World!"));Accepts an object and waits for all promise values to resolve before returning. Returns a new object with values from the resolved promises.
const P = require("extends-promise");
P
.props({
x : P.delay(100, 'a'),
y : P.delay(50, 'b'),
z : 'c'
})
.then(res => console.log(res.x));This method can be especially helpful when combined with destructuring as a way of returning named tuples.
P
.props({
x : P.delay(100, 'a'),
y : 'b'
})
.then(({ x, y }) => console.log(`x: ${x}, y: ${y}`));Extend a promise implementation with methods in this library. Useful if you want to duck-type the built-in promise everywhere.
const P = require("extends-promise");
P.extend(Promise);
Promise
.resolve("Hello, World!")
.delay(1000)
.then(console.log);Enhanced version of Promise.prototype.catch that supports catching specific errors. An
optional predicate may be provided that is either a sub-class of Error or a method that
returns a truthy value if the error matches.
const P = require("extends-promise");
// Custom errors must inherit from `Error`
class CustomError extends Error {}
// Catch a custom error
P.reject(new CustomError())
.catch(CustomError, console.error);
// Catch with a predicate function
P.reject(Object.assign(new Error(), { code : 404 }))
.catch(err => err.code === 404, console.warn);
// Catch all errors
P.reject(new Error())
.catch(console.error);Short-hand for returning a value from a .then.
const P = require("extends-promise");
P.resolve()
.return("Hello, World!")
.then(console.log);
// Equivalent
P.resolve()
.then(() => "Hello, World!")
.then(console.log);Short-hand for invoking a method on the result of a promise.
const P = require("extends-promise");
P.resolve(10)
.call("toString", 16)
.then(res => res === "a");
// Equivalent
P.resolve(10)
.then(res => res.toString(16))
.then(res => res === "a");Delay the resolution of a promise by N milliseconds. NOTE: This does not delay exceptions.
const P = require("extends-promise");
P.resolve("Hello, World!")
.delay(1000)
.then(console.log);Like .then, except returns a promise for the original value. Useful for side effects like logging.
const P = require("extends-promise");
P.resolve(100)
.tap(console.log)
.then(res => res === 100);Similar to [].map but, waits for promises returned from the mapping function to resolve. By
default all methods will be run concurrently. You may also pass a concurrency option,
{ concurrency : 1 }.
const P = require("extends-promise");
P.resolve([1, 2, 3])
.map(res => P.resolve(res * 100))
// [100, 200, 300]
.then(console.log);const P = require("extends-promise");
P.resolve([1, 2, 3])
.map(res => P.delay(Math.random() * 100, res), {
concurrency : 3
})
// [1, 2, 3]
.then(console.log);Similar to [].filter but waits for promises returned from the filtering function to resolve. By
default all methods will be run concurrently. You may also pass a concurrency option,
{ concurrency : 1 }.
const P = require("extends-promise");
P.resolve([1, 2, 3, 4])
.filter(res => P.resolve(res % 2))
// [1, 3]
.then(console.log);const P = require("extends-promise");
P.resolve([1, 2, 3, 4])
.filter(res => P.delay(Math.random() * 100, res % 2), {
concurrency : 3
})
// [1, 3]
.then(console.log);Similar to [].reduce but, waits for each iteration to resolve before calling the next method. The callback method may return promises or values. The optional intialValue may also be a value, promise.
const P = require("extends-promise");
P.resolve([2, 3, 4])
.reduce((y, x) => y + x, 1)
.then(console.log);Similar to [].forEach but, accepts a method that returns a promise. Each iteration of the loop will run serially.
const P = require("extends-promise");
P.resolve([1, 2, 3])
.forEach(console.log);Converts a promise back into callback style async. Uses error first convention.
P.resolve(1)
.toCallback((err, res) => console.log(res));Each of the following instance methods are also available as static methods which accept a promise or value.
delay(ms, value)map(Array, Function)filter(Array, Function)reduce(Array, Function[, initialValue])forEach(Array, Function)
Contributions are welcome either as pull requests or feature requests. If you are opening a pull request, please ensure that your code passes tests and lint.
Also, zero dependencies is an explicit goal of this project to make it easy to include in any script. Pull requests containing additional dependencies (excluding devDependencies) will not be accepted.
Thanks!