iterable-linq-utility 0.9.0 → 0.10.0

package/dist/index.d.cts

@@ -86,6 +86,22 @@ declare function average<T>(iterable: Iterable<T>, selector: Mapper<T, number> |
  */
 export declare type ChainMethod = (this: IIterableLinq<unknown>, ...args: any[]) => unknown;
 
+/**
+ * Lazily yields arrays of `size` values; the last array has the remaining values and can be shorter.
+ * Each array is new, and is yielded once its values have been read, so `chunk` works with infinite sources.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param size - how many values in each array; must be a positive integer
+ * @returns a lazy, re-runnable `Iterable` of arrays of at most `size` values
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `size` is not a positive integer (`0`, fractions, `NaN` and `Infinity` included)
+ * @example
+ * ```ts
+ * Array.from(Functions.chunk([1, 2, 3, 4, 5], 2)); // [[1, 2], [3, 4], [5]]
+ * ```
+ * @since 0.10.0
+ */
+declare function chunk<T>(iterable: Iterable<T>, size: number): Iterable<T[]>;
+
 /**
  * Collects the values of `iterable` into an `Array`.
  * @operation `Action`
@@ -100,6 +116,55 @@ export declare type ChainMethod = (this: IIterableLinq<unknown>, ...args: any[])
  */
 declare function collectToArray<T>(iterable: Iterable<T>): T[];
 
+/**
+ * Collects the values of `iterable` into a `Map`, with the key returned by `keySelector`.
+ * A later value with the same key (`SameValueZero`, as in `Map`) replaces the earlier one.
+ * If `keySelector` throws, the source is closed and the error propagates.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param keySelector - called with each value and its index; returns the key of the value
+ * @returns a `Map` from each key to the last value with that key; an empty `Map` when `iterable` is empty
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `keySelector` is not a function
+ * @example
+ * ```ts
+ * Functions.collectToMap([{ id: 1, name: 'a' }, { id: 2, name: 'b' }], v => v.id); // Map { 1 => { id: 1, name: 'a' }, 2 => { id: 2, name: 'b' } }
+ * ```
+ * @since 0.10.0
+ */
+declare function collectToMap<T, K>(iterable: Iterable<T>, keySelector: Mapper<T, K>): Map<K, T>;
+
+/**
+ * Collects the values of `iterable` into a `Map`, with the key returned by `keySelector` and the value returned by `valueSelector`.
+ * A later value with the same key (`SameValueZero`, as in `Map`) replaces the earlier one.
+ * If `keySelector` or `valueSelector` throws, the source is closed and the error propagates.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param keySelector - called with each value and its index; returns the key of the value
+ * @param valueSelector - called with each value and its index; returns the value to store; `undefined` stores the value itself
+ * @returns a `Map` from each key to the value selected from the last value with that key; an empty `Map` when `iterable` is empty
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, if `keySelector` is not a function, or if a provided `valueSelector` is not a function
+ * @example
+ * ```ts
+ * Functions.collectToMap([{ id: 1, name: 'a' }, { id: 2, name: 'b' }], v => v.id, v => v.name); // Map { 1 => 'a', 2 => 'b' }
+ * ```
+ * @since 0.10.0
+ */
+declare function collectToMap<T, K, V>(iterable: Iterable<T>, keySelector: Mapper<T, K>, valueSelector: Mapper<T, V> | undefined): Map<K, V>;
+
+/**
+ * Collects the values of `iterable` into a `Set`: a value equal to an earlier one (`SameValueZero`, as in `Set`) is left out.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @returns the distinct values, in the order of their first occurrence; an empty `Set` when `iterable` is empty
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Functions.collectToSet([1, 2, 1, 3]); // Set { 1, 2, 3 }
+ * ```
+ * @since 0.10.0
+ */
+declare function collectToSet<T>(iterable: Iterable<T>): Set<T>;
+
 /**
  * How `min` and `max` compare two values. One of:
  * - a compare function `(a, b) => number`: negative if `a` comes before `b`, 0 if they are equal, positive if `a` comes after `b`;
@@ -166,6 +231,22 @@ declare function count<T>(iterable: Iterable<T>): number;
  */
 declare function count<T>(iterable: Iterable<T>, predicate: Predicate<T> | undefined): number;
 
+/**
+ * Lazily yields the values of `iterable`, or only `value` when `iterable` is empty.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param value - the value yielded when `iterable` has no values
+ * @returns a lazy, re-runnable `Iterable` of the values, or of `value` alone
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.defaultIfEmpty([1, 2], 0)); // [1, 2]
+ * Array.from(Functions.defaultIfEmpty([], 0)); // [0]
+ * ```
+ * @since 0.10.0
+ */
+declare function defaultIfEmpty<T>(iterable: Iterable<T>, value: T): Iterable<T>;
+
 /**
  * Lazily yields the first value for each distinct value or selected key, in source order.
  * Keys use `SameValueZero`, like `Set`; original values are preserved.
@@ -207,6 +288,20 @@ export declare function empty<T>(): IIterableLinq<T>;
  */
 declare function empty_2<T>(): Iterable<T>;
 
+/**
+ * Lazily yields `[index, value]` pairs, like `Array.prototype.entries`.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @returns a lazy, re-runnable `Iterable` of pairs of the index, from 0, and the value
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.entries(['a', 'b'])); // [[0, 'a'], [1, 'b']]
+ * ```
+ * @since 0.10.0
+ */
+declare function entries<T>(iterable: Iterable<T>): Iterable<[number, T]>;
+
 /**
  * Tells whether every value satisfies `predicate`; stops and closes the source at the first rejected value.
  * @operation `Action`
@@ -372,6 +467,34 @@ declare function findLast<T>(iterable: Iterable<T>, predicate: Predicate<T>): T
  */
 declare function findLastIndex<T>(iterable: Iterable<T>, predicate: Predicate<T>): number;
 
+/**
+ * Lazily flattens the nested iterables of `iterable` up to `depth` levels, like `Array.prototype.flat` for any `Iterable`.
+ * Strings, primitive or `String` objects, are not flattened. Nested arrays are read by index: their `[Symbol.iterator]` is not called.
+ * If a nested iterable throws, the iterables that contain it and the source are closed, and the error propagates.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param depth - how many levels to flatten, `1` by default; a non-negative integer or `Infinity`
+ * @returns a lazy, re-runnable `Iterable` of the flattened values
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `depth` is not a non-negative integer or `Infinity`
+ * @example
+ * ```ts
+ * Array.from(Functions.flat([1, [2, [3]], new Set([4])])); // [1, 2, [3], 4]
+ * Array.from(Functions.flat([1, [2, [3]]], Infinity)); // [1, 2, 3]
+ * ```
+ * @since 0.10.0
+ */
+declare function flat<T, D extends number = 1>(iterable: Iterable<T>, depth?: D): Iterable<FlatIterable<T, D>>;
+
+/**
+ * The type of the values of `flat` with `Depth` levels: like `FlatArray`, for any `Iterable` except strings.
+ * A `Depth` of type `number` (for example `Infinity`) gives a wide type, as `FlatArray` does.
+ * @since 0.10.0
+ */
+export declare type FlatIterable<T, Depth extends number> = {
+    done: T;
+    recur: T extends string | String ? T : T extends Iterable<infer U> ? FlatIterable<U, [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20][Depth]> : T;
+}[Depth extends 0 ? 'done' : 'recur'];
+
 /**
  * Lazily maps each value to an `Iterable` and flattens the results.
  * Each inner `Iterable` is read completely before the next value is mapped.
@@ -487,17 +610,23 @@ declare namespace Functions {
         append,
         at,
         average,
+        chunk,
         collectToArray,
+        collectToMap,
+        collectToSet,
         concat,
         count,
+        defaultIfEmpty,
         distinct,
         empty_2 as empty,
+        entries,
         every,
         filter,
         find,
         findIndex,
         findLast,
         findLastIndex,
+        flat,
         flatMap,
         forEach,
         forEachAsync,
@@ -514,6 +643,7 @@ declare namespace Functions {
         prepend,
         range,
         reduce,
+        reduceRight,
         repeat_2 as repeat,
         reverse,
         sequenceEqual,
@@ -528,7 +658,9 @@ declare namespace Functions {
         takeLast,
         takeWhile,
         tap,
-        tapChain
+        tapChain,
+        withValue as with,
+        zip
     }
 }
 export { Functions }
@@ -623,6 +755,20 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.7.0
      */
     average(selector: Mapper<T, number> | undefined): number | undefined;
+    /**
+     * Lazily yields arrays of `size` values; the last array has the remaining values and can be shorter.
+     * Each array is new, and is yielded once its values have been read, so `chunk` works with infinite chains.
+     * @operation `Transformation`
+     * @param size - how many values in each array; must be a positive integer
+     * @returns a lazy, re-runnable chain of arrays of at most `size` values
+     * @throws Error if `size` is not a positive integer (`0`, fractions, `NaN` and `Infinity` included)
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 4, 5]).chunk(2).collectToArray(); // [[1, 2], [3, 4], [5]]
+     * ```
+     * @since 0.10.0
+     */
+    chunk(size: number): IIterableLinq<T[]>;
     /**
      * Runs the chain and collects its values into an `Array`.
      * @operation `Action`
@@ -634,6 +780,48 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.1
      */
     collectToArray(): T[];
+    /**
+     * Runs the chain and collects its values into a `Map`, with the key returned by `keySelector`.
+     * A later value with the same key (`SameValueZero`, as in `Map`) replaces the earlier one.
+     * If `keySelector` throws, the source is closed and the error propagates.
+     * @operation `Action`
+     * @param keySelector - called with each value and its index; returns the key of the value
+     * @returns a `Map` from each key to the last value with that key; an empty `Map` when the chain is empty
+     * @throws Error if `keySelector` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([{ id: 1, name: 'a' }, { id: 2, name: 'b' }]).collectToMap(v => v.id); // Map { 1 => { id: 1, name: 'a' }, 2 => { id: 2, name: 'b' } }
+     * ```
+     * @since 0.10.0
+     */
+    collectToMap<K>(keySelector: Mapper<T, K>): Map<K, T>;
+    /**
+     * Runs the chain and collects its values into a `Map`, with the key returned by `keySelector` and the value returned by `valueSelector`.
+     * A later value with the same key (`SameValueZero`, as in `Map`) replaces the earlier one.
+     * If `keySelector` or `valueSelector` throws, the source is closed and the error propagates.
+     * @operation `Action`
+     * @param keySelector - called with each value and its index; returns the key of the value
+     * @param valueSelector - called with each value and its index; returns the value to store; `undefined` stores the value itself
+     * @returns a `Map` from each key to the value selected from the last value with that key; an empty `Map` when the chain is empty
+     * @throws Error if `keySelector` is not a function, or if a provided `valueSelector` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([{ id: 1, name: 'a' }, { id: 2, name: 'b' }]).collectToMap(v => v.id, v => v.name); // Map { 1 => 'a', 2 => 'b' }
+     * ```
+     * @since 0.10.0
+     */
+    collectToMap<K, V>(keySelector: Mapper<T, K>, valueSelector: Mapper<T, V> | undefined): Map<K, V>;
+    /**
+     * Runs the chain and collects its values into a `Set`: a value equal to an earlier one (`SameValueZero`, as in `Set`) is left out.
+     * @operation `Action`
+     * @returns the distinct values, in the order of their first occurrence; an empty `Set` when the chain is empty
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 1, 3]).collectToSet(); // Set { 1, 2, 3 }
+     * ```
+     * @since 0.10.0
+     */
+    collectToSet(): Set<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.
@@ -674,6 +862,19 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.5.0
      */
     count(predicate: Predicate<T> | undefined): number;
+    /**
+     * Lazily yields the values of the chain, or only `value` when the chain is empty.
+     * @operation `Transformation`
+     * @param value - the value yielded when the chain has no values
+     * @returns a lazy, re-runnable chain of the values, or of `value` alone
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2]).defaultIfEmpty(0).collectToArray(); // [1, 2]
+     * IterableLinq.empty<number>().defaultIfEmpty(0).collectToArray(); // [0]
+     * ```
+     * @since 0.10.0
+     */
+    defaultIfEmpty(value: T): IIterableLinq<T>;
     /**
      * Yields the first value for each distinct value or selected key, in source order.
      * Keys use `SameValueZero`, like `Set`; original values are preserved.
@@ -690,6 +891,17 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.5.0
      */
     distinct<K>(keySelector?: Mapper<T, K>): IIterableLinq<T>;
+    /**
+     * Lazily yields `[index, value]` pairs, like `Array.prototype.entries`.
+     * @operation `Transformation`
+     * @returns a lazy, re-runnable chain of pairs of the index, from 0, and the value
+     * @example
+     * ```ts
+     * IterableLinq.from(['a', 'b']).entries().collectToArray(); // [[0, 'a'], [1, 'b']]
+     * ```
+     * @since 0.10.0
+     */
+    entries(): IIterableLinq<[number, T]>;
     /**
      * Tells whether every value satisfies `predicate`; stops and closes the source at the first rejected value.
      * @operation `Action`
@@ -815,6 +1027,22 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.6.0
      */
     findLastIndex(predicate: Predicate<T>): number;
+    /**
+     * Lazily flattens the nested iterables of the chain up to `depth` levels, like `Array.prototype.flat` for any `Iterable`.
+     * Strings, primitive or `String` objects, are not flattened. Nested arrays are read by index: their `[Symbol.iterator]` is not called.
+     * If a nested iterable throws, the iterables that contain it and the source are closed, and the error propagates.
+     * @operation `Transformation`
+     * @param depth - how many levels to flatten, `1` by default; a non-negative integer or `Infinity`
+     * @returns a lazy, re-runnable chain of the flattened values
+     * @throws Error if `depth` is not a non-negative integer or `Infinity`
+     * @example
+     * ```ts
+     * IterableLinq.from([1, [2, [3]], new Set([4])]).flat().collectToArray(); // [1, 2, [3], 4]
+     * IterableLinq.from([1, [2, [3]]]).flat(Infinity).collectToArray(); // [1, 2, 3]
+     * ```
+     * @since 0.10.0
+     */
+    flat<D extends number = 1>(depth?: D): IIterableLinq<FlatIterable<T, D>>;
     /**
      * 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.
@@ -1033,6 +1261,35 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.10
      */
     reduce<R>(neutralElement: R, reducer: Reducer<T, R>): R;
+    /**
+     * Runs the chain and accumulates its values into a single result, from the last value to the first, starting from the last value.
+     * The whole chain runs before `reducer` is called.
+     * @operation `Action`
+     * @param reducer - called with the accumulator, each value from the second-to-last one back to the first, and its index in the chain; returns the new accumulator
+     * @returns the final accumulator; the only value when the chain has one value, without calling `reducer`
+     * @throws Error if the chain is empty or if `reducer` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from(['a', 'b', 'c']).reduceRight((acc, v) => acc + v); // 'cba'
+     * ```
+     * @since 0.10.0
+     */
+    reduceRight(reducer: Reducer<T, T>): T;
+    /**
+     * Runs the chain and accumulates its values into a single result, from the last value to the first.
+     * The whole chain runs before `reducer` is called.
+     * @operation `Action`
+     * @param neutralElement - the initial accumulator (the seed)
+     * @param reducer - called with the accumulator, each value from the last one back to the first, and its index in the chain; returns the new accumulator
+     * @returns the final accumulator; `neutralElement` when the chain is empty
+     * @throws Error if `reducer` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).reduceRight('', (acc, v) => acc + v); // '321'
+     * ```
+     * @since 0.10.0
+     */
+    reduceRight<R>(neutralElement: R, reducer: Reducer<T, R>): R;
     /**
      * Lazily yields the values in reverse order. Unlike `Array.prototype.reverse`, the source is not changed.
      * The whole chain runs before the first value is yielded, so `reverse` does not end on an infinite chain.
@@ -1327,6 +1584,40 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.10
      */
     tapChainCreation(chainCreationTapper: (chain: IIterableLinq<T>) => Unit): 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,
+     * keeping only those `-index` values.
+     * @operation `Transformation`
+     * @param index - an integer; `-1` is the last value
+     * @param value - the value yielded in place of the value at `index`
+     * @returns a lazy, re-runnable chain of the values, with `value` at `index`
+     * @throws Error if `index` is not an integer (fractions, `NaN` and `Infinity` included); when the chain ends, if it has no value at `index`
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).with(1, 20).collectToArray(); // [1, 20, 3]
+     * IterableLinq.from([1, 2, 3]).with(-1, 30).collectToArray(); // [1, 2, 30]
+     * ```
+     * @since 0.10.0
+     */
+    with(index: number, value: T): IIterableLinq<T>;
+    /**
+     * Lazily yields tuples of the values at the same position in the chain and in each of `others`.
+     * It stops at the end of the shortest iterable and closes the others; if an iterable throws, the others are closed and the error propagates.
+     * @operation `Transformation`
+     * @param others - the iterables read side by side with the chain
+     * @returns a lazy, re-runnable chain of tuples, as many as the values of the shortest iterable
+     * @throws Error if a value of `others` is missing or does not implement `[Symbol.iterator]`
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).zip(['a', 'b']).collectToArray(); // [[1, 'a'], [2, 'b']]
+     * IterableLinq.from([1, 2]).zip(['a', 'b'], [true, false]).collectToArray(); // [[1, 'a', true], [2, 'b', false]]
+     * ```
+     * @since 0.10.0
+     */
+    zip<U extends unknown[]>(...others: {
+        [K in keyof U]: Iterable<U[K]>;
+    }): IIterableLinq<[T, ...U]>;
 }
 
 /**
@@ -1640,6 +1931,39 @@ declare function reduce<T, R>(iterable: Iterable<T>, neutralElement: R, reducer:
  */
 export declare type Reducer<T, R> = (acc: R, value: T, index: number) => R;
 
