@duplojs/agents-kit 0.0.0-stage → 0.1.0-beta.6

package/docs/API/10-lang/10-path/10-is.ts

@@ -0,0 +1,46 @@
+/**
+ * @title DPath.is
+ *
+ * Vérifier qu’une chaîne respecte la syntaxe d’un chemin et affiner son type.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+declare const value: string;
+
+if (DPath.is(value)) {
+	type _CheckValue = DCommon.ExpectType<typeof value, string & DPath.Path, "strict">;
+	const extracted = DPath.getBaseName(value);
+	type _CheckExtracted = DCommon.ExpectType<typeof extracted, (string & DPath.Segment & DPath.Path) | null, "strict">;
+}
+
+const path = DPath.is("src/index.ts");
+// Le test runtime produit true.
+type _CheckPath = DCommon.ExpectType<typeof path, boolean, "strict">;
+
+const baseName = DCommon.pipe(
+	value,
+	DCommon.when(
+		DPath.is,
+		(validPath) => {
+			type _CheckValidPath = DCommon.ExpectType<typeof validPath, string & DPath.Path, "strict">;
+
+			return DPath.getBaseName(validPath);
+		},
+	),
+);
+// Un chemin valide donne son nom de base ; un chemin invalide reste la chaîne d’origine.
+type _CheckBaseName = DCommon.ExpectType<
+	typeof baseName,
+	string | (string & DPath.Segment & DPath.Path) | null,
+	"strict"
+>;
+
+// Sur un littéral déjà valide, le predicate conserve le type littéral sans ajouter de contrainte.
+const known = "src/index.ts";
+if (DPath.is(known)) {
+	type _CheckKnown = DCommon.ExpectType<typeof known, "src/index.ts", "strict">;
+	// Pour obtenir un chemin contraint depuis cette constante, utiliser sa déclaration sûre.
+	const declared = DPath.declarePath(known);
+	type _CheckDeclared = DCommon.ExpectType<typeof declared, "src/index.ts" & DPath.Path, "strict">;
+}

package/docs/API/10-lang/10-path/10-isAbsolute.ts

@@ -0,0 +1,46 @@
+/**
+ * @title DPath.isAbsolute
+ *
+ * Vérifier qu’une chaîne est un chemin absolu et affiner son type.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+declare const value: string;
+
+if (DPath.isAbsolute(value)) {
+	type _CheckValue = DCommon.ExpectType<typeof value, string & DPath.Absolute, "strict">;
+	const extracted = DPath.getParentFolderPath(value);
+	type _CheckExtracted = DCommon.ExpectType<typeof extracted, (string & DPath.Path & DPath.Absolute) | null, "strict">;
+}
+
+const path = DPath.isAbsolute("/workspace/src");
+// Le test runtime produit true.
+type _CheckPath = DCommon.ExpectType<typeof path, boolean, "strict">;
+
+const parent = DCommon.pipe(
+	value,
+	DCommon.when(
+		DPath.isAbsolute,
+		(absolutePath) => {
+			type _CheckAbsolutePath = DCommon.ExpectType<typeof absolutePath, string & DPath.Absolute, "strict">;
+
+			return DPath.getParentFolderPath(absolutePath);
+		},
+	),
+);
+// Un chemin absolu donne son dossier parent ; les autres chaînes restent inchangées.
+type _CheckParent = DCommon.ExpectType<
+	typeof parent,
+	string | (string & DPath.Path & DPath.Absolute) | null,
+	"strict"
+>;
+
+// Sur un littéral déjà valide, le predicate conserve le type littéral sans ajouter de contrainte.
+const known = "/workspace";
+if (DPath.isAbsolute(known)) {
+	type _CheckKnown = DCommon.ExpectType<typeof known, "/workspace", "strict">;
+	// Pour obtenir un chemin contraint depuis cette constante, utiliser sa déclaration sûre.
+	const declared = DPath.declareAbsolutePath(known);
+	type _CheckDeclared = DCommon.ExpectType<typeof declared, "/workspace" & DPath.Absolute & DPath.Path, "strict">;
+}

package/docs/API/10-lang/10-path/10-isSegment.ts

@@ -0,0 +1,42 @@
+/**
+ * @title DPath.isSegment
+ *
+ * Vérifier qu’une chaîne est un segment unique et affiner son type.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+declare const value: string;
+
+if (DPath.isSegment(value)) {
+	type _CheckValue = DCommon.ExpectType<typeof value, string & DPath.Segment, "strict">;
+	const extracted = DPath.concatSegment(DPath.declareSegment("file"), value);
+	type _CheckExtracted = DCommon.ExpectType<typeof extracted, string & DPath.Segment, "strict">;
+}
+
+const segment = DPath.isSegment(".ts");
+// Le test runtime produit true.
+type _CheckSegment = DCommon.ExpectType<typeof segment, boolean, "strict">;
+
+const fullPath = DCommon.pipe(
+	value,
+	DCommon.when(
+		DPath.isSegment,
+		(validSegment) => {
+			type _CheckValidSegment = DCommon.ExpectType<typeof validSegment, string & DPath.Segment, "strict">;
+
+			return DPath.concatSegment(DPath.declareSegment("file"), validSegment);
+		},
+	),
+);
+// Le segment est ajouté au nom de fichier ; une chaîne qui n’est pas un segment reste inchangée.
+type _CheckFullPath = DCommon.ExpectType<typeof fullPath, string | (string & DPath.Segment), "strict">;
+
+// Sur un littéral déjà valide, le predicate conserve le type littéral sans ajouter de contrainte.
+const known = "index.ts";
+if (DPath.isSegment(known)) {
+	type _CheckKnown = DCommon.ExpectType<typeof known, "index.ts", "strict">;
+	// Pour obtenir un chemin contraint depuis cette constante, utiliser sa déclaration sûre.
+	const declared = DPath.declareSegment(known);
+	type _CheckDeclared = DCommon.ExpectType<typeof declared, "index.ts" & DPath.Segment & DPath.Path, "strict">;
+}

package/docs/API/10-lang/10-path/10-normalize.ts

@@ -0,0 +1,26 @@
+/**
+ * @title DPath.normalize
+ *
+ * Réduire les séparateurs et les segments relatifs d’un chemin.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+const result = DPath.normalize("src//module/../index.ts");
+// La valeur obtenue est src/index.ts ; null signale une entrée invalide.
+type _CheckResult = DCommon.ExpectType<typeof result, (string & DPath.Path) | null, "strict">;
+
+// Une URL file locale est décodée en chemin Unix, sans lire le fichier.
+const fileUrl = DPath.normalize("file:///workspace/my%20file.ts");
+// La valeur obtenue est /workspace/my file.ts ; le type ne déduit pas Absolute.
+type _CheckFileUrl = DCommon.ExpectType<typeof fileUrl, (string & DPath.Path) | null, "strict">;
+
+// Une chaîne vide désigne le chemin courant après normalisation.
+const current = DPath.normalize("");
+// La valeur obtenue est ".".
+type _CheckCurrent = DCommon.ExpectType<typeof current, (string & DPath.Path) | null, "strict">;
+
+// Un caractère nul ou une URL file distante ne peut pas être normalisé.
+const rejected = DPath.normalize("file://remote-host/workspace/index.ts");
+// La valeur obtenue est null.
+type _CheckRejected = DCommon.ExpectType<typeof rejected, (string & DPath.Path) | null, "strict">;

package/docs/API/10-lang/10-path/10-resolveFrom.ts

@@ -0,0 +1,37 @@
+/**
+ * @title DPath.resolveFrom
+ *
+ * Résoudre des segments depuis une origine absolue, avec une option pour la conserver.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+const origin = DPath.declareAbsolutePath("/workspace");
+const result = DPath.resolveFrom(
+	origin,
+	[DPath.declarePath("src"), DPath.declarePath("index.ts")],
+	{ stayInOrigin: true },
+);
+// La valeur obtenue est /workspace/src/index.ts. Une résolution qui sort de l’origine vaut null.
+type _CheckResult = DCommon.ExpectType<typeof result, (string & DPath.Path & DPath.Absolute) | null, "strict">;
+
+// Option runtime : dès que stayInOrigin peut valoir true, le type inclut null.
+declare const stayInOrigin: boolean;
+const configured = DPath.resolveFrom(origin, [DPath.declarePath("../shared")], { stayInOrigin });
+// La valeur obtenue est null si le confinement est activé, sinon /shared.
+type _CheckConfigured = DCommon.ExpectType<typeof configured, (string & DPath.Path & DPath.Absolute) | null, "strict">;
+
+// Sans confinement, .. peut remonter au-dessus de l’origine ; le résultat reste absolu.
+const outside = DPath.resolveFrom(origin, [DPath.declarePath("../shared")]);
+// La valeur obtenue est /shared ; sans stayInOrigin, null ne fait pas partie du type.
+type _CheckOutside = DCommon.ExpectType<typeof outside, string & DPath.Path & DPath.Absolute, "strict">;
+
+// Confinement : refuser une remontée hors de l’origine.
+const rejected = DPath.resolveFrom(origin, [DPath.declarePath("../shared")], { stayInOrigin: true });
+// La valeur obtenue est null.
+type _CheckRejected = DCommon.ExpectType<typeof rejected, (string & DPath.Path & DPath.Absolute) | null, "strict">;
+
+// Une entrée absolue remplace l’origine sans confinement.
+const replacement = DPath.resolveFrom(origin, [DPath.declareAbsolutePath("/shared")]);
+// La valeur obtenue est /shared. Avec stayInOrigin: true, une entrée absolue est refusée.
+type _CheckReplacement = DCommon.ExpectType<typeof replacement, string & DPath.Path & DPath.Absolute, "strict">;

package/docs/API/10-lang/10-path/10-resolveRelative.ts

@@ -0,0 +1,23 @@
+/**
+ * @title DPath.resolveRelative
+ *
+ * Résoudre une suite de chemins relatifs ou absolus en un seul chemin normalisé.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+const result = DPath.resolveRelative([
+	DPath.declarePath("src"),
+	DPath.declarePath("index.ts"),
+]);
+// La valeur obtenue est src/index.ts.
+type _CheckResult = DCommon.ExpectType<typeof result, string & DPath.Path, "strict">;
+
+// Un chemin absolu remplace tout ce qui a été assemblé avant lui.
+const absolute = DPath.resolveRelative([
+	DPath.declarePath("ignored"),
+	DPath.declareAbsolutePath("/workspace"),
+	DPath.declarePath("src/index.ts"),
+]);
+// La valeur obtenue est /workspace/src/index.ts ; l’entrée absolue établit Absolute.
+type _CheckAbsolute = DCommon.ExpectType<typeof absolute, string & DPath.Path & DPath.Absolute, "strict">;

package/docs/API/10-lang/10-path/index.llms.md

@@ -0,0 +1,88 @@
+## DPath
+
+Chemins Unix typés : déclarer des littéraux, valider et normaliser des chaînes runtime, extraire des segments, résoudre des chemins ou sélectionner des motifs glob, indépendamment du système de fichiers.
+
+### [DPath.computeRelative](10-computeRelative.ts)
+
+Calculer le chemin relatif entre deux chemins absolus.
+ 
+### [DPath.concatSegment](10-concatSegment.ts)
+
+Assembler un segment avec un ou plusieurs autres segments.
+ 
+### [DPath.create](10-create.ts)
+
+Normaliser une chaîne et retourner un Either selon qu’elle forme un chemin valide.
+ 
+### [DPath.createAbsolute](10-createAbsolute.ts)
+
+Normaliser une chaîne et vérifier qu’elle représente un chemin absolu.
+ 
+### [DPath.createAbsoluteOrThrow](10-createAbsoluteOrThrow.ts)
+
+Normaliser un chemin absolu ou lever une erreur si l’entrée est invalide.
+ 
+### [DPath.createMatcher](10-createMatcher.ts)
+
+Créer un predicate de chemin à partir de motifs glob positifs et négatifs.
+ 
+### [DPath.createOrThrow](10-createOrThrow.ts)
+
+Normaliser un chemin ou lever une erreur si l’entrée est invalide.
+ 
+### [DPath.createSegment](10-createSegment.ts)
+
+Normaliser une chaîne et vérifier qu’elle ne contient qu’un segment.
+ 
+### [DPath.createSegmentOrThrow](10-createSegmentOrThrow.ts)
+
+Normaliser un segment ou lever une erreur si l’entrée n’est pas un segment valide.
+ 
+### [DPath.declareAbsolutePath](10-declareAbsolutePath.ts)
+
+Déclarer un littéral de chemin comme chemin absolu après vérification statique.
+ 
+### [DPath.declarePath](10-declarePath.ts)
+
+Déclarer un littéral valide comme chemin après vérification statique.
+ 
+### [DPath.declareSegment](10-declareSegment.ts)
+
+Déclarer un littéral valide comme segment après vérification statique.
+ 
+### [DPath.getBaseName](10-getBaseName.ts)
+
+Lire le dernier segment d’un chemin, avec la possibilité d’en retirer l’extension.
+ 
+### [DPath.getExtensionName](10-getExtensionName.ts)
+
+Lire l’extension du dernier segment, avec la possibilité de conserver le point.
+ 
+### [DPath.getParentFolderPath](10-getParentFolderPath.ts)
+
+Lire le dossier parent d’un chemin en conservant son caractère absolu lorsqu’il est connu.
+ 
+### [DPath.is](10-is.ts)
+
+Vérifier qu’une chaîne respecte la syntaxe d’un chemin et affiner son type.
+ 
+### [DPath.isAbsolute](10-isAbsolute.ts)
+
+Vérifier qu’une chaîne est un chemin absolu et affiner son type.
+ 
+### [DPath.isSegment](10-isSegment.ts)
+
+Vérifier qu’une chaîne est un segment unique et affiner son type.
+ 
+### [DPath.normalize](10-normalize.ts)
+
+Réduire les séparateurs et les segments relatifs d’un chemin.
+ 
+### [DPath.resolveFrom](10-resolveFrom.ts)
+
+Résoudre des segments depuis une origine absolue, avec une option pour la conserver.
+ 
+### [DPath.resolveRelative](10-resolveRelative.ts)
+
+Résoudre une suite de chemins relatifs ou absolus en un seul chemin normalisé.
+ 

package/docs/API/10-lang/10-path/index.md

@@ -0,0 +1,3 @@
+## DPath
+
+Chemins Unix typés : déclarer des littéraux, valider et normaliser des chaînes runtime, extraire des segments, résoudre des chemins ou sélectionner des motifs glob, indépendamment du système de fichiers.

package/docs/API/10-lang/10-pattern/10-exhaustive.ts

@@ -0,0 +1,26 @@
+/**
+ * @title DPattern.exhaustive
+ *
+ * Terminer un traitement exhaustif en extrayant les valeurs des PatternResult.
+ */
+import * as DPattern from "@duplojs/lang/pattern";
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+import * as DNumber from "@duplojs/lang/number";
+
+// exhaustive n’accepte que des PatternResult : tous les cas doivent déjà être traités.
+declare const input: string | number;
+const value = DCommon.pipe(
+	input,
+	DPattern.when(
+		DCommon.isType("string"),
+		DString.toUpperCase,
+	),
+	DPattern.when(
+		DCommon.isType("number"),
+		(number) => DNumber.sum([number, 1]),
+	),
+	DPattern.exhaustive,
+);
+// Une chaîne donne sa version majuscule ; un nombre est augmenté de 1.
+type _CheckValue = DCommon.ExpectType<typeof value, Uppercase<string> | number, "strict">;

