@duplojs/utils 1.4.32 → 1.4.34

package/dist/array/findIndex.d.ts

@@ -1,6 +1,43 @@
 interface ArrayFindIndexParams {
     index: number;
 }
+/**
+ * Finds the index of the first element matching a predicate.
+ * 
+ * **Supported call styles:**
+ * - Classic: `findIndex(array, predicate)` → returns the index or `undefined`
+ * - Curried: `findIndex(predicate)` → returns a function waiting for the array
+ * 
+ * The predicate receives `(element, { index })`.
+ * 
+ * ```ts
+ * A.findIndex(
+ * 	[1, 2, 3],
+ * 	(value) => value > 1,
+ * ); // 1
+ * 
+ * pipe(
+ * 	["alpha", "beta"],
+ * 	A.findIndex((value) => value === "beta"),
+ * ); // 1
+ * 
+ * A.findIndex(
+ * 	[1, 2],
+ * 	(value) => value === 5,
+ * ); // undefined
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Returns `undefined` when no element matches (unlike `Array.prototype.findIndex` which returns `-1`)
+ * - Uses the same semantics as [`Array.prototype.findIndex`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex)
+ * 
+ * @see [`A.find`](https://utils.duplojs.dev/en/v1/api/array/find) For retrieving the element
+ * @see https://utils.duplojs.dev/en/v1/api/array/findIndex
+ * 
+ * @namespace A
+ * 
+ */
 export declare function findIndex<GenericArray extends readonly unknown[]>(predicate: (element: GenericArray[number], params: ArrayFindIndexParams) => boolean): (array: GenericArray) => number | undefined;
 export declare function findIndex<GenericElement extends unknown>(array: readonly GenericElement[], predicate: (element: GenericElement, params: ArrayFindIndexParams) => boolean): number | undefined;
 export {};

package/dist/array/findLast.d.ts

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

package/dist/array/findLastIndex.d.ts

@@ -1,6 +1,43 @@
 interface ArrayFindLastIndexParams {
     index: number;
 }
+/**
+ * Finds the index of the last element matching a predicate.
+ * 
+ * **Supported call styles:**
+ * - Classic: `findLastIndex(array, predicate)` → returns the index or `undefined`
+ * - Curried: `findLastIndex(predicate)` → returns a function waiting for the array
+ * 
+ * The predicate receives `(element, { index })`.
+ * 
+ * ```ts
+ * A.findLastIndex(
+ * 	[1, 2, 3, 2],
+ * 	(value) => value === 2,
+ * ); // 3
+ * 
+ * pipe(
+ * 	["alpha", "beta", "beta"],
+ * 	A.findLastIndex((value) => value === "beta"),
+ * ); // 2
+ * 
+ * A.findLastIndex(
+ * 	[1, 2],
+ * 	(value) => value === 5,
+ * ); // undefined
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Returns `undefined` when no element matches (unlike `Array.prototype.findLastIndex` which returns `-1`)
+ * - Uses the same semantics as [`Array.prototype.findLastIndex`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findLastIndex)
+ * 
+ * @see [`A.findLast`](https://utils.duplojs.dev/en/v1/api/array/findLast) For retrieving the element
+ * @see https://utils.duplojs.dev/en/v1/api/array/findLastIndex
+ * 
+ * @namespace A
+ * 
+ */
 export declare function findLastIndex<GenericArray extends readonly unknown[]>(predicate: (element: GenericArray[number], params: ArrayFindLastIndexParams) => boolean): (array: GenericArray) => number | undefined;
 export declare function findLastIndex<GenericElement extends unknown>(array: readonly GenericElement[], predicate: (element: GenericElement, params: ArrayFindLastIndexParams) => boolean): number | undefined;
 export {};

package/dist/array/flat.d.ts

