@ix-xs/node-comfort 1.2.0 → 2.1.0

package/types/src/Arr.d.ts

@@ -1,252 +1,640 @@
 /**
- * Splits an array into chunks of a given size.
+ * How to get a value out of an item: a property name, or a function
+ * `(item, index) => value`.
+ */
+export type Iteratee<T> = (T extends object ? keyof T & (string | number) : never) | ((item: T, index: number) => unknown);
+/**
+ * A sort key for `sortBy()`: an iteratee, or `[iteratee, "asc" | "desc"]`
+ * to give that key its own direction.
+ */
+export type SortKey<T> = Iteratee<T> | [Iteratee<T>, "asc" | "desc"];
+/**
+ * Options for `sortBy()`.
+ */
+export type SortByOptions = {
+    /**
+     * Direction for keys that don't set their own. Defaults to `"asc"`.
+     */
+    order?: "asc" | "desc" | undefined;
+    /**
+     * Sort text like a person would: ignore case, respect accents, `"item2"` before `"item10"`.
+     */
+    natural?: boolean | undefined;
+    /**
+     * Language used by `natural`. Defaults to the system's.
+     */
+    locale?: string | undefined;
+};
+/**
+ * A page returned by `paginate()`.
+ */
+export type Page<T> = {
+    /**
+     * The items on this page.
+     */
+    items: T[];
+    /**
+     * The page number, starting at 1.
+     */
+    page: number;
+    perPage: number;
+    /**
+     * Total number of items.
+     */
+    total: number;
+    /**
+     * Number of pages, at least 1.
+     */
+    pages: number;
+    hasPrev: boolean;
+    hasNext: boolean;
+};
+/**
+ * Options for `toSentence()`.
+ */
+export type ToSentenceOptions = {
+    /**
+     * Language of the joining word. Defaults to `"en"`.
+     */
+    locale?: string | undefined;
+    /**
+     * `"conjunction"` joins with "and", `"disjunction"` with "or", `"unit"` with commas only. Defaults to `"conjunction"`.
+     */
+    type?: "conjunction" | "disjunction" | "unit" | undefined;
+    /**
+     * Defaults to `"long"`.
+     */
+    style?: "long" | "short" | "narrow" | undefined;
+};
+/**
+ * Splits an array into groups of `size` items. The last group can be shorter.
+ *
+ * @example
+ * arr.chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+ * arr.chunk(emails, 100).forEach(sendBatch);
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {number} size
+ * @returns {T[][]}
+ */
+export function chunk<T>(array: readonly T[], size: number): T[][];
+/**
+ * Sliding windows of `size` items, moving by `step`. Good for moving
+ * averages and comparing neighbours.
+ *
+ * @example
+ * arr.windows([1, 2, 3, 4], 2);       // [[1, 2], [2, 3], [3, 4]]
+ * arr.windows([1, 2, 3, 4, 5], 3, 2); // [[1, 2, 3], [3, 4, 5]]
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {number} size
+ * @param {number} [step=1]
+ * @returns {T[][]}
+ */
+export function windows<T>(array: readonly T[], size: number, step?: number): T[][];
+/**
+ * The first item, or the first `n` items.
+ *
+ * @example
+ * arr.first([1, 2, 3]);    // 1
+ * arr.first([1, 2, 3], 2); // [1, 2]
+ *
+ * @template T
+ * @overload
+ * @param {readonly T[]} array
+ * @returns {T | undefined}
+ */
+export function first<T>(array: readonly T[]): T | undefined;
+/**
+ * The first `n` items.
+ *
+ * @template T
+ * @overload
+ * @param {readonly T[]} array
+ * @param {number} n
+ * @returns {T[]}
+ */
+export function first<T>(array: readonly T[], n: number): T[];
+/**
+ * The last item, or the last `n` items.
+ *
+ * @example
+ * arr.last([1, 2, 3]);    // 3
+ * arr.last([1, 2, 3], 2); // [2, 3]
+ *
+ * @template T
+ * @overload
+ * @param {readonly T[]} array
+ * @returns {T | undefined}
+ */
+export function last<T>(array: readonly T[]): T | undefined;
+/**
+ * The last `n` items.
+ *
+ * @template T
+ * @overload
+ * @param {readonly T[]} array
+ * @param {number} n
+ * @returns {T[]}
+ */
+export function last<T>(array: readonly T[], n: number): T[];
+/**
+ * One page of an array, with what you need to draw pagination controls.
+ * Pages start at 1; an out-of-range page is brought back into range.
+ *
+ * @example
+ * arr.paginate(products, 2, 20);
+ * // { items: [...], page: 2, perPage: 20, total: 95, pages: 5, hasPrev: true, hasNext: true }
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {number} [page=1]
+ * @param {number} [perPage=20]
+ * @returns {Page<T>}
+ */
+export function paginate<T>(array: readonly T[], page?: number, perPage?: number): Page<T>;
+/**
+ * Removes duplicates. With an iteratee, items that give the same value are
+ * duplicates; the first one is kept.
+ *
+ * @example
+ * arr.unique([1, 1, 2, 3]);                  // [1, 2, 3]
+ * arr.unique(users, "email");                // one user per email
+ * arr.unique(tags, (t) => t.toLowerCase());
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {Iteratee<T>} [iteratee]
+ * @returns {T[]}
+ */
+export function unique<T>(array: readonly T[], iteratee?: Iteratee<T>): T[];
+/**
+ * Groups items by key.
+ *
+ * @example
+ * arr.groupBy(users, "role"); // { admin: [...], user: [...] }
+ * arr.groupBy([1, 2, 3, 4], (n) => (n % 2 ? "odd" : "even")); // { odd: [1, 3], even: [2, 4] }
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {Iteratee<T>} iteratee
+ * @returns {Record<string, T[]>}
+ */
+export function groupBy<T>(array: readonly T[], iteratee: Iteratee<T>): Record<string, T[]>;
+/**
+ * Indexes items by key. If two items share a key, the last one wins.
+ *
+ * @example
+ * const byId = arr.keyBy(users, "id");
+ * byId[42]; // user 42
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {Iteratee<T>} iteratee
+ * @returns {Record<string, T>}
+ */
+export function keyBy<T>(array: readonly T[], iteratee: Iteratee<T>): Record<string, T>;
+/**
+ * Builds a `Map` from an array. Unlike `keyBy()`, keys keep their type.
+ *
+ * @example
+ * arr.toMap(users, "id");                 // Map<number, User>
+ * arr.toMap(users, "id", (u) => u.name);  // Map<number, string>
+ *
+ * @template T
+ * @template [V=T]
+ * @param {readonly T[]} array
+ * @param {Iteratee<T>} key
+ * @param {(item: T, index: number) => V} [value] The value to store. Defaults to the item.
+ * @returns {Map<any, V>}
+ */
+export function toMap<T, V = T>(array: readonly T[], key: Iteratee<T>, value?: (item: T, index: number) => V): Map<any, V>;
+/**
+ * Counts items per key.
+ *
+ * @example
+ * arr.countBy(["a", "b", "a"]);  // { a: 2, b: 1 }
+ * arr.countBy(users, "country"); // { FR: 12, US: 7 }
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {Iteratee<T>} [iteratee] Defaults to the item itself.
+ * @returns {Record<string, number>}
+ */
+export function countBy<T>(array: readonly T[], iteratee?: Iteratee<T>): Record<string, number>;
+/**
+ * Counts the items that pass a test.
+ *
+ * @example
+ * arr.count(users, (u) => u.active);
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {(item: T, index: number) => unknown} predicate
+ * @returns {number}
+ */
+export function count<T>(array: readonly T[], predicate: (item: T, index: number) => unknown): number;
+/**
+ * Splits items into those that pass a test and those that don't.
+ *
+ * @example
+ * const [adults, minors] = arr.partition(people, (p) => p.age >= 18);
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {(item: T, index: number) => unknown} predicate
+ * @returns {[T[], T[]]}
+ */
+export function partition<T>(array: readonly T[], predicate: (item: T, index: number) => unknown): [T[], T[]];
+/**
+ * Takes one property from every item.
+ *
+ * @example
+ * arr.pluck(users, "email"); // ["ada@x.io", "bob@x.io"]
+ *
+ * @template T
+ * @template {keyof T} K
+ * @param {readonly T[]} array
+ * @param {K} key
+ * @returns {Array<T[K]>}
+ */
+export function pluck<T, K extends keyof T>(array: readonly T[], key: K): Array<T[K]>;
+/**
+ * Sorts by one or more keys, each with its own direction if you like.
+ * The sort is stable and `null`/`undefined` always go last.
  *
  * @example
- * nodeComfort.arr.chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+ * arr.sortBy(users, "age");                         // youngest first
+ * arr.sortBy(users, "age", "desc");                 // oldest first
+ * arr.sortBy(users, [["age", "desc"], "lastName"]);
+ * arr.sortBy(files, "name", { natural: true });     // "file2" before "file10"
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {SortKey<T> | Array<SortKey<T>>} keys
+ * @param {"asc" | "desc" | SortByOptions} [order="asc"]
+ * @returns {T[]}
+ */
+export function sortBy<T>(array: readonly T[], keys: SortKey<T> | Array<SortKey<T>>, order?: "asc" | "desc" | SortByOptions): T[];
+/**
+ * A shuffled copy (Fisher-Yates).
  *
- * @param {any[]} array - Source array.
- * @param {number} size - Chunk size (must be >= 1).
- * @returns {any[][]} The chunked array.
+ * @template T
+ * @param {readonly T[]} array
+ * @returns {T[]}
  */
