suspenders-js/dist/Scope.d.ts

Asynchronous programming library utilizing coroutines, functional reactive programming and structured concurrency.

import { CancelFunction, Coroutine, CoroutineFactory, ResultCallback, Resume, Suspender } from "./Types";
/**
 * Scope is used to start groups of coroutines that are canceled together. If any coroutine in the
 * scope throws an error, it will cancel all the remaining active coroutines within the scope.
 * Scopes canceled with an error will call errorCallback and bubble up errrors to their parent
 * scope.
 */
export declare class Scope {
    static nonCanceling: Scope;
    _cancelCallbacks: Map<Coroutine<unknown>, CancelFunction>;
    private _finishedCallbacks;
    private _subscopes;
    private _isFinishing;
    private _isFinished;
    private _isCanceled;
    private _isCancelable;
    private _parent?;
    private _errorCallback?;
    constructor(options?: {
        parent?: Scope;
        errorCallback?: (error: unknown, scope: Scope) => void;
        isCancelable?: boolean;
    });
    /**
     * Returns true if scope is not canceled.
     */
    isActive(): boolean;
    /**
     * Starts a coroutine in this scope. Scope.call() is the preferred method of calling a coroutine
     * from a running coroutine when blocking on it's result.
     * @param {CoroutineFactory<T>} factory Factory creates a coroutine that is then started in this
     * Scope.
     */
    launch<T>(factory: CoroutineFactory<T>): CancelFunction;
    /**
     * Cancels all coroutines in this scope. All pending suspenders are canceled and all active
     * coroutines finally block is called. If their finally block suspends, they are migrated to a
     * non-canceling scope.
     */
    cancel(): void;
    /**
     * Converts a suspender to a coroutine that yields to get a result.
     * @param {Suspender<T>} suspender
     * @return {Coroutine<T>}
     */
    suspend<T>(suspender: Suspender<T>): Coroutine<T>;
    /**
     * Converts 2 suspenders to a coroutine that yields a tuple of the results. Usually used with
     * asynchronous suspenders so they run concurrently.
     * @param {Suspender<A>} susA
     * @param {Suspender<B>} susB
     * @return {[A, B]}
     */
    suspend2<A, B>(susA: Suspender<A>, susB: Suspender<B>): Coroutine<[A, B]>;
    /**
     * Converts 3 suspenders to a coroutine that yields a tuple of the results. Usually used with
     * asynchronous suspenders so they run concurrently.
     * @param {Suspender<A>} susA
     * @param {Suspender<B>} susB
     * @param {Suspender<C>} susC
     * @return {[A, B, C]}
     */
    suspend3<A, B, C>(susA: Suspender<A>, susB: Suspender<B>, susC: Suspender<C>): Coroutine<[A, B, C]>;
    /**
     * Converts 4 suspenders to a coroutine that yields a tuple of the results. Usually used with
     * asynchronous suspenders so they run concurrently.
     * @param {Suspender<A>} susA
     * @param {Suspender<B>} susB
     * @param {Suspender<C>} susC
     * @param {Suspender<D>} susD
     * @return {[A, B, C, D]}
     */
    suspend4<A, B, C, D>(susA: Suspender<A>, susB: Suspender<B>, susC: Suspender<C>, susD: Suspender<D>): Coroutine<[A, B, C, D]>;
    /**
     * Starts a coroutine in scope and waits for all it's launched coroutines to finish before
     * returning. Internally, this creates a subscope and launches the coroutine in that subscope.
     * When the subscope finishes the results of the coroutine are returned.
     * @param {CoroutineFactory<T>} factory
     */
    call<T>(factory: CoroutineFactory<T>): Coroutine<T>;
    /**
     * Starts a coroutine in this scope without waiting for it's returned result. Returns a suspender
     * to get the result of the coroutine.
     * @param {CoroutineFactory<T>} factory
     * @return {Suspender<T>}
     */
    callAsync<T>(factory: CoroutineFactory<T>): Suspender<T>;
    /**
     * Resumes a coroutine.
     * @param {Coroutine<T>} coroutine
     * @param {Resume<unknown>} resume
     * @param {(x: T) => void | void} doneCallback
     */
    _resume<T>(coroutine: Coroutine<T>, resume: Resume<unknown>, resultCallback?: ResultCallback<T>): void;
    /**
     * Marks this scope as finishing. Attempting to add new coroutines to this scope will throw a
     * FinishingError(). Returns a suspender that resolves when all the coroutines in this scope have
     * completed.
     * @return {Suspender<T>}
     */
    private _finish;
    /**
     * Cancels all coroutines in this scope and calls errorCallback. Bubbles error to parent.
     * @param error
     */
    _cancelWithError(error: unknown): void;
    /**
     * Checks if new coroutines can be created.
     */
    private _checkIfFinishing;
}