+/**
+ * Accumulates the values of `iterable` into a single result, from the last value to the first, starting from the last value.
+ * The whole source is read before `reducer` is called.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param reducer - called with the accumulator, each value from the second-to-last one back to the first, and its index in the source; returns the new accumulator
+ * @returns the final accumulator; the only value when `iterable` has one value, without calling `reducer`
+ * @throws Error if `iterable` is missing, does not implement `[Symbol.iterator]` or is empty, or if `reducer` is not a function
+ * @example
+ * ```ts
+ * Functions.reduceRight(['a', 'b', 'c'], (acc, v) => acc + v); // 'cba'
+ * ```
+ * @since 0.10.0
+ */
+declare function reduceRight<T>(iterable: Iterable<T>, reducer: Reducer<T, T>): T;
+
+/**
+ * Accumulates the values of `iterable` into a single result, from the last value to the first.
+ * The whole source is read before `reducer` is called.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param neutralElement - the initial accumulator (the seed)
+ * @param reducer - called with the accumulator, each value from the last one back to the first, and its index in the source; returns the new accumulator
+ * @returns the final accumulator; `neutralElement` when `iterable` is empty
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `reducer` is not a function
+ * @example
+ * ```ts
+ * Functions.reduceRight([1, 2, 3], '', (acc, v) => acc + v); // '321'
+ * ```
+ * @since 0.10.0
+ */
+declare function reduceRight<T, R>(iterable: Iterable<T>, neutralElement: R, reducer: Reducer<T, R>): R;
+
 /**
  * Starts a chain that yields `value` `count` times.
  * @param value - the value to repeat
@@ -2023,4 +2347,44 @@ export declare class Unit {
  */
 export declare function unit(): Unit;
 
