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

package/docs/API/10-lang/10-common/10-toCurriedPredicate.ts

@@ -0,0 +1,28 @@
+/**
+ * @title DCommon.toCurriedPredicate
+ *
+ * Adapter un prédicat non générique vers la forme curifiée attendue par une fonction.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+declare const input: string | number;
+
+const isString = (value: string | number): value is string => (
+	typeof value === "string"
+);
+
+const result = DCommon.pipe(
+	input,
+	DCommon.when(
+		DCommon.toCurriedPredicate(isString),
+		DString.toUpperCase,
+	),
+);
+
+// Le prédicat unaire est adapté à une API qui attend un predicate curifié.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	number | Uppercase<string>,
+	"strict"
+>;

package/docs/API/10-lang/10-common/10-toJSON.ts

@@ -0,0 +1,15 @@
+/**
+ * @title DCommon.toJSON
+ *
+ * Transformer récursivement les valeurs DuploJS vers leur représentation JSON.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const result = DCommon.toJSON({
+	toJSON() {
+		return "json" as const;
+	},
+});
+
+// La méthode toJSON est appelée sur la valeur fournie.
+type _CheckResult = DCommon.ExpectType<typeof result, "json", "strict">;

package/docs/API/10-lang/10-common/10-toNative.ts

@@ -0,0 +1,15 @@
+/**
+ * @title DCommon.toNative
+ *
+ * Transformer récursivement les valeurs DuploJS qui exposent `toNative`.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const result = DCommon.toNative({
+	toNative() {
+		return "native" as const;
+	},
+});
+
+// La méthode toNative est appelée sur la valeur fournie.
+type _CheckResult = DCommon.ExpectType<typeof result, "native", "strict">;

package/docs/API/10-lang/10-common/10-toRegExp.ts

@@ -0,0 +1,17 @@
+/**
+ * @title DCommon.toRegExp
+ *
+ * Convertir une chaîne, un tuple de chaînes ou une expression régulière en `RegExp`.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const fromString = DCommon.toRegExp("file.name");
+const fromTuple = DCommon.toRegExp(["pending", "done"] as const);
+const existing = /^(pending|done)$/;
+const fromRegExp = DCommon.toRegExp(existing);
+
+// Une chaîne devient un motif exact et ses caractères spéciaux sont échappés.
+// Un tuple devient une alternative exacte ; une RegExp existante est réutilisée.
+type _CheckString = DCommon.ExpectType<typeof fromString, RegExp, "strict">;
+type _CheckTuple = DCommon.ExpectType<typeof fromTuple, RegExp, "strict">;
+type _CheckRegExp = DCommon.ExpectType<typeof fromRegExp, RegExp, "strict">;

package/docs/API/10-lang/10-common/10-transformer.ts

@@ -0,0 +1,21 @@
+/**
+ * @title DCommon.transformer
+ *
+ * Appliquer récursivement une méthode sans argument aux objets, tableaux et valeurs imbriqués.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const result = DCommon.transformer(
+	{
+		value: {
+			toNative() {
+				return 42 as const;
+			},
+		},
+	},
+	"toNative",
+);
+
+// Les objets imbriqués sont transformés récursivement.
+type _CheckResult = DCommon.ExpectType<typeof result, { value: 42 }, "strict">;
+

package/docs/API/10-lang/10-common/10-truthy.ts

@@ -0,0 +1,12 @@
+/**
+ * @title DCommon.truthy
+ *
+ * Identifier les valeurs truthy et retirer les valeurs falsy de leur union.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: string | null;
+const result = DCommon.truthy(input);
+
+// Le predicate produit un booléen et peut affiner input vers une chaîne.
+type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;

package/docs/API/10-lang/10-common/10-useAsyncRetry.ts

@@ -0,0 +1,31 @@
+/**
+ * @title DCommon.useAsyncRetry
+ *
+ * Réessayer une opération asynchrone selon son résultat et une limite d’essais.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+let callCount = 0;
+
+const result = DCommon.useAsyncRetry(
+	async() => {
+		callCount += 1;
+		await DCommon.timeout();
+
+		return callCount === 1 ? "retry" : "done";
+	},
+	DCommon.equal("retry"),
+	{
+		maxRetry: 3,
+		timeToSleep: 10,
+	},
+);
+
+// Le résultat est testé après chaque essai : si le prédicat est vrai (`result === "retry"`), on recommence.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	Promise<"retry" | "done">,
+	"strict"
+>;
+
+// `maxRetry` est obligatoire ; `timeToSleep` ajoute une pause entre deux essais.

package/docs/API/10-lang/10-common/10-when.ts

@@ -0,0 +1,27 @@
+/**
+ * @title DCommon.when
+ *
+ * Transformer une valeur uniquement lorsqu’un prédicat est satisfait.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+declare const input: string | number;
+
+// Appel classique : donner la valeur avant le predicate.
+const result = DCommon.when(
+	input,
+	DCommon.isType("string"),
+	DString.toUpperCase,
+);
+type _CheckResult = DCommon.ExpectType<typeof result, number | Uppercase<string>, "strict">;
+
+// Appel curifié : l’étape configurée est directement placée dans DCommon.pipe.
+const piped = DCommon.pipe(
+	input,
+	DCommon.when(
+		DCommon.isType("string"),
+		DString.toUpperCase,
+	),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, number | Uppercase<string>, "strict">;

package/docs/API/10-lang/10-common/10-whenElse.ts

@@ -0,0 +1,28 @@
+/**
+ * @title DCommon.whenElse
+ *
+ * Choisir une transformation selon le résultat d’un prédicat.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: string | number;
+
+// Appel classique : les deux branches retournent la valeur sélectionnée.
+const result = DCommon.whenElse(
+	input,
+	DCommon.isType("string"),
+	DCommon.forward,
+	DCommon.forward,
+);
+type _CheckResult = DCommon.ExpectType<typeof result, string | number, "strict">;
+
+// Appel curifié : configurer le choix dans une étape de pipe.
+const piped = DCommon.pipe(
+	input,
+	DCommon.whenElse(
+		DCommon.isType("string"),
+		DCommon.forward,
+		DCommon.forward,
+	),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, string | number, "strict">;

package/docs/API/10-lang/10-common/10-whenNot.ts

@@ -0,0 +1,26 @@
+/**
+ * @title DCommon.whenNot
+ *
+ * Transformer une valeur uniquement lorsqu’un prédicat n’est pas satisfait.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: string | number;
+
+// Appel classique : transformer seulement la branche qui ne satisfait pas le predicate.
+const result = DCommon.whenNot(
+	input,
+	DCommon.isType("string"),
+	DCommon.forward,
+);
+type _CheckResult = DCommon.ExpectType<typeof result, string | number, "strict">;
+
+// Appel curifié : placer le traitement conditionnel dans un pipe.
+const piped = DCommon.pipe(
+	input,
+	DCommon.whenNot(
+		DCommon.isType("string"),
+		DCommon.forward,
+	),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, string | number, "strict">;

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

@@ -0,0 +1,228 @@
+## 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)
+
+Contrôler une boucle asynchrone avec un compteur et une sortie typée.
+ 
+### [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)
+
+Contrôler une boucle synchrone avec un compteur et une sortie typée.
+ 
+### [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.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"
+>;