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

package/docs/API/10-lang/10-common/index.llms.md

@@ -0,0 +1,244 @@
+## DCommon
+
+Fonctions générales de composition, de transformation, de contrôle de flux et de manipulation des valeurs partagées par les autres domaines DuploJS.
+
+### [DCommon.and](10-and.ts)
+
+Combiner plusieurs prédicats dans une condition qui doit tous les satisfaire.
+ 
+### [DCommon.asserts](10-asserts.ts)
+
+Affirmer une contrainte de type et lever une erreur si le prédicat échoue.
+ 
+### [DCommon.asyncInnerPipe](10-asyncInnerPipe.ts)
+
+Construire une fonction qui enchaîne des opérations synchrones ou asynchrones.
+ 
+### [DCommon.asyncLoop](10-asyncLoop.ts)
+
+Répéter une callback asynchrone jusqu’à `exit`, avec un compteur et une valeur de retour typée.
+ 
+### [DCommon.asyncLoopAccumulator](10-asyncLoopAccumulator.ts)
+
+Répéter une callback asynchrone en faisant circuler un accumulateur et retourner la valeur de `exit`.
+ 
+### [DCommon.asyncPipe](10-asyncPipe.ts)
+
+Exécuter séquentiellement plusieurs transformations en attendant chaque résultat.
+ 
+### [DCommon.callThen](10-callThen.ts)
+
+Appliquer une fonction à une valeur immédiate ou promise, avec gestion optionnelle des erreurs.
+ 
+### [DCommon.cast](10-cast.ts)
+
+Vérifier au niveau du typage qu’une valeur respecte une contrainte attendue.
+ 
+### [DCommon.clone](10-clone.ts)
+
+Copier récursivement les tableaux et objets simples sans modifier la valeur source.
+ 
+### [DCommon.createAsyncRetry](10-createAsyncRetry.ts)
+
+Décorer une fonction asynchrone avec une stratégie de nouvelle tentative.
+ 
+### [DCommon.createBuilder](10-createBuilder.ts)
+
+Configurer des handlers réutilisables pour construire un objet par étapes.
+ 
+### [DCommon.createEnum](10-createEnum.ts)
+
+Créer un enum littéral qui expose ses valeurs, un tuple et un prédicat `has`.
+ 
+### [DCommon.createExternalPromise](10-createExternalPromise.ts)
+
+Exposer les contrôles `resolve` et `reject` d’une promise séparément de sa création.
+ 
+### [DCommon.createFormData](10-createFormData.ts)
+
+Transformer un objet de valeurs en `FormData` en conservant ses valeurs d’entrée typées.
+ 
+### [DCommon.createInterpolation](10-createInterpolation.ts)
+
+Préparer une fonction qui remplace les identifiants entre accolades dans un modèle.
+ 
+### [DCommon.createQueue](10-createQueue.ts)
+
+Créer une file d’attente typée avec une capacité optionnelle.
+ 
+### [DCommon.createTransformer](10-createTransformer.ts)
+
+Créer une fonction de transformation récursive liée à un nom de méthode.
+ 
+### [DCommon.detachObjectMethod](10-detachObjectMethod.ts)
+
+Détacher une méthode d’un objet tout en conservant son contexte d’exécution.
+ 
+### [DCommon.equal](10-equal.ts)
+
+Créer un prédicat d’égalité pour une valeur ou une liste de valeurs littérales.
+ 
+### [DCommon.escapeRegExp](10-escapeRegExp.ts)
+
+Échapper les caractères spéciaux d’une chaîne avant de l’utiliser dans une expression régulière.
+ 
+### [DCommon.falsy](10-falsy.ts)
+
+Identifier les valeurs falsy JavaScript avec un narrowing TypeScript.
+ 
+### [DCommon.forward](10-forward.ts)
+
+Retourner une valeur telle quelle pour la rendre explicite dans une composition.
+ 
+### [DCommon.forwardAsserts](10-forwardAsserts.ts)
+
+Vérifier une valeur et la retourner, ou produire une fonction réutilisable de vérification.
+ 
+### [DCommon.forwardLog](10-forwardLog.ts)
+
+Afficher une valeur puis la retourner pour observer une composition.
+ 
+### [DCommon.infer](10-infer.ts)
+
+Inférer une contrainte à partir d’une valeur littérale dans une expression typée.
+ 
+### [DCommon.innerPipe](10-innerPipe.ts)
+
+Composer plusieurs transformations dans une fonction réutilisable.
+ 
+### [DCommon.instanceOf](10-instanceOf.ts)
+
+Créer un prédicat basé sur un constructeur avec narrowing de l’instance.
+ 
+### [DCommon.isType](10-isType.ts)
+
+Construire un prédicat de type à partir d’un type runtime.
+ 
+### [DCommon.justExec](10-justExec.ts)
+
+Encapsuler une logique impérative locale et affecter directement son résultat.
+ 
+### [DCommon.justReturn](10-justReturn.ts)
+
+Fournir une valeur déjà calculée à une étape de pipe sans écrire de callback.
+ 
+### [DCommon.loop](10-loop.ts)
+
+Répéter une callback synchrone jusqu’à `exit`, avec un compteur et une valeur de retour typée.
+ 
+### [DCommon.loopAccumulator](10-loopAccumulator.ts)
+
+Répéter une callback synchrone en faisant circuler un accumulateur et retourner la valeur de `exit`.
+ 
+### [DCommon.loopAccumulatorFrom](10-loopAccumulatorFrom.ts)
+
+Marquer une valeur initiale pour fixer précisément le type de l’accumulateur d’une boucle.
+ 
+### [DCommon.memo](10-memo.ts)
+
+Évaluer une fonction au premier accès puis mémoriser sa valeur.
+ 
+### [DCommon.memoObject](10-memoObject.ts)
+
+Exposer un objet calculé paresseusement tout en mémorisant son contenu.
+ 
+### [DCommon.memoPromise](10-memoPromise.ts)
+
+Mémoriser le résultat d’un calcul synchrone ou asynchrone.
+ 
+### [DCommon.or](10-or.ts)
+
+Combiner plusieurs prédicats en une condition satisfaite par au moins l’un d’eux.
+ 
+### [DCommon.pipe](10-pipe.ts)
+
+Appliquer une suite de transformations de gauche à droite.
+ 
+### [DCommon.pipeCall](10-pipeCall.ts)
+
+Corriger l’inférence d’une fonction sans générique utilisée dans un pipe.
+ 
+### [DCommon.prepareAsyncPipe](10-prepareAsyncPipe.ts)
+
+Préparer une fabrique de pipelines asynchrones partageant une contrainte d’entrée.
+ 
+### [DCommon.preparePipe](10-preparePipe.ts)
+
+Préparer une fabrique de pipelines partageant une contrainte d’entrée.
+ 
+### [DCommon.promiseAll](10-promiseAll.ts)
+
+Attendre un tuple ou un itérable de promesses en conservant la forme du tuple.
+ 
+### [DCommon.promiseObject](10-promiseObject.ts)
+
+Attendre toutes les propriétés promises d’un objet et reconstruire l’objet résolu.
+ 
+### [DCommon.removeConstraint](10-removeConstraint.ts)
+
+Retirer les contraintes DuploJS d’un type tout en conservant sa forme de valeur.
+ 
+### [DCommon.shameOnYou](10-shameOnYou.ts)
+
+Contourner explicitement une contrainte attendue dans un contrat de type.
+ 
+### [DCommon.simpleClone](10-simpleClone.ts)
+
+Créer une copie superficielle d’une valeur clonable.
+ 
+### [DCommon.stringToBytes](10-stringToBytes.ts)
+
+Convertir une quantité en octets écrite avec une unité ou déjà numérique.
+ 
+### [DCommon.stringToMillisecond](10-stringToMillisecond.ts)
+
+Additionner des durées écrites avec une unité ou exprimées en millisecondes.
+ 
+### [DCommon.tap](10-tap.ts)
+
+Exécuter un traitement secondaire tout en conservant la valeur d’entrée.
+ 
+### [DCommon.timeout](10-timeout.ts)
+
+Créer une promise résolue après un délai en millisecondes.
+ 
+### [DCommon.toCurriedPredicate](10-toCurriedPredicate.ts)
+
+Adapter un prédicat non générique vers la forme curifiée attendue par une fonction.
+ 
+### [DCommon.toJSON](10-toJSON.ts)
+
+Transformer récursivement les valeurs DuploJS vers leur représentation JSON.
+ 
+### [DCommon.toNative](10-toNative.ts)
+
+Transformer récursivement les valeurs DuploJS qui exposent `toNative`.
+ 
+### [DCommon.toRegExp](10-toRegExp.ts)
+
+Convertir une chaîne, un tuple de chaînes ou une expression régulière en `RegExp`.
+ 
+### [DCommon.transformer](10-transformer.ts)
+
+Appliquer récursivement une méthode sans argument aux objets, tableaux et valeurs imbriqués.
+ 
+### [DCommon.truthy](10-truthy.ts)
+
+Identifier les valeurs truthy et retirer les valeurs falsy de leur union.
+ 
+### [DCommon.useAsyncRetry](10-useAsyncRetry.ts)
+
+Réessayer une opération asynchrone selon son résultat et une limite d’essais.
+ 
+### [DCommon.when](10-when.ts)
+
+Transformer une valeur uniquement lorsqu’un prédicat est satisfait.
+ 
+### [DCommon.whenElse](10-whenElse.ts)
+
+Choisir une transformation selon le résultat d’un prédicat.
+ 
+### [DCommon.whenNot](10-whenNot.ts)
+
+Transformer une valeur uniquement lorsqu’un prédicat n’est pas satisfait.
+ 

