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

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,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,43 @@
+/**
+ * @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";
+import * as DString from "@duplojs/lang/string";
+
+declare const input: string | number | boolean;
+
+// 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">;
+
+if (DCommon.or(input, [DCommon.isType("string"), DCommon.isType("number")])) {
+	type _CheckInput = DCommon.ExpectType<typeof input, string | number, "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"),
+		]),
+		(value) => {
+			type _CheckValue = DCommon.ExpectType<typeof value, string | number, "strict">;
+
+			return DString.to(value);
+		},
+	),
+);
+
+// Les chaînes et les nombres sélectionnés deviennent des chaînes ; le booléen reste inchangé.
+type _CheckPreserved = DCommon.ExpectType<
+	typeof preserved,
+	string | boolean | (string & DString.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">;