Magic Aborter

English | 简体中文

A utility for managing multiple abortable operations in TypeScript/JavaScript applications. It allows you to:

• Collect multiple abortable objects (like fetch requests, timers, or any custom abortable operations)
• Create parent-child relationships between aborters
• Abort all collected operations and child aborters with a single call

Features

• 🎯 One-Click Abort: Abort multiple operations with a single abort() call
• 🌲 Parent-Child Structure: Create hierarchical abort relationships - when parent aborts, all children abort
• 🔄 Operation Collection: Collect any number of abortable operations (like fetch requests or timers)
• 🎭 Event Handling: Get notified before and after abort operations through event listeners
• 📦 TypeScript support out of the box

Installation

npm install magic-aborter
# or
yarn add magic-aborter
# or
pnpm add magic-aborter

Usage

Create an Aborter

Create a new instance of MagicAborter to manage your abortable operations.

// Create a new aborter
const aborter = createMagicAborter();

Create Abortable Promise

Transform a regular promise into an abortable one using the toAbortable utility.

// Create an abortable promise
const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
const abortableDelay = toAbortable(delay(5000), () => {
  console.log('Timer aborted!');
  // Clean up logic here (e.g., clear timeout)
});

Use with Fetch API

Integrate with native fetch API using AbortController.

// Use native AbortController for fetch
const controller = new AbortController();
const fetchData = fetch('https://api.example.com/data', { 
  signal: controller.signal 
});
// Directly collect the controller since it already has abort() method
aborter.collect(controller);

Custom Abortable Operation

Create a custom operation that can be aborted using AbortSignal.

// Another native AbortController example
const anotherController = new AbortController();
const customOperation = (signal: AbortSignal) => {
  return new Promise((resolve, reject) => {
    signal.addEventListener('abort', () => {
      reject(new Error('Operation aborted'));
    });
    // Your async operation here
  });
};
// Start the operation and collect its controller
customOperation(anotherController.signal);
aborter.collect(anotherController);

Collect Operations

Add abortable operations to your MagicAborter instance.

// Collect operations
aborter.collect(abortableDelay);

Event Handling

Listen to abort events to perform actions before and after abortion.

// Listen to abort events
aborter.onAbort(() => {
  console.log('Aborting all operations...');
});

aborter.onAborted(() => {
  console.log('All operations aborted!');
});

Trigger Abort

Abort all collected operations with a single call. After abort() is called, all collected abortables will be cleared automatically, allowing you to reuse the same aborter for new operations.

// Trigger abort - will abort all collected operations
aborter.abort();

// After abort(), the aborter is cleared and ready for new operations
aborter.collect(newAbortableOperation); // You can collect new operations

Hierarchical Abort Control

Create parent-child relationships between aborters for hierarchical control.

const parentAborter = createMagicAborter();
const childAborter = createMagicAborter();

parentAborter.addChildAborter(childAborter);

// When parent aborts, child will also abort
parentAborter.abort();

API

MagicAborter

The main class for managing abortable operations.

Methods

• abort(): void

  • Aborts all collected operations and child aborters
  • Clears all collected operations after aborting
  • Emits 'abort' event before starting and 'aborted' event after completion

• collect(abortable: Abortable): void

  • Collects an abortable operation
  • Parameters:
    • abortable: Any object implementing the Abortable interface (must have an abort() method)

• onAbort(listener: () => void): void

  • Registers a listener for the pre-abort event
  • Parameters:
    • listener: Callback function executed before abort operations begin

• onAborted(listener: () => void): void

  • Registers a listener for the post-abort event
  • Parameters:
    • listener: Callback function executed after all operations are aborted

• addChildAborter(child: MagicAborter): void

  • Adds a child aborter to the current instance
  • Parameters:
    • child: Another MagicAborter instance to be managed as a child

• removeChildAborter(child: MagicAborter): void

  • Removes a child aborter from the current instance
  • Parameters:
    • child: The child MagicAborter instance to remove

Properties

• aborted: boolean
  • Read-only property indicating whether this aborter and all its children are aborted
  • Returns true only if this aborter and all its children are aborted

createMagicAborter(options?)

Creates a new MagicAborter instance.

Parameters

• options?: AborterOptions
  • Optional configuration object with the following properties:
    • children?: MagicAborter[]: Array of child aborters to be managed

Returns

• MagicAborter: A new MagicAborter instance

toAbortable<T>(target, abortFn)

Converts any object into an abortable object.

Type Parameters

• T: The type of the target object

Parameters

• target: T: The object to make abortable
• abortFn: () => void: Function to be called when the object is aborted

Returns

• Abortable<T>: The original object enhanced with an abort() method

Types

Abortable<T>

Interface for abortable objects.

type Abortable<T = object> = T & {
  abort: () => any;
}

AborterOptions

Configuration options for creating a new MagicAborter.

interface AborterOptions {
  children?: Array<MagicAborter>;
}

License

MIT