@duplojs/utils 1.3.32 → 1.4.33

package/dist/common/asyncPipe.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include common/asyncPipe/index.md}
+ */
 async function asyncPipe(input, ...pipes) {
     let acc = await input;
     for (const pipe of pipes) {

package/dist/common/asyncPipe.d.ts

@@ -3,6 +3,41 @@ import { type BreakGenericLink, type EscapeVoid } from "./types";
 import { type AnyValue } from "./types/anyValue";
 import { type MaybePromise } from "./types/maybePromise";
 type MaybePromiseLike<GenericValue extends unknown> = MaybePromise<GenericValue> | MaybeFutureEither<GenericValue>;
+/**
+ * The asyncPipe() method chains asynchronous functions (promises or FutureEither) in series. Each step waits for the previous one to resolve and the last value is returned in a promise.
+ * 
+ * Signature: `asyncPipe(input, pipe1, pipe2)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = {
+ * 	host: "api.local",
+ * 	retries: 1,
+ * };
+ * 
+ * const result = await asyncPipe(
+ * 	input,
+ * 	({ host, retries }) => ({
+ * 		url: `https://${host}/health`,
+ * 		retries,
+ * 	}),
+ * 	// fake HTTP request
+ * 	async({ url, retries }) => Promise.resolve({
+ * 		url,
+ * 		status: 200,
+ * 		retries,
+ * 	}),
+ * 	({ status, url, retries }) => `${status} on ${url} (retries: ${retries})`,
+ * );
+ * // result: "200 on https://api.local/health (retries: 1)"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/asyncPipe
+ * 
+ * @namespace C
+ * 
+ */
 export declare function asyncPipe<GenericInput extends MaybePromiseLike<AnyValue>, GenericOutputPipe1 extends MaybePromiseLike<AnyValue | EscapeVoid>>(input: GenericInput, pipe1: (input: Awaited<GenericInput>) => GenericOutputPipe1): Promise<Awaited<BreakGenericLink<GenericOutputPipe1>>>;
 export declare function asyncPipe<GenericInput extends MaybePromiseLike<AnyValue>, GenericOutputPipe1 extends MaybePromiseLike<AnyValue | EscapeVoid>, GenericOutputPipe2 extends MaybePromiseLike<AnyValue | EscapeVoid>>(input: GenericInput, pipe1: (input: Awaited<GenericInput>) => GenericOutputPipe1, pipe2: (input: Awaited<GenericOutputPipe1>) => GenericOutputPipe2): Promise<Awaited<BreakGenericLink<GenericOutputPipe2>>>;
 export declare function asyncPipe<GenericInput extends MaybePromiseLike<AnyValue>, GenericOutputPipe1 extends MaybePromiseLike<AnyValue | EscapeVoid>, GenericOutputPipe2 extends MaybePromiseLike<AnyValue | EscapeVoid>, GenericOutputPipe3 extends MaybePromiseLike<AnyValue | EscapeVoid>>(input: GenericInput, pipe1: (input: Awaited<GenericInput>) => GenericOutputPipe1, pipe2: (input: Awaited<GenericOutputPipe1>) => GenericOutputPipe2, pipe3: (input: Awaited<GenericOutputPipe2>) => GenericOutputPipe3): Promise<Awaited<BreakGenericLink<GenericOutputPipe3>>>;

package/dist/common/asyncPipe.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include common/asyncPipe/index.md}
+ */
 async function asyncPipe(input, ...pipes) {
     let acc = await input;
     for (const pipe of pipes) {

package/dist/common/asyncRetry.cjs

@@ -2,6 +2,9 @@
 
 var sleep = require('./sleep.cjs');
 
+/**
+ * {@include common/asyncRetry/index.md}
+ */
 async function useAsyncRetry(retryFunction, shouldRetry, options) {
     for (let currentTry = 1; true; currentTry++) {
         const result = await retryFunction();
@@ -17,6 +20,9 @@ async function useAsyncRetry(retryFunction, shouldRetry, options) {
         }
     }
 }
+/**
+ * {@include common/asyncRetry/index.md}
+ */
 function createAsyncRetry(retryFunction, checkFunction, options) {
     return ((...args) => useAsyncRetry(() => retryFunction(...args), checkFunction, options));
 }

package/dist/common/asyncRetry.d.ts

@@ -3,6 +3,70 @@ interface CreateAsyncRetryOptions {
     timeToSleep?: number;
     log?: boolean;
 }
+/**
+ * The helpers useAsyncRetry() and createAsyncRetry() rerun an async function as long as a retry criterion is true, with options for attempts, delay, and logging.
+ * 
+ * Signature: `useAsyncRetry(retryFunction, shouldRetry, options)` and `createAsyncRetry(retryFunction, checkFunction, options)` → returns a value
+ * 
+ * ```ts
+ * // direct call
+ * const result = await useAsyncRetry(
+ * 	() => Promise.resolve("test"),
+ * 	equal("test"),
+ * 	{
+ * 		maxRetry: 5,
+ * 		timeToSleep: 0,
+ * 	},
+ * ); // type: string
+ * 
+ * // prepared function
+ * const prepareAsyncRetryFunction = createAsyncRetry(
+ * 	(input: string) => Promise.resolve(input),
+ * 	equal("test"),
+ * 	{
+ * 		maxRetry: 5,
+ * 		timeToSleep: 0,
+ * 	},
+ * ); // type: (input: string) => Promise<string>
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/asyncRetry
+ * 
+ * @namespace C
+ * 
+ */
 export declare function useAsyncRetry<GenericOutput extends unknown>(retryFunction: () => Promise<GenericOutput>, shouldRetry: (result: GenericOutput) => boolean, options: CreateAsyncRetryOptions): Promise<GenericOutput>;
+/**
+ * The helpers useAsyncRetry() and createAsyncRetry() rerun an async function as long as a retry criterion is true, with options for attempts, delay, and logging.
+ * 
+ * Signature: `useAsyncRetry(retryFunction, shouldRetry, options)` and `createAsyncRetry(retryFunction, checkFunction, options)` → returns a value
+ * 
+ * ```ts
+ * // direct call
+ * const result = await useAsyncRetry(
+ * 	() => Promise.resolve("test"),
+ * 	equal("test"),
+ * 	{
+ * 		maxRetry: 5,
+ * 		timeToSleep: 0,
+ * 	},
+ * ); // type: string
+ * 
+ * // prepared function
+ * const prepareAsyncRetryFunction = createAsyncRetry(
+ * 	(input: string) => Promise.resolve(input),
+ * 	equal("test"),
+ * 	{
+ * 		maxRetry: 5,
+ * 		timeToSleep: 0,
+ * 	},
+ * ); // type: (input: string) => Promise<string>
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/asyncRetry
+ * 
+ * @namespace C
+ * 
+ */
 export declare function createAsyncRetry<GenericAnyFunction extends ((...args: any[]) => Promise<any>)>(retryFunction: GenericAnyFunction, checkFunction: (result: Awaited<ReturnType<GenericAnyFunction>>) => boolean, options: CreateAsyncRetryOptions): GenericAnyFunction;
 export {};

package/dist/common/asyncRetry.mjs

@@ -1,5 +1,8 @@
 import { sleep } from './sleep.mjs';
 
+/**
+ * {@include common/asyncRetry/index.md}
+ */
 async function useAsyncRetry(retryFunction, shouldRetry, options) {
     for (let currentTry = 1; true; currentTry++) {
         const result = await retryFunction();
@@ -15,6 +18,9 @@ async function useAsyncRetry(retryFunction, shouldRetry, options) {
         }
     }
 }
+/**
+ * {@include common/asyncRetry/index.md}
+ */
 function createAsyncRetry(retryFunction, checkFunction, options) {
     return ((...args) => useAsyncRetry(() => retryFunction(...args), checkFunction, options));
 }

package/dist/common/builder.cjs

@@ -20,6 +20,9 @@ class MissingBuilderMethodsError extends kind.kindHeritage("missing-builder-meth
         this.method = method;
     }
 }
+/**
+ * {@include common/builder/index.md}
+ */
 function createBuilder(builderName) {
     const store = builderStore.value[builderName] ?? {};
     builderStore.set({

package/dist/common/builder.d.ts

@@ -30,5 +30,93 @@ export declare class MissingBuilderMethodsError extends MissingBuilderMethodsErr
     method: string;
     constructor(method: string);
 }
+/**
+ * The createBuilder() function lets you create a builder whose methods can be defined after declaration (and even redefined) while keeping strict typing.
+ * 
+ * Signature: `createBuilder(builderName)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * interface UrlAccumulator {
+ * 	base: string;
+ * 	path: string[];
+ * 	query: Record<string, string>;
+ * }
+ * 
+ * interface UrlBuilder extends Builder<UrlAccumulator> {
+ * 	path(segment: string): UrlBuilder;
+ * 	query(key: string, value: string): UrlBuilder;
+ * 	build(): string;
+ * }
+ * 
+ * const urlBuilderHandler = createBuilder<UrlBuilder>("urlBuilder");
+ * 
+ * urlBuilderHandler
+ * 	.set("path", ({ args, accumulator, next }) => {
+ * 		const [segment] = args;
+ * 		return next({
+ * 			...accumulator,
+ * 			path: [...accumulator.path, segment],
+ * 		});
+ * 	})
+ * 	.set("query", ({ args, accumulator, next }) => {
+ * 		const [key, value] = args;
+ * 		return next({
+ * 			...accumulator,
+ * 			query: {
+ * 				...accumulator.query,
+ * 				[key]: value,
+ * 			},
+ * 		});
+ * 	})
+ * 	.set("build", ({ accumulator }) => pipe(
+ * 		accumulator,
+ * 		DObject.to({
+ * 			base: DObject.getProperty("base"),
+ * 			path: ({ path }) => DArray.join(path, "/"),
+ * 			query: ({ query }) => DObject.entries(query),
+ * 		}),
+ * 		({ base, path, query }) => {
+ * 			const url = new URL(base);
+ * 			url.pathname = path;
+ * 			DArray.map(
+ * 				query,
+ * 				([key, value]) => void url.searchParams.set(key, value),
+ * 			);
+ * 			return url.toString();
+ * 		},
+ * 	));
+ * 
+ * // "https://example.com/users?page=1"
+ * const url = urlBuilderHandler
+ * 	.use({
+ * 		base: "https://example.com",
+ * 		path: [],
+ * 		query: {},
+ * 	})
+ * 	.path("users")
+ * 	.query("page", "1")
+ * 	.build();
+ * 
+ * // Override (le dernier set gagne)
+ * urlBuilderHandler.set("build", ({ accumulator }) => `${accumulator.base}/${accumulator.path.join("/")}`);
+ * 
+ * // "https://example.com/docs"
+ * const overridden = urlBuilderHandler
+ * 	.use({
+ * 		base: "https://example.com",
+ * 		path: [],
+ * 		query: {},
+ * 	})
+ * 	.path("docs")
+ * 	.build();
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/builder
+ * 
+ * @namespace C
+ * 
+ */
 export declare function createBuilder<GenericBuilder extends Builder>(builderName: string): BuilderHandler<GenericBuilder>;
 export {};

package/dist/common/builder.mjs

@@ -18,6 +18,9 @@ class MissingBuilderMethodsError extends kindHeritage("missing-builder-methods-e
         this.method = method;
     }
 }
+/**
+ * {@include common/builder/index.md}
+ */
 function createBuilder(builderName) {
     const store = builderStore.value[builderName] ?? {};
     builderStore.set({

package/dist/common/clone.cjs

@@ -2,6 +2,9 @@
 
 var entries = require('../object/entries.cjs');
 
+/**
+ * {@include common/clone/index.md}
+ */
 function clone(unknownValue) {
     if (!unknownValue) {
         return unknownValue;

package/dist/common/clone.d.ts

@@ -1,2 +1,14 @@
 import { type SimplifyTypeForce } from "../common/types/simplifyTypeForce";
+/**
+ * The clone() function performs a typed deep copy of a value while preserving its structure and types.
+ * 
+ * Signature: `clone(value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/clone
+ * 
+ * @namespace C
+ * 
+ */
 export declare function clone<T extends unknown = unknown>(unknownValue: T): SimplifyTypeForce<T>;

package/dist/common/clone.mjs

@@ -1,5 +1,8 @@
 import { entries } from '../object/entries.mjs';
 
+/**
+ * {@include common/clone/index.md}
+ */
 function clone(unknownValue) {
     if (!unknownValue) {
         return unknownValue;

package/dist/common/enum.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include common/createEnum/index.md}
+ */
 function createEnum(values) {
     return Object.fromEntries([
         ...values.map((value) => [value, value]),

package/dist/common/enum.d.ts

@@ -5,5 +5,39 @@ export type Enum<GenericValues extends [string, ...string[]] = [string, ...strin
     toTuple(): GenericValues;
     has(value: string): value is GenericValues[number];
 }>;
+/**
+ * The createEnum() function creates an immutable, typed string enum. The returned object exposes the keys/values, the has method, and toTuple.
+ * 
+ * Signature: `createEnum(values)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const enumValue = createEnum([
+ * 	"value1",
+ * 	"value2",
+ * 	"value3",
+ * ]);
+ * 
+ * type EnumValue = GetEnumValue<typeof enumValue>;
+ * 
+ * const tuple = enumValue.toTuple();
+ * 
+ * // type: ["value1", "value2", "value3"]
+ * 
+ * const maybe = true ? "value1" : "none";
+ * 
+ * if (enumValue.has(maybe)) {
+ * 	// type: "value1"
+ * } else {
+ * 	// type: "none"
+ * }
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/createEnum
+ * 
+ * @namespace C
+ * 
+ */
 export declare function createEnum<GenericValue extends string, GenericValues extends [GenericValue, ...GenericValue[]]>(values: GenericValues): Enum<GenericValues>;
 export type GetEnumValue<GenericEnum extends Enum<any>> = ReturnType<GenericEnum["toTuple"]>[number];

package/dist/common/enum.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include common/createEnum/index.md}
+ */
 function createEnum(values) {
     return Object.fromEntries([
         ...values.map((value) => [value, value]),

package/dist/common/equal.d.ts

@@ -7,6 +7,44 @@ type ExpectLiteral<GenericValue extends EligibleEqual> = Or<[
     UnionContain<GenericValue, bigint>,
     UnionContain<GenericValue, symbol>
 ]> extends true ? never : GenericValue;
+/**
+ * The equal() function compares a value to one or several literals. With primitives, it acts as a type guard and restricts the type to the provided values.
+ * 
+ * **Supported call styles:**
+ * - Classic: `equal(input, value)` → returns a value
+ * - Curried: `equal(value)` → returns a function waiting for the input
+ * - Classic predicate: `equal(input, value)` → narrows the input type
+ * - Curried predicate: `equal(value)` → narrows the input type
+ * 
+ * Predicate overloads (type guards) narrow the output type.
+ * 
+ * ```ts
+ * type Status = "pending" | "success" | "error";
+ * 
+ * const status = "success" as Status;
+ * 
+ * if (equal(status, [
+ * 	"success",
+ * 	"error",
+ * ])) {
+ * 	// type: "success" | "error"
+ * }
+ * 
+ * const result = pipe(
+ * 	status,
+ * 	when(
+ * 		equal("success"),
+ * 		() => "ok",
+ * 	),
+ * );
+ * // result: "ok"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/equal
+ * 
+ * @namespace C
+ * 
+ */
 export declare function equal<GenericInput extends EligibleEqual | object, GenericValue extends Exclude<GenericInput, object>>(value: ExpectLiteral<GenericValue> | ExpectLiteral<GenericValue>[]): (input: GenericInput) => input is NoInfer<GenericValue>;
 export declare function equal<GenericInput extends EligibleEqual | object, GenericValue extends Exclude<GenericInput, object>>(value: GenericValue | GenericValue[]): (input: GenericInput) => boolean;
 export declare function equal<GenericInput extends EligibleEqual | object, GenericValue extends Exclude<GenericInput, object>>(input: GenericInput, value: ExpectLiteral<GenericValue> | ExpectLiteral<GenericValue>[]): input is GenericValue;

package/dist/common/escapeRegExp.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include common/escapeRegExp/index.md}
+ */
 function escapeRegExp(input) {
     return input.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, "\\$&");
 }

package/dist/common/escapeRegExp.d.ts

@@ -1 +1,21 @@
+/**
+ * The escapeRegExp() function escapes special characters in a string so it can be reused in a regular expression without altering its meaning.
+ * 
+ * Signature: `escapeRegExp(value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const raw = "price (EUR) + taxes?";
+ * const escaped = escapeRegExp(raw);
+ * 
+ * const regex = new RegExp(escaped);
+ * // regex matches the literal string "price (EUR) + taxes?"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/escapeRegExp
+ * 
+ * @namespace C
+ * 
+ */
 export declare function escapeRegExp<GenericInput extends string>(input: GenericInput): string;

package/dist/common/escapeRegExp.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include common/escapeRegExp/index.md}
+ */
 function escapeRegExp(input) {
     return input.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, "\\$&");
 }

package/dist/common/externalPromise.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include common/externalPromise/index.md}
+ */
 function createExternalPromise() {
     let resolve = undefined;
     let reject = undefined;

package/dist/common/externalPromise.d.ts

@@ -1,3 +1,23 @@
+/**
+ * The createExternalPromise() function creates a promise controllable from the outside: it exposes resolve, reject, and the associated promise.
+ * 
+ * Signature: `createExternalPromise()` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const { promise, resolve } = createExternalPromise<number>();
+ * resolve(42);
+ * 
+ * const result = await promise;
+ * // result: 42
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/externalPromise
+ * 
+ * @namespace C
+ * 
+ */
 export declare function createExternalPromise<GenericPromiseValue extends unknown>(): {
     resolve: (_value: GenericPromiseValue | Awaited<GenericPromiseValue> | Promise<GenericPromiseValue>) => void;
     reject: (_value: unknown) => void;

package/dist/common/externalPromise.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include common/externalPromise/index.md}
+ */
 function createExternalPromise() {
     let resolve = undefined;
     let reject = undefined;

package/dist/common/falsy.cjs

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

package/dist/common/falsy.d.ts

@@ -1,2 +1,29 @@
 import { type FalsyValue, type UnionContain } from "./types";
+/**
+ * The falsy() function is a type guard that keeps only falsy values (false, 0, "", null, undefined).
+ * 
+ * Signature: `falsy(input)` → returns a value
+ * 
+ * Acts as a type guard and narrows the input type when true.
+ * 
+ * ```ts
+ * const values = [
+ * 	0,
+ * 	1,
+ * 	2,
+ * 	"",
+ * 	"toto",
+ * 	null,
+ * ] as const;
+ * 
+ * const result = A.filter(values, falsy);
+ * 
+ * // type: (0 | "" | null)[]
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/falsy
+ * 
+ * @namespace C
+ * 
+ */
 export declare function falsy<GenericInput extends unknown>(input: GenericInput): input is (Extract<GenericInput, FalsyValue> | (UnionContain<GenericInput, string> extends true ? "" : never) | (UnionContain<GenericInput, number> extends true ? 0 : never) | (UnionContain<GenericInput, bigint> extends true ? 0n : never));

package/dist/common/falsy.mjs

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

package/dist/common/forward.cjs

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

package/dist/common/forward.d.ts

@@ -1 +1,24 @@
+/**
+ * The forward() function returns the passed argument without modifying it. Useful to standardize an API that expects a function, or to improve readability in a pipeline.
+ * 
+ * Signature: `forward(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = {
+ * 	id: 1,
+ * 	name: "ZeRiix",
+ * };
+ * 
+ * const result = forward(input);
+ * 
+ * // type: { id: number; name: string; }
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/forward
+ * 
+ * @namespace C
+ * 
+ */
 export declare function forward<GenericValue extends unknown>(value: GenericValue): GenericValue;

package/dist/common/forward.mjs

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

package/dist/common/forwardLog.cjs

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

package/dist/common/forwardLog.d.ts

@@ -1 +1,29 @@
+/**
+ * The forwardLog() function logs the received value (side effect) then returns it unchanged, handy for inspecting a pipeline without breaking it.
+ * 
+ * Signature: `forwardLog(input)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const input = {
+ * 	id: 42,
+ * 	name: "Neo",
+ * };
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	forwardLog,
+ * 	({ name }) => `Hello ${name}!`,
+ * );
+ * 
+ * // logs: { id: 42, name: "Neo" }
+ * // result: "Hello Neo!"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/forwardLog
+ * 
+ * @namespace C
+ * 
+ */
 export declare function forwardLog<const GenericInput extends unknown>(input: GenericInput): GenericInput;

package/dist/common/forwardLog.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include common/forwardLog/index.md}
+ */
 function forwardLog(input) {
     console.log(input);
     return input;

package/dist/common/globalStore.cjs

@@ -4,6 +4,9 @@ const SymbolGlobalStore = Symbol.for("@duplojs/utils/global-store");
 const globalVar = Object;
 Object.defineProperty(globalVar, SymbolGlobalStore, { value: globalVar[SymbolGlobalStore] ?? {} });
 const store = globalVar[SymbolGlobalStore];
+/**
+ * {@include common/globalStore/index.md}
+ */
 function createGlobalStore(storeName, defaultValue) {
     if (store[storeName] === undefined) {
         store[storeName] = defaultValue;