iterable-linq-utility 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -317,6 +317,26 @@ declare function entries<T>(iterable: Iterable<T>): Iterable<[number, T]>;
  */
 declare function every<T>(iterable: Iterable<T>, predicate: Predicate<T>): boolean;
 
+/**
+ * Lazily yields the distinct values of `iterable` that are not in `other`, in the order of `iterable`.
+ * Before the first value it reads the whole `other` into a `Set`, so `other` must be finite; each run reads it again.
+ * Values, or the keys returned by `keySelector`, are compared with `SameValueZero`, like `Set`: for each key the first value of `iterable` is yielded.
+ * If `keySelector` throws, or `other` throws, the sources are closed and the error propagates.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param other - the `Iterable` whose values, or keys, are left out
+ * @param keySelector - called with every value of `iterable` and of `other`, and its index in its own source; omitted or `undefined` compares the values
+ * @returns a lazy, re-runnable `Iterable` of the distinct values of `iterable` that are not in `other`
+ * @throws Error if `iterable` or `other` is missing or does not implement `[Symbol.iterator]`, or if a provided `keySelector` is not a function
+ * @example
+ * ```ts
+ * Array.from(Functions.except([1, 2, 2, 3], [3, 4])); // [1, 2]
+ * Array.from(Functions.except([{ id: 1 }, { id: 2 }], [{ id: 2 }], v => v.id)); // [{ id: 1 }]
+ * ```
+ * @since 0.12.0
+ */
+declare function except<T, K>(iterable: Iterable<T>, other: Iterable<T>, keySelector?: Mapper<T, K>): Iterable<T>;
+
 /**
  * Adds a method to every chain, including the chains created before the call.
  * Declare the method first by augmenting `IIterableLinq`, then register it at application start-up.
@@ -664,6 +684,7 @@ declare namespace Functions {
         empty_2 as empty,
         entries,
         every,
+        except,
         filter,
         find,
         findIndex,
@@ -674,8 +695,12 @@ declare namespace Functions {
         forEach,
         forEachAsync,
         fromObject_2 as fromObject,
+        groupBy,
+        groupJoin,
         includes,
         indexOf,
+        innerJoin,
+        intersect,
         join,
         lastIndexOf,
         map,
@@ -703,6 +728,7 @@ declare namespace Functions {
         takeWhile,
         tap,
         tapChain,
+        union,
         withValue as with,
         zip
     }
@@ -716,6 +742,52 @@ export { Functions }
  */
 declare function getMemoizeDefaultOptions(): IMemoizeOptions;
 
+/**
+ * Lazily yields one `[key, values]` pair for each key returned by `keySelector`, in the order of the first appearance of the key;
+ * the values of a group are in the order of the source.
+ * The whole source is read before the first group is yielded, so `groupBy` does not end on an infinite source.
+ * Every iteration reads the source again and builds new arrays.
+ * The keys are compared with `SameValueZero`, like `Map`: `NaN` is one key, `null` and `undefined` are keys too.
+ * If `keySelector` throws, the source is closed and the error propagates.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param keySelector - called with each value and its index; returns the key of the group of the value
+ * @returns a lazy, re-runnable `Iterable` of `[key, values]` pairs
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `keySelector` is not a function
+ * @example
+ * ```ts
+ * Array.from(Functions.groupBy([1, 2, 3, 4, 5], v => v % 2)); // [[1, [1, 3, 5]], [0, [2, 4]]]
+ * ```
+ * @since 0.12.0
+ */
+declare function groupBy<T, K>(iterable: Iterable<T>, keySelector: Mapper<T, K>): Iterable<[K, T[]]>;
+
+/**
+ * Lazily yields `result(outer, inners)` for each value of `iterable`, with the values of `inner` that have the same key,
+ * in the order of `inner`; `inners` is empty when there are none.
+ * Before the first value it reads the whole `inner`, so `inner` must be finite; each run reads it again.
+ * The keys are compared with `SameValueZero`, like `Map`: `NaN` matches `NaN`, and `null` and `undefined` match themselves.
+ * Each call of `result` gets a new array.
+ * If a callback throws, or `inner` throws, the source is closed and the error propagates.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`, the outer values
+ * @param inner - the `Iterable` whose values are joined to the outer values
+ * @param outerKey - called with each value of `iterable` and its index; returns its key
+ * @param innerKey - called with each value of `inner` and its index; returns its key
+ * @param result - called with each outer value and the array of its inner values; returns the value to yield
+ * @returns a lazy, re-runnable `Iterable` with one result for each value of `iterable`
+ * @throws Error if `iterable` or `inner` is missing or does not implement `[Symbol.iterator]`, or if `outerKey`, `innerKey` or `result` is not a function
+ * @example
+ * ```ts
+ * const teams = [{ id: 1, name: 'a' }, { id: 2, name: 'b' }];
+ * const players = [{ team: 1, name: 'x' }, { team: 1, name: 'y' }];
+ * Array.from(Functions.groupJoin(teams, players, t => t.id, p => p.team, (t, ps) => [t.name, ps.length]));
+ * // [['a', 2], ['b', 0]]
+ * ```
+ * @since 0.12.0
+ */
+declare function groupJoin<T, I, K, R>(iterable: Iterable<T>, inner: Iterable<I>, outerKey: Mapper<T, K>, innerKey: Mapper<I, K>, result: (outer: T, inners: I[]) => R): Iterable<R>;
+
 /**
  * Fluent wrapper over an `Iterable`: every call builds a lazy, re-runnable operations chain.
  * Transformations and taps return a new `IIterableLinq`; actions run the chain and return a result.
@@ -959,6 +1031,24 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.5.0
      */
     every(predicate: Predicate<T>): boolean;