package/docs/API/10-lang/10-common/index.md

@@ -0,0 +1,3 @@
+## DCommon
+
+Fonctions générales de composition, de transformation, de contrôle de flux et de manipulation des valeurs partagées par les autres domaines DuploJS.

package/docs/API/10-lang/10-dataStructure/10-absolutePath.ts

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.absolutePath
+ *
+ * Construire une contrainte de chemin absolu et l’appliquer à une structure de chaîne.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DPath from "@duplojs/lang/path";
+
+const constraint = DDataStructure.absolutePath();
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.AbsolutePathConstraint,
+	"strict"
+>;
+
+const structure = DDataStructure.string([constraint]);
+const result = structure.check("/src/index.ts");
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	string & DPath.Absolute,
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-allowedCharacters.ts

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.allowedCharacters
+ *
+ * Construire une contrainte de caractères autorisés et l’appliquer à une structure de chaîne.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DString from "@duplojs/lang/string";
+
+const constraint = DDataStructure.allowedCharacters("a-z");
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.AllowedCharactersConstraint<"a-z">,
+	"strict"
+>;
+
+const structure = DDataStructure.string([constraint]);
+const result = structure.check("abc");
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	string & DString.AllowedCharacters<"a-z">,
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-array.ts

@@ -0,0 +1,23 @@
+/**
+ * @title DDataStructure.array
+ *
+ * Construire une structure de tableau à partir de la structure de ses éléments.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const structure = DDataStructure.array(
+	DDataStructure.string(),
+);
+const result = structure.check(["red", "blue"]);
+
+type _CheckStructure = DCommon.ExpectType<
+	typeof structure,
+	DDataStructure.ArrayStructure<readonly string[], readonly []>,
+	"strict"
+>;
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	readonly string[],
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-arrayLengthEqual.ts

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.arrayLengthEqual
+ *
+ * Construire une contrainte de longueur exacte et l’appliquer à une structure de tableau.
+ */
+import type * as DArray from "@duplojs/lang/array";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const constraint = DDataStructure.arrayLengthEqual(3);
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.ArrayLengthEqualConstraint<3>,
+	"strict"
+>;
+
+const structure = DDataStructure.array(DDataStructure.number(), [constraint]);
+const result = structure.check([1, 2, 3]);
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	readonly number[] & DArray.LengthEqual<3>,
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-betweenThan.ts

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.betweenThan
+ *
+ * Construire une contrainte de nombre strictement compris entre deux bornes.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DNumber from "@duplojs/lang/number";
+
+const constraint = DDataStructure.betweenThan(1, 3);
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.BetweenThanConstraint<1, 3>,
+	"strict"
+>;
+
+const structure = DDataStructure.number([constraint]);
+const result = structure.check(2);
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	number & DNumber.GreaterThan<1> & DNumber.LessThan<3>,
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-betweenThanOrEqual.ts

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.betweenThanOrEqual
+ *
+ * Construire une contrainte de nombre compris entre deux bornes inclusives.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DNumber from "@duplojs/lang/number";
+
+const constraint = DDataStructure.betweenThanOrEqual(1, 3);
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.BetweenThanOrEqualConstraint<1, 3>,
+	"strict"
+>;
+
+const structure = DDataStructure.number([constraint]);
+const result = structure.check(1);
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	number & DNumber.GreaterThanOrEqual<1> & DNumber.LessThanOrEqual<3>,
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-bigint.ts

