@duplojs/utils 1.3.32 → 1.4.33

package/dist/common/globalStore.d.ts

@@ -4,4 +4,16 @@ export interface GlobalStoreHandler<GenericValue extends unknown> {
     readonly value: GenericValue;
     set(value: GenericValue): void;
 }
+/**
+ * The createGlobalStore() function lets you create a global store (singleton) shared across the entire process. It is useful for storing a mutable value accessible from any module without passing it as a parameter.
+ * 
+ * Signature: `createGlobalStore(storeName, defaultValue)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/globalStore
+ * 
+ * @namespace C
+ * 
+ */
 export declare function createGlobalStore<GenericStoreName extends keyof GlobalStore>(storeName: GenericStoreName, defaultValue: GlobalStore[GenericStoreName]): GlobalStoreHandler<GlobalStore[GenericStoreName]>;

package/dist/common/globalStore.mjs

@@ -2,6 +2,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;

package/dist/common/hasKinds.d.ts

@@ -1,4 +1,43 @@
 import { type Kind, type KindHandler } from "./kind";
 import { type AnyTuple, type UnionToIntersection } from "./types";
+/**
+ * The hasKinds() function checks that a value carries all requested kinds and acts as a type guard toward their intersection.
+ * 
+ * **Supported call styles:**
+ * - Classic: `hasKinds(input, kinds)` → returns a value
+ * - Curried: `hasKinds(kinds)` → returns a function waiting for the input
+ * - Classic predicate: `hasKinds(input, kinds)` → narrows the input type
+ * - Curried predicate: `hasKinds(kinds)` → narrows the input type
+ * 
+ * Predicate overloads (type guards) narrow the output type.
+ * 
+ * ```ts
+ * const input = E.ok() as E.EitherOk | E.EitherError;
+ * 
+ * if (hasKinds(input, [
+ * 	E.eitherOkKind,
+ * 	E.eitherRightKind,
+ * ])) {
+ * 	// type: E.EitherOk
+ * }
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	when(
+ * 		hasKinds([
+ * 			E.eitherOkKind,
+ * 			E.eitherRightKind,
+ * 		]),
+ * 		() => "ok",
+ * 	),
+ * );
+ * // result: "ok" | E.EitherError<unknown>
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/hasKinds
+ * 
+ * @namespace C
+ * 
+ */
 export declare function hasKinds<GenericInput extends unknown, const GenericKindHandlers extends AnyTuple<KindHandler>, GenericKindHandler extends GenericKindHandlers[number]>(kinds: GenericKindHandlers): (input: GenericInput) => input is Extract<GenericInput, UnionToIntersection<GenericKindHandler extends any ? Kind<GenericKindHandler["definition"]> : never>>;
 export declare function hasKinds<GenericInput extends unknown, const GenericKindHandlers extends AnyTuple<KindHandler>, GenericKindHandler extends GenericKindHandlers[number]>(input: GenericInput, kinds: GenericKindHandlers): input is Extract<GenericInput, UnionToIntersection<GenericKindHandler extends any ? Kind<GenericKindHandler["definition"]> : never>>;

package/dist/common/hasSomeKinds.d.ts

@@ -1,4 +1,43 @@
 import { type Kind, type KindHandler } from "./kind";
 import { type AnyTuple } from "./types";
+/**
+ * The hasSomeKinds() function checks that a value carries at least one of the requested kinds and acts as a type guard toward their union.
+ * 
+ * **Supported call styles:**
+ * - Classic: `hasSomeKinds(input, kinds)` → returns a value
+ * - Curried: `hasSomeKinds(kinds)` → returns a function waiting for the input
+ * - Classic predicate: `hasSomeKinds(input, kinds)` → narrows the input type
+ * - Curried predicate: `hasSomeKinds(kinds)` → narrows the input type
+ * 
+ * Predicate overloads (type guards) narrow the output type.
+ * 
+ * ```ts
+ * const input = E.ok() as E.EitherOk | E.EitherError;
+ * 
+ * if (hasSomeKinds(input, [
+ * 	E.eitherOkKind,
+ * 	E.eitherErrorKind,
+ * ])) {
+ * 	// type: E.EitherOk | E.EitherError
+ * }
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	when(
+ * 		hasSomeKinds([
+ * 			E.eitherOkKind,
+ * 			E.eitherErrorKind,
+ * 		]),
+ * 		() => "known",
+ * 	),
+ * );
+ * // result: "known" | E.EitherError<unknown>
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/hasSomeKinds
+ * 
+ * @namespace C
+ * 
+ */
 export declare function hasSomeKinds<GenericInput extends unknown, const GenericKindHandlers extends AnyTuple<KindHandler>, GenericKindHandler extends GenericKindHandlers[number]>(kinds: GenericKindHandlers): (input: GenericInput) => input is Extract<GenericInput, GenericKindHandler extends any ? Kind<GenericKindHandler["definition"]> : never>;
 export declare function hasSomeKinds<GenericInput extends unknown, const GenericKindHandlers extends AnyTuple<KindHandler>, GenericKindHandler extends GenericKindHandlers[number]>(input: GenericInput, kinds: GenericKindHandlers): input is Extract<GenericInput, GenericKindHandler extends any ? Kind<GenericKindHandler["definition"]> : never>;