package/docs/API/10-lang/10-pattern/10-isMatch.ts

@@ -0,0 +1,72 @@
+/**
+ * @title DPattern.isMatch
+ *
+ * Vérifier un motif sur une valeur et affiner le type de la partie correspondante.
+ */
+import * as DPattern from "@duplojs/lang/pattern";
+import * as DCommon from "@duplojs/lang/common";
+import * as DObject from "@duplojs/lang/object";
+import * as DString from "@duplojs/lang/string";
+
+interface TextInput {
+	kind: "text";
+	value: string;
+}
+interface CountInput {
+	kind: "count";
+	value: number;
+}
+type Input = TextInput | CountInput;
+declare const input: Input;
+
+if (DPattern.isMatch(input, { kind: "text" })) {
+	type _CheckInput = DCommon.ExpectType<typeof input, TextInput, "strict">;
+	const text = DObject.getProperty(input, "value");
+	type _CheckText = DCommon.ExpectType<typeof text, string, "strict">;
+}
+
+// En pipe, DCommon.when reçoit le predicate curifié et laisse passer les cas non correspondants.
+const selected = DCommon.pipe(
+	input,
+	DCommon.when(
+		DPattern.isMatch({ kind: "count" }),
+		(value) => {
+			type _CheckCount = DCommon.ExpectType<typeof value, CountInput, "strict">;
+			return DObject.getProperty(value, "value");
+		},
+	),
+);
+// Le callback retourne le compte ; la variante text traverse le pipe sans être transformée.
+type _CheckSelected = DCommon.ExpectType<typeof selected, number | {
+	kind: "text";
+	value: string;
+}, "strict">;
+
+// Littéral : la branche prend la valeur exacte du motif.
+declare const status: "ready" | "pending";
+if (DPattern.isMatch(status, "ready")) {
+	type _CheckStatus = DCommon.ExpectType<typeof status, "ready", "strict">;
+	const label = DString.toUpperCase(status);
+	// La valeur obtenue est "READY".
+	type _CheckLabel = DCommon.ExpectType<typeof label, "READY", "strict">;
+}
+
+// Motif imbriqué avec predicate : seules les propriétés demandées sont testées.
+declare const packet: {
+	data: { value: string | number };
+	id: string;
+};
+if (DPattern.isMatch(packet, { data: { value: DCommon.isType("string") } })) {
+	type _CheckPacket = DCommon.ExpectType<typeof packet, {
+		data: { value: string };
+		id: string;
+	}, "strict">;
+	const text = DString.toUpperCase(packet.data.value);
+	// La sortie est la valeur imbriquée convertie en majuscules.
+	type _CheckText = DCommon.ExpectType<typeof text, Uppercase<string>, "strict">;
+}
+
+// Un motif tableau vérifie son préfixe et autorise des éléments supplémentaires.
+const prefix = DPattern.isMatch(["text", "hello"], ["text"]);
+// La valeur obtenue est true ; [] correspondrait à tout tableau, même non vide.
+type _CheckPrefix = DCommon.ExpectType<typeof prefix, boolean, "strict">;

