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

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

@@ -0,0 +1,46 @@
+/**
+ * @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 as const;
+	yield 2 as const;
+})();
+
+const tail = (async function *() {
+	await DCommon.timeout();
+	yield 4 as const;
+	yield 5 as const;
+})();
+
+// Appel classique : les valeurs sont produites dans l’ordre [1, 2, 3, 4, 5].
+const result = DGenerator.asyncConcat(head, [3] as const, 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,
+	] as number[])),
+	DArray.from,
+);
+
+// La promesse se résout vers [1, 2, 3, 4].
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	Promise<readonly number[]>,
+	"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]] as const;
+	yield [[3]] as const;
+})();
+
+// 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<readonly [1] | readonly [2] | readonly [3], void, unknown>,
+	"strict"
+>;
+
+const nestedInput = (async function *() {
+	await DCommon.timeout();
+	yield [[1], [2]] as const;
+	yield [[3]] as const;
+})();
+
+// 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<1 | 2 | 3, 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,59 @@
+/**
+ * @title DGenerator.asyncLoop
+ *
+ * Produire une séquence asynchrone dans un pipe en distinguant l’arrêt avec ou sans dernière valeur émise.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+import * as DNumber from "@duplojs/lang/number";
+
+// Arrêt sans dernière valeur : `exit()` termine la boucle asynchrone sans émettre d’élément supplémentaire.
+const withoutExitValue = DCommon.pipe(
+	DGenerator.asyncLoop(async({ previousOutput, next, exit }: DGenerator.LoopParams<number>) => {
+		await DCommon.timeout();
+
+		if (previousOutput === 3) {
+			return exit();
+		}
+
+		return next(
+			previousOutput === undefined
+				? 1
+				: DNumber.sum([previousOutput, 1]),
+		);
+	}),
+	DArray.from,
+);
+
+// La promesse se résout vers [1, 2, 3] : `exit()` n’émet aucune dernière valeur.
+type _CheckWithoutExitValue = DCommon.ExpectType<
+	typeof withoutExitValue,
+	Promise<readonly number[]>,
+	"strict"
+>;
+
+// Arrêt avec dernière valeur : `exit("done")` termine la boucle en l’émettant.
+const withExitValue = DCommon.pipe(
+	DGenerator.asyncLoop(async({ previousOutput, next, exit }: DGenerator.LoopParams<number>) => {
+		await DCommon.timeout();
+
+		if (previousOutput === 3) {
+			return exit("done");
+		}
+
+		return next(
+			previousOutput === undefined
+				? 1
+				: DNumber.sum([previousOutput, 1]),
+		);
+	}),
+	DArray.from,
+);
+
+// La promesse se résout vers [1, 2, 3, "done"] : la valeur de `exit` est émise comme dernier élément.
+type _CheckWithExitValue = DCommon.ExpectType<
+	typeof withExitValue,
+	Promise<readonly (number | "done")[]>,
+	"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] as const,
+	[3] as const,
+	[4] as const,
+);
+
+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]] as const);
+
+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]]] as const, 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"
+>;

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

@@ -0,0 +1,48 @@
+/**
+ * @title DGenerator.groupOutput
+ *
+ * Construire une sortie nommée destinée à la fonction de regroupement.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+import * as DPattern from "@duplojs/lang/pattern";
+import * as DString from "@duplojs/lang/string";
+
+declare const value: number;
+
+// Appel classique : associer directement la valeur au groupe `even`.
+const result = DGenerator.groupOutput("even", value);
+
+// La sortie associe le groupe `even` à la valeur fournie.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	DGenerator.GroupOutputResult<"even", number>,
+	"strict"
+>;
+
+// Composition dans un pipe : le pattern `when` sélectionne le premier groupe,
+// puis `otherwise` traite le reste sans ouvrir de callback intermédiaire.
+const input: string[] = ["a", "bb", "c"];
+
+const piped = DCommon.pipe(
+	input,
+	DGenerator.group(
+		DCommon.innerPipe(
+			DPattern.when(
+				DString.lengthEqual(1),
+				DGenerator.groupOutput("short"),
+			),
+			DPattern.otherwise(DGenerator.groupOutput("long")),
+		),
+	),
+);
+
+// La sortie vaut { short: ["a", "c"], long: ["bb"] }.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	{
+		readonly long?: readonly [string, ...string[]] | undefined;
+		readonly short?: readonly [string & DString.LengthEqual<1>, ...(string & DString.LengthEqual<1>)[]] | undefined;
+	},
+	"strict"
+>;