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

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.

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

@@ -0,0 +1,86 @@
+/**
+ * @title Contraintes de validation dans les structures.
+ *
+ * Ajouter et cumuler des contraintes compatibles, fournies ou personnalisées.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DString from "@duplojs/lang/string";
+import type * as DNumber from "@duplojs/lang/number";
+import type * as DArray from "@duplojs/lang/array";
+
+// Une structure vérifie la nature de la donnée, puis ses propriétés supplémentaires.
+// Les contraintes sont vérifiées au runtime et enrichissent le type obtenu par StructureValue.
+// Toute structure peut en recevoir, à condition que la contrainte soit compatible.
+
+const emailStructure = DDataStructure.string([DDataStructure.email()]);
+type _CheckEmailStructure = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof emailStructure>,
+	string & DString.Email,
+	"strict"
+>;
+
+// Une contrainte ne remplace pas le type de base.
+// Elle apporte une information supplémentaire garantie après validation.
+
+const ageStructure = DDataStructure.number([
+	DDataStructure.integer(),
+	DDataStructure.greaterThanOrEqual(18),
+]);
+type _CheckAgeStructure = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof ageStructure>,
+	number & DNumber.Integer & DNumber.GreaterThanOrEqual<18>,
+	"strict"
+>;
+
+type Age = DDataStructure.StructureValue<typeof ageStructure>;
+
+// Plusieurs contraintes peuvent être cumulées.
+// Toutes doivent être vérifiées pour que la donnée soit valide.
+
+const usernameStructure = DDataStructure.string([
+	DDataStructure.minCharacters(3),
+	DDataStructure.trimmed(),
+]);
+type _CheckUsernameStructure = DCommon.ExpectType<DDataStructure.StructureValue<typeof usernameStructure>, string & DString.MinCharacters<3> & DString.Trimmed, "strict">;
+
+// Les contraintes ne concernent pas uniquement les `TypeStructure`.
+// Elles peuvent s'appliquer aux autres structures comme les tableaux.
+
+const tagsStructure = DDataStructure.array(
+	DDataStructure.string(),
+	[DDataStructure.minElements(1)],
+);
+type _CheckTagsStructure = DCommon.ExpectType<DDataStructure.StructureValue<typeof tagsStructure>, readonly string[] & DArray.MinElements<1>, "strict">;
+
+// Une contrainte peut également être ajoutée après la création d'une structure.
+// La structure originale n'est pas modifiée.
+
+const stringStructure = DDataStructure.string();
+type _CheckStringStructure = DCommon.ExpectType<DDataStructure.StructureValue<typeof stringStructure>, string, "strict">;
+
+const constrainedStringStructure = stringStructure.addConstraint(
+	DDataStructure.email(),
+);
+type _CheckConstrainedStringStructure = DCommon.ExpectType<DDataStructure.StructureValue<typeof constrainedStringStructure>, string & DString.Email, "strict">;
+
+// `refine` permet de définir une contrainte spécifique au domaine.
+// Un type predicate permet également d'affiner le type produit par la structure.
+
+type UserId = `user:${string}`;
+
+const userIdStructure = DDataStructure.string([DDataStructure.refine(DString.startsWith("user:"))]);
+type _CheckUserIdStructure = DCommon.ExpectType<DDataStructure.StructureValue<typeof userIdStructure>, UserId, "strict">;
+
+// Une contrainte ne peut être utilisée que sur une structure compatible.
+
+// @ts-expect-error `positive` est une contrainte de nombre.
+DDataStructure.string([DDataStructure.positive()]);
+
+// @ts-expect-error `email` est une contrainte de string.
+DDataStructure.number([DDataStructure.email()]);
+
+// La compatibilité est également vérifiée avec `addConstraint`.
+
+// @ts-expect-error une structure de tableau ne peut pas recevoir une contrainte de string.
+DDataStructure.array(DDataStructure.string()).addConstraint(DDataStructure.email());

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

@@ -0,0 +1,104 @@
+/**
+ * @title Validation des données entrantes.
+ *
+ * Vérification, conversion et narrowing aux frontières du logiciel, en synchrone ou asynchrone.
+ */
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DString from "@duplojs/lang/string";
+
+// La structure décrit la donnée attendue à la fois dans TypeScript et au runtime.
+// Les opérations ci-dessous s’appliquent aux frontières du logiciel, avant de considérer
+// une donnée externe comme fiable.
+const componentStructure = DDataStructure.object({
+	id: DDataStructure.bigint(),
+	name: DDataStructure.string(),
+	alt: DDataStructure.optional(
+		DDataStructure.string(),
+	),
+	image: DDataStructure.object({
+		src: DDataStructure.string([DDataStructure.url()]),
+	}),
+});
+
+// Le type TypeScript correspondant à une structure peut être récupéré
+// avec `StructureValue`.
+//
+type Component = DDataStructure.StructureValue<typeof componentStructure>;
+type _CheckComponent = DCommon.ExpectType<
+	Component,
+	{
+		readonly id: bigint;
+		readonly name: string;
+		readonly alt?: string | undefined;
+		readonly image: { readonly src: string & DString.Url };
+	},
+	"strict"
+>;
+
+declare const unknownComponent: unknown;
+
+// check, decode et encode retournent un Either : donnée valide ou erreur structurée.
+// `check` valide une donnée déjà dans sa représentation interne.
+//
+// Il est principalement utilisé lorsqu'une donnée provient d'une source
+// non fiable mais ne nécessite aucune transformation de représentation.
+const checkResult = componentStructure.check(
+	unknownComponent,
+);
+
+// `decode` transforme une représentation externe vers la représentation
+// interne décrite par la structure, puis valide la donnée obtenue.
+//
+// Ici, `codecsJson` permet notamment de transformer `string` en `bigint`.
+const decodeResult = componentStructure.decode(
+	DDataStructure.codecsJson,
+	{
+		id: "42",
+		name: "Header",
+		image: {
+			src: "https://duplojs.dev/image.png",
+		},
+	},
+);
+
+declare const component: Component;
+
+// `encode` réalise l'opération inverse de `decode`.
+//
+// Il vérifie la donnée interne avant de la transformer vers la représentation attendue
+// par le système externe.
+//
+// Ici, `codecsJson` transforme notamment `bigint` en `string`.
+const encodeResult = componentStructure.encode(
+	DDataStructure.codecsJson,
+	component,
+);
+
+declare const value: unknown;
+
+// `is` permet de vérifier simplement si une donnée respecte la structure.
+//
+// Contrairement à `check`, il ne retourne pas les détails de l'erreur.
+// Il agit également comme un type predicate TypeScript.
+if (componentStructure.is(value)) {
+	type _CheckNarrowedComponent = DCommon.ExpectType<typeof value, Component, "strict">;
+	void value;
+}
+
+// Les variantes asyncCheck, asyncDecode et asyncEncode attendent les traitements asynchrones.
+// Une opération synchrone rencontrant une Promise retourne un Left "async-error".
+// is retourne false dans ce cas ; il ne peut pas attendre une validation asynchrone.
+const asyncCheckResult = componentStructure.asyncCheck(
+	unknownComponent,
+);
+
+const asyncDecodeResult = componentStructure.asyncDecode(
+	DDataStructure.codecsJson,
+	unknownComponent,
+);
+
+const asyncEncodeResult = componentStructure.asyncEncode(
+	DDataStructure.codecsJson,
+	component,
+);

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