@@ -1 +1,33 @@
+/**
+ * Flattens nested arrays up to a given depth.
+ * 
+ * Signature: `flat(array, depth?)` → returns a new array
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.flat(
+ * 	[[1], [2]],
+ * ); // [1, 2]
+ * 
+ * A.flat(
+ * 	[1, [2, [3]]],
+ * 	2,
+ * ); // [1, 2, 3]
+ * 
+ * A.flat(
+ * 	[],
+ * ); // []
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Array.prototype.flat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat)
+ * 
+ * @see [`A.flatMap`](https://utils.duplojs.dev/en/v1/api/array/flatMap) For map + flatten
+ * @see https://utils.duplojs.dev/en/v1/api/array/flat
+ * 
+ * @namespace A
+ * 
+ */
 export declare function flat<const GenericArray extends readonly unknown[], const Depth extends number = 1>(array: GenericArray, depth?: Depth): FlatArray<GenericArray, Depth>[];

package/dist/array/flatMap.d.ts

@@ -2,6 +2,43 @@ interface ArrayFlatMapParams<GenericInputArray extends readonly unknown[]> {
     index: number;
     self: GenericInputArray;
 }
+/**
+ * Maps each element and flattens the result by one level.
+ * 
+ * **Supported call styles:**
+ * - Classic: `flatMap(array, theFunction)` → returns a new array
+ * - Curried: `flatMap(theFunction)` → returns a function waiting for the array
+ * 
+ * The mapping function receives `(element, { index, self })`.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.flatMap(
+ * 	[1, 2],
+ * 	(value) => [value, value],
+ * ); // [1, 1, 2, 2]
+ * 
+ * pipe(
+ * 	["alpha", "beta"],
+ * 	A.flatMap((value) => [value.length]),
+ * ); // [5, 4]
+ * 
+ * A.flatMap(
+ * 	[1, 2, 3],
+ * 	(value, { index }) => [index, value],
+ * ); // [0, 1, 1, 2, 2, 3]
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Array.prototype.flatMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap)
+ * 
+ * @see [`A.map`](https://utils.duplojs.dev/en/v1/api/array/map) For mapping without flattening
+ * @see https://utils.duplojs.dev/en/v1/api/array/flatMap
+ * 
+ * @namespace A
+ * 
+ */
 export declare function flatMap<GenericInput extends readonly unknown[], GenericOutput extends unknown>(theFunction: (element: GenericInput[number], params: ArrayFlatMapParams<GenericInput>) => GenericOutput): (input: GenericInput) => FlatArray<GenericOutput, 1>[];
 export declare function flatMap<GenericInput extends readonly unknown[], GenericOutput extends unknown>(input: GenericInput, theFunction: (element: GenericInput[number], params: ArrayFlatMapParams<GenericInput>) => GenericOutput): FlatArray<GenericOutput, 1>[];
 export {};