package/docs/API/10-lang/10-pattern/10-match.ts

@@ -0,0 +1,133 @@
+/**
+ * @title DPattern.match
+ *
+ * Traiter une valeur selon un motif et conserver les cas qui ne correspondent pas.
+ */
+import * as DPattern from "@duplojs/lang/pattern";
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+import * as DNumber from "@duplojs/lang/number";
+
+type Input = {
+	status: "created";
+	id: number;
+} | {
+	status: "deleted";
+	id: number;
+	reason: string;
+};
+declare const input: Input;
+
+// Appel curifié : les étapes suivantes ignorent une branche déjà enveloppée.
+const piped = DCommon.pipe(
+	input,
+	DPattern.match(
+		{ status: "created" },
+		(value) => value.id,
+	),
+	DPattern.match(
+		{ status: "deleted" },
+		(value) => value.reason,
+	),
+	DPattern.exhaustive,
+);
+// La sortie est l’id créé ou la raison de suppression, sans wrapper.
+type _CheckPiped = DCommon.ExpectType<typeof piped, number | string, "strict">;
+
+// Le builder retire chaque branche traitée du domaine restant, puis exige son épuisement.
+const built = DPattern.match(input)
+	.with({ status: "created" }, (value) => value.id)
+	.with({ status: "deleted" }, (value) => value.reason)
+	.exhaustive();
+// Après couverture des deux variantes, exhaustive retourne directement number | string.
+type _CheckBuilt = DCommon.ExpectType<typeof built, number | string, "strict">;
+
+// Builder avec repli : seule la première branche correspondante est exécutée.
+const withFallback = DPattern.match(input)
+	.with({ status: "created" }, (value) => value.id)
+	.otherwise((remaining) => {
+		type _CheckRemaining = DCommon.ExpectType<typeof remaining, {
+			status: "deleted";
+			id: number;
+			reason: string;
+		}, "strict">;
+		return remaining.reason;
+	});
+// Même sortie, mais otherwise couvre explicitement le cas restant.
+type _CheckWithFallback = DCommon.ExpectType<typeof withFallback, number | string, "strict">;
+
+// Tableau imbriqué : le motif décrit un préfixe, pas une longueur exacte.
+declare const packet: { items: ["text", string] | ["count", number] };
+const nested = DCommon.pipe(
+	packet,
+	DPattern.match(
+		{ items: ["text"] },
+		(value) => {
+			type _CheckValue = DCommon.ExpectType<typeof value, { items: ["text", string] }, "strict">;
+			return value.items[1];
+		},
+	),
+	DPattern.match(
+		{ items: ["count"] },
+		(value) => value.items[1],
+	),
+	DPattern.exhaustive,
+);
+// Les deux préfixes imbriqués sont traités ; la sortie est le texte ou le nombre du tuple.
+type _CheckNested = DCommon.ExpectType<typeof nested, string | number, "strict">;
+
+// Motif predicate : une garantie peut remplacer un motif objet ou tableau.
+declare const scalar: string | number | null;
+const selected = DCommon.pipe(
+	scalar,
+	DPattern.match(
+		DCommon.isType("string"),
+		DString.toUpperCase,
+	),
+	DPattern.otherwise(
+		DCommon.forward,
+	),
+);
+// Les chaînes sont mises en majuscules ; number et null restent inchangés.
+type _CheckSelected = DCommon.ExpectType<typeof selected, Uppercase<string> | number | null, "strict">;
+
+// Sélection inverse dans le builder : traiter les états en lecture seule avant les états actifs.
+declare const state: "ready" | "draft" | "archived";
+const byPredicates = DPattern.match(state)
+	.whenNot(
+		DCommon.or([DCommon.equal("ready"), DCommon.equal("draft")]),
+		DString.prepend("Lecture seule : "),
+	)
+	.when(DCommon.equal("ready"), DString.toUpperCase)
+	.with("draft", DString.prepend("À compléter : "))
+	.exhaustive();
+// whenNot traite archived ; seuls ready et draft doivent encore être couverts.
+type _CheckByPredicates = DCommon.ExpectType<
+	typeof byPredicates,
+	"Lecture seule : archived" | "READY" | "À compléter : draft",
+	"strict"
+>;
+
+// Test booléen dans whenNot : le montant reste à traiter lorsque la livraison est offerte.
+declare const orderTotal: number;
+declare const freeShippingThreshold: number;
+declare const shippingFee: number;
+const withShipping = DPattern.match(orderTotal)
+	.whenNot(DNumber.greaterThanOrEqual(freeShippingThreshold), (value) => {
+		type _CheckValue = DCommon.ExpectType<typeof value, number, "strict">;
+
+		return DNumber.sum([value, shippingFee]);
+	});
+// Le seuil dynamique ne retire pas number des cas restants : exhaustive n'est pas disponible.
+type _CheckWithShipping = DCommon.ExpectType<typeof withShipping, DPattern.MatchBuilder<number, number>, "strict">;
+
+const pricedTotal = withShipping.otherwise(DCommon.forward);
+// Les petites commandes reçoivent les frais ; les autres conservent leur montant initial.
+type _CheckPricedTotal = DCommon.ExpectType<typeof pricedTotal, number, "strict">;
+
+// Motifs littéraux combinés : union regroupe plusieurs valeurs dans une même branche.
+const byValue = DPattern.match(state)
+	.with(DPattern.union("ready", "draft"), DString.toUpperCase)
+	.otherwise(DString.toUpperCase);
+// La valeur obtenue est "READY", "DRAFT" ou "ARCHIVED", selon l’entrée.
+type _CheckByValue = DCommon.ExpectType<typeof byValue, "READY" | "DRAFT" | "ARCHIVED", "strict">;

