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

package/docs/API/10-lang/10-either/10-whenIsSelected.ts

@@ -0,0 +1,33 @@
+/**
+ * @title DEither.whenIsSelected
+ *
+ * Transformer la valeur des variantes marquées `true` dans une sélection.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: DEither.Left<"invalid", string> | DEither.Success<"saved">;
+
+// Appel classique : seule la variante invalid est transformée.
+const direct = DEither.whenIsSelected(
+	input,
+	{
+		invalid: true,
+		success: false,
+	},
+	(value) => `invalid:${value}`,
+);
+type _CheckDirect = DCommon.ExpectType<typeof direct, `invalid:${string}` | DEither.Success<"saved">, "strict">;
+
+// Appel curifié : la sélection et la callback sont configurées dans le pipe.
+const piped = DCommon.pipe(
+	input,
+	DEither.whenIsSelected(
+		{
+			invalid: true,
+			success: false,
+		},
+		(value) => `invalid:${value}`,
+	),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, `invalid:${string}` | DEither.Success<"saved">, "strict">;

package/docs/API/10-lang/10-either/10-whenIsSelectedOtherwise.ts

@@ -0,0 +1,35 @@
+/**
+ * @title DEither.whenIsSelectedOtherwise
+ *
+ * Transformer les variantes sélectionnées et traiter toutes les autres dans une branche de repli.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: DEither.Left<"invalid", string> | DEither.Success<"saved">;
+
+// Appel classique : la branche otherwise reçoit le Right non sélectionné.
+const direct = DEither.whenIsSelectedOtherwise(
+	input,
+	{
+		invalid: true,
+		success: false,
+	},
+	(value) => `invalid:${value}`,
+	(value) => DEither.unwrapRight(value),
+);
+type _CheckDirect = DCommon.ExpectType<typeof direct, `invalid:${string}` | "saved", "strict">;
+
+// Appel curifié : la sélection et les deux callbacks sont configurées dans le pipe.
+const piped = DCommon.pipe(
+	input,
+	DEither.whenIsSelectedOtherwise(
+		{
+			invalid: true,
+			success: false,
+		},
+		(value) => `invalid:${value}`,
+		(value) => DEither.unwrapRight(value),
+	),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, `invalid:${string}` | "saved", "strict">;

package/docs/API/10-lang/10-either/index.llms.md

@@ -0,0 +1,196 @@
+## DEither
+
+Création, discrimination, transformation et propagation des réussites ou des échecs représentés par `Either`.
+
+### [DEither.asyncGroup](10-asyncGroup.ts)
+
+Regrouper séquentiellement des résultats synchrones ou asynchrones dans un Success.
+ 
+### [DEither.asyncSafeCallback](10-asyncSafeCallback.ts)
+
+Convertir une callback ou une promesse et ses exceptions en résultat asynchrone.
+ 
+### [DEither.error](10-error.ts)
+
+Créer un Left standardisé avec l’information `error`.
+ 
+### [DEither.expect](10-expect.ts)
+
+Retourner un Either sans modifier sa valeur ni son type.
+ 
+### [DEither.extractErrorInLeft](10-extractErrorInLeft.ts)
+
+Extraire d’un Left les erreurs DuploJS sélectionnées par leur identifiant.
+ 
+### [DEither.fail](10-fail.ts)
+
+Créer un Left standardisé représentant un échec sans valeur.
+ 
+### [DEither.forwardAssertsSelection](10-forwardAssertsSelection.ts)
+
+Affirmer qu’une information est sélectionnée et lever une exception sinon.
+ 
+### [DEither.group](10-group.ts)
+
+Regrouper des Right dans un Success en arrêtant au premier Left.
+ 
+### [DEither.hasInformation](10-hasInformation.ts)
+
+Tester l’information d’un Either et affiner le statut et la valeur.
+ 
+### [DEither.isLeft](10-isLeft.ts)
+
+Vérifier le statut Left et affiner le type de la valeur.
+ 
+### [DEither.isRight](10-isRight.ts)
+
+Vérifier le statut Right et affiner le type de la valeur.
+ 
+### [DEither.isSelected](10-isSelected.ts)
+
+Tester une sélection d’informations et affiner l’union d’Either.
+ 
+### [DEither.keepAsRightByInformation](10-keepAsRightByInformation.ts)
+
+Reclasser comme Right les variantes portant certaines informations.
+ 
+### [DEither.keepAsRightSelection](10-keepAsRightSelection.ts)
+
+Reclasser les variantes selon une sélection exhaustive d’informations.
+ 
+### [DEither.left](10-left.ts)
+
+Créer un résultat Left avec une information et une valeur optionnelle.
+ 
+### [DEither.matchInformation](10-matchInformation.ts)
+
+Appliquer exhaustivement une callback selon l’information du résultat.
+ 
+### [DEither.matchInformationCombination](10-matchInformationCombination.ts)
+
+Appliquer un traitement pour chaque combinaison d’informations d’une collection d’Either.
+ 
+### [DEither.matchInformationCombinationOtherwise](10-matchInformationCombinationOtherwise.ts)
+
+Traiter les combinaisons d’informations choisies et fournir un cas de repli.
+ 
+### [DEither.matchInformationOtherwise](10-matchInformationOtherwise.ts)
+
+Appliquer une callback pour certaines informations et une branche de repli pour les autres.
+ 
+### [DEither.none](10-none.ts)
+
+Créer le Left représentant l’absence d’une valeur.
+ 
+### [DEither.ok](10-ok.ts)
+
+Créer un Right standardisé représentant une réussite sans valeur.
+ 
+### [DEither.result](10-result.ts)
+
+Créer un état contextualisé de type Result, sans lui attribuer un succès ou un échec.
+ 
+### [DEither.rewriteInformation](10-rewriteInformation.ts)
+
+Renommer certaines informations en conservant le statut et la valeur.
+ 
+### [DEither.right](10-right.ts)
+
+Créer un résultat Right avec une information et une valeur optionnelle.
+ 
+### [DEither.rightAsyncPipe](10-rightAsyncPipe.ts)
+
+Enchaîner des transformations asynchrones sur la valeur d’un Right en arrêtant au premier Left.
+ 
+### [DEither.rightPipe](10-rightPipe.ts)
+
+Enchaîner des transformations sur la valeur d’un Right en arrêtant au premier Left.
+ 
+### [DEither.safeCallback](10-safeCallback.ts)
+
+Convertir une valeur ou une exception d’une callback en Either.
+ 
+### [DEither.some](10-some.ts)
+
+Créer un Right représentant une valeur présente dans un Maybe.
+ 
+### [DEither.success](10-success.ts)
+
+Créer un Right standardisé avec l’information `success`.
+ 
+### [DEither.toMaybe](10-toMaybe.ts)
+
+Convertir une valeur, une absence ou un Either en représentation Maybe.
+ 
+### [DEither.unwrapByInformation](10-unwrapByInformation.ts)
+
+Extraire les variantes portant une information donnée et transmettre les autres.
+ 
+### [DEither.unwrapByInformationOrThrow](10-unwrapByInformationOrThrow.ts)
+
+Extraire une information ciblée ou lever une exception si elle est absente.
+ 
+### [DEither.unwrapLeft](10-unwrapLeft.ts)
+
+Extraire la valeur d’un Left et laisser les autres valeurs inchangées.
+ 
+### [DEither.unwrapLeftOrThrow](10-unwrapLeftOrThrow.ts)
+
+Extraire un Left ou lever une exception lorsque le statut attendu n’est pas présent.
+ 
+### [DEither.unwrapOr](10-unwrapOr.ts)
+
+Extraire la valeur d’un Right ou fournir une valeur de remplacement.
+ 
+### [DEither.unwrapOtherwise](10-unwrapOtherwise.ts)
+
+Extraire la valeur d’un Right ou calculer une valeur de remplacement pour les autres cas.
+ 
+### [DEither.unwrapRight](10-unwrapRight.ts)
+
+Extraire la valeur d’un Right et laisser les autres valeurs inchangées.
+ 
+### [DEither.unwrapRightOrThrow](10-unwrapRightOrThrow.ts)
+
+Extraire un Right ou lever une exception lorsque le statut attendu n’est pas présent.
+ 
+### [DEither.unwrapSelection](10-unwrapSelection.ts)
+
+Extraire les variantes marquées `true` dans une sélection et transmettre les autres.
+ 
+### [DEither.unwrapSelectionOrThrow](10-unwrapSelectionOrThrow.ts)
+
+Extraire une variante sélectionnée ou lever une exception lorsqu’elle ne l’est pas.
+ 
+### [DEither.whenHasInformation](10-whenHasInformation.ts)
+
+Transformer la valeur des variantes portant une information donnée.
+ 
+### [DEither.whenHasInformationOtherwise](10-whenHasInformationOtherwise.ts)
+
+Traiter les variantes ciblées par information et fournir une branche de repli.
+ 
+### [DEither.whenIsLeft](10-whenIsLeft.ts)
+
+Transformer la valeur d’un Left et transmettre les autres résultats inchangés.
+ 
+### [DEither.whenIsLeftOtherwise](10-whenIsLeftOtherwise.ts)
+
+Traiter séparément les Left et les autres résultats.
+ 
+### [DEither.whenIsRight](10-whenIsRight.ts)
+
+Transformer la valeur d’un Right et transmettre les autres résultats inchangés.
+ 
+### [DEither.whenIsRightOtherwise](10-whenIsRightOtherwise.ts)
+
+Traiter séparément les Right et les autres résultats.
+ 
+### [DEither.whenIsSelected](10-whenIsSelected.ts)
+
+Transformer la valeur des variantes marquées `true` dans une sélection.
+ 
+### [DEither.whenIsSelectedOtherwise](10-whenIsSelectedOtherwise.ts)
+
+Transformer les variantes sélectionnées et traiter toutes les autres dans une branche de repli.
+ 

package/docs/API/10-lang/10-either/index.md

@@ -0,0 +1,3 @@
+## DEither
+
+Création, discrimination, transformation et propagation des réussites ou des échecs représentés par `Either`.

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

@@ -0,0 +1,55 @@
+/**
+ * @title DGenerator.asyncChunk
+ *
+ * Regrouper les valeurs d’un itérable asynchrone 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 = (async function *() {
+	await DCommon.timeout();
+	yield 1 as number;
+	yield 2 as number;
+	yield 3 as number;
+})();
+
+// Appel classique : les valeurs sont produites dans des groupes d’au plus deux éléments.
+const result = DGenerator.asyncChunk(input, 2);
+
+// La sortie est un AsyncGenerator qui produit [[1, 2], [3]].
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	AsyncGenerator<
+		& 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(
+	(async function *() {
+		await DCommon.timeout();
+		yield 1 as number;
+		yield 2 as number;
+		yield 3 as number;
+		yield 4 as number;
+	})(),
+	DGenerator.asyncChunk(3),
+	DArray.from,
+);
+
+// La promesse se résout vers [[1, 2, 3], [4]].
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	Promise<readonly (
+		& readonly number[]
+		& DArray.MinElements<1>
+		& DArray.MaxElements<3>
+	)[]>,
+	"strict"
+>;

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