Data Parser

Fonctions pour construire, composer et exécuter des validateurs immuables. DataParser.* ou DP.* décrit la forme attendue des données, renvoie un Either (parse / asyncParse) et produit des erreurs structurées prêtes à être sérialisées.

Comment faire les imports ?

La bibliothèque expose les namespaces DDataParser, DDataParserCoerce et DDataParserExtended depuis l'entrée principale ou en import direct (tree-shaking friendly), ce qui permet de ne charger que ce dont vous avez besoin.

// 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";

Contrat checker

Le contrat de checker est centré sur le type de sortie du parser : un checker est compatible si son type d'entrée correspond à Output<Parser>. Les checkers sont modélisés via ce contrat de compatibilité de type.

Certains checkers affinent aussi le type du parser. checkerRefine(...) resserre la sortie lorsque le prédicat est un type guard TypeScript, checkerEmail() resserre les chaînes vers un type template-literal d'email, et les checkers min/max des tableaux peuvent ajouter une information de tuple non vide et MaxElements<N> lorsque les bornes sont des nombres littéraux. Ces raffinements s'appliquent aux parsers classiques et étendus, puis se propagent aux contraintes Clean et aux NewTypes.

Parsers primitifs

string

Valide les chaînes : checkers min, max, regex, email, url, uuid, support de la coercition (42 → "42" normalisé).

number

Valide les nombres avec contraintes min, max, int et support de la coercition (Number(value)).

boolean

Valide les booléens ou les convertit depuis des chaînes courantes ("true", "1", etc.).

bigint

Valide les bigint avec checkers min/max dédiés, utile pour les identifiants haute précision.

date

Valide TheDate, SerializedTheDate et Date natif (avec coercition optionnelle des timestamps/chaînes) avant conversion vers TheDate.

time

Valide TheTime, SerializedTheTime et valeurs numériques sûres, avec checkers min/max et coercition optionnelle.

literal

Impose une valeur exacte ("admin", 42, true, etc.) en sortie.

templateLiteral

Construit un parser à partir d'un pattern TemplateLiteral (ex: order-${number}).

nil

N'accepte que null et permet d'ajouter des checkers spécifiques.

empty

Valide une absence de valeur (undefined) dans un schéma.

unknown

Accepte n'importe quelle valeur tout en conservant la possibilité d'ajouter des checkers/refine.

Structures composées

object

Déclare la structure d'un objet, gère les clés optionnelles, l'inférence statique et les erreurs contextualisées (chemin user.email).

array

Valide des tableaux homogènes, avec checkers min, max, nonEmpty, etc.

tuple

Définit une séquence ordonnée de parsers avec tailles fixes ou variables.

record

Décrit une map clé/valeur avec validation séparée sur les clés et sur les valeurs.

union

Essaie plusieurs parsers dans l'ordre, retourne le premier qui réussit et reporte les erreurs détaillées sinon.

Variants & optionnalité

optional

Autorise undefined tout en conservant la validation de la valeur présente.

nullable

Autorise null avec support natif des checkers additionnels.

lazy

Déclare des schémas récursifs (ex: arbres, catégories imbriquées) grâce à une fonction différée.

Pipelines & logique métier

pipe

Compose plusieurs parsers pour enchaîner coercition, validation, transformation et refinements.

transform

Transforme le résultat d'un parser via une fonction contrôlée (ex: string → URL).

refine

Ajoute des règles personnalisées (async/sync) avec messages et méta-données spécifiques.

recover

Intercepte les erreurs pour retourner une valeur alternative (fallback) ou lancer une logique métier.

errorHandler

Réassigne les messages d'issues après parsing, utile quand les messages utilisateur doivent être déclarés après le schéma.

Helpers d’exécution

isAsynchronous

Indique si un parser (ou ses parsers internes) nécessite une exécution async.

Coercition

coerce.*

Espace réservé aux variantes coercitives (coerce.string, coerce.number, coerce.boolean, coerce.date, etc.) lorsque vous devez normaliser les données avant validation stricte.