iterable-linq-utility 0.10.0 → 0.12.0

package/dist/index.d.cts

@@ -317,12 +317,34 @@ 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 once, at application start-up.
- * @param name - the method name; it must not exist yet (library methods, earlier extensions, `Object.prototype` members)
+ * Declare the method first by augmenting `IIterableLinq`, then register it at application start-up.
+ * Registering a name added by an earlier `extend` again replaces its implementation, so a module that runs twice
+ * (hot module replacement, a test runner that re-imports it) does not throw: the last registration wins.
+ * @param name - the method name; a new name or one added by an earlier `extend`, not a library method or an `Object.prototype` member
  * @param implementation - the method; `this` is the chain, typed `IIterableLinq<unknown>`
- * @throws Error if `name` already exists (use `override` to replace it), is empty, or `implementation` is not a function
+ * @throws Error if `name` is a library method (use `override` to replace it), an `Object.prototype` member or a name used by the chain instances, is empty, or `implementation` is not a function
  * @example
  * ```ts
  * declare module 'iterable-linq-utility' {
@@ -564,6 +586,47 @@ declare function forEachAsync<T>(iterable: Iterable<T>, action: AsyncAction<T>):
  */
 export declare function from<T>(iterable: Iterable<T>): IIterableLinq<T>;
 
+/**
+ * Starts a chain over the properties of `object`: its entries, its keys, its values or its property descriptors.
+ * With the default options it yields what `Object.entries` returns: the own, enumerable, string keys.
+ * - `options.yield`: `'entries'` (default) `[key, value]`, `'keys'`, `'values'`, or `'descriptors'` `[key, descriptor, owner]` without calling the getters.
+ * - `options.inherited` also reads the prototype chain, up to `Object.prototype` excluded; a key is yielded once, from the nearest object that has it, like `for…in`.
+ * - `options.nonEnumerable` also reads the non-enumerable properties, `options.symbols` the symbol keys.
+ * - Each run of the chain reads the object again: the keys of an object when the iteration reaches it, a value when it is yielded.
+ * @param object - the object to read
+ * @param options - `yield`, `inherited`, `nonEnumerable` and `symbols`
+ * @returns a chain of the properties of `object`
+ * @throws Error if `object` is not an object or a function, `options` is not an object, `yield` is not one of its values, or a flag is not a boolean
+ * @example
+ * ```ts
+ * IterableLinq.fromObject({ a: 1, b: 2 }).collectToArray();                    // [['a', 1], ['b', 2]]
+ * IterableLinq.fromObject({ a: 1, b: 2 }, { yield: 'keys' }).collectToArray();   // ['a', 'b']
+ * IterableLinq.fromObject({ a: 1, b: 2 }, { yield: 'values' }).collectToArray(); // [1, 2]
+ * ```
+ * @since 0.11.0
+ */
+export declare function fromObject<O extends object, const Options extends IObjectOptions = IObjectDefaultOptions>(object: O, options?: Options): IIterableLinq<ObjectItem<O, Options>>;
+
+/**
+ * Returns the properties of `object`: its entries, its keys, its values or its property descriptors.
+ * With the default options it yields what `Object.entries` returns: the own, enumerable, string keys.
+ * - `inherited` also reads the prototype chain, up to `Object.prototype` excluded; a key is yielded once, from the nearest object that has it, like `for…in`.
+ * - `nonEnumerable` also reads the non-enumerable properties, `symbols` the symbol keys.
+ * - The keys of an object are read when the iteration reaches it, a value when it is yielded: each run reads the object again.
+ * @operation `Transformation`
+ * @param object - the object to read
+ * @param options - `yield` (`'entries'`, `'keys'`, `'values'` or `'descriptors'`), `inherited`, `nonEnumerable` and `symbols`
+ * @returns a lazy, re-runnable `Iterable` of the properties of `object`
+ * @throws Error if `object` is not an object or a function, `options` is not an object, `yield` is not one of its values, or a flag is not a boolean
+ * @example
+ * ```ts
+ * Array.from(Functions.fromObject({ a: 1, b: 2 })); // [['a', 1], ['b', 2]]
+ * Array.from(Functions.fromObject({ a: 1, b: 2 }, { yield: 'keys' })); // ['a', 'b']
+ * ```
+ * @since 0.11.0
+ */
+declare function fromObject_2<O extends object, const Options extends IObjectOptions = IObjectDefaultOptions>(object: O, options?: Options): Iterable<ObjectItem<O, Options>>;
+
 /**
  * Starts a chain of numbers from 0 up to, but not including, `end`.
  * - `options.step` is the distance between two values (default 1); its sign is ignored, the direction comes from the sign of `end`.
@@ -621,6 +684,7 @@ declare namespace Functions {
         empty_2 as empty,
         entries,
         every,
+        except,
         filter,
         find,
         findIndex,
@@ -630,8 +694,13 @@ declare namespace Functions {
         flatMap,
         forEach,
         forEachAsync,
+        fromObject_2 as fromObject,
+        groupBy,
+        groupJoin,
         includes,
         indexOf,
+        innerJoin,
+        intersect,
         join,
         lastIndexOf,
         map,
@@ -659,6 +728,7 @@ declare namespace Functions {
         takeWhile,
         tap,
         tapChain,
+        union,
         withValue as with,
         zip
     }
@@ -672,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.
@@ -915,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.
@@ -1094,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.
@@ -1120,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`.
@@ -1309,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
@@ -1584,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,
@@ -1661,6 +1898,78 @@ 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
+ */
+export declare interface IObjectDefaultOptions extends IObjectOptions {
+    yield?: 'entries';
+    inherited?: false;
+    nonEnumerable?: false;
+    symbols?: false;
+}
+
+/**
+ * Options of `fromObject`. The defaults read what `Object.keys` reads: the own, enumerable, string keys.
+ * @since 0.11.0
+ */
+export declare interface IObjectOptions {
+    /** `'entries'` (default) yields `[key, value]`, `'keys'` the keys, `'values'` the values, `'descriptors'` `[key, descriptor, owner]` without calling the getters. */
+    yield?: ObjectYield;
+    /** Also reads the properties of the prototype chain, up to `Object.prototype` excluded; defaults to `false`. */
+    inherited?: boolean;
+    /** Also reads the non-enumerable properties; defaults to `false`. */
+    nonEnumerable?: boolean;
+    /** Also reads the symbol keys; defaults to `false`. */
+    symbols?: boolean;
+}
+
 /**
  * Options of `range`.
  * @since 0.1.0
@@ -1811,6 +2120,39 @@ declare function memoize<T>(iterable: Iterable<T>, options?: IMemoizeOptions): I
  */
 declare function min<T>(iterable: Iterable<T>, comparer?: Comparer<T>): T | undefined;
 
