@ts-fns/stdlib 0.1.0 → 0.2.1

package/dist/array/index.d.mts

@@ -1,30 +1,52 @@
 import { r as NotFoundError, t as EmptyArrayError } from "../errors-CJsLpYo9.mjs";
 import { a as NonEmptyArray, s as ReadonlyNonEmptyArray } from "../types-D8f67ZCe.mjs";
-import { i as Order } from "../order.constants-BWSCg3C7.mjs";
+import { i as Order } from "../order.constants-DpGY-EDp.mjs";
 
 //#region src/array/_globalAliases.d.ts
+/**
+ * Creates an array from an iterable or array-like object.
+ * @function
+ */
 declare const from: {
-    <T>(arrayLike: ArrayLike<T>): T[];
-    <T, U>(arrayLike: ArrayLike<T>, mapfn: (v: T, k: number) => U, thisArg?: any): U[];
-    <T>(iterable: Iterable<T> | ArrayLike<T>): T[];
-    <T, U>(iterable: Iterable<T> | ArrayLike<T>, mapfn: (v: T, k: number) => U, thisArg?: any): U[];
-  }, fromAsync: {
-    <T>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T | PromiseLike<T>> | ArrayLike<T | PromiseLike<T>>): Promise<T[]>;
-    <T, U>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T> | ArrayLike<T>, mapFn: (value: Awaited<T>, index: number) => U, thisArg?: any): Promise<Awaited<U>[]>;
-  }, isArray: (arg: any) => arg is any[], of: <T>(...items: T[]) => T[];
-declare const arrayConstructor: ArrayConstructor;
+  <T>(arrayLike: ArrayLike<T>): T[];
+  <T, U>(arrayLike: ArrayLike<T>, mapfn: (v: T, k: number) => U, thisArg?: any): U[];
+  <T>(iterable: Iterable<T> | ArrayLike<T>): T[];
+  <T, U>(iterable: Iterable<T> | ArrayLike<T>, mapfn: (v: T, k: number) => U, thisArg?: any): U[];
+};
+/**
+ * Creates an array from an async iterable.
+ * @function
+ */
+declare const fromAsync: {
+  <T>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T | PromiseLike<T>> | ArrayLike<T | PromiseLike<T>>): Promise<T[]>;
+  <T, U>(iterableOrArrayLike: AsyncIterable<T> | Iterable<T> | ArrayLike<T>, mapFn: (value: Awaited<T>, index: number) => U, thisArg?: any): Promise<Awaited<U>[]>;
+};
+/**
+ * Checks whether a value is an array.
+ * @function
+ */
+declare const isArray: (arg: any) => arg is any[];
+/**
+ * Creates an array containing the given values.
+ * @function
+ */
+declare const of: <T>(...items: T[]) => T[];
+/**
+ * Alias of the built-in array constructor. `new Array() === new Arr.Ctor()
+ * @function
+ */
+declare const Ctor: ArrayConstructor;
 //#endregion
 //#region src/array/at.d.ts
 /**
- * Get an element from an array by index.
- *
- * @category Array
- * @param arr - The array to get the element from.
- * @param index - The index of the element to get.
+ * Gets an element from an array by index, including negative indices from the end.
+ * Returns a range error when the array is empty or the index is out of bounds.
  *
  * @example
  * ```ts
  * at([1, 2, 3], 1); // 2
+ * at(-1)([1, 2, 3]); // 3
+ * at([1, 2, 3], 3); // RangeError
  * ```
  */
 declare function at<T>(index: number): (arr: readonly T[]) => RangeError | T;
@@ -37,8 +59,14 @@ declare function atAssert<T>(arr: readonly T[], index: number): T;
 //#endregion
 //#region src/array/chunk.d.ts
 /**
+ * Splits an array into consecutive groups of the given size.
+ * The last chunk may contain fewer elements when the length is not evenly divisible.
  *
- * @throws {RangeError}
+ * @example
+ * ```ts
+ * chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+ * chunk(2)([1, 2, 3, 4, 5]); // [[1, 2], [3, 4], [5]]
+ * ```
  */
 declare function chunk(size: number): <T>(arr: readonly T[]) => T[][];
 declare function chunk<T>(arr: readonly T[], size: number): T[][];
