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

package/docs/API/10-lang/10-either/10-isSelected.ts

@@ -0,0 +1,41 @@
+/**
+ * @title DEither.isSelected
+ *
+ * Tester une sélection d’informations et affiner l’union d’Either.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: DEither.Success<"saved"> | DEither.Left<"missing", Error>;
+
+if (DEither.isSelected(input, {
+	success: true,
+	missing: false,
+})) {
+	type _CheckInput = DCommon.ExpectType<typeof input, DEither.Success<"saved">, "strict">;
+	const value = DEither.unwrapRight(input);
+	type _CheckValue = DCommon.ExpectType<typeof value, "saved", "strict">;
+}
+
+// La forme curifiée est directement utilisable comme predicate de DCommon.when.
+const result = DCommon.pipe(
+	input,
+	DCommon.when(
+		DEither.isSelected({
+			success: true,
+			missing: false,
+		}),
+		DEither.unwrapRight,
+	),
+);
+
+// Le cas sélectionné est extrait ; le Left non sélectionné reste enveloppé.
+type _CheckResult = DCommon.ExpectType<typeof result, "saved" | DEither.Left<"missing", Error>, "strict">;
+
+const matches = DEither.isSelected(
+	DEither.left("missing", new Error("missing")),
+	{
+		missing: true,
+	},
+);
+type _CheckMatches = DCommon.ExpectType<typeof matches, boolean, "strict">;

package/docs/API/10-lang/10-either/10-keepAsRightByInformation.ts

@@ -0,0 +1,29 @@
+/**
+ * @title DEither.keepAsRightByInformation
+ *
+ * Reclasser comme Right les variantes portant certaines informations.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+const input = DEither.left("validated", "Alice");
+
+// Appel classique : l’information ciblée devient un Right.
+const direct = DEither.keepAsRightByInformation(input, "validated");
+type _CheckDirect = DCommon.ExpectType<typeof direct, DEither.Right<"validated", "Alice">, "strict">;
+
+// Appel curifié : le changement de statut est placé dans le pipe.
+const piped = DCommon.pipe(
+	input,
+	DEither.keepAsRightByInformation("validated"),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, DEither.Right<"validated", "Alice">, "strict">;
+
+// Un Right dont l’information n’est pas ciblée devient un Left ; les informations
+// impossibles pour l’union d’entrée doivent être déclarées explicitement au runtime.
+const rejected = DEither.keepAsRightByInformation(DEither.right("other", 42), "selected" as never);
+type _CheckRejected = DCommon.ExpectType<
+	typeof rejected,
+	DEither.Left<"other", 42>,
+	"strict"
+>;

package/docs/API/10-lang/10-either/10-keepAsRightSelection.ts

@@ -0,0 +1,23 @@
+/**
+ * @title DEither.keepAsRightSelection
+ *
+ * Reclasser les variantes selon une sélection exhaustive d’informations.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+const input = DEither.left("validated", "Alice");
+
+// Appel classique : la variante sélectionnée devient Right.
+const direct = DEither.keepAsRightSelection(input, { validated: true });
+type _CheckDirect = DCommon.ExpectType<typeof direct, DEither.Right<"validated", "Alice">, "strict">;
+
+// Appel curifié : la sélection est placée dans le pipe.
+const piped = DCommon.pipe(
+	input,
+	DEither.keepAsRightSelection({ validated: true }),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, DEither.Right<"validated", "Alice">, "strict">;
+
+const rejected = DEither.keepAsRightSelection(DEither.success("saved"), { success: false });
+type _CheckRejected = DCommon.ExpectType<typeof rejected, DEither.Left<"success", "saved">, "strict">;

package/docs/API/10-lang/10-either/10-left.ts

@@ -0,0 +1,13 @@
+/**
+ * @title DEither.left
+ *
+ * Créer un résultat Left avec une information et une valeur optionnelle.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const withoutValue = DEither.left("missing");
+type _CheckWithoutValue = DCommon.ExpectType<typeof withoutValue, DEither.Left<"missing", undefined>, "strict">;
+
+const withValue = DEither.left("invalid", "bad-input");
+type _CheckWithValue = DCommon.ExpectType<typeof withValue, DEither.Left<"invalid", "bad-input">, "strict">;

package/docs/API/10-lang/10-either/10-matchInformation.ts

@@ -0,0 +1,28 @@
+/**
+ * @title DEither.matchInformation
+ *
+ * Appliquer exhaustivement une callback selon l’information du résultat.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: DEither.Success<"saved"> | DEither.Left<"missing", Error>;
+declare const stored: "stored";
+declare const rejected: "rejected";
+
+// Appel classique : chaque information de l’union possède une callback.
+const direct = DEither.matchInformation(input, {
+	success: (value) => stored,
+	missing: (value) => rejected,
+});
+type _CheckDirect = DCommon.ExpectType<typeof direct, "stored" | "rejected", "strict">;
+
+// Appel curifié : le matcher est directement placé dans le pipe.
+const piped = DCommon.pipe(
+	input,
+	DEither.matchInformation({
+		success: (value) => stored,
+		missing: (value) => rejected,
+	}),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, "stored" | "rejected", "strict">;

package/docs/API/10-lang/10-either/10-matchInformationCombination.ts

@@ -0,0 +1,61 @@
+/**
+ * @title DEither.matchInformationCombination
+ *
+ * Appliquer un traitement pour chaque combinaison d’informations d’une collection d’Either.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+type Combination = readonly [
+	DEither.Success<42> | DEither.Error<"message">,
+	DEither.Right<"found", 1> | DEither.Left<"missing", undefined>,
+];
+
+declare const combination: Combination;
+
+// Appel classique : les quatre combinaisons possibles sont traitées explicitement.
+const direct = DEither.matchInformationCombination(combination, {
+	"success/found": (values) => {
+		type _CheckValues = DCommon.ExpectType<typeof values, readonly [42, 1], "strict">;
+		return values;
+	},
+	"success/missing": (values) => {
+		type _CheckValues = DCommon.ExpectType<typeof values, readonly [42, undefined], "strict">;
+		return values;
+	},
+	"error/found": (values) => {
+		type _CheckValues = DCommon.ExpectType<typeof values, readonly ["message", 1], "strict">;
+		return values;
+	},
+	"error/missing": (values) => {
+		type _CheckValues = DCommon.ExpectType<typeof values, readonly ["message", undefined], "strict">;
+		return values;
+	},
+});
+type _CheckDirect = DCommon.ExpectType<
+	typeof direct,
+	| readonly [42, 1]
+	| readonly [42, undefined]
+	| readonly ["message", 1]
+	| readonly ["message", undefined],
+	"strict"
+>;
+
+// Appel curifié : le matcher exhaustif est directement placé dans le pipe.
+const piped = DCommon.pipe(
+	combination,
+	DEither.matchInformationCombination({
+		"success/found": (values) => values,
+		"success/missing": (values) => values,
+		"error/found": (values) => values,
+		"error/missing": (values) => values,
+	}),
+);
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	| readonly [42, 1]
+	| readonly [42, undefined]
+	| readonly ["message", 1]
+	| readonly ["message", undefined],
+	"strict"
+>;

package/docs/API/10-lang/10-either/10-matchInformationCombinationOtherwise.ts

@@ -0,0 +1,62 @@
+/**
+ * @title DEither.matchInformationCombinationOtherwise
+ *
+ * Traiter les combinaisons d’informations choisies et fournir un cas de repli.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+type Combination = readonly [
+	DEither.Success<42> | DEither.Error<"message">,
+	DEither.Right<"found", 1> | DEither.Left<"missing", undefined>,
+];
+
+declare const combination: Combination;
+
+// Appel classique : traiter success/found et transmettre les autres cas au repli.
+const direct = DEither.matchInformationCombinationOtherwise(
+	combination,
+	{
+		"success/found": (values) => {
+			type _CheckValues = DCommon.ExpectType<typeof values, readonly [42, 1], "strict">;
+			return values;
+		},
+	},
+	(values) => {
+		type _CheckRemaining = DCommon.ExpectType<
+			typeof values,
+			| readonly [DEither.Success<42>, DEither.Left<"missing", undefined>]
+			| readonly [DEither.Error<"message">, DEither.Right<"found", 1>]
+			| readonly [DEither.Error<"message">, DEither.Left<"missing", undefined>],
+			"strict"
+		>;
+		return values;
+	},
+);
+type _CheckDirect = DCommon.ExpectType<
+	typeof direct,
+	| readonly [42, 1]
+	| readonly [DEither.Success<42>, DEither.Left<"missing", undefined>]
+	| readonly [DEither.Error<"message">, DEither.Right<"found", 1>]
+	| readonly [DEither.Error<"message">, DEither.Left<"missing", undefined>],
+	"strict"
+>;
+
+// Appel curifié : la sélection et le repli sont configurés dans le pipe.
+const piped = DCommon.pipe(
+	combination,
+	DEither.matchInformationCombinationOtherwise(
+		{
+			"error/missing": (values) => values,
+		},
+		(values) => values,
+	),
+);
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	| readonly [DEither.Success<42>, DEither.Right<"found", 1>]
+	| readonly [DEither.Success<42>, DEither.Left<"missing", undefined>]
+	| readonly [DEither.Error<"message">, DEither.Right<"found", 1>]
+	| readonly ["message", undefined],
+	"strict"
+>;

package/docs/API/10-lang/10-either/10-matchInformationOtherwise.ts

@@ -0,0 +1,29 @@
+/**
+ * @title DEither.matchInformationOtherwise
+ *
+ * Appliquer une callback pour certaines informations et une branche de repli pour les autres.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: DEither.Success<"saved"> | DEither.Left<"missing", Error>;
+declare const stored: "stored";
+declare const unhandled: "unhandled";
+
+// Appel classique : seules les informations documentées dans le matcher sont ciblées.
+const direct = DEither.matchInformationOtherwise(
+	input,
+	{ success: (value: "saved") => stored },
+	(value) => unhandled,
+);
+type _CheckDirect = DCommon.ExpectType<typeof direct, "stored" | "unhandled", "strict">;
+
+// Appel curifié : le matcher et la branche de repli sont configurés dans le pipe.
+const piped = DCommon.pipe(
+	input,
+	DEither.matchInformationOtherwise(
+		{ success: (value: "saved") => stored },
+		(value) => unhandled,
+	),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, "stored" | "unhandled", "strict">;

package/docs/API/10-lang/10-either/10-none.ts

@@ -0,0 +1,12 @@
+/**
+ * @title DEither.none
+ *
+ * Créer le Left représentant l’absence d’une valeur.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const result = DEither.none();
+
+// La sortie est `None`, un Left dont la valeur est `null`.
+type _CheckResult = DCommon.ExpectType<typeof result, DEither.None, "strict">;

package/docs/API/10-lang/10-either/10-ok.ts

@@ -0,0 +1,12 @@
+/**
+ * @title DEither.ok
+ *
+ * Créer un Right standardisé représentant une réussite sans valeur.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const result = DEither.ok();
+
+// La sortie est `Ok`, un Right dont la valeur est `undefined`.
+type _CheckResult = DCommon.ExpectType<typeof result, DEither.Ok, "strict">;

package/docs/API/10-lang/10-either/10-result.ts

@@ -0,0 +1,18 @@
+/**
+ * @title DEither.result
+ *
+ * Créer un état contextualisé de type Result, sans lui attribuer un succès ou un échec.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+// Appel classique : l’information et la valeur sont fournies ensemble.
+const direct = DEither.result("validated", 42);
+type _CheckDirect = DCommon.ExpectType<typeof direct, DEither.Result<"validated", 42>, "strict">;
+
+// Appel curifié : l’information est configurée avant la valeur dans le pipe.
+const piped = DCommon.pipe(
+	42,
+	DEither.result("validated"),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, DEither.Result<"validated", 42>, "strict">;

package/docs/API/10-lang/10-either/10-rewriteInformation.ts

@@ -0,0 +1,24 @@
+/**
+ * @title DEither.rewriteInformation
+ *
+ * Renommer certaines informations en conservant le statut et la valeur.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+const input = DEither.success("saved");
+
+// Appel classique : seule l’information `success` est renommée.
+const direct = DEither.rewriteInformation(input, { success: "stored" });
+type _CheckDirect = DCommon.ExpectType<typeof direct, DEither.Right<"stored", "saved">, "strict">;
+
+// Appel curifié : le mapping est configuré dans le pipe.
+const piped = DCommon.pipe(
+	input,
+	DEither.rewriteInformation({ success: "stored" }),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, DEither.Right<"stored", "saved">, "strict">;
+
+const unchanged = DEither.rewriteInformation(DEither.left("missing", "not-found"), { missing: "not-found" });
+// Le statut et la valeur sont conservés tandis que l’information est renommée.
+type _CheckUnchanged = DCommon.ExpectType<typeof unchanged, DEither.Left<"not-found", "not-found">, "strict">;

package/docs/API/10-lang/10-either/10-right.ts

@@ -0,0 +1,13 @@
+/**
+ * @title DEither.right
+ *
+ * Créer un résultat Right avec une information et une valeur optionnelle.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const withoutValue = DEither.right("ready");
+type _CheckWithoutValue = DCommon.ExpectType<typeof withoutValue, DEither.Right<"ready", undefined>, "strict">;
+
+const withValue = DEither.right("user-found", "Alice");
+type _CheckWithValue = DCommon.ExpectType<typeof withValue, DEither.Right<"user-found", "Alice">, "strict">;

package/docs/API/10-lang/10-either/10-rightAsyncPipe.ts

@@ -0,0 +1,70 @@
+/**
+ * @title DEither.rightAsyncPipe
+ *
+ * Enchaîner des transformations asynchrones sur la valeur d’un Right en arrêtant au premier Left.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DString from "@duplojs/lang/string";
+import type * as DCommon from "@duplojs/lang/common";
+
+// Une entrée brute peut être suivie d’une étape synchrone ; la sortie reste
+// toujours enveloppée dans une Promise de Success.
+const fromPlain = DEither.rightAsyncPipe(
+	Promise.resolve("saved"),
+	DString.toUpperCase,
+);
+type _CheckFromPlain = DCommon.ExpectType<
+	typeof fromPlain,
+	Promise<DEither.Success<Uppercase<string>>>,
+	"strict"
+>;
+
+// Chaque étape reçoit la valeur déballée du Right, même lorsqu’une étape
+// asynchrone retourne elle-même un Right.
+const fromIntermediateRight = DEither.rightAsyncPipe(
+	Promise.resolve(DEither.success("saved")),
+	(value) => Promise.resolve(DEither.right("normalized", value)),
+	DString.toUpperCase,
+);
+type _CheckFromIntermediateRight = DCommon.ExpectType<
+	typeof fromIntermediateRight,
+	Promise<DEither.Success<"SAVED">>,
+	"strict"
+>;
+
+// Si la dernière étape retourne un Right, ce wrapper est conservé tel quel.
+const finalRight = DEither.rightAsyncPipe(
+	Promise.resolve(DEither.success("saved")),
+	(value) => Promise.resolve(DEither.right("normalized", value)),
+);
+type _CheckFinalRight = DCommon.ExpectType<
+	typeof finalRight,
+	Promise<DEither.Right<"normalized", "saved">>,
+	"strict"
+>;
+
+declare const input: Promise<DEither.Success<"saved"> | DEither.Error<"missing">>;
+declare const neverReached: "never-reached";
+
+// Un Left initial est propagé et les étapes suivantes ne sont pas exécutées.
+const propagated = DEither.rightAsyncPipe(
+	input,
+	DString.toUpperCase,
+);
+type _CheckPropagated = DCommon.ExpectType<
+	typeof propagated,
+	Promise<DEither.Error<"missing"> | DEither.Success<"SAVED">>,
+	"strict"
+>;
+
+// Un Left produit par une étape arrête aussi les étapes suivantes.
+const stopped = DEither.rightAsyncPipe(
+	Promise.resolve(DEither.success("saved")),
+	() => Promise.resolve(DEither.error("not-found")),
+	() => Promise.resolve(neverReached),
+);
+type _CheckStopped = DCommon.ExpectType<
+	typeof stopped,
+	Promise<DEither.Error<"not-found"> | DEither.Success<"never-reached">>,
+	"strict"
+>;

package/docs/API/10-lang/10-either/10-rightPipe.ts

@@ -0,0 +1,72 @@
+/**
+ * @title DEither.rightPipe
+ *
+ * Enchaîner des transformations sur la valeur d’un Right en arrêtant au premier Left.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DString from "@duplojs/lang/string";
+import type * as DCommon from "@duplojs/lang/common";
+
+// Une entrée brute est transmise telle quelle à la première étape et sa sortie
+// brute est enveloppée dans un Success.
+const fromPlain = DEither.rightPipe(
+	"saved",
+	DString.toUpperCase,
+);
+type _CheckFromPlain = DCommon.ExpectType<typeof fromPlain, DEither.Success<"SAVED">, "strict">;
+
+// Une étape reçoit la valeur déballée du Right, jamais son wrapper.
+const fromRight = DEither.rightPipe(
+	DEither.success("saved"),
+	DString.toUpperCase,
+);
+type _CheckFromRight = DCommon.ExpectType<typeof fromRight, DEither.Success<"SAVED">, "strict">;
+
+// Un Right intermédiaire est déballé avant l’étape suivante ; seule la valeur
+// de la dernière étape détermine la sortie finale.
+const fromIntermediateRight = DEither.rightPipe(
+	DEither.success("saved"),
+	(value) => DEither.right("normalized", value),
+	DString.toUpperCase,
+);
+type _CheckFromIntermediateRight = DCommon.ExpectType<
+	typeof fromIntermediateRight,
+	DEither.Success<"SAVED">,
+	"strict"
+>;
+
+// Si la dernière étape retourne un Right, ce wrapper est conservé tel quel.
+const finalRight = DEither.rightPipe(
+	DEither.success("saved"),
+	(value) => DEither.right("normalized", value),
+);
+type _CheckFinalRight = DCommon.ExpectType<
+	typeof finalRight,
+	DEither.Right<"normalized", "saved">,
+	"strict"
+>;
+
+declare const input: DEither.Success<"saved"> | DEither.Error<"missing">;
+
+// Un Left initial est propagé sans exécuter les étapes prévues pour les Right.
+const propagated = DEither.rightPipe(
+	input,
+	DString.toUpperCase,
+);
+type _CheckPropagated = DCommon.ExpectType<
+	typeof propagated,
+	DEither.Error<"missing"> | DEither.Success<"SAVED">,
+	"strict"
+>;
+
+// Un Left produit par une étape arrête aussi les étapes suivantes.
+const stopped = DEither.rightPipe(
+	DEither.success("saved"),
+	() => DEither.error("not-found"),
+	() => "never-reached",
+);
+type _CheckStopped = DCommon.ExpectType<
+	typeof stopped,
+	DEither.Error<"not-found"> | DEither.Success<"never-reached">,
+	"strict"
+>;

package/docs/API/10-lang/10-either/10-safeCallback.ts

@@ -0,0 +1,29 @@
+/**
+ * @title DEither.safeCallback
+ *
+ * Convertir une valeur ou une exception d’une callback en Either.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const success = DEither.safeCallback(() => "saved");
+// Une valeur brute devient SafeCallbackSuccess ; la capture d’une exception reste dans le contrat.
+type _CheckSuccess = DCommon.ExpectType<
+	typeof success,
+	DEither.SafeCallbackSuccess<"saved"> | DEither.SafeCallbackError,
+	"strict"
+>;
+
+const existing = DEither.safeCallback(() => DEither.left("missing"));
+// Un Either déjà produit par la callback est conservé, avec le Left réservé aux exceptions.
+type _CheckExisting = DCommon.ExpectType<
+	typeof existing,
+	DEither.Left<"missing", undefined> | DEither.SafeCallbackError,
+	"strict"
+>;
+
+const failure = DEither.safeCallback(() => {
+	throw new Error("unexpected");
+});
+// Une exception devient SafeCallbackError et sa valeur reste inconnue.
+type _CheckFailure = DCommon.ExpectType<typeof failure, DEither.SafeCallbackError, "strict">;

package/docs/API/10-lang/10-either/10-some.ts

@@ -0,0 +1,12 @@
+/**
+ * @title DEither.some
+ *
+ * Créer un Right représentant une valeur présente dans un Maybe.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const result = DEither.some("Alice");
+
+// La sortie est `Some<"Alice">`, distincte de `None`.
+type _CheckResult = DCommon.ExpectType<typeof result, DEither.Some<string>, "strict">;

package/docs/API/10-lang/10-either/10-success.ts

@@ -0,0 +1,12 @@
+/**
+ * @title DEither.success
+ *
+ * Créer un Right standardisé avec l’information `success`.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const result = DEither.success("saved");
+
+// La sortie est un Success conservant le type littéral de la valeur.
+type _CheckResult = DCommon.ExpectType<typeof result, DEither.Success<"saved">, "strict">;

package/docs/API/10-lang/10-either/10-toMaybe.ts

@@ -0,0 +1,53 @@
+/**
+ * @title DEither.toMaybe
+ *
+ * Convertir une valeur, une absence ou un Either en représentation Maybe.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DString from "@duplojs/lang/string";
+import * as DCommon from "@duplojs/lang/common";
+
+const present = DEither.toMaybe("Alice");
+const absent = DEither.toMaybe(undefined);
+const existing = DEither.toMaybe(DEither.success("Alice"));
+
+// Une valeur présente devient Some, tandis que null et undefined deviennent None.
+type _CheckPresent = DCommon.ExpectType<typeof present, DEither.Some<string>, "strict">;
+type _CheckAbsent = DCommon.ExpectType<typeof absent, DEither.None, "strict">;
+// Un Either existant est transmis sans être encapsulé une seconde fois.
+type _CheckExisting = DCommon.ExpectType<typeof existing, DEither.Success<"Alice">, "strict">;
+
+declare const nullableName: string | null | undefined;
+
+// Une valeur nullable devient un Either exploitable par les outils de discrimination.
+const maybeName = DCommon.pipe(
+	nullableName,
+	DEither.toMaybe,
+);
+type _CheckMaybeName = DCommon.ExpectType<typeof maybeName, DEither.Some<string> | DEither.None, "strict">;
+
+// Dans un pipe ordinaire, whenIsRight transforme uniquement la présence et
+// transmet None sans exécuter la callback.
+const normalizedName = DCommon.pipe(
+	nullableName,
+	DEither.toMaybe,
+	DEither.whenIsRight(DString.toUpperCase),
+);
+type _CheckNormalizedName = DCommon.ExpectType<
+	typeof normalizedName,
+	DEither.None | Uppercase<string>,
+	"strict"
+>;
+
+// Dans un rightPipe, None devient un arrêt : l’étape suivante ne reçoit que la
+// valeur d’un Some et n’est pas exécutée lorsque la valeur initiale est absente.
+const rightPipedName = DEither.rightPipe(
+	nullableName,
+	DEither.toMaybe,
+	DString.toUpperCase,
+);
+type _CheckRightPipedName = DCommon.ExpectType<
+	typeof rightPipedName,
+	DEither.None | DEither.Success<Uppercase<string>>,
+	"strict"
+>;

package/docs/API/10-lang/10-either/10-unwrapByInformation.ts

@@ -0,0 +1,20 @@
+/**
+ * @title DEither.unwrapByInformation
+ *
+ * Extraire les variantes portant une information donnée et transmettre les autres.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: DEither.Success<"saved"> | DEither.Left<"missing", Error>;
+
+// Appel classique : seule l’information ciblée est déballée.
+const direct = DEither.unwrapByInformation(input, "success");
+type _CheckDirect = DCommon.ExpectType<typeof direct, "saved" | DEither.Left<"missing", Error>, "strict">;
+
+// Appel curifié : plusieurs informations peuvent être ciblées par un tableau.
+const piped = DCommon.pipe(
+	input,
+	DEither.unwrapByInformation(["success", "missing"]),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, "saved" | Error, "strict">;