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

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

@@ -0,0 +1,55 @@
+/**
+ * @title DGenerator.loop
+ *
+ * Produire une séquence 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 sans émettre d’élément supplémentaire.
+const withoutExitValue = DCommon.pipe(
+	DGenerator.loop(({ previousOutput, next, exit }: DGenerator.LoopParams<number>) => {
+		if (previousOutput === 3) {
+			return exit();
+		}
+
+		return next(
+			previousOutput === undefined
+				? 1
+				: DNumber.sum([previousOutput, 1]),
+		);
+	}),
+	DArray.from,
+);
+
+// La sortie vaut [1, 2, 3] : `next` émet les valeurs intermédiaires, mais `exit()` n’en émet aucune.
+type _CheckWithoutExitValue = DCommon.ExpectType<
+	typeof withoutExitValue,
+	readonly number[],
+	"strict"
+>;
+
+// Arrêt avec dernière valeur : `exit(value)` termine la boucle en émettant cette valeur.
+const withExitValue = DCommon.pipe(
+	DGenerator.loop(({ previousOutput, next, exit }: DGenerator.LoopParams<number>) => {
+		if (previousOutput === 3) {
+			return exit(4);
+		}
+
+		return next(
+			previousOutput === undefined
+				? 1
+				: DNumber.sum([previousOutput, 1]),
+		);
+	}),
+	DArray.from,
+);
+
+// La sortie vaut [1, 2, 3, 4] : `exit(4)` ajoute la dernière valeur à la séquence.
+type _CheckWithExitValue = DCommon.ExpectType<
+	typeof withExitValue,
+	readonly number[],
+	"strict"
+>;

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

@@ -0,0 +1,35 @@
+/**
+ * @title DGenerator.map
+ *
+ * Transformer chaque valeur d’un itérable dans un générateur.
+ */
+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 = [1, 2, 3] as const;
+
+// Appel classique : chaque nombre est doublé.
+const result = DGenerator.map(input, (item) => DNumber.sum([item, item]));
+
+// La sortie est un générateur qui produit [2, 4, 6].
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	Generator<number, unknown, unknown>,
+	"strict"
+>;
+
+// Appel curifié : la transformation est configurée dans l’étape du pipe.
+const piped = DCommon.pipe(
+	input,
+	DGenerator.map((item) => DNumber.sum([item, item, item])),
+	DArray.from,
+);
+
+// La sortie vaut [3, 6, 9].
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	readonly number[],
+	"strict"
+>;

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