@@ -49,20 +77,58 @@ declare function chunkAssert<T>(size: number): (arr: readonly T[]) => T[][];
 declare function chunkAssert<T>(arr: readonly T[], size: number): T[][];
 //#endregion
 //#region src/array/concat.d.ts
+/**
+ * Concatenates two arrays without mutating either input.
+ *
+ * @example
+ * ```ts
+ * concat([1, 2], [3, 4]); // [1, 2, 3, 4]
+ * concat([3, 4])([1, 2]); // [1, 2, 3, 4]
+ * ```
+ */
 declare function concat<T>(other: readonly T[]): (arr: readonly T[]) => T;
 declare function concat<T>(arr: readonly T[], other: readonly T[]): T;
 //#endregion
 //#region src/array/drop.d.ts
+/**
+ * Drops the first `n` elements from an array.
+ *
+ * @example
+ * ```ts
+ * drop([1, 2, 3, 4], 2); // [3, 4]
+ * drop(2)([1, 2, 3, 4]); // [3, 4]
+ * ```
+ */
 declare function drop<T>(n: number): (arr: readonly T[]) => T[];
 declare function drop<T>(arr: readonly T[], n: number): T[];
 //#endregion
 //#region src/array/every.d.ts
+/**
+ * Tests whether every element satisfies a predicate.
+ *
+ * @example
+ * ```ts
+ * every([2, 4, 6], n => n % 2 === 0); // true
+ * every(n => n > 0)([1, 2, 3]); // true
+ * ```
+ */
 declare function every<T, S extends T>(predicate: (value: T, index: number, array: readonly T[]) => value is S): (arr: readonly T[]) => arr is S[];
 declare function every<T>(predicate: (value: T, index: number, array: readonly T[]) => boolean): (arr: readonly T[]) => T[];
 declare function every<T, S extends T>(arr: readonly T[], predicate: (value: T, index: number, array: readonly T[]) => value is S): arr is S[];
 declare function every<T>(arr: readonly T[], predicate: (value: T, index: number, array: readonly T[]) => boolean): T[];
 //#endregion
 //#region src/array/find.d.ts
+/**
+ * Returns the first element that satisfies a predicate.
+ * Returns a not-found error when no element matches.
+ *
+ * @example
+ * ```ts
+ * find([1, 2, 3], n => n > 1); // 2
+ * find(n => n > 1)([1, 2, 3]); // 2
+ * find([1, 2, 3], n => n > 10); // NotFoundError
+ * ```
+ */
 declare function find<T, S extends T>(predicate: (value: T, index: number, array: readonly T[]) => value is S): (arr: readonly T[]) => NotFoundError | S;
 declare function find<T>(predicate: (value: T, index: number, array: readonly T[]) => boolean): (arr: readonly T[]) => NotFoundError | T;
 declare function find<T, S extends T>(arr: readonly T[], predicate: (value: T, index: number, array: readonly T[]) => value is S): NotFoundError | S;
