@duplojs/utils 1.4.32 → 1.4.33

package/dist/array/length.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include array/length/index.md}
+ */
 function length(input) {
     return input.length;
 }

package/dist/array/length.d.ts

@@ -1 +1,25 @@
+/**
+ * Gets the length of an array.
+ * 
+ * Signature: `length(array)` → returns the length
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.length([1, 2, 3]); // 3
+ * 
+ * A.length(<const>["alpha", "beta"]); // 2
+ * 
+ * A.length([]); // 0
+ * ```
+ * 
+ * @remarks
+ * - Tuple inputs preserve their literal length
+ * 
+ * @see [`A.lengthEqual`](https://utils.duplojs.dev/en/v1/api/array/lengthEqual) For length predicates
+ * @see https://utils.duplojs.dev/en/v1/api/array/length
+ * 
+ * @namespace A
+ * 
+ */
 export declare function length<GenericInput extends readonly unknown[]>(input: GenericInput): GenericInput["length"];

package/dist/array/length.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include array/length/index.md}
+ */
 function length(input) {
     return input.length;
 }

package/dist/array/lengthEqual.d.ts

@@ -1,3 +1,47 @@
 import { type CreateTuple } from "./types";
+/**
+ * Checks if an array has a specific length.
+ * 
+ * **Supported call styles:**
+ * - Classic: `lengthEqual(array, length)` → returns a boolean
+ * - Curried: `lengthEqual(length)` → returns a function waiting for the array
+ * - Classic predicate: `lengthEqual(array, length)` → narrows to a tuple
+ * - Curried predicate: `lengthEqual(length)` → narrows to a tuple
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.lengthEqual(
+ * 	[1, 2, 3],
+ * 	2,
+ * ); // false
+ * 
+ * const numbersList = [1, 2];
+ * 
+ * if (A.lengthEqual(numbersList, 2)) {
+ * 	// numbersList has length 2
+ * }
+ * 
+ * pipe(
+ * 	numbersList,
+ * 	when(
+ * 		A.lengthEqual(2),
+ * 		(items) => {
+ * 			// items has length 2
+ * 		},
+ * 	),
+ * );
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Predicate overloads (type guards) narrow the array to a tuple of the given length
+ * 
+ * @see [`A.length`](https://utils.duplojs.dev/en/v1/api/array/length) For getting length
+ * @see https://utils.duplojs.dev/en/v1/api/array/lengthEqual
+ * 
+ * @namespace A
+ * 
+ */
 export declare function lengthEqual<GenericArray extends readonly unknown[], GenericLength extends number>(length: GenericLength): (array: GenericArray) => array is CreateTuple<GenericArray[number], GenericLength>;
 export declare function lengthEqual<GenericArray extends readonly unknown[], GenericLength extends number>(array: GenericArray, length: GenericLength): array is CreateTuple<GenericArray[number], GenericLength>;

package/dist/array/map.d.ts

@@ -2,6 +2,39 @@ interface ArrayMapParams<GenericInputArray extends readonly unknown[]> {
     index: number;
     self: GenericInputArray;
 }
+/**
+ * Transforms each element of an array.
+ * 
+ * **Supported call styles:**
+ * - Classic: `map(array, theFunction)` → returns a new array
+ * - Curried: `map(theFunction)` → returns a function waiting for the array
+ * 
+ * The mapping function receives `(element, { index, self })`, where `index` is the element
+ * position and `self` is the original array.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.map(
+ * 	[1, 2, 3],
+ * 	(value) => value * 2,
+ * ); // [2, 4, 6]
+ * 
+ * pipe(
+ * 	["alpha", "beta"],
+ * 	A.map((value, { index }) => `${index}:${value}`),
+ * ); // ["0:alpha", "1:beta"]
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Array.prototype.map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map)
+ * 
+ * @see [`A.filter`](https://utils.duplojs.dev/en/v1/api/array/filter) For selecting elements
+ * @see [`A.reduce`](https://utils.duplojs.dev/en/v1/api/array/reduce) For accumulating values
+ * @see https://utils.duplojs.dev/en/v1/api/array/map
+ * 
+ * @namespace A
+ * 
+ */
 export declare function map<GenericInput extends readonly unknown[], GenericOutput extends unknown>(theFunction: (element: GenericInput[number], params: ArrayMapParams<GenericInput>) => GenericOutput): (input: GenericInput) => GenericOutput[];
 export declare function map<GenericInput extends readonly unknown[], GenericOutput extends unknown>(input: GenericInput, theFunction: (element: GenericInput[number], params: ArrayMapParams<GenericInput>) => GenericOutput): GenericOutput[];
 export {};