+    /**
+     * Yields the distinct values of the chain that are not in `other`, in the order of the chain.
+     * Before the first value it reads the whole `other` into a `Set`, so `other` must be finite; each run reads it again.
+     * Values, or the keys returned by `keySelector`, are compared with `SameValueZero`, like `Set`: for each key the first value is yielded.
+     * If `keySelector` throws, or `other` throws, the sources are closed and the error propagates.
+     * @operation `Transformation`
+     * @param other - the `Iterable` whose values, or keys, are left out
+     * @param keySelector - called with every value of the chain and of `other`, and its index in its own source; omitted or `undefined` compares the values
+     * @returns a new lazy, re-runnable chain of the distinct values that are not in `other`
+     * @throws Error if `other` is missing or does not implement `[Symbol.iterator]`, or if a provided `keySelector` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 2, 3]).except([3, 4]).collectToArray(); // [1, 2]
+     * IterableLinq.from([{ id: 1 }, { id: 2 }]).except([{ id: 2 }], v => v.id).collectToArray(); // [{ id: 1 }]
+     * ```
+     * @since 0.12.0
+     */
+    except<K>(other: Iterable<T>, keySelector?: Mapper<T, K>): IIterableLinq<T>;
     /**
      * Keeps the values accepted by a type guard and narrows their type.
      * If `predicate` throws, the source is closed and the error propagates.
@@ -1138,6 +1228,48 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.11
      */
     forEachAsync(action: AsyncAction<T>): Promise<Unit>;
