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

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

@@ -0,0 +1,29 @@
+/**
+ * @title DCommon.loopAccumulatorFrom
+ *
+ * Marquer une valeur initiale pour fixer précisément le type de l’accumulateur d’une boucle.
+ */
+import * as DCommon from "@duplojs/lang/common";
+
+interface Accumulator {
+	readonly total: number;
+	readonly previous?: number;
+}
+
+const initialAccumulator = DCommon.loopAccumulatorFrom<Accumulator>({ total: 0 });
+
+type _CheckInitialAccumulator = DCommon.ExpectType<
+	typeof initialAccumulator,
+	DCommon.LoopAccumulatorFromResult<Accumulator>,
+	"strict"
+>;
+
+const result = DCommon.loopAccumulator(initialAccumulator, ({ accumulator, count, next, exit }) => count === 2
+	? exit(accumulator.total)
+	: next({
+		total: accumulator.total + 1,
+		previous: accumulator.total,
+	}));
+
+// La boucle reçoit Accumulator comme état et retourne le nombre fourni à `exit`.
+type _CheckResult = DCommon.ExpectType<typeof result, number, "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">;

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-tap.ts

@@ -0,0 +1,28 @@
+/**
+ * @title DCommon.tap
+ *
+ * Exécuter un traitement secondaire tout en conservant la valeur d’entrée.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+const input = {
+	status: "saved",
+	revision: 3,
+};
+declare function recordStatus(status: Uppercase<string>): void;
+
+// Appel classique : enregistrer le statut sans remplacer l’objet d’entrée.
+const direct = DCommon.tap(input, (entry) => {
+	recordStatus(DString.toUpperCase(entry.status));
+});
+type _CheckDirect = DCommon.ExpectType<typeof direct, typeof input, "strict">;
+
+declare function persistAudit(entry: typeof input): Promise<void>;
+
+// Appel curifié : attendre l’audit asynchrone puis conserver l’objet dans le pipe.
+const piped = DCommon.pipe(
+	input,
+	DCommon.tap(persistAudit),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, Promise<typeof input>, "strict">;

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">;

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";
+	},
+});
+
+// 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";
+	},
+});
+
+// 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"]);
+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,31 @@
+/**
+ * @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">;
+
+// L’appel direct affine dans le if ; la branche peut alors transformer la chaîne.
+if (DCommon.truthy(input)) {
+	type _CheckInput = DCommon.ExpectType<typeof input, string, "strict">;
+}
+
+// Une fonction déjà unaire se passe telle quelle à DCommon.when.
+const transformed = DCommon.pipe(
+	input,
+	DCommon.when(
+		DCommon.truthy,
+		(value) => {
+			type _CheckValue = DCommon.ExpectType<typeof value, string, "strict">;
+
+			return DCommon.forward(value);
+		},
+	),
+);
+type _CheckTransformed = DCommon.ExpectType<typeof transformed, string | null, "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,57 @@
+/**
+ * @title DCommon.whenNot
+ *
+ * Transformer une valeur uniquement lorsqu’un prédicat n’est pas satisfait.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DNumber from "@duplojs/lang/number";
+import * as DString from "@duplojs/lang/string";
+
+// Appel classique : remplacer un nom vide, sans modifier les noms déjà renseignés.
+declare const displayName: string;
+const named = DCommon.whenNot(
+	displayName,
+	DString.isNotEmpty,
+	DCommon.justReturn("Anonyme"),
+);
+// La chaîne vide devient "Anonyme" ; les autres noms conservent la preuve NotEmpty.
+type _CheckNamed = DCommon.ExpectType<typeof named, (string & DString.NotEmpty) | "Anonyme", "strict">;
+
+// Appel curifié : convertir les références numériques avant de normaliser leur casse.
+declare const reference: string | number;
+const normalizedReference = DCommon.pipe(
+	reference,
+	DCommon.whenNot(
+		DCommon.isType("string"),
+		DString.to,
+	),
+	DString.toUpperCase,
+);
+// Par exemple, 42 donne "42" et "ticket-ab" donne "TICKET-AB".
+type _CheckNormalizedReference = DCommon.ExpectType<typeof normalizedReference, Uppercase<string>, "strict">;
+
+// Predicates composés : signaler seulement les états qui ne sont ni prêts ni en attente.
+declare const state: "ready" | "queued" | "blocked";
+const labeledState = DCommon.whenNot(
+	state,
+	DCommon.or([DCommon.equal("ready"), DCommon.equal("queued")]),
+	DString.prepend("Attention : "),
+);
+// "blocked" devient "Attention : blocked" ; les deux autres littéraux sont conservés.
+type _CheckLabeledState = DCommon.ExpectType<
+	typeof labeledState,
+	"ready" | "queued" | "Attention : blocked",
+	"strict"
+>;
+
+// Test booléen : appliquer un délai minimum calculé à l'exécution.
+declare const delay: number;
+declare const minimumDelay: number;
+const boundedDelay = DCommon.whenNot(
+	delay,
+	DNumber.greaterThanOrEqual(minimumDelay),
+	DCommon.justReturn(minimumDelay),
+);
+// Les délais trop courts sont relevés au minimum ; les autres restent inchangés.
+// La borne dynamique ne peut pas être représentée comme une contrainte littérale.
+type _CheckBoundedDelay = DCommon.ExpectType<typeof boundedDelay, number, "strict">;