README

promise-helper

promise-helper is a simple toolbelt that aims to help with the more complex tasks of using promises. It supports operations like handling promises in sequence, sequences with sleeps, parallel execution or limited parallel execution, promises with timeout and cancelable promises.

It is released under the UNLICENSE & supports modern environments.

Installation

Using npm:

# global
$ npm i -g @abecodes/promise-helper

# dependency
$ npm i -S @abecodes/promise-helper

# dev dependecy
$ npm i -D @abecodes/promise-helper

In Node.js:

// Require the package.
const ph = require("@abecodes/promise-helper");

API

sequence

// Default
ph.sequence(taskArray: [() => Promise<any>], cb?: (err, result) => any) => Promise<any>

// Adding timeout between each task
ph.sequence.withSleep(taskArray: [() => Promise<any>], timeout: number,cb?: (err, result) => any) => Promise<any>

// Adding a random timeout inbetween a given range between each task
ph.sequence.withSleepRange(taskArray: [() => Promise<any>], minTime: number, maxTime: number, cb?: (err, result) => any) => Promise<any>

The sequence method takes an array of HOFs that return a promise an runs them in sequence. If sequence.withSleep or sequence.withSleepRange is called, the sequence will sleep after each task.

Sequence can be used as Promise or with a callback. If one task fails, the whole sequence will fail. In case of an error, all previous results will be accessable (if not falsy).

If used as promise, they will be passed in the error object as result property.

If used with a callback, they are passed as the result parameter.

// Example
const p = ph.sequence.withSleep(
    [
        () =>
            new Promise((resolve, reject) => {
                setTimeout(() => {
                    resolve("Hello");
                }, 200);
            }),
        () =>
            new Promise((resolve, reject) => {
                setTimeout(() => {
                    resolve("World");
                }, 200);
            }),
    ],
    2000
);
p.then(res => console.log(res)).catch(err => console.log(err, err.result));

parallel

// Default
ph.parallel(taskArray: [() => Promise<any>], cb?: (err, result) => any) => Promise<any>

// Triggering limited execution
ph.parallel.limited(taskArray: [() => Promise<any>], limit: number) => void

The parallel method takes an array of HOFs that return a promise an runs them in parallel.

If parallel.limited is called, only the given number of tasks will run in parallel.

Parallel can be used as Promise or with a callback. If one task fails, the whole sequence will fail.

Parallel.limited returns void, so each task must be handled by itself during initialization.

// Example
ph.parallel.limited(
    [
        () =>
            new Promise((resolve, reject) => {
                setTimeout(() => {
                    resolve("Hello");
                }, 200);
            }).then(res => console.log(res)),
        () =>
            new Promise((resolve, reject) => {
                setTimeout(() => {
                    resolve("World");
                }, 200);
            }).then(res => console.log(res)),
        () =>
            new Promise((resolve, reject) => {
                setTimeout(() => {
                    reject(new Error("oO"));
                }, 200);
            }).catch(res => console.log(res)),
        () =>
            new Promise((resolve, reject) => {
                setTimeout(() => {
                    resolve("working limited");
                }, 200);
            }).then(res => console.log(res)),
    ],
    2
);

timeout

// Default (throws timeout)
ph.timeout((executor: (resolve: (value?: any) => void, reject: (reason?: any)) => void) => void, timeout: number, onTimeout?: () => any) => Promise<any>

// Instead of throwing an error, withNull will resolve with null on timeout
ph.timeout.withNull((executor: (resolve: (value?: any) => void, reject: (reason?: any)) => void) => void, timeout: number, onTimeout?: () => any) => Promise<any>

The timeout method creates a promise that is bound to a timeout.

If the promise fails to respond in time, it will throw an error. If timeout.withNull is used, it will resolve with null instead of throwing.

Due to how promises work, the original promise will still execute, but if the operation offers a abort function, it can be triggered with the onTimeout callback.

// Example
const p = ph.timeout(
    (resolve, reject) => {
        req = https.get("https://www.google.de", res => resolve(res));
        req.on("error", err => reject(err));
        req.on("abort", () => reject());
    },
    20,
    () => req.abort()
);
p.then(res => console.log(res)).catch(err => console.log(err));

cancelable

// Invocation
const p = ph.cancelable((executor: (resolve: (value?: any) => void, reject: (reason?: any)) => void) => void) => Promise<any>

// cancel (throws canceled)
p.cancel(onCancel?: () => void)

// cancelWithNull resolves with null
p.cancelWithNull(onCancel?: () => void)

The cancelable method creates a promise that could be canceled at will.

If canceled, it will throw an error. If cancelable.cancelWithNull is used, it will resolve with null instead of throwing.

Due to how promises work, the original promise will still execute, but if the operation offers a abort function, it can be triggered with the onCancel callback.

// Example
let req;

const p = ph.cancelable((resolve, reject) => {
    req = https.get("https://www.google.de", res => resolve(res));
    req.on("error", err => reject(err));
    req.on("abort", () => reject());
});
p.then(res => console.log(res)).catch(err => console.log(err));

setTimeout(() => p.cancel(() => req.abort()), 20);

Greetings

May you enjoy using this piece of software as much as I enjoyed writing it. Stay bug free and have an awesome day <3

Usage no npm install needed!