@@ -76,6 +142,17 @@ declare function findAssert<T, S extends T>(arr: readonly T[], predicate: (value
 declare function findAssert<T>(arr: readonly T[], predicate: (value: T, index: number, array: readonly T[]) => boolean): T;
 //#endregion
 //#region src/array/findIndex.d.ts
+/**
+ * Returns the index of the first element that satisfies a predicate.
+ * Returns a not-found error when no element matches.
+ *
+ * @example
+ * ```ts
+ * findIndex([1, 2, 3], n => n > 1); // 1
+ * findIndex(n => n > 1)([1, 2, 3]); // 1
+ * findIndex([1, 2, 3], n => n > 10); // NotFoundError
+ * ```
+ */
 declare function findIndex<T>(predicate: (value: T, index: number, array: readonly T[]) => boolean): (arr: readonly T[]) => NotFoundError | number;
 declare function findIndex<T>(arr: readonly T[], predicate: (value: T, index: number, array: readonly T[]) => boolean): NotFoundError | number;
 declare namespace findIndex {
@@ -85,6 +162,17 @@ declare function findIndexAssert<T>(predicate: (value: T, index: number, array:
 declare function findIndexAssert<T>(arr: readonly T[], predicate: (value: T, index: number, array: readonly T[]) => boolean): number;
 //#endregion
 //#region src/array/findLast.d.ts
+/**
+ * Returns the last element that satisfies a predicate.
+ * Returns a not-found error when no element matches.
+ *
+ * @example
+ * ```ts
+ * findLast([1, 2, 3, 2], n => n === 2); // 2
+ * findLast(n => n === 2)([1, 2, 3, 2]); // 2
+ * findLast([1, 2, 3], n => n > 10); // NotFoundError
+ * ```
+ */
 declare function findLast<T, S extends T>(predicate: (value: T, index: number, array: readonly T[]) => value is S): (arr: readonly T[]) => NotFoundError | S;
 declare function findLast<T>(predicate: (value: T, index: number, array: readonly T[]) => boolean): (arr: readonly T[]) => NotFoundError | T;
 declare function findLast<T, S extends T>(arr: readonly T[], predicate: (value: T, index: number, array: readonly T[]) => value is S): NotFoundError | S;
@@ -96,6 +184,17 @@ declare function findLastAssert<T>(predicate: (value: T, index: number, array: r
 declare function findLastAssert<T>(arr: readonly T[], predicate: (value: T, index: number, array: readonly T[]) => boolean): T;
 //#endregion
 //#region src/array/findLastIndex.d.ts
+/**
+ * Returns the index of the last element that satisfies a predicate.
+ * Returns a not-found error when no element matches.
+ *
+ * @example
+ * ```ts
+ * findLastIndex([1, 2, 3, 2], n => n === 2); // 3
+ * findLastIndex(n => n === 2)([1, 2, 3, 2]); // 3
+ * findLastIndex([1, 2, 3], n => n > 10); // NotFoundError
+ * ```
+ */
 declare function findLastIndex<T>(predicate: (value: T, index: number, array: readonly T[]) => boolean): (arr: readonly T[]) => NotFoundError | number;
 declare function findLastIndex<T>(arr: readonly T[], predicate: (value: T, index: number, array: readonly T[]) => boolean): NotFoundError | number;
 declare namespace findLastIndex {
@@ -106,7 +205,14 @@ declare function findLastIndexAssert<T>(arr: readonly T[], predicate: (value: T,
 //#endregion
 //#region src/array/first.d.ts
 /**
+ * Returns the first element of an array.
+ * Returns an empty-array error when the array has no elements.
  *
+ * @example
+ * ```ts
+ * first([1, 2, 3]); // 1
+ * first([]); // EmptyArrayError
+ * ```
  */
 declare function first<T>(arr: ReadonlyNonEmptyArray<T>): T[];
 declare function first<T>(arr: readonly T[]): EmptyArrayError | T;
@@ -116,16 +222,40 @@ declare namespace first {
 declare function firstAssert<T>(arr: readonly T[]): T;
 //#endregion
 //#region src/array/flatMap.d.ts
+/**
+ * Maps each element to an array and flattens the result by one level.
+ *
+ * @example
+ * ```ts
+ * flatMap([1, 2, 3], n => [n, n * 10]); // [1, 10, 2, 20, 3, 30]
+ * flatMap(n => [n, n * 10])([1, 2, 3]); // [1, 10, 2, 20, 3, 30]
+ * ```
+ */
 declare function flatMap<T, U>(callbackfn: (value: T, index: number, array: readonly T[]) => U | readonly U[]): (arr: T[]) => U[];
 declare function flatMap<T, U>(arr: T[], callbackfn: (value: T, index: number, array: readonly U[]) => U[]): U[];
 //#endregion
 //#region src/array/forEach.d.ts
+/**
+ * Runs a callback for each element and returns the original array.
+ *
+ * @example
+ * ```ts
+ * forEach([1, 2, 3], n => console.log(n)); // [1, 2, 3]
+ * forEach(n => console.log(n))([1, 2, 3]); // [1, 2, 3]
+ * ```
+ */
 declare function forEach<T>(callbackfn: (value: T, index: number, array: readonly T[]) => void): (arr: T[]) => T[];
 declare function forEach<T>(arr: T[], callbackfn: (value: T, index: number, array: readonly T[]) => void): T[];
 //#endregion
 //#region src/array/init.d.ts
 /**
+ * Returns all elements except the last.
  *
+ * @example
+ * ```ts
+ * init([1, 2, 3]); // [1, 2]
+ * init([1]); // []
+ * ```
  */
 declare function init<T>(arr: readonly T[]): T[];
 declare namespace init {
@@ -135,8 +265,15 @@ declare function initAssert<T>(arr: readonly T[]): T[];
 //#endregion
 //#region src/array/insert.d.ts
 /**
- * `with` is reserved word. So this function is uses `insert`
- * @throws RangeError
+ * Inserts or replaces the element at the given index without mutating the original array.
+ * Named `insert` because `with` is a reserved word.
+ * Returns a range error when the index is invalid.
+ *
+ * @example
+ * ```ts
+ * insert([1, 2, 3], 1, 9); // [1, 9, 3]
+ * insert(1, 9)([1, 2, 3]); // [1, 9, 3]
+ * ```
  */
 declare function insert<T>(index: number, value: T): (arr: readonly T[]) => T[];
 declare function insert<T>(arr: readonly T[], index: number, value: T): T[];
@@ -147,18 +284,52 @@ declare function insertAssert<T>(index: number, value: T): (arr: readonly T[]) =
 declare function insertAssert<T>(arr: readonly T[], index: number, value: T): T[];
 //#endregion
 //#region src/array/isEmpty.d.ts
+/**
+ * Checks whether an array contains at least one element.
+ *
+ * @example
+ * ```ts
+ * isNotEmpty([1, 2]); // true
+ * isNotEmpty([]); // false
+ * ```
+ */
 declare function isNotEmpty<T>(value: T[]): value is NonEmptyArray<T>;
 declare function isNotEmpty<T>(value: readonly T[]): value is ReadonlyNonEmptyArray<T>;
+/**
+ * Checks whether an array has no elements.
+ *
+ * @example
+ * ```ts
+ * isEmpty([]); // true
+ * isEmpty([1]); // false
+ * ```
+ */
 declare function isEmpty<T>(value: T[]): value is [];
 declare function isEmpty<T>(value: readonly T[]): value is readonly [];
 //#endregion
 //#region src/array/join.d.ts
+/**
+ * Joins string array elements with a separator.
+ *
+ * @example
+ * ```ts
+ * join(['a', 'b', 'c'], '-'); // 'a-b-c'
+ * join('-')(['a', 'b', 'c']); // 'a-b-c'
+ * ```
+ */
 declare function join(separator: string): (arr: string[]) => string;
 declare function join(arr: string[], separator: string): string;
 //#endregion
 //#region src/array/last.d.ts
 /**
+ * Returns the last element of an array.
+ * Returns an empty-array error when the array has no elements.
  *
+ * @example
+ * ```ts
+ * last([1, 2, 3]); // 3
+ * last([]); // EmptyArrayError
+ * ```
  */
 declare function last<T>(arr: ReadonlyNonEmptyArray<T>): T;
 declare function last<T>(arr: readonly T[]): EmptyArrayError | T;
@@ -169,25 +340,52 @@ declare function lastAssert<T>(arr: readonly T[]): T;
 //#endregion
 //#region src/array/length.d.ts
 /**
- * Returns length of array
- * @param arr
- * @returns
+ * Returns the number of elements in an array.
+ *
+ * @example
+ * ```ts
+ * length([1, 2, 3]); // 3
+ * length([]); // 0
+ * ```
  */
 declare function length(arr: readonly unknown[]): number;
 //#endregion
 //#region src/array/map.d.ts
-declare function map<T, U>(callbackfn: (value: T, index: number, array: readonly T[]) => U): (arr: T[]) => U[];
-declare function map<T, U>(data: T[], callbackfn: (value: T, index: number, array: readonly T[]) => U): U[];
+/**
+ * Transforms each element with a callback.
+ *
+ * @example
+ * ```ts
+ * map([1, 2, 3], n => n * 2); // [2, 4, 6]
+ * map(n => n * 2)([1, 2, 3]); // [2, 4, 6]
+ * ```
+ */
+declare function map<T, U>(callbackfn: (value: T, index: number, array: readonly T[]) => U): (arr: readonly T[]) => U[];
+declare function map<T, U>(data: readonly T[], callbackfn: (value: T, index: number, array: readonly T[]) => U): U[];
 //#endregion
 //#region src/array/ofLength.d.ts
 /**
- * Arr.ofLength
+ * Creates a sparse array with the given length.
  *
- * @throws {RangeError}
+ * @example
+ * ```ts
+ * ofLength(3); // [empty × 3]
+ * ofLength<string>(2); // [empty × 2]
+ * ```
  */
 declare function ofLength<T = unknown>(arrayLength: number): T[];
 //#endregion
 //#region src/array/partition.d.ts
+/**
+ * Splits an array into two groups based on a predicate.
+ * The first group contains matching elements; the second contains the rest.
+ *
+ * @example
+ * ```ts
+ * partition([1, 2, 3, 4], n => n % 2 === 0); // [[2, 4], [1, 3]]
+ * partition(n => n % 2 === 0)([1, 2, 3, 4]); // [[2, 4], [1, 3]]
+ * ```
+ */
 declare function partition<T, S extends T>(predicate: (value: T, index: number, arr: readonly T[]) => value is S): (data: readonly T[]) => [S[], T[]];
 declare function partition<T>(predicate: (value: T, index: number, arr: readonly T[]) => boolean): (data: readonly T[]) => [T[], T[]];
 declare function partition<T, S extends T>(data: readonly T[], predicate: (value: T, index: number, arr: readonly T[]) => value is S): [S[], T[]];
@@ -195,7 +393,14 @@ declare function partition<T>(data: readonly T[], predicate: (value: T, index: n
 //#endregion
 //#region src/array/pop.d.ts
 /**
- * Array.pop
+ * Removes and returns the last element along with the remaining array.
+ * Returns an empty-array error when the array has no elements.
+ *
+ * @example
+ * ```ts
+ * pop([1, 2, 3]); // [3, [1, 2]]
+ * pop([]); // EmptyArrayError
+ * ```
  */
 declare function pop<T>(arr: ReadonlyNonEmptyArray<T>): [T, T[]];
 declare function pop<T>(arr: readonly T[]): EmptyArrayError | [T, T[]];
@@ -205,48 +410,130 @@ declare namespace pop {
 declare function popAssert<T>(arr: readonly T[]): [T, T[]];
 //#endregion
 //#region src/array/prepend.d.ts
+/**
+ * Prepends the elements of one array to another without mutating either input.
+ *
+ * @example
+ * ```ts
+ * prepend([3, 4], [1, 2]); // [1, 2, 3, 4]
+ * prepend([1, 2])([3, 4]); // [1, 2, 3, 4]
+ * ```
+ */
 declare function prepend<T>(other: readonly T[]): (arr: readonly T[]) => T[];
 declare function prepend<T>(arr: readonly T[], other: readonly T[]): T[];
 //#endregion
 //#region src/array/push.d.ts
+/**
+ * Appends a value to an array without mutating the original.
+ *
+ * @example
+ * ```ts
+ * push([1, 2], 3); // [1, 2, 3]
+ * push(3)([1, 2]); // [1, 2, 3]
+ * ```
+ */
 declare function push<T>(value: T): (arr: readonly T[]) => T[];
 declare function push<T>(arr: readonly T[], value: T): T[];
 //#endregion
 //#region src/array/reduce.d.ts
+/**
+ * Reduces an array to a single value using an initial accumulator.
+ *
+ * @example
+ * ```ts
+ * reduce([1, 2, 3], (acc, n) => acc + n, 0); // 6
+ * reduce((acc, n) => acc + n, 0)([1, 2, 3]); // 6
+ * ```
+ */
 declare function reduce<T, U>(arr: readonly T[], callbackFn: (acc: U, value: T, index: number, array: readonly T[]) => U, initialValue: U): U;
 declare function reduce<T, U>(callbackFn: (acc: U, value: T, index: number, array: readonly T[]) => U, initialValue: U): (arr: readonly T[]) => U;
 //#endregion
 //#region src/array/reduce1.d.ts
+/**
+ * Reduces a non-empty array to a single value using the first element as the initial accumulator.
+ *
+ * @example
+ * ```ts
+ * reduce1([1, 2, 3], (acc, n) => acc + n); // 6
+ * reduce1((acc, n) => acc + n)([1, 2, 3]); // 6
+ * ```
+ */
 declare function reduce1<T>(arr: readonly T[], callbackFn: (acc: T, value: T, index: number, array: readonly T[]) => T): T;
 declare function reduce1<T>(callbackFn: (acc: T, value: T, index: number, array: readonly T[]) => T): (arr: readonly T[]) => T;
 //#endregion
 //#region src/array/reduceRight.d.ts
+/**
+ * Reduces an array from the right using an initial accumulator.
+ *
+ * @example
+ * ```ts
+ * reduceRight([1, 2, 3], (acc, n) => acc - n, 0); // -6
+ * reduceRight((acc, n) => acc - n, 0)([1, 2, 3]); // -6
+ * ```
+ */
 declare function reduceRight<T, U>(arr: readonly T[], callbackFn: (acc: U, value: T, index: number, array: readonly T[]) => U, initialValue: U): U;
 declare function reduceRight<T, U>(callbackFn: (acc: U, value: T, index: number, array: readonly T[]) => U, initialValue: U): (arr: readonly T[]) => U;
 //#endregion
 //#region src/array/reduceRight1.d.ts
+/**
+ * Reduces a non-empty array from the right using the last element as the initial accumulator.
+ *
+ * @example
+ * ```ts
+ * reduceRight1([1, 2, 3], (acc, n) => acc - n); // 0
+ * reduceRight1((acc, n) => acc - n)([1, 2, 3]); // 0
+ * ```
+ */
 declare function reduceRight1<T>(arr: readonly T[], callbackFn: (acc: T, value: T, index: number, array: readonly T[]) => T): T;
 declare function reduceRight1<T>(callbackFn: (acc: T, value: T, index: number, array: readonly T[]) => T): (arr: readonly T[]) => T;
 //#endregion
 //#region src/array/rest.d.ts
 /**
- * Returns an array excluding the first entry
- * @param arr
- * @returns
+ * Returns all elements except the first.
+ *
+ * @example
+ * ```ts
+ * rest([1, 2, 3]); // [2, 3]
+ * rest([1]); // []
+ * ```
  */
 declare function rest<T>(arr: readonly T[]): T[];
 //#endregion
 //#region src/array/reverse.d.ts
-declare function reverse(index: number): <T>(arr: readonly T[]) => T[];
-declare function reverse<T>(arr: readonly T[], index: number): T[];
+/**
+ * Returns a reversed copy of an array without mutating the original.
+ *
+ * @example
+ * ```ts
+ * reverse([1, 2, 3]); // [3, 2, 1]
+ * ```
+ */
+declare function reverse<T>(arr: readonly T[]): T[];
 //#endregion
 //#region src/array/scan.d.ts
+/**
+ * Returns the intermediate accumulator values produced while reducing an array.
+ * The first element is the initial value; each subsequent element is the accumulator after processing one more item.
+ *
+ * @example
+ * ```ts
+ * scan([1, 2, 3], (acc, n) => acc + n, 0); // [0, 1, 3, 6]
+ * scan((acc, n) => acc + n, 0)([1, 2, 3]); // [0, 1, 3, 6]
+ * ```
+ */
 declare function scan<T, U>(callbackFn: (acc: U, value: T, index: number, array: readonly T[]) => U, initialValue: U): (arr: T[]) => U[];
 declare function scan<T, U>(arr: T[], callbackFn: (acc: U, value: T, index: number, array: readonly T[]) => U, initialValue: U): U[];
 //#endregion
 //#region src/array/shift.d.ts
 /**
+ * Removes and returns the first element along with the remaining array.
+ * Returns an empty-array error when the array has no elements.
  *
+ * @example
+ * ```ts
+ * shift([1, 2, 3]); // [1, [2, 3]]
+ * shift([]); // EmptyArrayError
+ * ```
  */
 declare function shift<T>(arr: ReadonlyNonEmptyArray<T>): [T, T[]];
 declare namespace shift {
@@ -255,51 +542,141 @@ declare namespace shift {
 declare function shiftAssert<T>(arr: readonly T[]): [T, T[]];
 //#endregion
 //#region src/array/shuffle.d.ts
-declare function shuffle<T>(arr: T[]): T[];
+/**
+ * Returns a shuffled copy of an array using the Fisher-Yates algorithm.
+ *
+ * @example
+ * ```ts
+ * shuffle([1, 2, 3, 4]); // e.g. [3, 1, 4, 2]
+ * ```
+ */
+declare function shuffle<T>(arr: readonly T[]): T[];
 //#endregion
 //#region src/array/some.d.ts
+/**
+ * Tests whether at least one element satisfies a predicate.
+ *
+ * @example
+ * ```ts
+ * some([1, 2, 3], n => n > 2); // true
+ * some(n => n > 2)([1, 2, 3]); // true
+ * ```
+ */
 declare function some<T>(predicate: (value: T, index: number, array: readonly T[]) => boolean): (arr: readonly T[]) => T[];
 declare function some<T>(arr: readonly T[], predicate: (value: T, index: number, array: readonly T[]) => boolean): T[];
 //#endregion
 //#region src/array/sort.d.ts
+/**
+ * Returns a sorted copy of an array using a comparison function.
+ *
+ * @example
+ * ```ts
+ * sort([3, 1, 2], (a, b) => a - b); // [1, 2, 3]
+ * sort((a, b) => a - b)([3, 1, 2]); // [1, 2, 3]
+ * ```
+ */
 declare function sort<T>(compareFn: (left: T, right: T) => Order): (arr: T[]) => T[];
 declare function sort<T>(arr: T[], compareFn: (left: T, right: T) => Order): T[];
 //#endregion
 //#region src/array/sortBy.d.ts
+/**
+ * Returns a sorted copy of an array by mapping each element to a comparable value first.
+ *
+ * @example
+ * ```ts
+ * sortBy([{ n: 3 }, { n: 1 }], x => x.n); // [{ n: 1 }, { n: 3 }]
+ * sortBy(x => x.n)([{ n: 3 }, { n: 1 }]); // [{ n: 1 }, { n: 3 }]
+ * ```
+ */
 declare function sortBy<T>(mapFn: (value: T) => Date | boolean | number | string): (arr: T[]) => T[];
 declare function sortBy<T>(arr: T[], mapFn: (value: T) => Date | boolean | number | string): T[];
 //#endregion
 //#region src/array/take.d.ts
 /**
+ * Returns the first `limit` elements from an array.
  *
- * @throws {RangeError}
+ * @example
+ * ```ts
+ * take([1, 2, 3, 4], 2); // [1, 2]
+ * take(3)([1, 2, 3, 4]); // [1, 2, 3]
+ * ```
  */
 declare function take<T>(limit: number): (arr: readonly T[]) => T[];
 declare function take<T>(arr: readonly T[], limit: number): T[];
 //#endregion
 //#region src/array/transpose.d.ts
+/**
+ * Transposes a matrix so rows become columns and columns become rows.
+ *
+ * @example
+ * ```ts
+ * transpose([[1, 2], [3, 4], [5, 6]]); // [[1, 3, 5], [2, 4, 6]]
+ * ```
+ */
 declare function transpose<T>(arr: T[][]): T[][];
 //#endregion
 //#region src/array/unique.d.ts
+/**
+ * Returns a copy of an array with duplicate values removed.
+ *
+ * @example
+ * ```ts
+ * unique([1, 2, 2, 3]); // [1, 2, 3]
+ * unique([]); // []
+ * ```
+ */
 declare function unique<T>(arr: readonly T[]): T[];
 //#endregion
 //#region src/array/uniqueBy.d.ts
+/**
+ * Returns a copy of an array with duplicates removed by a derived key.
+ * Keeps the first occurrence for each key.
+ *
+ * @example
+ * ```ts
+ * uniqueBy([{ id: 1 }, { id: 2 }, { id: 1 }], x => x.id); // [{ id: 1 }, { id: 2 }]
+ * uniqueBy(x => x.id)([{ id: 1 }, { id: 2 }, { id: 1 }]); // [{ id: 1 }, { id: 2 }]
+ * ```
+ */
 declare function uniqueBy<T>(mapFn: (value: T) => unknown): (arr: T[]) => T[];
 declare function uniqueBy<T>(arr: T[], mapFn: (value: T) => unknown): T[];
 //#endregion
 //#region src/array/uniqueWith.d.ts
+/**
+ * Returns a copy of an array with duplicates removed using a custom equality function.
+ * Keeps the first occurrence of each equivalent value.
+ *
+ * @example
+ * ```ts
+ * uniqueWith([1, 1.0, 2], (a, b) => a === b); // [1, 2]
+ * uniqueWith([], (a, b) => a === b); // []
+ * ```
+ */
 declare function uniqueWith<T>(arr: readonly T[], isEqual: (left: T, right: T) => boolean): T[];
 //#endregion
 //#region src/array/unshift.d.ts
 /**
- * Immutably inserts new elements at the start of an array. Returns the new array.
+ * Prepends a value to an array without mutating the original.
+ *
+ * @example
+ * ```ts
+ * unshift([1, 2], 0); // [0, 1, 2]
+ * unshift(0)([1, 2]); // [0, 1, 2]
+ * ```
  */
 declare function unshift<T>(value: T): (arr: readonly T[]) => T[];
 declare function unshift<T>(arr: readonly T[], value: T): T[];
 //#endregion
 //#region src/array/update.d.ts
 /**
+ * Replaces the element at the given index using a callback without mutating the original array.
+ * Returns a range error when the index is out of bounds.
  *
+ * @example
+ * ```ts
+ * update([1, 2, 3], 1, n => n * 10); // [1, 20, 3]
+ * update(1, n => n * 10)([1, 2, 3]); // [1, 20, 3]
+ * ```
  */
 declare function update<T>(index: number, fn: (value: T) => T): (arr: readonly T[]) => RangeError | T[];
 declare function update<T>(arr: readonly T[], index: number, fn: (value: T) => T): RangeError | T[];
@@ -311,8 +688,14 @@ declare function updateAssert<T>(arr: readonly T[], index: number, fn: (value: T
 //#endregion
 //#region src/array/window.d.ts
 /**
+ * Creates a sliding window of consecutive elements with the given size.
+ * Returns an empty array when the window size is larger than the input.
  *
- * @throws {RangeError}
+ * @example
+ * ```ts
+ * window([1, 2, 3, 4], 2); // [[1, 2], [2, 3], [3, 4]]
+ * window(3)([1, 2, 3, 4]); // [[1, 2, 3], [2, 3, 4]]
+ * ```
  */
 declare function window(size: number): <T>(arr: readonly T[]) => T[][];
 declare function window<T>(arr: readonly T[], size: number): T[][];
@@ -323,12 +706,30 @@ declare function windowAssert<T>(size: number): (arr: readonly T[]) => T[][];
 declare function windowAssert<T>(arr: readonly T[], size: number): T[][];
 //#endregion
 //#region src/array/zip.d.ts
+/**
+ * Pairs elements from two arrays up to the length of the shorter one.
+ *
+ * @example
+ * ```ts
+ * zip([1, 2, 3], ['a', 'b']); // [[1, 'a'], [2, 'b']]
+ * zip(['a', 'b'])([1, 2, 3]); // [[1, 'a'], [2, 'b']]
+ * ```
+ */
 declare function zip<L, R>(other: readonly R[]): (arr: readonly L[]) => [L, R][];
 declare function zip<L, R>(arr: readonly L[], other: readonly R[]): [L, R][];
 //#endregion
 //#region src/array/zipWith.d.ts
+/**
+ * Combines two arrays element-wise using a callback, up to the length of the shorter one.
+ *
+ * @example
+ * ```ts
+ * zipWith([1, 2, 3], [10, 20], (a, b) => a + b); // [11, 22]
+ * zipWith([10, 20], (a, b) => a + b)([1, 2, 3]); // [11, 22]
+ * ```
+ */
 declare function zipWith<L, R, U>(other: readonly R[], fn: (l: L, R: R) => U): (arr: readonly L[]) => U[];
 declare function zipWith<L, R, U>(arr: readonly L[], other: readonly R[], fn: (l: L, R: R) => U): U[];
 //#endregion
-export { arrayConstructor as Array, at, atAssert, chunk, concat, drop, every, find, findIndex, findLast, findLastIndex, first, flatMap, forEach, from, fromAsync, init, insert, isArray, isEmpty, isNotEmpty, join, last, length, map, of, ofLength, partition, pop, prepend, push, reduce, reduce1, reduceRight, reduceRight1, rest, reverse, scan, shift, shuffle, some, sort, sortBy, take, transpose, unique, uniqueBy, uniqueWith, unshift, update, window, zip, zipWith };
+export { Ctor, at, chunk, concat, drop, every, find, findIndex, findLast, findLastIndex, first, flatMap, forEach, from, fromAsync, init, insert, isArray, isEmpty, isNotEmpty, join, last, length, map, of, ofLength, partition, pop, prepend, push, reduce, reduce1, reduceRight, reduceRight1, rest, reverse, scan, shift, shuffle, some, sort, sortBy, take, transpose, unique, uniqueBy, uniqueWith, unshift, update, window, zip, zipWith };
 //# sourceMappingURL=index.d.mts.map