@duplojs/utils 1.4.32 → 1.4.34

package/dist/common/whenElse.d.ts

@@ -1,4 +1,46 @@
 import { type EscapeVoid, type AnyValue, type BreakGenericLink } from "./types";
+/**
+ * The whenElse() function offers two explicit branches: if the predicate is true, theFunction runs, otherwise elseFunction. Return types stay disjoint and preserved.
+ * 
+ * **Supported call styles:**
+ * - Classic: `whenElse(input, predicate, theFunction, elseFunction)` → returns a value
+ * - Curried: `whenElse(predicate, theFunction, elseFunction)` → returns a function waiting for the input
+ * - Classic predicate: `whenElse(input, predicate, theFunction, elseFunction)` → narrows the input type
+ * - Curried predicate: `whenElse(predicate, theFunction, elseFunction)` → narrows the input type
+ * 
+ * Predicate overloads (type guards) narrow the output type.
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * type Input = "success" | "error";
+ * 
+ * const input = "success" as Input;
+ * 
+ * const direct = whenElse(
+ * 	input,
+ * 	equal("success"),
+ * 	() => "ok",
+ * 	() => "fail",
+ * );
+ * // result: "ok"
+ * 
+ * const piped = pipe(
+ * 	input,
+ * 	whenElse(
+ * 		equal("success"),
+ * 		() => "ok",
+ * 		() => "fail",
+ * 	),
+ * );
+ * // result: "ok"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/whenElse
+ * 
+ * @namespace C
+ * 
+ */
 export declare function whenElse<GenericInput extends AnyValue, GenericPredicatedInput extends GenericInput, GenericOutput1 extends AnyValue | EscapeVoid, GenericOutput2 extends AnyValue | EscapeVoid>(predicate: (input: GenericInput) => input is GenericPredicatedInput, theFunction: (predicatedInput: GenericPredicatedInput) => GenericOutput1, elseFunction: (predicatedInput: Exclude<GenericInput, GenericPredicatedInput>) => GenericOutput2): (input: GenericInput) => BreakGenericLink<GenericOutput1> | BreakGenericLink<GenericOutput2>;
 export declare function whenElse<GenericInput extends AnyValue, GenericPredicatedInput extends GenericInput, GenericOutput1 extends AnyValue | EscapeVoid, GenericOutput2 extends AnyValue | EscapeVoid>(input: GenericInput, predicate: (input: GenericInput) => input is GenericPredicatedInput, theFunction: (predicatedInput: GenericPredicatedInput) => GenericOutput1, elseFunction: (predicatedInput: Exclude<GenericInput, GenericPredicatedInput>) => GenericOutput2): GenericOutput1 | GenericOutput2;
 export declare function whenElse<GenericInput extends AnyValue, GenericOutput1 extends AnyValue | EscapeVoid, GenericOutput2 extends AnyValue | EscapeVoid>(predicate: (input: GenericInput) => boolean, theFunction: (predicatedInput: GenericInput) => GenericOutput1, elseFunction: (predicatedInput: GenericInput) => GenericOutput2): (input: GenericInput) => GenericOutput1 | GenericOutput2;

package/dist/common/whenNot.d.ts

@@ -1,4 +1,44 @@
 import { type EscapeVoid, type AnyValue, type BreakGenericLink } from "./types";
+/**
+ * The whenNot() function applies a transformation only when the predicate fails (or when the type guard does not match). Otherwise, the input is returned as is. Exists in immediate and curried versions.
+ * 
+ * **Supported call styles:**
+ * - Classic: `whenNot(input, predicate, theFunction)` → returns a value
+ * - Curried: `whenNot(predicate, theFunction)` → returns a function waiting for the input
+ * - Classic predicate: `whenNot(input, predicate, theFunction)` → narrows the input type
+ * - Curried predicate: `whenNot(predicate, theFunction)` → narrows the input type
+ * 
+ * Predicate overloads (type guards) narrow the output type.
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * type Input = "success" | "error";
+ * 
+ * const input = "error" as Input;
+ * 
+ * const direct = whenNot(
+ * 	input,
+ * 	equal("success"),
+ * 	() => "retry",
+ * );
+ * // result: "retry"
+ * 
+ * const piped = pipe(
+ * 	input,
+ * 	whenNot(
+ * 		equal("success"),
+ * 		() => "retry",
+ * 	),
+ * );
+ * // result: "retry"
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/whenNot
+ * 
+ * @namespace C
+ * 
+ */
 export declare function whenNot<GenericInput extends AnyValue, GenericPredicatedInput extends GenericInput, GenericOutput extends AnyValue | EscapeVoid>(ifFunction: (input: GenericInput) => input is GenericPredicatedInput, theFunction: (predicatedInput: Exclude<GenericInput, GenericPredicatedInput>) => GenericOutput): (input: GenericInput) => GenericOutput | BreakGenericLink<GenericPredicatedInput>;
 export declare function whenNot<GenericInput extends AnyValue, GenericPredicatedInput extends GenericInput, GenericOutput extends AnyValue | EscapeVoid>(input: GenericInput, ifFunction: (input: GenericInput) => input is GenericPredicatedInput, theFunction: (predicatedInput: Exclude<GenericInput, GenericPredicatedInput>) => GenericOutput): GenericOutput | GenericPredicatedInput;
 export declare function whenNot<GenericInput extends AnyValue, GenericOutput extends AnyValue | EscapeVoid>(ifFunction: (input: GenericInput) => boolean, theFunction: (predicatedInput: GenericInput) => GenericOutput): (input: GenericInput) => GenericOutput | GenericInput;