@@ -0,0 +1,22 @@
+/**
+ * @title DDataStructure.bigint
+ *
+ * Construire une structure représentant des valeurs `bigint`.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const structure = DDataStructure.bigint();
+const result = structure.check(42n);
+
+// La structure représente le type indiqué par son contrat.
+type _CheckStructure = DCommon.ExpectType<
+	typeof structure,
+	DDataStructure.TypeStructure<bigint, readonly []>,
+	"strict"
+>;
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	bigint,
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-boolean.ts

@@ -0,0 +1,22 @@
+/**
+ * @title DDataStructure.boolean
+ *
+ * Construire une structure représentant des valeurs booléennes.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const structure = DDataStructure.boolean();
+const result = structure.check(true);
+
+// La structure représente le type indiqué par son contrat.
+type _CheckStructure = DCommon.ExpectType<
+	typeof structure,
+	DDataStructure.TypeStructure<boolean, readonly []>,
+	"strict"
+>;
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	boolean,
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-createCodec.ts

@@ -0,0 +1,45 @@
+/**
+ * @title DDataStructure.createCodec
+ *
+ * Définir la conversion entre la valeur interne d’un type fondamental et sa représentation encodée.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DString from "@duplojs/lang/string";
+
+// Ce codec représente les nombres en chaînes numériques.
+// Le prédicat décrit la forme encodée que `decode` accepte et que `encode`
+// doit produire.
+const numberStringCodec = DDataStructure.createCodec(
+	DDataStructure.TheNumber,
+	(data): data is string => (
+		typeof data === "string"
+		&& DString.isNumber(data)
+	),
+	(number) => number.toString(),
+	(encodedNumber) => Number(encodedNumber),
+);
+
+// Le type du codec conserve à la fois le type fondamental représenté
+// et le type de sa valeur externe.
+type _CheckCodec = DCommon.ExpectType<
+	typeof numberStringCodec,
+	DDataStructure.Codec<DDataStructure.TheNumber, string>,
+	"strict"
+>;
+
+// `predicateEncode` est également un prédicat TypeScript pour la valeur encodée.
+const unknownEncodedValue: unknown = "42";
+if (numberStringCodec.predicateEncode(unknownEncodedValue)) {
+	type _CheckEncodedValue = DCommon.ExpectType<
+		typeof unknownEncodedValue,
+		string,
+		"strict"
+	>;
+}
+
+// `encode` transforme une valeur du type fondamental en représentation externe.
+const encodedValue = numberStringCodec.encode(42);
+
+// `decode` vérifie la représentation externe puis reconstruit la valeur interne.
+const decodedValue = numberStringCodec.decode("42");

package/docs/API/10-lang/10-dataStructure/10-createCodecs.ts

@@ -0,0 +1,134 @@
+/**
+ * @title DDataStructure.createCodecs
+ *
+ * Regrouper des codecs dans un contexte indexé par leurs types fondamentaux.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+
+const numberStringCodec = DDataStructure.createCodec(
+	DDataStructure.TheNumber,
+	(data): data is string => typeof data === "string",
+	(number) => number.toString(),
+	(encodedNumber) => Number(encodedNumber),
+);
+
+const booleanStringCodec = DDataStructure.createCodec(
+	DDataStructure.TheBoolean,
+	(data): data is string => data === "true" || data === "false",
+	(boolean) => boolean.toString(),
+	(encodedBoolean) => encodedBoolean === "true",
+);
+
+// Le mapper conserve les noms des codecs et leurs types précis.
+const codecs = DDataStructure.createCodecs({
+	number: numberStringCodec,
+	boolean: booleanStringCodec,
+});
+
+type _CheckCodecs = DCommon.ExpectType<
+	typeof codecs,
+	DDataStructure.Codecs<{
+		number: typeof numberStringCodec;
+		boolean: typeof booleanStringCodec;
+	}>,
+	"strict"
+>;
+
+// Le contexte mémorisé permet de retrouver un codec à partir du type fondamental.
+const numberCodecFromContext = codecs.context.value.get(DDataStructure.TheNumber);
+const booleanCodecFromContext = codecs.context.value.get(DDataStructure.TheBoolean);
+
+// `EncodedValue` applique le contexte aux valeurs qui correspondent à un codec.
+type _CheckEncodedNumber = DCommon.ExpectType<
+	DDataStructure.EncodedValue<number, typeof codecs>,
+	string,
+	"strict"
+>;
+type _CheckEncodedBoolean = DCommon.ExpectType<
+	DDataStructure.EncodedValue<boolean, typeof codecs>,
+	string,
+	"strict"
+>;
+
+// Une valeur sans codec associé conserve sa représentation d’origine.
+type _CheckUnencodedNull = DCommon.ExpectType<
+	DDataStructure.EncodedValue<null, typeof codecs>,
+	null,
+	"strict"
+>;
+
+// Le même contexte peut être fourni à une structure pour encoder et décoder
+// plusieurs types fondamentaux avec leurs codecs respectifs.
+const structure = DDataStructure.object({
+	amount: DDataStructure.number(),
+	active: DDataStructure.boolean(),
+});
+const encoded = structure.encode(codecs, {
+	amount: 12.5,
+	active: true,
+});
+const decoded = structure.decode(codecs, {
+	amount: "12.5",
+	active: "true",
+});
+
+// Le retour est un `Either` : la branche de droite contient la valeur encodée,
+// tandis que les branches de gauche décrivent une erreur asynchrone ou métier.
+type _CheckEncodedResult = DCommon.ExpectType<
+	typeof encoded,
+	| DEither.Right<
+		"encode-success",
+		{
+			readonly amount: string;
+			readonly active: string;
+		}
+	>
+	| DEither.Left<"async-error", DDataStructure.ErrorPromise>
+	| DEither.Left<"encode-error", DDataStructure.Error>,
+	"strict"
+>;
+
+type _CheckDecodedResult = DCommon.ExpectType<
+	typeof decoded,
+	| DEither.Right<
+		"decode-success",
+		{
+			readonly amount: number;
+			readonly active: boolean;
+		}
+	>
+	| DEither.Left<"async-error", DDataStructure.ErrorPromise>
+	| DEither.Left<"decode-error", DDataStructure.Error>,
+	"strict"
+>;
+
+// Après extraction de la branche de succès, les codecs sont visibles dans
+// le type de sortie : les deux propriétés externes sont des chaînes.
+const encodedValue = DCommon.pipe(
+	encoded,
+	DEither.unwrapByInformationOrThrow("encode-success"),
+);
+type _CheckEncodedValue = DCommon.ExpectType<
+	typeof encodedValue,
+	{
+		readonly amount: string;
+		readonly active: string;
+	},
+	"strict"
+>;
+
+// Le décodage reconstruit le type interne de la structure.
+const decodedValue = DCommon.pipe(
+	decoded,
+	DEither.unwrapByInformationOrThrow("decode-success"),
+);
+type _CheckDecodedValue = DCommon.ExpectType<
+	typeof decodedValue,
+	{
+		readonly amount: number;
+		readonly active: boolean;
+	},
+	"strict"
+>;