-export function chunk(array: any[], size: number): any[][];
+export function shuffle<T>(array: readonly T[]): T[];
 /**
- * Returns a new array with duplicate values removed.
+ * One random item, or `undefined` if the array is empty.
  *
- * Pass an `iteratee` to de-duplicate by a derived key.
+ * @template T
+ * @param {readonly T[]} array
+ * @returns {T | undefined}
+ */
+export function sample<T>(array: readonly T[]): T | undefined;
+/**
+ * `n` random items, never the same one twice.
+ *
+ * @example
+ * arr.sampleSize(players, 3);
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {number} n
+ * @returns {T[]}
+ */
+export function sampleSize<T>(array: readonly T[], n: number): T[];
+/**
+ * Rotates items. Positive `n` moves items from the start to the end,
+ * negative `n` the other way.
+ *
+ * @example
+ * arr.rotate([1, 2, 3, 4], 1);  // [2, 3, 4, 1]
+ * arr.rotate([1, 2, 3, 4], -1); // [4, 1, 2, 3]
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {number} [n=1]
+ * @returns {T[]}
+ */
+export function rotate<T>(array: readonly T[], n?: number): T[];
+/**
+ * Moves one item to another position. Negative indexes count from the end.
  *
  * @example
- * nodeComfort.arr.unique([1, 1, 2, 3]);                       // [1, 2, 3]
- * nodeComfort.arr.unique([{ id: 1 }, { id: 1 }], "id");       // [{ id: 1 }]
+ * arr.move(["a", "b", "c"], 0, 2); // ["b", "c", "a"]
  *
- * @param {any[]} array - Source array.
- * @param {string|((item: any) => any)} [iteratee] - Key or function to compare by.
- * @returns {any[]} The de-duplicated array.
+ * @template T
+ * @param {readonly T[]} array
+ * @param {number} from
+ * @param {number} to
+ * @returns {T[]}
  */
