iterable-linq-utility 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -54,6 +54,54 @@ declare type ComparerFunction<T> = (a: T, b: T) => number;
 
 declare type ComparingProps<T> = keyof T | Array<keyof T>;
 
+/**
+ * Counts the values of `iterable`; reads the whole source.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @returns the number of values in `iterable`
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Functions.count([1, 2, 3]); // 3
+ * ```
+ * @since 0.5.0
+ */
+declare function count<T>(iterable: Iterable<T>): number;
+
+/**
+ * Counts the values that satisfy `predicate`; reads the whole source.
+ * If `predicate` throws, the source is closed and the error propagates.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param predicate - called with each value and its index; `undefined` counts every value
+ * @returns the number of values that satisfy `predicate`
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if a provided `predicate` is not a function
+ * @example
+ * ```ts
+ * Functions.count([1, 5, 2, 6], v => v > 4); // 2
+ * ```
+ * @since 0.5.0
+ */
+declare function count<T>(iterable: Iterable<T>, predicate: Predicate<T> | undefined): number;
+
+/**
+ * Lazily yields the first value for each distinct value or selected key, in source order.
+ * Keys use `SameValueZero`, like `Set`; original values are preserved.
+ * Each iterator stores its own seen keys. If `keySelector` throws, the source is closed and the error propagates.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param keySelector - called with every source value and its index; omitted or `undefined` compares values directly
+ * @returns a lazy, re-runnable `Iterable` of the first values for each key
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if a provided `keySelector` is not a function
+ * @example
+ * ```ts
+ * Array.from(Functions.distinct([3, 1, 3, 2, 1])); // [3, 1, 2]
+ * Array.from(Functions.distinct([{ id: 1 }, { id: 1 }, { id: 2 }], v => v.id)); // [{ id: 1 }, { id: 2 }]
+ * ```
+ * @since 0.5.0
+ */
+declare function distinct<T, K>(iterable: Iterable<T>, keySelector?: Mapper<T, K>): Iterable<T>;
+
 /**
  * Starts a chain with no values.
  * @returns an empty chain
@@ -77,6 +125,21 @@ export declare function empty<T>(): IIterableLinq<T>;
  */
 declare function empty_2<T>(): Iterable<T>;
 
+/**
+ * Tells whether every value satisfies `predicate`; stops and closes the source at the first rejected value.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param predicate - called with each value and its index
+ * @returns `true` if every value satisfies `predicate`, or if `iterable` is empty; `false` otherwise
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * Functions.every([1, 2, 3], v => v > 0); // true
+ * ```
+ * @since 0.5.0
+ */
+declare function every<T>(iterable: Iterable<T>, predicate: Predicate<T>): boolean;
+
 /**
  * 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.
@@ -98,6 +161,24 @@ declare function empty_2<T>(): Iterable<T>;
  */
 export declare function extend<K extends Extract<keyof IIterableLinq<unknown>, string>>(name: K, implementation: ChainMethod): void;
 
+/**
+ * Lazily keeps the values accepted by a type guard and narrows their type.
+ * If `predicate` throws, the source is closed and the error propagates.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param predicate - a type guard called with each value and its index; return `true` to keep the value
+ * @returns a lazy, re-runnable `Iterable` of the narrowed values
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * const values: (number | string)[] = [1, 'two', 3];
+ * const strings = Functions.filter(values, (v): v is string => typeof v === 'string');
+ * Array.from(strings); // string[], ['two']
+ * ```
+ * @since 0.4.0
+ */
+declare function filter<T, S extends T>(iterable: Iterable<T>, predicate: (value: T, index: number) => value is S): Iterable<S>;
+
 /**
  * Lazily keeps only the values that satisfy `predicate`.
  * If `predicate` throws, the source is closed and the error propagates.
@@ -114,6 +195,52 @@ export declare function extend<K extends Extract<keyof IIterableLinq<unknown>, s
  */
 declare function filter<T>(iterable: Iterable<T>, predicate: Predicate<T>): Iterable<T>;
 
