iterable-linq-utility 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -33,6 +33,37 @@ export declare type AsyncAction<T> = (value: T, index: number) => Promise<Unit>;
  */
 declare function at<T>(iterable: Iterable<T>, index: number): T | undefined;
 
+/**
+ * Returns the average of the values of `iterable`: their sum with `+` divided by their number; reads the whole source.
+ * The values are not checked: `NaN` makes the result `NaN`.
+ * @operation `Action`
+ * @param iterable - the source `Iterable` of numbers
+ * @returns the average of the values, `undefined` when `iterable` is empty
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Functions.average([1, 2, 3, 4]); // 2.5
+ * ```
+ * @since 0.7.0
+ */
+declare function average(iterable: Iterable<number>): number | undefined;
+
+/**
+ * Returns the average of the numbers returned by `selector` for each value; reads the whole source.
+ * If `selector` throws, the source is closed and the error propagates.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param selector - called with each value and its index, returns the number to average; `undefined` averages the values themselves
+ * @returns the average of the selected numbers, `undefined` when `iterable` is empty
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if a provided `selector` is not a function
+ * @example
+ * ```ts
+ * Functions.average(['a', 'bb', 'ccc'], v => v.length); // 2
+ * ```
+ * @since 0.7.0
+ */
+declare function average<T>(iterable: Iterable<T>, selector: Mapper<T, number> | undefined): number | undefined;
+
 /**
  * Implementation of a method added with `extend` or `override`. `this` is the chain the method is called on.
  * @since 0.1.0
@@ -421,6 +452,7 @@ export declare function fromRange(start: number, end: number, options?: IRangeOp
 declare namespace Functions {
     export {
         at,
+        average,
         collectToArray,
         count,
         distinct,
@@ -436,6 +468,7 @@ declare namespace Functions {
         forEachAsync,
         includes,
         indexOf,
+        join,
         lastIndexOf,
         map,
         materialize,
@@ -446,9 +479,12 @@ declare namespace Functions {
         range,
         reduce,
         repeat_2 as repeat,
+        sequenceEqual,
+        single,
         skip,
         skipWhile,
         some,
+        sum,
         take,
         takeWhile,
         tap,
@@ -508,6 +544,32 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.6.0
      */
     at(index: number): T | undefined;
+    /**
+     * Returns the average of the values of a chain of numbers: their sum with `+` divided by their number; runs the whole chain.
+     * The values are not checked: `NaN` makes the result `NaN`.
+     * @operation `Action`
+     * @returns the average of the values, `undefined` when the chain is empty
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 4]).average(); // 2.5
+     * ```
+     * @since 0.7.0
+     */
+    average(this: IIterableLinqBase<number>): number | undefined;
+    /**
+     * Returns the average of the numbers returned by `selector` for each value; runs the whole chain.
+     * If `selector` throws, the source is closed and the error propagates.
+     * @operation `Action`
+     * @param selector - called with each value and its index, returns the number to average; `undefined` averages the values themselves
+     * @returns the average of the selected numbers, `undefined` when the chain is empty
+     * @throws Error if a provided `selector` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from(['a', 'bb', 'ccc']).average(v => v.length); // 2
+     * ```
+     * @since 0.7.0
+     */
+    average(selector: Mapper<T, number> | undefined): number | undefined;
     /**
      * Runs the chain and collects its values into an `Array`.
      * @operation `Action`
@@ -762,6 +824,20 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.6.0
      */
     indexOf(value: T): number;
+    /**
+     * Joins the values of the chain in a string, like `Array.prototype.join`; runs the whole chain.
+     * `null` and `undefined` become empty strings, every other value is converted with its `toString`.
+     * @operation `Action`
+     * @param separator - the string between two values; defaults to `,`
+     * @returns the joined values, `''` when the chain is empty
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).join(); // '1,2,3'
+     * IterableLinq.from(['a', 'b']).join(' - '); // 'a - b'
+     * ```
+     * @since 0.7.0
+     */
+    join(separator?: string): string;
     /**
      * Returns the index of the last value strictly equal (`===`) to `value`, like `Array.prototype.lastIndexOf`;
      * runs the whole chain.
@@ -876,6 +952,66 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.10
      */
     reduce<R>(neutralElement: R, reducer: Reducer<T, R>): R;
