shelving/sequence/Sequence.js

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 class Sequence {
    [Symbol.toStringTag] = "Sequence";
    /**
     * 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`.
     */
    async return(value) {
        // Default behaviour for a generator is to return `done: true` and repeat back input value.
        return { done: true, value: await value };
    }
    /**
     * 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.
     */
    async throw(reason) {
        // Default behaviour for a generator is to throw the error back out of the iterator and not continue.
        throw reason;
    }
    // Implement `AsyncIterable`
    [Symbol.asyncIterator]() {
        return this;
    }
    // Implement `AsyncDisposable`
    async [Symbol.asyncDispose]() {
        await this.return();
    }
}