package/dist/common/wrapValue.cjs

@@ -1,14 +1,23 @@
 'use strict';
 
 const keyWrappedValue = "@duplojs/utils/value";
+/**
+ * {@include common/wrapValue/index.md}
+ */
 function wrapValue(value) {
     return {
         [keyWrappedValue]: value,
     };
 }
+/**
+ * {@include common/isWrappedValue/index.md}
+ */
 function isWrappedValue(input) {
     return !!input && typeof input === "object" && keyWrappedValue in input;
 }
+/**
+ * {@include common/isRuntimeWrappedValueKey/index.md}
+ */
 function isRuntimeWrappedValueKey(value) {
     return value.startsWith(keyWrappedValue);
 }

package/dist/common/wrapValue.d.ts

@@ -4,7 +4,62 @@ export declare const keyWrappedValue = "@duplojs/utils/value";
 export interface WrappedValue<GenericValue extends unknown = unknown> {
     [SymbolWrappedValue]: GenericValue;
 }
+/**
+ * The wrapValue() function wraps a value in a marked container (SymbolWrappedValue) to identify it unambiguously in composite structures.
+ * 
+ * Signature: `wrapValue(value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const result = wrapValue({ id: 1 });
+ * 
+ * // type: WrappedValue<{ readonly id: 1 }>
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/wrapValue
+ * 
+ * @namespace C
+ * 
+ */
 export declare function wrapValue<const GenericValue extends unknown>(value: GenericValue): WrappedValue<GenericValue>;
+/**
+ * The isWrappedValue() function is a type guard that checks whether a value is a WrappedValue created via wrapValue/toWrappedValue.
+ * 
+ * Signature: `isWrappedValue(input)` → returns a value
+ * 
+ * Acts as a type guard and narrows the input type when true.
+ * 
+ * ```ts
+ * const maybe = true ? wrapValue(123) : null;
+ * 
+ * if (isWrappedValue(maybe)) {
+ * 	// type: WrappedValue<123>
+ * }
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/isWrappedValue
+ * 
+ * @namespace C
+ * 
+ */
 export declare function isWrappedValue<GenericInput extends unknown>(input: GenericInput): input is Extract<GenericInput, WrappedValue<any>>;
+/**
+ * The isRuntimeWrappedValueKey() function checks whether a string key matches the runtime marker of a WrappedValue (@duplojs/utils/value).
+ * 
+ * Signature: `isRuntimeWrappedValueKey(value)` → returns a value
+ * 
+ * The input value is not mutated.
+ * 
+ * ```ts
+ * const matches = isRuntimeWrappedValueKey(keyWrappedValue);
+ * // matches: true
+ * ```
+ * 
+ * @see https://utils.duplojs.dev/en/v1/api/common/isRuntimeWrappedValueKey
+ * 
+ * @namespace C
+ * 
+ */
 export declare function isRuntimeWrappedValueKey(value: string): boolean;
 export {};

package/dist/common/wrapValue.mjs

@@ -1,12 +1,21 @@
 const keyWrappedValue = "@duplojs/utils/value";
+/**
+ * {@include common/wrapValue/index.md}
+ */
 function wrapValue(value) {
     return {
         [keyWrappedValue]: value,
     };
 }
+/**
+ * {@include common/isWrappedValue/index.md}
+ */
 function isWrappedValue(input) {
     return !!input && typeof input === "object" && keyWrappedValue in input;
 }
+/**
+ * {@include common/isRuntimeWrappedValueKey/index.md}
+ */
 function isRuntimeWrappedValueKey(value) {
     return value.startsWith(keyWrappedValue);
 }

package/dist/dataParser/base.cjs

@@ -129,7 +129,6 @@ function dataParserInit(kind, definition, exec) {
             checkers: [...definition.checkers, ...checkers],
         }), exec),
         clone: () => dataParserInit(kind, simpleClone.simpleClone(definition), exec),
-        construct: (definition) => dataParserInit(kind, definition, exec),
     }, (value) => dataParserKind.setTo(value, null), kind.setTo, dataParserInit.overrideHandler.apply);
     return dataParser;
 }

package/dist/dataParser/base.d.ts

@@ -29,14 +29,114 @@ export interface DataParser<GenericDefinition extends DataParserDefinition = Dat
     readonly definition: GenericDefinition;
     exec(data: unknown, error: DataParserError): GenericOutput | SymbolDataParserError;
     asyncExec(data: unknown, error: DataParserError): Promise<GenericOutput | SymbolDataParserError>;
