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

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

@@ -0,0 +1,16 @@
+/**
+ * @title DCommon.createFormData
+ *
+ * Transformer un objet de valeurs en `FormData` en conservant ses valeurs d’entrée typées.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const values = { name: "Ada" };
+const result = DCommon.createFormData(values);
+
+// La FormData conserve l’objet d’entrée dans inputValues.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	DCommon.TheFormData<typeof values>,
+	"strict"
+>;

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

@@ -0,0 +1,12 @@
+/**
+ * @title DCommon.createInterpolation
+ *
+ * Préparer une fonction qui remplace les identifiants entre accolades dans un modèle.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const interpolation = DCommon.createInterpolation("user-{id}", true);
+const result = interpolation({ id: "42" });
+
+// Le mode strict reflète la valeur injectée dans le type de sortie.
+type _CheckResult = DCommon.ExpectType<typeof result, "user-42", "strict">;

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

@@ -0,0 +1,16 @@
+/**
+ * @title DCommon.createQueue
+ *
+ * Créer une file d’attente typée avec une capacité optionnelle.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const queue = DCommon.createQueue({ concurrency: 1 });
+const result = queue.add(() => "done");
+
+// Chaque tâche est exécutée dans une Promise et ses erreurs sont représentées par un Left.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	Promise<"done">,
+	"two-extends-one"
+>;

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

@@ -0,0 +1,16 @@
+/**
+ * @title DCommon.createTransformer
+ *
+ * Créer une fonction de transformation récursive liée à un nom de méthode.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const toNative = DCommon.createTransformer("toNative");
+const result = toNative({
+	toNative() {
+		return 42 as const;
+	},
+});
+
+// Le transformer appelle la méthode ciblée et retourne sa valeur.
+type _CheckResult = DCommon.ExpectType<typeof result, 42, "strict">;

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

@@ -0,0 +1,20 @@
+/**
+ * @title DCommon.detachObjectMethod
+ *
+ * Détacher une méthode d’un objet tout en conservant son contexte d’exécution.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+const source = {
+	value: "value",
+	upper() {
+		return DString.toUpperCase(this.value);
+	},
+};
+
+const upper = DCommon.detachObjectMethod(source, "upper");
+const result = upper();
+
+// La méthode détachée utilise toujours source comme contexte.
+type _CheckResult = DCommon.ExpectType<typeof result, Uppercase<string>, "strict">;

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

@@ -0,0 +1,31 @@
+/**
+ * @title DCommon.equal
+ *
+ * Créer un prédicat d’égalité pour une valeur ou une liste de valeurs littérales.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+// Appel classique : comparer immédiatement deux valeurs.
+const result = DCommon.equal("value", "value");
+
+// La valeur obtenue est true.
+type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;
+
+declare const source: string | number;
+
+// Appel curifié : le prédicat est passé directement à DCommon.when.
+const transformed = DCommon.pipe(
+	source,
+	DCommon.when(
+		DCommon.equal("value"),
+		DString.toUpperCase,
+	),
+);
+
+// La chaîne est transformée si elle vaut "value", sinon la source est conservée.
+type _CheckTransformed = DCommon.ExpectType<
+	typeof transformed,
+	number | string,
+	"strict"
+>;

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

@@ -0,0 +1,11 @@
+/**
+ * @title DCommon.escapeRegExp
+ *
+ * Échapper les caractères spéciaux d’une chaîne avant de l’utiliser dans une expression régulière.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const result = DCommon.escapeRegExp("file.name");
+
+// Le point est échappé pour être interprété littéralement.
+type _CheckResult = DCommon.ExpectType<typeof result, string, "strict">;

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

@@ -0,0 +1,12 @@
+/**
+ * @title DCommon.falsy
+ *
+ * Identifier les valeurs falsy JavaScript avec un narrowing TypeScript.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: string | null;
+const result = DCommon.falsy(input);
+
+// Le prédicat produit un booléen et distingue la branche falsy de l’union.
+type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;

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

@@ -0,0 +1,11 @@
+/**
+ * @title DCommon.forward
+ *
+ * Retourner une valeur telle quelle pour la rendre explicite dans une composition.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const result = DCommon.forward("value");
+
+// La valeur et son type sont conservés.
+type _CheckResult = DCommon.ExpectType<typeof result, "value", "strict">;

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

@@ -0,0 +1,17 @@
+/**
+ * @title DCommon.forwardAsserts
+ *
+ * Vérifier une valeur et la retourner, ou produire une fonction réutilisable de vérification.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+// Appel classique : vérifier et retourner immédiatement la valeur.
+const result = DCommon.forwardAsserts("value", DCommon.isType("string"));
+
+type _CheckResult = DCommon.ExpectType<typeof result, string, "strict">;
+
+// Appel curifié : préparer une vérification réutilisable.
+const ensureString = DCommon.forwardAsserts(DCommon.isType("string"));
+const checked = ensureString("value");
+
+type _CheckChecked = DCommon.ExpectType<typeof checked, string, "strict">;

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

@@ -0,0 +1,11 @@
+/**
+ * @title DCommon.forwardLog
+ *
+ * Afficher une valeur puis la retourner pour observer une composition.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const result = DCommon.forwardLog("value");
+
+// La valeur observée est aussi la valeur produite.
+type _CheckResult = DCommon.ExpectType<typeof result, "value", "strict">;

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

@@ -0,0 +1,16 @@
+/**
+ * @title DCommon.infer
+ *
+ * Inférer une contrainte à partir d’une valeur littérale dans une expression typée.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DString from "@duplojs/lang/string";
+
+const result: string & DString.MinCharacters<5> = DCommon.infer("value");
+
+// La longueur du littéral fournit la contrainte minimale attendue.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	string & DString.MinCharacters<5>,
+	"strict"
+>;

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

@@ -0,0 +1,23 @@
+/**
+ * @title DCommon.innerPipe
+ *
+ * Composer plusieurs transformations dans une fonction réutilisable.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DNumber from "@duplojs/lang/number";
+import * as DString from "@duplojs/lang/string";
+
+const result = DCommon.pipe(
+	"value",
+	DCommon.innerPipe(
+		DString.toUpperCase,
+		DString.length,
+	),
+);
+
+// La fonction composée retourne une longueur positive.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	number & DNumber.Positive,
+	"strict"
+>;

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

@@ -0,0 +1,23 @@
+/**
+ * @title DCommon.instanceOf
+ *
+ * Créer un prédicat basé sur un constructeur avec narrowing de l’instance.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: Date | string;
+const result = DCommon.instanceOf(input, Date);
+
+// Le test runtime produit un booléen.
+type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;
+
+// La forme curifiée s’utilise directement comme predicate dans DCommon.when.
+const preserved = DCommon.pipe(
+	input,
+	DCommon.when(
+		DCommon.instanceOf(Date),
+		DCommon.forward,
+	),
+);
+
+type _CheckPreserved = DCommon.ExpectType<typeof preserved, Date | string, "strict">;

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

@@ -0,0 +1,29 @@
+/**
+ * @title DCommon.isType
+ *
+ * Construire un prédicat de type à partir d’un type runtime.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+declare const input: string | number;
+
+// Appel classique : tester directement le type runtime.
+const result = DCommon.isType(input, "string");
+type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;
+
+// Appel curifié : le predicate est passé directement à DCommon.when.
+const transformed = DCommon.pipe(
+	input,
+	DCommon.when(
+		DCommon.isType("string"),
+		DString.toUpperCase,
+	),
+);
+
+// Seules les chaînes sont transformées.
+type _CheckTransformed = DCommon.ExpectType<
+	typeof transformed,
+	number | Uppercase<string>,
+	"strict"
+>;

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

@@ -0,0 +1,28 @@
+/**
+ * @title DCommon.justExec
+ *
+ * Encapsuler une logique impérative locale et affecter directement son résultat.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: number;
+
+const result = DCommon.justExec(() => {
+	if (input > 10) {
+		return "large" as const;
+	}
+
+	if (input > 0) {
+		return "positive" as const;
+	}
+
+	return "non-positive" as const;
+});
+
+// Le bloc est exécuté immédiatement : son résultat est directement affecté à `result`.
+// Cela évite une variable mutable initialisée à vide puis réassignée dans chaque branche.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	"large" | "positive" | "non-positive",
+	"strict"
+>;

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

@@ -0,0 +1,19 @@
+/**
+ * @title DCommon.justReturn
+ *
+ * Fournir une valeur déjà calculée à une étape de pipe sans écrire de callback.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: "ready" | "pending";
+
+const result = DCommon.pipe(
+	input,
+	DCommon.when(
+		DCommon.equal("ready"),
+		DCommon.justReturn("done"),
+	),
+);
+
+// `justReturn` remplace une callback comme `() => "done"` dans le `when` curifié.
+type _CheckResult = DCommon.ExpectType<typeof result, "done" | "pending", "strict">;

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

@@ -0,0 +1,20 @@
+/**
+ * @title DCommon.loop
+ *
+ * Contrôler une boucle synchrone avec un compteur et une sortie typée.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const result = DCommon.loop<"done", number>(({ count, previousOutput, next, exit }) => {
+	const current = previousOutput ?? 0;
+
+	if (count === 3) {
+		return exit("done");
+	}
+
+	return next(current + 1);
+});
+
+// `count` commence à 0 ; `previousOutput` vaut undefined à la première itération.
+// `next` poursuit la boucle avec une nouvelle sortie, tandis que `exit` la termine.
+type _CheckResult = DCommon.ExpectType<typeof result, "done", "strict">;

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

@@ -0,0 +1,12 @@
+/**
+ * @title DCommon.memo
+ *
+ * Évaluer une fonction au premier accès puis mémoriser sa valeur.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const memoized = DCommon.memo(() => "done");
+const result = memoized.value;
+
+// Le getter expose la valeur calculée avec son type inféré.
+type _CheckResult = DCommon.ExpectType<typeof result, string, "strict">;

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

@@ -0,0 +1,11 @@
+/**
+ * @title DCommon.memoObject
+ *
+ * Exposer un objet calculé paresseusement tout en mémorisant son contenu.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const result = DCommon.memoObject(() => ({ value: "done" }));
+
+// L’objet conserve la forme produite par le getter.
+type _CheckResult = DCommon.ExpectType<typeof result, { value: string }, "strict">;

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

@@ -0,0 +1,16 @@
+/**
+ * @title DCommon.memoPromise
+ *
+ * Mémoriser le résultat d’un calcul synchrone ou asynchrone.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const memoized = DCommon.memoPromise(() => "done");
+const result = memoized.value;
+
+// Le premier accès peut fournir la valeur ou la Promise partagée du calcul.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	string | Promise<string>,
+	"strict"
+>;

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

@@ -0,0 +1,29 @@
+/**
+ * @title DCommon.or
+ *
+ * Combiner plusieurs prédicats en une condition satisfaite par au moins l’un d’eux.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: string | number;
+
+// Appel classique : un seul predicate accepté suffit.
+const result = DCommon.or(input, [
+	DCommon.isType("string"),
+	DCommon.isType("number"),
+]);
+type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;
+
+// Appel curifié : le predicate composé est passé à DCommon.when.
+const preserved = DCommon.pipe(
+	input,
+	DCommon.when(
+		DCommon.or([
+			DCommon.isType("string"),
+			DCommon.isType("number"),
+		]),
+		DCommon.forward,
+	),
+);
+
+type _CheckPreserved = DCommon.ExpectType<typeof preserved, string | number, "strict">;

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

@@ -0,0 +1,21 @@
+/**
+ * @title DCommon.pipe
+ *
+ * Appliquer une suite de transformations de gauche à droite.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DNumber from "@duplojs/lang/number";
+import * as DString from "@duplojs/lang/string";
+
+const result = DCommon.pipe(
+	"value",
+	DString.toUpperCase,
+	DString.length,
+);
+
+// Chaque étape reçoit la sortie de la précédente.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	number & DNumber.Positive,
+	"strict"
+>;

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

@@ -0,0 +1,20 @@
+/**
+ * @title DCommon.pipeCall
+ *
+ * Corriger l’inférence d’une fonction sans générique utilisée dans un pipe.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DNumber from "@duplojs/lang/number";
+import * as DString from "@duplojs/lang/string";
+
+const result = DCommon.pipe(
+	"value",
+	DCommon.pipeCall(DString.length),
+);
+
+// La fonction unaire est adaptée au pipe et conserve son type de sortie.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	number & DNumber.Positive,
+	"strict"
+>;

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

@@ -0,0 +1,20 @@
+/**
+ * @title DCommon.prepareAsyncPipe
+ *
+ * Préparer une fabrique de pipelines asynchrones partageant une contrainte d’entrée.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+const toUpperCase = DCommon.prepareAsyncPipe<string>()(
+	DString.toUpperCase,
+);
+
+const result = toUpperCase("value");
+
+// Le pipeline préparé accepte une chaîne et retourne une Promise de chaîne transformée.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	Promise<Uppercase<string>>,
+	"strict"
+>;

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

@@ -0,0 +1,20 @@
+/**
+ * @title DCommon.preparePipe
+ *
+ * Préparer une fabrique de pipelines partageant une contrainte d’entrée.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+const toUpperCase = DCommon.preparePipe<string>()(
+	DString.toUpperCase,
+);
+
+const result = toUpperCase("value");
+
+// Le pipeline préparé conserve le type de sa transformation.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	Uppercase<string>,
+	"strict"
+>;

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

@@ -0,0 +1,16 @@
+/**
+ * @title DCommon.promiseAll
+ *
+ * Attendre un tuple ou un itérable de promesses en conservant la forme du tuple.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+declare const values: readonly [Promise<string>, number];
+const result = DCommon.promiseAll(values);
+
+// Le tuple résolu conserve l’ordre et la position de ses types.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	Promise<[string, number]>,
+	"strict"
+>;

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

@@ -0,0 +1,22 @@
+/**
+ * @title DCommon.promiseObject
+ *
+ * Attendre toutes les propriétés promises d’un objet et reconstruire l’objet résolu.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+declare const values: {
+	name: string;
+	count: Promise<number>;
+};
+const result = DCommon.promiseObject(values);
+
+// Chaque propriété conserve son nom et reçoit sa valeur résolue.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	Promise<{
+		name: string;
+		count: number;
+	}>,
+	"strict"
+>;

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

@@ -0,0 +1,13 @@
+/**
+ * @title DCommon.removeConstraint
+ *
+ * Retirer les contraintes DuploJS d’un type tout en conservant sa forme de valeur.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DString from "@duplojs/lang/string";
+
+declare const constrained: string & DString.NotEmpty;
+const result = DCommon.removeConstraint(constrained);
+
+// La valeur reste une chaîne, mais ne porte plus la contrainte NotEmpty.
+type _CheckResult = DCommon.ExpectType<typeof result, string, "strict">;

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

@@ -0,0 +1,20 @@
+/**
+ * @title DCommon.shameOnYou
+ *
+ * Contourner explicitement une contrainte attendue dans un contrat de type.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DString from "@duplojs/lang/string";
+
+const acceptLongString = (value: string & DString.MinCharacters<10>) => value;
+
+const result = acceptLongString(
+	DCommon.shameOnYou("short"),
+);
+
+// La valeur brute est acceptée malgré la contrainte, puis présentée au contrat comme contrainte.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	string & DString.MinCharacters<10>,
+	"strict"
+>;

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

@@ -0,0 +1,12 @@
+/**
+ * @title DCommon.simpleClone
+ *
+ * Créer une copie superficielle d’une valeur clonable.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const source = { value: "done" };
+const result = DCommon.simpleClone(source);
+
+// La copie conserve le type de la valeur clonée.
+type _CheckResult = DCommon.ExpectType<typeof result, typeof source, "strict">;

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

@@ -0,0 +1,16 @@
+/**
+ * @title DCommon.stringToBytes
+ *
+ * Convertir une quantité en octets écrite avec une unité ou déjà numérique.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const fromString = DCommon.stringToBytes("1.5kb");
+const fromNumber = DCommon.stringToBytes(512);
+
+// Les unités acceptées sont `b`, `kb`, `mb`, `gb`, `tb` et `pb`.
+// Les valeurs décimales sont converties en octets puis arrondies à l’entier inférieur.
+type _CheckString = DCommon.ExpectType<typeof fromString, number, "strict">;
+type _CheckNumber = DCommon.ExpectType<typeof fromNumber, number, "strict">;
+
+// Une chaîne qui ne respecte pas le format lève InvalidBytesInStringError à l’exécution.

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

@@ -0,0 +1,17 @@
+/**
+ * @title DCommon.stringToMillisecond
+ *
+ * Additionner des durées écrites avec une unité ou exprimées en millisecondes.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const fromStrings = DCommon.stringToMillisecond("1h", "30m", "2s", "500ms");
+const fromNumber = DCommon.stringToMillisecond(2_500);
+
+// Les unités acceptées sont `ms`, `s`, `m`, `h`, `d` et `w`.
+// Le premier paramètre est obligatoire ; les suivants sont additionnés au résultat.
+type _CheckStrings = DCommon.ExpectType<typeof fromStrings, number, "strict">;
+type _CheckNumber = DCommon.ExpectType<typeof fromNumber, number, "strict">;
+
+// Les valeurs décimales sont converties puis arrondies à l’entier inférieur.
+// Une chaîne invalide lève InvalidMillisecondInStringError à l’exécution.

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

@@ -0,0 +1,11 @@
+/**
+ * @title DCommon.timeout
+ *
+ * Créer une promise résolue après un délai en millisecondes.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const result = DCommon.timeout(10);
+
+// Le délai est représenté par une Promise sans valeur.
+type _CheckResult = DCommon.ExpectType<typeof result, Promise<void>, "strict">;