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

package/docs/API/10-lang/10-dataStructure/10-string.ts

@@ -0,0 +1,22 @@
+/**
+ * @title DDataStructure.string
+ *
+ * Construire une structure représentant des chaînes de caractères.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const structure = DDataStructure.string();
+const result = structure.check("DuploJS");
+
+// La structure représente le type indiqué par son contrat.
+type _CheckStructure = DCommon.ExpectType<
+	typeof structure,
+	DDataStructure.TypeStructure<string, readonly []>,
+	"strict"
+>;
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	string,
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-stringLengthEqual.ts

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.stringLengthEqual
+ *
+ * Construire une contrainte de longueur exacte pour une chaîne.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DString from "@duplojs/lang/string";
+
+const constraint = DDataStructure.stringLengthEqual(3);
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.StringLengthEqualConstraint<3>,
+	"strict"
+>;
+
+const structure = DDataStructure.string([constraint]);
+const result = structure.check("abc");
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	string & DString.LengthEqual<3>,
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-time.ts

@@ -0,0 +1,23 @@
+/**
+ * @title DDataStructure.time
+ *
+ * Construire une structure représentant les heures DuploJS.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DChrono from "@duplojs/lang/chrono";
+
+const structure = DDataStructure.time();
+const result = structure.check("12:30:00.000");
+
+// La structure représente le type indiqué par son contrat.
+type _CheckStructure = DCommon.ExpectType<
+	typeof structure,
+	DDataStructure.TypeStructure<DChrono.TheTime, readonly []>,
+	"strict"
+>;
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	DChrono.TheTime,
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-trimmed.ts

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.trimmed
+ *
+ * Construire une contrainte de chaîne sans espaces périphériques.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DString from "@duplojs/lang/string";
+
+const constraint = DDataStructure.trimmed();
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.TrimmedConstraint,
+	"strict"
+>;
+
+const structure = DDataStructure.string([constraint]);
+const result = structure.check("DuploJS");
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	string & DString.Trimmed,
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-typeStructureIdentifier.ts

@@ -0,0 +1,33 @@
+/**
+ * @title DDataStructure.typeStructureIdentifier
+ *
+ * Identifier une structure de type et affiner son type TypeScript.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+declare const structure: DDataStructure.Structure;
+
+if (DDataStructure.typeStructureIdentifier(
+	structure,
+	DDataStructure.numberTypeKind,
+)) {
+	type _CheckStructure = DCommon.ExpectType<
+		typeof structure,
+		DDataStructure.TypeStructure<number>,
+		"strict"
+	>;
+}
+
+// La forme curifiée s’utilise comme predicate dans DCommon.when.
+const result = DCommon.when(
+	structure,
+	DDataStructure.typeStructureIdentifier(DDataStructure.numberTypeKind),
+	(numberStructure) => numberStructure.definition.type.fundamentalType,
+);
+
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	DDataStructure.Structure | typeof DDataStructure.TheNumber,
+	"one-extends-two"
+>;

package/docs/API/10-lang/10-dataStructure/10-undefined.ts

@@ -0,0 +1,22 @@
+/**
+ * @title DDataStructure.undefined
+ *
+ * Construire une structure représentant la valeur `undefined`.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const structure = DDataStructure.undefined();
+const result = structure.check(undefined);
+
+// La structure représente le type indiqué par son contrat.
+type _CheckStructure = DCommon.ExpectType<
+	typeof structure,
+	DDataStructure.TypeStructure<undefined, readonly []>,
+	"strict"
+>;
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	undefined,
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-union.ts

@@ -0,0 +1,24 @@
+/**
+ * @title DDataStructure.union
+ *
+ * Construire une structure qui accepte plusieurs structures alternatives.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const structure = DDataStructure.union([
+	DDataStructure.string(),
+	DDataStructure.number(),
+]);
+const result = structure.check("DuploJS");
+
+type _CheckStructure = DCommon.ExpectType<
+	typeof structure,
+	DDataStructure.UnionStructure<string | number, readonly []>,
+	"strict"
+>;
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	string | number,
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-unwrapLazy.ts

@@ -0,0 +1,17 @@
+/**
+ * @title DDataStructure.unwrapLazy
+ *
+ * Résoudre une structure lazy et retourner la structure qu’elle contient.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const inner = DDataStructure.string();
+const lazyStructure = DDataStructure.lazy(() => inner);
+const structure = DDataStructure.unwrapLazy(lazyStructure);
+
+type _CheckResult = DCommon.ExpectType<
+	typeof structure,
+	DDataStructure.Structure<string>,
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-url.ts

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.url
+ *
+ * Construire une contrainte d’URL valide.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DString from "@duplojs/lang/string";
+
+const constraint = DDataStructure.url();
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.UrlConstraint,
+	"strict"
+>;
+
+const structure = DDataStructure.string([constraint]);
+const result = structure.check("https://duplojs.dev");
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	string & DString.Url,
+	"strict"
+>;

package/docs/API/10-lang/10-dataStructure/10-uuid.ts

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.uuid
+ *
+ * Construire une contrainte d’UUID valide.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DString from "@duplojs/lang/string";
+
+const constraint = DDataStructure.uuid();
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.UuidConstraint,
+	"strict"
+>;
+
+const structure = DDataStructure.string([constraint]);
+const result = structure.check("550e8400-e29b-41d4-a716-446655440000");
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	string & DString.Uuid,
+	"strict"
+>;

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

@@ -0,0 +1,264 @@
+## DDataStructure
+
+Construction de contrats de données validables au runtime, composables et reflétés dans les types TypeScript.
+
+### [DDataStructure.absolutePath](10-absolutePath.ts)
+
+Construire une contrainte de chemin absolu et l’appliquer à une structure de chaîne.
+ 
+### [DDataStructure.allowedCharacters](10-allowedCharacters.ts)
+
+Construire une contrainte de caractères autorisés et l’appliquer à une structure de chaîne.
+ 
+### [DDataStructure.array](10-array.ts)
+
+Construire une structure de tableau à partir de la structure de ses éléments.
+ 
+### [DDataStructure.arrayLengthEqual](10-arrayLengthEqual.ts)
+
+Construire une contrainte de longueur exacte et l’appliquer à une structure de tableau.
+ 
+### [DDataStructure.betweenThan](10-betweenThan.ts)
+
+Construire une contrainte de nombre strictement compris entre deux bornes.
+ 
+### [DDataStructure.betweenThanOrEqual](10-betweenThanOrEqual.ts)
+
+Construire une contrainte de nombre compris entre deux bornes inclusives.
+ 
+### [DDataStructure.bigint](10-bigint.ts)
+
+Construire une structure représentant des valeurs `bigint`.
+ 
+### [DDataStructure.boolean](10-boolean.ts)
+
+Construire une structure représentant des valeurs booléennes.
+ 
+### [DDataStructure.createCodec](10-createCodec.ts)
+
+Définir la conversion entre la valeur interne d’un type fondamental et sa représentation encodée.
+ 
+### [DDataStructure.createCodecs](10-createCodecs.ts)
+
+Regrouper des codecs dans un contexte indexé par leurs types fondamentaux.
+ 
+### [DDataStructure.createErrorInterpreter](10-createErrorInterpreter.ts)
+
+Transformer les issues d’une erreur de validation ou de codec en messages interprétables.
+ 
+### [DDataStructure.date](10-date.ts)
+
+Construire une structure représentant les dates DuploJS.
+ 
+### [DDataStructure.email](10-email.ts)
+
+Construire une contrainte d’adresse email et l’appliquer à une structure de chaîne.
+ 
+### [DDataStructure.endsWith](10-endsWith.ts)
+
+Construire une contrainte de suffixe et l’appliquer à une structure de chaîne.
+ 
+### [DDataStructure.even](10-even.ts)
+
+Construire une contrainte de nombre pair et l’appliquer à une structure numérique.
+ 
+### [DDataStructure.extend](10-extend.ts)
+
+Étendre une structure objet en ajoutant ou en remplaçant des propriétés.
+ 
+### [DDataStructure.greaterThan](10-greaterThan.ts)
+
+Construire une contrainte de nombre supérieur à un seuil.
+ 
+### [DDataStructure.greaterThanOrEqual](10-greaterThanOrEqual.ts)
+
+Construire une contrainte de nombre supérieur ou égal à un seuil.
+ 
+### [DDataStructure.include](10-include.ts)
+
+Construire une contrainte d’inclusion et l’appliquer à une structure de chaîne.
+ 
+### [DDataStructure.integer](10-integer.ts)
+
+Construire une contrainte de nombre entier et l’appliquer à une structure numérique.
+ 
+### [DDataStructure.isNullStructure](10-isNullStructure.ts)
+
+Vérifier qu’une structure représente exactement le type `null`.
+ 
+### [DDataStructure.isNullable](10-isNullable.ts)
+
+Vérifier qu’une structure accepte la valeur `null`.
+ 
+### [DDataStructure.isOptional](10-isOptional.ts)
+
+Vérifier qu’une structure accepte la valeur `undefined`.
+ 
+### [DDataStructure.isUndefinedStructure](10-isUndefinedStructure.ts)
+
+Vérifier qu’une structure représente exactement le type `undefined`.
+ 
+### [DDataStructure.lazy](10-lazy.ts)
+
+Construire une structure dont la résolution est différée.
+ 
+### [DDataStructure.lessThan](10-lessThan.ts)
+
+Construire une contrainte de nombre inférieur à un seuil.
+ 
+### [DDataStructure.lessThanOrEqual](10-lessThanOrEqual.ts)
+
+Construire une contrainte de nombre inférieur ou égal à un seuil.
+ 
+### [DDataStructure.literal](10-literal.ts)
+
+Construire une structure représentant une ou plusieurs valeurs littérales.
+ 
+### [DDataStructure.maxCharacters](10-maxCharacters.ts)
+
+Construire une contrainte de longueur maximale pour une chaîne.
+ 
+### [DDataStructure.maxElements](10-maxElements.ts)
+
+Construire une contrainte de cardinalité maximale pour un tableau.
+ 
+### [DDataStructure.minCharacters](10-minCharacters.ts)
+
+Construire une contrainte de longueur minimale pour une chaîne.
+ 
+### [DDataStructure.minElements](10-minElements.ts)
+
+Construire une contrainte de cardinalité minimale pour un tableau.
+ 
+### [DDataStructure.multipleOf](10-multipleOf.ts)
+
+Construire une contrainte de multiple numérique.
+ 
+### [DDataStructure.negative](10-negative.ts)
+
+Construire une contrainte de nombre négatif ou nul.
+ 
+### [DDataStructure.notEmpty](10-notEmpty.ts)
+
+Construire une contrainte qui refuse les chaînes vides.
+ 
+### [DDataStructure.notZero](10-notZero.ts)
+
+Construire une contrainte qui refuse zéro.
+ 
+### [DDataStructure.null](10-null.ts)
+
+Construire une structure représentant la valeur `null`.
+ 
+### [DDataStructure.nullable](10-nullable.ts)
+
+Ajouter `null` aux valeurs acceptées par une structure.
+ 
+### [DDataStructure.number](10-number.ts)
+
+Construire une structure représentant des nombres.
+ 
+### [DDataStructure.numberInString](10-numberInString.ts)
+
+Construire une contrainte qui exige qu’une chaîne représente un nombre.
+ 
+### [DDataStructure.object](10-object.ts)
+
+Construire une structure objet à partir d’une forme de propriétés.
+ 
+### [DDataStructure.odd](10-odd.ts)
+
+Construire une contrainte de nombre impair.
+ 
+### [DDataStructure.optional](10-optional.ts)
+
+Ajouter `undefined` aux valeurs acceptées par une structure.
+ 
+### [DDataStructure.partial](10-partial.ts)
+
+Rendre optionnelles toutes les propriétés d’une structure objet.
+ 
+### [DDataStructure.path](10-path.ts)
+
+Construire une contrainte qui exige une chaîne représentant un chemin.
+ 
+### [DDataStructure.positive](10-positive.ts)
+
+Construire une contrainte de nombre positif ou nul.
+ 
+### [DDataStructure.record](10-record.ts)
+
+Construire une structure d’objet dont les clés et les valeurs sont structurées.
+ 
+### [DDataStructure.refine](10-refine.ts)
+
+Construire une contrainte personnalisée à partir d’un predicate DuploJS.
+ 
+### [DDataStructure.regex](10-regex.ts)
+
+Construire une contrainte de correspondance avec une expression régulière.
+ 
+### [DDataStructure.required](10-required.ts)
+
+Rendre obligatoires les propriétés d’une structure objet qui peuvent être `undefined`.
+ 
+### [DDataStructure.safe](10-safe.ts)
+
+Construire une contrainte d’entier sûr JavaScript.
+ 
+### [DDataStructure.segmentPath](10-segmentPath.ts)
+
+Construire une contrainte qui exige un segment de chemin.
+ 
+### [DDataStructure.startsWith](10-startsWith.ts)
+
+Construire une contrainte de préfixe et l’appliquer à une structure de chaîne.
+ 
+### [DDataStructure.strictNegative](10-strictNegative.ts)
+
+Construire une contrainte de nombre strictement négatif.
+ 
+### [DDataStructure.strictPositive](10-strictPositive.ts)
+
+Construire une contrainte de nombre strictement positif.
+ 
+### [DDataStructure.string](10-string.ts)
+
+Construire une structure représentant des chaînes de caractères.
+ 
+### [DDataStructure.stringLengthEqual](10-stringLengthEqual.ts)
+
+Construire une contrainte de longueur exacte pour une chaîne.
+ 
+### [DDataStructure.time](10-time.ts)
+
+Construire une structure représentant les heures DuploJS.
+ 
+### [DDataStructure.trimmed](10-trimmed.ts)
+
+Construire une contrainte de chaîne sans espaces périphériques.
+ 
+### [DDataStructure.typeStructureIdentifier](10-typeStructureIdentifier.ts)
+
+Identifier une structure de type et affiner son type TypeScript.
+ 
+### [DDataStructure.undefined](10-undefined.ts)
+
+Construire une structure représentant la valeur `undefined`.
+ 
+### [DDataStructure.union](10-union.ts)
+
+Construire une structure qui accepte plusieurs structures alternatives.
+ 
+### [DDataStructure.unwrapLazy](10-unwrapLazy.ts)
+
+Résoudre une structure lazy et retourner la structure qu’elle contient.
+ 
+### [DDataStructure.url](10-url.ts)
+
+Construire une contrainte d’URL valide.
+ 
+### [DDataStructure.uuid](10-uuid.ts)
+
+Construire une contrainte d’UUID valide.
+ 

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

@@ -0,0 +1,3 @@
+## DDataStructure
+
+Construction de contrats de données validables au runtime, composables et reflétés dans les types TypeScript.

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

@@ -0,0 +1,44 @@
+/**
+ * @title DEither.asyncGroup
+ *
+ * Regrouper séquentiellement des résultats synchrones ou asynchrones dans un Success.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const objectResult = DEither.asyncGroup({
+	user: () => Promise.resolve(DEither.success("Alice")),
+	count: DEither.success(2),
+});
+
+// La sortie attend chaque entrée et regroupe les valeurs déballées dans une Promise.
+type _CheckObject = DCommon.ExpectType<
+	typeof objectResult,
+	Promise<DEither.Success<{
+		user: "Alice";
+		count: 2;
+	}>>,
+	"strict"
+>;
+
+// Le premier Left est retourné et les getters placés après lui ne sont pas exécutés.
+const errorResult = DEither.asyncGroup({
+	user: () => Promise.resolve(DEither.success("Alice")),
+	error: () => Promise.resolve(DEither.error("user-not-found")),
+	skipped: () => Promise.resolve(DEither.success(2)),
+});
+type _CheckError = DCommon.ExpectType<
+	typeof errorResult,
+	Promise<DEither.Error<"user-not-found"> | DEither.Success<{
+		user: "Alice";
+		error: never;
+		skipped: 2;
+	}>>,
+	"strict"
+>;
+
+const tupleResult = DEither.asyncGroup([
+	() => Promise.resolve(DEither.success("Alice")),
+	() => Promise.resolve(DEither.success(2)),
+] as const);
+type _CheckTuple = DCommon.ExpectType<typeof tupleResult, Promise<DEither.Success<["Alice", 2]>>, "strict">;

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

@@ -0,0 +1,23 @@
+/**
+ * @title DEither.asyncSafeCallback
+ *
+ * Convertir une callback ou une promesse et ses exceptions en résultat asynchrone.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const result = DEither.asyncSafeCallback(() => Promise.resolve("saved" as const));
+
+// La sortie est toujours une Promise et inclut le Left standard des erreurs capturées.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	Promise<DEither.SafeCallbackSuccess<"saved"> | DEither.SafeCallbackError>,
+	"strict"
+>;
+
+const promiseInput = DEither.asyncSafeCallback(Promise.resolve("saved" as const));
+type _CheckPromiseInput = DCommon.ExpectType<
+	typeof promiseInput,
+	Promise<DEither.SafeCallbackSuccess<"saved"> | DEither.SafeCallbackError>,
+	"strict"
+>;

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

@@ -0,0 +1,12 @@
+/**
+ * @title DEither.error
+ *
+ * Créer un Left standardisé avec l’information `error`.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const result = DEither.error("connection-failed");
+
+// La sortie est un Left portant l’information littérale "error".
+type _CheckResult = DCommon.ExpectType<typeof result, DEither.Error<"connection-failed">, "strict">;

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

@@ -0,0 +1,13 @@
+/**
+ * @title DEither.expect
+ *
+ * Retourner un Either sans modifier sa valeur ni son type.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const input = DEither.success("saved");
+const result = DEither.expect(input);
+
+// La sortie conserve exactement le Right fourni en entrée.
+type _CheckResult = DCommon.ExpectType<typeof result, DEither.Success<"saved">, "strict">;

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

@@ -0,0 +1,12 @@
+/**
+ * @title DEither.fail
+ *
+ * Créer un Left standardisé représentant un échec sans valeur.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const result = DEither.fail();
+
+// La sortie est `Fail`, un Left dont la valeur est `undefined`.
+type _CheckResult = DCommon.ExpectType<typeof result, DEither.Fail, "strict">;

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

@@ -0,0 +1,28 @@
+/**
+ * @title DEither.forwardAssertsSelection
+ *
+ * Affirmer qu’une information est sélectionnée et lever une exception sinon.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+const input = DEither.success("saved") as DEither.Success<"saved"> | DEither.Left<"missing", Error>;
+
+// Appel classique : le type est réduit aux informations sélectionnées.
+const direct = DEither.forwardAssertsSelection(input, {
+	success: true,
+	missing: false,
+});
+type _CheckDirect = DCommon.ExpectType<typeof direct, DEither.Success<"saved">, "strict">;
+
+// Appel curifié : l’affirmation est placée dans le pipe.
+const piped = DCommon.pipe(
+	input,
+	DEither.forwardAssertsSelection({
+		success: true,
+		missing: false,
+	}),
+);
+type _CheckPiped = DCommon.ExpectType<typeof piped, DEither.Success<"saved">, "strict">;
+
+// Une information marquée `false` provoque `ForwardAssertsSelectionError` au runtime.