iterable-linq-utility 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -6,6 +6,22 @@
  */
 export declare type Action<T> = (value: T, index: number) => Unit;
 
+/**
+ * Lazily yields the values of `iterable`, then `value`.
+ * `value` is yielded only when the source ends, so it is never reached on an infinite source.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param value - the value yielded after the last value of the source
+ * @returns a lazy, re-runnable `Iterable` of the values of the source followed by `value`
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.append([1, 2, 3], 4)); // [1, 2, 3, 4]
+ * ```
+ * @since 0.8.0
+ */
+declare function append<T>(iterable: Iterable<T>, value: T): Iterable<T>;
+
 /**
  * Callback of `forEachAsync`: an async side effect run on each value.
  * @param value - the current value
@@ -33,6 +49,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
@@ -72,6 +119,23 @@ declare type ComparerFunction<T> = (a: T, b: T) => number;
 
 declare type ComparingProps<T> = keyof T | Array<keyof T>;
 
+/**
+ * Lazily yields the values of `iterable`, then the values of each iterable in `others`, in order.
+ * Each iterable is opened only when the previous one ends, so the iterables after an infinite one are never read.
+ * Stopping early closes only the iterable being read.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param others - the iterables read after the source
+ * @returns a lazy, re-runnable `Iterable` of the values of the source followed by the values of `others`
+ * @throws Error if `iterable` or a value of `others` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.concat([1, 2], [3], new Set([4, 5]))); // [1, 2, 3, 4, 5]
+ * ```
+ * @since 0.8.0
+ */
+declare function concat<T>(iterable: Iterable<T>, ...others: Iterable<T>[]): Iterable<T>;
+
 /**
  * Counts the values of `iterable`; reads the whole source.
  * @operation `Action`
@@ -420,8 +484,11 @@ export declare function fromRange(start: number, end: number, options?: IRangeOp
 
 declare namespace Functions {
     export {
+        append,
         at,
+        average,
         collectToArray,
+        concat,
         count,
         distinct,
         empty_2 as empty,
@@ -436,6 +503,7 @@ declare namespace Functions {
         forEachAsync,
         includes,
         indexOf,
+        join,
         lastIndexOf,
         map,
         materialize,
@@ -443,12 +511,17 @@ declare namespace Functions {
         memoize,
         getMemoizeDefaultOptions,
         min,
+        prepend,
         range,
         reduce,
         repeat_2 as repeat,
+        sequenceEqual,
+        single,
         skip,
         skipWhile,
+        slice,
         some,
+        sum,
         take,
         takeWhile,
         tap,
@@ -492,6 +565,19 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.1
      */
     [Symbol.iterator](): Iterator<T, any, undefined>;
+    /**
+     * Yields the values of the chain, then `value`.
+     * `value` is yielded only when the source ends, so it is never reached on an infinite chain.
+     * @operation `Transformation`
+     * @param value - the value yielded after the last value of the chain
+     * @returns a new chain with the values of this chain followed by `value`
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).append(4).collectToArray(); // [1, 2, 3, 4]
+     * ```
+     * @since 0.8.0
+     */
+    append(value: T): IIterableLinq<T>;
     /**
      * 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,
@@ -508,6 +594,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`
@@ -519,6 +631,21 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.1
      */
     collectToArray(): T[];
+    /**
+     * Yields the values of the chain, then the values of each iterable in `others`, in order.
+     * Each iterable is opened only when the previous one ends, so the iterables after an infinite chain are never read.
+     * Stopping early closes only the iterable being read.
+     * @operation `Transformation`
+     * @param others - the iterables read after the chain; other chains are iterables too
+     * @returns a new chain with the values of this chain followed by the values of `others`
+     * @throws Error if a value of `others` is missing or does not implement `[Symbol.iterator]`
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2]).concat([3], new Set([4, 5])).collectToArray(); // [1, 2, 3, 4, 5]
+     * ```
+     * @since 0.8.0
+     */
+    concat(...others: Iterable<T>[]): IIterableLinq<T>;
     /**
      * Counts the values of the chain; runs the whole chain.
      * @operation `Action`
@@ -762,6 +889,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.
@@ -849,6 +990,19 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.8
      */
     min(comparer?: Comparer<T>): T | undefined;
