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

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

@@ -0,0 +1,51 @@
+/**
+ * @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.
+//
+const asyncTags = DCommon.asyncPipe(
+	Promise.resolve(" TypeScript, DuploJS " as const),
+	DString.split(","),
+	DArray.map(DString.trim),
+	(tags) => Promise.resolve(tags),
+	DArray.map(DString.toLowerCase),
+);
+type _CheckAsyncTags = DCommon.ExpectType<
+	typeof asyncTags,
+	Promise<readonly Lowercase<string>[] & DArray.LengthEqual<2> & DArray.MinElements<2> & DArray.MaxElements<2>>,
+	"strict"
+>;
+
+// `asyncInnerPipe` permet de composer plusieurs transformations synchrones
+// ou asynchrones lorsqu'une callback asynchrone est attendue.
+//
+// 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,
+		),
+	),
+);
+type _CheckValues = DCommon.ExpectType<
+	typeof values,
+	Promise<readonly Promise<Lowercase<string>>[] & DArray.LengthEqual<2>>,
+	"strict"
+>;
+
+// Pour récupérer les valeurs résolues, ajouter une étape qui attend toutes les promesses.
+const resolvedValues = DCommon.asyncPipe(
+	values,
+	DCommon.promiseAll,
+);
+type _CheckResolvedValues = DCommon.ExpectType<typeof resolvedValues, Promise<Lowercase<string>[]>, "strict">;

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,90 @@
+/**
+ * @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.
+const resultWhenIsRight = DCommon.pipe(
+	myResult,
+	DEither.whenIsRight(
+		(rightValue) => rightValue,
+	),
+);
+type _CheckResultWhenIsRight = DCommon.ExpectType<
+	typeof resultWhenIsRight,
+	"result" | DEither.Left<"fail-task", Error> | DEither.Fail | DEither.Error<Error>,
+	"strict"
+>;
+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".
+const resultWhenHasInformation = DCommon.pipe(
+	myResult,
+	DEither.whenHasInformation(
+		"fail-task",
+		(error) => "test" as const,
+	),
+);
+type _CheckResultWhenHasInformation = DCommon.ExpectType<
+	typeof resultWhenHasInformation,
+	DEither.Success<"result"> | DEither.Fail | DEither.Error<Error> | "test",
+	"strict"
+>;
+const resultUnwrapByInformation = DCommon.pipe(
+	myResult,
+	DEither.unwrapByInformation(
+		["success", "fail-task"],
+	),
+);
+type _CheckResultUnwrapByInformation = DCommon.ExpectType<typeof resultUnwrapByInformation, "result" | Error | DEither.Fail | DEither.Error<Error>, "strict">;
+// 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.
+const resultWhenIsRightOtherwise = DCommon.pipe(
+	myResult,
+	DEither.whenIsRightOtherwise(
+		(rightValue) => {
+			type _CheckRightValue = DCommon.ExpectType<typeof rightValue, "result", "strict">;
+			return "right" as const;
+		},
+		(leftResult) => {
+			type _CheckLeftResult = DCommon.ExpectType<typeof leftResult, DEither.Left<"fail-task", Error> | DEither.Fail | DEither.Error<Error>, "strict">;
+			return "left" as const;
+		},
+	),
+);
+type _CheckResultWhenIsRightOtherwise = DCommon.ExpectType<typeof resultWhenIsRightOtherwise, "right" | "left", "strict">;
+
+// Les variantes OrThrow extraient les cas ciblés et lèvent une exception pour les autres.
+const resultUnwrapByInformationOrThrow = DCommon.pipe(
+	myResult,
+	DEither.unwrapByInformationOrThrow(
+		["success", "fail-task"],
+	),
+);
+type _CheckResultUnwrapByInformationOrThrow = DCommon.ExpectType<typeof resultUnwrapByInformationOrThrow, "result" | Error, "strict">;
+// 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")) {
+	type _CheckSuccessResult = DCommon.ExpectType<typeof myResult, DEither.Success<"result">, "strict">;
+	void myResult;
+}
+// isRight et isLeft réduisent aussi le type selon le statut du résultat.
+if (DEither.isLeft(myResult)) {
+	const leftValue = DEither.unwrapLeft(myResult);
+	void leftValue;
+}

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

@@ -0,0 +1,90 @@
+/**
+ * @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.
+const resultWhenIsSelected = DCommon.pipe(
+	myResult,
+	DEither.whenIsSelected(
+		{
+			"fail-task": false,
+			error: true,
+			fail: false,
+			success: true,
+		},
+		(value) => "test" as const,
+	),
+);
+type _CheckResultWhenIsSelected = DCommon.ExpectType<
+	typeof resultWhenIsSelected,
+	DEither.Left<"fail-task", Error> | DEither.Fail | "test",
+	"strict"
+>;
+const resultUnwrapSelection = DCommon.pipe(
+	myResult,
+	DEither.unwrapSelection(
+		{
+			"fail-task": false,
+			error: true,
+			fail: false,
+			success: false,
+		},
+	),
+);
+type _CheckResultUnwrapSelection = DCommon.ExpectType<
+	typeof resultUnwrapSelection,
+	DEither.Success<"result"> | Error | DEither.Left<"fail-task", Error> | DEither.Fail,
+	"strict"
+>;
+// 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(
+		{
+			"fail-task": (value) => {
+				type _CheckFailTaskValue = DCommon.ExpectType<typeof value, Error, "strict">;
+				return "fail-task" as const;
+			},
+			error: (value) => {
+				type _CheckErrorValue = DCommon.ExpectType<typeof value, Error, "strict">;
+				return "error" as const;
+			},
+			fail: (value) => {
+				type _CheckFailValue = DCommon.ExpectType<typeof value, void, "strict">;
+				return "fail" as const;
+			},
+			success: (value) => {
+				type _CheckSuccessValue = DCommon.ExpectType<typeof value, "result", "strict">;
+				return "success" as const;
+			},
+		},
+	),
+);
+type _CheckResultMatchInformation = DCommon.ExpectType<typeof resultMatchInformation, "fail-task" | "success" | "fail" | "error", "strict">;
+// 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,80 @@
+/**
+ * @title Composition avec propagation des échecs.
+ *
+ * Enchaîner ou regrouper des opérations en arrêtant le traitement au premier Left.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+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é.
+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.
+	DString.toUpperCase,
+);
+type _CheckResultRightPipe = DCommon.ExpectType<
+	typeof resultRightPipe,
+	DEither.Left<"fail-task", Error> | DEither.Fail | DEither.Error<Error> | DEither.Left<"wrong", undefined> | DEither.Success<Uppercase<string>>,
+	"strict"
+>;
+// `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,
+);
+type _CheckAsyncResult = DCommon.ExpectType<
+	typeof asyncResult,
+	Promise<DEither.Left<"fail-task", Error> | DEither.Fail | DEither.Error<Error> | DEither.Success<"result">>,
+	"strict"
+>;
+// La dernière callback retourne une string brute : `asyncResult` est donc un
+// `Success<"result">`, 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.
+const groupResult = DEither.group({
+	result1: () => myResult,
+	result2: DEither.success("mySuperResult"),
+	result3: DEither.error("errorDeLaMort"),
+});
+type _CheckGroupResult = DCommon.ExpectType<typeof groupResult, DEither.Left<"fail-task", Error> | DEither.Fail | DEither.Error<Error> | DEither.Error<"errorDeLaMort"> | DEither.Success<{
+	result1: "result";
+	result2: "mySuperResult";
+	result3: never;
+}>, "strict">;
+// 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,46 @@
+/**
+ * @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.
+const resultKeepAsRightSelection = DCommon.pipe(
+	myResult,
+	DEither.keepAsRightSelection({
+		"fail-task": true,
+		error: false,
+		fail: false,
+		success: false,
+	}),
+);
+type _CheckResultKeepAsRightSelection = DCommon.ExpectType<
+	typeof resultKeepAsRightSelection,
+	DEither.Left<"fail", void> | DEither.Left<"error", Error> | DEither.Left<"success", "result"> | DEither.Right<"fail-task", Error>,
+	"strict"
+>;
+// 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.
+const resultRewriteInformation = DCommon.pipe(
+	myResult,
+	DEither.rewriteInformation({ success: "new-information" }),
+);
+type _CheckResultRewriteInformation = DCommon.ExpectType<
+	typeof resultRewriteInformation,
+	DEither.Fail | DEither.Error<Error> | DEither.Left<"fail-task", Error> | DEither.Right<"new-information", "result">,
+	"strict"
+>;

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

@@ -0,0 +1,72 @@
+/**
+ * @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;
+
+const resultToMaybe = DEither.toMaybe(someFunction());
+type _CheckResultToMaybeLine29 = DCommon.ExpectType<
+	typeof resultToMaybe,
+	DEither.None | DEither.Some<string> | DEither.Some<number>,
+	"strict"
+>;
+
+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.
+const userName = DCommon.pipe(
+	findUser(),
+	DEither.whenIsRight((user) => DEither.success(user.name)),
+);
+type _CheckUserName = DCommon.ExpectType<typeof userName, DEither.None | DEither.Success<string>, "strict">;
+
+// 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.
+const resultSafeCallback = DEither.safeCallback(
+	() => "test" as const,
+);
+type _CheckSafeCallback = DCommon.ExpectType<
+	typeof resultSafeCallback,
+	DEither.SafeCallbackError | DEither.SafeCallbackSuccess<"test">,
+	"strict"
+>;
+// asyncSafeCallback capture aussi les rejets et retourne toujours une Promise de résultat.
+declare function loadValue(): Promise<string>;
+const asyncSafeResult = DEither.asyncSafeCallback(loadValue);
+type _CheckAsyncSafeResult = DCommon.ExpectType<
+	typeof asyncSafeResult,
+	Promise<DEither.SafeCallbackError | DEither.SafeCallbackSuccess<string>>,
+	"strict"
+>;
+
+// 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.

package/docs/concepts/01-fundamental/04-data-structure/01-use.ts

@@ -0,0 +1,22 @@
+/**
+ * @title Contrats de données avec DataStructure.
+ *
+ * Décrire les données attendues et obtenir des valeurs typées après validation.
+ */
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+
+// Une structure porte le même contrat dans TypeScript et au runtime.
+// L’utiliser aux frontières du logiciel pour vérifier les données encore inconnues.
+const userStructure = DDataStructure.object({
+	name: DDataStructure.string(),
+	email: DDataStructure.string([DDataStructure.email()]),
+});
+type User = DDataStructure.StructureValue<typeof userStructure>;
+
+declare const input: unknown;
+const result = userStructure.check(input);
+if (DEither.isRight(result)) {
+	const user: User = DEither.unwrapRight(result);
+}
+// Un Left conserve une erreur structurée lorsque la validation échoue.