@util.js/promises

JavaScript utility methods for promises

@util.js/promises is part of Util.js.

This class contains all the non-instance methods of Promise in addition to:

• applyCallback
• applyPromise
• callbackify
• callCallback
• callPromise
• promisify

Promises#all and Promises#race behave a little differently from Promise#all and Promise#race. Unlike Promise#all and Promise#race, Promises#all and Promises#race can take multiple arguments.

Promises API

Kind: global class
Access: public

• Promises
  • .all(iterable) ⇒ Promise
  • .applyCallback(object, functionOnObjectWithCallback, args) ⇒ undefined | Promise
  • .applyPromise(object, promiseFunctionOnObject, args) ⇒ undefined | Promise
  • .callbackify(promiseFunction) ⇒ function
  • .callCallback(object, functionOnObjectWithCallback, [...args]) ⇒ undefined | Promise
  • .callPromise(object, promiseFunctionOnObject, [...args]) ⇒ undefined | Promise
  • .promisify(functionWithCallback) ⇒ function
  • .race(iterable) ⇒ Promise
  • .reject(reason) ⇒ Promise
  • .resolve(value) ⇒ Promise

promises.all(iterable) ⇒ Promise

Returns a single Promise that resolves when all of the promises in the iterable argument have resolved or when the iterable argument contains no promises.

It rejects with the reason of the first promise that rejects.

See MDN's documentation about all.

There is one minor difference between Promise#all and this method. Promise#all only takes one argument that must be iterable. This method, Promises#all, behaves the same as Promise#all when given one argument; when given multiple arguments, arguments becomes the iterable.

Kind: instance method of Promises
Returns: Promise - (A) An already resolved Promise if the iterable passed is empty. (B) An asynchronously resolved Promise if the iterable passed contains no promises. (C) A pending Promise in all other cases; this returned promise is then resolved/rejected asynchronously (as soon as the stack is empty) when all the promises in the given iterable have resolved, or if any of the promises reject; returned values will be in order of the Promises passed, regardless of completion order.
Access: public

| Param | Type | Description | | -------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | iterable | iterable | * | An iterable object such as an Array or String; if you give move than one argument to this method, arguments becomes the iterable |

Example

const promises = require("@util.js/promises");
const promise1 = Promise.resolve(3);
const promise2 = 42;
const promise3 = new Promise((resolve, reject) => {
  setTimeout(resolve, 100, "foo");
});
promises.all(promise1, promise2, promise3).then((values) => {
  console.log(values);
});
// expected output: Array [3, 42, "foo"]

promises.applyCallback(object, functionOnObjectWithCallback, args) ⇒ undefined | Promise

Calls the given functionOnObjectWithCallback with the given args that either (A) returns a Promise if args does not contain a callback or (B) notifies the callback if args contains a callback.

Use this function if you are wrapping an existing function that only takes a callback but would like that function to handle both callbacks and Promises.

It is also useful in writing new functions where you would like to support both callbacks and Promises.

This function adapts functions that accept a callback. applyPromise adapts functions that return a Promise.

This function is similar to Function#apply. It accepts a single array of arguments.

Function#call and callCallback accept an argument list.

When trying to remember the difference between #apply and #call, think, "#apply accepts an array. Both array and #apply start with a."

Kind: instance method of Promises
Returns: undefined | Promise - undefined if the last element of args is a callback or a Promise if args does not contain a callback
Throws:

• TypeError If functionOnObjectWithCallback is not a function or if args is null or undefined

Access: public

| Param | Type | Description | | ---------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | object | Object | Value to use as this when executing functionOnObjectWithCallback (can be null) | | functionOnObjectWithCallback | function | A function that takes a callback as its last argument | | args | | An array-like object containing the arguments to pass to functionOnObjectWithCallback; this is usually just arguments |

Example

// Wrap a function that only accepts a callback.
const promises = require("@util.js/promises");
const stream = require("stream");
const streams = require("@util.js/node-streams");
// stream#finished only takes a callback.
// Wrap stream#finished so that it handles both callbacks and Promises.
function finished() {
  return promises.applyCallback(stream, stream.finished, arguments);
}
const readableToCallback = streams.fromString("Call back, Hypnotoad!");
finished(readableToCallback, () => console.log("Finished with a callback"));
const readableToPromise = streams.fromString("Promise me, Hypnotoad!");
finished(readableToPromise).then(() => console.log("Finished as promised"));

Example