@@ -0,0 +1,51 @@
+/**
+ * @title DGenerator.reduce
+ *
+ * Réduire un itérable avec un accumulateur et des sorties next ou exit.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+import * as DNumber from "@duplojs/lang/number";
+
+const input = [1, 2, 3] as const;
+
+// Appel classique : le nombre initial est directement inféré comme accumulateur numérique.
+const result = DGenerator.reduce(
+	input,
+	0,
+	({ lastValue, item, next }) => next(DNumber.sum([lastValue, item])),
+);
+
+// La sortie vaut 6 et le type de l’accumulateur est inféré comme number.
+type _CheckResult = DCommon.ExpectType<typeof result, 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(
+	input,
+	DGenerator.reduce(
+		DGenerator.reduceFrom<Accumulator>({ total: 0 }),
+		({ lastValue, next }) => next(lastValue),
+	),
+);
+
+// La sortie conserve l’union { total: number } | { values: readonly number[] }.
+type _CheckPiped = DCommon.ExpectType<typeof piped, Accumulator, "strict">;
+
+// Une sortie exit interrompt la réduction : son type string est indépendant de l’accumulateur number.
+const stopped = DGenerator.reduce(
+	input,
+	0,
+	({ item, lastValue, next, exit }) => item === 2
+		? exit("stop")
+		: next(DNumber.sum([lastValue, item])),
+);
+
+type _CheckStopped = DCommon.ExpectType<
+	typeof stopped,
+	number | string,
+	"strict"
+>;

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

@@ -0,0 +1,30 @@
+/**
+ * @title DGenerator.reduceFrom
+ *
+ * Marquer une valeur initiale, éventuellement élargie par un générique, pour une réduction.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DGenerator from "@duplojs/lang/generator";
+
+// Pour une valeur primitive, son type est inféré directement.
+const numberInitial = DGenerator.reduceFrom(0);
+
+type _CheckNumberInitial = DCommon.ExpectType<
+	typeof numberInitial,
+	DGenerator.ReduceFromResult<number>,
+	"strict"
+>;
+
+type Accumulator =
+	| { total: number }
+	| { values: readonly number[] };
+
+// Pour une structure plus large, le générique de reduceFrom fixe la shape ou l’union sans utiliser `as`.
+const result = DGenerator.reduce(
+	[1, 2, 3],
+	DGenerator.reduceFrom<Accumulator>({ total: 0 }),
+	({ lastValue, next }) => next(lastValue),
+);
+
+// La réduction désempaquette l’accumulateur et conserve l’union définie par reduceFrom.
+type _CheckResult = DCommon.ExpectType<typeof result, Accumulator, "strict">;

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

@@ -0,0 +1,84 @@
+## DGenerator
+
+Création et composition de génératrices synchrones ou asynchrones pour produire, transformer, filtrer, réduire et consommer des séquences de valeurs.
+
+### [DGenerator.asyncChunk](10-asyncChunk.ts)
+
+Regrouper les valeurs d’un itérable asynchrone en sous-itérables de taille bornée.
+ 
+### [DGenerator.asyncConcat](10-asyncConcat.ts)
+
+Enchaîner plusieurs itérables synchrones ou asynchrones dans un générateur asynchrone.
+ 
+### [DGenerator.asyncFilter](10-asyncFilter.ts)
+
+Conserver dans un générateur asynchrone les valeurs acceptées par un prédicat.
+ 
+### [DGenerator.asyncFlat](10-asyncFlat.ts)
+
+Aplatir récursivement les valeurs itérables d’un générateur asynchrone jusqu’à une profondeur donnée.
+ 
+### [DGenerator.asyncGroup](10-asyncGroup.ts)
+
+Regrouper les valeurs d’un itérable asynchrone selon les sorties nommées d’une callback.
+ 
+### [DGenerator.asyncLoop](10-asyncLoop.ts)
+
+Produire une séquence asynchrone dans un pipe en distinguant l’arrêt avec ou sans dernière valeur émise.
+ 
+### [DGenerator.asyncMap](10-asyncMap.ts)
+
+Transformer chaque valeur dans un générateur asynchrone, en autorisant une callback synchrone ou asynchrone.
+ 
+### [DGenerator.asyncReduce](10-asyncReduce.ts)
+
+Réduire un itérable avec un accumulateur et des sorties next ou exit dans une promesse.
+ 
+### [DGenerator.chunk](10-chunk.ts)
+
+Regrouper les valeurs d’un itérable en sous-itérables de taille bornée.
+ 
+### [DGenerator.concat](10-concat.ts)
+
+Enchaîner plusieurs itérables dans un générateur synchrone.
+ 
+### [DGenerator.createExternalAsyncGenerator](10-createExternalAsyncGenerator.ts)
+
+Créer un générateur asynchrone dont la prochaine valeur ou la fin sont déclenchées de l’extérieur.
+ 
+### [DGenerator.execute](10-execute.ts)
+
+Consommer une génératrice jusqu’à sa fin, en retournant une promesse pour les génératrices asynchrones.
+ 
+### [DGenerator.filter](10-filter.ts)
+
+Conserver dans un générateur les valeurs acceptées par un prédicat.
+ 
+### [DGenerator.flat](10-flat.ts)
+
+Aplatir récursivement les valeurs itérables jusqu’à une profondeur donnée.
+ 
+### [DGenerator.group](10-group.ts)
+
+Regrouper les valeurs d’un itérable selon les sorties nommées d’une callback.
+ 
+### [DGenerator.groupOutput](10-groupOutput.ts)
+
+Construire une sortie nommée destinée à la fonction de regroupement.
+ 
+### [DGenerator.loop](10-loop.ts)
+
+Produire une séquence dans un pipe en distinguant l’arrêt avec ou sans dernière valeur émise.
+ 
+### [DGenerator.map](10-map.ts)
+
+Transformer chaque valeur d’un itérable dans un générateur.
+ 
+### [DGenerator.reduce](10-reduce.ts)
+
+Réduire un itérable avec un accumulateur et des sorties next ou exit.
+ 
+### [DGenerator.reduceFrom](10-reduceFrom.ts)
+
+Marquer une valeur initiale, éventuellement élargie par un générique, pour une réduction.
+ 

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

@@ -0,0 +1,3 @@
+## DGenerator
+
+Création et composition de génératrices synchrones ou asynchrones pour produire, transformer, filtrer, réduire et consommer des séquences de valeurs.

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

@@ -0,0 +1,3 @@
+# @duplojs/lang
+
+Primitives fonctionnelles indépendantes de la plateforme pour composer des transformations, manipuler les données et préserver leurs garanties de typage.

package/docs/API/index.md

@@ -0,0 +1,3 @@
+# Référence API
+
+Références des fonctions publiques de l’écosystème DuploJS, organisées par package, namespace et domaine.

package/docs/API.llms.md

@@ -0,0 +1,31 @@
+# Référence API
+
+Références des fonctions publiques de l’écosystème DuploJS, organisées par package, namespace et domaine.
+
+# @duplojs/lang
+
+Primitives fonctionnelles indépendantes de la plateforme pour composer des transformations, manipuler les données et préserver leurs garanties de typage.
+
+## [DArray](API/10-lang/10-array/index.llms.md)
+
+Opérations immuables de lecture, transformation, sélection, réduction et modification de tableaux, avec prise en compte de leurs contraintes de typage.
+
+## [DChrono](API/10-lang/10-chrono/index.llms.md)
+
+Création, calcul, comparaison, sérialisation et formatage des dates, heures, durées et fuseaux horaires dans les représentations Chrono de DuploJS.
+
+## [DCommon](API/10-lang/10-common/index.llms.md)
+
+Fonctions générales de composition, de transformation, de contrôle de flux et de manipulation des valeurs partagées par les autres domaines DuploJS.
+
+## [DDataStructure](API/10-lang/10-dataStructure/index.llms.md)
+
+Construction de contrats de données validables au runtime, composables et reflétés dans les types TypeScript.
+
+## [DEither](API/10-lang/10-either/index.llms.md)
+
+Création, discrimination, transformation et propagation des réussites ou des échecs représentés par `Either`.
+
+## [DGenerator](API/10-lang/10-generator/index.llms.md)
+
+Création et composition de génératrices synchrones ou asynchrones pour produire, transformer, filtrer, réduire et consommer des séquences de valeurs.

package/docs/concepts/01-fundamental/01-constraint/01-use.ts

@@ -0,0 +1,22 @@
+/**
+ * @title Acquisition des contraintes.
+ *
+ * Vérification runtime et narrowing vers un type contraint.
+ */
+import * as DNumber from "@duplojs/lang/number";
+
+// Une contrainte existe uniquement dans le typage : elle ne modifie ni ne valide la valeur.
+// L’intersection compose ici deux garanties établies par les predicates.
+type Age = number & DNumber.Integer & DNumber.Positive;
+
+// @ts-expect-error Le littéral seul ne porte pas les contraintes attendues.
+const age: Age = 12;
+
+// Chaque vérification réussie enrichit le type sans changer la valeur runtime.
+const maybeAge = 12;
+if (
+	DNumber.isInteger(maybeAge)
+	&& DNumber.isPositive(maybeAge)
+) {
+	const age: Age = maybeAge;
+}

