Foretell

A small, performant Promise/A+ 1.1 implementation in Typescript.

Installation and Usage

ES6 via NPM

npm install foretell

import Foretell from "foretell";

const delay = ms => new Foretell(resolve => setTimeout(resolve, ms));

delay(100).then(() => {
  // do something
});

UMD via NPM

const Foretell = require("foretell");

Polyfill for browser

<script src="./dist/umd/foretell.polyfill.js"></script>

Goals

• Provide a small, but fast Promises library for polyfilling personal projects.

Documentation

Foretell is a Promise/A+ 1.1 compliant library, and implements .then as well as a few additional utilities to have parity with browser implementations.

new Foretell<T>(func?: (resolve: (arg?: T) => void, reject: (reason: any) => void) => void)

Constructor for Foretell. Foretell does not implement the Deferred pattern.

const promise = new Foretell((resolve, reject) => {
  // resolve or reject here
});

.then<TResult = T, TReject = never>(onfulfilled?: ((value: T) => TResult | PromiseLike<TResult>) | undefined | null, onrejected?: ((reason: any) => TReject | PromiseLike<TReject>) | undefined | null ): PromiseLike<TResult | TReject>

Runs callbacks when a Promise resolves or rejects. Returns a new Promise, allowing .then to be chained. Accepts a callback for resolved Promises, and a callback for rejected Promises.

const delay = ms => new Foretell(resolve => setTimeout(resolve, ms));

delay(100)
  .then(() => {
    return 6;
  })
  .then(value => {
    // do something with the value
  });

.catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): PromiseLike<T | TResult>;

Runs a callback on a Promise rejection, and returns a new Promise. Sugar function for .then(null, errorHandler).

const delay = ms => new Foretell(resolve => setTimeout(resolve, ms));

delay(100)
  .then(() => {
    return Foretell.reject(new Error("Something bad"));
  })
  .catch(error => {
    // handle error
  });

finally(onfinally?: (() => any) | undefined | null): PromiseLike<T>;

Runs a callback regardless of whether the Promise has resolved or rejected. Sugar function for .then(sameHandler, sameHandler).

const delay = ms => new Foretell(resolve => setTimeout(resolve, ms));

delay(100)
  .then(() => {
    return Foretell.reject(new Error("Something bad"));
  })
  .catch(error => {
    // handle error
  })
  .finally(() => {
    // Do something after then/catch
  });

Foretell.resolve<U>(arg?: U): PromiseLike<U>

Provides an immediately resolved Promise.

const promise = Foretell.resolve(42);

promise.then(value => console.log(`value ${value} is immediately resolved`));

Foretell.reject<U = never>(error?: U): PromiseLike<U>;

Provides an immediately rejected Promise.

const promise = Foretell.reject(42);

promise.catch(value => console.log(`value ${value} is immediately rejected`));

Foretell.all(promises: PromiseLike<any>[]): PromiseLike<any[]>;

Resolves after all promises/values in the input array are resolved. Rejects immediately on the first promise to be rejected.

Accepts arrays as input, does not accept iterables for the sake of small code size. Use Array.from if you need to convert iterables into arrays.

const delay = (ms, value) =>
  new Foretell(resolve => setTimeout(resolve, ms, value));

const promises = [Foretell.resolve(2), delay(100, "5"), "something"];

Foretell.all(promises).then(values => {
  // passes all resolved values as an array
});

Foretell.race(promises: PromiseLike<any>[]): PromiseLike<any>;

Resolves on the first promise/value to resolve in the input array. Also rejects immediately on the first promise to be rejected.

Accepts arrays as input, does not accept iterables for the sake of small code size. Use Array.from if you need to convert iterables into arrays.

const delay = (ms, value) =>
  new Foretell(resolve => setTimeout(resolve, ms, value));

const promises = [delay(100, 1), delay(50, 2), delay(300, 3)];

Foretell.race(promises).then(value => {
  // returns first value to resolve, in this example, value is 2
});

Benchmarks

Tested against Native Promises, Zousan, and Bluebird, with the test machine being Ryzen 1700 @ 3.8Ghz with 32GB 3066 RAM. Test cases are in the benchmarks folder. Both serial and parallel tests include mixing of deferred and immediate return values.

Node.js v14.4.0

Library	Create & Resolve (ops/sec)	Serial (ops/sec)	Parallel (ops/sec)
Native	2,897,719 ±0.38%	21,952 ±0.45%	76,078 ±0.34%
Foretell	1,783,529 ±0.19%	15,116 ±0.30%	82,167 ±0.16%
Zousan	1,487,790 ±0.37%	10,591 ±0.81%	40,340 ±0.43%
Bluebird	291,128 ±0.26%	9,511 ±0.61%	78,763 ±0.84%

Chrome 83.0.4103.106

Library	Create & Resolve (ops/sec)	Serial (ops/sec)	Parallel (ops/sec)
Native	454,074 ±0.65%	22,229 ±0.52%	72,444 ±1.78%
Foretell	230,428 ±0.34%	14,817 ±0.21%	83,596 ±0.20%
Zousan	74,584 ±1.88%	11,072 ±0.52%	45,776 ±0.95%
Bluebird	4,804 ±0.79%	95.97 ±0.25%	442 ±3.22%

Firefox v68.0.2 (no queueMicrotask)

Library	Create & Resolve (ops/sec)	Serial (ops/sec)	Parallel (ops/sec)
Native	164,723 ±1.59%	567 ±2.32%	3,036 ±1.85%
Foretell	216,060 ±0.46%	4,383 ±2.10%	24,936 ±1.64%
Zousan	186,790 ±0.50%	1,913 ±2.17%	6,807 ±1.90%
Bluebird	19,817 ±1.69%	110 ±1.64%	399 ±1.92%

Firefox v77.0.1 (with queueMicrotask)

Library	Create & Resolve (ops/sec)	Serial (ops/sec)	Parallel (ops/sec)
Native	248,655 ±2.63%	757 ±0.95%	3,966 ±1.32%
Foretell	452,917 ±2.08%	4,900 ±2.62%	27,667 ±4.55%
Zousan	285,515 ±2.66%	2,964 ±1.80%	11,085 ±1.59%
Bluebird	22,959 ±1.18%	115 ±1.75%	483 ±1.23%

Licensing

Foretell is MIT licensed.