+/**
+ * The type of the values of `fromObject(object, options)`, chosen by `options.yield` (default `'entries'`).
+ * @since 0.11.0
+ */
+export declare type ObjectItem<O, Options extends IObjectOptions> = ObjectItemOf<O, Options, Options extends {
+    yield: infer Y;
+} ? Y : Options extends {
+    yield?: infer Y;
+} ? Y | undefined : undefined>;
+
+/** Distributes over `Y`, so a `yield` typed as a union gives the union of the items; `undefined` gives the entries. */
+declare type ObjectItemOf<O, Options extends IObjectOptions, Y> = Y extends 'keys' ? ObjectKey<O, Options> : Y extends 'values' ? ObjectValue<O, Options> : Y extends 'descriptors' ? [ObjectKey<O, Options>, PropertyDescriptor, object] : [ObjectKey<O, Options>, ObjectValue<O, Options>];
+
+/**
+ * The type of the keys `fromObject` yields: the keys of `O` as strings, as they are at runtime,
+ * or `string` (and `symbol`) when the options read keys that `O` does not declare.
+ * @since 0.11.0
+ */
+export declare type ObjectKey<O, Options extends IObjectOptions> = ReadsWide<Options> extends true ? string | (ReadsSymbols<Options> extends true ? symbol : never) : `${Extract<keyof O, string | number>}` | (ReadsSymbols<Options> extends true ? Extract<keyof O, symbol> : never);
+
+/**
+ * The type of the values `fromObject` yields: the values of the keys of `O` it reads, or `unknown`
+ * when the options read keys that `O` does not declare.
+ * @since 0.11.0
+ */
+export declare type ObjectValue<O, Options extends IObjectOptions> = ReadsWide<Options> extends true ? unknown : O[Extract<keyof O, string | number> | (ReadsSymbols<Options> extends true ? Extract<keyof O, symbol> : never)];
+
+/**
+ * What `fromObject` yields for each property.
+ * @since 0.11.0
+ */
+export declare type ObjectYield = 'entries' | 'keys' | 'values' | 'descriptors';
+
 /**
  * Replaces an existing method of every chain: a library method or one added with `extend`.
  * Typical use: a library release adds a method with the same name as one of your extensions,
@@ -1890,6 +2232,21 @@ declare function range(end: number, options?: IRangeOptions): Iterable<number>;
  */
 declare function range(start: number, end: number, options?: IRangeOptions): Iterable<number>;
 
+declare type ReadsSymbols<Options extends IObjectOptions> = Options extends {
+    yield?: unknown;
+    inherited?: unknown;
+    nonEnumerable?: unknown;
+    symbols?: false;
+} ? false : true;
+
+/** `true` when the options may read keys that are not in `keyof O`: inherited or non-enumerable ones. */
+declare type ReadsWide<Options extends IObjectOptions> = Options extends {
+    yield?: unknown;
+    inherited?: false;
+    nonEnumerable?: false;
+    symbols?: unknown;
+} ? false : true;
+
 /**
  * Accumulates the values of `iterable` into a single result, starting from the first value.
  * @operation `Action`
@@ -2016,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
@@ -2317,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`.