feat(94): add dataParser coercer

jsDoc/dataParser/classic/array/example.ts

@@ -7,9 +7,8 @@ if (E.isRight(result)) {
 	// value: string[]
 }
 
-const withCheckers = DP.array(DP.number(), {
-	checkers: [DP.checkerArrayMin(1), DP.checkerArrayMax(3)],
-});
+const withCheckers = DP.array(DP.number())
+	.addChecker(DP.checkerArrayMin(1), DP.checkerArrayMax(3));
 
 const nested = DP.array(DP.array(DP.boolean()));
 const nestedResult = nested.parse([[true, false]]);

jsDoc/dataParser/classic/array/index.md

@@ -7,7 +7,7 @@ Creates a data parser for arrays of a given element parser.
 Validates that the input is an array and validates each element with the provided parser.
 
 ```ts
-{@include dataParser/classic/array/example.ts[3,15]}
+{@include dataParser/classic/array/example.ts[3,14]}
 ```
 
 @see https://utils.duplojs.dev/en/v1/api/dataParser/array

jsDoc/dataParser/classic/base/clone/example.ts

@@ -8,5 +8,5 @@ const withMin = DP.string()
 
 const withMinClone = withMin.clone();
 
-const coerceNumber = DP.coerce.number();
+const coerceNumber = DP.coercer(DP.number());
 const coerceNumberClone = coerceNumber.clone();

jsDoc/dataParser/classic/base/parse/example.ts

@@ -8,16 +8,16 @@ if (E.isRight(result)) {
 	// value: string
 }
 
-const resultWithError = DP.string({
-	checkers: [DP.checkerStringMin(3)],
-}).parse("ok");
+const resultWithError = DP.string()
+	.addChecker(DP.checkerStringMin(3))
+	.parse("ok");
 
 if (E.isLeft(resultWithError)) {
 	const error = unwrap(resultWithError);
 	// error: DP.DataParserError
 }
 
