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

package/docs/concepts/01-fundamental/02-currying/10-built-in-function.ts

@@ -0,0 +1,178 @@
+/**
+ * @title Réutilisation des fonctions de l’écosystème dans les pipes.
+ *
+ * Composer les opérations fournies, sous forme curifiée ou directement compatible avec pipe.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DArray from "@duplojs/lang/array";
+import * as DString from "@duplojs/lang/string";
+import * as DObject from "@duplojs/lang/object";
+import * as DNumber from "@duplojs/lang/number";
+import * as DEither from "@duplojs/lang/either";
+import * as DTuple from "@duplojs/lang/tuple";
+import * as DChrono from "@duplojs/lang/chrono";
+import * as DGenerator from "@duplojs/lang/generator";
+import * as DPattern from "@duplojs/lang/pattern";
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+
+// Avant d’écrire une callback ou de recourir à une API native, rechercher une opération
+// fournie par l’écosystème : sa forme curifiée ou son unique argument peut convenir au pipe.
+// Cette démarche s’applique à tous les packages ; les domaines ci-dessous sont des exemples.
+
+// Les fonctions de `string` et `array` sont faites pour être composées.
+// readonly (Lowercase<string> & DString.MinCharacters<1>)[] & DArray.MaxElements<4>
+const normalizedNames = DCommon.pipe(
+	[" John ", "", " JANE ", " Alice "],
+	DArray.map(DString.trim),
+	DArray.filter(DString.isNotEmpty),
+	DArray.map(DString.toLowerCase),
+	DArray.sort(DString.sortCompare),
+);
+
+// Les prédicats de `number` peuvent directement être utilisés
+// dans les fonctions de manipulation de tableaux.
+// number
+const adultAges = DCommon.pipe(
+	[12, 18, 42, 8, 21],
+	DArray.filter(DNumber.greaterThanOrEqual(18)),
+	DNumber.sum,
+);
+
+// Les fonctions de `object` sont également prévues pour le pipe.
+// {
+//     name: string & DString.Trimmed & DString.MaxCharacters<6>;
+//     readonly age: 24;
+// }
+const publicUser = DCommon.pipe(
+	{
+		name: " John ",
+		password: "secret",
+		age: 24,
+	},
+	DObject.transformProperty("name", DString.trim),
+	DObject.omit(["password"]),
+);
+
+// `innerPipe` permet de composer plusieurs fonctions intégrées
+// directement à l'endroit où une callback est attendue.
+// readonly { name: Lowercase<string>; }[] & DArray.LengthEqual<2>
+const users = DCommon.pipe(
+	[
+		{
+			name: " John ",
+			age: 24,
+		},
+		{
+			name: " JANE ",
+			age: 32,
+		},
+	],
+	DArray.map(
+		DCommon.innerPipe(
+			DObject.transformProperty(
+				"name",
+				DCommon.innerPipe(
+					DString.trim,
+					DString.toLowerCase,
+				),
+			),
+			DObject.pick(["name"]),
+		),
+	),
+);
+
+// Les fonctions `Either` sont elles aussi composables avec les pipes.
+declare const maybeName:
+	| DEither.Right<"user-found", string>
+	| DEither.Left<"user-not-found">;
+
+// Lowercase<string>
+const name = DCommon.pipe(
+	maybeName,
+	DEither.unwrapOr("anonymous"),
+	DString.trim,
+	DString.toLowerCase,
+);
+
+// `Either` possède également ses propres pipes lorsque le traitement
+// doit continuer uniquement sur une valeur `Right`.
+// DEither.Left<"user-not-found", unknown> | DEither.Success<Lowercase<string>>
+const normalizedEitherName = DEither.rightPipe(
+	maybeName,
+	DString.trim,
+	DString.toLowerCase,
+);
+
+// Les tuples disposent eux aussi de fonctions curifiées.
+// readonly [string & DString.Trimmed & DString.MaxCharacters<6>, string & DString.Trimmed & DString.MaxCharacters<6>]
+const normalizedTuple = DCommon.pipe(
+	[" John ", " Jane "] as const,
+	DTuple.map(DString.trim),
+);
+
+// Les generators permettent de construire des transformations lazy
+// avec exactement le même modèle de composition.
+// readonly (Lowercase<string> & DString.MinCharacters<1>)[]
+const generatedNames = DCommon.pipe(
+	[" John ", "", " JANE ", " Alice "],
+	DGenerator.map(DString.trim),
+	DGenerator.filter(DString.isNotEmpty),
+	DGenerator.map(DString.toLowerCase),
+	DArray.from,
+);
+
+// Les fonctions de date peuvent être utilisées directement dans les pipes.
+declare const creationDate: DChrono.TheDate;
+
+// string
+const serializedCreationDate = DCommon.pipe(
+	creationDate,
+	DChrono.formatDate(
+		"YYYY-MM-DD HH:mm:ss",
+		"Europe/Paris",
+	),
+);
+
+// Le pattern matching fournit également des fonctions curifiées.
+declare const status: "draft" | "published" | "archived";
+
+// "Draft" | "Published" | "Archived"
+const statusLabel = DCommon.pipe(
+	status,
+	DPattern.matchWithStringOtherwise(
+		{
+			draft: () => "Draft" as const,
+			published: () => "Published" as const,
+		},
+		() => "Archived" as const,
+	),
+);
+
+// Les fonctions n'ont pas besoin d'être curifiées lorsqu'elles reçoivent
+// déjà la donnée comme unique argument : elles peuvent être utilisées
+// directement comme étape du pipe.
+declare const filePath: string & DPath.Path;
+
+// string & DString.Trimmed
+const fileContent = await DCommon.asyncPipe(
+	filePath,
+	DSFile.readTextFile,
+	DEither.unwrapOr(""),
+	DString.trim,
+);
+
+// Les fonctions curifiées existent également dans `@duplojs/server`.
+// DSFile.WriteTextFileResult
+const writeResult = await DCommon.asyncPipe(
+	filePath,
+	DSFile.writeTextFile("Hello world"),
+);
+
+// Cela permet de composer des traitements provenant de plusieurs packages.
+// DCommon.Json | {}
+const jsonContent = await DCommon.asyncPipe(
+	filePath,
+	DSFile.readJsonFile,
+	DEither.unwrapOr({}),
+);

package/docs/concepts/01-fundamental/02-currying/20-inner-pipe.ts

@@ -0,0 +1,39 @@
+/**
+ * @title Composition dans une callback.
+ *
+ * Enchaîner des transformations lorsque la fonction appelante attend une fonction.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DArray from "@duplojs/lang/array";
+import * as DString from "@duplojs/lang/string";
+
+// `innerPipe` permet d'enchaîner plusieurs transformations lorsqu'une
+// fonction de transformation est elle-même attendue.
+//
+// readonly (Lowercase<string> & DString.NotEmpty)[] & DArray.MaxElements<3>
+const normalizedTagsWithInnerPipe = DCommon.pipe(
+	" TypeScript, DuploJS, Functional " as const,
+	DString.split(","),
+	DArray.map(
+		DCommon.innerPipe(
+			DString.trim,
+			DString.toLowerCase,
+		),
+	),
+	DArray.filter(DString.isNotEmpty),
+);
+
+// `innerPipe` évite de créer une callback intermédiaire uniquement
+// pour enchaîner plusieurs transformations.
+//
+// readonly (number & Positive)[] & DArray.LengthEqual<3> & DArray.MinElements<3> & DArray.MaxElements<3>
+const tagLengths = DCommon.pipe(
+	" TypeScript, DuploJS, Functional " as const,
+	DString.split(","),
+	DArray.map(
+		DCommon.innerPipe(
+			DString.trim,
+			DString.length,
+		),
+	),
+);

package/docs/concepts/01-fundamental/02-currying/30-async-pipe.ts

@@ -0,0 +1,42 @@
+/**
+ * @title Composition de traitements asynchrones.
+ *
+ * Enchaîner des étapes synchrones et asynchrones dans un pipe ou une callback.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DArray from "@duplojs/lang/array";
+import * as DString from "@duplojs/lang/string";
+
+// `asyncPipe` applique le même principe lorsqu'une ou plusieurs étapes
+// du traitement sont asynchrones.
+//
+// Promise<readonly Lowercase<string>[] & DArray.LengthEqual<2> & DArray.MinElements<2> & DArray.MaxElements<2>>
+const asyncTags = DCommon.asyncPipe(
+	Promise.resolve(" TypeScript, DuploJS " as const),
+	DString.split(","),
+	DArray.map(DString.trim),
+	(tags) => Promise.resolve(tags),
+	DArray.map(DString.toLowerCase),
+);
+
+// `asyncInnerPipe` permet de composer plusieurs transformations synchrones
+// ou asynchrones lorsqu'une callback asynchrone est attendue.
+//
+// Promise<readonly Promise<Lowercase<string>>[] & DArray.LengthEqual<2>>
+// map produit ici un tableau de promesses ; asyncPipe attend chaque étape, pas chaque élément.
+const values = DCommon.asyncPipe(
+	[" TypeScript ", " DuploJS "] as const,
+	DArray.map(
+		DCommon.asyncInnerPipe(
+			(value) => Promise.resolve(value),
+			DString.trim,
+			DString.toLowerCase,
+		),
+	),
+);
+
+// Pour récupérer les valeurs résolues, ajouter une étape qui attend toutes les promesses.
+const resolvedValues = DCommon.asyncPipe(
+	values,
+	DCommon.promiseAll,
+);

package/docs/concepts/01-fundamental/02-currying/index.md

@@ -0,0 +1,3 @@
+## Currification
+
+Composition des transformations de données avec les fonctions DuploJS : pipes, callbacks et traitements asynchrones.

package/docs/concepts/01-fundamental/03-either/01-use.ts

@@ -0,0 +1,21 @@
+/**
+ * @title Représentation des résultats avec Either.
+ *
+ * Statuts Right et Left, information contextuelle et valeur associée.
+ */
+import * as DEither from "@duplojs/lang/either";
+
+// Un résultat porte un statut, une information qui identifie le cas et une valeur.
+const result = DEither.right("user-found", { name: "Alice" });
+const missing = DEither.left("user-not-found");
+
+// Les variantes fournies reposent sur Right (Success, Some, Result, Ok) ou Left
+// (Fail, Error, None).
+// Result décrit un état contextualisé sans décider s’il constitue un succès ou un échec.
+// Un contrat exprime les résultats possibles par une union, avec des informations
+// personnalisées ou des variantes fournies.
+// Dès qu'une branche d'une fonction renvoie un Right ou un Left, toutes ses
+// branches renvoient un Either. Envelopper les valeurs de réussite dans un Right,
+// y compris avec ok() pour une réussite sans valeur ; ne pas mélanger des Either
+// et des valeurs brutes dans le contrat de retour.
+type FindUserResult = DEither.Right<"user-found", { name: "Alice" }> | DEither.Left<"user-not-found", undefined>;

