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

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)),
+]);
+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,25 @@
+/**
+ * @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";
+
+declare const saved: "saved";
+const result = DEither.asyncSafeCallback(() => Promise.resolve(saved));
+
+// 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 savedPromise = Promise.resolve(saved);
+const promiseInput = DEither.asyncSafeCallback(savedPromise);
+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-extractErrorInLeft.ts

@@ -0,0 +1,45 @@
+/**
+ * @title DEither.extractErrorInLeft
+ *
+ * Extraire d’un Left les erreurs DuploJS sélectionnées par leur identifiant.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+class MissingError extends DCommon.DuploJSError.parentClass("missing") {}
+class ForbiddenError extends DCommon.DuploJSError.parentClass("forbidden") {}
+class UnexpectedError extends DCommon.DuploJSError.parentClass("unexpected") {}
+
+type LoadResult = (
+	| DEither.Left<"load-error", MissingError | ForbiddenError | UnexpectedError>
+	| DEither.Right<"success", string>
+	| null
+);
+
+declare const result: LoadResult;
+
+// Appel classique : l’erreur sélectionnée reçoit son identifiant comme information.
+const extracted = DEither.extractErrorInLeft(result, "missing");
+type _CheckExtracted = DCommon.ExpectType<
+	typeof extracted,
+	| DEither.Left<"load-error", ForbiddenError | UnexpectedError>
+	| DEither.Left<"missing", MissingError>
+	| DEither.Right<"success", string>
+	| null,
+	"strict"
+>;
+
+// Appel curifié : extraire plusieurs erreurs avant de traiter l’erreur restante.
+const separated = DCommon.pipe(
+	result,
+	DEither.extractErrorInLeft(["missing", "forbidden"]),
+);
+type _CheckSeparated = DCommon.ExpectType<
+	typeof separated,
+	| DEither.Left<"load-error", UnexpectedError>
+	| DEither.Left<"missing", MissingError>
+	| DEither.Left<"forbidden", ForbiddenError>
+	| DEither.Right<"success", string>
+	| null,
+	"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";
+
+declare const input: 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.

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

@@ -0,0 +1,58 @@
+/**
+ * @title DEither.group
+ *
+ * Regrouper des Right dans un Success en arrêtant au premier Left.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+// La forme objet conserve les clés et déballe les valeurs des Right.
+const objectResult = DEither.group({
+	user: DEither.success("Alice"),
+	count: DEither.success(2),
+});
+type _CheckObject = DCommon.ExpectType<
+	typeof objectResult,
+	DEither.Success<{
+		user: "Alice";
+		count: 2;
+	}>,
+	"strict"
+>;
+
+// Les getters permettent de différer le calcul de chaque résultat.
+const withGetters = DEither.group({
+	user: () => DEither.success("Alice"),
+	count: () => DEither.success(2),
+});
+type _CheckGetters = DCommon.ExpectType<
+	typeof withGetters,
+	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.group({
+	user: () => DEither.success("Alice"),
+	error: () => DEither.error("user-not-found"),
+	skipped: () => DEither.success(2),
+});
+type _CheckError = DCommon.ExpectType<
+	typeof errorResult,
+	DEither.Error<"user-not-found"> | DEither.Success<{
+		user: "Alice";
+		error: never;
+		skipped: 2;
+	}>,
+	"strict"
+>;
+
+const tupleResult = DEither.group([
+	DEither.success("Alice"),
+	DEither.success(2),
+]);
+// La forme tuple conserve sa longueur et déballe chaque Right.
+type _CheckTuple = DCommon.ExpectType<typeof tupleResult, DEither.Success<["Alice", 2]>, "strict">;

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

@@ -0,0 +1,30 @@
+/**
+ * @title DEither.hasInformation
+ *
+ * Tester l’information d’un Either et affiner le statut et la valeur.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: DEither.Success<"saved"> | DEither.Left<"missing", Error>;
+
+if (DEither.hasInformation(input, "missing")) {
+	type _CheckInput = DCommon.ExpectType<typeof input, DEither.Left<"missing", Error>, "strict">;
+	const reason = DEither.unwrapLeft(input);
+	type _CheckReason = DCommon.ExpectType<typeof reason, Error, "strict">;
+}
+
+// La forme curifiée est directement utilisable comme predicate de DCommon.when.
+const result = DCommon.pipe(
+	input,
+	DCommon.when(
+		DEither.hasInformation("missing"),
+		DEither.unwrapLeft,
+	),
+);
+
+// Le cas ciblé devient Error ; le cas non ciblé conserve son Right.
+type _CheckResult = DCommon.ExpectType<typeof result, Error | DEither.Success<"saved">, "strict">;
+
+const matches = DEither.hasInformation(DEither.success("saved"), "success");
+type _CheckMatches = DCommon.ExpectType<typeof matches, boolean, "strict">;

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

@@ -0,0 +1,25 @@
+/**
+ * @title DEither.isLeft
+ *
+ * Vérifier le statut Left et affiner le type de la valeur.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: DEither.Success<"saved"> | DEither.Left<"missing", Error>;
+
+if (DEither.isLeft(input)) {
+	// Dans cette branche, seul le Left reste possible.
+	type _CheckInput = DCommon.ExpectType<typeof input, DEither.Left<"missing", Error>, "strict">;
+	const value = DEither.unwrapLeft(input);
+	type _CheckValue = DCommon.ExpectType<typeof value, Error, "strict">;
+}
+
+const result = DCommon.pipe(
+	input,
+	DCommon.when(
+		DEither.isLeft,
+		DEither.unwrapLeft,
+	),
+);
+type _CheckResult = DCommon.ExpectType<typeof result, Error | DEither.Success<"saved">, "strict">;

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

@@ -0,0 +1,25 @@
+/**
+ * @title DEither.isRight
+ *
+ * Vérifier le statut Right et affiner le type de la valeur.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const input: DEither.Success<"saved"> | DEither.Left<"missing", Error>;
+
+if (DEither.isRight(input)) {
+	// Dans cette branche, seul le Right reste possible.
+	type _CheckInput = DCommon.ExpectType<typeof input, DEither.Success<"saved">, "strict">;
+	const value = DEither.unwrapRight(input);
+	type _CheckValue = DCommon.ExpectType<typeof value, "saved", "strict">;
+}
+
+const result = DCommon.pipe(
+	input,
+	DCommon.when(
+		DEither.isRight,
+		DEither.unwrapRight,
+	),
+);
+type _CheckResult = DCommon.ExpectType<typeof result, "saved" | DEither.Left<"missing", Error>, "strict">;