-export function unique(array: any[], iteratee?: string | ((item: any) => any)): any[];
+export function move<T>(array: readonly T[], from: number, to: number): T[];
 /**
- * Groups the items of an array by a key or function.
+ * Swaps two items.
  *
  * @example
- * nodeComfort.arr.groupBy([1, 2, 3, 4], (n) => (n % 2 ? "odd" : "even"));
- * // { odd: [1, 3], even: [2, 4] }
+ * arr.swap(["a", "b", "c"], 0, 2); // ["c", "b", "a"]
  *
- * @param {any[]} array - Source array.
- * @param {string|((item: any) => any)} iteratee - Key or function to group by.
- * @returns {Record<string, any[]>} The grouped object.
+ * @template T
+ * @param {readonly T[]} array
+ * @param {number} i
+ * @param {number} j
+ * @returns {T[]}
  */
-export function groupBy(array: any[], iteratee: string | ((item: any) => any)): Record<string, any[]>;
+export function swap<T>(array: readonly T[], i: number, j: number): T[];
 /**
- * Builds an object keyed by a derived value, mapping each key to the
- * (last) matching item.
+ * Items of `array` that appear in none of the others.
  *
  * @example
- * nodeComfort.arr.keyBy([{ id: "a" }, { id: "b" }], "id");
- * // { a: { id: "a" }, b: { id: "b" } }
+ * arr.difference([1, 2, 3, 4], [2, 4]); // [1, 3]
  *
- * @param {any[]} array - Source array.
- * @param {string|((item: any) => any)} iteratee - Key or function.
- * @returns {Record<string, any>} The keyed object.
+ * @template T
+ * @param {readonly T[]} array
+ * @param {...ReadonlyArray<T>} others
+ * @returns {T[]}
  */