package/docs/concepts/01-fundamental/03-either/10-discrimination.ts

@@ -0,0 +1,79 @@
+/**
+ * @title Discrimination et extraction des résultats.
+ *
+ * Choisir une branche par statut ou information, extraire sa valeur et traiter les autres cas.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const myResult: (
+	| DEither.Success<"result">
+	| DEither.Left<"fail-task", Error>
+	| DEither.Fail
+	| DEither.Error<Error>
+);
+
+// Choisir Right ou Left lorsque seul le statut du résultat compte.
+// whenIsRight transforme la valeur contenue dans un Right et transmet les Left tels quels.
+// "result" | DEither.Left<"fail-task", Error> | DEither.Fail | DEither.Error<Error>
+const resultWhenIsRight = DCommon.pipe(
+	myResult,
+	DEither.whenIsRight(
+		(rightValue) => rightValue,
+	),
+);
+// void | DEither.Success<"result"> | Error
+const resultUnwrapLeft = DEither.unwrapLeft(myResult);
+// unwrapLeft extrait la valeur des Left et conserve les autres résultats enveloppés.
+
+// Choisir une information lorsque le cas précis compte, quel que soit son statut.
+// La callback reçoit ici l’Error contenue dans le Left "fail-task".
+// DEither.Success<"result"> | DEither.Fail | DEither.Error<Error> | "test"
+const resultWhenHasInformation = DCommon.pipe(
+	myResult,
+	DEither.whenHasInformation(
+		"fail-task",
+		(error) => "test" as const,
+	),
+);
+// "result" | Error | DEither.Fail | DEither.Error<Error>
+const resultUnwrapByInformation = DCommon.pipe(
+	myResult,
+	DEither.unwrapByInformation(
+		["success", "fail-task"],
+	),
+);
+// Les variantes non ciblées sont conservées dans le résultat et dans son type.
+
+// Les variantes Otherwise traitent aussi les cas non ciblés, au lieu de les transmettre.
+// "right" | "left"
+const resultWhenIsRightOtherwise = DCommon.pipe(
+	myResult,
+	DEither.whenIsRightOtherwise(
+		// "result"
+		(rightValue) => "right" as const,
+		// DEither.Left<"fail-task", Error> | DEither.Fail | DEither.Error<Error>
+		(leftResult) => "left" as const,
+	),
+);
+
+// Les variantes OrThrow extraient les cas ciblés et lèvent une exception pour les autres.
+// "result" | Error
+const resultUnwrapByInformationOrThrow = DCommon.pipe(
+	myResult,
+	DEither.unwrapByInformationOrThrow(
+		["success", "fail-task"],
+	),
+);
+// Utile notamment pour affirmer le résultat attendu dans un test unitaire.
+
+// Les predicates réduisent le type dans une branche conditionnelle.
+if (DEither.hasInformation(myResult, "success")) {
+	// DEither.Success<"result">
+	void myResult;
+}
+// isRight et isLeft réduisent aussi le type selon le statut du résultat.
+if (DEither.isLeft(myResult)) {
+	// Error | void
+	const leftValue = DEither.unwrapLeft(myResult);
+}

package/docs/concepts/01-fundamental/03-either/20-exhaustive-handling.ts

@@ -0,0 +1,73 @@
+/**
+ * @title Décisions exhaustives sur les résultats.
+ *
+ * Sélection et traitement de chaque variante pour détecter les évolutions du contrat.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const myResult: (
+	| DEither.Success<"result">
+	| DEither.Left<"fail-task", Error>
+	| DEither.Fail
+	| DEither.Error<Error>
+);
+
+// Sélectionner plusieurs variantes avec une décision explicite pour chacune.
+// DEither.Left<"fail-task", Error> | DEither.Fail | "test"
+const resultWhenIsSelected = DCommon.pipe(
+	myResult,
+	DEither.whenIsSelected(
+		{
+			"fail-task": false,
+			error: true,
+			fail: false,
+			success: true,
+		},
+		(value) => "test" as const,
+	),
+);
+// DEither.Success<"result"> | Error | DEither.Left<"fail-task", Error> | DEither.Fail
+const resultUnwrapSelection = DCommon.pipe(
+	myResult,
+	DEither.unwrapSelection(
+		{
+			"fail-task": false,
+			error: true,
+			fail: false,
+			success: false,
+		},
+	),
+);
+// Chaque information doit apparaître dans le sélecteur, même lorsqu’elle vaut false.
+// Ajouter une variante au contrat oblige à réviser la sélection à cet endroit.
+// Cela place la décision dans la couche qui doit la prendre, plutôt que de transmettre
+// involontairement un nouveau résultat à une couche qui ne sait pas le traiter.
+
+// matchInformation impose une callback pour chaque information.
+// Chaque callback reçoit la valeur contenue dans la variante correspondante.
+// "fail-task" | "success" | "fail" | "error"
+const resultMatchInformation = DCommon.pipe(
+	myResult,
+	DEither.matchInformation(
+		{
+			// Error
+			"fail-task": (value) => "fail-task" as const,
+			// Error
+			error: (value) => "error" as const,
+			// void
+			fail: (value) => "fail" as const,
+			// "result"
+			success: (value) => "success" as const,
+		},
+	),
+);
+// matchInformationOtherwise autorise un traitement partiel avec une branche de repli.
+const resultWithFallback = DCommon.pipe(
+	myResult,
+	DEither.matchInformationOtherwise(
+		{ success: (value) => value },
+		(otherResult) => "unhandled" as const,
+	),
+);
+// Les fonctions whenIsSelected disposent aussi d’une variante Otherwise.

package/docs/concepts/01-fundamental/03-either/30-composition.ts

@@ -0,0 +1,72 @@
+/**
+ * @title Composition avec propagation des échecs.
+ *
+ * Enchaîner ou regrouper des opérations en arrêtant le traitement au premier Left.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DArray from "@duplojs/lang/array";
+import * as DString from "@duplojs/lang/string";
+
+declare const myResult: (
+	| DEither.Success<"result">
+	| DEither.Left<"fail-task", Error>
+	| DEither.Fail
+	| DEither.Error<Error>
+);
+
+// `rightPipe` transmet aux étapes la valeur contenue par les Right, jamais le
+// wrapper `Right` lui-même. Dès qu’un Left apparaît, les étapes suivantes sont
+// ignorées et ce Left est retourné. Une valeur finale brute est enveloppée dans
+// Success ; un Right final est conservé.
+// DEither.Left<"fail-task", Error> | DEither.Fail | DEither.Error<Error>
+// | DEither.Left<"wrong", undefined> | DEither.Success<string>
+const resultRightPipe = DEither.rightPipe(
+	myResult,
+	DString.split(""),
+	(value) => {
+		const elementAt = DArray.at(value, 10);
+		if (!elementAt) {
+			return DEither.left("wrong");
+		}
+
+		return DEither.success(elementAt);
+	},
+	// Cette étape reçoit la string du Success retourné ci-dessus, pas son wrapper.
+	(value) => value.toUpperCase(),
+);
+// `rightAsyncPipe` applique le même arrêt sur Left et attend chaque étape
+// asynchrone. Une étape peut retourner un Either : s’il s’agit d’un Right,
+// l’étape suivante reçoit encore sa valeur déballée ; s’il s’agit d’un Left,
+// la suite est ignorée.
+const asyncResult = DEither.rightAsyncPipe(
+	Promise.resolve(myResult),
+	(value) => Promise.resolve(DEither.right("normalized", value)),
+	DString.toLowerCase,
+);
+// La dernière callback retourne une string brute : `asyncResult` est donc un
+// `Success<string>`, tandis que le `Right<"normalized", ...>` intermédiaire
+// n’est pas transmis comme wrapper à la callback suivante.
+// Si une étape intermédiaire produit un `Result` dont une information doit être
+// sélectionnée, composez sa sélection dans cette même callback avec
+// `DCommon.asyncPipe`. Une étape séparée de `rightAsyncPipe` recevrait la valeur
+// du `Right`, et non le `Result` qui porte l’information.
+
+// group rassemble les valeurs des Right dans un Success, ou retourne le premier Left.
+// Les getters sont appelés dans l’ordre et ceux placés après un Left ne sont pas exécutés.
+// Les valeurs déjà calculées avant l’appel à group ne peuvent pas être annulées.
+// DEither.Left<"fail-task", Error> | DEither.Fail | DEither.Error<Error> | DEither.Error<"errorDeLaMort">
+// | DEither.Success<{
+//     result1: "result";
+//     result2: "mySuperResult";
+//     result3: never;
+// }>
+const groupResult = DEither.group({
+	result1: () => myResult,
+	result2: DEither.success("mySuperResult"),
+	result3: DEither.error("errorDeLaMort"),
+});
+// asyncGroup attend chaque résultat dans l’ordre, sans lancer les getters en parallèle.
+const asyncGroupResult = DEither.asyncGroup({
+	result1: () => Promise.resolve(myResult),
+	result2: () => Promise.resolve(DEither.success("mySuperResult")),
+});

package/docs/concepts/01-fundamental/03-either/40-result-adaptation.ts

@@ -0,0 +1,40 @@
+/**
+ * @title Adaptation des résultats au contexte.
+ *
+ * Reclasser les statuts et renommer les informations en conservant les valeurs.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const myResult: (
+	| DEither.Success<"result">
+	| DEither.Left<"fail-task", Error>
+	| DEither.Fail
+	| DEither.Error<Error>
+);
+
+// Réinterpréter les statuts selon le contexte : true donne Right, false donne Left.
+// L’information et la valeur sont conservées ; le sélecteur couvre toutes les variantes.
+// DEither.Left<"fail", void> | DEither.Left<"error", Error> | DEither.Left<"success", "result">
+// | DEither.Right<"fail-task", Error>
+const resultKeepAsRightSelection = DCommon.pipe(
+	myResult,
+	DEither.keepAsRightSelection({
+		"fail-task": true,
+		error: false,
+		fail: false,
+		success: false,
+	}),
+);
+// keepAsRightByInformation sélectionne seulement les informations à considérer comme Right.
+// Toutes les autres deviennent Left, sans imposer de sélecteur exhaustif.
+const resultByInformation = DEither.keepAsRightByInformation(myResult, "fail-task");
+
+// Renommer une information adapte le vocabulaire du résultat au contexte appelant.
+// rewriteInformation conserve le statut et la valeur ; les variantes non ciblées restent identiques.
+// DEither.Fail | DEither.Error<Error> | DEither.Left<"fail-task", Error>
+// | DEither.Right<"new-information", "result">
+const resultRewriteInformation = DCommon.pipe(
+	myResult,
+	DEither.rewriteInformation({ success: "new-information" }),
+);

package/docs/concepts/01-fundamental/03-either/50-external-results.ts

@@ -0,0 +1,59 @@
+/**
+ * @title Conversion des absences et exceptions en résultats.
+ *
+ * Distinguer les refus prévisibles des défaillances d'environnement et adapter les absences ou exceptions en résultats.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+// Une issue prévisible et exploitable par le traitement appartient à son contrat
+// de résultat : donnée invalide, absence ou refus d'une manipulation. Cela vaut
+// aussi pour les opérations techniques ; toute vérification de donnée externe
+// produit un Either pour laisser l'appelant décider de la suite.
+// Lors d'une défaillance imprévue de l'environnement, les dépendances ou le runtime
+// peuvent déjà lever une exception. Elle remonte implicitement à travers les appels ;
+// le code applicatif n'ajoute pas de throw dans les fonctions réutilisables.
+// Un throw explicite ou une conversion par OrThrow appartient à la consommation
+// finale du résultat, lorsque la frontière d'exécution décide de sa conséquence.
+// La distinction dépend du rôle de l'échec, pas de sa rareté ni du coût de propagation.
+// Le seul fait d'accéder à une ressource extérieure ne transforme pas une absence
+// prévue par l'opération en défaillance de l'environnement.
+
+// Maybe représente une présence ou une absence : Some<Value> est un Right, None est un Left.
+// toMaybe convertit null et undefined en None et les valeurs présentes en Some.
+// Un Either déjà construit est transmis tel quel.
+
+declare function someFunction(): string | number | null | undefined;
+
+// DEither.None | DEither.Some<string> | DEither.Some<number>
+const resultToMaybe = DEither.toMaybe(someFunction());
+
+interface User {
+	name: string;
+}
+declare function findUser(): DEither.Maybe<User>;
+
+// Une transformation sur Some reçoit le User ; None est transmis sans exécuter la callback.
+// DEither.None | DEither.Success<string>
+const userName = DCommon.pipe(
+	findUser(),
+	DEither.whenIsRight((user) => DEither.success(user.name)),
+);
+
+// Une API qui lève sur un refus prévisible doit être adaptée pour le rendre
+// exploitable comme résultat. Ne pas déduire la nature de l'échec du choix de cette API.
+// safeCallback transforme une exception en SafeCallbackError, dont la valeur est unknown.
+// Une valeur brute devient SafeCallbackSuccess ; un Either retourné est conservé.
+// La capture est large : distinguer le refus documenté d'une cause technique.
+// Conserver cette cause dans le résultat jusqu'à sa consommation finale, sans
+// la requalifier en refus métier ni la relancer depuis une fonction réutilisable.
+// DEither.SafeCallbackError | DEither.SafeCallbackSuccess<"test">
+const resultSafeCallback = DEither.safeCallback(
+	() => "test" as const,
+);
+// asyncSafeCallback capture aussi les rejets et retourne toujours une Promise de résultat.
+declare function loadValue(): Promise<string>;
+const asyncSafeResult = DEither.asyncSafeCallback(loadValue);
+
+// safeCallback gère aussi les promesses, mais une exception synchrone peut produire
+// directement un Left : préférer asyncSafeCallback pour un retour toujours asynchrone.

package/docs/concepts/01-fundamental/03-either/60-contextual-state.ts

@@ -0,0 +1,40 @@
+/**
+ * @title États contextualisés avec Result.
+ *
+ * Décrire et discriminer des états sans leur attribuer un sens de succès ou d’échec.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DString from "@duplojs/lang/string";
+
+// Result<Information, Value> étend Right et porte un marqueur Result supplémentaire.
+// Il exprime un constat : l’appelant décide du sens de cet état dans son contexte.
+// Une fonction peut ainsi renvoyer uniquement des Result, sans branche Left.
+type EmailState = (
+	| DEither.Result<"valid-email", string & DString.Email>
+	| DEither.Result<"invalid-email", string>
+);
+
+// Le format est vérifié, mais la fonction ne décide pas si l’état observé est un échec.
+// Un format invalide peut être précisément l’état recherché lors d’un nettoyage de données.
+function classifyEmail(input: string): EmailState {
+	if (DString.isEmail(input)) {
+		return DEither.result("valid-email", input);
+	}
+
+	return DEither.result("invalid-email", input);
+}
+
+declare const input: string;
+const state = classifyEmail(input);
+
+// Les deux variantes sont Right : isRight ne permet pas de distinguer ces états.
+// La discrimination repose sur l’information et affine aussi le type de la valeur.
+if (DEither.hasInformation(state, "valid-email")) {
+	const email: string & DString.Email = DEither.unwrapRight(state);
+}
+
+// Les outils Either restent disponibles, notamment pour traiter chaque état explicitement.
+const description = DEither.matchInformation(state, {
+	"valid-email": (email) => `Format reconnu : ${email}`,
+	"invalid-email": (value) => `Format à corriger : ${value}`,
+});

package/docs/concepts/01-fundamental/03-either/index.md

@@ -0,0 +1,3 @@
+## Either
+
+Résultats et états contextualisés : représentation, discrimination, traitement exhaustif, propagation des échecs et adaptation des contrats.