+    /**
+     * Yields one `[key, values]` pair for each key returned by `keySelector`, in the order of the first appearance of the key;
+     * the values of a group are in the order of the chain.
+     * The whole chain is read before the first group is yielded, so `groupBy` does not end on an infinite chain;
+     * every run reads the chain again and builds new arrays.
+     * The keys are compared with `SameValueZero`, like `Map`: `NaN` is one key, `null` and `undefined` are keys too.
+     * If `keySelector` throws, the source is closed and the error propagates.
+     * @operation `Transformation`
+     * @param keySelector - called with each value and its index; returns the key of the group of the value
+     * @returns a new chain of `[key, values]` pairs
+     * @throws Error if `keySelector` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 4, 5]).groupBy(v => v % 2).collectToArray(); // [[1, [1, 3, 5]], [0, [2, 4]]]
+     * ```
+     * @since 0.12.0
+     */
+    groupBy<K>(keySelector: Mapper<T, K>): IIterableLinq<[K, T[]]>;
+    /**
+     * Yields `result(outer, inners)` for each value of the chain, with the values of `inner` that have the same key,
+     * in the order of `inner`; `inners` is empty when there are none. Like LINQ `GroupJoin`.
+     * Before the first value it reads the whole `inner`, so `inner` must be finite; each run reads it again.
+     * The keys are compared with `SameValueZero`, like `Map`: `NaN` matches `NaN`, and `null` and `undefined` match themselves.
+     * Each call of `result` gets a new array.
+     * If a callback throws, or `inner` throws, the source is closed and the error propagates.
+     * @operation `Transformation`
+     * @param inner - the `Iterable` whose values are joined to the values of the chain
+     * @param outerKey - called with each value of the chain and its index; returns its key
+     * @param innerKey - called with each value of `inner` and its index; returns its key
+     * @param result - called with each value of the chain and the array of its inner values; returns the value to yield
+     * @returns a new chain with one result for each value of the chain
+     * @throws Error if `inner` is not iterable, or if `outerKey`, `innerKey` or `result` is not a function
+     * @example
+     * ```ts
+     * const players = [{ team: 1, name: 'x' }, { team: 1, name: 'y' }];
+     * IterableLinq.from([{ id: 1, name: 'a' }, { id: 2, name: 'b' }])
+     * 	.groupJoin(players, t => t.id, p => p.team, (t, ps) => [t.name, ps.length])
+     * 	.collectToArray(); // [['a', 2], ['b', 0]]
+     * ```
+     * @since 0.12.0
+     */
+    groupJoin<I, K, R>(inner: Iterable<I>, outerKey: Mapper<T, K>, innerKey: Mapper<I, K>, result: (outer: T, inners: I[]) => R): IIterableLinq<R>;
     /**
      * Tells whether the chain contains `value`, compared with `SameValueZero` like `Array.prototype.includes`;
      * stops and closes the source at the first match.
@@ -1164,6 +1296,48 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.6.0
      */
     indexOf(value: T): number;
+    /**
+     * Yields `result(outer, inner)` for each pair of a value of the chain and a value of `inner` with the same key:
+     * in the order of the chain, and for each value of the chain in the order of `inner`. A value without a match yields nothing.
+     * Like LINQ `Join`; named `innerJoin` because `join` is the string join of `Array.prototype`.
+     * Before the first value it reads the whole `inner`, so `inner` must be finite; each run reads it again.
+     * The keys are compared with `SameValueZero`, like `Map`: `NaN` matches `NaN`, and `null` and `undefined` match themselves.
+     * If a callback throws, or `inner` throws, the source is closed and the error propagates.
+     * @operation `Transformation`
+     * @param inner - the `Iterable` whose values are joined to the values of the chain
+     * @param outerKey - called with each value of the chain and its index; returns its key
+     * @param innerKey - called with each value of `inner` and its index; returns its key
+     * @param result - called with each pair of values with the same key; returns the value to yield
+     * @returns a new chain with one result for each pair of values with the same key
+     * @throws Error if `inner` is not iterable, or if `outerKey`, `innerKey` or `result` is not a function
+     * @example
+     * ```ts
+     * const players = [{ team: 1, name: 'x' }, { team: 1, name: 'y' }];
+     * IterableLinq.from([{ id: 1, name: 'a' }, { id: 2, name: 'b' }])
+     * 	.innerJoin(players, t => t.id, p => p.team, (t, p) => `${t.name}-${p.name}`)
+     * 	.collectToArray(); // ['a-x', 'a-y']
+     * ```
+     * @since 0.12.0
+     */
+    innerJoin<I, K, R>(inner: Iterable<I>, outerKey: Mapper<T, K>, innerKey: Mapper<I, K>, result: (outer: T, inner: I) => R): IIterableLinq<R>;
+    /**
+     * Yields the distinct values of the chain that are also in `other`, in the order of the chain.
+     * Before the first value it reads the whole `other` into a `Set`, so `other` must be finite; each run reads it again.
+     * Values, or the keys returned by `keySelector`, are compared with `SameValueZero`, like `Set`: for each key the first value is yielded.
+     * If `keySelector` throws, or `other` throws, the sources are closed and the error propagates.
+     * @operation `Transformation`
+     * @param other - the `Iterable` whose values, or keys, are kept
+     * @param keySelector - called with every value of the chain and of `other`, and its index in its own source; omitted or `undefined` compares the values
+     * @returns a new lazy, re-runnable chain of the distinct values that are in `other`
+     * @throws Error if `other` is missing or does not implement `[Symbol.iterator]`, or if a provided `keySelector` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 2, 3]).intersect([2, 3, 4]).collectToArray(); // [2, 3]
+     * IterableLinq.from([{ id: 1 }, { id: 2 }]).intersect([{ id: 2 }], v => v.id).collectToArray(); // [{ id: 2 }]
+     * ```
+     * @since 0.12.0
+     */
+    intersect<K>(other: Iterable<T>, keySelector?: Mapper<T, K>): IIterableLinq<T>;
     /**
      * 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`.
@@ -1353,12 +1527,13 @@ export declare interface IIterableLinqBase<T> {
      * 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 `===`
+     * @param equals - called with a value of the chain and the value of `other` at the same position; defaults to `SameValueZero`, like `Set` and `Map`: `NaN` equals `NaN`, `+0` equals `-0`, objects are compared by reference
      * @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([NaN]).sequenceEqual([NaN]); // true
      * IterableLinq.from(['a', 'bb']).sequenceEqual(['x', 'yy'], (a, b) => a.length === b.length); // true
      * ```
      * @since 0.7.0
@@ -1628,6 +1803,24 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.10
      */
     tapChainCreation(chainCreationTapper: (chain: IIterableLinq<T>) => Unit): IIterableLinq<T>;