-export function keyBy(array: any[], iteratee: string | ((item: any) => any)): Record<string, any>;
+export function difference<T>(array: readonly T[], ...others: ReadonlyArray<T>[]): T[];
 /**
- * Partitions an array into two groups based on a predicate:
- * `[matching, notMatching]`.
+ * Items present in every array, without duplicates.
  *
  * @example
- * nodeComfort.arr.partition([1, 2, 3, 4], (n) => n % 2 === 0);
- * // [[2, 4], [1, 3]]
+ * arr.intersection([1, 2, 3], [2, 3, 4], [3, 2]); // [2, 3]
  *
- * @param {any[]} array - Source array.
- * @param {(item: any, index: number) => boolean} predicate - Test function.
- * @returns {[any[], any[]]} The two partitions.
+ * @template T
+ * @param {...ReadonlyArray<T>} arrays
+ * @returns {T[]}
  */
-export function partition(array: any[], predicate: (item: any, index: number) => boolean): [any[], any[]];
+export function intersection<T>(...arrays: ReadonlyArray<T>[]): T[];
 /**
- * Recursively flattens a nested array up to a given depth.
+ * Items present in any array, without duplicates.
  *
  * @example
- * nodeComfort.arr.flatten([1, [2, [3, [4]]]]);      // [1, 2, 3, [4]]
- * nodeComfort.arr.flatten([1, [2, [3]]], Infinity); // [1, 2, 3]
+ * arr.union([1, 2], [2, 3], [3, 4]); // [1, 2, 3, 4]
  *
- * @param {any[]} array - Source array.
- * @param {number} [depth=1] - Maximum depth to flatten.
- * @returns {any[]} The flattened array.
+ * @template T
+ * @param {...ReadonlyArray<T>} arrays
+ * @returns {T[]}
  */
-export function flatten(array: any[], depth?: number): any[];
+export function union<T>(...arrays: ReadonlyArray<T>[]): T[];
 /**
- * Returns a shuffled copy of an array (Fisher–Yates).
+ * A copy without the given values. `NaN` works too.
  *
- * Uses `Math.random` • not cryptographically secure.
+ * @example
+ * arr.without([1, 2, 3, 2], 2); // [1, 3]
  *
- * @param {any[]} array - Source array.
- * @returns {any[]} A new shuffled array.
+ * @template T
+ * @param {readonly T[]} array
+ * @param {...T} values
+ * @returns {T[]}
  */
-export function shuffle(array: any[]): any[];
+export function without<T>(array: readonly T[], ...values: T[]): T[];
 /**
- * Returns a random element from an array.
+ * A copy without the items that pass the test.
+ *
+ * @example
+ * arr.remove([1, 2, 3, 4], (n) => n % 2 === 0); // [1, 3]
  *
- * @param {any[]} array - Source array.
- * @returns {any} A random element, or undefined if empty.
+ * @template T
+ * @param {readonly T[]} array
+ * @param {(item: T, index: number) => unknown} predicate
+ * @returns {T[]}
  */
-export function sample(array: any[]): any;
+export function remove<T>(array: readonly T[], predicate: (item: T, index: number) => unknown): T[];
 /**
- * Returns `n` random elements from an array (without repetition).
+ * Removes falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`).
  *
- * @param {any[]} array - Source array.
- * @param {number} n - Number of elements to pick.
- * @returns {any[]} The sampled elements.
+ * @example
+ * arr.compact([0, 1, false, 2, "", 3, null]); // [1, 2, 3]
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @returns {Array<Exclude<T, false | 0 | 0n | "" | null | undefined>>}
  */
