Data Parser

Functions to build, compose, and run immutable validators. DataParser.* or DP.* describes the expected shape of data, returns an Either (parse / asyncParse), and produces structured errors ready to be serialized.

How to import?

The library exposes the DDataParser, DDataParserCoerce, and DDataParserExtended namespaces from the main entry or via direct import (tree-shaking friendly), which lets you only load what you need.

// DataParser
import { DDataParser, DP } from "@duplojs/utils";
import * as DDataParser from "@duplojs/utils/dataParser";
import * as DP from "@duplojs/utils/dataParser";

// DataParserCoerce
import { DDataParserCoerce, DPC } from "@duplojs/utils";
import * as DDataParserCoerce from "@duplojs/utils/dataParserCoerce";
import * as DPC from "@duplojs/utils/dataParserCoerce";

// DataParserExtended
import { DDataParserExtended, DPE } from "@duplojs/utils";
import * as DDataParserExtended from "@duplojs/utils/dataParserExtended";
import * as DPE from "@duplojs/utils/dataParserExtended";

Primitive parsers

string

Validates strings: min, max, regex, email, url checkers, with coercion support ("42" → normalized "42").

number

Validates numbers with min, max, int constraints and coercion support (Number(value)).

boolean

Validates booleans or converts them from common strings ("true", "1", etc.).

bigint

Validates bigint with dedicated min/max checkers, useful for high-precision identifiers.

date

Validates a TheDate, a native Date, or a timestamp before converting to TheDate.

time

Validates a TheTime with min, max checkers and coercion support.

literal

Enforces an exact output value ("admin", 42, true, etc.).

templateLiteral

Builds a parser from a TemplateLiteral pattern (e.g. order-${number}).

nil

Accepts only null and allows adding specific checkers.

empty

Validates absence of a value (undefined) in a schema.

unknown

Accepts any value while keeping the ability to add checkers/refine.

Composed structures

object

Declares an object structure, handles optional keys, static inference, and contextualized errors (path user.email).

array

Validates homogeneous arrays, with min, max, nonEmpty, etc. checkers.

tuple

Defines an ordered sequence of parsers with fixed or variable sizes.

record

Describes a key/value map with separate validation for keys and values.

union

Tries multiple parsers in order, returns the first that succeeds, and otherwise reports detailed errors.

Variants & optionality

optional

Allows undefined while keeping validation of the present value.

nullable

Allows null with native support for additional checkers.

lazy

Declares recursive schemas (e.g. trees, nested categories) thanks to a deferred function.

Pipelines & business logic

pipe

Composes multiple parsers to chain coercion, validation, transformation, and refinements.

transform

Transforms a parser result via a controlled function (e.g. string → URL).

refine

Adds custom rules (async/sync) with specific messages and metadata.

recover

Intercepts errors to return an alternative value (fallback) or trigger business logic.

Coercion

coerce.*

Placeholder space for coercive variants (coerce.string, coerce.number, coerce.boolean, coerce.date, etc.) when you must normalize data before strict validation.

Override & extensions

To change the default behavior of DataParser, add your own helpers, or build a library/extension on top of it, see the guide How to override DataParser methods?.