+    /**
+     * Yields the distinct values of the chain, then the values of `other` not yielded yet.
+     * `other` is opened only when the chain ends, so after an infinite chain it is never read; stopping early closes only the source being read.
+     * Values, or the keys returned by `keySelector`, are compared with `SameValueZero`, like `Set`: for each key the first value is yielded.
+     * If `keySelector` throws, the source being read is closed and the error propagates.
+     * @operation `Transformation`
+     * @param other - the `Iterable` read after the chain
+     * @param keySelector - called with every value and its index in its own source (from 0 again for `other`); omitted or `undefined` compares the values
+     * @returns a new lazy, re-runnable chain of the distinct values of the chain and of `other`
+     * @throws Error if `other` is missing or does not implement `[Symbol.iterator]`, or if a provided `keySelector` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 2]).union([2, 3]).collectToArray(); // [1, 2, 3]
+     * IterableLinq.from([{ id: 1 }]).union([{ id: 1 }, { id: 2 }], v => v.id).collectToArray(); // [{ id: 1 }, { id: 2 }]
+     * ```
+     * @since 0.12.0
+     */
+    union<K>(other: Iterable<T>, keySelector?: Mapper<T, K>): IIterableLinq<T>;
     /**
      * Lazily yields the values of the chain, with `value` in place of the value at `index`, like `Array.prototype.with`; a negative index counts from the end.
      * A non-negative index yields the values as they are read. A negative index yields each value once `-index` more values have been read,
@@ -1705,6 +1898,52 @@ declare function includes<T>(iterable: Iterable<T>, value: T): boolean;
  */
 declare function indexOf<T>(iterable: Iterable<T>, value: T): number;
 