-export function sampleSize(array: any[], n: number): any[];
+export function compact<T>(array: readonly T[]): Array<Exclude<T, false | 0 | 0n | "" | null | undefined>>;
 /**
- * Sorts an array by one or more iteratees, ascending by default.
+ * Adds the item if it's missing, removes it if it's there. Handy for
+ * multi-select state.
  *
- * Does not mutate the input.
+ * @example
+ * arr.toggle(["a", "b"], "b"); // ["a"]
+ * arr.toggle(["a"], "b");      // ["a", "b"]
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {T} item
+ * @returns {T[]}
+ */
+export function toggle<T>(array: readonly T[], item: T): T[];
+/**
+ * Replaces the item with the same identity, or appends it if there's none.
  *
  * @example
- * nodeComfort.arr.sortBy(users, "age");
- * nodeComfort.arr.sortBy(users, [(u) => u.age, "name"]);
+ * arr.upsert(users, { id: 2, name: "Bob" }, "id");
  *
- * @param {any[]} array - Source array.
- * @param {string|((item: any) => any)|Array<string|((item: any) => any)>} iteratees - Sort key(s).
- * @param {"asc"|"desc"} [direction="asc"] - Sort direction.
- * @returns {any[]} A new sorted array.
+ * @template T
+ * @param {readonly T[]} array
+ * @param {T} item
+ * @param {Iteratee<T>} identity What makes two items "the same", like `"id"`.
+ * @returns {T[]}
  */
-export function sortBy(array: any[], iteratees: string | ((item: any) => any) | Array<string | ((item: any) => any)>, direction?: "asc" | "desc"): any[];
+export function upsert<T>(array: readonly T[], item: T, identity: Iteratee<T>): T[];
 /**
- * Returns the elements present in the first array but not in the others.
+ * Inserts items at an index. Negative indexes count from the end.
  *
  * @example
- * nodeComfort.arr.difference([1, 2, 3, 4], [2, 4]); // [1, 3]
+ * arr.insert(["a", "d"], 1, "b", "c"); // ["a", "b", "c", "d"]
  *
- * @param {any[]} array - Source array.
- * @param {...any[]} others - Arrays to subtract.
- * @returns {any[]} The difference.
+ * @template T
+ * @param {readonly T[]} array
+ * @param {number} index
+ * @param {...T} items
+ * @returns {T[]}
  */
-export function difference(array: any[], ...others: any[][]): any[];
+export function insert<T>(array: readonly T[], index: number, ...items: T[]): T[];
 /**
- * Returns the elements common to all provided arrays.
+ * Flattens nested arrays, one level by default.
  *
  * @example
- * nodeComfort.arr.intersection([1, 2, 3], [2, 3, 4]); // [2, 3]
+ * arr.flatten([1, [2, [3, [4]]]]);           // [1, 2, [3, [4]]]
+ * arr.flatten([1, [2, [3, [4]]]], Infinity); // [1, 2, 3, 4]
+ *
+ * @template T
+ * @template {number} [D=1]
+ * @param {readonly T[]} array
+ * @param {D} [depth]
+ * @returns {FlatArray<T[], D>[]}
+ */
+export function flatten<T, D extends number = 1>(array: readonly T[], depth?: D): FlatArray<T[], D>[];
+/**
+ * Pairs items by position. Shorter arrays leave `undefined` holes.
  *
- * @param {...any[]} arrays - Arrays to intersect.
- * @returns {any[]} The intersection.
+ * @example
+ * arr.zip(["a", "b"], [1, 2]); // [["a", 1], ["b", 2]]
+ *
+ * @template T
+ * @param {...ReadonlyArray<T>} arrays
+ * @returns {Array<Array<T | undefined>>}
  */
-export function intersection(...arrays: any[][]): any[];
+export function zip<T>(...arrays: ReadonlyArray<T>[]): Array<Array<T | undefined>>;
 /**
- * Returns the union (unique values) of all provided arrays.
+ * The opposite of `zip()`: rows become columns.
  *
  * @example
- * nodeComfort.arr.union([1, 2], [2, 3], [3, 4]); // [1, 2, 3, 4]
+ * arr.unzip([["a", 1], ["b", 2]]); // [["a", "b"], [1, 2]]
  *
- * @param {...any[]} arrays - Arrays to unite.
- * @returns {any[]} The union.
+ * @template T
+ * @param {ReadonlyArray<ReadonlyArray<T>>} tuples
+ * @returns {Array<Array<T | undefined>>}
  */
-export function union(...arrays: any[][]): any[];
+export function unzip<T>(tuples: ReadonlyArray<ReadonlyArray<T>>): Array<Array<T | undefined>>;
 /**
- * Zips multiple arrays together into an array of tuples.
+ * Takes items from each array in turn, then appends the rest.
  *
  * @example
- * nodeComfort.arr.zip(["a", "b"], [1, 2]); // [["a", 1], ["b", 2]]
+ * arr.interleave([1, 3, 5], [2, 4]); // [1, 2, 3, 4, 5]
  *
- * @param {...any[]} arrays - Arrays to zip.
- * @returns {any[][]} The zipped tuples.
+ * @template T
+ * @param {...ReadonlyArray<T>} arrays
+ * @returns {T[]}
  */
