@duplojs/utils 1.4.32 → 1.4.34

package/dist/array/at/default.d.ts

@@ -1,4 +1,36 @@
 import type { AtTuple } from "../types";
+/**
+ * Accesses an element at a given index, supporting negative indices.
+ * 
+ * **Supported call styles:**
+ * - Classic: `at(array, index)` → returns the element
+ * - Curried: `at(index)` → returns a function waiting for the array
+ * 
+ * **Negative indices:** `-1` is the last element, `-2` is second-to-last, etc.
+ * Returns `undefined` if out of bounds.
+ * 
+ * ```ts
+ * pipe(
+ * 	[10, 20, 30, 40],
+ * 	A.at(2),
+ * ); // 30
+ * 
+ * A.at(<const>[10, 20, 30, 40], 2); // 30
+ * A.at(<const>[10, 20, 30, 40], -1); // 40
+ * A.at(<const>[10, 20, 30], 10); // undefined
+ * ```
+ * 
+ * @remarks
+ * - Type-safe with tuple types: return type is inferred based on the index
+ * - Does not mutate the input array
+ * - Works seamlessly in functional composition and pipes
+ * 
+ * @see [`A.first`](https://utils.duplojs.dev/en/v1/api/array/first) For accessing the first element
+ * @see [`A.last`](https://utils.duplojs.dev/en/v1/api/array/last) For accessing the last element
+ * @see https://utils.duplojs.dev/en/v1/api/array/at
+ * 
+ * @namespace A
+ */
 export declare function at<GenericTuple extends readonly unknown[], GenericIndex extends number>(index: GenericIndex): (array: GenericTuple) => AtTuple<GenericTuple, GenericIndex>;
 export declare function at<GenericElement extends unknown>(index: number): (array: readonly GenericElement[]) => GenericElement | undefined;
 export declare function at<GenericTuple extends readonly unknown[], GenericIndex extends number>(array: GenericTuple, index: GenericIndex): AtTuple<GenericTuple, GenericIndex>;

package/dist/array/at/first.cjs

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

package/dist/array/at/first.d.ts

@@ -1,2 +1,27 @@
 import { type AnyTuple } from "../../common";
+/**
+ * Gets the first element of an array.
+ * 
+ * **Supported call styles:**
+ * - Classic: `first(array)` → returns the first element
+ * 
+ * Returns `undefined` when the array is empty.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.first([1, 2, 3]); // 1
+ * 
+ * A.first(<const>["alpha", "beta"]); // predicate "alpha"
+ * 
+ * A.first([]); // undefined
+ * ```
+ * 
+ * @remarks
+ * - Type-safe with tuple types: return type is inferred as the first element
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/array/first
+ * 
+ * @namespace A
+ * 
+ */
 export declare function first<GenericArray extends readonly unknown[]>(array: GenericArray): GenericArray extends AnyTuple ? GenericArray[0] : GenericArray[number] | undefined;

package/dist/array/at/first.mjs

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

package/dist/array/at/last.cjs

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

package/dist/array/at/last.d.ts

@@ -1 +1,26 @@
+/**
+ * Gets the last element of an array.
+ * 
+ * Signature: `last(array)` → returns the last element
+ * 
+ * Returns `undefined` when the array is empty.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.last([1, 2, 3]); // 3
+ * 
+ * A.last(<const>["alpha", "beta"]); // "beta"
+ * 
+ * A.last([]); // undefined
+ * ```
+ * 
+ * @remarks
+ * - Type-safe with tuple types: return type is inferred as the last element
+ * 
+ * @see [`A.first`](https://utils.duplojs.dev/en/v1/api/array/first) For accessing the first element
+ * @see https://utils.duplojs.dev/en/v1/api/array/last
+ * 
+ * @namespace A
+ * 
+ */
 export declare function last<GenericArray extends readonly unknown[]>(array: GenericArray): GenericArray extends readonly [...any[], infer InferredValue] ? InferredValue : GenericArray[number] | undefined;

package/dist/array/at/last.mjs

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

package/dist/array/chunk.d.ts