package/docs/concepts/01-fundamental/01-constraint/10-built-in-constraint.ts

@@ -0,0 +1,37 @@
+/**
+ * @title Composition des contraintes fournies.
+ *
+ * Réutilisation et composition des contraintes disponibles dans les domaines.
+ */
+import type * as DArray from "@duplojs/lang/array";
+import type * as DNumber from "@duplojs/lang/number";
+import type * as DString from "@duplojs/lang/string";
+
+// Avant de créer une contrainte, vérifier celles du domaine concerné.
+// Une intersection cumule les garanties ; déclarer ce type ne valide aucune donnée.
+// Nom sans espaces aux extrémités, contenant entre 5 et 35 caractères.
+type Name = (
+	& string
+	& DString.MaxCharacters<35>
+	& DString.MinCharacters<5>
+	& DString.Trimmed
+);
+
+// Entier strictement positif, supérieur ou égal à 18 et strictement inférieur à 100.
+type Age = (
+	& number
+	& DNumber.Integer
+	& DNumber.StrictPositive
+	& DNumber.GreaterThanOrEqual<18>
+	& DNumber.LessThan<100>
+);
+
+// Tableau de 1 à 15 éléments, dont chaque élément respecte aussi son contrat.
+type Friends = (
+	& {
+		name: Name;
+		age: Age;
+	}[]
+	& DArray.MinElements<1>
+	& DArray.MaxElements<15>
+);

package/docs/concepts/01-fundamental/01-constraint/20-manipulation.ts