+    /**
+     * Tells whether the chain and `other` have the same values in the same order.
+     * It reads the two sources side by side, and stops and closes both at the first difference or when one ends before the other.
+     * If `equals` throws, both sources are closed and the error propagates; if a source throws, the other one is closed.
+     * @operation `Action`
+     * @param other - the `Iterable` to compare with, for example another chain
+     * @param equals - called with a value of the chain and the value of `other` at the same position; defaults to `===`
+     * @returns `true` if the two sources have the same number of values and every pair is equal
+     * @throws Error if `other` is missing or does not implement `[Symbol.iterator]`, or if a provided `equals` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).sequenceEqual([1, 2, 3]); // true
+     * IterableLinq.from(['a', 'bb']).sequenceEqual(['x', 'yy'], (a, b) => a.length === b.length); // true
+     * ```
+     * @since 0.7.0
+     */
+    sequenceEqual(other: Iterable<T>, equals?: (a: T, b: T) => boolean): boolean;
+    /**
+     * Returns the only value of the chain, `undefined` if it is empty; throws if it has more than one.
+     * It stops and closes the source at the second value, so it also ends an infinite chain.
+     * @operation `Action`
+     * @returns the only value, or `undefined` when the chain is empty
+     * @throws Error if the chain contains more than one value
+     * @example
+     * ```ts
+     * IterableLinq.from([5]).single(); // 5
+     * IterableLinq.from([1, 2]).single(); // throws
+     * ```
+     * @since 0.7.0
+     */
+    single(): T | undefined;
+    /**
+     * Returns the only value accepted by a type guard, narrowing its type, `undefined` if there is none; throws if there is more than one.
+     * It stops and closes the source at the second match. If `predicate` throws, the source is closed and the error propagates.
+     * @operation `Action`
+     * @param predicate - a type guard called with each value and its index
+     * @returns the only value accepted by `predicate`, or `undefined` if there is none
+     * @throws Error if `predicate` is not a function, or if more than one value satisfies it
+     * @example
+     * ```ts
+     * const values: (number | string)[] = [1, 'two', 3];
+     * IterableLinq.from(values).single((v): v is string => typeof v === 'string'); // string | undefined, 'two'
+     * ```
+     * @since 0.7.0
+     */
+    single<S extends T>(predicate: (value: T, index: number) => value is S): S | undefined;
+    /**
+     * Returns the only value that satisfies `predicate`, `undefined` if there is none; throws if there is more than one.
+     * It stops and closes the source at the second match. If `predicate` throws, the source is closed and the error propagates.
+     * @operation `Action`
+     * @param predicate - called with each value and its index; `undefined` looks for the only value of the chain
+     * @returns the only value that satisfies `predicate`, or `undefined` if there is none
+     * @throws Error if a provided `predicate` is not a function, or if more than one value satisfies it
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 5, 2]).single(v => v > 4); // 5
+     * ```
+     * @since 0.7.0
+     */
+    single(predicate: Predicate<T> | undefined): T | undefined;
     /**
      * Lazily skips the first `count` values and yields the rest.
      * @operation `Transformation`
@@ -928,6 +1064,32 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.1
      */
     some(predicate: Predicate<T> | undefined): boolean;
+    /**
+     * Sums the values of a chain of numbers with `+`; runs the whole chain.
+     * The values are not checked: `NaN` makes the result `NaN`.
+     * @operation `Action`
+     * @returns the sum of the values, `0` when the chain is empty
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).sum(); // 6
+     * ```
+     * @since 0.7.0
+     */
+    sum(this: IIterableLinqBase<number>): number;
+    /**
+     * Sums the numbers returned by `selector` for each value; runs the whole chain.
+     * If `selector` throws, the source is closed and the error propagates.
+     * @operation `Action`
+     * @param selector - called with each value and its index, returns the number to add; `undefined` sums the values themselves
+     * @returns the sum of the selected numbers, `0` when the chain is empty
+     * @throws Error if a provided `selector` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from(['a', 'bb', 'ccc']).sum(v => v.length); // 6
+     * ```
+     * @since 0.7.0
+     */
+    sum(selector: Mapper<T, number> | undefined): number;
     /**
      * Yields the first `count` values, then closes the source.
      * The source is never read past the `count`-th value, so `take` also ends an infinite chain.
@@ -1094,6 +1256,23 @@ export declare interface IRangeOptions {
  */
 export declare function isIterableLinq(value: unknown): value is IIterableLinq<unknown>;
 
+/**
+ * Joins the values of `iterable` in a string, like `Array.prototype.join`; reads the whole source.
+ * `null` and `undefined` become empty strings, every other value is converted with its `toString`.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param separator - the string between two values; defaults to `,`
+ * @returns the joined values, `''` when `iterable` is empty
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Functions.join([1, 2, 3]); // '1,2,3'
+ * Functions.join(['a', 'b'], ' - '); // 'a - b'
+ * ```
+ * @since 0.7.0
+ */
+declare function join<T>(iterable: Iterable<T>, separator?: string): string;
+
 /**
  * Returns the index of the last value strictly equal (`===`) to `value`, like `Array.prototype.lastIndexOf`;
  * reads the whole source.
@@ -1334,6 +1513,77 @@ export declare function repeat<T>(value: T, count: number): IIterableLinq<T>;
  */
 declare function repeat_2<T>(value: T, count: number): Iterable<T>;
 