+/**
+ * Lazily yields `result(outer, inner)` for each pair of a value of `iterable` and a value of `inner` with the same key:
+ * in the order of `iterable`, and for each outer value in the order of `inner`. An outer value without a match yields nothing.
+ * Named `innerJoin` because `join` is the string join of `Array.prototype`.
+ * Before the first value it reads the whole `inner`, so `inner` must be finite; each run reads it again.
+ * The keys are compared with `SameValueZero`, like `Map`: `NaN` matches `NaN`, and `null` and `undefined` match themselves.
+ * If a callback throws, or `inner` throws, the source is closed and the error propagates.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`, the outer values
+ * @param inner - the `Iterable` whose values are joined to the outer values
+ * @param outerKey - called with each value of `iterable` and its index; returns its key
+ * @param innerKey - called with each value of `inner` and its index; returns its key
+ * @param result - called with each pair of values with the same key; returns the value to yield
+ * @returns a lazy, re-runnable `Iterable` with one result for each pair of values with the same key
+ * @throws Error if `iterable` or `inner` is missing or does not implement `[Symbol.iterator]`, or if `outerKey`, `innerKey` or `result` is not a function
+ * @example
+ * ```ts
+ * const teams = [{ id: 1, name: 'a' }, { id: 2, name: 'b' }];
+ * const players = [{ team: 1, name: 'x' }, { team: 1, name: 'y' }];
+ * Array.from(Functions.innerJoin(teams, players, t => t.id, p => p.team, (t, p) => `${t.name}-${p.name}`));
+ * // ['a-x', 'a-y']
+ * ```
+ * @since 0.12.0
+ */
+declare function innerJoin<T, I, K, R>(iterable: Iterable<T>, inner: Iterable<I>, outerKey: Mapper<T, K>, innerKey: Mapper<I, K>, result: (outer: T, inner: I) => R): Iterable<R>;
+
+/**
+ * Lazily yields the distinct values of `iterable` that are also in `other`, in the order of `iterable`.
+ * Before the first value it reads the whole `other` into a `Set`, so `other` must be finite; each run reads it again.
+ * Values, or the keys returned by `keySelector`, are compared with `SameValueZero`, like `Set`: for each key the first value of `iterable` is yielded.
+ * If `keySelector` throws, or `other` throws, the sources are closed and the error propagates.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param other - the `Iterable` whose values, or keys, are kept
+ * @param keySelector - called with every value of `iterable` and of `other`, and its index in its own source; omitted or `undefined` compares the values
+ * @returns a lazy, re-runnable `Iterable` of the distinct values of `iterable` that are in `other`
+ * @throws Error if `iterable` or `other` is missing or does not implement `[Symbol.iterator]`, or if a provided `keySelector` is not a function
+ * @example
+ * ```ts
+ * Array.from(Functions.intersect([1, 2, 2, 3], [2, 3, 4])); // [2, 3]
+ * Array.from(Functions.intersect([{ id: 1 }, { id: 2 }], [{ id: 2 }], v => v.id)); // [{ id: 2 }]
+ * ```
+ * @since 0.12.0
+ */
+declare function intersect<T, K>(iterable: Iterable<T>, other: Iterable<T>, keySelector?: Mapper<T, K>): Iterable<T>;
+
 /**
  * The options of `fromObject` when none are given: the type of the values follows `Object.entries`.
  * @since 0.11.0
@@ -2134,13 +2373,14 @@ declare function reverse<T>(iterable: Iterable<T>): Iterable<T>;
  * @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 `===`
+ * @param equals - called with a value of `iterable` and the value of `other` at the same position; defaults to `SameValueZero`, like `Set` and `Map`: `NaN` equals `NaN`, `+0` equals `-0`, objects are compared by reference
  * @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([NaN], [NaN]); // true
  * Functions.sequenceEqual([{ id: 1 }], [{ id: 1 }], (a, b) => a.id === b.id); // true
  * ```
  * @since 0.7.0
@@ -2435,6 +2675,26 @@ declare function tapChain<T>(iterable: Iterable<T>, tapper: Tapper<Iterable<T>>)
  */
 export declare type Tapper<T> = (value: T, index: number) => Unit;
 
+/**
+ * Lazily yields the distinct values of `iterable`, then the values of `other` not yielded yet.
+ * `other` is opened only when `iterable` ends, so after an infinite source it is never read; stopping early closes only the source being read.
+ * Values, or the keys returned by `keySelector`, are compared with `SameValueZero`, like `Set`: for each key the first value is yielded.
+ * If `keySelector` throws, the source being read is closed and the error propagates.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param other - the `Iterable` read after the source
+ * @param keySelector - called with every value and its index in its own source (from 0 again for `other`); omitted or `undefined` compares the values
+ * @returns a lazy, re-runnable `Iterable` of the distinct values of `iterable` and `other`
+ * @throws Error if `iterable` or `other` is missing or does not implement `[Symbol.iterator]`, or if a provided `keySelector` is not a function
+ * @example
+ * ```ts
+ * Array.from(Functions.union([1, 2, 2], [2, 3])); // [1, 2, 3]
+ * Array.from(Functions.union([{ id: 1 }], [{ id: 1 }, { id: 2 }], v => v.id)); // [{ id: 1 }, { id: 2 }]
+ * ```
+ * @since 0.12.0
+ */
+declare function union<T, K>(iterable: Iterable<T>, other: Iterable<T>, keySelector?: Mapper<T, K>): Iterable<T>;
+
 /**
  * The type with exactly one value, `unit()`: what an action or a tapper returns when it has nothing to return.
  * It is nominal: no other value (numbers, strings, objects, `\{\}`) is assignable to `Unit`.