@duplojs/utils 1.4.32 → 1.4.33

package/dist/generator/asyncChunk.d.ts

@@ -1,2 +1,36 @@
+/**
+ * Splits an async iterable into fixed-size chunks.
+ * 
+ * **Supported call styles:**
+ * - Classic: `asyncChunk(iterator, size)` → returns an async generator of arrays
+ * - Curried: `asyncChunk(size)` → returns a function waiting for the iterator
+ * 
+ * The last chunk may be smaller than the size.
+ * The input iterator is not mutated.
+ * 
+ * ```ts
+ * const input = [1, 2, 3, 4];
+ * 
+ * const iterator = G.asyncMap(
+ * 	input,
+ * 	async(value) => Promise.resolve(value * 2),
+ * );
+ * 
+ * const result = await pipe(
+ * 	G.asyncChunk(
+ * 		iterator,
+ * 		2,
+ * 	),
+ * 	A.from,
+ * );
+ * // number[][]
+ * ```
+ * 
+ * @see [`G.chunk`](https://utils.duplojs.dev/en/v1/api/generator/chunk) For sync iterables
+ * @see https://utils.duplojs.dev/en/v1/api/generator/asyncChunk
+ * 
+ * @namespace G
+ * 
+ */
 export declare function asyncChunk<const GenericElement extends unknown>(size: number): (input: AsyncIterable<GenericElement>) => AsyncGenerator<GenericElement[], unknown, unknown>;
 export declare function asyncChunk<const GenericElement extends unknown>(input: AsyncIterable<GenericElement>, size: number): AsyncGenerator<GenericElement[], unknown, unknown>;

package/dist/generator/asyncFilter.d.ts

@@ -1,6 +1,56 @@
 interface AsyncGeneratorFilterParams {
     index: number;
 }
+/**
+ * Filters values from an iterable with async support.
+ * 
+ * **Supported call styles:**
+ * - Classic: `asyncFilter(iterator, predicate)` → returns an async generator
+ * - Curried: `asyncFilter(predicate)` → returns a function waiting for the iterator
+ * - Classic predicate: `asyncFilter(iterator, isType)` → narrows item types
+ * - Curried predicate: `asyncFilter(isType)` → narrows item types
+ * 
+ * The predicate receives `(item, { index })`.
+ * The input iterator is not mutated.
+ * 
+ * ```ts
+ * const ids = [201, 202, 203, 204];
+ * 
+ * const response = await fetch("https://api.example.com/orders/status");
+ * const { statuses } = await response.json() as {
+ * 	statuses: {
+ * 		id: number;
+ * 		status: string;
+ * 	}[];
+ * };
+ * const statusById = new Map(statuses.map(({ id: orderId, status }) => [
+ * 	orderId,
+ * 	status,
+ * ]));
+ * 
+ * const iterator = G.asyncFilter(ids, (orderId) => statusById.get(orderId) === "paid");
+ * 
+ * const result = await G.asyncReduce(
+ * 	iterator,
+ * 	G.reduceFrom<number[]>([]),
+ * 	({ element, lastValue, next }) => next([
+ * 		...lastValue,
+ * 		element,
+ * 	]),
+ * );
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Predicate overloads (type guards) narrow the output type
+ * 
+ * @see [`G.filter`](https://utils.duplojs.dev/en/v1/api/generator/filter) For sync iterables
+ * @see [`G.asyncMap`](https://utils.duplojs.dev/en/v1/api/generator/asyncMap) For mapping values
+ * @see https://utils.duplojs.dev/en/v1/api/generator/asyncFilter
+ * 
+ * @namespace G
+ * 
+ */
 export declare function asyncFilter<GenericElement extends unknown, GenericOutput extends GenericElement>(predicate: (item: GenericElement, params: AsyncGeneratorFilterParams) => item is GenericOutput): (iterator: Iterable<GenericElement> | AsyncIterable<GenericElement>) => AsyncGenerator<GenericOutput, unknown, unknown>;
 export declare function asyncFilter<GenericElement extends unknown, GenericOutput extends GenericElement>(iterator: Iterable<GenericElement> | AsyncIterable<GenericElement>, predicate: (item: GenericElement, params: AsyncGeneratorFilterParams) => item is GenericOutput): AsyncGenerator<GenericOutput, unknown, unknown>;
 export declare function asyncFilter<GenericElement extends unknown>(predicate: (item: GenericElement, params: AsyncGeneratorFilterParams) => boolean): (iterator: Iterable<GenericElement> | AsyncIterable<GenericElement>) => AsyncGenerator<GenericElement, unknown, unknown>;

