extends-promise

extends-promise

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.

API

Additional examples are available in tests.

Static Helpers

promisify(Function fn, context)

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);

fromCallback(Function callback)

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);

defer(Function fn)

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!"));

extend(Promise)

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);

Instance Methods

return(value)

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);

call(String method, ...arguments)

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(Number milliseconds)

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);

tap(Function method)

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);

map(Function method[, options])

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);

filter(Function method[, options])

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);

reduce(Function method[, initialValue])

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);

forEach(Function method)

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);

toCallback(Function callback)

Converts a promise back into callback style async. Uses error first convention.

P.resolve(1)
	.toCallback((err, res) => console.log(res));

Instance Short-hand Statics

Each of the following instance methods are also available as static methods which accept a resolved value.

• delay(ms, value)
• map(Array, Function)
• filter(Array, Function)
• reduce(Array, Function[, initialValue])
• forEach(Array, Function)

Contributing

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!

License

MIT License