Task

The purpose of this package is to deliver a simple but flexible method of handling asynchronous code cancellation. The implementation is a Task class which is an extension of the built-in ES6 Promise class. The Task class extends the Promise constructor to support an onAbort callback and adds an abort method to the class instance. Internally the Task uses an AbortController to manage cancellation and AbortSignal instances as cancellation tokens between Task instances.

Features

• Fully compatible with JavaScript's native async/await syntax.
• Uses an AbortController as a native cancellation token which enables fetch requests and certain DOM operations to be cancelled inside the task.
• Synchronise cancellation of child tasks by sharing the controller between task instances.

Installation

# NPM
npm install @harlem/task

# Yarn
yard add @harlem/task

# Pnpm
pnpm install @harlem/task

Usage

Basic

function createTask(message: string, timeout: number = 1000): Task<string> {
    // Create a new task the same way you create a promise
    return new Task((resolve, reject, controller, onAbort) => {
        const handle = window.setTimeout(() => resolve(message), 1000);

        /*
        Register an onAbort handler to instruct the task how to handle cancellation.
        This is also handy for cleaning up resources such as timer handles
        */
        onAbort(() => {
            window.clearTimeout(handle);
            reject();
        });
        
        /*
        The controller could be passed to any number of child tasks
        to synchronise the cancellation all the way through a chain
        of async operations.
        
        eg. new Task((resolve, reject, controller, onAbort) => {
            // Do some nested async operation
        }, controller);
        
        Note the second parameter to the Task constructor is an
        existing AbortController. Handy for passing controllers
        down to child tasks.
        */
    });
}

async function run(): Promise<void> {
    const task = createTask('hello');

    // Abort the task before it has a chance to complete
    window.setTimeout(() => task.abort(), 500);

    try {
        const result = await task;
        console.log(result);
    } catch {
        console.log('aborted');
    }
}

Cancel Fetch Requests

function getUserData(id: string): Task<object> {
    // Create a new task the same way you create a promise
    return new Task(async (resolve, reject, controller) => {
        try {
            /* 
            Pass the abort controller signal into the fetch api
            to cancel the request when the task is aborted
            */
            const response = await window.fetch(`/api/users/${id}`, {
                signal: controller.signal
            });

            const data = await response.json();
            resolve(data);
        } catch (error) {
            reject(error)
        }
    });
}

async function run(): Promise<void> {
    const task = getUserData('some-id');

    // Abort the task before it has a chance to complete
    window.setTimeout(() => task.abort(), 100);

    try {
        const result = await task;
        console.log(result);
    } catch {
        console.log('aborted');
    }
}

API Reference

Constructor

new Task((resolve, reject, controller, onAbort) => {}, controller);

Arguments

• initialiser: Function - A function to initialise the task. Same as the Promise initialiser with extra arguments (see below).
  • resolve: Function - Resolve the task with an optional response payload. Same as the Promise resolve method.
  • reject: Function - Reject the task with an optional reason. Same as the Promise reject method.
  • controller: AbortController - The AbortController instance used to cancel this task. This is useful for sharing with child tasks to synchronise cancellation.
  • onAbort: Function - Register a callback function to be called when this task instance is cancelled. This function accepts a single reason argument which is optionally supplied when the abort method is called on the task instance. This is particularly useful for performing cleanups.
• controller: AbortController? - An optional AbortController instance to use as the cancellation manager for this task. This is useful for passing parent controller instances to child tasks to synchronise cancellation.

Note: ? indicates an optional value.

Properties

All properties available on the standard Promise instance with the addition of:

• signal: AbortSignal - Readonly access to the underlying AbortSignal attached to this task instance.
• hasAborted: Boolean - A flag indicating whether this task instance has been aborted.

Methods

All methods available on the standard Promise instance with the addition of:

• abort: Function - Abort this task instance (and any other tasks sharing this tasks's controller). The abort function accepts the following arguments:
  • reason: Any? - An optional reason for cancelling this task.