js-aborts

AbortController constructors inspired
by Go's context package

✅ Creating AbortControllers that
inherit abortion from a parent AbortSignals
and can be aborted manually or after a timeout.

✅ Created AbortControllers are Disposable and can be used with
using statement.

✅ Supports long timeouts (no wraps around).

✅ Zero dependencies

Disclaimer

For production use I would recommend using
AbortSignal.timeout() and
AbortSignal.any().

However, there are some issues with leaks if you use them together. My approach focuses on creating derived
AbortController rather than AbortSignal to allow manual disposal of not needed controllers to avoid leaks.

Install

``shell
npm install js-aborts
`

API

`typescript
import { aborts } from 'js-aborts';
`

$3

`typescript
function create(...parentSignals: (AbortSignal|undefined)[]): AbortController;
`

Creates a new AbortController:
- If valid parentSignals are provided, abortion any of them also aborts the returned controller.
- If any of parentSignals is already aborted, the returned controller is also already aborted with the reason
of the first aborted parent signal

$3

`typescript
function timeout(timeoutMs: number, ...parentSignals: (AbortSignal|undefined)[]): AbortController;
`

Creates a new AbortController that aborts after the specified timeoutMs.
If valid parentSignals are provided, abortion any of them also aborts the returned controller.
If any of parentSignals is already aborted, the returned controller is also already aborted with the reason
of the first aborted parent signal

Usage notes

$3

`typescript
import { aborts } from 'js-aborts';

async function doSome(arg: string, signal?: AbortSignal) {
// ...
}

async function doSomeComplex(signal?: AbortSignal) {
// Create a controller that will be aborted after 5 seconds or when the parent
// signal is aborted. Thanks to using statement, the created controller will
// be disposed (clearing the internal timeout) automatically at the end of the scope.
using ac = aborts.timeout(5000, signal)

await doSome('first call', ac.signal)
await doSome('second call', ac.signal)
}

`

$3

Unlike AbortSignal.timeout(),
the lib's functions return AbortController rather than AbortSignal.

This is done to allow manual abortion of not needed controllers to avoid leaks of internal timers/listeners.

It's better to dispose the created controllers explicitly when they are not needed anymore:

`typescript
// In typescript < 5.2:
function myFunc(signal?: AbortSignal) {
const ac = aborts.timeout(5000, signal)
try {
// use ac.signal
} finally {
ac.abort()
}
}
`

`typescript
// In typescript >= 5.2:
function myFunc(signal?: AbortSignal) {
// Unlike standard AbortControllers, the created controller is Disposable
using ac = aborts.timeout(5000, signal)
// use ac.signal
}
`

> [!WARNING]
> Be careful with using statement: it's not currently supported in all environments. The lib is built with
> ES6 target and polyfills Symbol.dispose that works with the code Typescript generates for using` statements,
> but it's a bit fragile.