evnty
Version:
Async-first, reactive event handling library for complex event flows in browser and Node.js
164 lines (163 loc) • 6.49 kB
TypeScript
import { AnyIterator, AnyIterable, MaybePromise } from './types.js';
/**
* @internal
*/
export declare function isThenable(value: unknown): value is PromiseLike<unknown>;
/**
* @internal
* A no-operation function. Useful as a default callback or placeholder.
*/
export declare const noop: () => void;
/**
* @internal
* Returns the minimum value from an iterable, or a fallback if empty.
*/
export declare function min(values: Iterable<number>, fallback: number): number;
/**
* @internal
* Indicates which iterator method triggered a mapping operation.
*/
export declare enum MapIteratorType {
/** The next() method was called */
NEXT = 0,
/** The return() method was called */
RETURN = 1,
/** The throw() method was called */
THROW = 2
}
/**
* @internal
* A mapping function for transforming iterator results.
* @template T - The input value type
* @template U - The output value type
* @template TReturn - The iterator return type
*/
export interface MapNext<T, U, TReturn> {
(result: MaybePromise<IteratorResult<T, TReturn>>, type: MapIteratorType): MaybePromise<IteratorResult<U, TReturn>>;
}
/**
* @internal
* Wraps an iterator with a mapping function applied to each result.
* @template U - The output value type
* @template T - The input value type
* @template TReturn - The iterator return type
* @template TNext - The type passed to next()
* @param iterator - The source iterator to wrap
* @param map - The mapping function to apply to each result
* @returns An async iterator with mapped results
*/
export declare const mapIterator: <U, T, TReturn, TNext>(iterator: AnyIterator<T, TReturn, TNext>, map: MapNext<T, U, TReturn>) => AsyncIterator<U, TReturn, TNext>;
/**
* Wraps an async iterable with abort signal support.
* Each iteration creates a fresh iterator with scoped abort handling.
* Listener is added at iteration start and removed on completion/abort/return.
*
* @template T - The yielded value type
* @template TReturn - The return value type
* @template TNext - The type passed to next()
* @param iterable - The source async iterable to wrap
* @param signal - AbortSignal to cancel iteration
* @returns An async iterable with abort support
*
* @example
* ```typescript
* const controller = new AbortController();
* const source = async function*() { yield 1; yield 2; yield 3; };
*
* for await (const value of abortableIterable(source(), controller.signal)) {
* console.log(value);
* if (value === 2) controller.abort();
* }
* ```
*/
export declare function abortableIterable<T, TReturn, TNext>(iterable: AsyncIterable<T, TReturn, TNext>, signal: AbortSignal): AsyncIterable<T, TReturn, TNext>;
/**
* Interface for creating iterable number sequences with various parameter combinations.
* Supports infinite sequences, counted sequences, and sequences with custom start and step values.
*/
export interface Iterate {
(): Iterable<number, void, unknown>;
(count: number): Iterable<number, void, unknown>;
(start: number, count: number): Iterable<number, void, unknown>;
(start: number, count: number, step: number): Iterable<number, void, unknown>;
}
/**
* Creates an iterable sequence of numbers with flexible parameters.
* Can generate infinite sequences, finite sequences, or sequences with custom start and step values.
*
* @param args Variable arguments to configure the sequence:
* - No args: Infinite sequence starting at 0 with step 1
* - 1 arg (count): Sequence from 0 to count-1
* - 2 args (start, count): Sequence starting at 'start' for 'count' iterations
* - 3 args (start, count, step): Custom start, count, and step value
* @returns An iterable that generates numbers according to the parameters
*
* @example
* ```typescript
* // Infinite sequence: 0, 1, 2, 3, ...
* for (const n of iterate()) { }
*
* // Count only: 0, 1, 2, 3, 4
* for (const n of iterate(5)) { }
*
* // Start and count: 10, 11, 12, 13, 14
* for (const n of iterate(10, 5)) { }
*
* // Start, count, and step: 0, 2, 4, 6, 8
* for (const n of iterate(0, 5, 2)) { }
* ```
*/
export declare const iterate: Iterate;
/**
* @internal
* Creates a promise that resolves after a specified timeout. If an `AbortSignal` is provided and triggered,
* the timeout is cleared, and the promise resolves to `false`.
*
* @param {number} timeout - The time in milliseconds to wait before resolving the promise.
* @param {AbortSignal} [signal] - An optional `AbortSignal` that can abort the timeout.
* @returns {Promise<boolean>} A promise that resolves to `true` if the timeout completed, or `false` if it was aborted.
*
* @example
* ```typescript
* const controller = new AbortController();
* setTimeout(() => controller.abort(), 500);
* const result = await setTimeoutAsync(1000, controller.signal);
* console.log(result); // false
* ```
*/
export declare const setTimeoutAsync: (timeout: number, signal?: AbortSignal) => Promise<boolean>;
/**
* Converts a synchronous iterable to an asynchronous iterable.
* Wraps the sync iterator methods to return promises, enabling uniform async handling.
*
* @template T The type of values yielded by the iterator
* @template TReturn The return type of the iterator
* @template TNext The type of value that can be passed to next()
* @param iterable A synchronous iterable to convert
* @returns An async iterable that yields the same values as the input
*
* @example
* ```typescript
* const syncArray = [1, 2, 3, 4, 5];
* const asyncIterable = toAsyncIterable(syncArray);
*
* for await (const value of asyncIterable) {
* console.log(value); // 1, 2, 3, 4, 5
* }
* ```
*/
export declare const toAsyncIterable: <T, TReturn, TNext>(iterable: Iterable<T, TReturn, TNext>) => AsyncIterable<T, TReturn, TNext>;
/**
* @internal
*/
export declare function pipe<T, U>(iterable: AsyncIterable<T>, generatorFactory: () => (value: T) => AnyIterable<U, void, unknown>, signal?: AbortSignal): AsyncGenerator<Awaited<U>, void, unknown>;
/**
* @internal
* Merges multiple async iterables into a single stream.
* Values are yielded as they become available from any source.
* Completes when all sources complete; aborts all on error.
* @template T - The value type yielded by all iterables
* @param iterables - The async iterables to merge
* @returns A merged async iterable
*/
export declare const mergeIterables: <T>(...iterables: AsyncIterable<T, void, unknown>[]) => AsyncIterable<T, void, unknown>;