@@ -0,0 +1,162 @@
+/**
+ * @title Changement de représentation avec des codecs.
+ *
+ * Encoder et décoder les données avec un même contrat, selon leur type fondamental.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DString from "@duplojs/lang/string";
+import type * as DEither from "@duplojs/lang/either";
+import type * as DNumber from "@duplojs/lang/number";
+
+// Un codec fait transiter les données entre deux représentations d’une même structure.
+// encode convertit la représentation interne vers l’externe ; decode effectue l’inverse.
+// Le contexte associe les codecs aux types fondamentaux pendant le parcours de la structure.
+
+// Les `FundamentalType` représentent les familles fondamentales de données.
+//
+// Par exemple :
+// `number()` utilise `TheNumber`.
+// `string()` utilise `TheString`.
+// `bigint()` utilise `TheBigint`.
+//
+// Le codec utilise ce `FundamentalType` comme repère pour savoir
+// quelles valeurs il doit transformer.
+
+// Codec : number <-> string
+const numberStringCodec = DDataStructure.createCodec(
+	DDataStructure.TheNumber,
+
+	// Décrit la représentation externe acceptée par le codec.
+	(data) => (
+		typeof data === "string"
+		&& DString.isNumber(data)
+	),
+
+	// encode : number -> string
+	DString.to,
+
+	// decode : string -> number
+	(data) => Number(data),
+);
+
+// Les codecs sont regroupés dans un contexte.
+// Un `FundamentalType` ne peut avoir qu'un seul codec dans ce contexte.
+const codecs = DDataStructure.createCodecs({
+	number: numberStringCodec,
+});
+
+// Une seule structure décrit la donnée.
+// Les codecs vont modifier sa représentation sans nécessiter
+// de créer une seconde structure pour la forme encodée.
+const productStructure = DDataStructure.object({
+	name: DDataStructure.string(),
+	price: DDataStructure.number(),
+	quantity: DDataStructure.number([
+		DDataStructure.integer(),
+		DDataStructure.positive(),
+	]),
+});
+
+const encodedProduct = productStructure.encode(
+	codecs,
+	{
+		name: "Keyboard",
+		price: 99.9,
+		quantity: 2,
+	},
+);
+type _CheckEncodedProductLine68 = DCommon.ExpectType<
+	typeof encodedProduct,
+	DEither.Right<
+		"encode-success",
+		{
+			readonly name: string;
+			readonly price: string & DString.Number;
+			readonly quantity: string & DString.Number;
+		}
+	>
+| DEither.Left<"async-error", DDataStructure.ErrorPromise>
+| DEither.Left<"encode-error", DDataStructure.Error>,
+	"strict"
+>;
+
+// Pendant l'encode, la structure est parcourue.
+//
+// `name` utilise `TheString`.
+// Aucun codec n'est enregistré pour `TheString`, la valeur reste inchangée.
+//
+// `price` et `quantity` utilisent `TheNumber`.
+// Le codec associé à `TheNumber` transforme donc automatiquement
+// leurs valeurs de `number` vers `string`.
+
+const decodedProduct = productStructure.decode(
+	codecs,
+	{
+		name: "Keyboard",
+		price: "99.9",
+		quantity: "2",
+	},
+);
+type _CheckDecodedProductLine96 = DCommon.ExpectType<
+	typeof decodedProduct,
+	DEither.Right<
+		"decode-success",
+		{
+			readonly name: string;
+			readonly price: number;
+			readonly quantity: number & DNumber.Integer & DNumber.Positive;
+		}
+	>
+| DEither.Left<"async-error", DDataStructure.ErrorPromise>
+| DEither.Left<"decode-error", DDataStructure.Error>,
+	"strict"
+>;
+
+// Le decode parcourt exactement la même structure dans le sens inverse.
+//
+// Le codec retrouve les valeurs associées à `TheNumber`, vérifie que
+// leur représentation externe est valide, puis les transforme en `number`.
+//
+// Les contraintes de la structure sont ensuite toujours appliquées.
+// `"2"` devient donc `2`, puis `integer()` et `positive()` sont vérifiés.
+
+// Ce principe permet de définir différents systèmes de représentation
+// sans modifier les structures métier.
+//
+// `codecsString` applique ce principe pour représenter les types
+// fondamentaux sous forme de chaînes de caractères.
+//
+// `codecsJson` applique le même principe aux types qui ne possèdent pas
+// naturellement de représentation JSON, notamment :
+//
+// bigint -> string
+// date   -> string
+// time   -> string
+
+const stringEncodedProduct = productStructure.encode(
+	DDataStructure.codecsString,
+	{
+		name: "Keyboard",
+		price: 99.9,
+		quantity: 2,
+	},
+);
+
+// Le principe reste toujours le même :
+//
+//        état interne
+//             |
+//           encode
+//             |
+//             v
+//        état externe
+//             |
+//           decode
+//             |
+//             v
+//        état interne
+//
+// La `DataStructure` définit la forme de la donnée.
+// Le `FundamentalType` identifie la famille de valeur.
+// Le `Codec` définit comment cette famille transite entre les deux états.

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

@@ -0,0 +1,57 @@
+/**
+ * @title Contrats de données récursifs.
+ *
+ * Références différées et cohérence entre un type déclaré et sa structure runtime.
+ */
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DEither from "@duplojs/lang/either";
+
+// Une structure récursive se référence elle-même. Le type attendu est déclaré en amont
+// pour permettre à TypeScript de typer cette dépendance récursive.
+interface Tree {
+	readonly value: string;
+	readonly children: readonly Tree[];
+}
+
+const treeStructure: DDataStructure.Structure<Tree> = DDataStructure.object({
+	value: DDataStructure.string(),
+	children: DDataStructure.array(
+		DDataStructure.lazy(() => treeStructure),
+	),
+}).contract();
+type _CheckTreeStructure = DCommon.ExpectType<DDataStructure.StructureValue<typeof treeStructure>, Tree, "strict">;
+
+// `lazy` retarde la résolution de `treeStructure`.
+//
+// Sans lui, la construction de la structure devrait accéder immédiatement
+// à une variable qui est elle-même en train d'être construite.
+//
+// Le type doit être déclaré en amont car TypeScript ne peut pas inférer
+// une structure qui dépend récursivement de son propre type.
+//
+// `contract()` compare strictement le type attendu par `Structure<Tree>`
+// avec le type obtenu par l'inférence de la structure.
+//
+// Si la structure ne correspond pas exactement à `Tree`, l'appel à
+// `contract()` produit une erreur de typage. Cela évite qu'une interface
+// déclarée manuellement diverge de sa représentation runtime.
+
+const tree = {
+	value: "root",
+	children: [
+		{
+			value: "child",
+			children: [],
+		},
+	],
+};
+
+const result = treeStructure.check(tree);
+type _CheckTreeResult = DCommon.ExpectType<
+	typeof result,
+	DEither.Left<"async-error", DDataStructure.ErrorPromise>
+		| DEither.Left<"check-error", DDataStructure.Error>
+		| DEither.Right<"check-success", Tree>,
+	"strict"
+>;