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

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,193 @@
+/**
+ * @title Composition des contrats de données.
+ *
+ * Construire et réutiliser des structures pour décrire des données simples ou composées.
+ */
+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.
+
+// string
+const nameStructure = DDataStructure.string();
+
+// number
+const ageStructure = DDataStructure.number();
+
+// boolean
+const activeStructure = DDataStructure.boolean();
+
+// Les structures simples comme `string`, `number` ou `boolean` sont des
+// `TypeStructure`. Elles représentent directement un type fondamental.
+
+// "user"
+const userKindStructure = DDataStructure.literal("user");
+
+// `literal` produit également une `TypeStructure` lorsqu'une seule valeur
+// est représentée.
+
+// "admin" | "member" | "guest"
+const roleStructure = DDataStructure.literal([
+	"admin",
+	"member",
+	"guest",
+]);
+
+// Lorsque plusieurs valeurs sont représentées, `literal` construit une
+// `UnionStructure` composée de plusieurs `TypeStructure`.
+
+// {
+//     readonly street: string;
+//     readonly city: string;
+//     readonly zipCode: string;
+// }
+const addressStructure = DDataStructure.object({
+	street: DDataStructure.string(),
+	city: DDataStructure.string(),
+	zipCode: DDataStructure.string(),
+});
+
+// `ObjectStructure` compose plusieurs structures pour représenter les
+// propriétés d'un objet.
+
+// {
+//     readonly name: string;
+//     readonly age: number;
+//     readonly active: boolean;
+//     readonly role: "admin" | "member" | "guest";
+//     readonly address: Address;
+// }
+const userStructure = DDataStructure.object({
+	name: nameStructure,
+	age: ageStructure,
+	active: activeStructure,
+	role: roleStructure,
+	address: addressStructure,
+});
+
+// Une structure déjà définie peut et doit être réutilisée pour construire
+// des structures plus complexes.
+
+// readonly User[]
+const usersStructure = DDataStructure.array(
+	userStructure,
+);
+
+// `array` applique une même structure à chaque élément du tableau.
+
+// {
+//     readonly name: string;
+//     readonly bio?: string | undefined;
+// }
+const profileStructure = DDataStructure.object({
+	name: DDataStructure.string(),
+	bio: DDataStructure.optional(
+		DDataStructure.string(),
+	),
+});
+
+type Profile = DDataStructure.StructureValue<typeof profileStructure>;
+
+// `optional` ajoute `undefined` à une structure.
+// Dans un `ObjectStructure`, cela permet également d'omettre la propriété.
+
+// {
+//     readonly user: User | null;
+// }
+const sessionStructure = DDataStructure.object({
+	user: DDataStructure.nullable(
+		userStructure,
+	),
+});
+
+// `nullable` ajoute `null` à une structure sans rendre la propriété optionnelle.
+
+// string | number
+const identifierStructure = DDataStructure.union([
+	DDataStructure.string(),
+	DDataStructure.number(),
+]);
+
+// `union` représente plusieurs structures possibles.
+
+// {
+//     readonly type: "user-created";
+//     readonly user: User;
+// }
+// |
+// {
+//     readonly type: "user-deleted";
+//     readonly userId: string | number;
+// }
+const eventStructure = DDataStructure.union([
+	DDataStructure.object({
+		type: DDataStructure.literal("user-created"),
+		user: userStructure,
+	}),
+	DDataStructure.object({
+		type: DDataStructure.literal("user-deleted"),
+		userId: identifierStructure,
+	}),
+]);
+
+// Les unions peuvent représenter plusieurs formes d'objets.
+// Des valeurs littérales peuvent être utilisées pour créer une union discriminée.
+
+// {
+//     readonly fr: string;
+//     readonly en: string;
+// }
+const translationsStructure = DDataStructure.record(
+	DDataStructure.literal([
+		"fr",
+		"en",
+	]),
+	DDataStructure.string(),
+);
+
+// `record` représente un objet dont les clés possibles et les valeurs
+// sont elles-mêmes décrites par des structures.
+
+// {
+//     readonly name?: string | undefined;
+//     readonly age?: number | undefined;
+//     readonly active?: boolean | undefined;
+//     readonly role?: "admin" | "member" | "guest" | undefined;
+//     readonly address?: Address | undefined;
+// }
+const updateUserStructure = DDataStructure.partial(
+	userStructure,
+);
+
+// `partial` transforme toutes les propriétés d'un `ObjectStructure`
+// en propriétés optionnelles.
+
+// {
+//     readonly name: string;
+//     readonly bio: string;
+// }
+const requiredProfileStructure = DDataStructure.required(
+	profileStructure,
+);
+
+// `required` réalise l'opération inverse et rend les propriétés obligatoires.
+
+// {
+//     readonly name: string;
+//     readonly age: number;
+//     readonly active: boolean;
+//     readonly role: "admin" | "member" | "guest";
+//     readonly address: Address;
+//     readonly id: string | number;
+//     readonly createdAt: string;
+// }
+const persistedUserStructure = DDataStructure.extend(
+	userStructure,
+	{
+		id: identifierStructure,
+		createdAt: DDataStructure.string(),
+	},
+);
+
+// `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,78 @@
+/**
+ * @title Contraintes de validation dans les structures.
+ *
+ * Ajouter et cumuler des contraintes compatibles, fournies ou personnalisées.
+ */
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+// 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.
+
+// string & DString.Email
+const emailStructure = DDataStructure.string([DDataStructure.email()]);
+
+// Une contrainte ne remplace pas le type de base.
+// Elle apporte une information supplémentaire garantie après validation.
+
+// number & DNumber.Integer & DNumber.GreaterThanOrEqual<18>
+const ageStructure = DDataStructure.number([
+	DDataStructure.integer(),
+	DDataStructure.greaterThanOrEqual(18),
+]);
+
+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.
+
+// string & DString.MinCharacters<3> & DString.Trimmed
+const usernameStructure = DDataStructure.string([
+	DDataStructure.minCharacters(3),
+	DDataStructure.trimmed(),
+]);
+
+// Les contraintes ne concernent pas uniquement les `TypeStructure`.
+// Elles peuvent s'appliquer aux autres structures comme les tableaux.
+
+// readonly string[] & DArray.MinElements<1>
+const tagsStructure = DDataStructure.array(
+	DDataStructure.string(),
+	[DDataStructure.minElements(1)],
+);
+
+// Une contrainte peut également être ajoutée après la création d'une structure.
+// La structure originale n'est pas modifiée.
+
+// string
+const stringStructure = DDataStructure.string();
+
+// string & DString.Email
+const constrainedStringStructure = stringStructure.addConstraint(
+	DDataStructure.email(),
+);
+
+// `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}`;
+
+// `user:${string}`
+const userIdStructure = DDataStructure.string([
+	DDataStructure.refine(
+		(value): value is UserId => value.startsWith("user:"),
+	),
+]);
+
+// 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,100 @@
+/**
+ * @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";
+
+// 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`.
+//
+// {
+//     readonly id: bigint;
+//     readonly name: string;
+//     readonly alt?: string | undefined;
+//     readonly image: {
+//         readonly src: string & DString.Url;
+//     };
+// }
+type Component = DDataStructure.StructureValue<typeof componentStructure>;
+
+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)) {
+	// Component
+	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,151 @@
+/**
+ * @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 * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DString from "@duplojs/lang/string";
+
+// 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(),
+	]),
+});
+
+// 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>
+const encodedProduct = productStructure.encode(
+	codecs,
+	{
+		name: "Keyboard",
+		price: 99.9,
+		quantity: 2,
+	},
+);
+
+// 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`.
+
+// 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>
+const decodedProduct = productStructure.decode(
+	codecs,
+	{
+		name: "Keyboard",
+		price: "99.9",
+		quantity: "2",
+	},
+);
+
+// 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,48 @@
+/**
+ * @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";
+
+// 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[];
+}
+
+// Tree
+const treeStructure: DDataStructure.Structure<Tree> = DDataStructure.object({
+	value: DDataStructure.string(),
+	children: DDataStructure.array(
+		DDataStructure.lazy(() => treeStructure),
+	),
+}).contract();
+
+// `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);