@@ -0,0 +1,38 @@
+/**
+ * @title Manipulation des valeurs contraintes.
+ *
+ * Exploitation des contraintes par les fonctions DuploJS pour simplifier la manipulation des valeurs.
+ */
+import * as DTuple from "@duplojs/lang/tuple";
+import * as DString from "@duplojs/lang/string";
+import * as DArray from "@duplojs/lang/array";
+
+// Les primitives exploitent les garanties d’entrée pour préciser leur sortie.
+// Une transformation conserve, adapte ou supprime les contraintes selon ce qui reste vrai.
+declare const userEmail: string & DString.Email;
+
+// Un email dans son format contenant obligatoirement un "@"
+// donne forcément un tableau avec minimum 2 éléments.
+// readonly string[] & DArray.MinElements<2>
+const splitEmail = DString.split(userEmail, "@");
+
+// Le passage du tableau en tuple est fait en interprétant la contrainte
+// DArray.MinElements<2>, ce qui garantit au moins deux éléments, sans imposer une longueur exacte.
+// readonly [string, string, ...string[]]
+const [first, second, ...maybeRest] = DTuple.from(splitEmail);
+
+// Les accès garantis par la cardinalité évitent le type string | undefined.
+// string
+const firstElement = DArray.first(splitEmail);
+
+// string
+const lastElement = DArray.last(splitEmail);
+
+// string
+const secondElement = DArray.at(splitEmail, 1);
+
+// string | undefined
+const otherElement = DArray.at(splitEmail, 10);
+
+// Le résultat porte une garantie de cardinalité ; les fragments ne sont plus typés Email.
+// Privilégier les transformations immuables : une mutation pourrait invalider une garantie.

package/docs/concepts/01-fundamental/01-constraint/30-cast.ts

