shelving/sequence/Sequence.d.ts

Toolkit for using data in JavaScript.

/**
 * Sequence of values designed to be extended that implements the full async generator protocol.
 *
 * Note: while this class implements the iterator protocol, it is not a _generator_.
 * - Generators place additional constraints on the operation of an iterator.
 * - Key constraint is that a generator only runs one time through and keeps track of its status.
 * - This means when a generator throws, further requests to `next()` will always return `done: true`
 * - This class does not provide that guarantee or have that constraint.
 */
export declare abstract class Sequence<T, R, N> implements AsyncIterable<T, R | undefined, N | undefined>, AsyncIterator<T, R | undefined, N | undefined>, AsyncDisposable {
    readonly [Symbol.toStringTag] = "Sequence";
    /**
     * Get a next value from this async iterator.
     *
     * @param value Optional next value that gets returned from `yield` statements.
     * - Rarely used in real world appliations.
     * - Will be `undefined` on the first call.
     * - Will be the `N` next value on subsequent calls.
     *
     * @returns An incomplete iterator result with `done: false` and `value: T`.
     */
    abstract next(value?: N | undefined): Promise<IteratorResult<T, R | undefined>>;
    /**
     * Finish iteration and optionally provide the iterator's final return value.
     * - Mirrors the default async generator `return()` behaviour.
     * - Subclasses can override this to perform cleanup before the sequence stops.
     *
     * @param value Optional return value that gets returned
     * - Rarely used in real world applications.
     * - Will be `undefined` on the first call.
     *
     * @returns A completed iterator result with `done: true`.
     */
    return(value?: R | undefined | PromiseLike<R | undefined>): Promise<IteratorResult<T, R | undefined>>;
    /**
     * Throw an error into this iterator.
     * - Mirrors the default async generator `throw()` behaviour.
     * - Subclasses can override this to recover from errors or perform cleanup.
     *
     * @param reason Error or other thrown value to send into the iterator.
     */
    throw(reason?: unknown): Promise<IteratorResult<T, R | undefined>>;
    [Symbol.asyncIterator](): AsyncIterator<T, R | undefined, N | undefined>;
    [Symbol.asyncDispose](): Promise<void>;
}