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

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

@@ -0,0 +1,40 @@
+/**
+ * @title DCommon.asyncLoopAccumulator
+ *
+ * Répéter une callback asynchrone en faisant circuler un accumulateur et retourner la valeur de `exit`.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const total = await DCommon.asyncLoopAccumulator(0, async({ accumulator, count, next, exit }) => {
+	await DCommon.timeout();
+
+	if (count === 3) {
+		return exit(accumulator);
+	}
+
+	return next(accumulator + count + 1);
+});
+
+// La callback est attendue à chaque tour et le résultat final est celui de `exit`.
+type _CheckTotal = DCommon.ExpectType<typeof total, number, "strict">;
+
+interface Accumulator {
+	readonly total: number;
+	readonly previous?: number;
+}
+
+const structuredTotal = await DCommon.asyncLoopAccumulator(
+	DCommon.loopAccumulatorFrom<Accumulator>({ total: 0 }),
+	async({ accumulator, count, next, exit }) => {
+		await DCommon.timeout();
+
+		return count === 2
+			? exit(accumulator.total)
+			: next({
+				total: accumulator.total + 1,
+				previous: accumulator.total,
+			});
+	},
+);
+
+type _CheckStructuredTotal = DCommon.ExpectType<typeof structuredTotal, number, "strict">;

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

@@ -0,0 +1,21 @@
+/**
+ * @title DCommon.asyncPipe
+ *
+ * Exécuter séquentiellement plusieurs transformations en attendant chaque résultat.
+ */
+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.asyncPipe(
+	"value",
+	DString.toUpperCase,
+	DString.length,
+);
+
+// Le résultat final est la longueur positive de la chaîne transformée.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	Promise<number & DNumber.Positive>,
+	"strict"
+>;

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