package/dist/generator/asyncLoop.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include generator/asyncLoop/index.md}
+ */
 async function* asyncLoop(loop) {
     let previousOutput = undefined;
     for (let count = 0; true; count++) {

package/dist/generator/asyncLoop.d.ts

@@ -1,3 +1,46 @@
 import { type MaybePromise } from "../common";
 import { type LoopOutputExistResult, type LoopOutputNextResult, type GeneratorLoopParams } from "./loop";
+/**
+ * Creates an async generator from a loop function.
+ * 
+ * Signature: `asyncLoop(loopFunction)` → returns an async generator
+ * 
+ * The loop receives `{ count, previousOutput, next, exit }`.
+ * The generator ends when `exit` is returned.
+ * 
+ * ```ts
+ * const limit = 3;
+ * 
+ * const iterator = G.asyncLoop(async(
+ * 	{
+ * 		count,
+ * 		next,
+ * 		exit,
+ * 	}: G.GeneratorLoopParams<number>,
+ * ) => {
+ * 	if (count === limit) {
+ * 		return exit();
+ * 	}
+ * 	const response = await fetch(`https://api.example.com/pages/${count + 1}`);
+ * 	const { id: pageId } = await response.json() as { id: number };
+ * 	return next(pageId);
+ * });
+ * 
+ * const result = await G.asyncReduce(
+ * 	iterator,
+ * 	G.reduceFrom<number[]>([]),
+ * 	({ element, lastValue, next }) => next([
+ * 		...lastValue,
+ * 		element,
+ * 	]),
+ * );
+ * 
+ * ```
+ * 
+ * @see [`G.loop`](https://utils.duplojs.dev/en/v1/api/generator/loop) For sync loops
+ * @see https://utils.duplojs.dev/en/v1/api/generator/asyncLoop
+ * 
+ * @namespace G
+ * 
+ */
 export declare function asyncLoop<GenericRawNextOutput extends unknown, GenericOutput extends MaybePromise<LoopOutputNextResult<GenericRawNextOutput> | LoopOutputExistResult<unknown> | LoopOutputNextResult<undefined> | LoopOutputExistResult<undefined>>>(loop: (params: GeneratorLoopParams<GenericRawNextOutput>) => GenericOutput): AsyncGenerator<Exclude<Awaited<GenericOutput> extends infer InferredOutput ? InferredOutput extends LoopOutputNextResult ? InferredOutput["-nextData"] : InferredOutput extends LoopOutputExistResult ? InferredOutput["-exitData"] : never : never, undefined>, unknown, unknown>;

package/dist/generator/asyncLoop.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include generator/asyncLoop/index.md}
+ */
 async function* asyncLoop(loop) {
     let previousOutput = undefined;
     for (let count = 0; true; count++) {

package/dist/generator/asyncMap.d.ts

@@ -1,6 +1,44 @@
 interface AsyncGeneratorMapParams {
     index: number;
 }
+/**
+ * Maps values from an iterable to an async generator.
+ * 
+ * **Supported call styles:**
+ * - Classic: `asyncMap(iterator, theFunction)` → returns an async generator
+ * - Curried: `asyncMap(theFunction)` → returns a function waiting for the iterator
+ * 
+ * The function receives `(item, { index })`.
+ * The input iterator is not mutated.
+ * 
+ * ```ts
+ * const ids = [1, 2, 3];
+ * 
+ * const result = await pipe(
+ * 	ids,
+ * 	G.asyncMap(async(itemId) => {
+ * 		const response = await fetch(`https://api.example.com/items/${itemId}`);
+ * 		const { price } = await response.json() as { price: number };
+ * 		return price;
+ * 	}),
+ * 	G.asyncReduce(
+ * 		G.reduceFrom<number[]>([]),
+ * 		({ element, lastValue, next }) => next([
+ * 			...lastValue,
+ * 			element,
+ * 		]),
+ * 	),
+ * );
+ * 
+ * ```
+ * 
+ * @see [`G.map`](https://utils.duplojs.dev/en/v1/api/generator/map) For sync iterables
+ * @see [`G.asyncFilter`](https://utils.duplojs.dev/en/v1/api/generator/asyncFilter) For filtering values
+ * @see https://utils.duplojs.dev/en/v1/api/generator/asyncMap
+ * 
+ * @namespace G
+ * 
+ */
 export declare function asyncMap<const GenericInput extends unknown, const GenericOutput extends unknown>(theFunction: (arg: GenericInput, params: AsyncGeneratorMapParams) => GenericOutput): (iterator: AsyncIterable<GenericInput> | Iterable<GenericInput>) => AsyncGenerator<Awaited<GenericOutput>, unknown, unknown>;
 export declare function asyncMap<const GenericInput extends unknown, const GenericOutput extends unknown>(iterator: AsyncIterable<GenericInput> | Iterable<GenericInput>, theFunction: (arg: GenericInput, params: AsyncGeneratorMapParams) => GenericOutput): AsyncGenerator<Awaited<GenericOutput>, unknown, unknown>;
 export {};

package/dist/generator/asyncReduce.d.ts

@@ -1,4 +1,38 @@
 import { type GeneratorReduceFromValue, type GeneratorEligibleReduceFromValue, type GeneratorReduceFunctionParams, type GeneratorReduceExit, type GeneratorReduceNext } from "./reduce";
 import { type IsEqual, type MaybePromise } from "../common";
+/**
+ * Reduces an iterable to a single value with async support.
+ * 
+ * **Supported call styles:**
+ * - Classic: `asyncReduce(iterator, startValue, theFunction)` → returns a promise
+ * - Curried: `asyncReduce(startValue, theFunction)` → returns a function waiting for the iterator
+ * 
+ * The function receives `{ element, index, lastValue, next, exit, nextWithObject }`.
+ * The input iterator is not mutated.
+ * 
+ * ```ts
+ * const values = [10, 20, 30];
+ * 
+ * const result = await G.asyncReduce(
+ * 	values,
+ * 	G.reduceFrom(0),
+ * 	async({ element, lastValue, next }) => {
+ * 		const response = await fetch("https://api.example.com/tax");
+ * 		const { rate } = await response.json() as { rate: number };
+ * 		return next(N.add(lastValue, N.multiply(element, rate)));
+ * 	},
+ * );
+ * 
+ * ```
+ * 
+ * @remarks
+ * - `exit` stops the reduction early
+ * 
+ * @see [`G.reduce`](https://utils.duplojs.dev/en/v1/api/generator/reduce) For sync iterables
+ * @see https://utils.duplojs.dev/en/v1/api/generator/asyncReduce
+ * 
+ * @namespace G
+ * 
+ */
 export declare function asyncReduce<GenericElement extends unknown, GenericReduceFrom extends GeneratorEligibleReduceFromValue, GenericExit extends GeneratorReduceExit = GeneratorReduceExit<never>>(startValue: GenericReduceFrom, theFunction: (params: GeneratorReduceFunctionParams<GenericElement, GeneratorReduceFromValue<GenericReduceFrom>>) => MaybePromise<GeneratorReduceNext<GeneratorReduceFromValue<GenericReduceFrom>> | GenericExit>): (iterator: Iterable<GenericElement> | AsyncIterable<GenericElement>) => Promise<GeneratorReduceFromValue<GenericReduceFrom> | (IsEqual<GenericExit, GeneratorReduceExit> extends true ? never : GenericExit["-exit"])>;
 export declare function asyncReduce<GenericElement extends unknown, GenericReduceFrom extends GeneratorEligibleReduceFromValue, GenericExit extends GeneratorReduceExit = GeneratorReduceExit<never>>(iterator: Iterable<GenericElement> | AsyncIterable<GenericElement>, startValue: GenericReduceFrom, theFunction: (params: GeneratorReduceFunctionParams<GenericElement, GeneratorReduceFromValue<GenericReduceFrom>>) => MaybePromise<GeneratorReduceNext<GeneratorReduceFromValue<GenericReduceFrom>> | GenericExit>): Promise<GeneratorReduceFromValue<GenericReduceFrom> | (IsEqual<GenericExit, GeneratorReduceExit> extends true ? never : GenericExit["-exit"])>;

package/dist/generator/chunk.d.ts

@@ -1,2 +1,29 @@
+/**
+ * Splits an iterable into fixed-size chunks.
+ * 
+ * **Supported call styles:**
+ * - Classic: `chunk(iterator, size)` → returns a generator of arrays
+ * - Curried: `chunk(size)` → returns a function waiting for the iterator
+ * 
+ * The last chunk may be smaller than the size.
+ * The input iterator is not mutated.
+ * 
+ * ```ts
+ * const input = G.loop(
+ * 	({ count, next, exit }: G.GeneratorLoopParams<number>) => N.greater(count, 7)
+ * 		? exit()
+ * 		: next(count),
+ * );
+ * 
+ * const result = G.chunk(input, 3);
+ * // Generator<number[], unknown, unknown>
+ * ```
+ * 
+ * @see [`G.asyncChunk`](https://utils.duplojs.dev/en/v1/api/generator/asyncChunk) For async iterables
+ * @see https://utils.duplojs.dev/en/v1/api/generator/chunk
+ * 
+ * @namespace G
+ * 
+ */
 export declare function chunk<const GenericElement extends unknown>(size: number): (input: Iterable<GenericElement>) => Generator<GenericElement[], unknown, unknown>;
 export declare function chunk<const GenericElement extends unknown>(input: Iterable<GenericElement>, size: number): Generator<GenericElement[], unknown, unknown>;

package/dist/generator/execute.d.ts

@@ -1,2 +1,35 @@
 import { type EscapeVoid } from "../common";
+/**
+ * Consumes an iterable or async iterable.
+ * 
+ * Signature: `execute(iterator)` → returns `void` or `Promise<void>`
+ * 
+ * This is useful for running generators with side effects.
+ * 
+ * ```ts
+ * const source = [5, 10, 15, 20];
+ * 
+ * const iterator = G.asyncMap(
+ * 	source,
+ * 	async(value) => {
+ * 		if (N.modulo(value, 2) === 0) {
+ * 			await fetch("https://api.example.com/collect", {
+ * 				method: "POST",
+ * 				body: JSON.stringify({ value }),
+ * 			});
+ * 		}
+ * 		return value;
+ * 	},
+ * );
+ * 
+ * await G.execute(iterator);
+ * 
+ * ```
+ * 
+ * @see [`G.loop`](https://utils.duplojs.dev/en/v1/api/generator/loop) For generating values
+ * @see https://utils.duplojs.dev/en/v1/api/generator/execute
+ * 
+ * @namespace G
+ * 
+ */
 export declare function execute<GenericIterator extends AsyncIterable<unknown> | Iterable<unknown>>(iterator: GenericIterator): GenericIterator extends AsyncIterable<unknown> ? Promise<void> : EscapeVoid;

package/dist/generator/filter.d.ts

@@ -1,6 +1,46 @@
 interface GeneratorFilterParams {
     index: number;
 }
+/**
+ * Filters values from an iterable.
+ * 
+ * **Supported call styles:**
+ * - Classic: `filter(iterator, predicate)` → returns a generator
+ * - Curried: `filter(predicate)` → returns a function waiting for the iterator
+ * - Classic predicate: `filter(iterator, isType)` → narrows item types
+ * - Curried predicate: `filter(isType)` → narrows item types
+ * 
+ * The predicate receives `(item, { index })`.
+ * The input iterator is not mutated.
+ * 
+ * ```ts
+ * const values = [9, 12, 15, 18, 21];
+ * const threshold = 15;
+ * 
+ * const result = pipe(
+ * 	values,
+ * 	G.filter((value) => value >= threshold && value % 3 === 0),
+ * 	G.reduce(
+ * 		G.reduceFrom<number[]>([]),
+ * 		({ element, lastValue, next }) => next([
+ * 			...lastValue,
+ * 			element,
+ * 		]),
+ * 	),
+ * );
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Predicate overloads (type guards) narrow the output type
+ * 
+ * @see [`G.map`](https://utils.duplojs.dev/en/v1/api/generator/map) For mapping values
+ * @see [`G.asyncFilter`](https://utils.duplojs.dev/en/v1/api/generator/asyncFilter) For async iterables
+ * @see https://utils.duplojs.dev/en/v1/api/generator/filter
+ * 
+ * @namespace G
+ * 
+ */
 export declare function filter<GenericElement extends unknown, GenericOutput extends GenericElement>(predicate: (item: GenericElement, params: GeneratorFilterParams) => item is GenericOutput): (iterator: Iterable<GenericElement>) => Generator<GenericOutput, unknown, unknown>;
 export declare function filter<GenericElement extends unknown, GenericOutput extends GenericElement>(iterator: Iterable<GenericElement>, predicate: (item: GenericElement, params: GeneratorFilterParams) => item is GenericOutput): Generator<GenericOutput, unknown, unknown>;
 export declare function filter<GenericElement extends unknown>(predicate: (item: GenericElement, params: GeneratorFilterParams) => boolean): (iterator: Iterable<GenericElement>) => Generator<GenericElement, unknown, unknown>;

package/dist/generator/index.cjs

@@ -12,7 +12,9 @@ var asyncLoop = require('./asyncLoop.cjs');
 var chunk = require('./chunk.cjs');
 var asyncChunk = require('./asyncChunk.cjs');
 
-
+/**
+ * {@include generator/index.md}
+ */
 
 exports.map = map.map;
 exports.execute = execute.execute;

package/dist/generator/index.d.ts

@@ -1,3 +1,29 @@
+/**
+ * Generator utilities for iterable and async iterable processing. Functions preserve
+ * inputs and return new values or iterables.
+ * 
+ * **How to import:**
+ * - From the main entry (namespace style)
+ * - Via direct import for tree-shaking
+ * 
+ * ```ts
+ * import { DGenerator, G } from "@duplojs/utils";
+ * import * as DGenerator from "@duplojs/utils/generator";
+ * import * as G from "@duplojs/utils/generator";
+ * ```
+ * 
+ * What you will find in this namespace:
+ * - iteration and transforms (`G.map`, `G.filter`, `G.reduce`)
+ * - reduce helpers (`G.reduceFrom`)
+ * - control and execution (`G.loop`, `G.execute`)
+ * - batching (`G.chunk`)
+ * - async variants (`G.asyncMap`, `G.asyncFilter`, `G.asyncReduce`, `G.asyncLoop`, `G.asyncChunk`)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/generator
+ * 
+ * @namespace G
+ * 
+ */
 export * from "./map";
 export * from "./execute";
 export * from "./asyncMap";

package/dist/generator/index.mjs

@@ -9,3 +9,7 @@ export { loop } from './loop.mjs';
 export { asyncLoop } from './asyncLoop.mjs';
 export { chunk } from './chunk.mjs';
 export { asyncChunk } from './asyncChunk.mjs';
+
+/**
+ * {@include generator/index.md}
+ */

package/dist/generator/loop.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include generator/loop/index.md}
+ */
 function* loop(loop) {
     let previousOutput = undefined;
     for (let count = 0; true; count++) {

package/dist/generator/loop.d.ts

@@ -11,4 +11,39 @@ export interface GeneratorLoopParams<GenericRawNextOutput extends any> {
     next<GenericValue extends GenericRawNextOutput | undefined = undefined>(output?: GenericValue): LoopOutputNextResult<GenericValue>;
     exit<GenericOutput extends AnyValue = undefined>(output?: GenericOutput): LoopOutputExistResult<GenericOutput>;
 }
+/**
+ * Creates a generator from a loop function.
+ * 
+ * Signature: `loop(loopFunction)` → returns a generator
+ * 
+ * The loop receives `{ count, previousOutput, next, exit }`.
+ * The generator ends when `exit` is returned.
+ * 
+ * ```ts
+ * const limit = 4;
+ * 
+ * const result = pipe(
+ * 	G.loop(({ count, next, exit }: G.GeneratorLoopParams<number>) => {
+ * 		if (count > limit) {
+ * 			return exit();
+ * 		}
+ * 		return next(count * 2);
+ * 	}),
+ * 	G.reduce(
+ * 		G.reduceFrom<number[]>([]),
+ * 		({ element, lastValue, next }) => next([
+ * 			...lastValue,
+ * 			element,
+ * 		]),
+ * 	),
+ * );
+ * 
+ * ```
+ * 
+ * @see [`G.asyncLoop`](https://utils.duplojs.dev/en/v1/api/generator/asyncLoop) For async loops
+ * @see https://utils.duplojs.dev/en/v1/api/generator/loop
+ * 
+ * @namespace G
+ * 
+ */
 export declare function loop<GenericRawExitOutput extends AnyValue = undefined, GenericRawNextOutput extends AnyValue = undefined>(loop: (params: GeneratorLoopParams<GenericRawNextOutput>) => LoopOutputNextResult<GenericRawNextOutput> | LoopOutputNextResult<undefined> | LoopOutputExistResult<GenericRawExitOutput> | LoopOutputExistResult<undefined>): Generator<Exclude<GenericRawExitOutput | GenericRawNextOutput, undefined>, unknown, unknown>;

package/dist/generator/loop.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include generator/loop/index.md}
+ */
 function* loop(loop) {
     let previousOutput = undefined;
     for (let count = 0; true; count++) {

package/dist/generator/map.d.ts

@@ -1,6 +1,41 @@
 interface GeneratorMapParams {
     index: number;
 }
+/**
+ * Maps values from an iterable to a new generator.
+ * 
+ * **Supported call styles:**
+ * - Classic: `map(iterator, theFunction)` → returns a generator
+ * - Curried: `map(theFunction)` → returns a function waiting for the iterator
+ * 
+ * The function receives `(item, { index })`.
+ * The input iterator is not mutated.
+ * 
+ * ```ts
+ * const values = [8, 12, 20];
+ * const rate = 1.1;
+ * 
+ * const result = pipe(
+ * 	values,
+ * 	G.map((value) => N.multiply(value, rate)),
+ * 	G.reduce(
+ * 		G.reduceFrom<number[]>([]),
+ * 		({ element, lastValue, next }) => next([
+ * 			...lastValue,
+ * 			element,
+ * 		]),
+ * 	),
+ * );
+ * 
+ * ```
+ * 
+ * @see [`G.filter`](https://utils.duplojs.dev/en/v1/api/generator/filter) For filtering values
+ * @see [`G.asyncMap`](https://utils.duplojs.dev/en/v1/api/generator/asyncMap) For async iterables
+ * @see https://utils.duplojs.dev/en/v1/api/generator/map
+ * 
+ * @namespace G
+ * 
+ */
 export declare function map<const GenericInput extends unknown, const GenericOutput extends unknown>(theFunction: (arg: GenericInput, params: GeneratorMapParams) => GenericOutput): (iterator: Iterable<GenericInput>) => Generator<GenericOutput, unknown, unknown>;
 export declare function map<const GenericInput extends unknown, const GenericOutput extends unknown>(iterator: Iterable<GenericInput>, theFunction: (arg: GenericInput, params: GeneratorMapParams) => GenericOutput): Generator<GenericOutput, unknown, unknown>;
 export {};

package/dist/generator/reduce.cjs

@@ -6,6 +6,9 @@ var unwrap = require('../common/unwrap.cjs');
 var reduce$1 = require('../array/reduce.cjs');
 
 const generatorReduceFromKind = kind.createKind("generator-reduce-from");
+/**
+ * {@include generator/reduceFrom/index.md}
+ */
 function reduceFrom(value) {
     return generatorReduceFromKind.setTo(wrapValue.wrapValue(value));
 }

package/dist/generator/reduce.d.ts

@@ -20,9 +20,69 @@ export interface GeneratorReduceFunctionParams<GenericElement extends unknown =
 declare const generatorReduceFromKind: import("../common").KindHandler<import("../common").KindDefinition<"generator-reduce-from", unknown>>;
 export interface GeneratorReduceFromResult<GenericValue extends unknown = unknown> extends Kind<typeof generatorReduceFromKind.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
+ * const result = G.reduce(
+ * 	[1, 2],
+ * 	G.reduceFrom(0),
+ * 	({ element, lastValue, next }) => next(lastValue + element),
+ * );
+ * ```
+ * 
+ * @see [`G.reduce`](https://utils.duplojs.dev/en/v1/api/generator/reduce) For reducing iterables
+ * @see https://utils.duplojs.dev/en/v1/api/generator/reduceFrom
+ * 
+ * @namespace G
+ * 
+ */
 export declare function reduceFrom<GenericValue extends unknown>(value: GenericValue): GeneratorReduceFromResult<GenericValue>;
 export type GeneratorEligibleReduceFromValue = number | string | bigint | boolean | GeneratorReduceFromResult;
 export type GeneratorReduceFromValue<GenericValue extends GeneratorEligibleReduceFromValue> = GenericValue extends GeneratorReduceFromResult ? Unwrap<GenericValue> : ToLargeEnsemble<GenericValue>;
+/**
+ * Reduces an iterable to a single value.
+ * 
+ * **Supported call styles:**
+ * - Classic: `reduce(iterator, startValue, theFunction)` → returns the reduced value
+ * - Curried: `reduce(startValue, theFunction)` → returns a function waiting for the iterator
+ * 
+ * The function receives `{ element, index, lastValue, next, exit, nextWithObject, nextPush }`.
+ * The input iterator is not mutated.
+ * 
+ * ```ts
+ * const values = [4, 8, 12];
+ * 
+ * const result = pipe(
+ * 	values,
+ * 	G.reduce(
+ * 		G.reduceFrom({
+ * 			total: 0,
+ * 			count: 0,
+ * 		}),
+ * 		({ element, lastValue, next }) => next({
+ * 			total: N.add(lastValue.total, element),
+ * 			count: N.add(lastValue.count, 1),
+ * 		}),
+ * 	),
+ * );
+ * 
+ * ```
+ * 
+ * @remarks
+ * - `exit` stops the reduction early
+ * 
+ * @see [`G.reduceFrom`](https://utils.duplojs.dev/en/v1/api/generator/reduceFrom) For typed start values
+ * @see [`G.asyncReduce`](https://utils.duplojs.dev/en/v1/api/generator/asyncReduce) For async iterables
+ * @see https://utils.duplojs.dev/en/v1/api/generator/reduce
+ * 
+ * @namespace G
+ * 
+ */
 export declare function reduce<GenericElement extends unknown, GenericReduceFrom extends GeneratorEligibleReduceFromValue, GenericExit extends GeneratorReduceExit = GeneratorReduceExit<never>>(startValue: GenericReduceFrom, theFunction: (params: GeneratorReduceFunctionParams<GenericElement, GeneratorReduceFromValue<GenericReduceFrom>>) => GeneratorReduceNext<GeneratorReduceFromValue<GenericReduceFrom>> | GenericExit): (iterator: Iterable<GenericElement>) => GeneratorReduceFromValue<GenericReduceFrom> | (IsEqual<GenericExit, GeneratorReduceExit> extends true ? never : GenericExit["-exit"]);
 export declare function reduce<GenericElement extends unknown, GenericReduceFrom extends GeneratorEligibleReduceFromValue, GenericExit extends GeneratorReduceExit = GeneratorReduceExit<never>>(iterator: Iterable<GenericElement>, startValue: GenericReduceFrom, theFunction: (params: GeneratorReduceFunctionParams<GenericElement, GeneratorReduceFromValue<GenericReduceFrom>>) => GeneratorReduceNext<GeneratorReduceFromValue<GenericReduceFrom>> | GenericExit): GeneratorReduceFromValue<GenericReduceFrom> | (IsEqual<GenericExit, GeneratorReduceExit> extends true ? never : GenericExit["-exit"]);
 export {};

package/dist/generator/reduce.mjs

@@ -4,6 +4,9 @@ import { unwrap } from '../common/unwrap.mjs';
 import { reduceTools } from '../array/reduce.mjs';
 
 const generatorReduceFromKind = createKind("generator-reduce-from");
+/**
+ * {@include generator/reduceFrom/index.md}
+ */
 function reduceFrom(value) {
     return generatorReduceFromKind.setTo(wrapValue(value));
 }

package/dist/metadata.json

@@ -3084,6 +3084,15 @@
         {
           "name": "format.mjs"
         },
+        {
+          "name": "formatTime.cjs"
+        },
+        {
+          "name": "formatTime.d.ts"
+        },
+        {
+          "name": "formatTime.mjs"
+        },
         {
           "name": "getTimezoneOffset.cjs"
         },

package/dist/number/abs.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include number/abs/index.md}
+ */
 function abs(value) {
     return Math.abs(value);
 }

package/dist/number/abs.d.ts

@@ -1 +1,28 @@
+/**
+ * Returns the absolute value of a number.
+ * 
+ * Signature: `abs(value)` → returns a number
+ * 
+ * ```ts
+ * N.abs(-5); // 5
+ * 
+ * pipe(
+ * 	-5,
+ * 	N.abs,
+ * ); // 5
+ * 
+ * N.abs(0); // 0
+ * 
+ * N.abs(3); // 3
+ * 
+ * ```
+ * 
+ * @remarks
+ * - Uses the same semantics as [`Math.abs`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/abs)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/number/abs
+ * 
+ * @namespace N
+ * 
+ */
 export declare function abs<GenericValue extends number>(value: GenericValue): number;

package/dist/number/abs.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include number/abs/index.md}
+ */
 function abs(value) {
     return Math.abs(value);
 }