-const numberSchema = DP.coerce.number();
+const numberSchema = DP.coercer(DP.number());
 const numberResult = numberSchema.parse("42");
 if (E.isRight(numberResult)) {
 	const value = unwrap(numberResult);

jsDoc/dataParser/classic/base/parseOrThrow/example.ts

@@ -1,8 +1,7 @@
 import { DP } from "@scripts";
 
-const stringSchema = DP.string({
-	checkers: [DP.checkerStringMin(3)],
-});
+const stringSchema = DP.string()
+	.addChecker(DP.checkerStringMin(3));
 
 const value = stringSchema.parseOrThrow("DuploJS");
 // value: string

jsDoc/dataParser/classic/base/parseOrThrow/index.md

@@ -6,7 +6,7 @@ The parseOrThrow() method runs a data parser synchronously and returns the parse
 It executes the parser, applies all registered checkers, and never mutates the input.
 
 ```ts
-{@include dataParser/classic/base/parseOrThrow/example.ts[3,23]}
+{@include dataParser/classic/base/parseOrThrow/example.ts[3,15]}
 ```
 
 @namespace DP

jsDoc/dataParser/classic/bigint/example.ts

@@ -7,9 +7,8 @@ if (E.isRight(result)) {
 	// value: bigint
 }
 
-const withCheckers = DP.bigint({
-	checkers: [DP.checkerBigIntMin(BigInt(1)), DP.checkerBigIntMax(BigInt(10))],
-});
+const withCheckers = DP.bigint()
+	.addChecker(DP.checkerBigIntMin(BigInt(1)), DP.checkerBigIntMax(BigInt(10)));
 
-const coerceParser = DP.coerce.bigint();
+const coerceParser = DP.coercer(DP.bigint());
 const coerceResult = coerceParser.parse("42");

jsDoc/dataParser/classic/bigint/index.md

@@ -7,7 +7,7 @@ Creates a data parser for bigint values.
 Validates that the input is a bigint, optionally applies coerce, and runs the configured checkers.
 
 ```ts
-{@include dataParser/classic/bigint/example.ts[3,15]}
+{@include dataParser/classic/bigint/example.ts[3,14]}
 ```
 
 @see https://utils.duplojs.dev/en/v1/api/dataParser/bigint

jsDoc/dataParser/classic/boolean/example.ts

@@ -7,9 +7,8 @@ if (E.isRight(result)) {
 	// value: boolean
 }
 
-const onlyTrue = DP.boolean({
-	checkers: [DP.checkerRefine((value) => value === true)],
-});
+const onlyTrue = DP.boolean()
+	.addChecker(DP.checkerRefine((value) => value === true));
 
-const coerceParser = DP.coerce.boolean();
+const coerceParser = DP.coercer(DP.boolean());
 const coerceResult = coerceParser.parse("false");

jsDoc/dataParser/classic/boolean/index.md

@@ -7,7 +7,7 @@ Creates a data parser for boolean values.
 Validates that the input is a boolean, optionally applies coerce, and runs the configured checkers.
 
 ```ts
-{@include dataParser/classic/boolean/example.ts[3,15]}
+{@include dataParser/classic/boolean/example.ts[3,14]}
 ```
 
 @see https://utils.duplojs.dev/en/v1/api/dataParser/boolean

jsDoc/dataParser/classic/checkerTimeMax/example.ts

@@ -1,8 +1,7 @@
 import { D, DP } from "@scripts";
 
-const parser = DP.time({
-	checkers: [DP.checkerTimeMax(D.createTime(2, "minute"))],
-});
+const parser = DP.time()
+	.addChecker(DP.checkerTimeMax(D.createTime(2, "minute")));
 
 const valid = parser.parse("time1500+");
 // valid: Error<DP.DataParserError> | Success<D.TheTime>

jsDoc/dataParser/classic/checkerTimeMax/index.md

@@ -5,7 +5,7 @@ Signature: `checkerTimeMax(max, definition?)` → `DataParserCheckerTimeMax`
 The checker passes when parsed value is less than or equal to `max`.
 
 ```ts
-{@include dataParser/classic/checkerTimeMax/example.ts[3,13]}
+{@include dataParser/classic/checkerTimeMax/example.ts[3,10]}
 ```
 
 @remarks

jsDoc/dataParser/classic/checkerTimeMin/example.ts

@@ -1,8 +1,7 @@
 import { D, DP } from "@scripts";
 
-const parser = DP.time({
-	checkers: [DP.checkerTimeMin(D.createTime(1, "minute"))],
-});
+const parser = DP.time()
+	.addChecker(DP.checkerTimeMin(D.createTime(1, "minute")));
 
 const valid = parser.parse("time1500+");
 // valid: Error<DP.DataParserError> | Success<D.TheTime>

jsDoc/dataParser/classic/checkerTimeMin/index.md

@@ -5,7 +5,7 @@ Signature: `checkerTimeMin(min, definition?)` → `DataParserCheckerTimeMin`
 The checker passes when parsed value is greater than or equal to `min`.
 
 ```ts
-{@include dataParser/classic/checkerTimeMin/example.ts[3,13]}
+{@include dataParser/classic/checkerTimeMin/example.ts[3,10]}
 ```
 
 @remarks

jsDoc/dataParser/classic/coercer/example.ts

@@ -0,0 +1,23 @@
+import { DP, E, unwrap } from "@scripts";
+
+const parser = DP.coercer(DP.number());
+const result = parser.parse("42");
+if (E.isRight(result)) {
+	const value = unwrap(result);
+	// value: number
+}
+
+const withCheckers = DP.coercer(
+	DP.string(),
+).addChecker(DP.checkerStringMin(3));
+
+const checkedResult = withCheckers.parse(42);
+
+const complex = DP.object({
+	name: DP.coercer(DP.string()),
+	age: DP.coercer(DP.number()),
+});
+const complexResult = complex.parse({
+	name: 123,
+	age: "42",
+});

jsDoc/dataParser/classic/coercer/index.md

@@ -0,0 +1,18 @@
+Creates a classic coercer parser around another DataParser.
+
+Signature: `DP.coercer(inner, definition?)` -> `DataParserCoercer`
+
+This parser does not represent a data type by itself. It represents a parsing action, like `DP.pipe(...)` or `DP.lazy(...)`: it receives an input, transforms it with the transformer registered for the inner parser kind, then gives the transformed value to the inner parser.
+
+```ts
+{@include dataParser/classic/coercer/example.ts[3,23]}
+```
+
+@remarks
+- Parsed output is always the output of the inner parser.
+- Accepted input is widened with the values supported by the inner parser coercion transformer.
+- If no transformer is registered for the inner parser kind, the coercer still runs the inner parser with the original value.
+
+@see https://utils.duplojs.dev/en/v1/api/dataParser/coercer
+
+@namespace DP

jsDoc/dataParser/classic/coercer/transformers/example.ts

@@ -0,0 +1,13 @@
+import { DP } from "@scripts";
+
+const numberTransformer = DP.DataParserCoercer.transformers.get(
+	DP.numberKind,
+);
+
+DP.DataParserCoercer.transformers.set(
+	DP.stringKind,
+	(value) => String(value),
+);
+
+const parser = DP.coercer(DP.string());
+const result = parser.parse(42);

jsDoc/dataParser/classic/coercer/transformers/index.md

@@ -0,0 +1,18 @@
+Defines the transformer map used by classic coercer parsers.
+
+Signature: `DP.DataParserCoercer.transformers` -> `Map<KindHandler, AnyFunction>`
+
+The map links a DataParser kind to the function that prepares raw input before the inner parser runs. This is what makes `DP.coercer(DP.number())` accept values like numeric strings while still returning the output of `DP.number()`.
+
+```ts
+{@include dataParser/classic/coercer/transformers/example.ts[3,13]}
+```
+
+@remarks
+- This property is the source of truth for the parser kinds that support coercion.
+- A coercer memoizes the transformer it resolves during its first parse.
+- Changing this map is an advanced extension point.
+
+@see https://utils.duplojs.dev/en/v1/api/dataParser/coercer
+
+@namespace DP

jsDoc/dataParser/classic/date/example.ts

@@ -7,12 +7,11 @@ if (E.isRight(result)) {
 	// value: TheDate
 }
 
-const withCheckers = DP.date({
-	checkers: [DP.checkerRefine((value) => value.getUTCFullYear() >= 2024)],
-});
+const withCheckers = DP.date()
+	.addChecker(DP.checkerRefine((value) => value.getUTCFullYear() >= 2024));
 const checked = withCheckers.parse("date1704067200000+");
 // checked: E.Error<DP.DataParserError> | E.Success<TheDate>
 
-const coerceParser = DP.coerce.date();
+const coerceParser = DP.coercer(DP.date());
 const coerceResult = coerceParser.parse("2024-01-01T00:00:00.000Z");
 // coerceResult: E.Error<DP.DataParserError> | E.Success<TheDate>

jsDoc/dataParser/classic/date/index.md

@@ -6,12 +6,12 @@ The parser accepts `TheDate`, `SerializedTheDate`, and native `Date`.
 With `coerce: true`, safe timestamps and parsable date strings are also supported.
 
 ```ts
-{@include dataParser/classic/date/example.ts[3,18]}
+{@include dataParser/classic/date/example.ts[3,17]}
 ```
 
 @remarks
 - Parsed output is always `TheDate`.
-- Use `DP.coerce.date()` when you want coercion enabled by default.
+- Use `DP.coercer(DP.date())` when you want coercion enabled by default.
 
 @see https://utils.duplojs.dev/en/v1/api/dataParser/date
 

jsDoc/dataParser/classic/empty/example.ts

@@ -6,9 +6,8 @@ if (E.isRight(result)) {
 	// E.Success<undefined>
 }
 
-const withCheckers = DP.empty({
-	checkers: [DP.checkerRefine((value) => value === undefined)],
-});
+const withCheckers = DP.empty()
+	.addChecker(DP.checkerRefine((value) => value === undefined));
 
-const coerceParser = DP.coerce.empty();
+const coerceParser = DP.coercer(DP.empty());
 const coerceResult = coerceParser.parse("undefined");

jsDoc/dataParser/classic/empty/index.md

@@ -7,7 +7,7 @@ Creates a data parser that accepts undefined.
 Accepts undefined (or the string "undefined" when coerce is enabled) and rejects other inputs.
 
 ```ts
-{@include dataParser/classic/empty/example.ts[3,14]}
+{@include dataParser/classic/empty/example.ts[3,13]}
 ```
 
 @see https://utils.duplojs.dev/en/v1/api/dataParser/empty

jsDoc/dataParser/classic/nil/example.ts

@@ -7,9 +7,8 @@ if (E.isRight(result)) {
 	// value: null
 }
 
-const withCheckers = DP.nil({
-	checkers: [DP.checkerRefine((value) => value === null)],
-});
+const withCheckers = DP.nil()
+	.addChecker(DP.checkerRefine((value) => value === null));
 
-const coerceParser = DP.coerce.nil();
+const coerceParser = DP.coercer(DP.nil());
 const coerceResult = coerceParser.parse("null");

jsDoc/dataParser/classic/nil/index.md

@@ -7,7 +7,7 @@ Creates a data parser that accepts null.
 Accepts null (or the string "null" when coerce is enabled) and rejects other inputs.
 
 ```ts
-{@include dataParser/classic/nil/example.ts[3,15]}
+{@include dataParser/classic/nil/example.ts[3,14]}
 ```
 
 @see https://utils.duplojs.dev/en/v1/api/dataParser/nil

jsDoc/dataParser/classic/nullable/example.ts

@@ -10,6 +10,5 @@ if (E.isRight(result)) {
 const withCoalescing = DP.nullable(DP.number(), { coalescingValue: 0 });
 const coalesced = withCoalescing.parse(null);
 
-const withCheckers = DP.nullable(DP.boolean(), {
-	checkers: [DP.checkerRefine((value) => value !== null)],
-});
+const withCheckers = DP.nullable(DP.boolean())
+	.addChecker(DP.checkerRefine((value) => value !== null));

jsDoc/dataParser/classic/nullable/index.md

@@ -7,7 +7,7 @@ Creates a data parser that accepts null or the inner parser output.
 Returns null (or a coalescing value) when input is null, otherwise parses with the inner parser.
 
 ```ts
-{@include dataParser/classic/nullable/example.ts[3,15]}
+{@include dataParser/classic/nullable/example.ts[3,14]}
 ```
 
 @see https://utils.duplojs.dev/en/v1/api/dataParser/nullable

jsDoc/dataParser/classic/number/example.ts

@@ -7,9 +7,8 @@ if (E.isRight(result)) {
 	// value: number
 }
 
-const withCheckers = DP.number({
-	checkers: [DP.checkerNumberMin(0), DP.checkerInt()],
-});
+const withCheckers = DP.number()
+	.addChecker(DP.checkerNumberMin(0), DP.checkerInt());
 
-const coerceParser = DP.coerce.number();
+const coerceParser = DP.coercer(DP.number());
 const coerceResult = coerceParser.parse("42");

jsDoc/dataParser/classic/number/index.md

@@ -7,7 +7,7 @@ Creates a data parser for numbers.
 Validates that the input is a finite number, optionally applies coerce, and runs the configured checkers. `NaN`, `Infinity`, and `-Infinity` are rejected.
 
 ```ts
-{@include dataParser/classic/number/example.ts[3,15]}
+{@include dataParser/classic/number/example.ts[3,14]}
 ```
 
 @see https://utils.duplojs.dev/en/v1/api/dataParser/number

jsDoc/dataParser/classic/optional/example.ts

@@ -10,6 +10,5 @@ if (E.isRight(result)) {
 const withCoalescing = DP.optional(DP.number(), { coalescingValue: 0 });
 const coalesced = withCoalescing.parse(undefined);
 
-const withCheckers = DP.optional(DP.number(), {
-	checkers: [DP.checkerRefine((value) => value !== 13)],
-});
+const withCheckers = DP.optional(DP.number())
+	.addChecker(DP.checkerRefine((value) => value !== 13));

jsDoc/dataParser/classic/optional/index.md

@@ -7,7 +7,7 @@ Creates a data parser that accepts undefined or the inner parser output.
 Returns undefined (or a coalescing value) when input is undefined, otherwise parses with the inner parser.
 
 ```ts
-{@include dataParser/classic/optional/example.ts[3,15]}
+{@include dataParser/classic/optional/example.ts[3,14]}
 ```
 
 @see https://utils.duplojs.dev/en/v1/api/dataParser/optional

jsDoc/dataParser/classic/pipe/example.ts

@@ -1,7 +1,7 @@
 import { DP, E, unwrap } from "@scripts";
 
 const schema = DP.pipe(
-	DP.coerce.number(),
+	DP.coercer(DP.number()),
 	DP.transform(
 		DP.number(),
 		(value) => value + 1,

jsDoc/dataParser/classic/record/example.ts

@@ -17,6 +17,5 @@ const strictResult = strictKeys.parse({
 	yPos: false,
 });
 
-const withCheckers = DP.record(DP.string(), DP.string(), {
-	checkers: [DP.checkerRefine((value) => Object.keys(value).length > 0)],
-});
+const withCheckers = DP.record(DP.string(), DP.string())
+	.addChecker(DP.checkerRefine((value) => Object.keys(value).length > 0));

jsDoc/dataParser/classic/record/index.md

@@ -7,7 +7,7 @@ Creates a data parser for records with key and value parsers.
 Validates that the input is an object and parses each key and value with the provided parsers.
 
 ```ts
-{@include dataParser/classic/record/example.ts[3,22]}
+{@include dataParser/classic/record/example.ts[3,21]}
 ```
 
 @see https://utils.duplojs.dev/en/v1/api/dataParser/record