npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@xuchaoqian/abortable-promise

v1.11.2

Published

A TypeScript library for creating abortable promises with ease.

Downloads

1,485

Readme

AbortablePromise

A TypeScript library for creating abortable promises with ease.

npm version License: MIT

Overview

AbortablePromise extends the standard Promise functionality by adding the ability to abort ongoing asynchronous operations. When aborted, an AbortablePromise rejects with an AbortError or any custom reason you provide, allowing for clean and predictable error handling.

Features

  • Simple API, rich features, fully compatible with standard Promises
  • Cooperates with AbortController very well, including the fetch API
  • Provides a set of helper classes and functions to make abortable promises more intuitive and easier to use
  • Written in TypeScript, with full type safety

Installation

# Install using npm:
npm install @xuchaoqian/abortable-promise

# Install using pnpm:
pnpm install @xuchaoqian/abortable-promise

# Install using yarn:
yarn add @xuchaoqian/abortable-promise

Usage

1. Creating an AbortablePromise

Using the constructor

const abortablePromise = new AbortablePromise<string>((resolve, reject) => {
  setTimeout(() => resolve('Operation completed'), 3000);
});

Using static methods

// use new(), this is the same as using constructor, just for API design consistency
const abortablePromise = AbortablePromise.new<string>((resolve, reject) => {
  setTimeout(() => resolve('Operation completed'), 3000);
});
// Or use newWithSignal() if you want the API to create a new AbortSignal for you automatically
const abortablePromise = AbortablePromise.newWithSignal<string>((resolve, reject, signal) => {
  signal.onabort = () => reject('Operation aborted');
  setTimeout(() => resolve('Operation completed'), 3000);
});

From an Promise

const abortablePromise = AbortablePromise.from(new Promise<string>((resolve) => {
  setTimeout(() => resolve('Operation completed'), 3000);
}));

2. Aborting an AbortablePromise

Abort by the built-in abort() method

const abortablePromise = new AbortablePromise<string>((resolve, reject) => {
  setTimeout(() => resolve('Operation completed'), 3000);
});
abortablePromise.abort(); // Abort with default reason
abortablePromise.abort('Custom abort reason'); // Abort with custom reason

Abort by an external AbortController

const controller = new AbortController();
const abortablePromise = new AbortablePromise<string>((resolve, reject) => {
  setTimeout(() => resolve('Operation completed'), 3000);
}, controller.signal);
controller.abort(); // Abort with default reason
controller.abort('Custom abort reason'); // Abort with custom reason

3. Cooperating with the fetch API

interface Data {
  id: number;l
  [key: string]: any;
}
const loadData = (id: number): AbortablePromise<Data> => {
  return AbortablePromise.newWithSignal<Data>((resolve, reject, signal) => {
    fetch(`https://api.example.com/data/${id}`, { signal })
      .then(response => response.json())
      .then(data => resolve(data as Data))
      .catch(reject);
  });
}
const abortablePromise = loadData(123);
setTimeout(() => abortablePromise.abort(), 100);

API Reference

Class: AbortablePromise<T>

AbortablePromise<T> is a class that extends the native Promise<T> with abort functionality.

Constructor

new AbortablePromise<T>(executor, signal?)

Creates a new AbortablePromise.

  • executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void, signal: AbortSignal) => void
  • signal?: AbortSignal (optional)

Static Methods

AbortablePromise.new<T>(executor, signal?)

The same as new AbortablePromise<T>(executor, signal?), just for API design consistency.

AbortablePromise.newWithSignal<T>(executor, signal?)

Creates a new AbortablePromise with a new AbortSignalPlus if no signal is provided.

AbortablePromise.from<T>(promise, signal?)

Creates a new AbortablePromise from an existing Promise.

AbortablePromise.fromWithSignal<T>(promise, signal?)

Creates a new AbortablePromise from an existing Promise, with a new AbortSignalPlus if no signal is provided.

AbortablePromise.all<T>(values, signal?)

Similar to Promise.all(), but returns an AbortablePromise.

AbortablePromise.allWithSignal<T>(values, signal?)

Similar to AbortablePromise.all(), but creates a new AbortSignalPlus if no signal is provided.

AbortablePromise.allSettled<T>(values, signal?)

Similar to Promise.allSettled(), but returns an AbortablePromise.

AbortablePromise.allSettledWithSignal<T>(values, signal?)

Similar to AbortablePromise.allSettled(), but creates a new AbortSignalPlus if no signal is provided.

AbortablePromise.any<T>(values, signal?)

Similar to Promise.any(), but returns an AbortablePromise.

AbortablePromise.anyWithSignal<T>(values, signal?)

Similar to AbortablePromise.any(), but creates a new AbortSignalPlus if no signal is provided.

AbortablePromise.race<T>(values, signal?)

Similar to Promise.race(), but returns an AbortablePromise.

AbortablePromise.raceWithSignal<T>(values, signal?)

Similar to AbortablePromise.race(), but creates a new AbortSignalPlus if no signal is provided.

AbortablePromise.resolve(value?, signal?)

Creates a new resolved AbortablePromise.

AbortablePromise.resolveWithSignal(value?, signal?)

Creates a new resolved AbortablePromise, with a new AbortSignalPlus if no signal is provided.

AbortablePromise.reject<T>(reason?)

Creates a new rejected AbortablePromise.

Instance Methods

abort(reason?)

Aborts the promise with an optional reason.

listen(signal)

Listens to the provided abort signal.

then<TResult1, TResult2>(onfulfilled?, onrejected?)

Adds callbacks to the promise. Returns a new AbortablePromise.

catch<TResult>(onrejected?)

Adds a rejection callback to the promise. Returns a new AbortablePromise.

finally(onfinally?)

Adds a callback to be executed when the promise is settled. Returns a new AbortablePromise.

Notes

  • All methods that return a new AbortablePromise propagate the abort functionality through the promise chain.
  • The xxxWithSignal variants of methods create a new AbortSignalPlus if no signal is provided, allowing for easier abort control.

Helper Classes

AbortError

A custom class extending DomException representing an abort error.

TimeoutError

A custom class extending DomException representing a timeout error.

AbortControllerPlus

AbortControllerPlus implements the AbortController interface as the native AbortController class does, but will abort with AbortError when abort() is called without a reason.

AbortSignalPlus

AbortSignalPlus implements the AbortSignal interface as the native AbortSignal class does, but allows access to the underlying controller from the signal and adds additional features, such as the one, hasTimeout methods.

Helper Functions

isAbortError(error: any): boolean

Checks if the given object is an AbortError. Will return true for both AbortError instances and DOMException instances with name AbortError.

isTimeoutError(error: any): boolean

Checks if the given object is an TimeoutError. Will return true for both TimeoutError instances and DOMException instances with name TimeoutError.

License

This project is licensed under the MIT License - see the LICENSE file for details.