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

package/docs/API/10-lang/10-generator/10-asyncConcat.ts

@@ -0,0 +1,43 @@
+/**
+ * @title DGenerator.asyncConcat
+ *
+ * Enchaîner plusieurs itérables synchrones ou asynchrones dans un générateur asynchrone.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DArray from "@duplojs/lang/array";
+import * as DGenerator from "@duplojs/lang/generator";
+
+const head = (async function *() {
+	await DCommon.timeout();
+	yield 1;
+	yield 2;
+})();
+
+const tail = (async function *() {
+	await DCommon.timeout();
+	yield 4;
+	yield 5;
+})();
+
+// Appel classique : les valeurs sont produites dans l’ordre [1, 2, 3, 4, 5].
+const result = DGenerator.asyncConcat(head, [3], tail);
+
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	AsyncGenerator<1 | 2 | 3 | 4 | 5, unknown, unknown>,
+	"strict"
+>;
+
+// Appel curifié : les itérables ajoutés sont configurés dans l’étape du pipe.
+const piped = DCommon.pipe(
+	[1, 2],
+	DGenerator.asyncConcat([3, 4]),
+	DArray.from,
+);
+
+// La promesse se résout vers [1, 2, 3, 4].
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	Promise<readonly (1 | 2 | 3 | 4)[]>,
+	"strict"
+>;

package/docs/API/10-lang/10-generator/10-asyncFilter.ts

@@ -0,0 +1,41 @@
+/**
+ * @title DGenerator.asyncFilter
+ *
+ * Conserver dans un générateur asynchrone les valeurs acceptées par un prédicat.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DArray from "@duplojs/lang/array";
+import * as DGenerator from "@duplojs/lang/generator";
+import * as DNumber from "@duplojs/lang/number";
+
+const input = (async function *() {
+	await DCommon.timeout();
+	yield 1 as number;
+	yield 2 as number;
+	yield 3 as number;
+	yield 4 as number;
+})();
+
+// Appel classique : seuls les nombres supérieurs à deux sont produits.
+const result = DGenerator.asyncFilter(input, DNumber.greaterThan(2));
+
+// La sortie est un AsyncGenerator qui produit [3, 4].
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	AsyncGenerator<number & DNumber.GreaterThan<2>, unknown, unknown>,
+	"strict"
+>;
+
+// Appel curifié : le prédicat est configuré dans l’étape du pipe.
+const piped = DCommon.pipe(
+	[1, 2, 3, 4] as number[],
+	DGenerator.asyncFilter(DNumber.isEven),
+	DArray.from,
+);
+
+// La promesse se résout vers [2, 4].
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	Promise<readonly (number & DNumber.Even)[]>,
+	"strict"
+>;

package/docs/API/10-lang/10-generator/10-asyncFlat.ts

@@ -0,0 +1,37 @@
+/**
+ * @title DGenerator.asyncFlat
+ *
+ * Aplatir récursivement les valeurs itérables d’un générateur asynchrone jusqu’à une profondeur donnée.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+
+const input = (async function *() {
+	await DCommon.timeout();
+	yield [[1], [2]];
+	yield [[3]];
+})();
+
+// Profondeur par défaut : un seul niveau est aplati, donc la sortie contient [[1], [2], [3]].
+const result = DGenerator.asyncFlat(input);
+
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	AsyncGenerator<number[], void, unknown>,
+	"strict"
+>;
+
+const nestedInput = (async function *() {
+	await DCommon.timeout();
+	yield [[1], [2]];
+	yield [[3]];
+})();
+
+// Une profondeur de deux aplati également les tuples internes : la sortie contient [1, 2, 3].
+const deeplyFlattened = DGenerator.asyncFlat(nestedInput, 2);
+
+type _CheckDeeplyFlattened = DCommon.ExpectType<
+	typeof deeplyFlattened,
+	AsyncGenerator<number, void, unknown>,
+	"strict"
+>;

package/docs/API/10-lang/10-generator/10-asyncGroup.ts

@@ -0,0 +1,65 @@
+/**
+ * @title DGenerator.asyncGroup
+ *
+ * Regrouper les valeurs d’un itérable asynchrone selon les sorties nommées d’une callback.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+import * as DNumber from "@duplojs/lang/number";
+import * as DString from "@duplojs/lang/string";
+
+const input = (async function *() {
+	await DCommon.timeout();
+	yield 1 as number;
+	yield 2 as number;
+	yield 3 as number;
+})();
+
+// Appel classique : chaque valeur est ajoutée au groupe dont le nom dépend de sa parité.
+// Le ternaire porte sur la structure entière : `group` devient un discriminant littéral.
+const result = DGenerator.asyncGroup(
+	input,
+	(item, params) => DNumber.isEven(item)
+		? params.output("even", item)
+		: params.output("odd", item),
+);
+
+// La promesse se résout vers { odd: [1, 3], even: [2] }.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	Promise<{
+		readonly even?: readonly [number & DNumber.Even, ...(number & DNumber.Even)[]] | undefined;
+		readonly odd?: readonly [number, ...number[]] | undefined;
+	}>,
+	"strict"
+>;
+
+// Appel curifié : le regroupement est configuré dans l’étape du pipe.
+const values: string[] = ["a", "bb", "c"];
+
+const piped = DCommon.pipe(
+	values,
+	DGenerator.asyncMap(async(item) => {
+		await DCommon.timeout();
+		return item;
+	}),
+	DGenerator.asyncGroup(async(item, params) => {
+		await DCommon.timeout();
+		return DString.lengthEqual(item, 1)
+			? params.output("short", item)
+			: params.output("long", item);
+	}),
+);
+
+// La promesse se résout vers { short: ["a", "c"], long: ["bb"] }.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	Promise<{
+		readonly long?: readonly [string, ...string[]] | undefined;
+		readonly short?: readonly [
+			string & DString.LengthEqual<1>,
+			...(string & DString.LengthEqual<1>)[],
+		] | undefined;
+	}>,
+	"strict"
+>;

package/docs/API/10-lang/10-generator/10-asyncLoop.ts

@@ -0,0 +1,50 @@
+/**
+ * @title DGenerator.asyncLoop
+ *
+ * Produire une séquence asynchrone en distinguant les valeurs de `next` et celles de la sortie `exit`.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+
+// La callback peut être asynchrone ; `count` est le seul état fourni à chaque tour.
+const withoutExitValue = DCommon.pipe(
+	DGenerator.asyncLoop(async({ count, next, exit }: DGenerator.LoopParams<number>) => {
+		await DCommon.timeout();
+
+		if (count === 3) {
+			return exit();
+		}
+
+		return next(count + 1);
+	}),
+	DArray.from,
+);
+
+// La promesse se résout vers [1, 2, 3] : `exit()` termine sans ajouter de valeur.
+type _CheckWithoutExitValue = DCommon.ExpectType<
+	typeof withoutExitValue,
+	Promise<readonly number[]>,
+	"strict"
+>;
+
+// La callback est attendue à chaque tour ; les sorties sont émises avant l’appel du tour suivant.
+const withExitValue = DCommon.pipe(
+	DGenerator.asyncLoop(async({ count, next, exit }: DGenerator.LoopParams<number | "done">) => {
+		await DCommon.timeout();
+
+		if (count === 3) {
+			return exit("done");
+		}
+
+		return next(count + 1);
+	}),
+	DArray.from,
+);
+
+// La promesse se résout vers [1, 2, 3, "done"] : `exit` ajoute sa valeur en dernier.
+type _CheckWithExitValue = DCommon.ExpectType<
+	typeof withExitValue,
+	Promise<readonly (number | "done")[]>,
+	"strict"
+>;

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

@@ -0,0 +1,40 @@
+/**
+ * @title DGenerator.asyncLoopAccumulator
+ *
+ * Produire une séquence asynchrone en mettant à jour un accumulateur à chaque itération.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+
+const values = await DArray.from(DGenerator.asyncLoopAccumulator(0, async({ accumulator, count, next, exit }) => {
+	await DCommon.timeout();
+
+	return count === 3
+		? exit(Promise.resolve(accumulator))
+		: next(accumulator + 1, Promise.resolve(accumulator));
+}));
+
+// La callback et les valeurs émises peuvent être asynchrones ; les sorties sont résolues avant émission.
+type _CheckValues = DCommon.ExpectType<typeof values, readonly number[], "strict">;
+
+interface Accumulator {
+	readonly total: number;
+	readonly previous?: number;
+}
+
+const finalTotal = await DArray.from(DGenerator.asyncLoopAccumulator(
+	DGenerator.loopAccumulatorFrom<Accumulator>({ total: 0 }),
+	async({ accumulator, count, next, exit }) => {
+		await DCommon.timeout();
+
+		return count === 2
+			? exit(Promise.resolve(accumulator.total))
+			: next({
+				total: accumulator.total + 1,
+				previous: accumulator.total,
+			}, Promise.resolve(accumulator.total));
+	},
+));
+
+type _CheckFinalTotal = DCommon.ExpectType<typeof finalTotal, readonly number[], "strict">;

package/docs/API/10-lang/10-generator/10-asyncMap.ts

@@ -0,0 +1,48 @@
+/**
+ * @title DGenerator.asyncMap
+ *
+ * Transformer chaque valeur dans un générateur asynchrone, en autorisant une callback synchrone ou asynchrone.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DArray from "@duplojs/lang/array";
+import * as DGenerator from "@duplojs/lang/generator";
+import * as DNumber from "@duplojs/lang/number";
+
+const input = (async function *() {
+	await DCommon.timeout();
+	yield 1;
+	yield 2;
+})();
+
+// Appel classique : chaque valeur est doublée après l’exécution de la callback asynchrone.
+const result = DGenerator.asyncMap(
+	input,
+	async(item) => {
+		await DCommon.timeout();
+		return DNumber.sum([item, item]);
+	},
+);
+
+// La sortie est un AsyncGenerator qui produit [2, 4].
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	AsyncGenerator<number, unknown, unknown>,
+	"strict"
+>;
+
+// Appel curifié : la transformation est configurée dans l’étape du pipe.
+const piped = DCommon.pipe(
+	[1, 2, 3],
+	DGenerator.asyncMap(async(item) => {
+		await DCommon.timeout();
+		return DNumber.sum([item, item, item]);
+	}),
+	DArray.from,
+);
+
+// La promesse se résout vers [3, 6, 9].
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	Promise<readonly number[]>,
+	"strict"
+>;

package/docs/API/10-lang/10-generator/10-asyncReduce.ts

@@ -0,0 +1,63 @@
+/**
+ * @title DGenerator.asyncReduce
+ *
+ * Réduire un itérable avec un accumulateur et des sorties next ou exit dans une promesse.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+import * as DNumber from "@duplojs/lang/number";
+
+const input = (async function *() {
+	await DCommon.timeout();
+	yield 1;
+	yield 2;
+	yield 3;
+})();
+
+// Appel classique : le nombre initial est directement inféré comme accumulateur numérique.
+const result = DGenerator.asyncReduce(
+	input,
+	0,
+	async({ lastValue, item, next }) => {
+		await DCommon.timeout();
+		return next(DNumber.sum([lastValue, item]));
+	},
+);
+
+// La promesse se résout vers 6 et l’accumulateur est inféré comme number.
+type _CheckResult = DCommon.ExpectType<typeof result, Promise<number>, "strict">;
+
+type Accumulator =
+	| { total: number }
+	| { values: readonly number[] };
+
+// Appel curifié : le générique porté par reduceFrom décrit une union sans utiliser `as`.
+const piped = DCommon.pipe(
+	[1, 2, 3],
+	DGenerator.asyncReduce(DGenerator.reduceFrom<Accumulator>({ total: 0 }), async({ lastValue, next }) => {
+		await DCommon.timeout();
+		return next(lastValue);
+	}),
+);
+
+// La promesse conserve l’union { total: number } | { values: readonly number[] }.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	Promise<Accumulator>,
+	"strict"
+>;
+
+// Une sortie exit interrompt la réduction : son type string est indépendant de l’accumulateur number.
+const stopped = DGenerator.asyncReduce(
+	[1, 2, 3],
+	0,
+	({ item, lastValue, next, exit }) => item === 2
+		? exit("stop")
+		: next(DNumber.sum([lastValue, item])),
+);
+
+type _CheckStopped = DCommon.ExpectType<
+	typeof stopped,
+	Promise<number | string>,
+	"strict"
+>;

package/docs/API/10-lang/10-generator/10-chunk.ts

@@ -0,0 +1,44 @@
+/**
+ * @title DGenerator.chunk
+ *
+ * Regrouper les valeurs d’un itérable en sous-itérables de taille bornée.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+
+const input: number[] = [1, 2, 3, 4, 5];
+
+// Appel classique : les valeurs sont produites dans des groupes d’au plus deux éléments.
+const result = DGenerator.chunk(input, 2);
+
+// La sortie est un générateur qui produit [[1, 2], [3, 4], [5]].
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	Generator<
+		& readonly number[]
+		& DArray.MinElements<1>
+		& DArray.MaxElements<2>,
+		unknown,
+		unknown
+	>,
+	"strict"
+>;
+
+// Appel curifié : la taille est configurée dans l’étape du pipe.
+const piped = DCommon.pipe(
+	input,
+	DGenerator.chunk(3),
+	DArray.from,
+);
+
+// La sortie vaut [[1, 2, 3], [4, 5]].
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	readonly (
+		& readonly number[]
+		& DArray.MinElements<1>
+		& DArray.MaxElements<3>
+	)[],
+	"strict"
+>;

package/docs/API/10-lang/10-generator/10-concat.ts

@@ -0,0 +1,37 @@
+/**
+ * @title DGenerator.concat
+ *
+ * Enchaîner plusieurs itérables dans un générateur synchrone.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DArray from "@duplojs/lang/array";
+import * as DGenerator from "@duplojs/lang/generator";
+
+// Appel classique : les valeurs sont produites dans l’ordre [1, 2, 3, 4].
+const result = DGenerator.concat(
+	[1, 2],
+	[3],
+	[4],
+);
+
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	Generator<1 | 2 | 3 | 4, unknown, unknown>,
+	"strict"
+>;
+
+const tail: Iterable<number> = [3, 4];
+
+// Appel curifié : les itérables ajoutés sont configurés dans l’étape du pipe.
+const piped = DCommon.pipe(
+	[1, 2],
+	DGenerator.concat(tail),
+	DArray.from,
+);
+
+// La sortie vaut [1, 2, 3, 4].
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	readonly number[],
+	"strict"
+>;

package/docs/API/10-lang/10-generator/10-createExternalAsyncGenerator.ts

@@ -0,0 +1,29 @@
+/**
+ * @title DGenerator.createExternalAsyncGenerator
+ *
+ * Créer un générateur asynchrone dont la prochaine valeur ou la fin sont déclenchées de l’extérieur.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+
+const external = DGenerator.createExternalAsyncGenerator<number>();
+
+// L’itérateur attend un appel à `next` et produira ensuite la valeur fournie.
+const nextResult = external.next(12);
+
+type _CheckNext = DCommon.ExpectType<typeof nextResult, undefined, "strict">;
+
+// `exit` termine l’itérateur sans produire de valeur.
+const exitResult = external.exit();
+
+type _CheckExit = DCommon.ExpectType<typeof exitResult, undefined, "strict">;
+
+type _CheckExternal = DCommon.ExpectType<
+	typeof external,
+	{
+		asyncGenerator: AsyncGenerator<number, void, unknown>;
+		next(item: number): undefined;
+		exit(): undefined;
+	},
+	"strict"
+>;

package/docs/API/10-lang/10-generator/10-execute.ts

@@ -0,0 +1,44 @@
+/**
+ * @title DGenerator.execute
+ *
+ * Consommer une génératrice jusqu’à sa fin, en retournant une promesse pour les génératrices asynchrones.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+
+// Appel synchrone : `loop` rappelle sa callback comme une boucle `while`,
+// puis `map` traite chaque valeur avant qu’`execute` ne consomme la génératrice.
+const result = DCommon.pipe(
+	DGenerator.loop(({ count, next, exit }: DGenerator.LoopParams<number>) => {
+		if (count === 3) {
+			return exit();
+		}
+
+		return next(count);
+	}),
+	DGenerator.map(DCommon.forwardLog),
+	DGenerator.execute,
+);
+
+// La génératrice est consommée jusqu’à sa fin et chaque valeur est transmise à `forwardLog`.
+type _CheckResult = DCommon.ExpectType<typeof result, void, "strict">;
+
+// Appel asynchrone : `asyncLoop` produit une génératrice asynchrone,
+// et `execute` retourne une promesse résolue après le traitement de chaque valeur.
+const asyncResult = DCommon.pipe(
+	DGenerator.asyncLoop(async({ count, next, exit }: DGenerator.LoopParams<number>) => {
+		await DCommon.timeout();
+
+		return count === 3
+			? exit()
+			: next(count);
+	}),
+	DGenerator.asyncMap(DCommon.forwardLog),
+	DGenerator.execute,
+);
+
+type _CheckAsyncResult = DCommon.ExpectType<
+	typeof asyncResult,
+	Promise<void>,
+	"strict"
+>;

package/docs/API/10-lang/10-generator/10-filter.ts

@@ -0,0 +1,35 @@
+/**
+ * @title DGenerator.filter
+ *
+ * Conserver dans un générateur les valeurs acceptées par un prédicat.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DArray from "@duplojs/lang/array";
+import * as DGenerator from "@duplojs/lang/generator";
+import * as DNumber from "@duplojs/lang/number";
+
+const input: number[] = [1, 2, 3, 4];
+
+// Appel classique : seuls les nombres supérieurs à deux sont produits.
+const result = DGenerator.filter(input, DNumber.greaterThan(2));
+
+// La sortie est un générateur qui produit [3, 4] et conserve l’affinement du prédicat.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	Generator<number & DNumber.GreaterThan<2>, unknown, unknown>,
+	"strict"
+>;
+
+// Appel curifié : le prédicat est configuré dans l’étape du pipe.
+const piped = DCommon.pipe(
+	input,
+	DGenerator.filter(DNumber.isEven),
+	DArray.from,
+);
+
+// La sortie vaut [2, 4].
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	readonly (number & DNumber.Even)[],
+	"strict"
+>;

package/docs/API/10-lang/10-generator/10-flat.ts

@@ -0,0 +1,25 @@
+/**
+ * @title DGenerator.flat
+ *
+ * Aplatir récursivement les valeurs itérables jusqu’à une profondeur donnée.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+
+// Profondeur par défaut : un seul niveau est aplati et la sortie contient [1, 2, 3].
+const result = DGenerator.flat([[1, 2], [3]]);
+
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	Generator<1 | 2 | 3, void, unknown>,
+	"strict"
+>;
+
+// Une profondeur de deux aplati deux niveaux et produit également [1, 2, 3].
+const deeplyFlattened = DGenerator.flat([[[1], [2]], [[3]]], 2);
+
+type _CheckDeeplyFlattened = DCommon.ExpectType<
+	typeof deeplyFlattened,
+	Generator<1 | 2 | 3, void, unknown>,
+	"strict"
+>;

package/docs/API/10-lang/10-generator/10-group.ts

@@ -0,0 +1,44 @@
+/**
+ * @title DGenerator.group
+ *
+ * Regrouper les valeurs d’un itérable selon les sorties nommées d’une callback.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+import * as DString from "@duplojs/lang/string";
+
+const input: string[] = ["a", "bb", "c"];
+
+// Appel classique : chaque valeur est ajoutée au groupe dont le nom dépend de sa longueur.
+// Le ternaire porte sur la structure entière : `group` devient un discriminant littéral.
+const result = DGenerator.group(
+	input,
+	(item, params) => DString.lengthEqual(item, 1)
+		? params.output("short", item)
+		: params.output("long", item),
+);
+
+// La sortie vaut { short: ["a", "c"], long: ["bb"] }.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	{
+		readonly long?: readonly [string, ...string[]] | undefined;
+		readonly short?: readonly [string & DString.LengthEqual<1>, ...(string & DString.LengthEqual<1>)[]] | undefined;
+	},
+	"strict"
+>;
+
+// Appel curifié : le regroupement est configuré dans l’étape du pipe.
+const piped = DCommon.pipe(
+	input,
+	DGenerator.group((item, params) => params.output("value", item)),
+);
+
+// La sortie vaut { value: ["a", "bb", "c"] }.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	{
+		readonly value?: readonly [string, ...string[]] | undefined;
+	},
+	"strict"
+>;