@rimbu/common 1.0.0 → 2.0.0

package/dist/types/reducer.d.mts

@@ -1,542 +0,0 @@
-import { CollectFun, Eq, OptLazy } from './internal.mjs';
-/**
- * A `Reducer` is a stand-alone calculation that takes input values of type I, and, when requested, produces an output value of type O.
- * @typeparam I - the input value type
- * @typeparam O - the output value type
- */
-export type Reducer<I, O = I> = Reducer.Impl<I, O, unknown>;
-export declare namespace Reducer {
-    /**
-     * The Implementation interface for a `Reducer`, which also exposes the internal state type.
-     * @typeparam I - the input value type
-     * @typeparam O - the output value type
-     * @typeparam S - the internal state type
-     */
-    interface Impl<I, O, S> {
-        /**
-         * The initial state value for the reducer algorithm.
-         */
-        readonly init: OptLazy<S>;
-        /**
-         * Returns the next state based on the given input values
-         * @param state - the current state
-         * @param elem - the current input value
-         * @param index - the current input index
-         * @param halt - a function that, when called, ensures no more values are passed to the reducer
-         */
-        next(state: S, elem: I, index: number, halt: () => void): S;
-        /**
-         * Returns the output value based on the given `state`
-         * @param state - the current state
-         */
-        stateToResult(state: S): O;
-        /**
-         * Returns a `Reducer` instance that only passes values to the reducer that satisy the given `pred` predicate.
-         * @param pred - a function that returns true if the value should be passed to the reducer based on the following inputs:<br/>
-         * - value: the current input value<br/>
-         * - index: the current input index<br/>
-         * - halt: function that, when called, ensures no more new values are passed to the reducer
-         * @example
-         * ```ts
-         * Reducer.sum.filterInput(v => v > 10)
-         * // this reducer will only sum values larger than 10
-         * ```
-         */
-        filterInput(pred: (value: I, index: number, halt: () => void) => boolean): Reducer<I, O>;
-        /**
-         * Returns a `Reducer` instance that converts its input values using given `mapFun` before passing them to the reducer.
-         * @typeparam I2 - the resulting reducer input type
-         * @param mapFun - a function that returns a new value to pass to the reducer based on the following inputs:<br/>
-         * - value: the current input value<br/>
-         * - index: the current input index
-         * @example
-         * ```ts
-         * Reducer.sum.mapInput(v => v * 2)
-         * // this reducer will double all input values before summing them
-         * ```
-         */
-        mapInput<I2>(mapFun: (value: I2, index: number) => I): Reducer<I2, O>;
-        /**
-         * Returns a `Reducer` instance that converts or filters its input values using given `collectFun` before passing them to the reducer.
-         * @typeparam I2 - the resulting reducer input type
-         * @param collectFun - a function receiving<br/>
-         * - `value`: the next value<br/>
-         * - `index`: the value index<br/>
-         * - `skip`: a token that, when returned, will not add a value to the resulting collection<br/>
-         * - `halt`: a function that, when called, ensures no next elements are passed
-         * @example
-         * ```ts
-         * Reducer.sum.collectInput((v, _, skip) => v <= 10 ? skip : v * 2)
-         * // this reducer will double all input values larger thant 10 before summing them,
-         * // and will skip all values smaller than 10
-         * ```
-         */
-        collectInput<I2>(collectFun: CollectFun<I2, I>): Reducer<I2, O>;
-        /**
-         * Returns a `Reducer` instance that converts its output values using given `mapFun`.
-         * @typeparam O2 - the resulting reducer output type
-         * @param mapFun - a function that takes the current output value and converts it to a new output value
-         * @example
-         * ```ts
-         * Reducer.sum.mapOutput(String)
-         * // this reducer will convert all its results to string before returning them
-         * ```
-         */
-        mapOutput<O2>(mapFun: (value: O) => O2): Reducer<I, O2>;
-        /**
-         * Returns a `Reducer` instance that takes at most the given `amount` of input elements, and will ignore subsequent elements.
-         * @param amount - the amount of elements to accept
-         * @example
-         * ```ts
-         * Stream.range({ end: 10 }).reduce(Reducer.sum.takeInput(2))
-         * // => 1
-         * ```
-         */
-        takeInput(amount: number): Reducer<I, O>;
-        /**
-         * Returns a `Reducer` instance that skips the first given `amount` of input elements, and will process subsequent elements.
-         * @param amount - the amount of elements to skip
-         * @example
-         * ```ts
-         * Stream.range({ end: 10 }).reduce(Reducer.sum.dropInput(9))
-         * // => 19
-         * ```
-         */
-        dropInput(amount: number): Reducer<I, O>;
-        /**
-         * Returns a `Reducer` instance that takes given `amount` of elements starting at given `from` index, and ignores other elements.
-         * @param from - (default: 0) the index at which to start processing elements
-         * @param amount - (optional) the amount of elements to process, if not given, processes all elements from the `from` index
-         * @example
-         * ```ts
-         * Stream.range({ end: 10 }).reduce(Reducer.sum.sliceInput(1, 2))
-         * // => 3
-         * ```
-         */
-        sliceInput(from?: number, amount?: number): Reducer<I, O>;
-    }
-    /**
-     * A base class that can be used to easily create `Reducer` instances.
-     * @typeparam I - the input value type
-     * @typeparam O - the output value type
-     * @typeparam S - the internal state type
-     */
-    class Base<I, O, S> implements Reducer.Impl<I, O, S> {
-        readonly init: OptLazy<S>;
-        readonly next: (state: S, elem: I, index: number, halt: () => void) => S;
-        readonly stateToResult: (state: S) => O;
-        constructor(init: OptLazy<S>, next: (state: S, elem: I, index: number, halt: () => void) => S, stateToResult: (state: S) => O);
-        filterInput(pred: (value: I, index: number, halt: () => void) => boolean): Reducer<I, O>;
-        mapInput<I2>(mapFun: (value: I2, index: number) => I): Reducer<I2, O>;
-        collectInput<I2>(collectFun: CollectFun<I2, I>): Reducer<I2, O>;
-        mapOutput<O2>(mapFun: (value: O) => O2): Reducer<I, O2>;
-        takeInput(amount: number): Reducer<I, O>;
-        dropInput(amount: number): Reducer<I, O>;
-        sliceInput(from?: number, amount?: number): Reducer<I, O>;
-    }
-    /**
-     * Returns a `Reducer` with the given options:
-     * @param init - the initial state value
-     * @param next - returns the next state value based on the given inputs:<br/>
-     * - current: the current state<br/>
-     * - next: the current input value<br/>
-     * - index: the input index value<br/>
-     * - halt: function that, when called, ensures no more elements are passed to the reducer
-     * @param stateToResult - a function that converts the current state to an output value
-     * @typeparam I - the input value type
-     * @typeparam O - the output value type
-     * @typeparam S - the internal state type
-     * @example
-     * ```ts
-     * const evenNumberOfOnes = Reducer
-     *   .create(
-     *     true,
-     *     (current, value: number) => value === 1 ? !current : current,
-     *     state => state ? 'even' : 'not even')
-     * const result = Stream.of(1, 2, 3, 2, 1)).reduce(evenNumberOfOnes)
-     * console.log+(result)
-     * // => 'even'
-     * ```
-     */
-    function create<I, O = I, S = O>(init: OptLazy<S>, next: (current: S, next: I, index: number, halt: () => void) => S, stateToResult: (state: S) => O): Reducer<I, O>;
-    /**
-     * Returns a `Reducer` of which the input, state, and output types are the same.
-     * @param init - the initial state value
-     * @param next - returns the next state value based on the given inputs:<br/>
-     * - current: the current state<br/>
-     * - next: the current input value<br/>
-     * - index: the input index value<br/>
-     * - halt: function that, when called, ensures no more elements are passed to the reducer
-     * @param stateToResult - (optional) a function that converts the current state to an output value
-     * @typeparam T - the overall value type
-     * @example
-     * ```ts
-     * const sum = Reducer
-     *   .createMono(
-     *     0,
-     *     (current, value) => current + value
-     *   )
-     * const result = Stream.of(1, 2, 3, 2, 1)).reduce(sum)
-     * console.log+(result)
-     * // => 9
-     * ```
-     */
-    function createMono<T>(init: OptLazy<T>, next: (current: T, next: T, index: number, halt: () => void) => T, stateToResult?: (state: T) => T): Reducer<T>;
-    /**
-     * Returns a `Reducer` of which the state and output types are the same.
-     * @param init - the initial state value
-     * @param next - returns the next state value based on the given inputs:<br/>
-     * - current: the current state<br/>
-     * - next: the current input value<br/>
-     * - index: the input index value<br/>
-     * - halt: function that, when called, ensures no more elements are passed to the reducer
-     * @param stateToResult - (optional) a function that converts the current state to an output value
-     * @typeparam I - the input value type
-     * @typeparam O - the output value type
-     * @example
-     * ```ts
-     * const boolToString = Reducer
-     *   .createOutput(
-     *     '',
-     *     (current, value: boolean) => current + (value ? 'T' : 'F')
-     *   )
-     * const result = Stream.of(true, false, true)).reduce(boolToString)
-     * console.log+(result)
-     * // => 'TFT'
-     * ```
-     */
-    function createOutput<I, O = I>(init: OptLazy<O>, next: (current: O, next: I, index: number, halt: () => void) => O, stateToResult?: (state: O) => O): Reducer<I, O>;
-    /**
-     * A `Reducer` that sums all given numeric input values.
-     * @example
-     * ```ts
-     * console.log(Stream.range({ amount: 5 }).reduce(Reducer.sum))
-     * // => 10
-     * ```
-     */
-    const sum: Reducer<number, number>;
-    /**
-     * A `Reducer` that calculates the product of all given numeric input values.
-     * @example
-     * ```ts
-     * console.log(Stream.range({ start: 1, amount: 5 }).reduce(product))
-     * // => 120
-     * ```
-     */
-    const product: Reducer<number, number>;
-    /**
-     * A `Reducer` that calculates the average of all given numberic input values.
-     * @example
-     * ```ts
-     * console.log(Stream.range({ amount: 5 }).reduce(Reducer.average));
-     * // => 2
-     * ```
-     */
-    const average: Reducer<number, number>;
-    /**
-     * Returns a `Reducer` that remembers the minimum value of the inputs using the given `compFun` to compare input values
-     * @param compFun - a comparison function for two input values, returning 0 when equal, positive when greater, negetive when smaller
-     * @param otherwise - (default: undefineds) a fallback value when there were no input values given
-     * @example
-     * ```ts
-     * const stream = Stream.of('abc', 'a', 'abcde', 'ab')
-     * console.log(stream.minBy((s1, s2) => s1.length - s2.length))
-     * // 'a'
-     * ```
-     */
-    const minBy: {
-        <T>(compFun: (v1: T, v2: T) => number): Reducer<T, T | undefined>;
-        <T, O>(compFun: (v1: T, v2: T) => number, otherwise: OptLazy<O>): Reducer<T, T | O>;
-    };
-    /**
-     * Returns a `Reducer` that remembers the minimum value of the numberic inputs.
-     * @param otherwise - (default: undefined) a fallback value when there were no input values given
-     * @example
-     * ```ts
-     * console.log(Stream.of(5, 3, 7, 4).reduce(Reducer.min()))
-     * // => 3
-     * ```
-     */
-    const min: {
-        (): Reducer<number, number | undefined>;
-        <O>(otherwise: OptLazy<O>): Reducer<number, number | O>;
-    };
-    /**
-     * Returns a `Reducer` that remembers the maximum value of the inputs using the given `compFun` to compare input values
-     * @param compFun - a comparison function for two input values, returning 0 when equal, positive when greater, negetive when smaller
-     * @param otherwise - (default: undefined) a fallback value when there were no input values given
-     * @example
-     * ```ts
-     * const stream = Stream.of('abc', 'a', 'abcde', 'ab')
-     * console.log(stream.maxBy((s1, s2) => s1.length - s2.length))
-     * // 'abcde'
-     * ```
-     */
-    const maxBy: {
-        <T>(compFun: (v1: T, v2: T) => number): Reducer<T, T | undefined>;
-        <T, O>(compFun: (v1: T, v2: T) => number, otherwise: OptLazy<O>): Reducer<T, T | O>;
-    };
-    /**
-     * Returns a `Reducer` that remembers the maximum value of the numberic inputs.
-     * @param otherwise - (default: undefined) a fallback value when there were no input values given
-     * @example
-     * ```ts
-     * console.log(Stream.of(5, 3, 7, 4).reduce(Reducer.max()))
-     * // => 7
-     * ```
-     */
-    const max: {
-        (): Reducer<number, number | undefined>;
-        <O>(otherwise: OptLazy<O>): Reducer<number, number | O>;
-    };
-    /**
-     * Returns a `Reducer` that joins the given input values into a string using the given options.
-     * @param options - an object containing:<br/>
-     * - sep: (optional) a seperator string value between values in the output<br/>
-     * - start: (optional) a start string to prepend to the output<br/>
-     * - end: (optional) an end string to append to the output<br/>
-     * @example
-     * ```ts
-     * console.log(Stream.of(1, 2, 3).reduce(Reducer.join({ sep: '-' })))
-     * // => '1-2-3'
-     * ```
-     */
-    function join<T>({ sep, start, end, valueToString, }?: {
-        sep?: string | undefined;
-        start?: string | undefined;
-        end?: string | undefined;
-        valueToString?: ((value: T) => string) | undefined;
-    }): Reducer<T, string>;
-    /**
-     * Returns a `Reducer` that remembers the amount of input items provided.
-     * @param pred - (optional) a predicate that returns false if the item should not be counted given:<br/>
-     * - value: the current input value<br/>
-     * - index: the input value index
-     * @example
-     * ```ts
-     * const stream = Stream.range({ amount: 10 })
-     * console.log(stream.reduce(Reducer.count()))
-     * // => 10
-     * console.log(stream.reduce(Reducer.count(v => v < 5)))
-     * // => 5
-     * ```
-     */
-    const count: {
-        (): Reducer<never, number>;
-        <T>(pred: (value: T, index: number) => boolean): Reducer<T, number>;
-    };
-    /**
-     * Returns a `Reducer` that remembers the first input value for which the given `pred` function returns true.
-     * @param pred - a function taking an input value and its index, and returning true if the value should be remembered
-     * @param otherwise - (default: undefined) a fallback value to output if no input value yet has satisfied the given predicate
-     * @typeparam T - the input value type
-     * @typeparam O - the fallback value type
-     * @example
-     * ```ts
-     * console.log(Stream.range({ amount: 10 }).reduce(Reducer.firstWhere(v => v > 5)))
-     * // => 6
-     * ```
-     */
-    const firstWhere: {
-        <T>(pred: (value: T, index: number) => boolean): Reducer<T, T | undefined>;
-        <T, O>(pred: (value: T, index: number) => boolean, otherwise: OptLazy<O>): Reducer<T, T | O>;
-    };
-    /**
-     * Returns a `Reducer` that remembers the first input value.
-     * @param otherwise - (default: undefined) a fallback value to output if no input value has been provided
-     * @typeparam T - the input value type
-     * @typeparam O - the fallback value type
-     * @example
-     * ```ts
-     * console.log(Stream.range{ amount: 10 }).reduce(Reducer.first())
-     * // => 0
-     * ```
-     */
-    const first: {
-        <T>(): Reducer<T, T | undefined>;
-        <T, O>(otherwise: OptLazy<O>): Reducer<T, T | O>;
-    };
-    /**
-     * Returns a `Reducer` that remembers the last input value for which the given `pred` function returns true.
-     * @param pred - a function taking an input value and its index, and returning true if the value should be remembered
-     * @param otherwise - (default: undefined) a fallback value to output if no input value yet has satisfied the given predicate
-     * @typeparam T - the input value type
-     * @typeparam O - the fallback value type
-     * @example
-     * ```ts
-     * console.log(Stream.range({ amount: 10 }).reduce(Reducer.lastWhere(v => v > 5)))
-     * // => 9
-     * ```
-     */
-    const lastWhere: {
-        <T>(pred: (value: T, index: number) => boolean): Reducer<T, T | undefined>;
-        <T, O>(pred: (value: T, index: number) => boolean, otherwise: OptLazy<O>): Reducer<T, T | O>;
-    };
-    /**
-     * Returns a `Reducer` that remembers the last input value.
-     * @param otherwise - (default: undefined) a fallback value to output if no input value has been provided
-     * @typeparam T - the input value type
-     * @typeparam O - the fallback value type
-     * @example
-     * ```ts
-     * console.log(Stream.range{ amount: 10 }).reduce(Reducer.last())
-     * // => 9
-     * ```
-     */
-    const last: {
-        <T>(): Reducer<T, T | undefined>;
-        <T, O>(otherwise: OptLazy<O>): Reducer<T, T | O>;
-    };
-    /**
-     * Returns a `Reducer` that ouputs false as long as no input value satisfies given `pred`, true otherwise.
-     * @typeparam T - the element type
-     * @param pred - a function taking an input value and its index, and returning true if the value satisfies the predicate
-     * @example
-     * ```ts
-     * console.log(Stream.range{ amount: 10 }).reduce(Reducer.some(v => v > 5))
-     * // => true
-     * ```
-     */
-    function some<T>(pred: (value: T, index: number) => boolean): Reducer<T, boolean>;
-    /**
-     * Returns a `Reducer` that ouputs true as long as all input values satisfy the given `pred`, false otherwise.
-     * @typeparam T - the element type
-     * @param pred - a function taking an input value and its index, and returning true if the value satisfies the predicate
-     * @example
-     * ```ts
-     * console.log(Stream.range{ amount: 10 }).reduce(Reducer.every(v => v < 5))
-     * // => false
-     * ```
-     */
-    function every<T>(pred: (value: T, index: number) => boolean): Reducer<T, boolean>;
-    /**
-     * Returns a `Reducer` that outputs false as long as the given `elem` has not been encountered in the input values, true otherwise.
-     * @typeparam T - the element type
-     * @param elem - the element to search for
-     * @param eq - (optional) a comparison function that returns true if te two given input values are considered equal
-     * @example
-     * ```ts
-     * console.log(Stream.range({ amount: 10 }).reduce(Reducer.contains(5)))
-     * // => true
-     * ```
-     */
-    function contains<T>(elem: T, eq?: Eq<T>): Reducer<T, boolean>;
-    /**
-     * Returns a `Reducer` that takes boolean values and outputs true if all input values are true, and false otherwise.
-     * @example
-     * ```ts
-     * console.log(Stream.of(true, false, true)).reduce(Reducer.and))
-     * // => false
-     * ```
-     */
-    const and: Reducer<boolean, boolean>;
-    /**
-     * Returns a `Reducer` that takes boolean values and outputs true if one or more input values are true, and false otherwise.
-     * @example
-     * ```ts
-     * console.log(Stream.of(true, false, true)).reduce(Reducer.or))
-     * // => true
-     * ```
-     */
-    const or: Reducer<boolean, boolean>;
-    /**
-     * Returns a `Reducer` that outputs true if no input values are received, false otherwise.
-     * @example
-     * ```ts
-     * console.log(Stream.of(1, 2, 3).reduce(Reducer.isEmpty))
-     * // => false
-     * ```
-     */
-    const isEmpty: Reducer<never, boolean>;
-    /**
-     * Returns a `Reducer` that outputs true if one or more input values are received, false otherwise.
-     * @example
-     * ```ts
-     * console.log(Stream.of(1, 2, 3).reduce(Reducer.nonEmpty))
-     * // => true
-     * ```
-     */
-    const nonEmpty: Reducer<never, boolean>;
-    /**
-     * Returns a `Reducer` that collects received input values in an array, and returns a copy of that array as an output value when requested.
-     * @typeparam T - the element type
-     * @example
-     * ```ts
-     * console.log(Stream.of(1, 2, 3).reduce(Reducer.toArray()))
-     * // => [1, 2, 3]
-     * ```
-     */
-    function toArray<T>(): Reducer<T, T[]>;
-    /**
-     * Returns a `Reducer` that collects received input tuples into a mutable JS Map, and returns
-     * a copy of that map when output is requested.
-     * @typeparam K - the map key type
-     * @typeparam V - the map value type
-     * @example
-     * ```ts
-     * console.log(Stream.of([1, 'a'], [2, 'b']).reduce(Reducer.toJSMap()))
-     * // Map { 1 => 'a', 2 => 'b' }
-     * ```
-     */
-    function toJSMap<K, V>(): Reducer<[K, V], Map<K, V>>;
-    /**
-     * Returns a `Reducer` that collects received input values into a mutable JS Set, and returns
-     * a copy of that map when output is requested.
-     * @typeparam T - the element type
-     * @example
-     * ```ts
-     * console.log(Stream.of(1, 2, 3).reduce(Reducer.toJSSet()))
-     * // Set {1, 2, 3}
-     * ```
-     */
-    function toJSSet<T>(): Reducer<T, Set<T>>;
-    /**
-     * Returns a `Reducer` that collects 2-tuples containing keys and values into a plain JS object, and
-     * returns a copy of that object when output is requested.
-     * @typeparam K - the result object key type
-     * @typeparam V - the result object value type
-     * @example
-     * ```ts
-     * console.log(Stream.of(['a', 1], ['b', true]).reduce(Reducer.toJSObject()))
-     * // { a: 1, b: true }
-     * ```
-     */
-    function toJSObject<K extends string | number | symbol, V>(): Reducer<[
-        K,
-        V
-    ], Record<K, V>>;
-    /**
-     * Returns a `Reducer` that combines multiple input `reducers` by providing input values to all of them and collecting the outputs in an array.
-     * @param reducers - 2 or more reducers to combine
-     * @example
-     * ```ts
-     * const red = Reducer.combineArr(Reducer.sum, Reducer.average)
-     * console.log(Stream.range({amount: 9 }).reduce(red))
-     * // => [36, 4]
-     * ```
-     */
-    function combineArr<T, R extends readonly [unknown, unknown, ...unknown[]]>(...reducers: {
-        [K in keyof R]: Reducer<T, R[K]>;
-    } & Reducer<T, unknown>[]): Reducer<T, R>;
-    /**
-     * Returns a `Reducer` that combines multiple input `reducers` by providing input values to all of them and collecting the outputs in the shape of the given object.
-     * @typeparam T - the input type for all the reducers
-     * @typeparam R - the result object shape
-     * @param reducerObj - an object of keys, and reducers corresponding to those keys
-     * @example
-     * ```ts
-     * const red = Reducer.combineObj({
-     *   theSum: Reducer.sum,
-     *   theAverage: Reducer.average
-     * });
-     *
-     * Stream.range({ amount: 9 }).reduce(red);
-     * // => { theSum: 36, theAverage: 4 }
-     * ```
-     */
-    function combineObj<T, R extends {
-        readonly [key: string]: unknown;
-    }>(reducerObj: {
-        readonly [K in keyof R]: Reducer<T, R[K]>;
-    } & Record<string, Reducer<T, unknown>>): Reducer<T, R>;
-}