package/docs/API/10-lang/10-pattern/10-matchWithEntity.ts

@@ -0,0 +1,49 @@
+/**
+ * @title DPattern.matchWithEntity
+ *
+ * Router une union d’entités DuploJS vers un callback pour chaque nom d’entité.
+ */
+import * as DPattern from "@duplojs/lang/pattern";
+import * as DCommon from "@duplojs/lang/common";
+import type * as DModeling from "@duplojs/lang/modeling";
+
+interface User extends DModeling.Entity<"User"> {
+	id: string;
+	name: string;
+}
+interface Admin extends DModeling.Entity<"Admin"> {
+	id: string;
+	permissions: readonly string[];
+}
+declare const account: User | Admin;
+
+// Appel direct : chaque nom de l’union exige une branche, sans clé étrangère.
+const result = DPattern.matchWithEntity(account, {
+	User: (entity) => {
+		type _CheckValue = DCommon.ExpectType<typeof entity, User, "strict">;
+		return entity.name;
+	},
+	Admin: (entity) => {
+		type _CheckValue = DCommon.ExpectType<typeof entity, Admin, "strict">;
+		return entity.permissions;
+	},
+});
+// La sortie est le nom utilisateur ou les permissions de l’administrateur.
+type _CheckResult = DCommon.ExpectType<typeof result, string | readonly string[], "strict">;
+
+// Appel curifié : configurer les branches directement dans le pipe.
+const piped = DCommon.pipe(
+	account,
+	DPattern.matchWithEntity({
+		User: (entity) => {
+			type _CheckValue = DCommon.ExpectType<typeof entity, User, "strict">;
+			return entity.name;
+		},
+		Admin: (entity) => {
+			type _CheckValue = DCommon.ExpectType<typeof entity, Admin, "strict">;
+			return entity.permissions;
+		},
+	}),
+);
+// Même sélection : le nom utilisateur ou les permissions de l’administrateur.
+type _CheckPiped = DCommon.ExpectType<typeof piped, string | readonly string[], "strict">;