package/dist/common/index.d.ts

@@ -1,3 +1,30 @@
+/**
+ * Cross-cutting utilities to compose functions, handle promises, manipulate wrappers/kinds, and apply runtime conversions shared by the whole library.
+ * 
+ * **How to import:**
+ * - From the main entry (namespace style or direct named imports)
+ * - Via direct import for tree-shaking
+ * 
+ * ```ts
+ * import { pipe, when, clone } from "@duplojs/utils";
+ * import * as DCommon from "@duplojs/utils/common";
+ * import * as C from "@duplojs/utils/common";
+ * import { pipe, when, clone } from "@duplojs/utils/common";
+ * ```
+ * 
+ * What you will find in this namespace:
+ * - composition helpers (`pipe`, `innerPipe`, `asyncPipe`, `asyncInnerPipe`, `forward`)
+ * - predicates and guards (`when`, `whenNot`, `whenElse`, `and`, `or`, `isType`, `instanceOf`)
+ * - control flow (`loop`, `asyncLoop`, `asyncRetry`, `sleep`, `memo`)
+ * - promise utilities (`externalPromise`, `promiseObject`)
+ * - string and value conversions (`toString`, `stringToMillisecond`, `stringToBytes`, `escapeRegExp`)
+ * - wrappers and kinds (`wrapValue`, `unwrap`, `toWrappedValue`, `hasKinds`, `hasSomeKinds`)
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common
+ * 
+ * @namespace C
+ * 
+ */
 export * from "./types";
 export * from "./addWrappedProperties";
 export * from "./asyncPipe";

package/dist/common/innerPipe.d.ts

@@ -1,5 +1,40 @@
 import { type BreakGenericLink, type EscapeVoid } from "./types";
 import { type AnyValue } from "./types/anyValue";
+/**
+ * The innerPipe() method prepares a reusable synchronous pipeline: it returns a function that will apply the chain of transformations to any compatible input.
+ * 
+ * Signature: `innerPipe(pipe1, pipe2)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const tvaRate = 1.2;
+ * const digit = 2;
+ * const input = [
+ * 	10,
+ * 	15,
+ * 	23,
+ * 	30.4,
+ * ];
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	A.map(
+ * 		innerPipe(
+ * 			N.multiply(tvaRate),
+ * 			N.toFixed(digit),
+ * 			S.concat("€"),
+ * 		),
+ * 	),
+ * );
+ * // result ["12€", "18€", "27.6€", "36.48€"]
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/innerPipe
+ * 
+ * @namespace C
+ * 
+ */
 export declare function innerPipe<GenericInput extends AnyValue, GenericOutputPipe1 extends AnyValue | EscapeVoid>(pipe1: (input: GenericInput) => GenericOutputPipe1): (input: GenericInput) => BreakGenericLink<GenericOutputPipe1>;
 export declare function innerPipe<GenericInput extends AnyValue, GenericOutputPipe1 extends AnyValue | EscapeVoid, GenericOutputPipe2 extends AnyValue | EscapeVoid>(pipe1: (input: GenericInput) => GenericOutputPipe1, pipe2: (input: GenericOutputPipe1) => GenericOutputPipe2): (input: GenericInput) => BreakGenericLink<GenericOutputPipe2>;
 export declare function innerPipe<GenericInput extends AnyValue, GenericOutputPipe1 extends AnyValue | EscapeVoid, GenericOutputPipe2 extends AnyValue | EscapeVoid, GenericOutputPipe3 extends AnyValue | EscapeVoid>(pipe1: (input: GenericInput) => GenericOutputPipe1, pipe2: (input: GenericOutputPipe1) => GenericOutputPipe2, pipe3: (input: GenericOutputPipe2) => GenericOutputPipe3): (input: GenericInput) => BreakGenericLink<GenericOutputPipe3>;