+/**
+ * Tells whether `iterable` and `other` have the same values in the same order.
+ * It reads the two sources side by side, and stops and closes both at the first difference or when one ends before the other.
+ * If `equals` throws, both sources are closed and the error propagates; if a source throws, the other one is closed.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param other - the `Iterable` to compare with
+ * @param equals - called with a value of `iterable` and the value of `other` at the same position; defaults to `===`
+ * @returns `true` if the two sources have the same number of values and every pair is equal
+ * @throws Error if `iterable` or `other` is missing or does not implement `[Symbol.iterator]`, or if a provided `equals` is not a function
+ * @example
+ * ```ts
+ * Functions.sequenceEqual([1, 2, 3], [1, 2, 3]); // true
+ * Functions.sequenceEqual([1, 2], [1, 2, 3]); // false
+ * Functions.sequenceEqual([{ id: 1 }], [{ id: 1 }], (a, b) => a.id === b.id); // true
+ * ```
+ * @since 0.7.0
+ */
+declare function sequenceEqual<T>(iterable: Iterable<T>, other: Iterable<T>, equals?: (a: T, b: T) => boolean): boolean;
+
+/**
+ * Returns the only value of `iterable`, `undefined` if it is empty; throws if it has more than one.
+ * It stops and closes the source at the second value, so it also ends on an infinite source.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @returns the only value, or `undefined` when `iterable` is empty
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if it contains more than one value
+ * @example
+ * ```ts
+ * Functions.single([5]); // 5
+ * Functions.single([]); // undefined
+ * Functions.single([1, 2]); // throws
+ * ```
+ * @since 0.7.0
+ */
+declare function single<T>(iterable: Iterable<T>): T | undefined;
+
+/**
+ * Returns the only value accepted by a type guard, narrowing its type, `undefined` if there is none; throws if there is more than one.
+ * It stops and closes the source at the second match. If `predicate` throws, the source is closed and the error propagates.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param predicate - a type guard called with each value and its index
+ * @returns the only value accepted by `predicate`, or `undefined` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, if `predicate` is not a function, or if more than one value satisfies it
+ * @example
+ * ```ts
+ * const values: (number | string)[] = [1, 'two', 3];
+ * Functions.single(values, (v): v is string => typeof v === 'string'); // string | undefined, 'two'
+ * ```
+ * @since 0.7.0
+ */
+declare function single<T, S extends T>(iterable: Iterable<T>, predicate: (value: T, index: number) => value is S): S | undefined;
+
+/**
+ * Returns the only value that satisfies `predicate`, `undefined` if there is none; throws if there is more than one.
+ * It stops and closes the source at the second match. 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` looks for the only value of `iterable`
+ * @returns the only value that satisfies `predicate`, or `undefined` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, if a provided `predicate` is not a function, or if more than one value satisfies it
+ * @example
+ * ```ts
+ * Functions.single([1, 5, 2], v => v > 4); // 5
+ * Functions.single([5, 6], v => v > 4); // throws
+ * ```
+ * @since 0.7.0
+ */
+declare function single<T>(iterable: Iterable<T>, predicate: Predicate<T> | undefined): T | undefined;
+
 /**
  * Lazily skips the first `count` values and yields the rest.
  * @operation `Transformation`
@@ -1395,6 +1645,37 @@ declare function some<T>(iterable: Iterable<T>): boolean;
  */
 declare function some<T>(iterable: Iterable<T>, predicate: Predicate<T> | undefined): boolean;
 
+/**
+ * Sums the values of `iterable` with `+`; reads the whole source.
+ * The values are not checked: `NaN` makes the result `NaN`.
+ * @operation `Action`
+ * @param iterable - the source `Iterable` of numbers
+ * @returns the sum of the values, `0` when `iterable` is empty
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Functions.sum([1, 2, 3]); // 6
+ * ```
+ * @since 0.7.0
+ */
+declare function sum(iterable: Iterable<number>): number;
+
+/**
+ * Sums the numbers returned by `selector` for each value; reads the whole source.
+ * If `selector` throws, the source is closed and the error propagates.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param selector - called with each value and its index, returns the number to add; `undefined` sums the values themselves
+ * @returns the sum of the selected numbers, `0` when `iterable` is empty
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if a provided `selector` is not a function
+ * @example
+ * ```ts
+ * Functions.sum(['a', 'bb', 'ccc'], v => v.length); // 6
+ * ```
+ * @since 0.7.0
+ */
+declare function sum<T>(iterable: Iterable<T>, selector: Mapper<T, number> | undefined): number;
+
 /**
  * Lazily yields the first `count` values, then closes the source.
  * The source is never read past the `count`-th value, so `take` also ends an infinite source.