+/**
+ * Returns the first value accepted by a type guard, narrowing its type; stops and closes the source at the first match.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param predicate - a type guard called with each value and its index
+ * @returns the first value accepted by `predicate`, or `undefined` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * const values: (number | string)[] = [1, 'two', 3];
+ * Functions.find(values, (v): v is string => typeof v === 'string'); // string | undefined, 'two'
+ * ```
+ * @since 0.5.0
+ */
+declare function find<T, S extends T>(iterable: Iterable<T>, predicate: (value: T, index: number) => value is S): S | undefined;
+
+/**
+ * Returns the first value that 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 the first value that satisfies `predicate`, or `undefined` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * Functions.find([1, 5, 6], v => v > 4); // 5
+ * ```
+ * @since 0.5.0
+ */
+declare function find<T>(iterable: Iterable<T>, predicate: Predicate<T>): T | undefined;
+
+/**
+ * Returns the index of the first value that 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 the index of the first value that satisfies `predicate`, or `-1` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * Functions.findIndex([1, 5, 6], v => v > 4); // 1
+ * ```
+ * @since 0.5.0
+ */
+declare function findIndex<T>(iterable: Iterable<T>, predicate: Predicate<T>): number;
+
 /**
  * Lazily maps each value to an `Iterable` and flattens the results.
  * Each inner `Iterable` is read completely before the next value is mapped.
@@ -227,11 +354,17 @@ export declare function fromRange(start: number, end: number, options?: IRangeOp
 declare namespace Functions {
     export {
         collectToArray,
+        count,
+        distinct,
         empty_2 as empty,
+        every,
         filter,
+        find,
+        findIndex,
         flatMap,
         forEach,
         forEachAsync,
+        includes,
         map,
         materialize,
         max,
@@ -242,8 +375,10 @@ declare namespace Functions {
         reduce,
         repeat_2 as repeat,
         skip,
+        skipWhile,
         some,
         take,
+        takeWhile,
         tap,
         tapChain
     }
@@ -296,6 +431,75 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.1
      */
     collectToArray(): T[];
+    /**
+     * Counts the values of the chain; runs the whole chain.
+     * @operation `Action`
+     * @returns the number of values in the chain
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).count(); // 3
+     * ```
+     * @since 0.5.0
+     */
+    count(): number;
+    /**
+     * Counts the values that satisfy `predicate`; runs the whole chain.
+     * If `predicate` throws, the source is closed and the error propagates.
+     * @operation `Action`
+     * @param predicate - called with each value and its index; `undefined` counts every value
+     * @returns the number of values that satisfy `predicate`
+     * @throws Error if a provided `predicate` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 5, 2, 6]).count(v => v > 4); // 2
+     * ```
+     * @since 0.5.0
+     */
+    count(predicate: Predicate<T> | undefined): number;
+    /**
+     * Yields the first value for each distinct value or selected key, in source order.
+     * Keys use `SameValueZero`, like `Set`; original values are preserved.
+     * Each iteration stores its own seen keys. If `keySelector` throws, the source is closed and the error propagates.
+     * @operation `Transformation`
+     * @param keySelector - called with every source value and its index; omitted or `undefined` compares values directly
+     * @returns a new lazy, re-runnable chain of the first values for each key
+     * @throws Error if a provided `keySelector` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([3, 1, 3, 2, 1]).distinct().collectToArray(); // [3, 1, 2]
+     * IterableLinq.from([{ id: 1 }, { id: 1 }, { id: 2 }]).distinct(v => v.id).collectToArray(); // [{ id: 1 }, { id: 2 }]
+     * ```
+     * @since 0.5.0
+     */
+    distinct<K>(keySelector?: Mapper<T, K>): IIterableLinq<T>;
+    /**
+     * Tells whether every value satisfies `predicate`; stops and closes the source at the first rejected value.
+     * @operation `Action`
+     * @param predicate - called with each value and its index
+     * @returns `true` if every value satisfies `predicate`, or if the chain is empty; `false` otherwise
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).every(v => v > 0); // true
+     * ```
+     * @since 0.5.0
+     */
+    every(predicate: Predicate<T>): boolean;
+    /**
+     * Keeps the values accepted by a type guard and narrows their type.
+     * If `predicate` throws, the source is closed and the error propagates.
+     * @operation `Transformation`
+     * @param predicate - a type guard called with each value and its index; return `true` to keep the value
+     * @returns a new chain with the narrowed values
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * const values: (number | string)[] = [1, 'two', 3];
+     * IterableLinq.from(values).filter((v): v is string => typeof v === 'string').collectToArray(); // string[], ['two']
+     * ```
+     * @since 0.4.0
+     */
+    filter<S extends T>(predicate: (value: T, index: number) => value is S): IIterableLinq<S>;
     /**
      * Keeps only the values that satisfy `predicate`.
      * If `predicate` throws, the source is closed and the error propagates.
@@ -310,6 +514,46 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.1
      */
     filter(predicate: Predicate<T>): IIterableLinq<T>;
