iterable-linq-utility 0.0.16 → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,847 @@
+/**
+ * Callback of `forEach`: a side effect run on each value. It returns `unit()` because it has nothing to return.
+ * @param value - the current value
+ * @param index - the position of `value` in the chain, starting from 0
+ * @since 0.0.13
+ */
+export declare type Action<T> = (value: T, index: number) => Unit;
+
+/**
+ * Callback of `forEachAsync`: an async side effect run on each value.
+ * @param value - the current value
+ * @param index - the position of `value` in the chain, starting from 0
+ * @returns a promise of `unit()`; a rejection stops `forEachAsync`
+ * @since 0.0.13
+ */
+export declare type AsyncAction<T> = (value: T, index: number) => Promise<Unit>;
+
+/**
+ * Implementation of a method added with `extend` or `override`. `this` is the chain the method is called on.
+ * @since 0.1.0
+ */
+export declare type ChainMethod = (this: IIterableLinq<unknown>, ...args: any[]) => unknown;
+
+/**
+ * Collects the values of `iterable` into an `Array`.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @returns the values, in order; an empty array when `iterable` is empty
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Functions.collectToArray(new Set([1, 2, 3])); // [1, 2, 3]
+ * ```
+ * @since 0.0.10
+ */
+declare function collectToArray<T>(iterable: Iterable<T>): T[];
+
+/**
+ * How `min` and `max` compare two values. One of:
+ * - a compare function `(a, b) => number`: negative if `a` comes before `b`, 0 if they are equal, positive if `a` comes after `b`;
+ * - a key: the values are compared by that property, with `<`;
+ * - a list of keys: the values are compared by the first key, ties are broken by the next one, and so on.
+ * @example
+ * ```ts
+ * IterableLinq.from(people).max((a, b) => a.age - b.age);
+ * IterableLinq.from(people).max('age');
+ * IterableLinq.from(people).min(['lastName', 'firstName']);
+ * ```
+ * @since 0.0.13
+ */
+export declare type Comparer<T> = ComparerFunction<T> | ComparingProps<T>;
+
+declare type ComparerFunction<T> = (a: T, b: T) => number;
+
+declare type ComparingProps<T> = keyof T | Array<keyof T>;
+
+/**
+ * Starts a chain with no values.
+ * @returns an empty chain
+ * @example
+ * ```ts
+ * IterableLinq.empty<number>().collectToArray(); // []
+ * ```
+ * @since 0.0.10
+ */
+export declare function empty<T>(): IIterableLinq<T>;
+
+/**
+ * Returns an `Iterable` with no values.
+ * @operation `Transformation`
+ * @returns an empty, re-runnable `Iterable`
+ * @example
+ * ```ts
+ * Array.from(Functions.empty<number>()); // []
+ * ```
+ * @since 0.0.10
+ */
+declare function empty_2<T>(): Iterable<T>;
+
+/**
+ * Adds a method to every chain, including the chains created before the call.
+ * Declare the method first by augmenting `IIterableLinq`, then register it once, at application start-up.
+ * @param name - the method name; it must not exist yet (library methods, earlier extensions, `Object.prototype` members)
+ * @param implementation - the method; `this` is the chain, typed `IIterableLinq<unknown>`
+ * @throws Error if `name` already exists (use `override` to replace it), is empty, or `implementation` is not a function
+ * @example
+ * ```ts
+ * declare module 'iterable-linq-utility' {
+ * 	interface IIterableLinq<T> { chunk(size: number): IIterableLinq<T[]>; }
+ * }
+ * extend('chunk', function (size: number) {
+ * 	// `this` is the chain the method is called on; chunks() is your generator function
+ * 	return IterableLinq.from({ [Symbol.iterator]: () => chunks(this, size) });
+ * });
+ * IterableLinq.from([1, 2, 3]).chunk(2).collectToArray(); // [[1, 2], [3]]
+ * ```
+ * @since 0.1.0
+ */
+export declare function extend<K extends Extract<keyof IIterableLinq<unknown>, string>>(name: K, implementation: ChainMethod): void;
+
+/**
+ * Lazily keeps only the values that satisfy `predicate`.
+ * If `predicate` throws, the source is closed and the error propagates.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param predicate - called with each value and its index; return `true` to keep the value
+ * @returns a lazy, re-runnable `Iterable` of the kept values
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * Array.from(Functions.filter([1, 2, 3, 4], v => v % 2 === 0)); // [2, 4]
+ * ```
+ * @since 0.0.10
+ */
+declare function filter<T>(iterable: Iterable<T>, predicate: Predicate<T>): Iterable<T>;
+
+/**
+ * Lazily maps each value to an `Iterable` and flattens the results.
+ * Each inner `Iterable` is read completely before the next value is mapped.
+ * Inner arrays are read by index, as in `Array.prototype.flatMap`: their `[Symbol.iterator]` is not called.
+ * If `mapper` or an inner `Iterable` throws, the source is closed and the error propagates.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param mapper - called with each value and its index; returns the `Iterable` to flatten
+ * @returns a lazy, re-runnable `Iterable` of the flattened values
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `mapper` is not a function
+ * @example
+ * ```ts
+ * Array.from(Functions.flatMap([1, 2], v => [v, v * 10])); // [1, 10, 2, 20]
+ * ```
+ * @since 0.0.11
+ */
+declare function flatMap<T, R>(iterable: Iterable<T>, mapper: Mapper<T, Iterable<R>>): Iterable<R>;
+
+/**
+ * Calls `action` on each value of `iterable`. If `action` throws, the source is closed and the error propagates.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param action - called with each value and its index; returns `unit()`
+ * @returns `unit()`
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `action` is not a function
+ * @example
+ * ```ts
+ * Functions.forEach([1, 2], v => {
+ * 	console.log(v); // 1, 2
+ * 	return unit();
+ * });
+ * ```
+ * @since 0.0.11
+ */
+declare function forEach<T>(iterable: Iterable<T>, action: Action<T>): Unit;
+
+/**
+ * Calls the async `action` on each value of `iterable`, sequentially: each action starts after the previous one has settled.
+ * The first rejection stops the iteration and closes the source. Works on infinite sources.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param action - called with each value and its index; returns a promise of `unit()`
+ * @returns a promise resolved with `unit()` after the last action, or rejected with the first error
+ * @throws Error, as a rejection of the returned promise, if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `action` is not a function
+ * @example
+ * ```ts
+ * await Functions.forEachAsync(['a.txt', 'b.txt'], async file => {
+ * 	await upload(file); // 'b.txt' starts after 'a.txt' has finished
+ * 	return unit();
+ * });
+ * ```
+ * @since 0.0.11
+ */
+declare function forEachAsync<T>(iterable: Iterable<T>, action: AsyncAction<T>): Promise<Unit>;
+
+/**
+ * Starts a chain over any `Iterable` (array, string, Set, Map, generator…). The source is not copied.
+ * @param iterable - the source of the chain
+ * @returns a chain over `iterable`; each run of the chain iterates `iterable` again
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * IterableLinq.from([1, 2, 3]).map(v => v * 2).collectToArray(); // [2, 4, 6]
+ * IterableLinq.from('abc').collectToArray(); // ['a', 'b', 'c']
+ * ```
+ * @since 0.0.1
+ */
+export declare function from<T>(iterable: Iterable<T>): IIterableLinq<T>;
+
+/**
+ * Starts a chain of numbers from 0 up to, but not including, `end`.
+ * - `options.step` is the distance between two values (default 1); its sign is ignored, the direction comes from the sign of `end`.
+ * - `options.reverse` yields the same numbers in reverse order.
+ * - Values are computed as `index * step`, so decimal steps do not accumulate rounding errors.
+ * - A `NaN` bound gives an empty chain.
+ * @param end - the bound, not included
+ * @param options - `step` and `reverse`
+ * @returns a chain of numbers
+ * @throws Error if `options` is not an object, or if `step` is 0, `NaN` or infinite
+ * @example
+ * ```ts
+ * IterableLinq.fromRange(3).collectToArray();                       // [0, 1, 2]
+ * IterableLinq.fromRange(3, { reverse: true }).collectToArray();    // [2, 1, 0]
+ * IterableLinq.fromRange(-3).collectToArray();                      // [0, -1, -2]
+ * ```
+ * @since 0.0.10
+ */
+export declare function fromRange(end: number, options?: IRangeOptions): IIterableLinq<number>;
+
+/**
+ * Starts a chain of numbers from `start` up to, but not including, `end`.
+ * - `options.step` is the distance between two values (default 1); its sign is ignored, the direction comes from `start` and `end`.
+ * - `options.reverse` yields the same numbers in reverse order.
+ * - Values are computed as `start + index * step`, so decimal steps do not accumulate rounding errors.
+ * - A `NaN` bound gives an empty chain.
+ * @param start - the first value
+ * @param end - the bound, not included
+ * @param options - `step` and `reverse`
+ * @returns a chain of numbers
+ * @throws Error if `options` is not an object, or if `step` is 0, `NaN` or infinite
+ * @example
+ * ```ts
+ * IterableLinq.fromRange(1, 7, { step: 2 }).collectToArray();       // [1, 3, 5]
+ * IterableLinq.fromRange(5, 0).collectToArray();                    // [5, 4, 3, 2, 1]
+ * IterableLinq.fromRange(0, 1, { step: 0.25 }).collectToArray();    // [0, 0.25, 0.5, 0.75]
+ * ```
+ * @since 0.0.10
+ */
+export declare function fromRange(start: number, end: number, options?: IRangeOptions): IIterableLinq<number>;
+
+declare namespace Functions {
+    export {
+        collectToArray,
+        empty_2 as empty,
+        filter,
+        flatMap,
+        forEach,
+        forEachAsync,
+        map,
+        materialize,
+        max,
+        memoize,
+        getMemoizeDefaultOptions,
+        min,
+        range,
+        reduce,
+        repeat_2 as repeat,
+        some,
+        tap,
+        tapChain
+    }
+}
+export { Functions }
+
+/**
+ * Returns the options `memoize` uses when none are given.
+ * @returns a new object: `{ allowPartialMemoization: true }`
+ * @since 0.0.16
+ */
+declare function getMemoizeDefaultOptions(): IMemoizeOptions;
+
+/**
+ * Fluent wrapper over an `Iterable`: every call builds a lazy, re-runnable operations chain.
+ * Transformations and taps return a new `IIterableLinq`; actions run the chain and return a result.
+ * Create chains with `from`, `fromRange`, `repeat` and `empty`; recognise them with `isIterableLinq`.
+ *
+ * Augment this interface (not `IIterableLinqBase`) to declare the methods you add with `extend`.
+ * @since 0.0.10
+ */
+export declare interface IIterableLinq<T> extends IIterableLinqBase<T> {
+}
+
+/**
+ * The operations provided by the library on every chain. See `IIterableLinq`.
+ * @since 0.1.0
+ */
+export declare interface IIterableLinqBase<T> {
+    /**
+     * Starts a new run of the chain. Each call iterates the source again, so a chain can be consumed many times.
+     * @returns a new iterator over the values of the chain
+     * @example
+     * ```ts
+     * const chain = IterableLinq.from([1, 2, 3]).map(v => v * 10);
+     * [...chain]; // [10, 20, 30]
+     * for (const value of chain) console.log(value); // 10, 20, 30
+     * ```
+     * @since 0.0.1
+     */
+    [Symbol.iterator](): Iterator<T, any, undefined>;
+    /**
+     * Runs the chain and collects its values into an `Array`.
+     * @operation `Action`
+     * @returns the values of the chain, in order; an empty array when the chain is empty
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).map(v => v * 10).collectToArray(); // [10, 20, 30]
+     * ```
+     * @since 0.0.1
+     */
+    collectToArray(): T[];
+    /**
+     * Keeps only the values that satisfy `predicate`.
+     * If `predicate` throws, the source is closed and the error propagates.
+     * @operation `Transformation`
+     * @param predicate - called with each value and its index; return `true` to keep the value
+     * @returns a new chain with the kept values
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 4]).filter(v => v % 2 === 0).collectToArray(); // [2, 4]
+     * ```
+     * @since 0.0.1
+     */
+    filter(predicate: Predicate<T>): IIterableLinq<T>;
+    /**
+     * Maps each value to an `Iterable` and flattens the results into one chain.
+     * Each inner `Iterable` is read completely before the next value of the chain is mapped.
+     * Inner arrays are read by index, as in `Array.prototype.flatMap`: their `[Symbol.iterator]` is not called.
+     * If `mapper` or an inner `Iterable` throws, the source is closed and the error propagates.
+     * @operation `Transformation`
+     * @param mapper - called with each value and its index; returns the `Iterable` to flatten
+     * @returns a new chain with the flattened values
+     * @throws Error if `mapper` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2]).flatMap(v => [v, v * 10]).collectToArray(); // [1, 10, 2, 20]
+     * ```
+     * @since 0.0.11
+     */
+    flatMap<R>(mapper: Mapper<T, Iterable<R>>): IIterableLinq<R>;
+    /**
+     * Runs the chain and calls `action` on each value.
+     * If `action` throws, the source is closed and the error propagates.
+     * @operation `Action`
+     * @param action - called with each value and its index; returns `unit()`
+     * @returns `unit()`
+     * @throws Error if `action` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2]).forEach(v => {
+     * 	console.log(v); // 1, 2
+     * 	return unit();
+     * });
+     * ```
+     * @since 0.0.11
+     */
+    forEach(action: Action<T>): Unit;
+    /**
+     * Runs the chain and calls the async `action` on each value.
+     * The actions run sequentially: each one starts after the previous one has settled.
+     * The first rejection stops the iteration and closes the source. Works on infinite sources.
+     * @operation `Action`
+     * @param action - called with each value and its index; returns a promise of `unit()`
+     * @returns a promise resolved with `unit()` after the last action, or rejected with the first error
+     * @throws Error, as a rejection of the returned promise, if `action` is not a function
+     * @example
+     * ```ts
+     * await IterableLinq.from(['a.txt', 'b.txt']).forEachAsync(async file => {
+     * 	await upload(file); // 'b.txt' starts after 'a.txt' has finished
+     * 	return unit();
+     * });
+     * ```
+     * @since 0.0.11
+     */
+    forEachAsync(action: AsyncAction<T>): Promise<Unit>;
+    /**
+     * Transforms each value with `mapper`.
+     * If `mapper` throws, the source is closed and the error propagates.
+     * @operation `Transformation`
+     * @param mapper - called with each value and its index; returns the new value
+     * @returns a new chain with the mapped values
+     * @throws Error if `mapper` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 4]).map(v => v * 10).collectToArray(); // [10, 20, 30, 40]
+     * ```
+     * @since 0.0.1
+     */
+    map<R>(mapper: Mapper<T, R>): IIterableLinq<R>;
+    /**
+     * Runs the chain immediately and stores its values, so later chains start from the stored values
+     * instead of running the source again. Materializing a materialized chain does not copy the values again.
+     * @operation `Action`
+     * @returns a new chain over the stored values
+     * @example
+     * ```ts
+     * const stored = IterableLinq.fromRange(1_000_000).filter(isPrime).materialize(); // runs now
+     * stored.max(); // reads the stored values, does not run filter again
+     * ```
+     * @since 0.0.1
+     */
+    materialize(): IIterableLinq<T>;
+    /**
+     * Runs the chain and returns its greatest value. Among equal values the first one wins;
+     * `null` and `undefined` never win against a defined value.
+     * @operation `Action`
+     * @param comparer - a compare function, a key, or a list of keys to compare by; defaults to `<`
+     * @returns the greatest value, or `undefined` when the chain is empty
+     * @example
+     * ```ts
+     * IterableLinq.from([3, 1, 2]).max(); // 3
+     * IterableLinq.from([{ v: 1 }, { v: 3 }]).max('v'); // { v: 3 }
+     * IterableLinq.empty<number>().max(); // undefined
+     * ```
+     * @since 0.0.1
+     */
+    max(comparer?: Comparer<T>): T | undefined;
+    /**
+     * Caches the values the first time they are read, so later runs do not run the chain again.
+     * With partial memoization (the default) the cache fills as far as consumers read;
+     * a consumer that stops early keeps the source open until another consumer finishes it.
+     * If the source throws, every later read past the cached values throws the same error.
+     * @operation `Transformation`
+     * @param options - `allowPartialMemoization: false` reads the whole source on the first read
+     * @returns a new chain backed by the cache
+     * @example
+     * ```ts
+     * const cached = IterableLinq.from(readLines()).map(parse).memoize();
+     * cached.collectToArray(); // reads and parses the lines
+     * cached.collectToArray(); // same values, from the cache
+     * ```
+     * @since 0.0.1
+     */
+    memoize(options?: IMemoizeOptions): IIterableLinq<T>;
+    /**
+     * Runs the chain and returns its smallest value. Among equal values the first one wins;
+     * `null` and `undefined` never win against a defined value.
+     * @operation `Action`
+     * @param comparer - a compare function, a key, or a list of keys to compare by; defaults to `<`
+     * @returns the smallest value, or `undefined` when the chain is empty
+     * @example
+     * ```ts
+     * IterableLinq.from([3, 1, 2]).min(); // 1
+     * IterableLinq.from([{ v: 1 }, { v: 3 }]).min('v'); // { v: 1 }
+     * IterableLinq.empty<number>().min(); // undefined
+     * ```
+     * @since 0.0.8
+     */
+    min(comparer?: Comparer<T>): T | undefined;
+    /**
+     * Runs the chain and accumulates its values into a single result.
+     * @operation `Action`
+     * @param neutralElement - the initial accumulator (the seed)
+     * @param reducer - called with the accumulator, each value and its index; returns the new accumulator
+     * @returns the final accumulator; `neutralElement` when the chain is empty
+     * @throws Error if `reducer` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).reduce(0, (acc, v) => acc + v); // 6
+     * ```
+     * @since 0.0.10
+     */
+    reduce<R>(neutralElement: R, reducer: Reducer<T, R>): R;
+    /**
+     * Runs the chain until a value satisfies `predicate`, then stops and closes the source.
+     * @operation `Action`
+     * @param predicate - called with each value and its index
+     * @returns `true` if at least one value satisfies `predicate`; `false` when the chain is empty
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).some(v => v > 2); // true
+     * ```
+     * @since 0.0.1
+     */
+    some(predicate: Predicate<T>): boolean;
+    /**
+     * Calls `tapper` on each value as it flows through the chain, without changing it.
+     * If `tapper` throws, the source is closed and the error propagates.
+     * `tapper` runs only when the chain runs, once per value and per run.
+     * @operation `Tap`
+     * @param tapper - called with each value and its index; returns `unit()`
+     * @returns a new chain with the same values
+     * @throws Error if `tapper` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2])
+     * 	.tap(v => { console.log('read', v); return unit(); })
+     * 	.map(v => v * 10)
+     * 	.collectToArray(); // logs "read 1", "read 2"; returns [10, 20]
+     * ```
+     * @since 0.0.10
+     */
+    tap(tapper: Tapper<T>): IIterableLinq<T>;
+    /**
+     * Calls `tapper` with the upstream `Iterable` each time the chain starts a run, before the first value is read.
+     * @operation `Tap`
+     * @param tapper - called with the upstream `Iterable` (the index is always 0); returns `unit()`
+     * @returns a new chain with the same values
+     * @throws Error if `tapper` is not a function
+     * @example
+     * ```ts
+     * const chain = IterableLinq.from([1, 2]).tapChain(() => { console.log('run'); return unit(); });
+     * chain.collectToArray(); // logs "run"
+     * chain.collectToArray(); // logs "run" again
+     * ```
+     * @since 0.0.10
+     */
+    tapChain(tapper: Tapper<Iterable<T>>): IIterableLinq<T>;
+    /**
+     * Calls `chainCreationTapper` immediately with this chain, while the chain is being built. Nothing runs.
+     * @operation `Tap`
+     * @param chainCreationTapper - called once, now, with this chain; returns `unit()`
+     * @returns this same chain
+     * @throws Error if `chainCreationTapper` is not a function
+     * @example
+     * ```ts
+     * let evens: IIterableLinq<number> | undefined;
+     * IterableLinq.fromRange(10)
+     * 	.filter(v => v % 2 === 0)
+     * 	.tapChainCreation(chain => { evens = chain; return unit(); })
+     * 	.map(v => v * 10);
+     * evens?.collectToArray(); // [0, 2, 4, 6, 8]
+     * ```
+     * @since 0.0.10
+     */
+    tapChainCreation(chainCreationTapper: (chain: IIterableLinq<T>) => Unit): IIterableLinq<T>;
+}
+
+/**
+ * Options of `memoize`.
+ * @since 0.1.0
+ */
+export declare interface IMemoizeOptions {
+    /** `true` (default): the cache fills as far as consumers read. `false`: the first read drains the whole source. */
+    allowPartialMemoization?: boolean;
+}
+
+/**
+ * Options of `range`.
+ * @since 0.1.0
+ */
+export declare interface IRangeOptions {
+    /** Distance between two values; defaults to 1. Only its absolute value is used: the direction comes from `start` and `end`. */
+    step?: number;
+    /** Yields the same values in reverse order; defaults to `false`. */
+    reverse?: boolean;
+}
+
+/**
+ * Tells whether `value` is a chain created by this library.
+ * It checks a `Symbol.for` brand instead of `instanceof`, so it also works when two copies of the library are loaded.
+ * It is a brand check, not a validation: do not use it to decide whether untrusted input is safe to call.
+ * @param value - any value
+ * @returns `true` if `value` is an `IIterableLinq` chain
+ * @example
+ * ```ts
+ * isIterableLinq(IterableLinq.from([1, 2, 3])); // true
+ * isIterableLinq([1, 2, 3]); // false
+ * ```
+ * @since 0.1.0
+ */
+export declare function isIterableLinq(value: unknown): value is IIterableLinq<unknown>;
+
+/**
+ * Lazily transforms each value with `mapper`.
+ * If `mapper` throws, the source is closed and the error propagates.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param mapper - called with each value and its index; returns the new value
+ * @returns a lazy, re-runnable `Iterable` of the mapped values
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `mapper` is not a function
+ * @example
+ * ```ts
+ * Array.from(Functions.map([1, 2, 3], v => v * 10)); // [10, 20, 30]
+ * ```
+ * @since 0.0.10
+ */
+declare function map<T, R>(iterable: Iterable<T>, mapper: Mapper<T, R>): Iterable<R>;
+
+/**
+ * Callback of `map` and `flatMap`: turns a value into a new one.
+ * @param value - the current value
+ * @param index - the position of `value` in the chain, starting from 0
+ * @returns the new value
+ * @since 0.0.13
+ */
+export declare type Mapper<T, R> = (value: T, index: number) => R;
+
+/**
+ * Reads `iterable` immediately and stores its values.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @returns an `Iterable` over the stored values; a materialized input is returned as is
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * const stored = Functions.materialize(Functions.map([1, 2, 3], v => v * 10)); // runs now
+ * Array.from(stored); // [10, 20, 30], read from the stored values
+ * ```
+ * @since 0.0.10
+ */
+declare function materialize<T>(iterable: Iterable<T>): Iterable<T>;
+
+/**
+ * Returns the greatest value; the first one among equals. `null`/`undefined` never win against a defined value.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param comparer - a compare function, a key, or a list of keys; defaults to `<`
+ * @returns the greatest value, or `undefined` when `iterable` is empty
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Functions.max([3, 1, 2]); // 3
+ * Functions.max([{ v: 1 }, { v: 3 }], 'v'); // { v: 3 }
+ * ```
+ * @since 0.0.10
+ */
+declare function max<T>(iterable: Iterable<T>, comparer?: Comparer<T>): T | undefined;
+
+/**
+ * Caches the values of `iterable` the first time they are read, so later iterations do not run the source again.
+ * With partial memoization, a consumer that stops early keeps the shared source open until another consumer finishes it.
+ * If the source throws, every later read past the cached values throws the same error.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param options - `allowPartialMemoization: false` reads the whole source on the first read
+ * @returns a lazy `Iterable` backed by the cache
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * const cached = Functions.memoize(Functions.map(readLines(), parse));
+ * Array.from(cached); // reads and parses the lines
+ * Array.from(cached); // same values, from the cache
+ * ```
+ * @since 0.0.10
+ */
+declare function memoize<T>(iterable: Iterable<T>, options?: IMemoizeOptions): Iterable<T>;
+
+/**
+ * Returns the smallest value; the first one among equals. `null`/`undefined` never win against a defined value.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param comparer - a compare function, a key, or a list of keys; defaults to `<`
+ * @returns the smallest value, or `undefined` when `iterable` is empty
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Functions.min([3, 1, 2]); // 1
+ * Functions.min([{ v: 1 }, { v: 3 }], 'v'); // { v: 1 }
+ * ```
+ * @since 0.0.10
+ */
+declare function min<T>(iterable: Iterable<T>, comparer?: Comparer<T>): T | undefined;
+
+/**
+ * Replaces an existing method of every chain: a library method or one added with `extend`.
+ * Typical use: a library release adds a method with the same name as one of your extensions,
+ * so `extend` throws at start-up; switch that call to `override` to keep your version.
+ * Only the fluent method changes: `Functions` and the library internals keep the original behaviour.
+ * @param name - an existing chain method; `constructor` and `Object.prototype` members are rejected
+ * @param implementation - the new method; `this` is the chain, typed `IIterableLinq<unknown>`
+ * @throws Error if `name` is not a chain method (use `extend` to add it), is empty, or `implementation` is not a function
+ * @example
+ * ```ts
+ * // a library release added its own `chunk`: keep your version
+ * override('chunk', function (size: number) {
+ * 	return IterableLinq.from({ [Symbol.iterator]: () => chunks(this, size) });
+ * });
+ * ```
+ * @since 0.1.0
+ */
+export declare function override<K extends Extract<keyof IIterableLinq<unknown>, string>>(name: K, implementation: ChainMethod): void;
+
+/**
+ * Callback of `filter` and `some`: tests a value.
+ * @param value - the current value
+ * @param index - the position of `value` in the chain, starting from 0
+ * @returns `true` if `value` satisfies the condition
+ * @since 0.0.13
+ */
+export declare type Predicate<T> = (value: T, index: number) => boolean;
+
+/**
+ * Returns the numbers from 0 up to, but not including, `end`, computed as `index * step`.
+ * The direction follows the sign of `end`; `reverse` yields the same numbers backwards; a `NaN` bound gives an empty `Iterable`.
+ * @operation `Transformation`
+ * @param end - the bound, not included
+ * @param options - `step` (default 1, sign ignored) and `reverse` (default `false`)
+ * @returns a lazy, re-runnable `Iterable` of numbers
+ * @throws Error if `options` is not an object, or if `step` is 0, `NaN` or infinite
+ * @example
+ * ```ts
+ * Array.from(Functions.range(3)); // [0, 1, 2]
+ * Array.from(Functions.range(3, { reverse: true })); // [2, 1, 0]
+ * ```
+ * @since 0.0.10
+ */
+declare function range(end: number, options?: IRangeOptions): Iterable<number>;
+
+/**
+ * Returns the numbers from `start` up to, but not including, `end`, computed as `start + index * step`.
+ * The direction follows `start` and `end`; `reverse` yields the same numbers backwards; a `NaN` bound gives an empty `Iterable`.
+ * @operation `Transformation`
+ * @param start - the first value
+ * @param end - the bound, not included
+ * @param options - `step` (default 1, sign ignored) and `reverse` (default `false`)
+ * @returns a lazy, re-runnable `Iterable` of numbers
+ * @throws Error if `options` is not an object, or if `step` is 0, `NaN` or infinite
+ * @example
+ * ```ts
+ * Array.from(Functions.range(1, 7, { step: 2 })); // [1, 3, 5]
+ * Array.from(Functions.range(5, 0)); // [5, 4, 3, 2, 1]
+ * ```
+ * @since 0.0.10
+ */
+declare function range(start: number, end: number, options?: IRangeOptions): Iterable<number>;
+
+/**
+ * Accumulates the values of `iterable` into a single result.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param neutralElement - the initial accumulator (the seed)
+ * @param reducer - called with the accumulator, each value and its index; returns the new accumulator
+ * @returns the final accumulator; `neutralElement` when `iterable` is empty
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `reducer` is not a function
+ * @example
+ * ```ts
+ * Functions.reduce([1, 2, 3], 0, (acc, v) => acc + v); // 6
+ * ```
+ * @since 0.0.10
+ */
+declare function reduce<T, R>(iterable: Iterable<T>, neutralElement: R, reducer: Reducer<T, R>): R;
+
+/**
+ * Callback of `reduce`: combines the accumulator with a value.
+ * @param acc - the accumulator: the seed for the first value, then the result of the previous call
+ * @param value - the current value
+ * @param index - the position of `value` in the chain, starting from 0
+ * @returns the new accumulator
+ * @since 0.0.13
+ */
+export declare type Reducer<T, R> = (acc: R, value: T, index: number) => R;
+
+/**
+ * Starts a chain that yields `value` `count` times.
+ * @param value - the value to repeat
+ * @param count - how many times; must be a non-negative integer
+ * @returns a chain of `count` values
+ * @throws Error if `count` is negative, not an integer, `NaN` or `Infinity`
+ * @example
+ * ```ts
+ * IterableLinq.repeat(5, 3).collectToArray(); // [5, 5, 5]
+ * ```
+ * @since 0.0.10
+ */
+export declare function repeat<T>(value: T, count: number): IIterableLinq<T>;
+
+/**
+ * Returns an `Iterable` that yields `value` `count` times.
+ * @operation `Transformation`
+ * @param value - the value to repeat
+ * @param count - how many times; must be a non-negative integer
+ * @returns a lazy, re-runnable `Iterable`
+ * @throws Error if `count` is negative, not an integer, `NaN` or `Infinity`
+ * @example
+ * ```ts
+ * Array.from(Functions.repeat('a', 3)); // ['a', 'a', 'a']
+ * ```
+ * @since 0.0.10
+ */
+declare function repeat_2<T>(value: T, count: number): Iterable<T>;
+
+/**
+ * Tells whether at least one value satisfies `predicate`; stops and closes the source at the first match.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param predicate - called with each value and its index
+ * @returns `true` if a value satisfies `predicate`; `false` when `iterable` is empty
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * Functions.some([1, 2, 3], v => v > 2); // true
+ * ```
+ * @since 0.0.10
+ */
+declare function some<T>(iterable: Iterable<T>, predicate: Predicate<T>): boolean;
+
+/**
+ * Lazily calls `tapper` on each value as it flows through, without changing it.
+ * If `tapper` throws, the source is closed and the error propagates.
+ * @operation `Tap`
+ * @param iterable - the source `Iterable`
+ * @param tapper - called with each value and its index; returns `unit()`
+ * @returns a lazy, re-runnable `Iterable` of the same values
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `tapper` is not a function
+ * @example
+ * ```ts
+ * const logged = Functions.tap([1, 2], v => { console.log(v); return unit(); });
+ * Array.from(logged); // logs 1, 2; returns [1, 2]
+ * ```
+ * @since 0.0.10
+ */
+declare function tap<T>(iterable: Iterable<T>, tapper: Tapper<T>): Iterable<T>;
+
+/**
+ * Calls `tapper` with `iterable` each time a new iteration starts, before the first value is read.
+ * @operation `Tap`
+ * @param iterable - the source `Iterable`
+ * @param tapper - called with `iterable` (the index is always 0); returns `unit()`
+ * @returns a lazy, re-runnable `Iterable` of the same values
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `tapper` is not a function
+ * @example
+ * ```ts
+ * const tapped = Functions.tapChain([1, 2], () => { console.log('run'); return unit(); });
+ * Array.from(tapped); // logs "run"
+ * Array.from(tapped); // logs "run" again
+ * ```
+ * @since 0.0.10
+ */
+declare function tapChain<T>(iterable: Iterable<T>, tapper: Tapper<Iterable<T>>): Iterable<T>;
+
+/**
+ * Callback of `tap` and `tapChain`: observes a value without changing it.
+ * @param value - the current value (for `tapChain`, the upstream `Iterable`)
+ * @param index - the position of `value` in the chain, starting from 0 (for `tapChain`, always 0)
+ * @since 0.0.13
+ */
+export declare type Tapper<T> = (value: T, index: number) => Unit;
+
+/**
+ * The type with exactly one value, `unit()`: what an action or a tapper returns when it has nothing to return.
+ * It is nominal: no other value (numbers, strings, objects, `\{\}`) is assignable to `Unit`.
+ * @since 0.0.13
+ */
+export declare class Unit {
+    /**
+     * The only value of the type. The same frozen object as `unit()`.
+     * @since 0.1.0
+     */
+    static readonly instance: Unit;
+    private readonly unitBrand;
+    private constructor();
+    private static createFrozen;
+}
+
+/**
+ * Returns the only value of `Unit`. Return it from callbacks that have nothing to return.
+ * @returns `Unit.instance`
+ * @example
+ * ```ts
+ * IterableLinq.from([1, 2]).forEach(v => {
+ * 	console.log(v);
+ * 	return unit();
+ * });
+ * ```
+ * @since 0.0.13
+ */
+export declare function unit(): Unit;
+
+export { }