iterable-linq-utility 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -15,6 +15,55 @@ export declare type Action<T> = (value: T, index: number) => Unit;
  */
 export declare type AsyncAction<T> = (value: T, index: number) => Promise<Unit>;
 
+/**
+ * Returns the value at `index`, like `Array.prototype.at`; a negative index counts from the end.
+ * A non-negative index reads up to the value, then closes the source; a negative index reads the whole source,
+ * keeping only the last `-index` values.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param index - an integer; `-1` is the last value
+ * @returns the value at `index`, or `undefined` if `iterable` has no value there
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `index` is not an integer (fractions, `NaN` and `Infinity` included)
+ * @example
+ * ```ts
+ * Functions.at([10, 20, 30], 1); // 20
+ * Functions.at([10, 20, 30], -1); // 30
+ * ```
+ * @since 0.6.0
+ */
+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
@@ -241,6 +290,55 @@ declare function find<T>(iterable: Iterable<T>, predicate: Predicate<T>): T | un
  */
 declare function findIndex<T>(iterable: Iterable<T>, predicate: Predicate<T>): number;
 
+/**
+ * Returns the last value accepted by a type guard, narrowing its type; reads the whole source.
+ * 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 last 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, 'four'];
+ * Functions.findLast(values, (v): v is string => typeof v === 'string'); // string | undefined, 'four'
+ * ```
+ * @since 0.6.0
+ */
+declare function findLast<T, S extends T>(iterable: Iterable<T>, predicate: (value: T, index: number) => value is S): S | undefined;
+
+/**
+ * Returns the last value that satisfies `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
+ * @returns the last 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.findLast([1, 5, 6, 2], v => v > 4); // 6
+ * ```
+ * @since 0.6.0
+ */
+declare function findLast<T>(iterable: Iterable<T>, predicate: Predicate<T>): T | undefined;
+
+/**
+ * Returns the index of the last value that satisfies `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
+ * @returns the index of the last 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.findLastIndex([1, 5, 6, 2], v => v > 4); // 2
+ * ```
+ * @since 0.6.0
+ */
+declare function findLastIndex<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.
@@ -353,6 +451,8 @@ export declare function fromRange(start: number, end: number, options?: IRangeOp
 
 declare namespace Functions {
     export {
+        at,
+        average,
         collectToArray,
         count,
         distinct,
@@ -361,10 +461,15 @@ declare namespace Functions {
         filter,
         find,
         findIndex,
+        findLast,
+        findLastIndex,
         flatMap,
         forEach,
         forEachAsync,
         includes,
+        indexOf,
+        join,
+        lastIndexOf,
         map,
         materialize,
         max,
@@ -374,9 +479,12 @@ declare namespace Functions {
         range,
         reduce,
         repeat_2 as repeat,
+        sequenceEqual,
+        single,
         skip,
         skipWhile,
         some,
+        sum,
         take,
         takeWhile,
         tap,
@@ -420,6 +528,48 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.1
      */
     [Symbol.iterator](): Iterator<T, any, undefined>;
+    /**
+     * Returns the value at `index`, like `Array.prototype.at`; a negative index counts from the end.
+     * A non-negative index runs the chain up to the value, then closes the source; a negative index runs the whole chain,
+     * keeping only the last `-index` values.
+     * @operation `Action`
+     * @param index - an integer; `-1` is the last value
+     * @returns the value at `index`, or `undefined` if the chain has no value there
+     * @throws Error if `index` is not an integer (fractions, `NaN` and `Infinity` included)
+     * @example
+     * ```ts
+     * IterableLinq.from([10, 20, 30]).at(1); // 20
+     * IterableLinq.from([10, 20, 30]).at(-1); // 30
+     * ```
+     * @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`
@@ -554,6 +704,49 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.5.0
      */
     findIndex(predicate: Predicate<T>): number;
+    /**
+     * Returns the last value accepted by a type guard, narrowing its type; runs the whole chain.
+     * 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 last 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, 'four'];
+     * IterableLinq.from(values).findLast((v): v is string => typeof v === 'string'); // string | undefined, 'four'
+     * ```
+     * @since 0.6.0
+     */
+    findLast<S extends T>(predicate: (value: T, index: number) => value is S): S | undefined;
+    /**
+     * Returns the last value that satisfies `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
+     * @returns the last 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, 2]).findLast(v => v > 4); // 6
+     * ```
+     * @since 0.6.0
+     */
+    findLast(predicate: Predicate<T>): T | undefined;
+    /**
+     * Returns the index of the last value that satisfies `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
+     * @returns the index of the last 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, 2]).findLastIndex(v => v > 4); // 2
+     * ```
+     * @since 0.6.0
+     */
+    findLastIndex(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.
@@ -618,6 +811,46 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.5.0
      */
     includes(value: T): boolean;
+    /**
+     * Returns the index of the first value strictly equal (`===`) to `value`, like `Array.prototype.indexOf`;
+     * stops and closes the source at the first match.
+     * @operation `Action`
+     * @param value - the value to look for; `NaN` is never found, use `includes` or `findIndex` for it
+     * @returns the index of the first value equal to `value`, or `-1` if there is none
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 2]).indexOf(2); // 1
+     * ```
+     * @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.
+     * @operation `Action`
+     * @param value - the value to look for; `NaN` is never found, use `findLastIndex` for it
+     * @returns the index of the last value equal to `value`, or `-1` if there is none
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 2]).lastIndexOf(2); // 3
+     * ```
+     * @since 0.6.0
+     */
+    lastIndexOf(value: T): number;
     /**
      * Transforms each value with `mapper`.
      * If `mapper` throws, the source is closed and the error propagates.
@@ -719,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`
@@ -771,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.
@@ -895,6 +1214,22 @@ export declare interface IMemoizeOptions {
  */
 declare function includes<T>(iterable: Iterable<T>, value: T): boolean;
 
+/**
+ * Returns the index of the first value strictly equal (`===`) to `value`, like `Array.prototype.indexOf`;
+ * stops and closes the source at the first match.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param value - the value to look for; `NaN` is never found, use `includes` or `findIndex` for it
+ * @returns the index of the first value equal to `value`, or `-1` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Functions.indexOf([1, 2, 3, 2], 2); // 1
+ * ```
+ * @since 0.6.0
+ */
+declare function indexOf<T>(iterable: Iterable<T>, value: T): number;
+
 /**
  * Options of `range`.
  * @since 0.1.0
@@ -921,6 +1256,39 @@ 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.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param value - the value to look for; `NaN` is never found, use `findLastIndex` for it
+ * @returns the index of the last value equal to `value`, or `-1` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Functions.lastIndexOf([1, 2, 3, 2], 2); // 3
+ * ```
+ * @since 0.6.0
+ */
+declare function lastIndexOf<T>(iterable: Iterable<T>, value: T): number;
+
 /**
  * Lazily transforms each value with `mapper`.
  * If `mapper` throws, the source is closed and the error propagates.
@@ -1145,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`
@@ -1206,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.