// Write a function that supports both callbacks and Promises.
const promises = require("@util.js/promises");
function notify(message, who, callback) {
  if (!callback) return promises.applyCallback(null, notify, arguments);
  callback(null, `${message}, ${who}!`);
}
notify("Call back", "Hypnotoad", (error, message) => console.log(message));
notify("Promise me", "Hypnotoad").then(console.log);

promises.applyPromise(object, promiseFunctionOnObject, args) ⇒ undefined | Promise

Calls the given promiseFunctionOnObject with the given args that either (A) returns a Promise if args does not contain a callback or (B) notifies the callback if args contains a callback.

Use this function if you are wrapping an existing function that only returns a Promise but would like that function to handle both callbacks and Promises.

It is also useful in writing new functions where you would like to support both callbacks and Promises.

This function adapts functions that return a Promise. applyCallback adapts functions that accept a callback.

This function is similar to Function#apply. It accepts a single array of arguments.

Function#call and callPromise accept an argument list.

When trying to remember the difference between #apply and #call, think, "#apply accepts an array. Both array and #apply start with a."

Kind: instance method of Promises
Returns: undefined | Promise - undefined if the last element of args is a callback or a Promise if args does not contain a callback
Throws:

• TypeError If promiseFunctionOnObject is not a function or if args is null or undefined

Access: public

| Param | Type | Description | | ----------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | object | Object | Value to use as this when executing promiseFunctionOnObject (can be null) | | promiseFunctionOnObject | function | A function that returns a Promise | | args | | An array-like object containing the arguments to pass to promiseFunctionOnObject; this is usually just arguments |

Example

// Wrap a function that only returns a Promise.
const promises = require("@util.js/promises");
function notifyPromise(message, who) {
  return promises.resolve(`${message}, ${who}!`);
}
// #notifyPromise only returns a Promise.
// Wrap #notifyPromise so that it handles both callbacks and Promises.
function notify(message, who, callback) {
  return promises.applyPromise(null, notifyPromise, arguments);
}
notify("Call back", "Hypnotoad", (error, message) => console.log(message));
notify("Promise me", "Hypnotoad").then(console.log);

Example

// Write a function that supports both callbacks and Promises.
const promises = require("@util.js/promises");
function notify(message, who, callback) {
  if (callback) return promises.applyPromise(null, notify, arguments);
  return promises.resolve(`${message}, ${who}!`);
}
notify("Call back", "Hypnotoad", (error, message) => console.log(message));
notify("Promise me", "Hypnotoad").then(console.log);

promises.callbackify(promiseFunction) ⇒ function

Wraps the given promiseFunction such that calling the returned function with a callback notifies the callback with an error if promiseFunction rejects or the return value if promiseFunction resolves.

Use callPromise if you would like to callbackify a method and call it in one line.

Kind: instance method of Promises
Returns: function - A function that accepts a callback
Throws:

• TypeError If promiseFunction is not a function

Access: public

| Param | Type | Description | | --------------- | --------------------- | --------------------------------- | | promiseFunction | function | A function that returns a Promise |

Example

const promises = require("@util.js/promises");
function notifyPromise(message, who) {
  return promises.resolve(`${message}, ${who}!`);
}
// #notifyPromise only returns a Promise.
// Wrap #notifyPromise so that it accepts a callback.
const notify = promises.callbackify(notifyPromise);
notify("Call back", "Hypnotoad", (error, message) => console.log(message));

promises.callCallback(object, functionOnObjectWithCallback, [...args]) ⇒ undefined | Promise

Calls the given functionOnObjectWithCallback with the given args that either (A) returns a Promise if args does not contain a callback or (B) notifies the callback if args contains a callback.

This method just calls:

See applyCallback.

Kind: instance method of Promises
Returns: undefined | Promise - undefined if the last element of args is a callback or a Promise if args does not contain a callback
Throws:

• TypeError If functionOnObjectWithCallback is not a function

Access: public

| Param | Type | Description | | ---------------------------- | --------------------- | -------------------------------------------------------------------------------- | | object | Object | Value to use as this when executing functionOnObjectWithCallback (can be null) | | functionOnObjectWithCallback | function | A function that takes a callback as its last argument | | [...args] | * | The arguments to pass to functionOnObjectWithCallback or its promisified version |

Example

const promises = require("@util.js/promises");
function notifyCallback(message, who, callback) {
  callback(null, `${message}, ${who}!`);
}
// #notifyCallback only accpets a callback.
// Force #notifyCallback to return a Promise.
promises
  .callCallback(null, notifyCallback, "Promise me", "Hypnotoad")
  .then(console.log);