package/dist/common/instanceOf.d.ts

@@ -1,3 +1,36 @@
 import { type AnyConstructor } from "./types";
+/**
+ * The instanceOf() function creates a type guard based on one or several constructors. It checks instanceof while keeping precise typing.
+ * 
+ * **Supported call styles:**
+ * - Classic: `instanceOf(input, constructor)` → returns a value
+ * - Curried: `instanceOf(constructor)` → returns a function waiting for the input
+ * - Classic predicate: `instanceOf(input, constructor)` → narrows the input type
+ * - Curried predicate: `instanceOf(constructor)` → narrows the input type
+ * 
+ * Predicate overloads (type guards) narrow the output type.
+ * 
+ * ```ts
+ * const input = new Date();
+ * 
+ * if (instanceOf(input, Date)) {
+ * 	// type: Date
+ * }
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	when(
+ * 		instanceOf(Date),
+ * 		(value) => value.toISOString(),
+ * 	),
+ * );
+ * // result: "..."
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/instanceOf
+ * 
+ * @namespace C
+ * 
+ */
 export declare function instanceOf<GenericInput extends unknown, GenericConstructor extends AnyConstructor>(constructor: GenericConstructor | GenericConstructor[]): (input: GenericInput) => input is Extract<GenericInput, InstanceType<GenericConstructor>>;
 export declare function instanceOf<GenericInput extends unknown, GenericConstructor extends AnyConstructor>(input: GenericInput, constructor: GenericConstructor | GenericConstructor[]): input is Extract<GenericInput, InstanceType<GenericConstructor>>;

package/dist/common/isType.d.ts

