magic-aborter/dist/cjs/index.d.ts

An magic util to control everything abortable

/**
 * Represents an object that can be aborted.
 * Any object that implements this interface must provide an abort method.
 *
 * @template T - The type of the object being made abortable
 */
export type Abortable<T = object> = T & {
    /**
     * Aborts the operation.
     */
    abort: () => any;
};
/**
 * Configuration options for creating a new MagicAborter instance.
 */
export interface AborterOptions {
    /** Optional array of child aborters that will be aborted when the parent is aborted */
    children?: Array<MagicAborter>;
}
/** Event types that can be emitted by MagicAborter */
export type EventType = "abort" | "aborted";
/**
 * MagicAborter is a utility class that manages multiple abortable operations.
 * It can collect various types of abortable objects (like Promises, fetch requests, or native AbortControllers)
 * and abort them all at once.
 *
 * Features:
 * - Collect multiple abortable objects
 * - Create parent-child relationships between aborters
 * - Event-driven architecture with abort events
 * - TypeScript support
 *
 * @implements {Abortable}
 */
export declare class MagicAborter implements Abortable {
    private _aborted;
    private children;
    private collections;
    private emitter;
    /**
     * Converts any object into an abortable object by adding an abort method.
     *
     * @template T - The type of object to make abortable
     * @param {T} target - The object to make abortable
     * @param {() => void} abort - The abort function to be called
     * @returns {Abortable<T>} The original object with an abort method
     */
    static toAbortable<T>(target: T, abort: () => void): Abortable<T>;
    /**
     * Creates a new MagicAborter instance.
     *
     * @param {AborterOptions} [options] - Configuration options
     * @param {Array<MagicAborter>} [options.children] - Child aborters to be managed
     */
    constructor(options?: AborterOptions);
    /**
     * Gets the current abort state.
     * Returns true only if this aborter and all its children are aborted.
     */
    get aborted(): boolean;
    /**
     * Sets the abort state of this aborter.
     */
    set aborted(value: boolean);
    /**
     * Collects an abortable object to be managed by this aborter.
     * The object must implement the Abortable interface (have an abort method).
     *
     * @param {Abortable} abortable - The abortable object to collect
     */
    collect(abortable: Abortable): void;
    /**
     * Aborts all collected operations and child aborters.
     * This will:
     * 1. Emit the 'abort' event
     * 2. Abort all collected operations
     * 3. Abort all child aborters
     * 4. Set the aborted state to true
     * 5. Emit the 'aborted' event
     */
    abort(): void;
    /**
     * Registers an event listener for the specified event type.
     *
     * @param {EventType} event - The event type to listen for ('abort' or 'aborted')
     * @param {() => void} listener - The callback function to execute when the event occurs
     */
    on(event: EventType, listener: () => void): void;
    /**
     * Removes an event listener for the specified event type.
     *
     * @param {EventType} event - The event type to remove the listener from
     * @param {() => void} listener - The callback function to remove
     */
    off(event: EventType, listener: () => void): void;
    /**
     * Registers a listener for the 'abort' event.
     * This event is emitted before the abort operation begins.
     *
     * @param {() => void} listener - The callback function to execute
     */
    onAbort(listener: () => void): void;
    /**
     * Registers a listener for the 'aborted' event.
     * This event is emitted after all operations have been aborted.
     *
     * @param {() => void} listener - The callback function to execute
     */
    onAborted(listener: () => void): void;
    /**
     * Adds a child aborter to this aborter.
     * When this aborter is aborted, all child aborters will also be aborted.
     *
     * @param {MagicAborter} child - The child aborter to add
     */
    addChildAborter(child: MagicAborter): void;
    /**
     * Removes a child aborter from this aborter.
     *
     * @param {MagicAborter} child - The child aborter to remove
     */
    removeChildAborter(child: MagicAborter): void;
}
/**
 * Creates a new MagicAborter instance with the specified options.
 * This is a convenience function for creating a new aborter.
 *
 * @param {AborterOptions} [options] - Configuration options for the aborter
 * @returns {MagicAborter} A new MagicAborter instance
 */
export declare function createMagicAborter(options?: AborterOptions): MagicAborter;
/**
 * A convenience export of the static toAbortable method.
 * Converts any object into an abortable object.
 *
 * @template T - The type of object to make abortable
 * @param {T} target - The object to make abortable
 * @param {() => void} abort - The abort function to be called
 * @returns {Abortable<T>} The original object with an abort method
 */
export declare const toAbortable: typeof MagicAborter.toAbortable;
//# sourceMappingURL=index.d.ts.map