promises.callPromise(object, promiseFunctionOnObject, [...args]) ⇒ undefined | Promise

Calls the given promiseFunctionOnObject with the given args that either (A) returns a Promise if args does not contain a callback or (B) notifies the callback if args contains a callback.

This method just calls:

See applyPromise.

Kind: instance method of Promises
Returns: undefined | Promise - undefined if the last element of args is a callback or a Promise if args does not contain a callback
Throws:

• TypeError If promiseFunctionOnObject is not a function

Access: public

| Param | Type | Description | | ----------------------- | --------------------- | ----------------------------------------------------------------------------- | | object | Object | Value to use as this when executing promiseFunctionOnObject (can be null) | | promiseFunctionOnObject | function | A function that returns a Promise | | [...args] | * | The arguments to pass to promiseFunctionOnObject or its callbackified version |

Example

const promises = require("@util.js/promises");
function notifyPromise(message, who) {
  return promises.resolve(`${message}, ${who}!`);
}
// #notifyPromise only returns a Promise.
// Force #notifyPromise to accept a callback.
promises.callPromise(
  null,
  notifyPromise,
  "Call back",
  "Hypnotoad",
  (error, message) => console.log(message)
);

promises.promisify(functionWithCallback) ⇒ function

Wraps the given functionWithCallback such that calling the returned function returns a Promise that resolves if functionWithCallback succeeds and rejects if functionWithCallback errors.

Use callCallback if you would like to promisify a method and call it in one line.

Kind: instance method of Promises
Returns: function - A function that returns a Promise
Throws:

• TypeError If functionWithCallback is not a function

Access: public

| Param | Type | Description | | -------------------- | --------------------- | ----------------------------------------------------- | | functionWithCallback | function | A function that takes a callback as its last argument |

Example

const promises = require("@util.js/promises");
const stream = require("stream");
const streams = require("@util.js/node-streams");
// stream#finished only takes a callback.
// Let us wrap stream#finished so that it returns a Promise.
const readable = streams.fromString("Promise me, Hypnotoad!");
const finished = promises.promisify(stream.finished);
finished(readable).then(() => console.log("Finished as promised"));

promises.race(iterable) ⇒ Promise

Returns a promise that resolves or rejects as soon as one of the promises in the iterable resolves or rejects, with the value or reason from that promise.

See MDN's documentation about race.

There is one minor difference between Promise#race and this method. Promise#race only takes one argument that must be iterable. This method, Promises#race, behaves the same as Promise#race when given one argument; when given multiple arguments, arguments becomes the iterable.

Kind: instance method of Promises
Returns: Promise - A pending Promise that resolves or rejects asynchronically (as soon as the stack is empty) as soon as one of the promises in the given iterable resolves or rejects, adopting that first promise's value as its value
Access: public

| Param | Type | Description | | -------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | iterable | iterable | * | An iterable object such as an Array or String; if you give move than one argument to this method, arguments becomes the iterable |

Example

const promises = require("@util.js/promises");
const promise1 = new Promise((resolve, reject) => {
  setTimeout(resolve, 500, "one");
});
const promise2 = new Promise((resolve, reject) => {
  setTimeout(resolve, 100, "two");
});
promises.race(promise1, promise2).then((value) => {
  console.log(value);
  // Both resolve, but promise2 is faster
});
// expected output: "two"

promises.reject(reason) ⇒ Promise

Returns a Promise object that is rejected with the given reason.

See MDN's documentation about reject.

Kind: instance method of Promises
Returns: Promise - A Promise that is rejected with the given reason
Access: public

| Param | Type | Description | | ------ | --------------- | -------------------------------- | | reason | * | Reason why this Promise rejected |

promises.resolve(value) ⇒ Promise

Returns a Promise object that is resolved with the given value.

If the value is a promise, that promise is returned; if the value is a thenable (i.e. has a "then" method), the returned promise will "follow" that thenable, adopting its eventual state; otherwise the returned promise will be fulfilled with the value.

See MDN's documentation about resolve.

Kind: instance method of Promises
Returns: Promise - A Promise that is resolved with the given value, or the promise passed as value, if the value was a promise object
Access: public

| Param | Type | Description | | ----- | --------------- | ------------------------------------------------------------------------------------------- | | value | * | Argument to be resolved by this Promise that can also be a Promise or a thenable to resolve |