+    /**
+     * Returns the first value accepted by a type guard, narrowing its type; stops and closes the source at the first match.
+     * @operation `Action`
+     * @param predicate - a type guard called with each value and its index
+     * @returns the first value accepted by `predicate`, or `undefined` if there is none
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * const values: (number | string)[] = [1, 'two', 3];
+     * IterableLinq.from(values).find((v): v is string => typeof v === 'string'); // string | undefined, 'two'
+     * ```
+     * @since 0.5.0
+     */
+    find<S extends T>(predicate: (value: T, index: number) => value is S): S | undefined;
+    /**
+     * Returns the first value that satisfies `predicate`; stops and closes the source at the first match.
+     * @operation `Action`
+     * @param predicate - called with each value and its index
+     * @returns the first value that satisfies `predicate`, or `undefined` if there is none
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 5, 6]).find(v => v > 4); // 5
+     * ```
+     * @since 0.5.0
+     */
+    find(predicate: Predicate<T>): T | undefined;
+    /**
+     * Returns the index of the first value that satisfies `predicate`; stops and closes the source at the first match.
+     * @operation `Action`
+     * @param predicate - called with each value and its index
+     * @returns the index of the first value that satisfies `predicate`, or `-1` if there is none
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 5, 6]).findIndex(v => v > 4); // 1
+     * ```
+     * @since 0.5.0
+     */
+    findIndex(predicate: Predicate<T>): number;
     /**
      * 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.
@@ -361,6 +605,19 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.11
      */
     forEachAsync(action: AsyncAction<T>): Promise<Unit>;
+    /**
+     * Tells whether the chain contains `value`, compared with `SameValueZero` like `Array.prototype.includes`;
+     * stops and closes the source at the first match.
+     * @operation `Action`
+     * @param value - the value to look for; `NaN` matches `NaN`, and `+0` matches `-0`
+     * @returns `true` if the chain contains `value`; `false` otherwise
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, NaN]).includes(NaN); // true
+     * ```
+     * @since 0.5.0
+     */
+    includes(value: T): boolean;
     /**
      * Transforms each value with `mapper`.
      * If `mapper` throws, the source is closed and the error propagates.
@@ -475,6 +732,21 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.3.0
      */
     skip(count: number): IIterableLinq<T>;
+    /**
+     * Skips the values while `predicate` returns `true`, then yields the first rejected value and all the rest.
+     * After the first rejected value, `predicate` is not called again.
+     * If `predicate` throws, the source is closed and the error propagates.
+     * @operation `Transformation`
+     * @param predicate - called with each value and its index until it returns `false`
+     * @returns a new chain of the values from the first rejected one
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 5, 3]).skipWhile(v => v < 4).collectToArray(); // [5, 3]
+     * ```
+     * @since 0.5.0
+     */
+    skipWhile(predicate: Predicate<T>): IIterableLinq<T>;
     /**
      * Runs the chain until its first value, then stops and closes the source.
      * @operation `Action`
@@ -513,6 +785,37 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.3.0
      */
     take(count: number): IIterableLinq<T>;