@@ -1,2 +1,29 @@
+/**
+ * Splits an array into chunks of a given size.
+ * 
+ * **Supported call styles:**
+ * - Classic: `chunk(array, size)` → returns a new array of chunks
+ * - Curried: `chunk(size)` → returns a function waiting for the array
+ * 
+ * Each chunk contains up to `size` items, and the last chunk may be smaller.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.chunk([1, 2, 3, 4, 5], 2);
+ * // [[1, 2], [3, 4], [5]]
+ * 
+ * pipe(
+ * 	["alpha", "beta", "gamma", "delta", "epsilon"],
+ * 	A.chunk(3),
+ * ); // [["alpha", "beta", "gamma"], ["delta", "epsilon"]]
+ * ```
+ * 
+ * @remarks
+ * - `size` should be a positive integer to avoid unexpected behavior
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/array/chunk
+ * 
+ * @namespace A
+ */
 export declare function chunk<GenericInput extends readonly unknown[]>(size: number): (input: GenericInput) => GenericInput[];
 export declare function chunk<GenericInput extends readonly unknown[]>(input: GenericInput, size: number): GenericInput[];

package/dist/array/coalescing.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include array/coalescing/index.md}
+ */
 function coalescing(value) {
     return value instanceof Array
         ? value

package/dist/array/coalescing.d.ts

@@ -1,3 +1,25 @@
 import { type AnyValue } from "../common";
 import { type ArrayCoalescing } from "./types";
+/**
+ * Ensures a value is returned as an array.
+ * 
+ * Signature: `coalescing(value)` → returns an array
+ * 
+ * If the value is already an array, it is returned as-is.
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * A.coalescing(1); // [1]
+ * 
+ * A.coalescing(["alpha", "beta"]); // ["alpha", "beta"]
+ * 
+ * A.coalescing(null); // [null]
+ * ```
+ * 
+ * @see [`A.toTuple`](https://utils.duplojs.dev/en/v1/api/array/toTuple) For shaping outputs
+ * @see https://utils.duplojs.dev/en/v1/api/array/coalescing
+ * 
+ * @namespace A
+ * 
+ */
 export declare function coalescing<GenericValue extends AnyValue>(value: GenericValue): ArrayCoalescing<GenericValue>;

package/dist/array/coalescing.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include array/coalescing/index.md}
+ */
 function coalescing(value) {
     return value instanceof Array
         ? value

package/dist/array/concat.d.ts

@@ -1,2 +1,30 @@
+/**
+ * Concatenates arrays into a new array.
+ * 
+ * **Supported call styles:**
+ * - Classic: `concat(array, elements, ...elementsRest)` → returns a new array
+ * - Curried: `concat(elements)` → returns a function waiting for the array
+ * 
+ * All arrays are concatenated in order.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.concat(["alpha"], ["beta"], ["gamma"]); // ["alpha", "beta", "gamma"]
+ * 
+ * pipe(
+ * 	["x"],
+ * 	A.concat(["y", "z"]),
+ * ); // ["x", "y", "z"]
+ * ```
+ * 
+ * @remarks
+ * - Classic style supports concatenating multiple arrays via rest parameters
+ * - Curried style concatenates only two arrays (`elements` into `array`)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/array/concat
+ * 
+ * @namespace A
+ * 
+ */
 export declare function concat<GenericFirstArray extends readonly unknown[], GenericSecondArray extends readonly unknown[]>(elements: GenericSecondArray): (array: GenericFirstArray) => (GenericFirstArray[number] | GenericSecondArray[number])[];
 export declare function concat<GenericFirstArray extends readonly unknown[], GenericSecondArray extends readonly unknown[], GenericRest extends readonly unknown[][]>(array: GenericFirstArray, elements: GenericSecondArray, ...elementsRest: GenericRest): (GenericFirstArray[number] | GenericSecondArray[number] | GenericRest[number][number])[];

package/dist/array/copyWithin.d.ts

@@ -1,2 +1,33 @@
+/**
+ * Copies a sequence within an array to another position.
+ * 
+ * **Supported call styles:**
+ * - Classic: `copyWithin(array, target, start, end?)` → returns a new array
+ * - Curried: `copyWithin(target, start, end?)` → returns a function waiting for the array
+ * 
+ * The copy uses the range `[start, end)` and writes from `target`.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.copyWithin([1, 2, 3, 4], 0, 2); // [3, 4, 3, 4]
+ * 
+ * A.copyWithin([1, 2, 3, 4], 1, 0, 2); // [1, 1, 2, 4]
+ * 
+ * pipe(
+ * 	["alpha", "beta", "gamma"],
+ * 	A.copyWithin(1, 0, 2),
+ * ); // ["alpha", "alpha", "beta"]
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Array.prototype.copyWithin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin)
+ * 
+ * @see [`A.slice`](https://utils.duplojs.dev/en/v1/api/array/slice) For extracting ranges
+ * @see [`A.spliceReplace`](https://utils.duplojs.dev/en/v1/api/array/spliceReplace) For replacing a segment
+ * @see https://utils.duplojs.dev/en/v1/api/array/copyWithin
+ * 
+ * @namespace A
+ * 
+ */
 export declare function copyWithin<GenericElement extends unknown>(target: number, start: number, end?: number): (array: readonly GenericElement[]) => GenericElement[];
 export declare function copyWithin<GenericElement extends unknown>(array: readonly GenericElement[], target: number, start: number, end?: number): GenericElement[];

package/dist/array/every.d.ts

@@ -2,6 +2,43 @@ interface ArrayEveryParams<GenericInputArray extends readonly unknown[]> {
     index: number;
     self: GenericInputArray;
 }
+/**
+ * Checks whether all elements satisfy a predicate.
+ * 
+ * **Supported call styles:**
+ * - Classic: `every(array, predicate)` → returns a boolean
+ * - Curried: `every(predicate)` → returns a function waiting for the array
+ * 
+ * The predicate receives `(element, { index, self })`, where `index` is the element position
+ * and `self` is the original array.
+ * 
+ * ```ts
+ * A.every(
+ * 	[1, 2, 3],
+ * 	(value, { index }) => value > 0 && (index + 1) === value,
+ * ); // true
+ * 
+ * pipe(
+ * 	["alpha", "beta"],
+ * 	when(
+ * 		A.every((value) => value.length > 3),
+ * 		(items) => {
+ * 			// items all match the predicate
+ * 		},
+ * 	),
+ * );
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Array.prototype.every`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every)
+ * 
+ * @see [`A.some`](https://utils.duplojs.dev/en/v1/api/array/some) For checking if any element matches
+ * @see [`A.filter`](https://utils.duplojs.dev/en/v1/api/array/filter) For selecting matching elements
+ * @see https://utils.duplojs.dev/en/v1/api/array/every
+ * 
+ * @namespace A
+ * 
+ */
 export declare function every<GenericInput extends readonly unknown[]>(predicate: (element: GenericInput[number], params: ArrayEveryParams<GenericInput>) => boolean): (input: GenericInput) => boolean;
 export declare function every<GenericInput extends readonly unknown[]>(input: GenericInput, predicate: (element: GenericInput[number], params: ArrayEveryParams<GenericInput>) => boolean): boolean;
 export {};

package/dist/array/fill/all.d.ts

@@ -1,2 +1,38 @@
+/**
+ * Fills all elements of an array with a given value.
+ * 
+ * **Supported call styles:**
+ * - Classic: `fillAll(array, value)` → returns a new array
+ * - Curried: `fillAll(value)` → returns a function waiting for the array
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.fillAll(
+ * 	[1, 2, 3],
+ * 	0,
+ * ); // [0, 0, 0]
+ * 
+ * pipe(
+ * 	["alpha", "beta"],
+ * 	A.fillAll("gamma"),
+ * ); // ["gamma", "gamma"]
+ * 
+ * A.fillAll(
+ * 	[],
+ * 	true,
+ * ); // []
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Array.prototype.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill)
+ * 
+ * @see [`A.fill`](https://utils.duplojs.dev/en/v1/api/array/fill) For filling a range
+ * @see https://utils.duplojs.dev/en/v1/api/array/fillAll
+ * 
+ * @namespace A
+ * 
+ */
 export declare function fillAll<GenericElement extends unknown>(element: GenericElement): (input: readonly unknown[]) => GenericElement[];
 export declare function fillAll<GenericElement extends unknown>(input: readonly unknown[], element: GenericElement): GenericElement[];

package/dist/array/fill/default.d.ts

@@ -1,2 +1,38 @@
+/**
+ * Fills part of an array with a given value.
+ * 
+ * **Supported call styles:**
+ * - Classic: `fill(array, value, start, end)` → returns a new array
+ * - Curried: `fill(value, start, end)` → returns a function waiting for the array
+ * 
+ * The fill operation applies from `start` (inclusive) to `end` (exclusive).
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.fill(
+ * 	[10, 20, 30, 40],
+ * 	0,
+ * 	1,
+ * 	3,
+ * ); // [10, 0, 0, 40]
+ * 
+ * pipe(
+ * 	[
+ * 		"alpha",
+ * 		"beta",
+ * 		"gamma",
+ * 	],
+ * 	A.fill("delta", 0, 2),
+ * ); // ["delta", "delta", "gamma"]
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Array.prototype.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) for `start` and `end`
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/array/fill
+ * 
+ * @namespace A
+ * 
+ */
 export declare function fill<GenericElement extends unknown>(value: GenericElement, start: number, end: number): (array: readonly GenericElement[]) => GenericElement[];
 export declare function fill<GenericElement extends unknown>(array: readonly GenericElement[], value: GenericElement, start: number, end: number): GenericElement[];

package/dist/array/filter.d.ts

@@ -2,6 +2,39 @@ interface ArrayFilterParams<GenericInputArray extends readonly unknown[]> {
     index: number;
     self: GenericInputArray;
 }
+/**
+ * Filters an array by a predicate, with classic and curried styles.
+ * 
+ * **Supported call styles:**
+ * - Classic: `filter(array, predicate)` → returns a new array
+ * - Curried: `filter(predicate)` → returns a function waiting for the array
+ * - Classic predicate: `filter(array, isType)` → narrows item types
+ * - Curried predicate: `filter(isType)` → narrows item types
+ * 
+ * The predicate receives `(item, { index, self })`.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.filter(
+ * 	[1, 2, 3, 4],
+ * 	(value) => value > 2,
+ * ); // [3, 4]
+ * 
+ * pipe(
+ * 	<const>[1, "alpha", null],
+ * 	A.filter(isType("string")),
+ * ); // "alpha"[]
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Predicate overloads (type guards) narrow the output element type
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/array/filter
+ * 
+ * @namespace A
+ * 
+ */
 export declare function filter<GenericInput extends readonly unknown[], GenericOutput extends GenericInput[number]>(predicate: (item: GenericInput[number], params: ArrayFilterParams<GenericInput>) => item is GenericOutput): (input: GenericInput) => GenericOutput[];
 export declare function filter<GenericInput extends readonly unknown[], GenericOutput extends GenericInput[number]>(input: GenericInput, predicate: (item: GenericInput[number], params: ArrayFilterParams<GenericInput>) => item is GenericOutput): GenericOutput[];
 export declare function filter<GenericInput extends readonly unknown[]>(predicate: (item: GenericInput[number], params: ArrayFilterParams<GenericInput>) => boolean): (input: GenericInput) => GenericInput[number][];

package/dist/array/find.d.ts

@@ -1,6 +1,40 @@
 interface ArrayFindParams {
     index: number;
 }
+/**
+ * Finds the first element matching a predicate.
+ * 
+ * **Supported call styles:**
+ * - Classic: `find(array, predicate)` → returns the element or `undefined`
+ * - Curried: `find(predicate)` → returns a function waiting for the array
+ * - Classic predicate: `find(array, isType)` → narrows the return type
+ * - Curried predicate: `find(isType)` → narrows the return type
+ * 
+ * The predicate receives `(element, { index })`.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.find(
+ * 	[1, 2, 3],
+ * 	(value) => value > 2,
+ * ); // 3
+ * 
+ * pipe(
+ * 	<const>[1, "alpha", null],
+ * 	A.find(isType("string")),
+ * ); // "alpha"
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Predicate overloads (type guards) narrow the output type but can still return `undefined`
+ * - Uses the same semantics as [`Array.prototype.find`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/array/find
+ * 
+ * @namespace A
+ * 
+ */
 export declare function find<GenericArray extends readonly unknown[], GenericOutput extends GenericArray[number]>(predicate: (element: GenericArray[number], params: ArrayFindParams) => element is GenericOutput): (array: GenericArray) => GenericOutput | undefined;
 export declare function find<GenericElement extends unknown, GenericOutput extends GenericElement>(array: readonly GenericElement[], predicate: (element: GenericElement, params: ArrayFindParams) => element is GenericOutput): GenericOutput | undefined;
 export declare function find<GenericArray extends readonly unknown[]>(predicate: (element: GenericArray[number], params: ArrayFindParams) => boolean): (array: GenericArray) => GenericArray[number] | undefined;

package/dist/array/findAndReplace.d.ts

@@ -2,6 +2,46 @@ import { type AnyValue } from "../common";
 interface ArrayFindAndSetIndexParams {
     index: number;
 }
+/**
+ * Finds the first element matching a predicate and replaces it.
+ * 
+ * **Supported call styles:**
+ * - Classic: `findAndReplace(array, predicate, value)` → returns a new array or `undefined`
+ * - Curried: `findAndReplace(predicate, value)` → returns a function waiting for the array
+ * 
+ * The predicate receives `(element, { index })`.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.findAndReplace(
+ * 	[1, 2, 3],
+ * 	(value) => value === 2,
+ * 	9,
+ * ); // [1, 9, 3]
+ * 
+ * pipe(
+ * 	["alpha", "beta"],
+ * 	A.findAndReplace((value) => value === "beta", "gamma"),
+ * ); // ["alpha", "gamma"]
+ * 
+ * A.findAndReplace(
+ * 	[1, 2],
+ * 	(value) => value === 5,
+ * 	0,
+ * ); // undefined
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Returns `undefined` when no element matches
+ * 
+ * @see [`A.find`](https://utils.duplojs.dev/en/v1/api/array/find) For finding an element
+ * @see [`A.findAndSpliceReplace`](https://utils.duplojs.dev/en/v1/api/array/findAndSpliceReplace) For replacing via splice
+ * @see https://utils.duplojs.dev/en/v1/api/array/findAndReplace
+ * 
+ * @namespace A
+ * 
+ */
 export declare function findAndReplace<GenericArray extends readonly unknown[], GenericValue extends AnyValue>(predicate: (element: GenericArray[number], params: ArrayFindAndSetIndexParams) => boolean, value: GenericValue): (input: GenericArray) => (GenericArray[number] | GenericValue)[] | undefined;
 export declare function findAndReplace<GenericArray extends readonly unknown[], GenericValue extends AnyValue>(input: GenericArray, predicate: (element: GenericArray[number], params: ArrayFindAndSetIndexParams) => boolean, value: GenericValue): (GenericArray[number] | GenericValue)[] | undefined;
 export {};

package/dist/array/findAndSplice/delete.d.ts

@@ -1,6 +1,46 @@
 interface ArrayFindAndSpliceDeleteIndexParams {
     index: number;
 }
+/**
+ * Finds the first element matching a predicate and deletes a segment.
+ * 
+ * **Supported call styles:**
+ * - Classic: `findAndSpliceDelete(array, predicate, deleteCount)` → returns a new array or `undefined`
+ * - Curried: `findAndSpliceDelete(predicate, deleteCount)` → returns a function waiting for the array
+ * 
+ * The predicate receives `(element, { index })`.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.findAndSpliceDelete(
+ * 	[1, 2, 3, 4],
+ * 	(value) => value === 2,
+ * 	2,
+ * ); // [1, 4]
+ * 
+ * pipe(
+ * 	["alpha", "beta", "gamma"],
+ * 	A.findAndSpliceDelete((value) => value === "beta", 1),
+ * ); // ["alpha", "gamma"]
+ * 
+ * A.findAndSpliceDelete(
+ * 	[1, 2],
+ * 	(value) => value === 5,
+ * 	1,
+ * ); // undefined
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Returns `undefined` when no element matches
+ * 
+ * @see [`A.findAndSpliceInsert`](https://utils.duplojs.dev/en/v1/api/array/findAndSpliceInsert) For inserting elements
+ * @see [`A.findAndSpliceReplace`](https://utils.duplojs.dev/en/v1/api/array/findAndSpliceReplace) For replacing elements
+ * @see https://utils.duplojs.dev/en/v1/api/array/findAndSpliceDelete
+ * 
+ * @namespace A
+ * 
+ */
 export declare function findAndSpliceDelete<GenericElement extends unknown>(predicate: (element: GenericElement, params: ArrayFindAndSpliceDeleteIndexParams) => boolean, deleteCount: number): (array: readonly GenericElement[]) => GenericElement[] | undefined;
 export declare function findAndSpliceDelete<GenericElement extends unknown>(array: readonly GenericElement[], predicate: (element: GenericElement, params: ArrayFindAndSpliceDeleteIndexParams) => boolean, deleteCount: number): GenericElement[] | undefined;
 export {};

package/dist/array/findAndSplice/insert.d.ts

@@ -1,6 +1,46 @@
 interface ArrayFindAndSpliceInsertIndexParams {
     index: number;
 }
+/**
+ * Finds the first element matching a predicate and inserts elements.
+ * 
+ * **Supported call styles:**
+ * - Classic: `findAndSpliceInsert(array, predicate, elements)` → returns a new array or `undefined`
+ * - Curried: `findAndSpliceInsert(predicate, elements)` → returns a function waiting for the array
+ * 
+ * The predicate receives `(element, { index })`.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.findAndSpliceInsert(
+ * 	[1, 2, 3],
+ * 	(value) => value === 2,
+ * 	[9],
+ * ); // [1, 9, 2, 3]
+ * 
+ * pipe(
+ * 	["alpha", "beta"],
+ * 	A.findAndSpliceInsert((value) => value === "alpha", ["start"]),
+ * ); // ["start", "alpha", "beta"]
+ * 
+ * A.findAndSpliceInsert(
+ * 	[1, 2],
+ * 	(value) => value === 5,
+ * 	[0],
+ * ); // undefined
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Returns `undefined` when no element matches
+ * 
+ * @see [`A.findAndSpliceDelete`](https://utils.duplojs.dev/en/v1/api/array/findAndSpliceDelete) For deleting elements
+ * @see [`A.findAndSpliceReplace`](https://utils.duplojs.dev/en/v1/api/array/findAndSpliceReplace) For replacing elements
+ * @see https://utils.duplojs.dev/en/v1/api/array/findAndSpliceInsert
+ * 
+ * @namespace A
+ * 
+ */
 export declare function findAndSpliceInsert<GenericElement extends unknown>(predicate: (element: GenericElement, params: ArrayFindAndSpliceInsertIndexParams) => boolean, elements: GenericElement[]): (array: readonly GenericElement[]) => GenericElement[] | undefined;
 export declare function findAndSpliceInsert<GenericElement extends unknown>(array: readonly GenericElement[], predicate: (element: GenericElement, params: ArrayFindAndSpliceInsertIndexParams) => boolean, elements: GenericElement[]): GenericElement[] | undefined;
 export {};

package/dist/array/findAndSplice/replace.d.ts

@@ -1,6 +1,46 @@
 interface ArrayFindAndSpliceReplaceIndexParams {
     index: number;
 }
+/**
+ * Finds the first element matching a predicate and replaces a segment.
+ * 
+ * **Supported call styles:**
+ * - Classic: `findAndSpliceReplace(array, predicate, elements)` → returns a new array or `undefined`
+ * - Curried: `findAndSpliceReplace(predicate, elements)` → returns a function waiting for the array
+ * 
+ * The predicate receives `(element, { index })`.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.findAndSpliceReplace(
+ * 	[1, 2, 3, 4],
+ * 	(value) => value === 2,
+ * 	[9, 8],
+ * ); // [1, 9, 8, 4]
+ * 
+ * pipe(
+ * 	["alpha", "beta", "gamma"],
+ * 	A.findAndSpliceReplace((value) => value === "beta", ["delta"]),
+ * ); // ["alpha", "delta", "gamma"]
+ * 
+ * A.findAndSpliceReplace(
+ * 	[1, 2],
+ * 	(value) => value === 5,
+ * 	[0],
+ * ); // undefined
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Returns `undefined` when no element matches
+ * 
+ * @see [`A.findAndSpliceDelete`](https://utils.duplojs.dev/en/v1/api/array/findAndSpliceDelete) For deleting elements
+ * @see [`A.findAndSpliceInsert`](https://utils.duplojs.dev/en/v1/api/array/findAndSpliceInsert) For inserting elements
+ * @see https://utils.duplojs.dev/en/v1/api/array/findAndSpliceReplace
+ * 
+ * @namespace A
+ * 
+ */
 export declare function findAndSpliceReplace<GenericElement extends unknown>(predicate: (element: GenericElement, params: ArrayFindAndSpliceReplaceIndexParams) => boolean, elements: GenericElement[]): (array: readonly GenericElement[]) => GenericElement[] | undefined;
 export declare function findAndSpliceReplace<GenericElement extends unknown>(array: readonly GenericElement[], predicate: (element: GenericElement, params: ArrayFindAndSpliceReplaceIndexParams) => boolean, elements: GenericElement[]): GenericElement[] | undefined;
 export {};