/** * Type declarations for generators and related. */ import { Enhancements } from "./enhancements"; import type { EnhancedGenerator } from "./sync-impl"; import type { EnhancedAsyncGenerator } from "./async-impl"; /** * Like `Iterable` except allows specifying `TReturn` and `TNext`. * * Unlike `Iterable`, `TReturn` and `TNext` default to `T`, rather than * `any` and `undefined`, respectively. */ export type FullIterable = { sync: Iterable & { [Symbol.iterator]: () => Iterator; }; async: AsyncIterable & { [Symbol.asyncIterator]: () => AsyncIterator; }; }[S]; /** * Like `IterableIterator` except allows specifying `TReturn` and `TNext`. * * Unlike `IterableIterator`, `TReturn` and `TNext` default to `T`, rather than * `any` and `undefined`, respectively. */ export type FullIterableIterator = { sync: IterableIterator & { [Symbol.iterator]: () => FullIterableIterator; }; async: AsyncIterable & { [Symbol.asyncIterator]: () => FullIterableIterator; }; }[S]; /** * Selector type to select the types for synchronous generators. * @deprecated Use {@link Sync.type} */ export type Sync = 'sync'; /** * Selector type to select the types for asynchronous generators. * @deprecated Use {@link Async.type} */ export type Async = 'async'; /** * Selector type to select the types for synchronous or asynchronous generators. * Reference the members as {@link Sync.type} or {@link Async.type} */ export type SyncType = Sync | Async; /** * @internal */ export type FlatGen = any; /** * Returns the union of the element types of a tuple of generators. * @typeParam Arr a tuple type of Genable's. */ export type GenUnion = Arr extends [] ? Arr : Arr extends Array ? E extends Genable ? E2 : never : never; /** * Returns the element type of a [[Genable]] * @typeParam T the value type produced by the [[Genable]] */ export type GenType = G extends Genable ? T : never; /** * Any `Generator`, `Iterator`, or `Iterable`, which can be coerced to a * [[EnhancedGenerator]]. * * @typeParam T the value type produced by the [[Genable]] */ export type Genable = { sync: Generator | Iterator | Iterable | Enhancements; async: AsyncGenerator | AsyncIterator | AsyncIterable | Enhancements | Genable; }[S]; /** * A `Promise`, unless already promisified. */ export type GenPromise = globalThis.Promise ? X : T>; /** * A value in the [[Sync]] case, or a promise of a value in the [[Async]] case. */ export type ReturnValue = { sync: T; async: GenPromise; }[S]; type PromiseType = T extends PromiseLike ? R : T; /** * A value, or in the [[Async]] case, optionally a `Promise` of the value. */ type Value = ReturnValue | PromiseType; /** * A function which can be supplied to a reduce method. * * For the case where an init value of type A will be supplied, use: * * [[Reducer|Reducer\\]] * * For the case where no init value will be supplied, use: * * [[Reducer|Reducer\\]] * * For cases where an init value may or may not be supplied: * * [[Reducer|Reducer\\]] (equivalent to [[Reducer|Reducer\]]). * * For cases where **A** = **T** (for example, reducing a set of numbers to a number): * * [[Reducer|Reducer\\]] * * @typeParam A The accumulated result. * @typeParam T The individual element values supplied to be reduced. * @typeParam Init the initial value for the reducer. If no init value is supplied, the first call will be **T**; otherwise it will be **A**. * @typeParam S either Sync or Async. */ export type Reducer = { sync: (acc: Init | A, v: T) => A; async: (acc: Init | A, v: T) => A | PromiseLike; }[S]; /** * A predicate which can be applied to elements of an iteration. * @param v the element * @param idx the sequential index * @typeParam T the type of the elements. * @typeParam R the return type. */ export type IndexedFn = { sync: (v: T, idx: number) => R; async: (v: T, idx: number) => PromiseLike | R; }[S]; /** * A predicate which can be applied to elements of an iteration. * @param v the element * @param idx the sequential index * @typeParam T the type of the elements. */ export type IndexedPredicate = IndexedFn; export type UnwrapGenTypeArray = { [K in (keyof B) & number]: B[K] extends Genable ? PromiseType : never; }; /** * Unwrap an array of Genables * @typeParam B the type to be unwrapped. * @internal */ export type UnwrapGenType = UnwrapGenTypeArray[keyof B & number]; export interface GeneratorOps { /** * Return a generator that provides the supplied values. * @param values */ of(...values: T): Enhanced, S, TReturn, TNext>; asArray(gen: Genable): ReturnValue; /** * Limit the number of values that can be generated. A `RangeError` is thrown if this limit is * exceeded. See [[EnhancedGenerator.slice]] if you want to truncate. * @param max * @param gen */ limit(max: number, gen: Genable): Enhanced; /** * Limit the number of values that can be generated. A `RangeError` is thrown if this limit is * exceeded. See [[EnhancedGenerator.slice]] if you want to truncate. * @param max */ limit(max: number): GenOp; /** * Operate on each value produced by the generator. f is called with two values, the * value yielded by this generator and a sequential index. * @param f * @param thisArg Optional value to be supplied as context `this` for function _f_. * @param gen the generator. * @typeParam T the type of value produced by the generator. * @typeParam TReturn the type accepted by the `Iterator.return()` method. * @typeParam TNext the type accepted by the `Iterator.next()` method. */ forEach(f: IndexedFn, thisArg: any, gen: Genable): GenVoid; /** * Operate on each value produced by the generator. f is called with two values, the * value yielded by this generator and a sequential index. * @param f * @param gen the generator. * @typeParam T the type of value produced by the generator. * @typeParam TReturn the type accepted by the `Iterator.return()` method. * @typeParam TNext the type accepted by the `Iterator.next()` method. */ forEach(f: IndexedFn, gen: Genable): GenVoid; /** * Operate on each value produced by the generator. f is called with two values, the * value yielded by this generator and a sequential index. * @param f * @param thisArg Optional value to be supplied as context `this` for function _f_. * @typeParam T the type of value produced by the generator. * @typeParam TReturn the type accepted by the `Iterator.return()` method. * @typeParam TNext the type accepted by the `Iterator.next()` method. */ forEach(f: IndexedFn, thisArg?: any): (gen: Genable) => GenVoid; /** * Operate on each value produced by the generator. f is called with two values, the * value yielded by this generator and a sequential index. * @param f * @typeParam T the type of value produced by the generator. * @typeParam TReturn the type accepted by the `Iterator.return()` method. * @typeParam TNext the type accepted by the `Iterator.next()` method. */ forEach(f: IndexedFn): (gen: Genable, thisArg?: any) => GenVoid; /** * Accepts a function from `T` to `V, and returns a function that adapts a `Generator` * (or any [Genable|Genable\\]) to an enhanced `Generator`. Each yielded value V is * the result of applying the function `f` to to a value yielded by the `Generator`. * * In the async case, `f` may also return `Promise`. * * @param f a function from `V` to `T` * @typeParam T the type of value yielded by the supplied generator. * @typeParam V the type of value yielded by the resulting generator. */ map(f: IndexedFn): GenOpValue; /** * Accepts a function from `T` to `V, and returns a function that adapts a `Generator` * (or any [Genable|Genable\\]) to an enhanced `Generator`. Each yielded value V is * the result of applying the function `f` to to a value yielded by the `Generator`. * * In the async case, `f` may also return `Promise`. * * @param f * @param thisArg supplied as 'this' for each invocation of `f`. * @typeParam T the type of value produced by the generator. * @typeParam V the type of value yielded by the resulting generator. */ map(f: IndexedFn, thisArg?: any): GenOpValue; /** * Accepts a function from `T` to `V, and a `Generator` * (or any [Genable|Genable\\]) and returns an enhanced `Generator`. * * Each yielded value V is * the result of applying the function `f` to to a value yielded by the `Generator`. * * In the async case, `f` may also return `Promise`. * * @param f * @param gen the [[Genable]] whose yielded values we are mapping over. * @typeParam T the type of value produced by the generator. * @typeParam V the type of value yielded by the resulting generator. */ map(f: IndexedFn, gen: Genable): Enhanced; /** * Accepts a function from `T` to `V, and a `Generator` * (or any [Genable|Genable\\]) and returns an enhanced `Generator`. * * Each yielded value V is * the result of applying the function `f` to to a value yielded by the `Generator`. * * In the async case, `f` may also return `Promise`. * * @param f * @param thisArg supplied as 'this' for each invocation of `f`. * @param gen the [[Genable]] whose yielded values we are mapping over. * @typeParam T the type of value produced by the generator. * @typeParam V the type of value yielded by the resulting generator. */ map(f: IndexedFn, thisArg: any, gen: Genable): Enhanced; /** * Return a functionthat filters a [[Genable]] and yields a new [[EnhancedGenerator]] * that yields only the values that satisfy the predicate _f_. * * f receives the value and a sequential index. * @param f * @typeParam T the type of value. */ filter(f: IndexedPredicate): GenOpValue; /** * Return a functionthat filters a [[Genable]] and yields a new [[EnhancedGenerator]] * that yields only the values that satisfy the predicate _f_. * * f receives the value and a sequential index. * @param f * @param thisArg Optional context to be passed as `this` to the predicate. * @typeParam T the type of value. */ filter(f: IndexedPredicate, thisArg: any): GenOpValue; /** * Return a new [[EnhancedGenerator]] that yields only the values that satisfy the predicate _f_. * * f receives the value and a sequential index. * @param f * @param iter a [[Genable|Genable]] * @typeParam T the type of value. */ filter(f: IndexedPredicate, iter: Genable): Enhanced; /** * Return a new [[EnhancedGenerator]] that yields only the values that satisfy the predicate _f_. * * f receives the value and a sequential index. * @param f * @param thisArg Optional context to be passed as `this` to the predicate. * @param iter a [[Genable|Genable]] * @typeParam T the type of value. */ filter(f: IndexedPredicate, thisArg: any, iter: Genable): Enhanced; filter(f: IndexedPredicate, thisArg?: any, iter?: Genable): Enhanced; /** * Flatten the values yielded by the generator to level _depth_. Produces a generator that yields * the individual values at each level in depth-first order. Any iterable (including Array) or iterator * will be traversed and its values yielded. * * The return type is currently over-broad * @param depth */ flat(depth: D): (gen: Genable) => Enhanced, S, TReturn, TNext>; /** * Flatten the values yielded by the generator to level _depth_. Produces a generator that yields * the individual values at each level in depth-first order. Any iterable (including Array) or iterator * will be traversed and its values yielded. * * The return type is currently over-broad * @param depth * @param gen */ flat(depth: D, gen: Genable): Enhanced, S, TReturn, TNext>; /** * Flatten the values yielded by the generator to level _depth_. Produces a generator that yields * the individual values at each level in depth-first order. Any iterable (including Array) or iterator * will be traversed and its values yielded. * * The return type is currently over-broad * @param gen * @param depth default = 1 */ flat(gen: Genable, depth?: D): Enhanced, S, TReturn, TNext>; flat(depth: D | Genable, gen?: Genable | D): Enhanced, S, TReturn, TNext> | ((gen: Genable) => Enhanced, S, XReturn, XNext>) | ((gen: Genable, thisObj: any) => Enhanced, S, XReturn, XNext>); /** * Flatten the values yielded by applying the function to the values yielded by the generator to level _depth_. * Produces a function that accepts a generator, and returns another generator that yields the individual value * at each level in depth-first order. Any iterable * (including Array) or iterator will be traversed and its values yielded. * * The return type is currently over-broad * @param f * @param depth */ flatMap, T>(f: IndexedFn, depth: D): (gen: Genable) => Enhanced; /** * Flatten the values yielded by applying the function to the values yielded by the generator to level _depth_. * Produces a function that accepts a generator, and returns another generator that yields the individual value * at each level in depth-first order. Any iterable * (including Array) or iterator will be traversed and its values yielded. * * The return type is currently over-broad * @param f */ flatMap, T>(f: IndexedFn): (gen: Genable, depth?: D) => Enhanced; /** * Flatten the values yielded by applying the function to the values yielded by the generator to level _depth_. * Produces a generator that yields the individual values at each level in depth-first order. Any iterable * (including Array) or iterator will be traversed and its values yielded. * * The return type is currently over-broad * @param f * @param gen */ flatMap, T, TReturn, TNext>(f: IndexedFn, gen: Genable): Enhanced; /** * Flatten the values yielded by applying the function to the values yielded by the generator to level _depth_. * Produces a generator that yields the individual values at each level in depth-first order. Any iterable * (including Array) or iterator will be traversed and its values yielded. * * The return type is currently over-broad * @param f * @param depth * @param gen */ flatMap, T, TReturn, TNext>(f: IndexedFn, depth: D, gen: Genable): Enhanced, S, TReturn, TNext>; flatMap, T, TReturn, TNext>(f: IndexedFn, depthOrGen?: D | Genable, gen?: Genable): Enhanced, S, TReturn, TNext> | (, XReturn, XNext>(gen: Genable) => Enhanced) | (, XReturn, XNext>(gen: Genable, depth?: D) => Enhanced); /** * Return a new [[EnhancedGenerator]] that only yields the indicated values, skipping _start_ initial values * and continuing until the _end_. * @param start * @param end */ slice(start: number, end: number): (iter: Genable) => Enhanced; /** * Return a new [[EnhancedGenerator]] that only yields the indicated values, skipping _start_ initial values * and continuing until the _end_. * @param start * @param end * @param iter */ slice(start: number, end: number, iter: Genable): Enhanced; slice(start: number, end: number, iter?: Genable): Enhanced | ((gen: Genable) => Enhanced); /** * Concatenates generators (or iterators or iterables). * * Ensures that any supplied generators are terminated when this is terminated. * @param gens zero or more additional [[Genable]] to provide values. */ concat(...gens: Genable[]): Enhanced; /** * Reduces **gen** like `Array.prototype.reduce`, but the 3rd argument to the reducing function ("array") * is omitted because there is no array. * @param f * @param gen */ reduce(f: Reducer, gen: Genable): ReturnValue; /** * * Returns a reducer function that, when applied to a `Generator` **gen**, reduces **gen** like * **Array.prototype.reduce**. The 3rd argument to the reducing function ("array") * is omitted because there is no array. * * @param f */ reduce(f: Reducer): (gen: Genable) => ReturnValue; /** * * Returns a reducer function that, when applied to a `Generator` **gen**, reduces **gen** like * `Array.prototype.reduce`. The 3rd argument to the reducing function ("array") * is omitted because there is no array. * * @param f */ reduce(f: Reducer): (init: A, gen: Genable) => ReturnValue; /** * Reduces **gen** like `Array.prototype.reduce`, but the 3rd argument to the reducing function ("array") * is omitted because there is no array. * @param f * @param init * @param gen */ reduce(f: Reducer, init: A, gen: Genable): ReturnValue; /** * Returns a reducer function that, when applied to a `Generator` **gen**, reduces **gen** like * `Array.prototype.reduce`. The 3rd argument to the reducing function ("array") * is omitted because there is no array. * * Alternatively, the init value can be supplied along with the generator as a second argument. * @param f * @param init */ reduce(f: Reducer, init: A): (gen: Genable) => ReturnValue; reduce(f: Reducer, initOrGen?: Value | Genable, gen?: Genable): Value | ((gen: Genable) => Value) | ((f: (acc: A, v: T) => Value, init: A) => Value) | ((f: (acc: A | T, v: T) => Value) => Value); /** * Returns `true` and terminates the generator if the predicate is true for any of the generator's * yielded values. * * If the generator terminates without having satisfied the predicate, `false` is returned. * @param p predicate to apply to each yielded value. * @param thisArg Optional value to supply as context (`this`) for the predicate */ some(p: IndexedPredicate, thisArg?: any): (gen: Genable) => ReturnValue; /** * Returns `true` and terminates the generator if the predicate is true for any of the generator's * yielded values. * * If the generator terminates without having satisfied the predicate, `false` is returned. * @param p predicate to apply to each yielded value. */ some(p: IndexedPredicate): (gen: Genable, thisArg?: any) => ReturnValue; /** * Returns `true` and terminates the generator if the predicate is true for any of the generator's * yielded values. * * If the generator terminates without having satisfied the predicate, `false` is returned. * @param p predicate to apply to each yielded value. * @param gen the generator */ some(p: IndexedPredicate, gen: Genable): ReturnValue; /** * Returns `true` and terminates the generator if the predicate is true for any of the generator's * yielded values. * * If the generator terminates without having satisfied the predicate, `false` is returned. * @param p predicate to apply to each yielded value. * @param thisArg Optional value to supply as context (`this`) for the predicate * @param gen the generator */ some(p: IndexedPredicate, thisArg: any, gen: Genable): ReturnValue; some(pred: IndexedPredicate, thisOrGen?: any | Genable, gen?: Genable): ReturnValue | ((gen: Genable) => ReturnValue); /** * Returns `false` and terminates the generator if the predicate is false for any of the generator's * yielded values. * * If the generator terminates without having failed the predicate, `true` is returned. * @param p predicate to apply to each yielded value. * @param thisArg Optional value to supply as context (`this`) for the predicate */ every(p: IndexedPredicate, thisArg?: any): (gen: Genable) => ReturnValue; /** * Returns `false` and terminates this generator if the predicate is false for any of the generator's * yielded values. * * If the generator terminates without having failed the predicate, `true` is returned. * @param p predicate to apply to each yielded value. */ every(p: IndexedPredicate): (gen: Genable, thisArg?: any) => ReturnValue; /** * Returns `false` and terminates this generator if the predicate is false for any of the generator's * yielded values. * * If the generator terminates without having failed the predicate, `true` is returned. * @param p predicate to apply to each yielded value. * @param gen the generator */ every(p: IndexedPredicate, gen: Genable): ReturnValue; /** * Returns `false` and terminates this generator if the predicate is false for any of the generator's * yielded values. * * If the generator terminates without having failed the predicate, `true` is returned. * @param p predicate to apply to each yielded value. * @param thisArg Optional value to supply as context (`this`) for the predicate * @param gen the generator */ every(p: IndexedPredicate, thisArg: any, gen: Genable): ReturnValue; every(pred: IndexedPredicate, genOrThis?: any | Genable, gen?: Genable): ReturnValue | ((gen: Genable) => ReturnValue); /** * Returns a new generator that repeatedly yields the last value returned by **gen** (or returns `undefined` if **gen** * did not return any values). * * @param gen * @param max */ repeatLast(gen: Genable, max: number): Enhanced; /** * Returns a new generator that repeats the supplied value. * * @param value the value to repeat * @param repetitions The number repetitions; the default is infinite. */ repeat(value: T, repetitions: number): Enhanced; /** * Combines generators, returning a generator that produces a tuple with each of their results. * * Terminates when the first generator terminates. To get other behaviors, use with [[EnhancedGenerator.repeat]] or * [[EnhancedGenerator.repeatLast]]. * @param gens */ zip(...gens: Array>): Enhanced, S, TReturn, TNext>; /** * Returns a function that joins the elements produced by a [[Genable]], analogous to `Array.prototype.join`. * @param sep (default = ',') */ join(sep: string): (gen: Genable) => ReturnValue; /** * Joins the elements produced by a [[Genable]], analogous to `Array.prototype.join`. * @param gen * @param sep */ join(gen: Genable, sep?: string): ReturnValue; join(genOrSeparator: Genable | string, sep?: string): ReturnValue | ((gen: Genable) => ReturnValue); /** * Returns a new generator that returns values from each of the supplied sources as they are available. * For [[Sync]] generators, these will be taken in round-robin fashion from each non-terminated * generator, until all have terminated. For [[Async]] generators, they will be taken as they become * available. The yielded values will not be distinguished by which which source they are taken; for * that, another method will be supplied. * * Any calls to `Generator.throw()` or `Generator.return()` will be passed to all non-terminated * sources. * @param sources */ merge(...sources: Array>): Enhanced; /** * Returns a function that sorts the supplied sources and returns a sorted array. * @param cmp a comparison function */ sort(cmp?: (a: T, b: T) => number): (...sources: Array>) => ReturnValue; /** * Enhance a `Generator` with our enhanced methods. * @param gen */ enhance(gen: Genable): Enhanced; } /** * An enhanced `Generator` * @typeParam T The value type yielded by the `Generator`. * @typeParam S Selects for Sync or Async operation. */ export type Enhanced = { sync: EnhancedGenerator; async: EnhancedAsyncGenerator; }[S]; /** * An operator that takes a [[Genable]], optionals, and returns an [[Enhanced]] * with a free type parameter T for the element type of the [[Genable]]. * * This is used for signatures that take some parameters * and return a function that is not constrained as to element type. * @typeParam S Selects for Sync or Async operation * @typeParam Optional An array of types with any additional arguments after the [[Genable]] */ export type GenOp = (gen: Genable, ...rest: Optional) => Enhanced; /** * An operator that takes a [[Genable]], optionals, and returns a relate type, * often an [[Enhanced]]. * @typeParam S Selects for Sync or Async operation * @typeParam T the element type of the [[Genable]] * @typeParam Optional an array of types with any additional arguments after the [[Genable]] * @typeParam R the return type; defaults to [[Enhanced|Enhanced\\]]. */ export type GenOpValue = (gen: Genable, ...rest: Optional) => Enhanced; export type GenIteratorReturnResult = { sync: IteratorReturnResult; async: Promise>; }[S]; export type GenIteratorYieldResult = { sync: IteratorYieldResult; async: Promise>; }[S]; export type GenIteratorResult = GenIteratorYieldResult | GenIteratorReturnResult; export type GenVoid = { sync: void; async: Promise; }[S]; export type UnwrapArray = T extends Array ? E : never; /** * @internal */ export type Constructor = abstract new (...args: P) => T; /** * Extract the value type being iterated over. _I_ can be an iterator type or an iterable type, synchronous or asynchronous. * @typeParam A type describing an iteration. */ export type IteratorValue = I extends Iterator ? T : I extends AsyncIterator ? T : I extends Iterable ? T : I extends AsyncIterable ? T : never; export {}; //# sourceMappingURL=types.d.ts.map