@marcelkloubert/promises

Helpers for promises, which work in Node and the browser.

Install

Execute the following command from your project folder, where your package.json file is stored:

npm i @marcelkloubert/promises

Usage

doRepeat(action: DoRepeatAction, countOrCondition: number | DoRepeatCondition, ...args: any[]): Promise

Repeats an action or promise.

import assert from "assert";
import { doRepeat, DoRepeatActionContext } from "@marcelkloubert/promises";

const repeatCount = 5979;
const counter = 0;

const results = await doRepeat(async (context: DoRepeatActionContext) => {
  console.log("context.state", String(context.state));
  context.state = context.index * 2;

  ++counter;

  // do some work here
}, repeatCount);

assert.strictEqual(results.length, repeatCount);
assert.strictEqual(counter, results.length);

isPromise(value: any): boolean

Checks if a value is a Promise.

import { isPromise } from "@marcelkloubert/promises";
import Bluebird from "bluebird";

// all are (true)
isPromise(Promise.resolve("Foo"));
isPromise(Bluebird.resolve("Foo"));
isPromise({
  then: (onfulfilled?: Function, onrejected?: Function): any => {},
  catch: (onrejected?: Function) => {},
});

// all are (false)
isPromise("Foo");
isPromise({
  then: (onfulfilled?: Function, onrejected?: Function): any => {},
});
isPromise(null);

isPromiseLike(value: any): boolean

Checks if a value is a PromiseLike.

import { isPromiseLike } from "@marcelkloubert/promises";
import Bluebird from "bluebird";

// all are (true)
isPromiseLike(Promise.resolve("Foo"));
isPromiseLike(Bluebird.resolve("Foo"));
isPromiseLike({
  then: (onfulfilled?: Function, onrejected?: Function): any => {},
});

// all are (false)
isPromiseLike("Foo");
isPromiseLike({});
isPromiseLike(null);

PromiseQueue

A promise queue.

import assert from "assert";
import { PromiseQueue } from "@marcelkloubert/promises";

// create and start the queue
const queue = new PromiseQueue({
  autoStart: true,
  concurrency: 10, // maximum 10 actions at the same time
});

const promises: Promise<any>[] = [];
let counter = 0;

// lets create 100 actions and
// add them to queue
const actionCount = 100;
for (let i = 0; i < actionCount; i++) {
  promises.push(
    queue.enqueue(async () => {
      // do some (long) work here ...

      ++counter;
    })
  );
}

// wait until all actions have been executed
await Promise.all(promises);

// stop the queue
queue.stop();

// counter should now be the number of
// enqueued actions
assert.strictEqual(counter, promises.length);

waitFor(action: WaitForAction, condition: WaitForCondition, ...args: any[]): Promise

Invokes an action or promise, but waits for a condition.

import {
  waitFor,
  WaitForActionContext,
  WaitForCondition,
} from "@marcelkloubert/promises";
import fs from "fs";

const waitForFile: WaitForCondition = async (context) => {
  // use context.cancel() function
  // to cancel the operation
  // maybe for a timeout

  // setup 'state' value for upcoming
  // action
  context.state = "Foo Bar BUZZ"; // (s. below in action)

  // return a truthy value to keep waiting
  // otherwise falsy to start execution of action
  return !fs.existsSync("/path/to/my/file.xlsx");
};

const result = await waitFor(async ({ state }: WaitForActionContext) => {
  // state === "Foo Bar BUZZ" (s. above)
}, waitForFile);

withCancellation(action: WithCancellationAction, ...args: any[]): Promise

Invokes an action or promise, which can be cancelled.

import {
  CancellationError,
  withCancellation,
  WithCancellationActionContext,
} from "@marcelkloubert/promises";

const promise = withCancellation(
  async (context: WithCancellationActionContext) => {
    let hasBeenFinished = false;
    while (!context.cancellationRequested && !hasBeenFinished) {
      // do some long work here
    }
  }
);

setTimeout(() => {
  promise.cancel("Promise action takes too long");
}, 10000);

try {
  await promise;
} catch (ex) {
  if (ex instanceof CancellationError) {
    // has been cancelled
  } else {
    // other error
  }
}

withRetries(action: WithRetriesAction, optionsOrMaxRetries: WithRetriesOptions | number, ...args: any[]): Promise

Invokes an action or promise and throws an error if a maximum number of tries has been reached.

import {
  MaximumTriesReachedError,
  withRetries,
} from "@marcelkloubert/promises";

const myAsyncAction = async () => {
  // do something here
};

try {
  // try this action
  await withTimeout(myAsyncAction, {
    maxRetries: 9, // try invoke the myLongAction
    // with a maximum of 10 times
    // (first invocation + maxRetries)
    waitBeforeRetry: 10000, // wait 10 seconds, before retry
  });
} catch (error) {
  // error should be a MaximumTriesReachedError instance
  console.error("Invokation of myLongAction failed", error);
}

withTimeout(action: WithTimeoutAction, timeout: number, ...args: any[]): Promise

Invokes an action or promise and throws an error on a timeout.

import { TimeoutError, withTimeout } from "@marcelkloubert/promises";

const action = () => {
  return new Promise<string>((resolve) => {
    setTimeout(() => result("FOO"), 1000);
  });
};

// submit action as function
// should NOT throw a TimeoutError
const fooResult1 = await withTimeout(action, 10000);

// submit action as Promise
// this should throw a TimeoutError
const fooResult2 = await withTimeout(action(), 100);

withWorker(workerFileOrUrl: string | URL, options?: WithWorkerOptions): Promise

Wraps the execution of a worker into a Promise.

import { withWorker } from "@marcelkloubert/promises";

// this is code for Node.js
// in a browser 'exitCode' will not exist
const { exitCode, lastMessage } = await withWorker("/path/to/worker_script.js");

Documentation

The API documentation can be found here.

License

MIT © Marcel Joachim Kloubert

Support

Or visit https://marcel.coffee/