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

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

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

@@ -0,0 +1,19 @@
+/**
+ * @title DEither.unwrapByInformationOrThrow
+ *
+ * Extraire une information ciblée ou lever une exception si elle est absente.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+const direct = DEither.unwrapByInformationOrThrow(DEither.success("saved"), "success");
+type _CheckDirect = DCommon.ExpectType<typeof direct, "saved", "strict">;
+
+// Appel curifié : l’information attendue est configurée dans le pipe.
+const piped = DCommon.pipe(
+	DEither.left("missing", new Error("missing")),
+	DEither.unwrapByInformationOrThrow("missing"),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, Error, "strict">;
+
+// Une information absente provoque `HasNotInformationError` au runtime.

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

@@ -0,0 +1,14 @@
+/**
+ * @title DEither.unwrapLeft
+ *
+ * Extraire la valeur d’un Left et laisser les autres valeurs inchangées.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const leftValue = DEither.unwrapLeft(DEither.left("invalid", "bad-input"));
+type _CheckLeft = DCommon.ExpectType<typeof leftValue, "bad-input", "strict">;
+
+const rightValue = DEither.unwrapLeft(DEither.success("saved"));
+// Un Right n’est pas extrait et reste présent dans la sortie.
+type _CheckRight = DCommon.ExpectType<typeof rightValue, DEither.Success<"saved">, "strict">;

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

@@ -0,0 +1,17 @@
+/**
+ * @title DEither.unwrapLeftOrThrow
+ *
+ * Extraire un Left ou lever une exception lorsque le statut attendu n’est pas présent.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const value = DEither.unwrapLeftOrThrow(DEither.left("invalid", "bad-input"));
+
+// Pour une entrée connue comme Left, la valeur extraite est directement typée.
+type _CheckValue = DCommon.ExpectType<typeof value, "bad-input", "strict">;
+
+// Un Right provoque `NotLeftError` au runtime.
+declare const maybeLeft: DEither.Left<"invalid", string> | DEither.Success<"saved">;
+const narrowed = DEither.unwrapLeftOrThrow(maybeLeft);
+type _CheckNarrowed = DCommon.ExpectType<typeof narrowed, string, "strict">;

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

@@ -0,0 +1,17 @@
+/**
+ * @title DEither.unwrapOr
+ *
+ * Extraire la valeur d’un Right ou fournir une valeur de remplacement.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+const direct = DEither.unwrapOr(DEither.success("saved"), "fallback");
+type _CheckDirect = DCommon.ExpectType<typeof direct, "saved" | "fallback", "strict">;
+
+const piped = DCommon.pipe(
+	DEither.left("missing"),
+	DEither.unwrapOr("fallback"),
+);
+// Le Left prend la valeur de remplacement.
+type _CheckPiped = DCommon.ExpectType<typeof piped, "fallback", "strict">;

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

@@ -0,0 +1,20 @@
+/**
+ * @title DEither.unwrapOtherwise
+ *
+ * Extraire la valeur d’un Right ou calculer une valeur de remplacement pour les autres cas.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+const direct = DEither.unwrapOtherwise(
+	DEither.left("missing"),
+	() => "fallback",
+);
+type _CheckDirect = DCommon.ExpectType<typeof direct, "fallback", "strict">;
+
+const piped = DCommon.pipe(
+	DEither.success("saved"),
+	DEither.unwrapOtherwise(() => "fallback"),
+);
+// La callback de remplacement n’est pas utilisée pour un Right.
+type _CheckPiped = DCommon.ExpectType<typeof piped, "saved" | "fallback", "strict">;

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

@@ -0,0 +1,14 @@
+/**
+ * @title DEither.unwrapRight
+ *
+ * Extraire la valeur d’un Right et laisser les autres valeurs inchangées.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const rightValue = DEither.unwrapRight(DEither.success("saved"));
+type _CheckRight = DCommon.ExpectType<typeof rightValue, "saved", "strict">;
+
+const leftValue = DEither.unwrapRight(DEither.left("missing", "not-found"));
+// Un Left n’est pas extrait et reste présent dans la sortie.
+type _CheckLeft = DCommon.ExpectType<typeof leftValue, DEither.Left<"missing", "not-found">, "strict">;

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

@@ -0,0 +1,17 @@
+/**
+ * @title DEither.unwrapRightOrThrow
+ *
+ * Extraire un Right ou lever une exception lorsque le statut attendu n’est pas présent.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const value = DEither.unwrapRightOrThrow(DEither.success("saved"));
+
+// Pour une entrée connue comme Right, la valeur extraite est directement typée.
+type _CheckValue = DCommon.ExpectType<typeof value, "saved", "strict">;
+
+// Un Left provoque `NotRightError` au runtime.
+declare const maybeRight: DEither.Success<string> | DEither.Left<"missing", null>;
+const narrowed = DEither.unwrapRightOrThrow(maybeRight);
+type _CheckNarrowed = DCommon.ExpectType<typeof narrowed, string, "strict">;

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

@@ -0,0 +1,26 @@
+/**
+ * @title DEither.unwrapSelection
+ *
+ * Extraire les variantes marquées `true` dans une sélection 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 : la variante success est extraite, la variante missing reste enveloppée.
+const direct = DEither.unwrapSelection(input, {
+	success: true,
+	missing: false,
+});
+type _CheckDirect = DCommon.ExpectType<typeof direct, "saved" | DEither.Left<"missing", Error>, "strict">;
+
+// Appel curifié : la sélection est appliquée dans le pipe.
+const piped = DCommon.pipe(
+	input,
+	DEither.unwrapSelection({
+		success: true,
+		missing: false,
+	}),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, "saved" | DEither.Left<"missing", Error>, "strict">;

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

@@ -0,0 +1,19 @@
+/**
+ * @title DEither.unwrapSelectionOrThrow
+ *
+ * Extraire une variante sélectionnée ou lever une exception lorsqu’elle ne l’est pas.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+const direct = DEither.unwrapSelectionOrThrow(DEither.success("saved"), { success: true });
+type _CheckDirect = DCommon.ExpectType<typeof direct, "saved", "strict">;
+
+// Appel curifié : la sélection est configurée avant l’entrée du pipe.
+const piped = DCommon.pipe(
+	DEither.success("saved"),
+	DEither.unwrapSelectionOrThrow({ success: true }),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, "saved", "strict">;
+
+// Une information associée à `false` provoque `HasNotSelectedInformationError` au runtime.

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

@@ -0,0 +1,36 @@
+/**
+ * @title DEither.whenHasInformation
+ *
+ * Transformer la valeur des variantes portant une information donnée.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+const input = DEither.left("invalid", "bad-input");
+
+// Appel classique : la callback reçoit la valeur de l’information ciblée.
+const direct = DEither.whenHasInformation(
+	input,
+	"invalid",
+	(value) => `reason:${value}`,
+);
+type _CheckDirect = DCommon.ExpectType<typeof direct, "reason:bad-input", "strict">;
+
+// Appel curifié : l’information et la callback sont configurées dans le pipe.
+const piped = DCommon.pipe(
+	input,
+	DEither.whenHasInformation(
+		"invalid",
+		(value) => `reason:${value}`,
+	),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, "reason:bad-input", "strict">;
+
+declare const mixedInput: DEither.Success<"saved"> | DEither.Left<"invalid", string>;
+const unchanged = DEither.whenHasInformation(
+	mixedInput,
+	["invalid"],
+	(value) => value,
+);
+// Une information non ciblée transmet le Right inchangé.
+type _CheckUnchanged = DCommon.ExpectType<typeof unchanged, string | DEither.Success<"saved">, "strict">;

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

@@ -0,0 +1,29 @@
+/**
+ * @title DEither.whenHasInformationOtherwise
+ *
+ * Traiter les variantes ciblées par information et fournir une branche de repli.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: DEither.Left<"invalid", string> | DEither.Success<"saved">;
+
+// Appel classique : la branche otherwise reçoit le résultat non ciblé.
+const direct = DEither.whenHasInformationOtherwise(
+	input,
+	"invalid",
+	(value) => `invalid:${value}`,
+	(value) => DEither.unwrapRight(value),
+);
+type _CheckDirect = DCommon.ExpectType<typeof direct, `invalid:${string}` | "saved", "strict">;
+
+// Appel curifié : les deux traitements sont configurés dans le pipe.
+const piped = DCommon.pipe(
+	input,
+	DEither.whenHasInformationOtherwise(
+		"invalid",
+		(value) => `invalid:${value}`,
+		(value) => DEither.unwrapRight(value),
+	),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, `invalid:${string}` | "saved", "strict">;

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

@@ -0,0 +1,20 @@
+/**
+ * @title DEither.whenIsLeft
+ *
+ * Transformer la valeur d’un Left et transmettre les autres résultats inchangés.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+const input = DEither.left("invalid", "bad-input");
+
+// Appel classique : la callback ne reçoit que la valeur du Left.
+const direct = DEither.whenIsLeft(input, (value) => `reason:${value}`);
+type _CheckDirect = DCommon.ExpectType<typeof direct, "reason:bad-input", "strict">;
+
+// Appel curifié : la transformation est directement placée dans le pipe.
+const piped = DCommon.pipe(
+	input,
+	DEither.whenIsLeft((value) => `reason:${value}`),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, "reason:bad-input", "strict">;

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

@@ -0,0 +1,27 @@
+/**
+ * @title DEither.whenIsLeftOtherwise
+ *
+ * Traiter séparément les Left et les autres résultats.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: DEither.Success<"saved"> | DEither.Left<"invalid", string>;
+
+// Appel classique : la seconde callback reçoit le résultat lorsqu’il n’est pas Left.
+const direct = DEither.whenIsLeftOtherwise(
+	input,
+	(value) => `left:${value}`,
+	(value) => DEither.unwrapRight(value),
+);
+type _CheckDirect = DCommon.ExpectType<typeof direct, `left:${string}` | "saved", "strict">;
+
+// Appel curifié : les deux branches sont configurées avant l’entrée du pipe.
+const piped = DCommon.pipe(
+	input,
+	DEither.whenIsLeftOtherwise(
+		(value) => `left:${value}`,
+		(value) => DEither.unwrapRight(value),
+	),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, `left:${string}` | "saved", "strict">;

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

@@ -0,0 +1,20 @@
+/**
+ * @title DEither.whenIsRight
+ *
+ * Transformer la valeur d’un Right et transmettre les autres résultats inchangés.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+const input = DEither.success("saved");
+
+// Appel classique : la callback ne reçoit que la valeur du Right.
+const direct = DEither.whenIsRight(input, (value) => `status:${value}`);
+type _CheckDirect = DCommon.ExpectType<typeof direct, "status:saved", "strict">;
+
+// Appel curifié : la transformation est directement placée dans le pipe.
+const piped = DCommon.pipe(
+	input,
+	DEither.whenIsRight((value) => `status:${value}`),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, "status:saved", "strict">;

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

@@ -0,0 +1,26 @@
+/**
+ * @title DEither.whenIsRightOtherwise
+ *
+ * Traiter séparément les Right et les autres résultats.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: DEither.Success<"saved"> | DEither.Left<"missing", string>;
+
+const direct = DEither.whenIsRightOtherwise(
+	input,
+	(value) => `right:${value}`,
+	(value) => `left:${DEither.unwrapLeft(value)}`,
+);
+type _CheckDirect = DCommon.ExpectType<typeof direct, "right:saved" | `left:${string}`, "strict">;
+
+// Appel curifié : les deux branches sont configurées avant l’entrée du pipe.
+const piped = DCommon.pipe(
+	input,
+	DEither.whenIsRightOtherwise(
+		(value) => `right:${value}`,
+		(value) => `left:${DEither.unwrapLeft(value)}`,
+	),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, "right:saved" | `left:${string}`, "strict">;