package/dist/array/from.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include array/from/index.md}
+ */
 function from(input) {
     if (typeof input === "object" && Symbol.asyncIterator in input) {
         return (async () => {

package/dist/array/from.d.ts

@@ -1 +1,34 @@
+/**
+ * Creates an array from an iterable or array-like value.
+ * 
+ * Signature: `from(input)` → returns an array or a promise
+ * 
+ * Async iterables return a `Promise` of an array.
+ * 
+ * ```ts
+ * A.from(
+ * 	"ab",
+ * ); // ["a", "b"]
+ * 
+ * A.from(
+ * 	new Set([1, 2]),
+ * ); // [1, 2]
+ * 
+ * A.from(
+ * 	{
+ * 		0: "alpha",
+ * 		1: "beta",
+ * 		length: 2,
+ * 	},
+ * ); // ["alpha", "beta"]
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) for sync inputs
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/array/from
+ * 
+ * @namespace A
+ * 
+ */
 export declare function from<const GenericArray extends (ArrayLike<unknown> | Iterable<unknown> | AsyncIterable<unknown>)>(input: GenericArray): GenericArray extends AsyncIterable<infer InferredValue> ? Promise<InferredValue[]> : GenericArray extends Iterable<infer InferredValue> ? InferredValue[] : GenericArray extends ArrayLike<infer InferredValue> ? InferredValue[] : never;

package/dist/array/from.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include array/from/index.md}
+ */
 function from(input) {
     if (typeof input === "object" && Symbol.asyncIterator in input) {
         return (async () => {

package/dist/array/group.d.ts

@@ -3,6 +3,37 @@ export interface ArrayGroupFunctionOutput<GenericGroupName extends string = stri
     group: GenericGroupName;
     value: GenericGroupValue;
 }
+/**
+ * Creates a group output object for `group`.
+ * 
+ * **Supported call styles:**
+ * - Classic: `groupOutput(group, value)` → returns a group output
+ * - Curried: `groupOutput(group)` → returns a function waiting for the value
+ * 
+ * ```ts
+ * A.groupOutput(
+ * 	"even",
+ * 	2,
+ * ); // { group: "even", value: 2 }
+ * 
+ * pipe(
+ * 	3,
+ * 	A.groupOutput("odd"),
+ * ); // { group: "odd", value: 3 }
+ * 
+ * A.groupOutput(
+ * 	"status",
+ * 	true,
+ * ); // { group: "status", value: true }
+ * 
+ * ```
+ * 
+ * @see [`A.group`](https://utils.duplojs.dev/en/v1/api/array/group) For grouping arrays
+ * @see https://utils.duplojs.dev/en/v1/api/array/groupOutput
+ * 
+ * @namespace A
+ * 
+ */
 export declare function groupOutput<GenericGroupValue extends unknown, GenericGroupName extends string>(group: GenericGroupName): (value: GenericGroupValue) => ArrayGroupFunctionOutput<GenericGroupName, GenericGroupValue>;
 export declare function groupOutput<GenericGroupValue extends unknown, GenericGroupName extends string>(group: GenericGroupName, value: GenericGroupValue): ArrayGroupFunctionOutput<GenericGroupName, GenericGroupValue>;
 export interface ArrayGroupFunctionParams {
@@ -12,5 +43,41 @@ export interface ArrayGroupFunctionParams {
 export type ArrayGroupResult<GenericOutput extends ArrayGroupFunctionOutput> = SimplifyTopLevel<{
     [Output in GenericOutput as Output["group"]]?: Output["value"][];
 }>;
+/**
+ * Groups elements into an object by a group name.
+ * 
+ * **Supported call styles:**
+ * - Classic: `group(array, theFunction)` → returns a grouped object
+ * - Curried: `group(theFunction)` → returns a function waiting for the array
+ * 
+ * The function receives `(element, { index, output })`, where `output` is `groupOutput`.
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.group(
+ * 	[1, 2, 3],
+ * 	(value, { output }) => output(value % 2 ? "odd" : "even", value),
+ * );
+ * // { even: [2], odd: [1, 3] }
+ * 
+ * pipe(
+ * 	["alpha", "beta"],
+ * 	A.group((value, { output }) => output("len", value.length)),
+ * ); // { len: [5, 4] }
+ * 
+ * A.group(
+ * 	[true, false],
+ * 	(_value, { output }) => output("flag", true),
+ * );
+ * // { flag: [true, true] }
+ * 
+ * ```
+ * 
+ * @see [`A.groupOutput`](https://utils.duplojs.dev/en/v1/api/array/groupOutput) For creating group outputs
+ * @see https://utils.duplojs.dev/en/v1/api/array/group
+ * 
+ * @namespace A
+ * 
+ */
 export declare function group<GenericArray extends readonly unknown[], GenericOutput extends ArrayGroupFunctionOutput>(theFunction: (element: GenericArray[number], params: ArrayGroupFunctionParams) => GenericOutput): (array: GenericArray) => ArrayGroupResult<GenericOutput>;
 export declare function group<GenericElement extends unknown, GenericOutput extends ArrayGroupFunctionOutput>(array: readonly GenericElement[], theFunction: (element: GenericElement, params: ArrayGroupFunctionParams) => GenericOutput): ArrayGroupResult<GenericOutput>;

package/dist/array/includes.d.ts

@@ -1,2 +1,42 @@
+/**
+ * Checks if an array includes a given value.
+ * 
+ * **Supported call styles:**
+ * - Classic: `includes(array, value)` → returns a boolean
+ * - Curried: `includes(value)` → returns a function waiting for the array
+ * 
+ * ```ts
+ * const numbersList = [1, 2, 3];
+ * 
+ * if (A.includes(numbersList, 4)) {
+ * 	// numbersList contains "4"
+ * } else {
+ * 	// numbersList not contains "4"
+ * }
+ * 
+ * pipe(
+ * 	["alpha", "beta"],
+ * 	when(
+ * 		A.includes("beta"),
+ * 		(value) => {
+ * 			// value contains "beta"
+ * 		},
+ * 	),
+ * );
+ * 
+ * ```
+ * 
+ * @remarks
+ * - relevant for taking action based on the result
+ * - Uses the same semantics as [`Array.prototype.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes)
+ * 
+ * @see [`A.notIncludes`](https://utils.duplojs.dev/en/v1/api/array/notIncludes) For the opposite check
+ * @see [`A.indexOf`](https://utils.duplojs.dev/en/v1/api/array/indexOf) For getting the index
+ * @see [`A.find`](https://utils.duplojs.dev/en/v1/api/array/find) For finding the element
+ * @see https://utils.duplojs.dev/en/v1/api/array/includes
+ * 
+ * @namespace A
+ * 
+ */
 export declare function includes<GenericArrayValue extends unknown>(value: NoInfer<GenericArrayValue>): (array: readonly GenericArrayValue[]) => boolean;
 export declare function includes<GenericArrayValue extends unknown>(array: readonly GenericArrayValue[], value: NoInfer<GenericArrayValue>): boolean;

package/dist/array/index.cjs

@@ -56,7 +56,9 @@ var _delete$1 = require('./findAndSplice/delete.cjs');
 var insert$1 = require('./findAndSplice/insert.cjs');
 var replace$1 = require('./findAndSplice/replace.cjs');
 
-
+/**
+ * {@include array/index.md}
+ */
 
 exports.filter = filter.filter;
 exports.find = find.find;

package/dist/array/index.d.ts

@@ -1,3 +1,30 @@
+/**
+ * Array utilities for immutable, type-safe array manipulation. All functions preserve the
+ * original array and return a new value.
+ * 
+ * **How to import:**
+ * - From the main entry (namespace style)
+ * - Via direct import for tree-shaking
+ * 
+ * ```ts
+ * import { DArray, A } from "@duplojs/utils";
+ * import * as DArray from "@duplojs/utils/array";
+ * import * as A from "@duplojs/utils/array";
+ * ```
+ * 
+ * What you will find in this namespace:
+ * - iteration and transforms (`A.map`, `A.filter`, `A.reduce`)
+ * - reduce helpers (`A.reduceFrom`)
+ * - element access helpers (`A.at`, `A.first`, `A.last`)
+ * - search and predicates (`A.find`, `A.findIndex`, `A.some`, `A.every`)
+ * - transforms (`A.map`, `A.flatMap`, `A.select`, `A.group`)
+ * - structure updates (`A.set`, `A.insert`, `A.push`, `A.unshift`)
+ * - slicing and composition (`A.slice`, `A.concat`, `A.chunk`, `A.copyWithin`)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/array
+ * 
+ * @namespace A
+ */
 export * from "./types";
 export * from "./filter";
 export * from "./find";

package/dist/array/index.mjs

@@ -53,3 +53,7 @@ export { fillAll } from './fill/all.mjs';
 export { findAndSpliceDelete } from './findAndSplice/delete.mjs';
 export { findAndSpliceInsert } from './findAndSplice/insert.mjs';
 export { findAndSpliceReplace } from './findAndSplice/replace.mjs';
+
+/**
+ * {@include array/index.md}
+ */

package/dist/array/indexOf.d.ts

@@ -1,2 +1,40 @@
+/**
+ * Finds the first index of a value.
+ * 
+ * **Supported call styles:**
+ * - Classic: `indexOf(array, value, fromIndex?)` → returns the index or `undefined`
+ * - Curried: `indexOf(value)` → returns a function waiting for the array
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.indexOf(
+ * 	[1, 2, 3],
+ * 	2,
+ * ); // 1
+ * 
+ * A.indexOf(
+ * 	[1, 2, 3],
+ * 	2,
+ * 	2,
+ * ); // undefined
+ * 
+ * pipe(
+ * 	["alpha", "beta"],
+ * 	A.indexOf("beta"),
+ * ); // 1
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Returns `undefined` when not found (unlike `Array.prototype.indexOf` which returns `-1`)
+ * - Curried style does not accept `fromIndex`
+ * 
+ * @see [`A.lastIndexOf`](https://utils.duplojs.dev/en/v1/api/array/lastIndexOf) For searching from the end
+ * @see https://utils.duplojs.dev/en/v1/api/array/indexOf
+ * 
+ * @namespace A
+ * 
+ */
 export declare function indexOf<GenericElement extends unknown>(element: GenericElement): (array: readonly GenericElement[]) => number | undefined;
 export declare function indexOf<GenericElement extends unknown>(array: readonly GenericElement[], element: GenericElement, fromIndex?: number): number | undefined;

package/dist/array/insert.d.ts

@@ -1,2 +1,36 @@
+/**
+ * Adds an element to the end of an array.
+ * 
+ * **Supported call styles:**
+ * - Classic: `insert(input, array)` → returns a new array
+ * - Curried: `insert(array)` → returns a function waiting for the input
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.insert(
+ * 	4,
+ * 	[1, 2, 3],
+ * ); // [1, 2, 3, 4]
+ * 
+ * pipe(
+ * 	"gamma",
+ * 	A.insert(<string[]>["alpha", "beta"]),
+ * ); // ["alpha", "beta", "gamma"]
+ * 
+ * A.insert(true, [false]); // [false, true]
+ * ```
+ * 
+ * @remarks
+ * - Works like `push`, but the input is inserted into the array argument, which is handy in pipes
+ * 
+ * @see [`A.unshift`](https://utils.duplojs.dev/en/v1/api/array/unshift) For adding at the start
+ * @see [`A.concat`](https://utils.duplojs.dev/en/v1/api/array/concat) For concatenating arrays
+ * @see [`A.push`](https://utils.duplojs.dev/en/v1/api/array/push) For adding at the end of an array (input first)
+ * @see https://utils.duplojs.dev/en/v1/api/array/insert
+ * 
+ * @namespace A
+ * 
+ */
 export declare function insert<GenericElement extends unknown>(array: readonly GenericElement[]): (input: GenericElement) => GenericElement[];
 export declare function insert<GenericElement extends unknown>(input: GenericElement, array: readonly GenericElement[]): GenericElement[];

package/dist/array/is.cjs

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

package/dist/array/is.d.ts

@@ -1 +1,26 @@
+/**
+ * Checks whether a value is an array.
+ * 
+ * Signature: `is(value)` → returns a boolean
+ * 
+ * This is a type guard.
+ * ```ts
+ * A.is([1, 2]); // true
+ * 
+ * A.is("alpha"); // false
+ * 
+ * const value: unknown = ["beta"];
+ * if (A.is(value)) {
+ * 	// value is unknown[]
+ * }
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/array/is
+ * 
+ * @namespace A
+ * 
+ */
 export declare function is<GenericValue extends unknown>(arg: GenericValue): arg is GenericValue extends any[] ? GenericValue : never;

package/dist/array/is.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include array/is/index.md}
+ */
 function is(arg) {
     return arg instanceof Array;
 }

package/dist/array/isLastIndex.d.ts

@@ -1,2 +1,30 @@
+/**
+ * Checks if an index is the last index of an array.
+ * 
+ * **Supported call styles:**
+ * - Classic: `isLastIndex(array, index)` → returns a boolean
+ * - Curried: `isLastIndex(index)` → returns a function waiting for the array
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.map(
+ * 	["alpha", "beta", "omega"],
+ * 	(element, { index, self }) => whenElse(
+ * 		self,
+ * 		A.isLastIndex(index),
+ * 		() => `${element}:last`,
+ * 		() => element,
+ * 	),
+ * ); // ["alpha", "beta", "omega:last"]
+ * ```
+ * 
+ * @see [`A.at`](https://utils.duplojs.dev/en/v1/api/array/at) For accessing by index
+ * @see [`A.length`](https://utils.duplojs.dev/en/v1/api/array/length) For getting length
+ * @see https://utils.duplojs.dev/en/v1/api/array/isLastIndex
+ * 
+ * @namespace A
+ * 
+ */
 export declare function isLastIndex<GenericInput extends readonly unknown[]>(index: number): (input: GenericInput) => boolean;
 export declare function isLastIndex<GenericInput extends readonly unknown[]>(input: GenericInput, index: number): boolean;

package/dist/array/join.d.ts

@@ -1,4 +1,39 @@
 import { type AnyTuple } from "../common/types/anyTuple";
 import { type JoinTuple } from "./types";
+/**
+ * Joins array elements into a string.
+ * 
+ * **Supported call styles:**
+ * - Classic: `join(array, separator)` → returns a string
+ * - Curried: `join(separator)` → returns a function waiting for the array
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.join(
+ * 	["alpha", "beta"],
+ * 	"-",
+ * ); // "alpha-beta"
+ * 
+ * pipe(
+ * 	["a", "b", "c"],
+ * 	A.join(""),
+ * ); // "abc"
+ * 
+ * A.join(
+ * 	<const>["x", "y"],
+ * 	":",
+ * ); // "x:y"
+ * ```
+ * 
+ * @remarks
+ * - Tuple inputs preserve their literal joined type
+ * - Uses the same semantics as [`Array.prototype.join`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/array/join
+ * 
+ * @namespace A
+ * 
+ */
 export declare function join<GenericArray extends readonly string[], GenericSeparator extends string>(separator: GenericSeparator): (array: GenericArray) => GenericArray extends AnyTuple ? JoinTuple<GenericArray, GenericSeparator> : string;
 export declare function join<GenericArray extends readonly string[], GenericSeparator extends string>(array: GenericArray, separator: GenericSeparator): GenericArray extends AnyTuple ? JoinTuple<GenericArray, GenericSeparator> : string;

package/dist/array/lastIndexOf.d.ts

@@ -1,2 +1,39 @@
+/**
+ * Finds the last index of a value.
+ * 
+ * **Supported call styles:**
+ * - Classic: `lastIndexOf(array, value, fromIndex?)` → returns the index or `undefined`
+ * - Curried: `lastIndexOf(value)` → returns a function waiting for the array
+ * 
+ * The input array is not mutated.
+ * 
+ * ```ts
+ * A.lastIndexOf(
+ * 	[1, 2, 1],
+ * 	1,
+ * ); // 2
+ * 
+ * A.lastIndexOf(
+ * 	[1, 2, 1],
+ * 	1,
+ * 	1,
+ * ); // 0
+ * 
+ * pipe(
+ * 	["alpha", "beta"],
+ * 	A.lastIndexOf("gamma"),
+ * ); // undefined
+ * ```
+ * 
+ * @remarks
+ * - Returns `undefined` when not found (unlike `Array.prototype.lastIndexOf` which returns `-1`)
+ * - Curried style does not accept `fromIndex`
+ * 
+ * @see [`A.indexOf`](https://utils.duplojs.dev/en/v1/api/array/indexOf) For searching from the start
+ * @see https://utils.duplojs.dev/en/v1/api/array/lastIndexOf
+ * 
+ * @namespace A
+ * 
+ */
 export declare function lastIndexOf<GenericElement extends unknown>(element: GenericElement): (array: readonly GenericElement[]) => number | undefined;
 export declare function lastIndexOf<GenericElement extends unknown>(array: readonly GenericElement[], element: GenericElement, fromIndex?: number): number | undefined;