tinkit 0.0.0-stage → 1.0.1

package/dist/arrays/index.d.ts

@@ -0,0 +1,1168 @@
+import type { RandomGenerator } from '../utils/index.js';
+/**
+ * Values that are falsy in JavaScript and representable as types.
+ * At runtime {@link compact} also removes `-0` and `NaN`, which TypeScript cannot express as literal types.
+ */
+export type Falsy = false | null | undefined | 0 | 0n | '';
+/**
+ * Recursively unwraps (possibly readonly) nested arrays down to their non-array element type.
+ * @example
+ * type R = FlatDeep<number | (number | string[])[]>; // number | string
+ */
+export type FlatDeep<T> = T extends ReadonlyArray<infer U> ? FlatDeep<U> : T;
+/**
+ * The tuple of element types produced by {@link zip} for a tuple of input arrays.
+ * @example
+ * type R = Zipped<[number[], string[]]>; // [number, string]
+ */
+export type Zipped<T extends ReadonlyArray<ReadonlyArray<unknown>>> = {
+    -readonly [K in keyof T]: T[K] extends ReadonlyArray<infer U> ? U : never;
+};
+/**
+ * Values accepted as sort keys by {@link sortBy}. Selectors may also return `null` or `undefined` (a missing key): such keys,
+ * like `NaN` and invalid `Date`s, rank after every other key in both directions.
+ */
+export type SortKey = number | string | bigint | Date;
+/**
+ * Sort direction accepted by {@link sortBy}.
+ */
+export type SortOrder = 'asc' | 'desc';
+/**
+ * Check if an array contains a value, using SameValueZero equality (so `NaN` is found and `0` matches `-0`).
+ * @template T
+ * @param {ReadonlyArray<T>} array - The array to be checked
+ * @param {T} value - The value to look for
+ * @returns {boolean} Whether the value is in the array
+ * @example
+ * contains([1, 2, 3], 2); // => true
+ * contains([NaN], NaN); // => true
+ */
+export declare function contains<T>(array: ReadonlyArray<T>, value: T): boolean;
+/**
+ * Get the first item in an array.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The array to be processed
+ * @returns {T | undefined} The first item, or `undefined` when the array is empty
+ * @example
+ * first([1, 2, 3]); // => 1
+ * first([]); // => undefined
+ */
+export declare function first<T>(array: ReadonlyArray<T>): T | undefined;
+/**
+ * Get the last item in an array.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The array to be processed
+ * @returns {T | undefined} The last item, or `undefined` when the array is empty
+ * @example
+ * last([1, 2, 3]); // => 3
+ * last([]); // => undefined
+ */
+export declare function last<T>(array: ReadonlyArray<T>): T | undefined;
+/**
+ * Flatten an array by exactly one level, like `Array.prototype.flat()` (holes in sparse arrays are skipped).
+ * @template T
+ * @param {ReadonlyArray<T | ReadonlyArray<T>>} array - The array to be flattened
+ * @returns {T[]} A new, one-level-flattened array
+ * @example
+ * flatten([[1, 2], 3, [4]]); // => [1, 2, 3, 4]
+ * flatten([[1, [2]]]); // => [1, [2]]
+ */
+export declare function flatten<T>(array: ReadonlyArray<T | ReadonlyArray<T>>): T[];
+/**
+ * Recursively flatten nested arrays of any depth, like `Array.prototype.flat(Infinity)` (holes are skipped).
+ * The implementation is iterative, so very deep nesting cannot overflow the call stack.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The array to be flattened
+ * @returns {Array<FlatDeep<T>>} A new array containing every non-array leaf, in depth-first order
+ * @throws {TypeError} when the array contains itself (directly or through nested arrays)
+ * @example
+ * flattenDeep([1, [2, [3, [4]]]]); // => [1, 2, 3, 4]
+ */
+export declare function flattenDeep<T>(array: ReadonlyArray<T>): Array<FlatDeep<T>>;
+/**
+ * Remove duplicates from an iterable (SameValueZero equality), keeping the first occurrence of each value.
+ * @template T
+ * @param {Iterable<T>} iterable - The iterable to be processed
+ * @returns {T[]} A new array with duplicates removed, in first-appearance order
+ * @example
+ * unique([1, 2, 2, 3, 1]); // => [1, 2, 3]
+ */
+export declare function unique<T>(iterable: Iterable<T>): T[];
+/**
+ * Get the union of two iterables: every distinct value from `a`, then every distinct value of `b` not already in `a`.
+ * Uses SameValueZero equality.
+ * @template T
+ * @param {Iterable<T>} a - The first iterable
+ * @param {Iterable<T>} b - The second iterable
+ * @returns {T[]} The unique values of both iterables, in first-appearance order
+ * @example
+ * union([1, 2, 3], [3, 4, 5]); // => [1, 2, 3, 4, 5]
+ */
+export declare function union<T>(a: Iterable<T>, b: Iterable<T>): T[];
+/**
+ * Get the intersection of two iterables: the distinct values of `a` that also appear in `b`.
+ * Uses SameValueZero equality.
+ * @template T
+ * @param {Iterable<T>} a - The first iterable (defines the output order)
+ * @param {Iterable<T>} b - The second iterable
+ * @returns {T[]} The unique common values, in order of first appearance in `a`
+ * @example
+ * intersection([1, 2, 3], [2, 3, 4]); // => [2, 3]
+ */
+export declare function intersection<T>(a: Iterable<T>, b: Iterable<T>): T[];
+/**
+ * Get the difference of two iterables: the distinct values of `a` that do not appear in `b`.
+ * Uses SameValueZero equality.
+ * @template T
+ * @param {Iterable<T>} a - The iterable to take values from (defines the output order)
+ * @param {Iterable<T>} b - The iterable of values to exclude
+ * @returns {T[]} The unique values of `a` missing from `b`, in first-appearance order
+ * @example
+ * difference([1, 2, 3, 1], [2, 3, 4]); // => [1]
+ */
+export declare function difference<T>(a: Iterable<T>, b: Iterable<T>): T[];
+/**
+ * Get the symmetric difference of two iterables: the distinct values that appear in exactly one of them.
+ * Uses SameValueZero equality.
+ * @template T
+ * @param {Iterable<T>} a - The first iterable
+ * @param {Iterable<T>} b - The second iterable
+ * @returns {T[]} The values only in `a` (first-appearance order), followed by the values only in `b`
+ * @example
+ * symmetricDifference([1, 2, 3], [3, 4]); // => [1, 2, 4]
+ */
+export declare function symmetricDifference<T>(a: Iterable<T>, b: Iterable<T>): T[];
+/**
+ * Check whether every value of `subset` also appears in `superset` (SameValueZero equality).
+ * An empty `subset` is a subset of anything.
+ * @template T
+ * @param {Iterable<T>} subset - The candidate subset
+ * @param {Iterable<T>} superset - The candidate superset
+ * @returns {boolean} Whether `subset` ⊆ `superset`
+ * @example
+ * isSubset([1, 2], [3, 2, 1]); // => true
+ * isSubset([1, 4], [1, 2, 3]); // => false
+ */
+export declare function isSubset<T>(subset: Iterable<T>, superset: Iterable<T>): boolean;
+/**
+ * Split an array into consecutive chunks of `size` items; only the last chunk may be shorter.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The array to split
+ * @param {number} size - The maximum length of each chunk (a positive integer)
+ * @returns {T[][]} A new array of chunks (empty when the input is empty)
+ * @throws {RangeError} when `size` is not a positive integer
+ * @throws {TypeError} when `size` is not a number
+ * @example
+ * chunk([1, 2, 3, 4, 5], 2); // => [[1, 2], [3, 4], [5]]
+ */
+export declare function chunk<T>(array: ReadonlyArray<T>, size: number): T[][];
+/**
+ * Remove every falsy value (`false`, `null`, `undefined`, `0`, `-0`, `NaN`, `''`, `0n`) from an array.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The array to compact
+ * @returns {Array<Exclude<T, Falsy>>} A new array containing only the truthy values
+ * @example
+ * compact([0, 1, false, 2, '', 3, null, NaN]); // => [1, 2, 3]
+ */
+export declare function compact<T>(array: ReadonlyArray<T>): Array<Exclude<T, Falsy>>;
+/**
+ * Create an array of numbers progressing from `start` up to, but not including, `end`, with Python `range` semantics.
+ * With a single argument, it is the (exclusive) end and the range starts at 0.
+ * The result is empty when `step` points away from `end`. Each value is computed as `start + i * step`,
+ * so fractional steps do not accumulate rounding errors (but are still subject to floating-point precision).
+ * When `(end - start) / step` is an integer up to floating-point rounding (e.g. `range(0, 2.1, 0.3)`), the range has exactly
+ * that many items, and no item ever reaches `end` (it is always exclusive, even when rounding errors would land on it).
+ * Only lengths above `2 ** 32 - 1` (the array limit) are rejected, far more than a heap can hold: callers must bound untrusted sizes
+ * (e.g. `range(Number(query.pages))`), since a result that does not fit in memory aborts the whole process with a fatal
+ * "heap out of memory" error rather than throwing.
+ * @param {number} start - The first value, or the exclusive end when `end` is omitted
+ * @param {number} [end] - The exclusive end of the range
+ * @param {number} [step=1] - The increment between values (may be negative, never 0)
+ * @returns {number[]} The generated numbers
+ * @throws {TypeError} when `start`, `end` or `step` is not a number
+ * @throws {RangeError} when an argument is not finite, `step` is 0, or the result would exceed the maximum array length
+ * @example
+ * range(5); // => [0, 1, 2, 3, 4]
+ * range(2, 8, 2); // => [2, 4, 6]
+ * range(5, 0, -2); // => [5, 3, 1]
+ * range(0, 5, -1); // => []
+ * range(0, 2.1, 0.3); // => [0, 0.3, 0.6, 0.8999999999999999, 1.2, 1.5, 1.7999999999999998] // 7 items, 2.1 excluded
+ */
+export declare function range(start: number, end?: number, step?: number): number[];
+/**
+ * Combine arrays element-wise into tuples, truncating to the length of the shortest array.
+ * @template T
+ * @param {...ReadonlyArray<unknown>} arrays - The arrays to zip
+ * @returns {Array<Zipped<T>>} A new array of tuples; empty when called without arrays
+ * @example
+ * zip([1, 2, 3], ['a', 'b']); // => [[1, 'a'], [2, 'b']] // typed as [number, string][]
+ */
+export declare function zip<T extends Array<ReadonlyArray<unknown>>>(...arrays: T): Array<Zipped<T>>;
+/**
+ * Group the items of an array by the key returned by `keyFn`, preserving input order within each group.
+ * The result is a null-prototype object, so keys such as `'__proto__'` or `'constructor'` are stored safely
+ * (no prototype pollution), but it has no `Object.prototype` methods. Number keys are converted to strings, as in any object.
+ * @template T
+ * @template K
+ * @param {ReadonlyArray<T>} array - The items to group
+ * @param {(item: T, index: number) => K} keyFn - Returns the group key of an item
+ * @returns {Partial<Record<K, T[]>>} An object mapping each key to the items that produced it
+ * @throws {TypeError} when `keyFn` is not a function
+ * @example
+ * groupBy([1, 2, 3, 4], function (n) { return n % 2 === 0 ? 'even' : 'odd'; }); // => { odd: [1, 3], even: [2, 4] }
+ */
+export declare function groupBy<T, K extends PropertyKey>(array: ReadonlyArray<T>, keyFn: (item: T, index: number) => K): Partial<Record<K, T[]>>;
+/**
+ * Index the items of an array by the key returned by `keyFn`; when several items share a key, the last one wins.
+ * The result is a null-prototype object (safe for keys such as `'__proto__'`).
+ * @template T
+ * @template K
+ * @param {ReadonlyArray<T>} array - The items to index
+ * @param {(item: T, index: number) => K} keyFn - Returns the key of an item
+ * @returns {Record<K, T>} An object mapping each key to the last item that produced it
+ * @throws {TypeError} when `keyFn` is not a function
+ * @example
+ * keyBy([{ id: 'a', v: 1 }, { id: 'a', v: 2 }], function (o) { return o.id; }); // => { a: { id: 'a', v: 2 } }
+ */
+export declare function keyBy<T, K extends PropertyKey>(array: ReadonlyArray<T>, keyFn: (item: T, index: number) => K): Record<K, T>;
+/**
+ * Count the items of an array per key returned by `keyFn`.
+ * The result is a null-prototype object (safe for keys such as `'__proto__'`).
+ * @template T
+ * @template K
+ * @param {ReadonlyArray<T>} array - The items to count
+ * @param {(item: T, index: number) => K} keyFn - Returns the key of an item
+ * @returns {Record<K, number>} An object mapping each key to the number of items that produced it
+ * @throws {TypeError} when `keyFn` is not a function
+ * @example
+ * countBy(['one', 'two', 'three'], function (s) { return s.length; }); // => { 3: 2, 5: 1 }
+ */
+export declare function countBy<T, K extends PropertyKey>(array: ReadonlyArray<T>, keyFn: (item: T, index: number) => K): Record<K, number>;
+/**
+ * Split an array in two: the items matching a type-guard `predicate`, and the others. Relative order is preserved.
+ * @template T
+ * @template S
+ * @param {ReadonlyArray<T>} array - The items to split
+ * @param {(item: T, index: number) => item is S} predicate - Type guard deciding which side an item goes to
+ * @returns {[S[], Exclude<T, S>[]]} `[matching, nonMatching]`
+ * @throws {TypeError} when `predicate` is not a function
+ * @example
+ * partition([1, 'a', 2], function (v): v is number { return typeof v === 'number'; }); // => [[1, 2], ['a']]
+ */
+export declare function partition<T, S extends T>(array: ReadonlyArray<T>, predicate: (item: T, index: number) => item is S): [S[], Exclude<T, S>[]];
+/**
+ * Split an array in two: the items for which `predicate` returns true, and the others. Relative order is preserved.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items to split
+ * @param {(item: T, index: number) => boolean} predicate - Decides which side an item goes to
+ * @returns {[T[], T[]]} `[matching, nonMatching]`
+ * @throws {TypeError} when `predicate` is not a function
+ * @example
+ * partition([1, 2, 3, 4], function (n) { return n % 2 === 0; }); // => [[2, 4], [1, 3]]
+ */
+export declare function partition<T>(array: ReadonlyArray<T>, predicate: (item: T, index: number) => boolean): [T[], T[]];
+/**
+ * Remove items whose key (as returned by `keyFn`, compared with SameValueZero) was already seen, keeping the first occurrence.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items to deduplicate
+ * @param {(item: T, index: number) => unknown} keyFn - Returns the identity key of an item
+ * @returns {T[]} A new array with one item per distinct key, in first-appearance order
+ * @throws {TypeError} when `keyFn` is not a function
+ * @example
+ * uniqueBy([{ id: 1, v: 'a' }, { id: 1, v: 'b' }, { id: 2, v: 'c' }], function (o) { return o.id; }); // => [{ id: 1, v: 'a' }, { id: 2, v: 'c' }]
+ */
+export declare function uniqueBy<T>(array: ReadonlyArray<T>, keyFn: (item: T, index: number) => unknown): T[];
+/**
+ * Return a sorted copy of an array, ordered by the key `selector` returns for each item. The sort is stable
+ * (items with equal keys keep their relative order, in both directions) and the selector is called once per item.
+ *
+ * Ordering rules, chosen to be deterministic and locale-independent:
+ * - numbers and bigints compare numerically (and may be mixed); `Date`s compare by timestamp;
+ * - strings compare by UTF-16 code units with plain `<` (not `localeCompare`), so `'B' < 'a'`;
+ * - numeric keys sort before string keys when both kinds are mixed;
+ * - `NaN` keys, invalid `Date`s and missing (`null`/`undefined`) keys always go last, whatever the order, in input order.
+ *
+ * Use {@link orderBy} to sort by several keys.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items to sort (not mutated)
+ * @param {(item: T, index: number) => SortKey | null | undefined} selector - Returns the sort key of an item
+ * @param {SortOrder} [order='asc'] - `'asc'` for ascending or `'desc'` for descending keys
+ * @returns {T[]} A new sorted array
+ * @throws {TypeError} when `selector` is not a function
+ * @throws {RangeError} when `order` is neither `'asc'` nor `'desc'`
+ * @example
+ * sortBy([{ n: 'b' }, { n: 'a' }], function (o) { return o.n; }); // => [{ n: 'a' }, { n: 'b' }]
+ * sortBy([1, 3, 2], function (n) { return n; }, 'desc'); // => [3, 2, 1]
+ * sortBy([{ n: 2 }, {}, { n: 1 }], function (o: { n?: number }) { return o.n; }); // => [{ n: 1 }, { n: 2 }, {}]
+ */
+export declare function sortBy<T>(array: ReadonlyArray<T>, selector: (item: T, index: number) => SortKey | null | undefined, order?: SortOrder): T[];
+/**
+ * Return a shuffled copy of an array using the Fisher–Yates algorithm (the input is not mutated).
+ * Not cryptographically secure by default: pass `secureRandom` (random module) for tokens, OTPs, lotteries…
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items to shuffle
+ * @param {RandomGenerator} [random=Math.random] - Generator of floats in `[0, 1)`, injectable for deterministic results
+ * @returns {T[]} A new array containing the same items in random order
+ * @throws {RangeError} when `random()` returns a value outside `[0, 1)`
+ * @throws {TypeError} when `random` is not a function
+ * @example
+ * shuffle([1, 2, 3, 4]); // e.g. [3, 1, 4, 2]
+ */
+export declare function shuffle<T>(array: ReadonlyArray<T>, random?: RandomGenerator): T[];
+/**
+ * Pick a random item from an array.
+ * Not cryptographically secure by default: pass `secureRandom` (random module) for tokens, OTPs, lotteries…
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items to pick from
+ * @param {RandomGenerator} [random=Math.random] - Generator of floats in `[0, 1)`, injectable for deterministic results
+ * @returns {T | undefined} A random item, or `undefined` when the array is empty (`random` is then not called)
+ * @throws {RangeError} when `random()` returns a value outside `[0, 1)`
+ * @throws {TypeError} when `random` is not a function
+ * @example
+ * sample(['a', 'b', 'c']); // e.g. 'b'
+ * sample([]); // => undefined
+ */
+export declare function sample<T>(array: ReadonlyArray<T>, random?: RandomGenerator): T | undefined;
+/**
+ * Return the first `n` items of an array (or all of them when it is shorter).
+ * @template T
+ * @param {ReadonlyArray<T>} array - The source array
+ * @param {number} n - How many items to take (a non-negative integer)
+ * @returns {T[]} A new array with at most `n` items
+ * @throws {RangeError} when `n` is negative or not an integer
+ * @throws {TypeError} when `n` is not a number
+ * @example
+ * take([1, 2, 3], 2); // => [1, 2]
+ */
+export declare function take<T>(array: ReadonlyArray<T>, n: number): T[];
+/**
+ * Return an array without its first `n` items.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The source array
+ * @param {number} n - How many items to skip (a non-negative integer)
+ * @returns {T[]} A new array with the remaining items
+ * @throws {RangeError} when `n` is negative or not an integer
+ * @throws {TypeError} when `n` is not a number
+ * @example
+ * drop([1, 2, 3], 2); // => [3]
+ */
+export declare function drop<T>(array: ReadonlyArray<T>, n: number): T[];
+/**
+ * The tuple of arrays produced by {@link unzip} for an array of tuples of type `T`.
+ * @example
+ * type R = Unzipped<[number, string]>; // [number[], string[]]
+ */
+export type Unzipped<T extends ReadonlyArray<unknown>> = {
+    -readonly [K in keyof T]: Array<T[K]>;
+};
+/**
+ * A comparator, as accepted by `Array.prototype.sort`: negative when `a` sorts before `b`, positive when after, `0` when equivalent.
+ */
+export type Comparator<T> = (a: T, b: T) => number;
+/**
+ * Split an array of tuples into one array per tuple position: the inverse of {@link zip}.
+ * Like `zip`, the result is truncated to the SHORTEST tuple, so `unzip(zip(a, b))` gives back `[a, b]` for equal-length, non-empty arrays.
+ * The number of positions is read from the tuples themselves, so for an EMPTY input it cannot be known and `[]` is returned;
+ * the return type says so (`Unzipped<T> | []`) — use destructuring defaults: `const [xs = [], ys = []] = unzip(pairs);`.
+ * @template T - The tuple type
+ * @param {ReadonlyArray<T>} tuples - The tuples to split
+ * @returns {Unzipped<T> | []} One fresh array per tuple position, or `[]` when there are no tuples
+ * @example
+ * unzip([[1, 'a'], [2, 'b']] as [number, string][]); // => [[1, 2], ['a', 'b']] // typed as [number[], string[]] | []
+ * unzip([]); // => []
+ */
+export declare function unzip<T extends ReadonlyArray<unknown>>(tuples: ReadonlyArray<T>): Unzipped<T> | [];
+/**
+ * Return the sliding windows of `size` consecutive items, starting every `step` items. Only FULL windows are returned,
+ * so an array shorter than `size` gives `[]`, and trailing items that do not fill a window are dropped.
+ * The number of windows is `max(0, floor((length - size) / step) + 1)`, and the result holds `size` times as many items in all, which
+ * must not exceed `2 ** 32 - 1`. That limit is far more than a heap can hold: callers must bound untrusted sizes, since a result
+ * that does not fit in memory aborts the whole process with a fatal "heap out of memory" error rather than throwing.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The source array
+ * @param {number} size - The length of each window (a positive integer)
+ * @param {number} [step=1] - The distance between the starts of two consecutive windows (a positive integer)
+ * @returns {T[][]} A new array of windows (each window is a fresh array)
+ * @throws {RangeError} when `size` or `step` is not a positive integer, or the windows would hold more than `2 ** 32 - 1` items in all
+ * @throws {TypeError} when `size` or `step` is not a number
+ * @example
+ * windowed([1, 2, 3, 4], 2); // => [[1, 2], [2, 3], [3, 4]]
+ * windowed([1, 2, 3, 4, 5], 2, 2); // => [[1, 2], [3, 4]]
+ * windowed([1, 2], 3); // => []
+ */
+export declare function windowed<T>(array: ReadonlyArray<T>, size: number, step?: number): T[][];
+/**
+ * Return every pair of adjacent items: `[a[0], a[1]], [a[1], a[2]], ...` (empty for arrays with fewer than 2 items).
+ * @template T
+ * @param {ReadonlyArray<T>} array - The source array
+ * @returns {Array<[T, T]>} A new array of `length - 1` pairs
+ * @example
+ * pairwise([1, 2, 3]); // => [[1, 2], [2, 3]]
+ * pairwise([1]); // => []
+ */
+export declare function pairwise<T>(array: ReadonlyArray<T>): Array<[T, T]>;
+/**
+ * Return the item with the SMALLEST key, using the same ordering rules as {@link sortBy}
+ * (numbers/bigints numerically and before strings, strings by UTF-16 code units, `Date`s by timestamp).
+ * On ties the FIRST such item wins. Items whose key is `NaN`, an invalid `Date`, `null` or `undefined` are ignored.
+ * The selector is called exactly once per item.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items to inspect
+ * @param {(item: T, index: number) => SortKey | null | undefined} selector - Returns the key of an item
+ * @returns {T | undefined} The first item with the smallest key, or `undefined` when the array is empty or every key is `NaN`
+ * @throws {TypeError} when `selector` is not a function
+ * @example
+ * const items = [{ n: 3 }, { n: 1 }, { n: 1 }];
+ * minBy(items, function (o) { return o.n; }) === items[1]; // => true // ties keep the first
+ * minBy([NaN, 2], function (n) { return n; }); // => 2
+ */
+export declare function minBy<T>(array: ReadonlyArray<T>, selector: (item: T, index: number) => SortKey | null | undefined): T | undefined;
+/**
+ * Return the item with the LARGEST key, using the same ordering rules as {@link sortBy}
+ * (numbers/bigints numerically and before strings, strings by UTF-16 code units, `Date`s by timestamp).
+ * On ties the FIRST such item wins. Items whose key is `NaN`, an invalid `Date`, `null` or `undefined` are ignored.
+ * The selector is called exactly once per item.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items to inspect
+ * @param {(item: T, index: number) => SortKey | null | undefined} selector - Returns the key of an item
+ * @returns {T | undefined} The first item with the largest key, or `undefined` when the array is empty or every key is `NaN`
+ * @throws {TypeError} when `selector` is not a function
+ * @example
+ * maxBy([{ n: 3 }, { n: 7 }], function (o) { return o.n; }); // => { n: 7 }
+ * maxBy(['b', 'a', 'B'], function (s) { return s; }); // => 'b'
+ */
+export declare function maxBy<T>(array: ReadonlyArray<T>, selector: (item: T, index: number) => SortKey | null | undefined): T | undefined;
+/**
+ * Add up the numbers returned by `selector` for each item, using compensated (Neumaier) summation like `sum` from the math module (same algorithm, same result),
+ * so the rounding error does not grow with the number of items.
+ * `NaN`/`Infinity` keys propagate as in plain addition. Like the aggregates of the math module, each key is converted once with unary `+`,
+ * so numeric strings count as numbers instead of being concatenated.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items to add up
+ * @param {(item: T, index: number) => number} selector - Returns the number contributed by an item
+ * @returns {number} The total (`0` for an empty array)
+ * @throws {TypeError} when `selector` is not a function
+ * @example
+ * sumBy([{ price: 0.1 }, { price: 0.2 }, { price: 0.3 }], function (o) { return o.price; }); // => 0.6
+ */
+export declare function sumBy<T>(array: ReadonlyArray<T>, selector: (item: T, index: number) => number): number;
+/**
+ * Return a copy of an array with the item at `from` moved to position `to` (the input is not mutated).
+ * `to` is the index the item has in the RESULT. Negative indices count from the end, like `Array.prototype.at`.
+ * Equivalent to `copy.splice(to, 0, ...copy.splice(from, 1))` on a copy. Holes of sparse arrays become `undefined`.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The source array
+ * @param {number} from - Index of the item to move, in `[-length, length - 1]`
+ * @param {number} to - Index of the item in the result, in `[-length, length - 1]`
+ * @returns {T[]} A new array, a permutation of the input
+ * @throws {RangeError} when `from` or `to` is not an integer or is out of range (any index is out of range for an empty array)
+ * @throws {TypeError} when `from` or `to` is not a number
+ * @example
+ * move(['a', 'b', 'c', 'd'], 0, 2); // => ['b', 'c', 'a', 'd']
+ * move(['a', 'b', 'c'], -1, 0); // => ['c', 'a', 'b']
+ */
+export declare function move<T>(array: ReadonlyArray<T>, from: number, to: number): T[];
+/**
+ * Return a copy of an array with `items` inserted before position `index` (the input is not mutated).
+ * Negative indices count from the end, like `Array.prototype.at` / `splice`: `-1` inserts before the last item;
+ * `index === length` appends. Holes of sparse arrays become `undefined`.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The source array
+ * @param {number} index - Insertion position, in `[-length, length]`
+ * @param {...T} items - The items to insert (in order)
+ * @returns {T[]} A new array of length `array.length + items.length`
+ * @throws {RangeError} when `index` is not an integer or is out of range
+ * @throws {TypeError} when `index` is not a number
+ * @example
+ * insertAt([1, 2, 3], 1, 9, 8); // => [1, 9, 8, 2, 3]
+ * insertAt([1, 2, 3], -1, 9); // => [1, 2, 9, 3]
+ * insertAt([1, 2, 3], 3, 9); // => [1, 2, 3, 9]
+ */
+export declare function insertAt<T>(array: ReadonlyArray<T>, index: number, ...items: T[]): T[];
+/**
+ * Return a copy of an array without the `count` items starting at `index` (the input is not mutated).
+ * Negative indices count from the end, like `Array.prototype.at`. Like `splice`, `count` is clamped to the items available
+ * (pass `array.length` to remove everything from `index` on). Holes of sparse arrays become `undefined`.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The source array
+ * @param {number} index - Index of the first item to remove, in `[-length, length - 1]`
+ * @param {number} [count=1] - How many items to remove (a non-negative integer)
+ * @returns {T[]} A new array without the removed items
+ * @throws {RangeError} when `index` is not an integer or is out of range (any index is out of range for an empty array)
+ * @throws {RangeError} when `count` is not a non-negative integer
+ * @throws {TypeError} when `index` or `count` is not a number
+ * @example
+ * removeAt([1, 2, 3, 4], 1); // => [1, 3, 4]
+ * removeAt([1, 2, 3, 4], -2, 2); // => [1, 2]
+ */
+export declare function removeAt<T>(array: ReadonlyArray<T>, index: number, count?: number): T[];
+/**
+ * Find, by binary search (O(log n)), the LOWEST index at which `value` can be inserted into `sortedArray` keeping it sorted
+ * (before any equal items). Without a comparator, numbers, strings or bigints are ordered with `<` (strings by UTF-16 code units).
+ * The array must already be sorted in that order (and contain no `NaN`); otherwise the result is unspecified.
+ * @template T - A number, string or bigint type
+ * @param {ReadonlyArray<T>} sortedArray - An array sorted in ascending `<` order
+ * @param {T} value - The value to locate
+ * @returns {number} An index in `[0, length]`
+ * @throws {RangeError} when `value` is `NaN`
+ * @example
+ * sortedIndex([10, 20, 20, 30], 20); // => 1
+ * sortedIndex([10, 20, 30], 99); // => 3
+ */
+export declare function sortedIndex<T extends number | string | bigint>(sortedArray: ReadonlyArray<T>, value: T): number;
+/**
+ * Find, by binary search (O(log n)), the LOWEST index at which `value` can be inserted into `sortedArray` keeping it sorted
+ * according to `compare` (before any items comparing equal). The array must already be sorted by `compare`.
+ * @template T
+ * @param {ReadonlyArray<T>} sortedArray - An array sorted according to `compare`
+ * @param {T} value - The value to locate
+ * @param {Comparator<T>} compare - The comparator the array is sorted by
+ * @returns {number} An index in `[0, length]`
+ * @throws {TypeError} when `compare` is given but is not a function
+ * @example
+ * sortedIndex([{ n: 1 }, { n: 5 }], { n: 3 }, function (a, b) { return a.n - b.n; }); // => 1
+ */
+export declare function sortedIndex<T>(sortedArray: ReadonlyArray<T>, value: T, compare: Comparator<T>): number;
+/**
+ * Find the index of `value` in `sortedArray` by binary search (O(log n)); with duplicates, the LOWEST matching index is returned.
+ * Without a comparator, numbers, strings or bigints are ordered with `<`. The array must already be sorted in that order.
+ * @template T - A number, string or bigint type
+ * @param {ReadonlyArray<T>} sortedArray - An array sorted in ascending `<` order
+ * @param {T} value - The value to find
+ * @returns {number} The index of `value`, or `-1` when it is absent
+ * @throws {RangeError} when `value` is `NaN`
+ * @example
+ * binarySearch([1, 3, 5, 7], 5); // => 2
+ * binarySearch([1, 3, 5, 7], 4); // => -1
+ */
+export declare function binarySearch<T extends number | string | bigint>(sortedArray: ReadonlyArray<T>, value: T): number;
+/**
+ * Find the index of an item comparing equal (`compare(item, value) === 0`) to `value` in `sortedArray` by binary search;
+ * with several equal items, the LOWEST index is returned. The array must already be sorted by `compare`.
+ * @template T
+ * @param {ReadonlyArray<T>} sortedArray - An array sorted according to `compare`
+ * @param {T} value - The value to find
+ * @param {Comparator<T>} compare - The comparator the array is sorted by
+ * @returns {number} The index of a matching item, or `-1`
+ * @throws {TypeError} when `compare` is given but is not a function
+ * @example
+ * binarySearch(['b', 'c'], 'B', function (a, b) { return a.toLowerCase() < b.toLowerCase() ? -1 : a.toLowerCase() > b.toLowerCase() ? 1 : 0; }); // => 0
+ */
+export declare function binarySearch<T>(sortedArray: ReadonlyArray<T>, value: T, compare: Comparator<T>): number;
+/**
+ * Return the cartesian product of the given arrays: every tuple taking one item from each array, in lexicographic order
+ * (the LAST array varies fastest). The result has `product of the lengths` tuples: it is empty when any array is empty,
+ * and is `[[]]` (one empty tuple) when called without arrays. The tuples must not hold more than `2 ** 32 - 1` items in all (checked
+ * before anything is allocated). That limit is far more than a heap can hold: callers must bound untrusted inputs (e.g. option lists
+ * of a product configurator), since a result that does not fit in memory aborts the whole process with a fatal "heap out of memory"
+ * error rather than throwing.
+ * @template T - The tuple of input array types
+ * @param {...ReadonlyArray<unknown>} arrays - The arrays to combine
+ * @returns {Array<Zipped<T>>} A new array of fresh tuples
+ * @throws {RangeError} when the tuples would hold more than `2 ** 32 - 1` items in all
+ * @example
+ * cartesianProduct([1, 2], ['a', 'b']); // => [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']] // typed as [number, string][]
+ */
+export declare function cartesianProduct<T extends Array<ReadonlyArray<unknown>>>(...arrays: T): Array<Zipped<T>>;
+/**
+ * Return a copy of an array with `separator` inserted between every two consecutive items.
+ * @template T - The item type
+ * @template S - The separator type
+ * @param {ReadonlyArray<T>} array - The source array
+ * @param {S} separator - The value to insert
+ * @returns {Array<T | S>} A new array of length `max(0, 2 * length - 1)`
+ * @example
+ * intersperse([1, 2, 3], 0); // => [1, 0, 2, 0, 3]
+ * intersperse(['a'], ','); // => ['a']
+ */
+export declare function intersperse<T, S>(array: ReadonlyArray<T>, separator: S): Array<T | S>;
+/**
+ * Like {@link difference}, but items are compared by the key `keyFn` returns (SameValueZero): the items of `a` whose key is
+ * not the key of any item of `b`, keeping only the FIRST item of `a` per key. `differenceBy(a, b, identity)` equals `difference(a, b)`.
+ * `keyFn` is called once per item of both iterables.
+ * @template T - The item type of `a`
+ * @template U - The item type of `b`
+ * @param {Iterable<T>} a - The items to take from (defines the output order)
+ * @param {Iterable<U>} b - The items whose keys are excluded
+ * @param {(item: T | U) => unknown} keyFn - Returns the identity key of an item of either iterable
+ * @returns {T[]} The items of `a` with a distinct key missing from `b`, in first-appearance order
+ * @throws {TypeError} when `keyFn` is not a function
+ * @example
+ * differenceBy([{ id: 1 }, { id: 2 }], [{ id: 2 }], function (o) { return o.id; }); // => [{ id: 1 }]
+ * differenceBy([1.2, 2.5, 3.1], [2.1], Math.floor); // => [1.2, 3.1]
+ */
+export declare function differenceBy<T, U = T>(a: Iterable<T>, b: Iterable<U>, keyFn: (item: T | U) => unknown): T[];
+/**
+ * Like {@link intersection}, but items are compared by the key `keyFn` returns (SameValueZero): the items of `a` whose key is
+ * also the key of an item of `b`, keeping only the FIRST item of `a` per key. `intersectionBy(a, b, identity)` equals `intersection(a, b)`.
+ * `keyFn` is called once per item of both iterables.
+ * @template T - The item type of `a`
+ * @template U - The item type of `b`
+ * @param {Iterable<T>} a - The items to take from (defines the output order)
+ * @param {Iterable<U>} b - The items whose keys are kept
+ * @param {(item: T | U) => unknown} keyFn - Returns the identity key of an item of either iterable
+ * @returns {T[]} The items of `a` with a distinct key also present in `b`, in first-appearance order
+ * @throws {TypeError} when `keyFn` is not a function
+ * @example
+ * intersectionBy([{ id: 1 }, { id: 2 }], [{ id: 2 }], function (o) { return o.id; }); // => [{ id: 2 }]
+ */
+export declare function intersectionBy<T, U = T>(a: Iterable<T>, b: Iterable<U>, keyFn: (item: T | U) => unknown): T[];
+/**
+ * One step of the edit script returned by {@link diffSequences}:
+ * - `'equal'`: `value` is `a[indexA]`, kept (it matches `b[indexB]`);
+ * - `'delete'`: `value` is `a[indexA]`, removed;
+ * - `'insert'`: `value` is `b[indexB]`, added.
+ * @template T - The element type
+ */
+export type DiffOperation<T> = {
+    type: 'equal';
+    value: T;
+    indexA: number;
+    indexB: number;
+} | {
+    type: 'delete';
+    value: T;
+    indexA: number;
+} | {
+    type: 'insert';
+    value: T;
+    indexB: number;
+};
+/**
+ * Options accepted by {@link diffSequences} and {@link longestCommonSubsequence}.
+ */
+export interface DiffOptions {
+    /**
+     * Largest number of edits (deletions plus insertions) accepted: when the sequences differ by more, a `RangeError` is thrown instead,
+     * after O((N + M) · maxEdits) work. An integer >= 0 or `Infinity`.
+     * @default Infinity
+     */
+    maxEdits?: number;
+}
+/**
+ * Computes a minimal edit script turning sequence `a` into sequence `b`: a list of `'equal'`, `'delete'` and `'insert'` operations
+ * (see {@link DiffOperation}) with the smallest possible number of deletions plus insertions. Reading the script in order,
+ * the `'equal'` and `'delete'` values spell out `a`, and the `'equal'` and `'insert'` values spell out `b`. Within each run of
+ * changes, deletions come before insertions. When several minimal scripts exist, which one is returned is unspecified but
+ * deterministic.
+ *
+ * Uses Myers' O((N + M)·D) algorithm, in its linear-space divide-and-conquer form, after stripping the common prefix and suffix:
+ * time is O((N + M)·D) where D is the size of the edit script (so near-identical inputs are fast, and completely different ones
+ * cost O((N + M)²)), memory is O(N + M), and recursion depth is O(log D). Non-array iterables are copied first (strings are split
+ * into code points).
+ *
+ * **Untrusted input:** two unrelated texts of 16,000 characters already take seconds of CPU. Cap the input sizes, or pass
+ * `{ maxEdits }`, which bounds the work to O((N + M) · maxEdits) and throws a `RangeError` when the sequences differ by more.
+ * @template T - The element type
+ * @param {Iterable<T>} a - The original sequence
+ * @param {Iterable<T>} b - The target sequence
+ * @param {(x: T, y: T) => boolean} [equals=SameValueZero] - Element equality, always called as `equals(itemOfA, itemOfB)`;
+ * defaults to SameValueZero (`===`, except that `NaN` equals `NaN`). `'equal'` operations carry the element of `a`.
+ * @param {DiffOptions} [options={}] - `maxEdits` (default `Infinity`): the largest number of deletions plus insertions accepted
+ * @returns {Array<DiffOperation<T>>} The edit script, in order
+ * @throws {TypeError} when `a` or `b` is not iterable, `equals` is not a function, or `maxEdits` is not a number
+ * @throws {RangeError} when `maxEdits` is not an integer >= 0 or `Infinity`, or the sequences differ by more than `maxEdits` edits
+ * @example
+ * diffSequences([1, 2, 3], [1, 3, 4]); // => [{ type: 'equal', value: 1, indexA: 0, indexB: 0 }, { type: 'delete', value: 2, indexA: 1 }, { type: 'equal', value: 3, indexA: 2, indexB: 1 }, { type: 'insert', value: 4, indexB: 2 }]
+ * diffSequences('cat', 'cut').map(function (op) { return op.type; }); // => ['equal', 'delete', 'insert', 'equal']
+ * @example
+ * const before = ['Alice', 'bob'];
+ * const after = ['alice', 'Bob', 'Carol'];
+ * diffSequences(before, after, function (x, y) { return x.toLowerCase() === y.toLowerCase(); }).map(function (op) { return op.type; }); // => ['equal', 'equal', 'insert']
+ * @example
+ * diffSequences('kitten', 'sitting', undefined, { maxEdits: 5 }).length; // => 9
+ * diffSequences('a'.repeat(10000), 'b'.repeat(10000), undefined, { maxEdits: 100 }); // throws RangeError
+ */
+export declare function diffSequences<T>(a: Iterable<T>, b: Iterable<T>, equals?: (x: T, y: T) => boolean, options?: DiffOptions): Array<DiffOperation<T>>;
+/**
+ * Computes a longest common subsequence of `a` and `b`: the longest list of elements that appear in both, in the same relative
+ * order (not necessarily contiguously). It is the `'equal'` part of {@link diffSequences}, with the same complexity
+ * (O((N + M)·D) time, O(N + M) memory). When several longest subsequences exist, which one is returned is unspecified but deterministic.
+ * **Untrusted input:** cap the input sizes or pass `{ maxEdits }`, as for {@link diffSequences}.
+ * @template T - The element type
+ * @param {Iterable<T>} a - The first sequence
+ * @param {Iterable<T>} b - The second sequence
+ * @param {(x: T, y: T) => boolean} [equals=SameValueZero] - Element equality, always called as `equals(itemOfA, itemOfB)`;
+ * defaults to SameValueZero. The returned elements are taken from `a`.
+ * @param {DiffOptions} [options={}] - `maxEdits` (default `Infinity`): the largest number of deletions plus insertions accepted
+ * @returns {T[]} The common subsequence, as a new array of elements of `a`
+ * @throws {TypeError} when `a` or `b` is not iterable, `equals` is not a function, or `maxEdits` is not a number
+ * @throws {RangeError} when `maxEdits` is not an integer >= 0 or `Infinity`, or the sequences differ by more than `maxEdits` edits
+ * @example
+ * longestCommonSubsequence([1, 2, 3, 4, 5], [2, 4, 6, 5]); // => [2, 4, 5]
+ * longestCommonSubsequence('ABCBDAB', 'BDCABA').length; // => 4
+ * longestCommonSubsequence([NaN, 0], [-0, NaN]).length; // => 1
+ */
+export declare function longestCommonSubsequence<T>(a: Iterable<T>, b: Iterable<T>, equals?: (x: T, y: T) => boolean, options?: DiffOptions): T[];
+/**
+ * Like {@link union}, but items are compared by the key `keyFn` returns (SameValueZero): every item of `a`, then of `b`, whose key
+ * was not seen before, so only the FIRST item per key is kept. `unionBy(a, b, identity)` equals `union(a, b)`.
+ * `keyFn` is called once per item of both iterables.
+ * @template T - The item type of `a`
+ * @template U - The item type of `b`
+ * @param {Iterable<T>} a - The first items
+ * @param {Iterable<U>} b - The second items
+ * @param {(item: T | U) => unknown} keyFn - Returns the identity key of an item of either iterable
+ * @returns {Array<T | U>} One item per distinct key, in first-appearance order
+ * @throws {TypeError} when `keyFn` is not a function
+ * @example
+ * unionBy([{ id: 1 }, { id: 2 }], [{ id: 2 }, { id: 3 }], function (o) { return o.id; }); // => [{ id: 1 }, { id: 2 }, { id: 3 }]
+ * unionBy([1.2, 2.5], [2.1, 3.4], Math.floor); // => [1.2, 2.5, 3.4]
+ */
+export declare function unionBy<T, U = T>(a: Iterable<T>, b: Iterable<U>, keyFn: (item: T | U) => unknown): Array<T | U>;
+/**
+ * Like {@link symmetricDifference}, but items are compared by the key `keyFn` returns (SameValueZero): the items of `a` whose key
+ * is not the key of any item of `b`, followed by the items of `b` whose key is not the key of any item of `a`, keeping only the
+ * FIRST item per key. `keyFn` is called once per item of both iterables.
+ * @template T - The item type of `a`
+ * @template U - The item type of `b`
+ * @param {Iterable<T>} a - The first items
+ * @param {Iterable<U>} b - The second items
+ * @param {(item: T | U) => unknown} keyFn - Returns the identity key of an item of either iterable
+ * @returns {Array<T | U>} The items whose key appears in exactly one of the iterables, in first-appearance order
+ * @throws {TypeError} when `keyFn` is not a function
+ * @example
+ * symmetricDifferenceBy([{ id: 1 }, { id: 2 }], [{ id: 2 }, { id: 3 }], function (o) { return o.id; }); // => [{ id: 1 }, { id: 3 }]
+ */
+export declare function symmetricDifferenceBy<T, U = T>(a: Iterable<T>, b: Iterable<U>, keyFn: (item: T | U) => unknown): Array<T | U>;
+/**
+ * Remove the items `equals` to an earlier item, keeping the first occurrence: {@link unique} with a custom equality, for
+ * values that have no identity key (e.g. points within a tolerance). It compares every pair, in O(n²): when a key exists, prefer
+ * {@link uniqueBy}, which is O(n).
+ * @template T
+ * @param {Iterable<T>} iterable - The items to deduplicate
+ * @param {(x: T, y: T) => boolean} equals - Whether two items are duplicates (`x` is the candidate, `y` an item already kept)
+ * @returns {T[]} A new array of distinct items, in first-appearance order
+ * @throws {TypeError} when `equals` is not a function
+ * @example
+ * uniqueWith([1, 1.05, 2, 1.9], function (x, y) { return Math.abs(x - y) < 0.2; }); // => [1, 2]
+ */
+export declare function uniqueWith<T>(iterable: Iterable<T>, equals: (x: T, y: T) => boolean): T[];
+/**
+ * {@link union} with a custom equality: every item of `a`, then of `b`, not `equals` to an item already kept (first occurrence
+ * wins). O(n²) in the total number of items: when a key exists, prefer {@link unionBy}, which is linear.
+ * @template T - The item type of `a`
+ * @template U - The item type of `b`
+ * @param {Iterable<T>} a - The first items
+ * @param {Iterable<U>} b - The second items
+ * @param {(x: T | U, y: T | U) => boolean} equals - Whether two items are the same (`x` is the candidate, `y` an item already kept)
+ * @returns {Array<T | U>} The distinct items of both iterables, in first-appearance order
+ * @throws {TypeError} when `equals` is not a function
+ * @example
+ * unionWith([{ x: 1, y: 2 }], [{ x: 1, y: 2 }, { x: 3, y: 4 }], function (p, q) { return p.x === q.x && p.y === q.y; }); // => [{ x: 1, y: 2 }, { x: 3, y: 4 }]
+ */
+export declare function unionWith<T, U = T>(a: Iterable<T>, b: Iterable<U>, equals: (x: T | U, y: T | U) => boolean): Array<T | U>;
+/**
+ * {@link difference} with a custom equality: the items of `a` not `equals` to any item of `b`, keeping only the first of several
+ * items of `a` that are `equals` to each other. O(n·m): when a key exists, prefer {@link differenceBy}, which is linear.
+ * @template T - The item type of `a`
+ * @template U - The item type of `b`
+ * @param {Iterable<T>} a - The items to take from (defines the output order)
+ * @param {Iterable<U>} b - The items to exclude
+ * @param {(x: T, y: T | U) => boolean} equals - Whether two items are the same (`x` is always an item of `a`; `y` is an item of `b`, or an item of `a` already kept)
+ * @returns {T[]} The distinct items of `a` with no equal in `b`, in first-appearance order
+ * @throws {TypeError} when `equals` is not a function
+ * @example
+ * differenceWith([{ x: 1 }, { x: 2 }], [{ x: 2 }], function (p, q) { return p.x === q.x; }); // => [{ x: 1 }]
+ */
+export declare function differenceWith<T, U = T>(a: Iterable<T>, b: Iterable<U>, equals: (x: T, y: T | U) => boolean): T[];
+/**
+ * {@link intersection} with a custom equality: the items of `a` `equals` to some item of `b`, keeping only the first of several
+ * items of `a` that are `equals` to each other. O(n·m): when a key exists, prefer {@link intersectionBy}, which is linear.
+ * @template T - The item type of `a`
+ * @template U - The item type of `b`
+ * @param {Iterable<T>} a - The items to take from (defines the output order)
+ * @param {Iterable<U>} b - The items to match
+ * @param {(x: T, y: T | U) => boolean} equals - Whether two items are the same (`x` is always an item of `a`; `y` is an item of `b`, or an item of `a` already kept)
+ * @returns {T[]} The distinct items of `a` with an equal in `b`, in first-appearance order
+ * @throws {TypeError} when `equals` is not a function
+ * @example
+ * intersectionWith([{ x: 1 }, { x: 2 }], [{ x: 2 }], function (p, q) { return p.x === q.x; }); // => [{ x: 2 }]
+ */
+export declare function intersectionWith<T, U = T>(a: Iterable<T>, b: Iterable<U>, equals: (x: T, y: T | U) => boolean): T[];
+/**
+ * Return a sorted copy of an array, ordered by several keys: by the first selector's key, then items with equal first keys by the
+ * second selector's key, and so on, each key in its own direction. The sort is stable (items with equal keys in all selectors keep
+ * their input order) and each selector is called exactly once per item, not once per comparison.
+ *
+ * Every key follows the ordering rules of {@link sortBy}, which make the order TOTAL and deterministic: numbers/bigints numerically
+ * and before strings, strings by UTF-16 code units, `Date`s by timestamp, and `NaN`, invalid `Date`s, `null` and `undefined` keys
+ * after every other key in BOTH directions (equal to each other, so the next selector decides between them).
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items to sort (not mutated)
+ * @param {ReadonlyArray<(item: T, index: number) => SortKey | null | undefined>} selectors - Return the keys of an item, most significant first (none: a plain copy)
+ * @param {SortOrder | ReadonlyArray<SortOrder>} [orders='asc'] - One direction for all keys, or one per selector (missing trailing ones are `'asc'`)
+ * @returns {T[]} A new sorted array
+ * @throws {TypeError} when `selectors` is not an array of functions, or `orders` is neither a direction nor an array
+ * @throws {RangeError} when a direction is neither `'asc'` nor `'desc'`, or there are more directions than selectors
+ * @example
+ * const users = [{ name: 'bo', age: 30 }, { name: 'al', age: 25 }, { name: 'cy', age: 30 }];
+ * orderBy(users, [function (u) { return u.age; }, function (u) { return u.name; }], ['desc', 'asc']); // => [{ name: 'bo', age: 30 }, { name: 'cy', age: 30 }, { name: 'al', age: 25 }]
+ * orderBy([3, NaN, 1], [function (n) { return n; }]); // => [1, 3, NaN]
+ */
+export declare function orderBy<T>(array: ReadonlyArray<T>, selectors: ReadonlyArray<(item: T, index: number) => SortKey | null | undefined>, orders?: SortOrder | ReadonlyArray<SortOrder>): T[];
+/**
+ * Return the `n` first items of `sortBy(array, selector, order)` without sorting the whole array: a bounded heap selects them in
+ * O(length · log n), then only they are sorted. Same ordering rules as {@link sortBy} (stable on ties, `NaN`/invalid `Date`/nullish
+ * keys last in both directions), so the result always equals `sortBy(array, selector, order).slice(0, n)`.
+ * The selector is called exactly once per item. Use `'desc'` for the `n` largest ("top N").
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items to rank (not mutated)
+ * @param {number} n - How many items to return (a non-negative integer; all of them when larger than the array)
+ * @param {(item: T, index: number) => SortKey | null | undefined} selector - Returns the ranking key of an item
+ * @param {SortOrder} [order='asc'] - `'asc'` for the smallest keys first, `'desc'` for the largest first
+ * @returns {T[]} A new array of at most `n` items, in rank order
+ * @throws {TypeError} when `n` is not a number or `selector` is not a function
+ * @throws {RangeError} when `n` is not a non-negative integer, or `order` is neither `'asc'` nor `'desc'`
+ * @example
+ * const scores = [{ id: 'a', score: 7 }, { id: 'b', score: 9 }, { id: 'c', score: 8 }];
+ * takeFirstBy(scores, 2, function (s) { return s.score; }, 'desc'); // => [{ id: 'b', score: 9 }, { id: 'c', score: 8 }]
+ * takeFirstBy([5, NaN, 1, 3], 3, function (n) { return n; }); // => [1, 3, 5]
+ */
+export declare function takeFirstBy<T>(array: ReadonlyArray<T>, n: number, selector: (item: T, index: number) => SortKey | null | undefined, order?: SortOrder): T[];
+/**
+ * Return the item at position `index` of `sortBy(array, selector, order)` without sorting the whole array (a bounded heap of
+ * `position + 1` items, O(length · log position)): `0` is the first ranked item, `1` the second... Negative indices count from the end
+ * like `Array.prototype.at` (`-1` is the last ranked item). Same ordering rules as {@link sortBy}: stable on ties, and `NaN`/invalid
+ * `Date`/nullish keys ranked last in both directions. The selector is called exactly once per item.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items to rank (not mutated)
+ * @param {number} index - The rank to return, an integer (negative counts from the end)
+ * @param {(item: T, index: number) => SortKey | null | undefined} selector - Returns the ranking key of an item
+ * @param {SortOrder} [order='asc'] - `'asc'` to rank the smallest keys first, `'desc'` the largest first
+ * @returns {T | undefined} The item at that rank, or `undefined` when `index` is out of range
+ * @throws {TypeError} when `index` is not a number or `selector` is not a function
+ * @throws {RangeError} when `index` is not an integer, or `order` is neither `'asc'` nor `'desc'`
+ * @example
+ * nthBy([40, 10, 30, 20], 1, function (n) { return n; }); // => 20
+ * nthBy([40, 10, 30, 20], 0, function (n) { return n; }, 'desc'); // => 40
+ * nthBy([40, 10, 30, 20], -1, function (n) { return n; }); // => 40
+ * nthBy([1, 2], 5, function (n) { return n; }); // => undefined
+ */
+export declare function nthBy<T>(array: ReadonlyArray<T>, index: number, selector: (item: T, index: number) => SortKey | null | undefined, order?: SortOrder): T | undefined;
+/**
+ * Find, by binary search (O(log n) selector calls), the LOWEST index at which `value` can be inserted into `sortedArray` keeping it
+ * sorted by the key `selector` returns (before any items with an equal key). Keys are compared with the ordering rules of
+ * {@link sortBy}, so any array sorted by `sortBy(items, selector, order)` qualifies, including its trailing `NaN`/invalid
+ * `Date`/nullish keys (an unorderable `value` key is located among them). For another order, use {@link sortedIndex} with a comparator.
+ * @template T
+ * @param {ReadonlyArray<T>} sortedArray - Items sorted as `sortBy(sortedArray, selector, order)` would
+ * @param {T} value - The item to locate (its key is computed once)
+ * @param {(item: T) => SortKey | null | undefined} selector - Returns the sort key of an item
+ * @param {SortOrder} [order='asc'] - The direction the array is sorted in
+ * @returns {number} An index in `[0, length]`
+ * @throws {TypeError} when `selector` is not a function
+ * @throws {RangeError} when `order` is neither `'asc'` nor `'desc'`
+ * @example
+ * const byAge = [{ age: 20 }, { age: 30 }, { age: 30 }, { age: 40 }];
+ * sortedIndexBy(byAge, { age: 30 }, function (p) { return p.age; }); // => 1
+ * sortedIndexBy([3, 2, 1], 2, function (n) { return n; }, 'desc'); // => 1
+ */
+export declare function sortedIndexBy<T>(sortedArray: ReadonlyArray<T>, value: T, selector: (item: T) => SortKey | null | undefined, order?: SortOrder): number;
+/**
+ * Like {@link sortedIndexBy}, but returns the HIGHEST insertion index (after any items with an equal key), which keeps insertion
+ * order among equal keys when used to insert.
+ * @template T
+ * @param {ReadonlyArray<T>} sortedArray - Items sorted as `sortBy(sortedArray, selector, order)` would
+ * @param {T} value - The item to locate (its key is computed once)
+ * @param {(item: T) => SortKey | null | undefined} selector - Returns the sort key of an item
+ * @param {SortOrder} [order='asc'] - The direction the array is sorted in
+ * @returns {number} An index in `[0, length]`
+ * @throws {TypeError} when `selector` is not a function
+ * @throws {RangeError} when `order` is neither `'asc'` nor `'desc'`
+ * @example
+ * sortedLastIndexBy([{ age: 20 }, { age: 30 }, { age: 30 }, { age: 40 }], { age: 30 }, function (p) { return p.age; }); // => 3
+ */
+export declare function sortedLastIndexBy<T>(sortedArray: ReadonlyArray<T>, value: T, selector: (item: T) => SortKey | null | undefined, order?: SortOrder): number;
+/**
+ * Find, by binary search (O(log n)), the HIGHEST index at which `value` can be inserted into `sortedArray` keeping it sorted (after
+ * any equal items): the upper-bound counterpart of {@link sortedIndex}. Without a comparator, numbers, strings or bigints are
+ * ordered with `<`; the array must already be sorted in that order (and contain no `NaN`), otherwise the result is unspecified.
+ * @template T - A number, string or bigint type
+ * @param {ReadonlyArray<T>} sortedArray - An array sorted in ascending `<` order
+ * @param {T} value - The value to locate
+ * @returns {number} An index in `[0, length]`
+ * @throws {RangeError} when `value` is `NaN`
+ * @example
+ * sortedLastIndex([10, 20, 20, 30], 20); // => 3
+ * sortedLastIndex([10, 20, 30], 5); // => 0
+ */
+export declare function sortedLastIndex<T extends number | string | bigint>(sortedArray: ReadonlyArray<T>, value: T): number;
+/**
+ * Find, by binary search (O(log n)), the HIGHEST index at which `value` can be inserted into `sortedArray` keeping it sorted
+ * according to `compare` (after any items comparing equal). The array must already be sorted by `compare`.
+ * @template T
+ * @param {ReadonlyArray<T>} sortedArray - An array sorted according to `compare`
+ * @param {T} value - The value to locate
+ * @param {Comparator<T>} compare - The comparator the array is sorted by
+ * @returns {number} An index in `[0, length]`
+ * @throws {TypeError} when `compare` is given but is not a function
+ * @example
+ * sortedLastIndex([{ n: 1 }, { n: 3 }, { n: 3 }], { n: 3 }, function (a, b) { return a.n - b.n; }); // => 3
+ */
+export declare function sortedLastIndex<T>(sortedArray: ReadonlyArray<T>, value: T, compare: Comparator<T>): number;
+/**
+ * Return the last `n` items of an array (or all of them when it is shorter). Unlike `array.slice(-n)`, `n = 0` gives `[]`.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The source array
+ * @param {number} n - How many items to take (a non-negative integer)
+ * @returns {T[]} A new array with at most `n` items
+ * @throws {RangeError} when `n` is negative or not an integer
+ * @throws {TypeError} when `n` is not a number
+ * @example
+ * takeLast([1, 2, 3], 2); // => [2, 3]
+ * takeLast([1, 2, 3], 0); // => []
+ */
+export declare function takeLast<T>(array: ReadonlyArray<T>, n: number): T[];
+/**
+ * Return an array without its last `n` items.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The source array
+ * @param {number} n - How many items to drop (a non-negative integer)
+ * @returns {T[]} A new array with the remaining items
+ * @throws {RangeError} when `n` is negative or not an integer
+ * @throws {TypeError} when `n` is not a number
+ * @example
+ * dropLast([1, 2, 3], 2); // => [1]
+ * dropLast([1, 2, 3], 0); // => [1, 2, 3]
+ */
+export declare function dropLast<T>(array: ReadonlyArray<T>, n: number): T[];
+/**
+ * Return the longest suffix of an array whose items all match `predicate`, scanning from the end and stopping at the first item
+ * that does not match. The predicate receives each item with its index in the input.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The source array
+ * @param {(item: T, index: number) => boolean} predicate - The condition the kept items meet
+ * @returns {T[]} A new array with the matching trailing items, in input order
+ * @throws {TypeError} when `predicate` is not a function
+ * @example
+ * takeLastWhile([1, 5, 2, 3], function (n) { return n < 4; }); // => [2, 3]
+ */
+export declare function takeLastWhile<T>(array: ReadonlyArray<T>, predicate: (item: T, index: number) => boolean): T[];
+/**
+ * Return an array without its longest suffix whose items all match `predicate` (scanning from the end, stopping at the first item
+ * that does not match). The predicate receives each item with its index in the input.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The source array
+ * @param {(item: T, index: number) => boolean} predicate - The condition the dropped items meet
+ * @returns {T[]} A new array with the remaining items
+ * @throws {TypeError} when `predicate` is not a function
+ * @example
+ * dropLastWhile(['a', 'b', '', ''], function (s) { return s === ''; }); // => ['a', 'b']
+ */
+export declare function dropLastWhile<T>(array: ReadonlyArray<T>, predicate: (item: T, index: number) => boolean): T[];
+/**
+ * Split an array into runs of ADJACENT items with the same key (compared with SameValueZero, so `NaN` keys group together), like
+ * Python's `itertools.groupby`: unlike {@link groupBy}, a key that comes back after another one starts a new run.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The source array
+ * @param {(item: T, index: number) => unknown} keyFn - Returns the key of an item (called once per item)
+ * @returns {T[][]} The runs, in input order (each a fresh, non-empty array); `[]` for an empty array
+ * @throws {TypeError} when `keyFn` is not a function
+ * @example
+ * chunkBy([1, 3, 2, 4, 5], function (n) { return n % 2; }); // => [[1, 3], [2, 4], [5]]
+ * chunkBy(['a', 'b', 'a'], function (s) { return s; }); // => [['a'], ['b'], ['a']]
+ */
+export declare function chunkBy<T>(array: ReadonlyArray<T>, keyFn: (item: T, index: number) => unknown): T[][];
+/**
+ * Split an array in two at the first item matching `predicate`: the items before it, and the rest (starting with that item).
+ * When no item matches, the second part is empty.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The source array
+ * @param {(item: T, index: number) => boolean} predicate - The condition that starts the second part
+ * @returns {[T[], T[]]} `[before, fromMatch]`, two new arrays
+ * @throws {TypeError} when `predicate` is not a function
+ * @example
+ * splitWhen([1, 2, 3, 2], function (n) { return n > 2; }); // => [[1, 2], [3, 2]]
+ * splitWhen([1, 2], function (n) { return n > 5; }); // => [[1, 2], []]
+ */
+export declare function splitWhen<T>(array: ReadonlyArray<T>, predicate: (item: T, index: number) => boolean): [T[], T[]];
+/**
+ * Return a copy of an array with the items at positions `i` and `j` exchanged (the input is not mutated). Negative indices count
+ * from the end, like `Array.prototype.at`. Holes of sparse arrays become `undefined`.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The source array
+ * @param {number} i - Index of the first item, in `[-length, length - 1]`
+ * @param {number} j - Index of the second item, in `[-length, length - 1]`
+ * @returns {T[]} A new array, a permutation of the input
+ * @throws {RangeError} when `i` or `j` is not an integer or is out of range (any index is out of range for an empty array)
+ * @throws {TypeError} when `i` or `j` is not a number
+ * @example
+ * swap(['a', 'b', 'c'], 0, 2); // => ['c', 'b', 'a']
+ * swap(['a', 'b', 'c'], 0, -2); // => ['b', 'a', 'c']
+ */
+export declare function swap<T>(array: ReadonlyArray<T>, i: number, j: number): T[];
+/**
+ * Return a copy of an array rotated by `k` positions (the input is not mutated): a positive `k` moves every item `k` places towards
+ * the END, the last items wrapping around to the front (like Python's `deque.rotate`); a negative `k` rotates towards the start.
+ * `k` may exceed the length (it is taken modulo the length). Holes of sparse arrays become `undefined`.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The source array
+ * @param {number} k - The number of positions, an integer (any sign or magnitude)
+ * @returns {T[]} A new array, a permutation of the input
+ * @throws {RangeError} when `k` is not an integer
+ * @throws {TypeError} when `k` is not a number
+ * @example
+ * rotate([1, 2, 3, 4], 1); // => [4, 1, 2, 3]
+ * rotate([1, 2, 3, 4], -1); // => [2, 3, 4, 1]
+ * rotate([1, 2, 3], 7); // => [3, 1, 2]
+ */
+export declare function rotate<T>(array: ReadonlyArray<T>, k: number): T[];
+/**
+ * Return a copy of an array where `item` is removed if present, or appended otherwise: the state change of a checkbox list or tag
+ * picker. Presence is decided by SameValueZero (so `NaN` is found), or by comparing the keys `keyFn` returns. Every matching item
+ * is removed (a list with duplicates loses all of them).
+ * @template T
+ * @param {ReadonlyArray<T>} array - The current items (not mutated)
+ * @param {T} item - The item to toggle
+ * @param {(item: T) => unknown} [keyFn] - Returns the identity key of an item (compared with SameValueZero)
+ * @returns {T[]} A new array without the matching items, or with `item` appended when none matched
+ * @throws {TypeError} when `keyFn` is given but is not a function
+ * @example
+ * toggle(['a', 'b'], 'b'); // => ['a']
+ * toggle(['a', 'b'], 'c'); // => ['a', 'b', 'c']
+ * toggle([{ id: 1 }, { id: 2 }], { id: 1 }, function (o) { return o.id; }); // => [{ id: 2 }]
+ */
+export declare function toggle<T>(array: ReadonlyArray<T>, item: T, keyFn?: (item: T) => unknown): T[];
+/**
+ * Normalize a value that may be a single item, an array of items, or nothing, into a fresh array (lodash's `castArray`):
+ * - an array is COPIED (shallowly), so the result can be mutated without touching the input (lodash returns the same array);
+ * - `null` and `undefined` mean "nothing" and give `[]` (lodash gives `[undefined]` for `castArray(undefined)` but `[]` for
+ *   `castArray()`); to keep a nullish item, wrap it yourself: `[value]`;
+ * - anything else, including strings, `Set`s and other iterables, is wrapped as ONE item (use `Array.from` to spread an iterable).
+ * @template T
+ * @param {T | ReadonlyArray<T> | null | undefined} value - An item, an array of items, or nothing
+ * @returns {T[]} A new array
+ * @example
+ * toArray(1); // => [1]
+ * toArray([1, 2]); // => [1, 2]
+ * toArray(null); // => []
+ * toArray('ab'); // => ['ab']
+ */
+export declare function toArray<T>(value: T | ReadonlyArray<T> | null | undefined): T[];
+/**
+ * Build an object from a list of keys and a list of values: `{ [keys[i]]: values[i] }`, like `Object.fromEntries(zip(keys, values))`.
+ * Keys are DEFINED as own data properties, never assigned: a `'__proto__'` key becomes an ordinary own property instead of
+ * replacing the prototype (as it does in es-toolkit and radash), and no inherited setter or read-only property interferes.
+ * The result is a plain object (`Object.prototype`). When a key repeats, the last value wins (its position stays the first one's).
+ * @template K - The key type
+ * @template V - The value type
+ * @param {ReadonlyArray<K>} keys - The property keys (strings, numbers or symbols)
+ * @param {ReadonlyArray<V>} values - The values, one per key
+ * @returns {Record<K, V>} A new object
+ * @throws {RangeError} when the arrays have different lengths (no key or value is silently dropped)
+ * @example
+ * zipObject(['a', 'b'], [1, 2]); // => { a: 1, b: 2 }
+ * Object.keys(zipObject(['__proto__'], [1])); // => ['__proto__']
+ * zipObject(['a', 'b'], [1]); // throws RangeError
+ */
+export declare function zipObject<const K extends PropertyKey, V>(keys: ReadonlyArray<K>, values: ReadonlyArray<V>): Record<K, V>;
+/**
+ * Combine arrays element-wise with `fn`: `fn(a[i], b[i], ...)` for every index, truncating to the length of the SHORTEST array like
+ * {@link zip} (lodash pads the shorter arrays with `undefined` instead, which `fn`'s parameter types would not reveal). The
+ * arguments of `fn` are typed from the arrays, one per array.
+ * @template T - The tuple of input array types
+ * @template R - The result type of `fn`
+ * @param {(...values: Zipped<T>) => R} fn - Combines the items at one index
+ * @param {...ReadonlyArray<unknown>} arrays - The arrays to combine
+ * @returns {R[]} A new array of `fn` results; empty when called without arrays
+ * @throws {TypeError} when `fn` is not a function
+ * @example
+ * zipWith(function (a, b) { return a + b; }, [1, 2, 3], [10, 20]); // => [11, 22]
+ * zipWith(function (name, age) { return `${name} (${age})`; }, ['al', 'bo'], [30, 25]); // => ['al (30)', 'bo (25)']
+ */
+export declare function zipWith<T extends Array<ReadonlyArray<unknown>>, R>(fn: (...values: Zipped<T>) => R, ...arrays: T): R[];
+/**
+ * Return `n` distinct random items of an array (sampling WITHOUT replacement: positions are distinct, so equal values may repeat only
+ * if the input repeats them). The result is in random order: a uniformly random arrangement of a uniformly random subset, so
+ * `sampleSize(array, array.length)` is a shuffle. When `n` exceeds the length, every item is returned (like {@link take}).
+ * Partial Fisher–Yates, on a copy when `n` is a large part of the array, otherwise over a virtual copy (O(n) time and memory
+ * whatever the array length); both make exactly `min(n, length)` calls to `random` and give the same result for the same draws.
+ * Not cryptographically secure by default: pass `secureRandom` (random module) for raffles, lotteries, audits...
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items to pick from (not mutated)
+ * @param {number} n - How many items to pick (a non-negative integer)
+ * @param {RandomGenerator} [random=Math.random] - Generator of floats in `[0, 1)`, injectable for deterministic results
+ * @returns {T[]} A new array of `min(n, length)` items
+ * @throws {RangeError} when `n` is not a non-negative integer, or `random()` returns a value outside `[0, 1)`
+ * @throws {TypeError} when `n` is not a number or `random` is not a function
+ * @example
+ * sampleSize([1, 2, 3, 4, 5], 2); // e.g. [4, 1]
+ * sampleSize([1, 2, 3], 3, function () { return 0; }); // => [1, 2, 3]
+ * sampleSize([1, 2], 5).length; // => 2
+ */
+export declare function sampleSize<T>(array: ReadonlyArray<T>, n: number, random?: RandomGenerator): T[];
+/**
+ * Return the mean of the numbers `selector` returns for each item, added up with compensated summation like {@link sumBy} (so
+ * `0.1`, `0.2`, `0.3` average to exactly `0.2`). Each key is converted once with unary `+`; `NaN` keys propagate.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items
+ * @param {(item: T, index: number) => number} selector - Returns the number of an item
+ * @returns {number} The mean, or `NaN` for an empty array (like `average` from the math module)
+ * @throws {TypeError} when `selector` is not a function
+ * @example
+ * averageBy([{ n: 0.1 }, { n: 0.2 }, { n: 0.3 }], function (o) { return o.n; }); // => 0.2
+ * averageBy([], function (n: number) { return n; }); // => NaN
+ */
+export declare function averageBy<T>(array: ReadonlyArray<T>, selector: (item: T, index: number) => number): number;
+/**
+ * Return the median of the numbers `selector` returns for each item (the mean of the two middle values for an even count), with
+ * the semantics of `median` from the math module: keys are converted once with unary `+`, and the result does not depend on the
+ * item order.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items
+ * @param {(item: T, index: number) => number} selector - Returns the number of an item
+ * @returns {number} The median, or `NaN` when the array is empty or a key is `NaN`
+ * @throws {TypeError} when `selector` is not a function
+ * @example
+ * medianBy([{ age: 30 }, { age: 20 }, { age: 50 }], function (p) { return p.age; }); // => 30
+ * medianBy([4, 1, 3, 2], function (n) { return n; }); // => 2.5
+ */
+export declare function medianBy<T>(array: ReadonlyArray<T>, selector: (item: T, index: number) => number): number;
+/**
+ * Return every combination of `k` items of an array (subsets of `k` POSITIONS, items in input order), in lexicographic order of
+ * positions, like Python's `itertools.combinations`. There are `C(length, k)` of them: `[[]]` for `k = 0`, `[]` when `k > length`.
+ * Positions are distinct, not values: duplicate inputs give duplicate-looking combinations (deduplicate the input first if needed).
+ * The size is checked before anything is allocated: more than `2 ** 32 - 1` tuples or items in all throws, and since a result
+ * that does not fit in memory aborts the process instead of throwing, callers must still bound untrusted sizes.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items to choose from
+ * @param {number} k - The size of each combination (a non-negative integer)
+ * @returns {T[][]} A new array of fresh tuples
+ * @throws {TypeError} when `k` is not a number
+ * @throws {RangeError} when `k` is not a non-negative integer, or the result would exceed `2 ** 32 - 1` tuples or items
+ * @example
+ * combinations(['a', 'b', 'c'], 2); // => [['a', 'b'], ['a', 'c'], ['b', 'c']]
+ * combinations([1, 2], 3); // => []
+ */
+export declare function combinations<T>(array: ReadonlyArray<T>, k: number): T[][];
+/**
+ * Return every arrangement of `k` items of an array (ordered selections of `k` distinct POSITIONS), in lexicographic order of
+ * positions, like Python's `itertools.permutations`. There are `length! / (length - k)!` of them: `[[]]` for `k = 0`, `[]` when
+ * `k > length`. Positions are distinct, not values: duplicate inputs give duplicate-looking permutations.
+ * The size is checked before anything is allocated: more than `2 ** 32 - 1` tuples or items in all throws, and since a result
+ * that does not fit in memory aborts the process instead of throwing, callers must still bound untrusted sizes.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items to arrange
+ * @param {number} [k=array.length] - The size of each permutation (a non-negative integer)
+ * @returns {T[][]} A new array of fresh tuples
+ * @throws {TypeError} when `k` is not a number
+ * @throws {RangeError} when `k` is not a non-negative integer, or the result would exceed `2 ** 32 - 1` tuples or items
+ * @example
+ * permutations([1, 2, 3]); // => [[1, 2, 3], [1, 3, 2], [2, 1, 3], [2, 3, 1], [3, 1, 2], [3, 2, 1]]
+ * permutations(['a', 'b', 'c'], 2); // => [['a', 'b'], ['a', 'c'], ['b', 'a'], ['b', 'c'], ['c', 'a'], ['c', 'b']]
+ */
+export declare function permutations<T>(array: ReadonlyArray<T>, k?: number): T[][];
+/**
+ * Return every subset of an array (`2 ** length` of them, items in input order), in binary-counting order: item `i` is in subset
+ * `m` when bit `i` of `m` is set, so `[]` comes first and the whole array last. Positions are distinct, not values.
+ * The size is checked before anything is allocated (more than `2 ** 32 - 1` subsets or items in all throws, i.e. inputs longer
+ * than 28 items); since a result that does not fit in memory aborts the process instead of throwing, keep inputs short.
+ * @template T
+ * @param {ReadonlyArray<T>} array - The items
+ * @returns {T[][]} A new array of fresh subsets
+ * @throws {RangeError} when the result would exceed `2 ** 32 - 1` subsets or items
+ * @example
+ * powerSet(['a', 'b', 'c']); // => [[], ['a'], ['b'], ['a', 'b'], ['c'], ['a', 'c'], ['b', 'c'], ['a', 'b', 'c']]
+ */
+export declare function powerSet<T>(array: ReadonlyArray<T>): T[][];