+    /**
+     * Yields `value`, then the values of the chain.
+     * `value` is yielded before the source is read.
+     * @operation `Transformation`
+     * @param value - the value yielded before the first value of the chain
+     * @returns a new chain with `value` followed by the values of this chain
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).prepend(0).collectToArray(); // [0, 1, 2, 3]
+     * ```
+     * @since 0.8.0
+     */
+    prepend(value: T): IIterableLinq<T>;
     /**
      * Runs the chain and accumulates its values into a single result, starting from the first value.
      * @operation `Action`
@@ -876,6 +1030,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`
@@ -904,6 +1118,24 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.5.0
      */
     skipWhile(predicate: Predicate<T>): IIterableLinq<T>;
+    /**
+     * Yields the values from `start` to `end` (excluded), like `Array.prototype.slice`; a negative index counts from the end.
+     * With non-negative indexes the values are yielded as they are read, and the source is closed at `end`, so `slice` also ends an infinite chain.
+     * A negative `end` yields each value once `-end` more values have been read, keeping only those `-end` values.
+     * A negative `start` runs the whole chain before yielding, keeping only the last `-start` values.
+     * @operation `Transformation`
+     * @param start - an integer, `0` by default; `-1` is the last value
+     * @param end - an integer; the values are yielded up to the end of the chain by default
+     * @returns a new chain with the values from `start` to `end`
+     * @throws Error if `start` or `end` is given and is not an integer (fractions, `NaN` and `Infinity` included)
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 4, 5]).slice(1, 3).collectToArray(); // [2, 3]
+     * IterableLinq.from([1, 2, 3, 4, 5]).slice(-2).collectToArray(); // [4, 5]
+     * ```
+     * @since 0.8.0
+     */
+    slice(start?: number, end?: number): IIterableLinq<T>;
     /**
      * Runs the chain until its first value, then stops and closes the source.
      * @operation `Action`
@@ -928,6 +1160,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 +1352,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.
@@ -1229,6 +1504,22 @@ export declare function override<K extends Extract<keyof IIterableLinq<unknown>,
  */
 export declare type Predicate<T> = (value: T, index: number) => boolean;
 
+/**
+ * Lazily yields `value`, then the values of `iterable`.
+ * `value` is yielded before the source is read.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param value - the value yielded before the first value of the source
+ * @returns a lazy, re-runnable `Iterable` of `value` followed by the values of the source
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.prepend([1, 2, 3], 0)); // [0, 1, 2, 3]
+ * ```
+ * @since 0.8.0
+ */
+declare function prepend<T>(iterable: Iterable<T>, value: T): Iterable<T>;
+
 /**
  * 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`.
@@ -1334,6 +1625,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`
@@ -1366,6 +1728,26 @@ declare function skip<T>(iterable: Iterable<T>, count: number): Iterable<T>;
  */
 declare function skipWhile<T>(iterable: Iterable<T>, predicate: Predicate<T>): Iterable<T>;
 
+/**
+ * Lazily yields the values from `start` to `end` (excluded), like `Array.prototype.slice`; a negative index counts from the end.
+ * With non-negative indexes the values are yielded as they are read, and the source is closed at `end`, so `slice` also ends an infinite source.
+ * A negative `end` yields each value once `-end` more values have been read, keeping only those `-end` values.
+ * A negative `start` reads the whole source before yielding, keeping only the last `-start` values.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param start - an integer, `0` by default; `-1` is the last value
+ * @param end - an integer; the values are yielded up to the end of the source by default
+ * @returns a lazy, re-runnable `Iterable` of the values from `start` to `end`
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `start` or `end` is given and is not an integer (fractions, `NaN` and `Infinity` included)
+ * @example
+ * ```ts
+ * Array.from(Functions.slice([1, 2, 3, 4, 5], 1, 3)); // [2, 3]
+ * Array.from(Functions.slice([1, 2, 3, 4, 5], -2)); // [4, 5]
+ * ```
+ * @since 0.8.0
+ */
+declare function slice<T>(iterable: Iterable<T>, start?: number, end?: number): Iterable<T>;
+
 /**
  * Tells whether `iterable` contains a value; reads one value, then closes the source.
  * @operation `Action`
@@ -1395,6 +1777,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.