-export function zip(...arrays: any[][]): any[][];
+export function interleave<T>(...arrays: ReadonlyArray<T>[]): T[];
 /**
- * Splits an array into `matching` and removes falsy values.
+ * Every combination of one item from each array.
+ *
+ * @example
+ * arr.cartesian(["S", "M"], ["red", "blue"]);
+ * // [["S", "red"], ["S", "blue"], ["M", "red"], ["M", "blue"]]
  *
- * Removes `false`, `null`, `0`, `""`, `undefined` and `NaN`.
+ * @template T
+ * @param {...ReadonlyArray<T>} arrays
+ * @returns {T[][]}
+ */
+export function cartesian<T>(...arrays: ReadonlyArray<T>[]): T[][];
+/**
+ * An array of `n` items, from a value or a function of the index.
  *
  * @example
- * nodeComfort.arr.compact([0, 1, false, 2, "", 3, null]); // [1, 2, 3]
+ * arr.times(3, "x");          // ["x", "x", "x"]
+ * arr.times(3, (i) => i * 2); // [0, 2, 4]
  *
- * @param {any[]} array - Source array.
- * @returns {any[]} The compacted array.
+ * @template T
+ * @param {number} n
+ * @param {T | ((index: number) => T)} [value]
+ * @returns {T[]}
  */
-export function compact(array: any[]): any[];
+export function times<T>(n: number, value?: T | ((index: number) => T)): T[];
 /**
- * Returns the first element (or the first `n` elements) of an array.
+ * Adds up a number from each item. Non-numbers count as 0.
+ *
+ * @example
+ * arr.sumBy(cart, "price");
+ * arr.sumBy(cart, (item) => item.price * item.quantity);
  *
- * @param {any[]} array - Source array.
- * @param {number} [n] - How many elements to take.
- * @returns {any} The first element, or the first `n` elements when `n` is given.
+ * @template T
+ * @param {readonly T[]} array
+ * @param {Iteratee<T>} [iteratee]
+ * @returns {number}
  */
-export function first(array: any[], n?: number): any;
+export function sumBy<T>(array: readonly T[], iteratee?: Iteratee<T>): number;
 /**
- * Returns the last element (or the last `n` elements) of an array.
+ * The average of a number from each item, or `0` for an empty array.
+ *
+ * @example
+ * arr.averageBy(reviews, "rating"); // 4.3
  *
- * @param {any[]} array - Source array.
- * @param {number} [n] - How many elements to take.
- * @returns {any} The last element, or the last `n` elements when `n` is given.
+ * @template T
+ * @param {readonly T[]} array
+ * @param {Iteratee<T>} [iteratee]
+ * @returns {number}
  */
-export function last(array: any[], n?: number): any;
+export function averageBy<T>(array: readonly T[], iteratee?: Iteratee<T>): number;
 /**
- * Removes items from an array where the predicate is true, returning a new array.
+ * The item with the highest value.
  *
- * @param {any[]} array - Source array.
- * @param {(item: any, index: number) => boolean} predicate - Removal test.
- * @returns {any[]} A new array without the removed items.
+ * @example
+ * arr.maxBy(players, "score");
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {Iteratee<T>} [iteratee]
+ * @returns {T | undefined}
  */
-export function remove(array: any[], predicate: (item: any, index: number) => boolean): any[];
+export function maxBy<T>(array: readonly T[], iteratee?: Iteratee<T>): T | undefined;
 /**
- * Moves an element from one index to another (returns a new array).
+ * The item with the lowest value.
+ *
+ * @example
+ * arr.minBy(products, "price");
  *
- * @param {any[]} array - Source array.
- * @param {number} from - Source index.
- * @param {number} to - Destination index.
- * @returns {any[]} The reordered array.
+ * @template T
+ * @param {readonly T[]} array
+ * @param {Iteratee<T>} [iteratee]
+ * @returns {T | undefined}
  */