package/dist/array/maxElements.d.ts

@@ -1,2 +1,35 @@
+/**
+ * Checks whether an array has at most a given length.
+ * 
+ * **Supported call styles:**
+ * - Classic: `maxElements(array, maxLength)` → returns a boolean
+ * - Curried: `maxElements(maxLength)` → returns a function waiting for the array
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.maxElements(
+ * 	[1, 2, 3],
+ * 	2,
+ * ); // false
+ * 
+ * A.maxElements(
+ * 	[1, 2],
+ * 	2,
+ * ); // true
+ * 
+ * pipe(
+ * 	["alpha", "beta"],
+ * 	A.maxElements(3),
+ * ); // true
+ * 
+ * ```
+ * 
+ * @see [`A.minElements`](https://utils.duplojs.dev/en/v1/api/array/minElements) For minimum length checks
+ * @see https://utils.duplojs.dev/en/v1/api/array/maxElements
+ * 
+ * @namespace A
+ * 
+ */
 export declare function maxElements<GenericArray extends readonly unknown[]>(maxLength: number): (array: GenericArray) => boolean;
 export declare function maxElements<GenericArray extends readonly unknown[]>(array: GenericArray, maxLength: number): boolean;

package/dist/array/maxOf.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include array/maxOf/index.md}
+ */
 function maxOf(values) {
     const [first, ...rest] = values;
     if (first === undefined) {

package/dist/array/maxOf.d.ts

@@ -1 +1,29 @@
+/**
+ * Gets the maximum value from a number array.
+ * 
+ * Signature: `maxOf(array)` → returns a number or `undefined`
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.maxOf(
+ * 	[1, 5, 2],
+ * ); // 5
+ * 
+ * A.maxOf(
+ * 	[-1, -3],
+ * ); // -1
+ * 
+ * A.maxOf(
+ * 	[],
+ * ); // undefined
+ * 
+ * ```
+ * 
+ * @see [`A.minOf`](https://utils.duplojs.dev/en/v1/api/array/minOf) For the minimum value
+ * @see https://utils.duplojs.dev/en/v1/api/array/maxOf
+ * 
+ * @namespace A
+ * 
+ */
 export declare function maxOf<GenericArray extends readonly number[]>(values: GenericArray): number | undefined;

package/dist/array/maxOf.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include array/maxOf/index.md}
+ */
 function maxOf(values) {
     const [first, ...rest] = values;
     if (first === undefined) {

package/dist/array/minElements.d.ts

@@ -1,4 +1,51 @@
 import { type CreateTuple } from "./types/createTuple";
+/**
+ * Checks if an array has at least a given length.
+ * 
+ * **Supported call styles:**
+ * - Classic: `minElements(array, minLength)` → returns a boolean
+ * - Curried: `minElements(minLength)` → returns a function waiting for the array
+ * - Classic predicate: `minElements(array, minLength)` → narrows to a tuple prefix
+ * - Curried predicate: `minElements(minLength)` → narrows to a tuple prefix
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.minElements(
+ * 	[1],
+ * 	2,
+ * ); // false
+ * 
+ * const valuesList = [
+ * 	1,
+ * 	2,
+ * ];
+ * 
+ * if (A.minElements(valuesList, 2)) {
+ * 	// valuesList has at least 2 items
+ * }
+ * 
+ * pipe(
+ * 	valuesList,
+ * 	when(
+ * 		A.minElements(2),
+ * 		(items) => {
+ * 			// items has at least 2 items
+ * 		},
+ * 	),
+ * );
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Predicate overloads (type guards) narrow the array length but can still be `false`
+ * 
+ * @see [`A.maxElements`](https://utils.duplojs.dev/en/v1/api/array/maxElements) For maximum length checks
+ * @see https://utils.duplojs.dev/en/v1/api/array/minElements
+ * 
+ * @namespace A
+ * 
+ */
 export declare function minElements<GenericArray extends readonly unknown[], GenericLength extends number>(minLength: GenericLength): (array: GenericArray) => array is [
     ...CreateTuple<GenericArray[number], GenericLength>,
     ...GenericArray[number][]

package/dist/array/minOf.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include array/minOf/index.md}
+ */
 function minOf(values) {
     const [first, ...rest] = values;
     if (first === undefined) {

package/dist/array/minOf.d.ts

@@ -1 +1,29 @@
+/**
+ * Gets the minimum value from a number array.
+ * 
+ * Signature: `minOf(array)` → returns a number or `undefined`
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.minOf(
+ * 	[1, 5, 2],
+ * ); // 1
+ * 
+ * A.minOf(
+ * 	[-1, -3],
+ * ); // -3
+ * 
+ * A.minOf(
+ * 	[],
+ * ); // undefined
+ * 
+ * ```
+ * 
+ * @see [`A.maxOf`](https://utils.duplojs.dev/en/v1/api/array/maxOf) For the maximum value
+ * @see https://utils.duplojs.dev/en/v1/api/array/minOf
+ * 
+ * @namespace A
+ * 
+ */
 export declare function minOf<GenericArray extends readonly number[]>(values: GenericArray): number | undefined;

package/dist/array/minOf.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include array/minOf/index.md}
+ */
 function minOf(values) {
     const [first, ...rest] = values;
     if (first === undefined) {

package/dist/array/notIncludes.d.ts

@@ -1,4 +1,45 @@
 import { type RemoveFromUnion } from "../common";
 export type NotIncludeValue = string | null | undefined | boolean | number | bigint | symbol;
+/**
+ * Checks that an array does not include a value.
+ * 
+ * **Supported call styles:**
+ * - Classic: `notIncludes(array, value)` → returns a boolean
+ * - Curried: `notIncludes(value)` → returns a function waiting for the array
+ * - Classic predicate: `notIncludes(array, value)` → narrows element types
+ * - Curried predicate: `notIncludes(value)` → narrows element types
+ * 
+ * Uses same-value-zero comparison.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * const mixedList = ["alpha", null];
+ * 
+ * if (A.notIncludes(mixedList, null)) {
+ * 	// mixedList is string[]
+ * }
+ * 
+ * pipe(
+ * 	mixedList,
+ * 	when(
+ * 		A.notIncludes(null),
+ * 		(items) => {
+ * 			// items is string[]
+ * 		},
+ * 	),
+ * );
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Predicate overloads (type guards) narrow the element type
+ * 
+ * @see [`A.includes`](https://utils.duplojs.dev/en/v1/api/array/includes) For the opposite check
+ * @see [`A.filter`](https://utils.duplojs.dev/en/v1/api/array/filter) For selecting elements
+ * @see https://utils.duplojs.dev/en/v1/api/array/notIncludes
+ * 
+ * @namespace A
+ * 
+ */
 export declare function notIncludes<GenericArrayValue extends unknown, const GenericNotIncludeValue extends RemoveFromUnion<Extract<GenericArrayValue, NotIncludeValue>, Exclude<NotIncludeValue, null | undefined>>>(value: GenericNotIncludeValue): (input: readonly GenericArrayValue[]) => input is Exclude<GenericArrayValue, GenericNotIncludeValue>[];
 export declare function notIncludes<GenericArrayValue extends unknown, const GenericNotIncludeValue extends RemoveFromUnion<Extract<GenericArrayValue, NotIncludeValue>, Exclude<NotIncludeValue, null | undefined>>>(input: readonly GenericArrayValue[], value: GenericNotIncludeValue): input is Exclude<GenericArrayValue, GenericNotIncludeValue>[];

package/dist/array/pop.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include array/pop/index.md}
+ */
 function pop(array) {
     return array.slice(0, -1);
 }

package/dist/array/pop.d.ts

@@ -1,3 +1,34 @@
 import { type AnyTuple } from "../common";
 import { type PopTuple } from "./types";
+/**
+ * Removes the last element from an array.
+ * 
+ * Signature: `pop(array)` → returns a new array
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.pop(
+ * 	[1, 2, 3],
+ * ); // [1, 2]
+ * 
+ * A.pop(
+ * 	<const>["alpha", "beta"],
+ * ); // ["alpha"]
+ * 
+ * A.pop(
+ * 	[],
+ * ); // []
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Type-safe with tuple types: return type is inferred without the last element
+ * 
+ * @see [`A.shift`](https://utils.duplojs.dev/en/v1/api/array/shift) For removing the first element
+ * @see https://utils.duplojs.dev/en/v1/api/array/pop
+ * 
+ * @namespace A
+ * 
+ */
 export declare function pop<const GenericArray extends readonly unknown[]>(array: GenericArray): GenericArray extends AnyTuple ? PopTuple<GenericArray> : GenericArray;

package/dist/array/pop.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include array/pop/index.md}
+ */
 function pop(array) {
     return array.slice(0, -1);
 }

package/dist/array/push.d.ts

@@ -1,2 +1,40 @@
+/**
+ * Adds elements to the end of an array.
+ * 
+ * **Supported call styles:**
+ * - Classic: `push(array, item, ...items)` → returns a new array
+ * - Curried: `push(item)` → returns a function waiting for the array
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.push(
+ * 	[1, 2],
+ * 	3,
+ * ); // [1, 2, 3]
+ * 
+ * A.push(
+ * 	[1, 2],
+ * 	3,
+ * 	4,
+ * ); // [1, 2, 3, 4]
+ * 
+ * pipe(
+ * 	["alpha", "beta"],
+ * 	A.push("gamma"),
+ * ); // ["alpha", "beta", "gamma"]
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Classic style supports multiple items via rest parameters
+ * - Curried style adds only a single item
+ * 
+ * @see [`A.unshift`](https://utils.duplojs.dev/en/v1/api/array/unshift) For adding at the start
+ * @see https://utils.duplojs.dev/en/v1/api/array/push
+ * 
+ * @namespace A
+ * 
+ */
 export declare function push<GenericElement extends unknown>(item: NoInfer<GenericElement>): (input: readonly GenericElement[]) => GenericElement[];
 export declare function push<GenericElement extends unknown>(input: readonly GenericElement[], item: NoInfer<GenericElement>, ...items: NoInfer<GenericElement>[]): GenericElement[];

package/dist/array/reduce.cjs

@@ -7,6 +7,9 @@ var push = require('./push.cjs');
 var override = require('../object/override.cjs');
 
 const arrayReduceFromKind = kind.createKind("array-reduce-from");
+/**
+ * {@include array/reduceFrom/index.md}
+ */
 function reduceFrom(value) {
     return arrayReduceFromKind.setTo(wrapValue.wrapValue(value));
 }

package/dist/array/reduce.d.ts

@@ -21,10 +21,84 @@ export interface ArrayReduceFunctionParams<GenericInputArray extends readonly un
 declare const arrayReduceFromKind: import("../common").KindHandler<import("../common").KindDefinition<"array-reduce-from", unknown>>;
 export interface ArrayReduceFromResult<GenericValue extends unknown = unknown> extends Kind<typeof arrayReduceFromKind.definition>, WrappedValue<GenericValue> {
 }
+/**
+ * Creates a typed start value for `reduce`.
+ * 
+ * Signature: `reduceFrom(value)` → returns a reduce start wrapper
+ * 
+ * This is useful for preserving object and array types in reductions.
+ * 
+ * ```ts
+ * A.reduce(
+ * 	[1, 2],
+ * 	A.reduceFrom(0),
+ * 	({ element, lastValue, next }) => next(lastValue + element),
+ * ); // 3
+ * 
+ * A.reduce(
+ * 	["alpha", "beta"],
+ * 	A.reduceFrom({}),
+ * 	({ element, lastValue, nextWithObject }) => nextWithObject(lastValue, { [element]: true }),
+ * ); // { alpha: true, beta: true }
+ * 
+ * A.reduce(
+ * 	[1, 2],
+ * 	A.reduceFrom([0]),
+ * 	({ element, lastValue, nextPush }) => nextPush(lastValue, element),
+ * ); // [0, 1, 2]
+ * 
+ * ```
+ * 
+ * @see [`A.reduce`](https://utils.duplojs.dev/en/v1/api/array/reduce) For reducing arrays
+ * @see https://utils.duplojs.dev/en/v1/api/array/reduceFrom
+ * 
+ * @namespace A
+ * 
+ */
 export declare function reduceFrom<GenericValue extends unknown>(value: GenericValue): ArrayReduceFromResult<GenericValue>;
 export declare const reduceTools: Pick<ArrayReduceFunctionParams<any, any>, "exit" | "next" | "nextWithObject" | "nextPush">;
 export type ArrayEligibleReduceFromValue = number | string | bigint | boolean | ArrayReduceFromResult;
 export type ArrayReduceFromValue<GenericValue extends ArrayEligibleReduceFromValue> = GenericValue extends ArrayReduceFromResult ? Unwrap<GenericValue> : ToLargeEnsemble<GenericValue>;
+/**
+ * Reduces an array to a single value.
+ * 
+ * **Supported call styles:**
+ * - Classic: `reduce(array, startValue, theFunction)` → returns the reduced value
+ * - Curried: `reduce(startValue, theFunction)` → returns a function waiting for the array
+ * 
+ * The function receives `{ element, index, lastValue, next, exit, nextWithObject, nextPush, self }`.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.reduce(
+ * 	[1, 2, 3],
+ * 	0,
+ * 	({ element, lastValue, next }) => next(lastValue + element),
+ * ); // 6
+ * 
+ * pipe(
+ * 	[1, 2],
+ * 	A.reduce(1, ({ element, lastValue, next }) => next(lastValue * element)),
+ * ); // 2
+ * 
+ * A.reduce(
+ * 	[1, 2, 3],
+ * 	0,
+ * 	({ element, lastValue, next, exit }) => element === 2 ? exit(lastValue) : next(lastValue + element),
+ * ); // 1
+ * 
+ * ```
+ * 
+ * @remarks
+ * - `exit` stops the reduction early
+ * 
+ * @see [`A.reduceFrom`](https://utils.duplojs.dev/en/v1/api/array/reduceFrom) For typed start values
+ * @see [`A.reduceRight`](https://utils.duplojs.dev/en/v1/api/array/reduceRight) For reducing from the end
+ * @see https://utils.duplojs.dev/en/v1/api/array/reduce
+ * 
+ * @namespace A
+ * 
+ */
 export declare function reduce<GenericInput extends readonly unknown[], GenericReduceFrom extends ArrayEligibleReduceFromValue, GenericExit extends ArrayReduceExit = ArrayReduceExit<never>>(startValue: GenericReduceFrom, theFunction: (params: ArrayReduceFunctionParams<GenericInput, ArrayReduceFromValue<GenericReduceFrom>>) => ArrayReduceNext<ArrayReduceFromValue<GenericReduceFrom>> | GenericExit): (input: GenericInput) => ArrayReduceFromValue<GenericReduceFrom> | (IsEqual<GenericExit, ArrayReduceExit> extends true ? never : GenericExit["-exit"]);
 export declare function reduce<GenericInput extends readonly unknown[], GenericReduceFrom extends number | string | bigint | boolean | ArrayReduceFromResult, GenericExit extends ArrayReduceExit = ArrayReduceExit<never>>(input: GenericInput, startValue: GenericReduceFrom, theFunction: (params: ArrayReduceFunctionParams<GenericInput, ArrayReduceFromValue<GenericReduceFrom>>) => ArrayReduceNext<ArrayReduceFromValue<GenericReduceFrom>> | GenericExit): ArrayReduceFromValue<GenericReduceFrom> | (IsEqual<GenericExit, ArrayReduceExit> extends true ? never : GenericExit["-exit"]);
 export {};

package/dist/array/reduce.mjs

@@ -5,6 +5,9 @@ import { push } from './push.mjs';
 import { override } from '../object/override.mjs';
 
 const arrayReduceFromKind = createKind("array-reduce-from");
+/**
+ * {@include array/reduceFrom/index.md}
+ */
 function reduceFrom(value) {
     return arrayReduceFromKind.setTo(wrapValue(value));
 }

package/dist/array/reduceRight.d.ts

@@ -1,4 +1,43 @@
 import { type ArrayReduceFunctionParams, type ArrayReduceFromResult, type ArrayReduceFromValue, type ArrayReduceExit, type ArrayReduceNext } from "./reduce";
 import { type IsEqual } from "../common";
+/**
+ * Reduces an array from right to left.
+ * 
+ * **Supported call styles:**
+ * - Classic: `reduceRight(array, startValue, theFunction)` → returns the reduced value
+ * - Curried: `reduceRight(startValue, theFunction)` → returns a function waiting for the array
+ * 
+ * The function receives `{ element, index, lastValue, next, exit, nextWithObject, nextPush, self }`.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.reduceRight(
+ * 	[1, 2, 3],
+ * 	"",
+ * 	({ element, lastValue, next }) => next(`${lastValue}${element}`),
+ * ); // "321"
+ * 
+ * pipe(
+ * 	["a", "b", "c"],
+ * 	A.reduceRight("", ({ element, lastValue, next }) => next(`${lastValue}${element}`)),
+ * ); // "cba"
+ * 
+ * A.reduceRight(
+ * 	[1, 2, 3],
+ * 	0,
+ * 	({ element, lastValue, next }) => next(lastValue + element),
+ * ); // 6
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as `reduce`, but iterates from the end
+ * 
+ * @see [`A.reduce`](https://utils.duplojs.dev/en/v1/api/array/reduce) For left-to-right reduction
+ * @see https://utils.duplojs.dev/en/v1/api/array/reduceRight
+ * 
+ * @namespace A
+ * 
+ */
 export declare function reduceRight<GenericInput extends readonly unknown[], GenericReduceFrom extends number | string | bigint | boolean | ArrayReduceFromResult, GenericExit extends ArrayReduceExit = ArrayReduceExit<never>>(startValue: GenericReduceFrom, theFunction: (params: ArrayReduceFunctionParams<GenericInput, ArrayReduceFromValue<GenericReduceFrom>>) => ArrayReduceNext<ArrayReduceFromValue<GenericReduceFrom>> | GenericExit): (input: GenericInput) => ArrayReduceFromValue<GenericReduceFrom> | (IsEqual<GenericExit, ArrayReduceExit> extends true ? never : GenericExit["-exit"]);
 export declare function reduceRight<GenericInput extends readonly unknown[], GenericReduceFrom extends number | string | bigint | boolean | ArrayReduceFromResult, GenericExit extends ArrayReduceExit = ArrayReduceExit<never>>(input: GenericInput, startValue: GenericReduceFrom, theFunction: (params: ArrayReduceFunctionParams<GenericInput, ArrayReduceFromValue<GenericReduceFrom>>) => ArrayReduceNext<ArrayReduceFromValue<GenericReduceFrom>> | GenericExit): ArrayReduceFromValue<GenericReduceFrom> | (IsEqual<GenericExit, ArrayReduceExit> extends true ? never : GenericExit["-exit"]);

package/dist/array/reverse.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include array/reverse/index.md}
+ */
 function reverse(array) {
     return [...array].reverse();
 }

package/dist/array/reverse.d.ts

@@ -1,3 +1,34 @@
 import { type AnyTuple } from "../common/types/anyTuple";
 import { type ReverseTuple } from "../array";
+/**
+ * Reverses the order of an array.
+ * 
+ * Signature: `reverse(array)` → returns a new array
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.reverse(
+ * 	[1, 2, 3],
+ * ); // [3, 2, 1]
+ * 
+ * A.reverse(
+ * 	<const>["alpha", "beta"],
+ * ); // ["beta", "alpha"]
+ * 
+ * A.reverse(
+ * 	[],
+ * ); // []
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Type-safe with tuple types: return type is inferred as the reversed tuple
+ * - Uses the same semantics as [`Array.prototype.reverse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/array/reverse
+ * 
+ * @namespace A
+ * 
+ */
 export declare function reverse<GenericArray extends readonly unknown[]>(array: GenericArray): GenericArray extends AnyTuple ? ReverseTuple<GenericArray> : GenericArray;

package/dist/array/reverse.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include array/reverse/index.md}
+ */
 function reverse(array) {
     return [...array].reverse();
 }