@@ -0,0 +1,62 @@
+/**
+ * @title Compatibilité statique des contraintes.
+ *
+ * Cast par implication, valeurs littérales et inférence en contexte générique.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DNumber from "@duplojs/lang/number";
+import type * as DString from "@duplojs/lang/string";
+
+// cast restitue la valeur sans validation runtime : TypeScript doit prouver la compatibilité.
+// Il convertit une garantie existante, ou exploite une valeur connue statiquement.
+// Une donnée runtime sans preuve doit d’abord être vérifiée par un predicate.
+declare function myFunction(name: string & DString.MinCharacters<10>): void;
+
+declare const validName: string & DString.MinCharacters<15>;
+// Au moins 15 caractères implique au moins 10 caractères.
+myFunction(DCommon.cast(validName));
+
+declare const invalidName: string & DString.MinCharacters<5>;
+// Erreur de type car la contrainte `DString.MinCharacters<5>`
+// n'induit pas `string & DString.MinCharacters<10>`
+// @ts-expect-error constraint error
+myFunction(DCommon.cast(invalidName));
+
+// De même, une borne strictement inférieure à 10 implique une borne inférieure à 20.
+declare const belowTen: number & DNumber.LessThan<10>;
+const belowTwenty: number & DNumber.LessThan<20> = DCommon.cast(belowTen);
+
+// Les valeurs littérales permettent aussi de calculer la compatibilité sans validation.
+const declaredName: string & DString.MinCharacters<10> = DCommon.cast("thisIsASuperName");
+const declaredAge: number & DNumber.GreaterThanOrEqual<18> = DCommon.cast(20);
+
+declare function myFunctionWithGeneric<
+	GenericName extends string & DString.MinCharacters<10>,
+>(name: GenericName): void;
+
+// Ici, le paramètre générique ne fournit pas à cast un type de retour assez précis.
+// satisfies explicite la cible pour permettre le calcul de compatibilité.
+myFunctionWithGeneric(
+	DCommon.cast("thisIsASuperName") satisfies string & DString.MinCharacters<10>,
+);
+
+// @ts-expect-error cast ne peut pas inférer ici le type de retour attendu.
+myFunctionWithGeneric(DCommon.cast("thisIsASuperName"));
+
+declare function createUser<
+	GenericUser extends {
+		name: string & DString.MinCharacters<10>;
+		age: number & DNumber.GreaterThanOrEqual<18>;
+	},
+>(name: GenericUser): GenericUser;
+
+// infer calcule les contraintes attendues tout en conservant la valeur littérale.
+// Il est adapté aux constantes connues statiquement et ne valide rien au runtime.
+createUser({
+	name: DCommon.infer("thisIsASuperName"),
+	age: DCommon.infer(18),
+});
+// {
+//     name: "thisIsASuperName" & DString.MinCharacters<10>;
+//     age: 18 & DNumber.GreaterThanOrEqual<18>;
+// }

package/docs/concepts/01-fundamental/01-constraint/40-custom-constraint.ts

@@ -0,0 +1,45 @@
+/**
+ * @title Contraintes personnalisées.
+ *
+ * Déclaration, predicate de validation et extension des règles de cast.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DNumber from "@duplojs/lang/number";
+
+// Étendre Constraint avec un identifiant propre à la propriété modélisée.
+// Cette interface n’ajoute aucun marqueur à la valeur runtime.
+interface Adult extends DCommon.Constraint<"example-adult"> {}
+
+// La signature du predicate doit correspondre à une vérification réelle.
+function isAdult(input: number): input is number & Adult {
+	return DNumber.greaterThanOrEqual(input, 18);
+}
+
+declare const candidate: number;
+if (isAdult(candidate)) {
+	const adult: number & Adult = candidate;
+}
+
+// Les règles de cast peuvent être étendues par augmentation du module common.
+// Cette règle reconnaît la preuve GreaterThanOrEqual<18> comme suffisante pour Adult.
+// Elle ne couvre volontairement pas toutes les autres bornes compatibles.
+declare module "@duplojs/lang/common" {
+	interface ComputeCastConstraintNumberRule<
+		GenericValue extends number,
+		GenericExpectedConstraint extends DCommon.BaseConstraint,
+	> {
+		exampleAdult: GenericExpectedConstraint extends Adult
+			? GenericValue extends DNumber.GreaterThanOrEqual<18>
+				? unknown
+				: DCommon.CastError<"La preuve de majorité est absente.", GenericValue, GenericExpectedConstraint>
+			: never;
+	}
+}
+
+// unknown accepte la compatibilité, CastError la refuse, never ignore les autres cibles.
+// Consulter les interfaces de règles existantes pour étendre les autres domaines.
+declare const verifiedAge: number & DNumber.GreaterThanOrEqual<18>;
+const adultFromProof: number & Adult = DCommon.cast(verifiedAge);
+
+// @ts-expect-error Un nombre sans preuve ne peut pas être converti en Adult.
+const adultWithoutProof: number & Adult = DCommon.cast(candidate);

package/docs/concepts/01-fundamental/01-constraint/index.md

@@ -0,0 +1,3 @@
+## Contraintes de typage
+
+Garanties sur les valeurs : acquisition, composition, propagation, compatibilité statique et contraintes personnalisées.

package/docs/concepts/01-fundamental/02-currying/01-use.ts

@@ -0,0 +1,33 @@
+/**
+ * @title Currification et composition avec pipe.
+ *
+ * Configurer les opérations avant de recevoir la donnée et enchaîner ses transformations.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DArray from "@duplojs/lang/array";
+import * as DString from "@duplojs/lang/string";
+
+// La forme curifiée reçoit les paramètres, puis la donnée transmise par pipe.
+// Si la fonction retournée ne déclare pas ses propres génériques, ses types sont
+// fixés dès l'appel de configuration, même si la surcharge extérieure est générique.
+// Écrire alors l'appel curifié directement comme étape de pipe ou asyncPipe pour
+// fournir le contexte d'inférence attendu. Passer à un pipe une variable contenant
+// une fonction déjà préparée ne déplace pas sa configuration dans ce contexte.
+// Ne pas forcer cette préparation avec des génériques explicites, annotations ou casts.
+// Formater chaque pipe sur plusieurs lignes, un argument par ligne et la fermeture
+// sur sa propre ligne, même avec seulement une donnée et une étape.
+// Privilégier pipe dès qu’une donnée subit plusieurs transformations,
+// ou si le traitement est susceptible d’en accueillir d’autres.
+// Utiliser en priorité les fonctions fournies par l’écosystème.
+const normalizedTags = DCommon.pipe(
+	" TypeScript, DuploJS, Functional " as const,
+	// Configure le séparateur ; pipe fournit ensuite la chaîne.
+	DString.split(","),
+	// Configure la transformation ; pipe fournit le tableau.
+	DArray.map(DString.trim),
+	DArray.filter(DString.isNotEmpty),
+	DArray.map(DString.toLowerCase),
+);
+// Résultat : ["typescript", "duplojs", "functional"].
+// Chaque étape reçoit la sortie précédente ; les types suivent ces transformations.
+// On peut ajouter, retirer ou réordonner les étapes sans restructurer le traitement.