promist

promist

A dependable promises and async utility belt.

Install

npm install promist

Documentation

• Classes: a set of promise classes.
  • ExtensiblePromise: a safe to extend promise class.
  • CancellablePromise: a cancellable promise.
    • cancel
  • DeferredPromise: an externally actionable promise.
    • resolve
    • reject
  • LazyPromise: a promise that will not execute until awaited.
    • static from
    • consume
    • operate
  • SyncPromise: a promise with values synchronously available and operable.
    • static from
• Creation: a set of promise returning conveniency functions.
  • wait: waits for a set time.
  • until: resolves once a test function returns true.
  • timeout: cancels a promise after a set time.
• Iterables: a set of functions to deal with iterables of promises.
  • Series: executes operations' callbacks in series.
    • map
    • filter
    • reduce
    • each
  • Parallel: executes operations' callbacks in parallel.
    • map
    • filter
    • reduce
    • each
• Utils: a set of utility functions.
  • control: for async flow control via generators.
  • isPromise: a type guard for promises.
  • isPromiseLike: a type guard for thenable objects.

Utils

control(test: Function, generator: Function): Function

Used to control async flow. It returns a promise returning function taking the same arguments as generator.

• test: a test function (can be async) that will be run before calling each next() on generator, with signature () => Promise<boolean | Error> | boolean | Error. It can return:
  • false: generator will not continue execution (it will never resolve).
  • true: generator will continue execution until the next yield.
  • Error: generator call will return a rejected promise. The same behavior can be expected if the error is thrown instead of returned.
• generator: must be a generator function. Within it, you'd use yield as you would await for an async function.

import { control } from 'promist';

function* gen(n) {
  // You can use yield as you'd use await
  let res = yield Promise.resolve(n * 2);
  // test() will be called here,
  // if it returns falsy or throws an error this next line won't execute
  res = yield Promise.resolve(res * 5);

  return res;
}

const willContinue = control(() => true, gen);
const willNotContinue = control(() => false, gen);
const willReject = control(() => Error('An error ocurred'), gen);

willContinue(1).then(console.log); // 10
willNotContinue(2).then(console.log); // Will not resolve
willReject(3).then(console.log).catch(console.error); // Error: An error occurred

isPromise(value: any): boolean

Returns true if value is a thenable and catchable, false otherwise.

• value: object to test.

import { isPromise } from 'promist';

if (isPromise(promise)) {
  promise.then(() => { /* ... */ }).catch(() => { /* ... */ });
}

isPromiseLike(value: any): boolean

Returns true if value is a thenable, false otherwise.

• value: object to test.

import { isPromiseLike } from 'promist';

if (isPromiseLike(promise)) {
  promise.then(() => { /* ... */ });
}

Changelog

5.0.0 (2021-12-13)

chore

• reboot package development (0a3d779)

Features

• classes: add CancellablePromise (1aa340e)
• classes: add DeferredPromise (c24ad6b)
• classes: add ExtensiblePromise (0166da2)
• classes: add LazyPromise (d9b5984)
• classes: add SyncPromise (e34ca8d)
• collection: add Parallel (2ed3bdf)
• collection: add Series methods (87ca458)
• creation: add timeout (17d3edb)
• creation: add until (8cc3dd2)
• creation: add wait (67b9da7)
• utils: add control and type guards utils (ec0cff2)

BREAKING CHANGES

• Promist has been almost entirely rewritten and its api redesigned. Please check the latest documentation.