+    /**
+     * The parse() method runs a data parser synchronously and returns an Either with the parsed value or a DataParserError.
+     * 
+     * **Supported call styles:**
+     * - Method: `dataParser.parse(input)` -> returns an `Either`
+     * 
+     * It executes the parser, applies all registered checkers, and never mutates the input.
+     * 
+     * ```ts
+     * const stringSchema = DP.string();
+     * 
+     * const result = stringSchema.parse("DuploJS");
+     * if (E.isRight(result)) {
+     * 	const value = unwrap(result);
+     * 	// value: string
+     * }
+     * 
+     * const resultWithError = DP.string({
+     * 	checkers: [DP.checkerStringMin(3)],
+     * }).parse("ok");
+     * 
+     * if (E.isLeft(resultWithError)) {
+     * 	const error = unwrap(resultWithError);
+     * 	// error: DP.DataParserError
+     * }
+     * 
+     * const numberSchema = DP.coerce.number();
+     * const numberResult = numberSchema.parse("42");
+     * if (E.isRight(numberResult)) {
+     * 	const value = unwrap(numberResult);
+     * 	// value: number
+     * }
+     * ```
+     * 
+     * @namespace DP
+     * 
+     */
     parse(data: unknown): DEither.EitherSuccess<GenericOutput> | DEither.EitherError<DataParserError>;
+    /**
+     * The asyncParse() method runs a data parser asynchronously and resolves to an Either with the parsed value or a DataParserError.
+     * 
+     * **Supported call styles:**
+     * - Method: `dataParser.asyncParse(input)` -> returns a promise
+     * 
+     * It executes the async parser path, applies all registered checkers, and never mutates the input.
+     * 
+     * ```ts
+     * // TODO: add asyncParse examples.
+     * ```
+     * 
+     * @remarks 
+     * - TODO: complete this documentation and examples.
+     * 
+     * @namespace DP
+     * 
+     */
     asyncParse(data: unknown): Promise<DEither.EitherSuccess<GenericOutput> | DEither.EitherError<DataParserError>>;
+    /**
+     * The addChecker() method returns a new data parser with one or more additional checkers appended.
+     * 
+     * **Supported call styles:**
+     * - Method: `dataParser.addChecker(checker1, checker2)` -> returns a new parser
+     * 
+     * Checkers are executed after the parser core logic, and the original parser is not mutated.
+     * 
+     * ```ts
+     * const withMin = DP.string()
+     * 	.addChecker(DP.checkerStringMin(3));
+     * 
+     * const withRange = DP.string()
+     * 	.addChecker(
+     * 		DP.checkerStringMin(3),
+     * 		DP.checkerStringMax(10),
+     * 	);
+     * 
+     * const withRefine = DP.string()
+     * 	.addChecker(DP.checkerRefine((value) => value.startsWith("id:")));
+     * ```
+     * 
+     * @namespace DP
+     * 
+     */
     addChecker(...args: never): DataParser;
-    clone(): this;
     /**
-     * @deprecated Method with unreliable typing.
+     * The clone() method creates a new data parser instance with the same definition and checkers.
+     * 
+     * **Supported call styles:**
+     * - Method: `dataParser.clone()` -> returns a new parser
+     * 
+     * The original parser is not mutated, and the clone can be extended independently.
+     * 
+     * ```ts
+     * const base = DP.string();
+     * const cloned = base.clone();
+     * 
+     * const withMin = DP.string()
+     * 	.addChecker(DP.checkerStringMin(3));
+     * 
+     * const withMinClone = withMin.clone();
+     * 
+     * const coerceNumber = DP.coerce.number();
+     * const coerceNumberClone = coerceNumber.clone();
+     * ```
+     * 
+     * @namespace DP
+     * 
      */
-    construct(definition: never): DataParser;
+    clone(): this;
 }
 interface DataParserInitExecParams<GenericDataParser extends DataParser> {
     sync(...args: [...Parameters<GenericDataParser["exec"]>, self: GenericDataParser]): (GetKindValue<typeof dataParserKind, GenericDataParser>["output"] | SymbolDataParserErrorIssue | SymbolDataParserErrorPromiseIssue);

package/dist/dataParser/base.mjs

@@ -127,7 +127,6 @@ function dataParserInit(kind, definition, exec) {
             checkers: [...definition.checkers, ...checkers],
         }), exec),
         clone: () => dataParserInit(kind, simpleClone(definition), exec),
-        construct: (definition) => dataParserInit(kind, definition, exec),
     }, (value) => dataParserKind.setTo(value, null), kind.setTo, dataParserInit.overrideHandler.apply);
     return dataParser;
 }

package/dist/dataParser/baseExtended.cjs

@@ -59,9 +59,6 @@ function dataParserExtendedInit(dataParser, rest) {
         recover(recoveredValue, definition) {
             return recover.recover(self, recoveredValue, definition);
         },
-        construct(definition) {
-            return dataParserExtendedInit(dataParser.construct(definition), rest);
-        },
     }, extendedKind.setTo, dataParserExtendedInit.overrideHandler.apply);
     return self;
 }