package/docs/API/10-lang/10-pattern/10-matchWithEntityOtherwise.ts

@@ -0,0 +1,55 @@
+/**
+ * @title DPattern.matchWithEntityOtherwise
+ *
+ * Router les entités sélectionnées et conserver dans le type du fallback les entités restantes.
+ */
+import * as DPattern from "@duplojs/lang/pattern";
+import * as DCommon from "@duplojs/lang/common";
+import type * as DModeling from "@duplojs/lang/modeling";
+
+interface User extends DModeling.Entity<"User"> {
+	id: string;
+	name: string;
+}
+interface Admin extends DModeling.Entity<"Admin"> {
+	id: string;
+	permissions: readonly string[];
+}
+interface Guest extends DModeling.Entity<"Guest"> { id: string }
+declare const account: User | Admin | Guest;
+
+// Appel direct : traiter certains noms ; le repli reçoit uniquement le reste.
+const result = DPattern.matchWithEntityOtherwise(
+	account,
+	{
+		User: (entity) => {
+			type _CheckValue = DCommon.ExpectType<typeof entity, User, "strict">;
+			return entity.name;
+		},
+	},
+	(entity) => {
+		type _CheckRemaining = DCommon.ExpectType<typeof entity, Admin | Guest, "strict">;
+		return entity.id;
+	},
+);
+// User produit son résultat ; les autres variantes fournissent leur id.
+type _CheckResult = DCommon.ExpectType<typeof result, string, "strict">;
+
+// Appel curifié dans un pipe : le repli conserve le même affinement.
+const piped = DCommon.pipe(
+	account,
+	DPattern.matchWithEntityOtherwise(
+		{
+			User: (entity) => {
+				type _CheckValue = DCommon.ExpectType<typeof entity, User, "strict">;
+				return entity.name;
+			},
+		},
+		(entity) => {
+			type _CheckRemaining = DCommon.ExpectType<typeof entity, Admin | Guest, "strict">;
+			return entity.id;
+		},
+	),
+);
+// User produit son résultat ; les autres variantes fournissent leur id.
+type _CheckPiped = DCommon.ExpectType<typeof piped, string, "strict">;