shelving/util/sequence.d.ts

Toolkit for using data in JavaScript.

import { ABORT } from "./constants.js";
import type { ErrorCallback, ValueCallback } from "./function.js";
export interface IteratorAbortResult<R> {
    done: typeof ABORT;
    value: R;
}
/** An extension of  */
export type IteratorAbortableResult<T, R> = IteratorResult<T, R> | IteratorAbortResult<R>;
/**
 * Is a value an async iterable object?
 * - Any object with a `Symbol.iterator` property is iterable.
 * - Note: Array and Map instances etc will return true because they implement `Symbol.iterator`
 */
export declare function isSequence(value: unknown): value is AsyncIterable<unknown>;
/** Infinite sequence that yields until a `SIGNAL` is received. */
export declare function repeatUntil<T = void, R = void, N = void>(source: AsyncIterable<T, R | undefined, N | undefined>, ...signals: [PromiseLike<R>, ...PromiseLike<R>[]]): AsyncGenerator<T, R | undefined, N | undefined>;
/** Infinite sequence that yields every X milliseconds (yields a count of the number of iterations). */
export declare function repeatDelay(ms: number): AsyncGenerator<number, void, void>;
/** Dispatch items in a sequence to a (possibly async) callback. */
export declare function callSequence<T>(sequence: AsyncIterable<T, void, void>, callback: ValueCallback<T>): AsyncGenerator<T, void, void>;
/**
 * Iterate over a sequence until the returned `stop()` callback is called.
 *
 * Regarding errors:
 * - Does not stop iterating on errors, simply sends the error to `onError()` and continues to iterate.
 * - On the following iterator after throwing an error, a "generator" will return `done: true` (because they regard errors as concluding the iteration).
 * - But the iterator protocol does not require this, so this continues to iterate until it's explicitly ended via the returned `stop()` callback.
 *
 * @return Callback function that can end the sequence run.
 */
export declare function runSequence<T, R, N>(sequence: AsyncIterable<T, R | undefined, N | undefined>, onNext?: (value: T) => N | undefined, onError?: ErrorCallback, onReturn?: (value: R | undefined) => void): (value?: R | undefined) => void;
/** Merge several sequences (calls the sequences in series). */
export declare function mergeSequences<T>(...sequences: AsyncIterable<T>[]): AsyncIterable<T>;