+    /**
+     * Yields the values while a type guard accepts them, narrowing their type, then closes the source.
+     * The source is never read past the first rejected value, which is not yielded.
+     * If `predicate` throws, the source is closed and the error propagates.
+     * @operation `Transformation`
+     * @param predicate - a type guard called with each value and its index; the first `false` ends the chain
+     * @returns a new chain of the narrowed values before the first rejected one
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * const values: (number | string)[] = [1, 2, 'three', 4];
+     * IterableLinq.from(values).takeWhile((v): v is number => typeof v === 'number').collectToArray(); // number[], [1, 2]
+     * ```
+     * @since 0.5.0
+     */
+    takeWhile<S extends T>(predicate: (value: T, index: number) => value is S): IIterableLinq<S>;
+    /**
+     * Yields the values while `predicate` returns `true`, then closes the source.
+     * The source is never read past the first rejected value, which is not yielded, so `takeWhile` can end an infinite chain.
+     * If `predicate` throws, the source is closed and the error propagates.
+     * @operation `Transformation`
+     * @param predicate - called with each value and its index; the first `false` ends the chain
+     * @returns a new chain of the values before the first rejected one
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 5, 3]).takeWhile(v => v < 4).collectToArray(); // [1, 2]
+     * ```
+     * @since 0.5.0
+     */
+    takeWhile(predicate: Predicate<T>): IIterableLinq<T>;
     /**
      * 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.
@@ -555,11 +858,12 @@ export declare interface IIterableLinqBase<T> {
      * @example
      * ```ts
      * let evens: IIterableLinq<number> | undefined;
-     * IterableLinq.fromRange(10)
+     * const evensByTen = 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]
+     * evensByTen.collectToArray(); // [0, 20, 40, 60, 80]
      * ```
      * @since 0.0.10
      */
@@ -575,6 +879,22 @@ export declare interface IMemoizeOptions {
     allowPartialMemoization?: boolean;
 }
 
+/**
+ * Tells whether `iterable` contains `value`, compared with `SameValueZero` like `Array.prototype.includes`;
+ * stops and closes the source at the first match.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param value - the value to look for; `NaN` matches `NaN`, and `+0` matches `-0`
+ * @returns `true` if `iterable` contains `value`; `false` otherwise
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Functions.includes([1, 2, NaN], NaN); // true
+ * ```
+ * @since 0.5.0
+ */
+declare function includes<T>(iterable: Iterable<T>, value: T): boolean;
+
 /**
  * Options of `range`.
  * @since 0.1.0
@@ -840,6 +1160,23 @@ declare function repeat_2<T>(value: T, count: number): Iterable<T>;
  */
 declare function skip<T>(iterable: Iterable<T>, count: number): Iterable<T>;
 
+/**
+ * Lazily skips the values while `predicate` returns `true`, then yields the first rejected value and all the rest.
+ * After the first rejected value, `predicate` is not called again.
+ * 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 until it returns `false`
+ * @returns a lazy, re-runnable `Iterable` of the values from the first rejected one
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * Array.from(Functions.skipWhile([1, 2, 5, 3], v => v < 4)); // [5, 3]
+ * ```
+ * @since 0.5.0
+ */
+declare function skipWhile<T>(iterable: Iterable<T>, predicate: Predicate<T>): Iterable<T>;
+
 /**
  * Tells whether `iterable` contains a value; reads one value, then closes the source.
  * @operation `Action`
@@ -885,6 +1222,41 @@ declare function some<T>(iterable: Iterable<T>, predicate: Predicate<T> | undefi
  */
 declare function take<T>(iterable: Iterable<T>, count: number): Iterable<T>;
 
+/**
+ * Lazily yields the values while a type guard accepts them, narrowing their type, then closes the source.
+ * The source is never read past the first rejected value, which is not yielded.
+ * If `predicate` throws, the source is closed and the error propagates.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param predicate - a type guard called with each value and its index; the first `false` ends the iterable
+ * @returns a lazy, re-runnable `Iterable` of the narrowed values before the first rejected one
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * const values: (number | string)[] = [1, 2, 'three', 4];
+ * Array.from(Functions.takeWhile(values, (v): v is number => typeof v === 'number')); // number[], [1, 2]
+ * ```
+ * @since 0.5.0
+ */
+declare function takeWhile<T, S extends T>(iterable: Iterable<T>, predicate: (value: T, index: number) => value is S): Iterable<S>;
+
+/**
+ * Lazily yields the values while `predicate` returns `true`, then closes the source.
+ * The source is never read past the first rejected value, which is not yielded, so `takeWhile` can end an infinite source.
+ * 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; the first `false` ends the iterable
+ * @returns a lazy, re-runnable `Iterable` of the values before the first rejected one
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * Array.from(Functions.takeWhile([1, 2, 5, 3], v => v < 4)); // [1, 2]
+ * ```
+ * @since 0.5.0
+ */
+declare function takeWhile<T>(iterable: Iterable<T>, predicate: Predicate<T>): Iterable<T>;
+
 /**
  * Lazily calls `tapper` on each value as it flows through, without changing it.
  * If `tapper` throws, the source is closed and the error propagates.