npm:@brainsights/promise-task

README

Lazy promises with progress and cancelation.

Installation

npm install promise-task

Usage

Use a task anywhere you would use a promise, with a few minor changes.

const Task = require("promise-task");

let task = new Task((context) => {
    let progress = 0;
    let timer;
    timer = setInterval(() => {
        progress += 1;
        if(progress >= 100) {
            clearTimeout(timer);
            context.progress(100);
            context.resolve(true);
        } else {
            context.progress(progress);
        }
    }, 100);

    context.onCancel = () => {
        clearTimeout(timer);
    };
});

task.on("progress", (progress) => console.log(progress));
await task.run();

Task#constructor

Create a new task by new Task(executor).

executor (Function) accepts a single argument, context.

Task#run()

Invoke this to begin executing the task. Returns a Promise that is resolved or rejected when the task completes.

Task#progress()

Returns the current progress as number.

Task#cancel()

Cancels execution and rejects the associated promise.

Task#isCanceled()

Returns true if the task is canceled, false otherwise.

Task#clone()

Creates a copy of a task instance.

Task#series(tasks)

Returns a new Task that wraps one or more tasks that are executed one-at-a-time.

tasks (Array): A list of tasks to execute in series when run() is invoked.

Task.error

Task property that contains the last Error if there is one, or null.

Context#resolve(result)

Invoke this from the executor to resolve the associated promise.

result (Any): The successful result of the completed task.

Context#reject(error)

Invoke this from the exectutor to reject the associated promise.

error (Error): An error explaining why the task failed.

Context#progress(value)

Invoke this from the executor to update the task progress.

value: A number between 0 and 100 (inclusive).

Context.onCancel(callback)

Set this property to the callback that should be invoked if the task is canceled. This property is only writable, and cannot be read.

callback (Function): A callback function invoked when Task.cancel() is called.

Usage no npm install needed!