@@ -17,6 +17,41 @@ type ComputeResult<GenericInput extends unknown, GenericTypeEntry extends Type[k
 type EligibleType<GenericInput extends unknown> = {
     [Prop in keyof Type]: IsEqual<ComputeResult<GenericInput, Type[Prop]>, never> extends true ? never : Prop;
 }[keyof Type];
+/**
+ * The isType() function creates a type guard based on typeof, Array.isArray, iterables, functions, etc. It allows narrowing a union to the checked type.
+ * 
+ * **Supported call styles:**
+ * - Classic: `isType(input, type)` → returns a value
+ * - Curried: `isType(type)` → returns a function waiting for the input
+ * - Classic predicate: `isType(input, type)` → narrows the input type
+ * - Curried predicate: `isType(type)` → narrows the input type
+ * 
+ * Predicate overloads (type guards) narrow the output type.
+ * 
+ * ```ts
+ * type Input = string | number;
+ * 
+ * const input = 3 as Input;
+ * 
+ * if (isType(input, "number")) {
+ * 	// type: number
+ * }
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	when(
+ * 		isType("number"),
+ * 		(value) => value + 1,
+ * 	),
+ * );
+ * // result: 4
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/isType
+ * 
+ * @namespace C
+ * 
+ */
 export declare function isType<GenericInput extends unknown, GenericType extends EligibleType<GenericInput>>(type: GenericType): (input: GenericInput) => input is ComputeResult<GenericInput, Type[GenericType]>;
 export declare function isType<GenericInput extends unknown, GenericType extends EligibleType<GenericInput>>(input: GenericInput, type: GenericType): input is ComputeResult<GenericInput, Type[GenericType]>;
 export {};

package/dist/common/justReturn.d.ts

@@ -1,3 +1,46 @@
 import { type AnyValue } from "./types";
+/**
+ * The justReturn() function builds a constant function: it ignores its argument and always returns the same value. It also exists in direct form to immediately return that value.
+ * 
+ * Signature: `justReturn(value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * type Input =
+ * 	| {
+ * 		kind: "ok";
+ * 		value: number;
+ * 	} | {
+ * 		kind: "healt";
+ * 		info: string;
+ * 	} | {
+ * 		kind: "error";
+ * 		message: string;
+ * 	};
+ * 
+ * const input = {
+ * 	kind: "ok",
+ * 	value: 4,
+ * } as Input;
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	P.match(
+ * 		{ kind: "ok" },
+ * 		O.getProperty("value"),
+ * 	),
+ * 	// whatever else happens, we return "error"
+ * 	P.otherwise(justReturn("error")),
+ * );
+ * 
+ * // type: number | "error"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/justReturn
+ * 
+ * @namespace C
+ * 
+ */
 export declare function justReturn<GenericInput extends unknown, GenericValue extends AnyValue>(value: GenericValue): (input: GenericInput) => GenericValue;
 export declare function justReturn<GenericInput extends unknown, GenericValue extends AnyValue>(input: GenericInput, value: GenericValue): GenericValue;

package/dist/common/kind.cjs

@@ -1,6 +1,9 @@
 'use strict';
 
 const keyKindPrefix = "@duplojs/utils/kind/";
+/**
+ * {@include common/kind/index.md}
+ */
 function createKind(name) {
     const runTimeKey = `${keyKindPrefix}${name}`;
     return {
@@ -29,6 +32,9 @@ function createKind(name) {
         },
     };
 }
+/**
+ * {@include common/kind/index.md}
+ */
 function createKindNamespace(namespace) {
     return (name) => {
         const kindHandler = createKind(`@${namespace}/${name}`);

package/dist/common/kind.d.ts

@@ -38,6 +38,53 @@ export type GetKindHandler<GenericObject extends Kind<any>> = {
 }[keyof GenericObject[SymbolKind]];
 export declare const keyKindPrefix = "@duplojs/utils/kind/";
 type ForbiddenKindCharacters<GenericValue extends string> = ForbiddenString<GenericValue, "@" | "/">;
+/**
+ * Kinds are a discrimination (type narrowing) mechanism based on adding a marker to an object, but with a few constraints we wanted in our projects:
+ * 
+ * Signature: `createKind(name)` and `createKindNamespace(namespace)` → returns a value
+ * 
+ * ```ts
+ * const userKind = createKind<"user", { id: string }>("user");
+ * 
+ * interface User extends Kind<typeof userKind.definition> {
+ * 	name: string;
+ * }
+ * 
+ * const User = {
+ * 	new(params: {
+ * 		id: string;
+ * 		name: string;
+ * 	}): User {
+ * 		return userKind.addTo(
+ * 			{ name: params.name },
+ * 			{ id: params.id },
+ * 		);
+ * 	},
+ * 	is(input: unknown): input is User {
+ * 		return userKind.has(input);
+ * 	},
+ * };
+ * 
+ * const user = User.new({
+ * 	id: "u_1",
+ * 	name: "Ada",
+ * });
+ * 
+ * if (User.is(user)) {
+ * 	const userId = userKind.getValue(user).id;
+ * }
+ * 
+ * const received: unknown = JSON.parse(JSON.stringify(user));
+ * if (User.is(received)) {
+ * 	const userId = userKind.getValue(received).id;
+ * }
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/kind
+ * 
+ * @namespace C
+ * 
+ */
 export declare function createKind<GenericName extends string, GenericKindValue extends unknown = unknown>(name: GenericName & ForbiddenKindCharacters<GenericName>): KindHandler<KindDefinition<GenericName, GenericKindValue>>;
 export interface ReservedKindNamespace {
     DuplojsUtilsEither: true;
@@ -47,6 +94,53 @@ export interface ReservedKindNamespace {
     DuplojsUtilsClean: true;
 }
 type ForbiddenKindNamespace<GenericValue extends string> = (ForbiddenKindCharacters<GenericValue> & ForbiddenString<GenericValue, GetPropsWithValue<ReservedKindNamespace, true>>);
+/**
+ * Kinds are a discrimination (type narrowing) mechanism based on adding a marker to an object, but with a few constraints we wanted in our projects:
+ * 
+ * Signature: `createKind(name)` and `createKindNamespace(namespace)` → returns a value
+ * 
+ * ```ts
+ * const userKind = createKind<"user", { id: string }>("user");
+ * 
+ * interface User extends Kind<typeof userKind.definition> {
+ * 	name: string;
+ * }
+ * 
+ * const User = {
+ * 	new(params: {
+ * 		id: string;
+ * 		name: string;
+ * 	}): User {
+ * 		return userKind.addTo(
+ * 			{ name: params.name },
+ * 			{ id: params.id },
+ * 		);
+ * 	},
+ * 	is(input: unknown): input is User {
+ * 		return userKind.has(input);
+ * 	},
+ * };
+ * 
+ * const user = User.new({
+ * 	id: "u_1",
+ * 	name: "Ada",
+ * });
+ * 
+ * if (User.is(user)) {
+ * 	const userId = userKind.getValue(user).id;
+ * }
+ * 
+ * const received: unknown = JSON.parse(JSON.stringify(user));
+ * if (User.is(received)) {
+ * 	const userId = userKind.getValue(received).id;
+ * }
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/kind
+ * 
+ * @namespace C
+ * 
+ */
 export declare function createKindNamespace<GenericNamespace extends string>(namespace: GenericNamespace & ForbiddenKindNamespace<GenericNamespace>): <GenericName extends string, GenericKindValue extends unknown = unknown>(name: GenericName & ForbiddenKindCharacters<GenericName>) => KindHandler<KindDefinition<`@${GenericNamespace}/${GenericName}`, GenericKindValue>>;
 export type KindHeritageConstructorParams<GenericKindHandler extends KindHandler> = {
     [KindHandler in GenericKindHandler as KindHandler["definition"]["name"]]: KindHandler["definition"]["value"];

package/dist/common/kind.mjs

@@ -1,4 +1,7 @@
 const keyKindPrefix = "@duplojs/utils/kind/";
+/**
+ * {@include common/kind/index.md}
+ */
 function createKind(name) {
     const runTimeKey = `${keyKindPrefix}${name}`;
     return {
@@ -27,6 +30,9 @@ function createKind(name) {
         },
     };
 }
+/**
+ * {@include common/kind/index.md}
+ */
 function createKindNamespace(namespace) {
     return (name) => {
         const kindHandler = createKind(`@${namespace}/${name}`);

package/dist/common/loop.cjs

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

package/dist/common/loop.d.ts

@@ -11,5 +11,31 @@ export interface LoopParams<GenericRawNextOutput extends any> {
     next<GenericValue extends GenericRawNextOutput | undefined = undefined>(output?: GenericValue): LoopOutputNextResult<GenericValue>;
     exit<GenericOutput extends AnyValue = undefined>(output?: GenericOutput): LoopOutputExistResult<GenericOutput>;
 }
+/**
+ * The loop() function runs a loop controlled via the next and exit callbacks. Each iteration receives the counter and the previous output to drive the flow.
+ * 
+ * Signature: `loop(from, theFunction)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const result = loop<number, number>(
+ * 	({ previousOutput, next, exit }) => {
+ * 		const current = (previousOutput ?? 0) + 1;
+ * 		if (current >= 5) {
+ * 			return exit(current);
+ * 		}
+ * 
+ * 		return next(current);
+ * 	},
+ * );
+ * // result: 5
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/loop
+ * 
+ * @namespace C
+ * 
+ */
 export declare function loop<GenericRawExitOutput extends AnyValue = undefined, GenericRawNextOutput extends AnyValue = undefined>(loop: (params: LoopParams<GenericRawNextOutput>) => LoopOutputNextResult<GenericRawNextOutput> | LoopOutputExistResult<GenericRawExitOutput>): GenericRawExitOutput;
 export {};

package/dist/common/loop.mjs

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

package/dist/common/memo.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+/**
+ * {@include common/memo/index.md}
+ */
 function memo(theFunction) {
     const payload = {
         get value() {

package/dist/common/memo.d.ts

@@ -2,4 +2,29 @@ import { type AnyValue } from "./types";
 export interface Memoized<GenericValue extends unknown> {
     readonly value: GenericValue;
 }
+/**
+ * The memo() function evaluates a function only once then memorizes the result. Subsequent calls return the same value without recalculation.
+ * 
+ * Signature: `memo(theFunction)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * let calls = 0;
+ * const expensive = memo(() => {
+ * 	calls += 1;
+ * 	return "cached";
+ * });
+ * 
+ * const first = expensive.value;
+ * // "cached", calls = 1
+ * const second = expensive.value;
+ * // "cached", calls = 1 (no recompute)
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/memo
+ * 
+ * @namespace C
+ * 
+ */
 export declare function memo<GenericOutput extends AnyValue>(theFunction: () => GenericOutput): Memoized<GenericOutput>;

package/dist/common/memo.mjs

@@ -1,3 +1,6 @@
+/**
+ * {@include common/memo/index.md}
+ */
 function memo(theFunction) {
     const payload = {
         get value() {

package/dist/common/or.d.ts

@@ -3,6 +3,47 @@ type ExtractPredicate<GenericPredicatedInput extends readonly AnyFunction<any[],
     (input: any, ...args: any[]) => input is infer InferredPredicate,
     ...infer InferredRest extends readonly AnyPredicate[]
 ] ? InferredRest extends readonly [] ? InferredPredicate : ExtractPredicate<InferredRest> extends infer InferredResult ? IsEqual<InferredResult, never> extends true ? never : InferredPredicate | InferredResult : never : never;
+/**
+ * The or() function combines several predicates or type guards: if at least one passes, the result is true and the type is narrowed to the union of accepted cases.
+ * 
+ * **Supported call styles:**
+ * - Classic: `or(input, predicates)` → returns a value
+ * - Curried: `or(predicates)` → returns a function waiting for the input
+ * - Classic predicate: `or(input, predicates)` → narrows the input type
+ * - Curried predicate: `or(predicates)` → narrows the input type
+ * 
+ * Predicate overloads (type guards) narrow the output type.
+ * 
+ * ```ts
+ * type Input = "click" | "hover" | "keydown";
+ * 
+ * const input = "hover" as Input;
+ * 
+ * if (or(input, [
+ * 	equal("click"),
+ * 	equal("hover"),
+ * ])) {
+ * 	// type: "click" | "hover"
+ * }
+ * 
+ * const result = pipe(
+ * 	input,
+ * 	when(
+ * 		or([
+ * 			equal("click"),
+ * 			equal("hover"),
+ * 		]),
+ * 		() => "handled",
+ * 	),
+ * );
+ * // result: "handled"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/or
+ * 
+ * @namespace C
+ * 
+ */
 export declare function or<GenericInput extends unknown, const GenericArrayPredicatedInput extends readonly [
     (input: GenericInput) => input is any,
     (input: GenericInput) => input is any,

package/dist/common/override.cjs

@@ -4,6 +4,9 @@ var globalStore = require('./globalStore.cjs');
 
 const SymbolOverrideStore = Symbol.for("@duplojs/utils/override");
 const overrideStore = globalStore.createGlobalStore(SymbolOverrideStore, {});
+/**
+ * {@include common/override/index.md}
+ */
 function createOverride(overrideName) {
     const overridePropertiesStore = overrideStore.value[overrideName] ?? {};
     overrideStore.value[overrideName] ||= overridePropertiesStore;

package/dist/common/override.d.ts

@@ -11,5 +11,50 @@ export interface OverrideHandler<GenericInterface extends object> {
     setPropertyDefaultValue<GenericProperty extends Exclude<keyof GenericInterface, DObject.GetPropsWithValueExtends<GenericInterface, AnyFunction>>>(prop: GenericProperty, value: Adaptor<GenericInterface[GenericProperty], AnyValue>): void;
     apply(overrideInterface: GenericInterface): GenericInterface;
 }
+/**
+ * The createOverride() function lets you register changes (default values and/or methods) that will be applied when creating an object.
+ * 
+ * Signature: `createOverride(overrideName)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * interface Service {
+ * 	readonly prefix: string;
+ * 	greet(name: string): string;
+ * }
+ * 
+ * function createService(prefix: string): Service {
+ * 	const self: Service = {
+ * 		prefix,
+ * 		greet: (name) => `${prefix} ${name}`,
+ * 	};
+ * 
+ * 	return createService.overrideHandler.apply(self);
+ * }
+ * 
+ * createService.overrideHandler = createOverride<Service>(
+ * 	"@duplojs/utils/docs/service",
+ * );
+ * 
+ * const base = createService("Hello");
+ * base.greet("Ada");
+ * // "Hello Ada"
+ * 
+ * // "Plugin": modifie ce qui sera appliqué à la création
+ * createService.overrideHandler.setPropertyDefaultValue("prefix", "Hi");
+ * createService.overrideHandler.setMethod("greet", (self, name) => `${self.prefix} ${name.toUpperCase()}`);
+ * 
+ * const overridden = createService("Hello");
+ * // prefix override + greet override
+ * overridden.greet("Ada");
+ * // "Hi ADA"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/override
+ * 
+ * @namespace C
+ * 
+ */
 export declare function createOverride<GenericInterface extends object>(overrideName: string): OverrideHandler<GenericInterface>;
 export {};