-export function move(array: any[], from: number, to: number): any[];
+export function minBy<T>(array: readonly T[], iteratee?: Iteratee<T>): T | undefined;
 /**
- * Counts occurrences of each derived key in an array.
+ * The items that appear more than once, each listed once.
  *
  * @example
- * nodeComfort.arr.countBy(["a", "b", "a"]);       // { a: 2, b: 1 }
- * nodeComfort.arr.countBy([1.1, 2.3, 1.7], Math.floor); // { 1: 2, 2: 1 }
+ * arr.duplicates([1, 2, 2, 3, 3, 3]); // [2, 3]
+ * arr.duplicates(users, "email");      // users whose email is taken by an earlier one
  *
- * @param {any[]} array - Source array.
- * @param {string|((item: any) => any)} [iteratee] - Key or function.
- * @returns {Record<string, number>} The counts.
+ * @template T
+ * @param {readonly T[]} array
+ * @param {Iteratee<T>} [iteratee] What makes two items "the same". Defaults to the item itself.
+ * @returns {T[]} For each repeated value, its second occurrence.
  */
-export function countBy(array: any[], iteratee?: string | ((item: any) => any)): Record<string, number>;
+export function duplicates<T>(array: readonly T[], iteratee?: Iteratee<T>): T[];
 /**
- * Sums an array by a numeric iteratee (or the values themselves).
+ * Items found in exactly one of the arrays, without duplicates.
  *
  * @example
- * nodeComfort.arr.sumBy([{ n: 1 }, { n: 2 }], "n"); // 3
+ * arr.xor([1, 2, 3], [2, 3, 4]); // [1, 4]
  *
- * @param {any[]} array - Source array.
- * @param {string|((item: any) => number)} [iteratee] - Key or function returning a number.
- * @returns {number} The sum.
+ * @template T
+ * @param {...ReadonlyArray<T>} arrays
+ * @returns {T[]}
  */
-export function sumBy(array: any[], iteratee?: string | ((item: any) => number)): number;
+export function xor<T>(...arrays: ReadonlyArray<T>[]): T[];
 /**
- * Returns the item with the maximum derived value.
+ * The items from the start, up to the first one that fails the test.
  *
- * @param {any[]} array - Source array.
- * @param {string|((item: any) => number)} [iteratee] - Key or function.
- * @returns {any} The item, or undefined if the array is empty.
+ * @example
+ * arr.takeWhile([1, 2, 5, 1], (n) => n < 3); // [1, 2]
+ *
+ * @template T
+ * @param {readonly T[]} array
+ * @param {(item: T, index: number) => unknown} predicate
+ * @returns {T[]}
  */
-export function maxBy(array: any[], iteratee?: string | ((item: any) => number)): any;
+export function takeWhile<T>(array: readonly T[], predicate: (item: T, index: number) => unknown): T[];
 /**
- * Returns the item with the minimum derived value.
+ * Skips items from the start while they pass the test, and returns the rest.
+ *
+ * @example
+ * arr.dropWhile([1, 2, 5, 1], (n) => n < 3); // [5, 1]
  *
- * @param {any[]} array - Source array.
- * @param {string|((item: any) => number)} [iteratee] - Key or function.
- * @returns {any} The item, or undefined if the array is empty.
+ * @template T
+ * @param {readonly T[]} array
+ * @param {(item: T, index: number) => unknown} predicate
+ * @returns {T[]}
  */
-export function minBy(array: any[], iteratee?: string | ((item: any) => number)): any;
+export function dropWhile<T>(array: readonly T[], predicate: (item: T, index: number) => unknown): T[];
 /**
- * Creates an array of a given length, filled by a value or generator function.
+ * Joins items the way a sentence would, in any language.
  *
  * @example
- * nodeComfort.arr.times(3, "x");           // ["x", "x", "x"]
- * nodeComfort.arr.times(3, (i) => i * 2);  // [0, 2, 4]
+ * arr.toSentence(["Ada", "Bob", "Cy"]);                    // "Ada, Bob, and Cy"
+ * arr.toSentence(["Ada", "Bob"], { locale: "fr" });        // "Ada et Bob"
+ * arr.toSentence(["red", "blue"], { type: "disjunction" }); // "red or blue"
  *
- * @param {number} n - Number of items.
- * @param {any|((index: number) => any)} [value] - Fill value or generator.
- * @returns {any[]} The generated array.
+ * @param {Iterable<unknown>} items
+ * @param {ToSentenceOptions} [options]
+ * @returns {string}
  */
-export function times(n: number, value?: any | ((index: number) => any)): any[];
+export function toSentence(items: Iterable<unknown>, options?: ToSentenceOptions): string;
 //# sourceMappingURL=Arr.d.ts.map