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

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.

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

@@ -0,0 +1,244 @@
+/**
+ * @title Composition des contrats de données.
+ *
+ * Construire et réutiliser des structures pour décrire des données simples ou composées.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+// Une Structure associe un type TypeScript à une représentation capable de vérifier la donnée.
+// Une TypeStructure repose sur un Type ; les autres structures composent plusieurs contrats.
+
+const nameStructure = DDataStructure.string();
+type _CheckNameStructure = DCommon.ExpectType<DDataStructure.StructureValue<typeof nameStructure>, string, "strict">;
+
+const ageStructure = DDataStructure.number();
+type _CheckAgeStructure = DCommon.ExpectType<DDataStructure.StructureValue<typeof ageStructure>, number, "strict">;
+
+const activeStructure = DDataStructure.boolean();
+type _CheckActiveStructure = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof activeStructure>,
+	boolean,
+	"strict"
+>;
+
+// Les structures simples comme `string`, `number` ou `boolean` sont des
+// `TypeStructure`. Elles représentent directement un type fondamental.
+
+const userKindStructure = DDataStructure.literal("user");
+type _CheckUserKindStructure = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof userKindStructure>,
+	"user",
+	"strict"
+>;
+
+// `literal` produit également une `TypeStructure` lorsqu'une seule valeur
+// est représentée.
+
+const roleStructure = DDataStructure.literal([
+	"admin",
+	"member",
+	"guest",
+]);
+type _CheckRoleStructure = DCommon.ExpectType<DDataStructure.StructureValue<typeof roleStructure>, "admin" | "member" | "guest", "strict">;
+
+// Lorsque plusieurs valeurs sont représentées, `literal` construit une
+// `UnionStructure` composée de plusieurs `TypeStructure`.
+
+const addressStructure = DDataStructure.object({
+	street: DDataStructure.string(),
+	city: DDataStructure.string(),
+	zipCode: DDataStructure.string(),
+});
+type _CheckAddressStructure = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof addressStructure>,
+	{
+		readonly street: string;
+		readonly city: string;
+		readonly zipCode: string;
+	},
+	"strict"
+>;
+
+// `ObjectStructure` compose plusieurs structures pour représenter les
+// propriétés d'un objet.
+
+const userStructure = DDataStructure.object({
+	name: nameStructure,
+	age: ageStructure,
+	active: activeStructure,
+	role: roleStructure,
+	address: addressStructure,
+});
+type _CheckUserStructure = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof userStructure>,
+	{
+		readonly name: string;
+		readonly age: number;
+		readonly active: boolean;
+		readonly role: "admin" | "member" | "guest";
+		readonly address: DDataStructure.StructureValue<typeof addressStructure>;
+	},
+	"strict"
+>;
+
+// Une structure déjà définie peut et doit être réutilisée pour construire
+// des structures plus complexes.
+
+const usersStructure = DDataStructure.array(
+	userStructure,
+);
+type _CheckUsersStructure = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof usersStructure>,
+	readonly DDataStructure.StructureValue<typeof userStructure>[],
+	"strict"
+>;
+
+// `array` applique une même structure à chaque élément du tableau.
+
+const profileStructure = DDataStructure.object({
+	name: DDataStructure.string(),
+	bio: DDataStructure.optional(
+		DDataStructure.string(),
+	),
+});
+type _CheckProfileStructure = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof profileStructure>,
+	{
+		readonly name: string;
+		readonly bio?: string | undefined;
+	},
+	"strict"
+>;
+
+type Profile = DDataStructure.StructureValue<typeof profileStructure>;
+
+// `optional` ajoute `undefined` à une structure.
+// Dans un `ObjectStructure`, cela permet également d'omettre la propriété.
+
+const sessionStructure = DDataStructure.object({
+	user: DDataStructure.nullable(
+		userStructure,
+	),
+});
+type _CheckSessionStructure = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof sessionStructure>,
+	{ readonly user: DDataStructure.StructureValue<typeof userStructure> | null },
+	"strict"
+>;
+
+// `nullable` ajoute `null` à une structure sans rendre la propriété optionnelle.
+
+const identifierStructure = DDataStructure.union([
+	DDataStructure.string(),
+	DDataStructure.number(),
+]);
+type _CheckIdentifierStructure = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof identifierStructure>,
+	string | number,
+	"strict"
+>;
+
+// `union` représente plusieurs structures possibles.
+
+const eventStructure = DDataStructure.union([
+	DDataStructure.object({
+		type: DDataStructure.literal("user-created"),
+		user: userStructure,
+	}),
+	DDataStructure.object({
+		type: DDataStructure.literal("user-deleted"),
+		userId: identifierStructure,
+	}),
+]);
+interface UserCreatedEvent {
+	readonly type: "user-created";
+	readonly user: DDataStructure.StructureValue<typeof userStructure>;
+}
+interface UserDeletedEvent {
+	readonly type: "user-deleted";
+	readonly userId: string | number;
+}
+type _CheckEventStructure = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof eventStructure>,
+	UserCreatedEvent | UserDeletedEvent,
+	"strict"
+>;
+
+// Les unions peuvent représenter plusieurs formes d'objets.
+// Des valeurs littérales peuvent être utilisées pour créer une union discriminée.
+
+const translationsStructure = DDataStructure.record(
+	DDataStructure.literal([
+		"fr",
+		"en",
+	]),
+	DDataStructure.string(),
+);
+type _CheckTranslationsStructure = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof translationsStructure>,
+	{
+		readonly fr: string;
+		readonly en: string;
+	},
+	"strict"
+>;
+
+// `record` représente un objet dont les clés possibles et les valeurs
+// sont elles-mêmes décrites par des structures.
+
+const updateUserStructure = DDataStructure.partial(
+	userStructure,
+);
+type _CheckUpdateUserStructure = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof updateUserStructure>,
+	{
+		readonly name?: string | undefined;
+		readonly age?: number | undefined;
+		readonly active?: boolean | undefined;
+		readonly role?: "admin" | "member" | "guest" | undefined;
+		readonly address?: DDataStructure.StructureValue<typeof addressStructure> | undefined;
+	},
+	"strict"
+>;
+
+// `partial` transforme toutes les propriétés d'un `ObjectStructure`
+// en propriétés optionnelles.
+
+const requiredProfileStructure = DDataStructure.required(
+	profileStructure,
+);
+type _CheckRequiredProfileStructure = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof requiredProfileStructure>,
+	{
+		readonly name: string;
+		readonly bio: string;
+	},
+	"strict"
+>;
+
+// `required` réalise l'opération inverse et rend les propriétés obligatoires.
+
+const persistedUserStructure = DDataStructure.extend(
+	userStructure,
+	{
+		id: identifierStructure,
+		createdAt: DDataStructure.string(),
+	},
+);
+type _CheckPersistedUserStructure = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof persistedUserStructure>,
+	{
+		readonly name: string;
+		readonly age: number;
+		readonly active: boolean;
+		readonly role: "admin" | "member" | "guest";
+		readonly address: DDataStructure.StructureValue<typeof addressStructure>;
+		readonly id: string | number;
+		readonly createdAt: string;
+	},
+	"strict"
+>;
+
+// `extend` crée un nouvel `ObjectStructure` en ajoutant des propriétés
+// à une structure objet existante.