isotropic-timeout-cancel

A utility that manages the cancellation of an asynchronous task with a time limit, abort signals, and standardized errors.

Why Use This?

• Everything From isotropic-cancel: Reasons, abort signals, silent cancellation, standardized AbortError and CanceledError objects, and using support
• Built-In Time Limit: A timeout config automatically cancels the task with a standardized TimeoutError
• Temporal Support: The timeout accepts a number of milliseconds or a Temporal.Duration
• Event Loop Control: ref, unref, and hasRef pass through to the internal timer
• Shared Implementation: The pending-task machinery used by isotropic-backoff, isotropic-mutex, isotropic-request, and isotropic-throttle

Installation

npm install isotropic-timeout-cancel

Overview

TimeoutCancel is a child class of isotropic-cancel. It behaves identically, with one addition: when constructed with a finite timeout, an internal isotropic-later timer cancels the instance with a TimeoutError if it is still pending when the time limit elapses. Settling or canceling the instance by any other means clears the timer.

Usage

import _TimeoutCancel from 'isotropic-timeout-cancel';

const _acquireSomething = ({
    signal,
    timeout
} = {}) => {
    const {
            promise,
            reject,
            resolve
        } = Promise.withResolvers(),

        cancel = _TimeoutCancel({
            onCancel: ({
                error
            }) => {
                removeFromQueue();

                if (error) {
                    reject(error);
                }
            },
            signal,
            subject: 'Acquisition',
            timeout
        });

    addToQueue(() => {
        cancel.complete();
        resolve(theThing);
    });

    promise.cancel = config => {
        cancel.cancel(config);

        return promise;
    };

    return promise;
};

If the time limit elapses first, the promise rejects with an error like:

TimeoutError: Acquisition timed out

API

Constructor

_TimeoutCancel(config)

Creates a new timeout cancel instance. TimeoutCancel is created with isotropic-make, so it can be called with or without new.

Parameters

All isotropic-cancel config properties (details, onCancel, signal, and subject), plus:

• timeout (Number | Temporal.Duration, optional): The time limit. A number is interpreted as milliseconds. When omitted or not finite, no timer is created and the instance behaves exactly like a base Cancel. When the config signal is already aborted, the instance cancels during construction and no timer is created.

Note that a timeout of 0 or a negative number follows the same 'soon' or 'asap' scheduling as isotropic-later, canceling almost immediately but still asynchronously.

Instance Members

All isotropic-cancel members (cancel, complete, canceled, completed, and Symbol.dispose), plus:

hasRef()

Returns whether the internal timer is keeping the event loop alive. Returns false when there is no pending timer.

ref()

Requests that the internal timer keep the event loop alive. Returns the instance.

unref()

Requests that the internal timer not keep the event loop alive. Returns the instance.

TimeoutCancel.timeoutError(config)

A static factory for the standardized TimeoutError.

Parameters

• config (Object, optional):
  • details (Object, optional): Merged into the error details along with duration
  • duration (Number): The elapsed time limit
  • subject (String, optional): Default: 'Task'

Returns

• (Error): An isotropic-error with name 'TimeoutError', message `${subject} timed out`, and details including duration

Errors

| Name | Cause | Details | | --- | --- | --- | | AbortError | Canceled via an AbortSignal | The configured details | | CanceledError | Canceled without a reason | The configured details | | TimeoutError | The timeout elapsed | duration, plus the configured details |

When cancel is called with a reason, that reason is delivered as-is instead of a generated error.

Related Packages

• isotropic-cancel: The parent class, without a time limit
• isotropic-later: The timer implementation used for the time limit
• isotropic-timeout: A convenience wrapper that applies this class to a callback function or promise

Contributing

Please refer to CONTRIBUTING.md for contribution guidelines.

Issues

If you encounter any issues, please file them at https://github.com/ibi-group/isotropic-timeout-cancel/issues