@@ -0,0 +1,22 @@
+/**
+ * @title DCommon.callThen
+ *
+ * Appliquer une fonction à une valeur immédiate ou promise, avec gestion optionnelle des erreurs.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+const result = DCommon.callThen("value", DString.toUpperCase);
+
+// Une valeur immédiate reste immédiate après l’application de la fonction.
+type _CheckResult = DCommon.ExpectType<typeof result, Uppercase<string>, "strict">;
+
+declare const promisedValue: Promise<string>;
+const promisedResult = DCommon.callThen(promisedValue, DString.toUpperCase);
+
+// Une Promise conserve son caractère asynchrone.
+type _CheckPromisedResult = DCommon.ExpectType<
+	typeof promisedResult,
+	Promise<Uppercase<string>>,
+	"strict"
+>;

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

@@ -0,0 +1,16 @@
+/**
+ * @title DCommon.cast
+ *
+ * Vérifier au niveau du typage qu’une valeur respecte une contrainte attendue.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DString from "@duplojs/lang/string";
+
+const result: string & DString.MinCharacters<10> = DCommon.cast("thisIsASuperName");
+
+// La compatibilité est vérifiée par TypeScript ; cast n’ajoute aucune validation runtime.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	string & DString.MinCharacters<10>,
+	"strict"
+>;

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

@@ -0,0 +1,12 @@
+/**
+ * @title DCommon.clone
+ *
+ * Copier récursivement les tableaux et objets simples sans modifier la valeur source.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const source = { nested: { value: 1 } };
+const result = DCommon.clone(source);
+
+// La copie conserve la forme typée de l’objet source.
+type _CheckResult = DCommon.ExpectType<typeof result, typeof source, "strict">;

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

@@ -0,0 +1,34 @@
+/**
+ * @title DCommon.createAsyncRetry
+ *
+ * Décorer une fonction asynchrone avec une stratégie de nouvelle tentative.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+let callCount = 0;
+
+const retry = DCommon.createAsyncRetry(
+	async(value: string) => {
+		callCount += 1;
+		await DCommon.timeout();
+
+		return callCount === 1 ? "retry" : value;
+	},
+	DCommon.equal("retry"),
+	{
+		maxRetry: 3,
+		timeToSleep: 10,
+	},
+);
+const result = retry("done");
+
+// La fonction décorée conserve ses paramètres et retourne une Promise.
+type _CheckRetry = DCommon.ExpectType<
+	typeof retry,
+	(value: string) => Promise<string>,
+	"strict"
+>;
+type _CheckResult = DCommon.ExpectType<typeof result, Promise<string>, "strict">;
+
+// Le prédicat vrai (`result === "retry"`) relance l’opération ; `done` arrête les tentatives.
+// `maxRetry` limite le nombre d’essais et `timeToSleep` règle la pause entre deux essais.

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

@@ -0,0 +1,19 @@
+/**
+ * @title DCommon.createBuilder
+ *
+ * Configurer des handlers réutilisables pour construire un objet par étapes.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+interface ExampleBuilder extends DCommon.Builder<{ value: string }> {
+	build(): { value: string };
+}
+
+const handlers = DCommon.createBuilder<ExampleBuilder>("api-documentation-builder").set(
+	"build",
+	({ accumulator }) => accumulator,
+);
+const result = handlers.use({ value: "done" }).build();
+
+// Le handler réutilise l’accumulateur et conserve sa forme typée.
+type _CheckResult = DCommon.ExpectType<typeof result, { value: string }, "strict">;

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

@@ -0,0 +1,25 @@
+/**
+ * @title DCommon.createEnum
+ *
+ * Créer un enum littéral qui expose ses valeurs, un tuple et un prédicat `has`.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const status = DCommon.createEnum([
+	"pending",
+	"done",
+]);
+const result = status.toTuple();
+
+// Le tuple conserve les valeurs littérales et leur ordre.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	readonly ["pending", "done"],
+	"strict"
+>;
+
+declare const input: "pending" | "done" | "missing";
+if (status.has(input)) {
+	// Le predicate has affine l’union vers les valeurs de l’enum.
+	type _CheckInput = DCommon.ExpectType<typeof input, "pending" | "done", "strict">;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * @title DCommon.createExternalPromise
+ *
+ * Exposer les contrôles `resolve` et `reject` d’une promise séparément de sa création.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const external = DCommon.createExternalPromise<string>();
+const result = external.promise;
+
+// La promise est résolue séparément par la méthode resolve.
+external.resolve("done");
+type _CheckResult = DCommon.ExpectType<typeof result, Promise<string>, "strict">;

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,17 @@
+/**
+ * @title DCommon.createQueue
+ *
+ * Créer une file d’attente typée avec une capacité optionnelle.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DEither from "@duplojs/lang/either";
+
+const queue = DCommon.createQueue({ concurrency: 1 });
+const result = queue.add(() => "done");
+
+// Le résultat contient la valeur de la tâche, ou un Left si son exécution lève une erreur.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	Promise<string | DEither.Left<"execution-error", unknown>>,
+	"strict"
+>;

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;
+	},
+});
+
+// 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,37 @@
+/**
+ * @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;
+
+if (DCommon.equal(source, "value")) {
+	type _CheckIfValue = DCommon.ExpectType<typeof source, "value", "strict">;
+	const uppercase = DString.toUpperCase(source);
+	type _CheckUppercase = DCommon.ExpectType<typeof uppercase, "VALUE", "strict">;
+}
+
+// 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,31 @@
+/**
+ * @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">;
+
+// L’appel direct expose la branche falsy dans le if.
+if (DCommon.falsy(input)) {
+	type _CheckInput = DCommon.ExpectType<typeof input, "" | null, "strict">;
+}
+
+// Le predicate unaire s’utilise directement avec DCommon.when.
+const preserved = DCommon.pipe(
+	input,
+	DCommon.when(
+		DCommon.falsy,
+		(value) => {
+			type _CheckValue = DCommon.ExpectType<typeof value, "" | null, "strict">;
+
+			return DCommon.forward(value);
+		},
+	),
+);
+type _CheckPreserved = DCommon.ExpectType<typeof preserved, string | null, "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,34 @@
+/**
+ * @title DCommon.instanceOf
+ *
+ * Créer un prédicat basé sur un constructeur avec narrowing de l’instance.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DChrono from "@duplojs/lang/chrono";
+
+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">;
+
+if (DCommon.instanceOf(input, Date)) {
+	type _CheckInput = DCommon.ExpectType<typeof input, Date, "strict">;
+	const chronoDate = DChrono.createDateOrThrow(input);
+	type _CheckChronoDate = DCommon.ExpectType<typeof chronoDate, DChrono.TheDate, "strict">;
+}
+
+// La forme curifiée s’utilise directement comme predicate dans DCommon.when.
+const converted = DCommon.pipe(
+	input,
+	DCommon.when(
+		DCommon.instanceOf(Date),
+		(date) => {
+			type _CheckDate = DCommon.ExpectType<typeof date, Date, "strict">;
+
+			return DChrono.createDateOrThrow(date);
+		},
+	),
+);
+
+type _CheckConverted = DCommon.ExpectType<typeof converted, DChrono.TheDate | string, "strict">;

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

@@ -0,0 +1,35 @@
+/**
+ * @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">;
+
+if (DCommon.isType(input, "string")) {
+	type _CheckInput = DCommon.ExpectType<typeof input, string, "strict">;
+	const uppercase = DString.toUpperCase(input);
+	type _CheckUppercase = DCommon.ExpectType<typeof uppercase, Uppercase<string>, "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";
+	}
+
+	if (input > 0) {
+		return "positive";
+	}
+
+	return "non-positive";
+});
+
+// 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,18 @@
+/**
+ * @title DCommon.loop
+ *
+ * Répéter une callback synchrone jusqu’à `exit`, avec un compteur et une valeur de retour typée.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const result = DCommon.loop<"done">(({ count, next, exit }) => {
+	if (count === 3) {
+		return exit("done");
+	}
+
+	return next();
+});
+
+// `count` commence à 0. `next()` poursuit la boucle ; les valeurs d'une itération à l'autre
+// doivent être portées par loopAccumulator, car `loop` ne conserve pas les données de `next`.
+type _CheckResult = DCommon.ExpectType<typeof result, "done", "strict">;

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

@@ -0,0 +1,35 @@
+/**
+ * @title DCommon.loopAccumulator
+ *
+ * Répéter une callback synchrone en faisant circuler un accumulateur et retourner la valeur de `exit`.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+const total = DCommon.loopAccumulator(0, ({ accumulator, count, next, exit }) => {
+	if (count === 3) {
+		return exit(accumulator);
+	}
+
+	return next(accumulator + count + 1);
+});
+
+// Le nombre initial est élargi en number ; chaque `next` fournit l’accumulateur du tour suivant.
+type _CheckTotal = DCommon.ExpectType<typeof total, number, "strict">;
+
+interface Accumulator {
+	readonly total: number;
+	readonly previous?: number;
+}
+
+const structuredTotal = DCommon.loopAccumulator(
+	DCommon.loopAccumulatorFrom<Accumulator>({ total: 0 }),
+	({ accumulator, count, next, exit }) => count === 2
+		? exit(accumulator.total)
+		: next({
+			total: accumulator.total + 1,
+			previous: accumulator.total,
+		}),
+);
+
+// `loopAccumulatorFrom` conserve le type choisi pour un accumulateur structuré.
+type _CheckStructuredTotal = DCommon.ExpectType<typeof structuredTotal, number, "strict">;