+/**
+ * Lazily yields the values of `iterable`, 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,
+ * keeping only those `-index` values.
+ * Exported as `with`, a reserved word that cannot name a function declaration.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param index - an integer; `-1` is the last value
+ * @param value - the value yielded in place of the value at `index`
+ * @returns a lazy, re-runnable `Iterable` of the values, with `value` at `index`
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `index` is not an integer (fractions, `NaN` and `Infinity` included);
+ * when the source ends, if it has no value at `index`
+ * @example
+ * ```ts
+ * Array.from(Functions.with([1, 2, 3], 1, 20)); // [1, 20, 3]
+ * Array.from(Functions.with([1, 2, 3], -1, 30)); // [1, 2, 30]
+ * ```
+ * @since 0.10.0
+ */
+declare function withValue<T>(iterable: Iterable<T>, index: number, value: T): Iterable<T>;
+
+/**
+ * Lazily yields tuples of the values at the same position in `iterable` and in each of `others`.
+ * It stops at the end of the shortest iterable and closes the others; if an iterable throws, the others are closed and the error propagates.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param others - the iterables read side by side with the source
+ * @returns a lazy, re-runnable `Iterable` of tuples, as many as the values of the shortest iterable
+ * @throws Error if `iterable` or a value of `others` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.zip([1, 2, 3], ['a', 'b'])); // [[1, 'a'], [2, 'b']]
+ * Array.from(Functions.zip([1, 2], ['a', 'b'], [true, false])); // [[1, 'a', true], [2, 'b', false]]
+ * ```
+ * @since 0.10.0
+ */
+declare function zip<T, U extends unknown[]>(iterable: Iterable<T>, ...others: {
+    [K in keyof U]: Iterable<U[K]>;
+}): Iterable<[T, ...U]>;
+
 export { }