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

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

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

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

@@ -0,0 +1,19 @@
+/**
+ * @title DDataStructure.nullable
+ *
+ * Ajouter `null` aux valeurs acceptées par une structure.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DString from "@duplojs/lang/string";
+
+const structure = DDataStructure.nullable(
+	DDataStructure.string([DDataStructure.email()]),
+);
+const result = structure.check(null);
+
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	string & DString.Email | null,
+	"strict"
+>;

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

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

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

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.numberInString
+ *
+ * Construire une contrainte qui exige qu’une chaîne représente un nombre.
+ */
+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.numberInString();
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.NumberInStringConstraint,
+	"strict"
+>;
+
+const structure = DDataStructure.string([constraint]);
+const result = structure.check("42");
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	string & DString.Number,
+	"strict"
+>;

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

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.object
+ *
+ * Construire une structure objet à partir d’une forme de propriétés.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const structure = DDataStructure.object({
+	name: DDataStructure.string(),
+	age: DDataStructure.number(),
+});
+const result = structure.check({
+	name: "Jane",
+	age: 30,
+});
+
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	{
+		readonly name: string;
+		readonly age: number;
+	},
+	"strict"
+>;

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

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.odd
+ *
+ * Construire une contrainte de nombre impair.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DNumber from "@duplojs/lang/number";
+
+const constraint = DDataStructure.odd();
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.OddConstraint,
+	"strict"
+>;
+
+const structure = DDataStructure.number([constraint]);
+const result = structure.check(7);
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	number & DNumber.Odd,
+	"strict"
+>;

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

@@ -0,0 +1,19 @@
+/**
+ * @title DDataStructure.optional
+ *
+ * Ajouter `undefined` aux valeurs acceptées par une structure.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DString from "@duplojs/lang/string";
+
+const structure = DDataStructure.optional(
+	DDataStructure.string([DDataStructure.email()]),
+);
+const result = structure.check(undefined);
+
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	string & DString.Email | undefined,
+	"strict"
+>;

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

@@ -0,0 +1,23 @@
+/**
+ * @title DDataStructure.partial
+ *
+ * Rendre optionnelles toutes les propriétés d’une structure objet.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const source = DDataStructure.object({
+	name: DDataStructure.string(),
+	age: DDataStructure.number(),
+});
+const structure = DDataStructure.partial(source);
+const result = structure.check({ name: "Jane" });
+
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	{
+		readonly name?: string;
+		readonly age?: number;
+	},
+	"strict"
+>;

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

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.path
+ *
+ * Construire une contrainte qui exige une chaîne représentant un chemin.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DPath from "@duplojs/lang/path";
+
+const constraint = DDataStructure.path();
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.PathConstraint,
+	"strict"
+>;
+
+const structure = DDataStructure.string([constraint]);
+const result = structure.check("src/index.ts");
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	string & DPath.Path,
+	"strict"
+>;

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

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.positive
+ *
+ * Construire une contrainte de nombre positif ou nul.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DNumber from "@duplojs/lang/number";
+
+const constraint = DDataStructure.positive();
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.PositiveConstraint,
+	"strict"
+>;
+
+const structure = DDataStructure.number([constraint]);
+const result = structure.check(1);
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	number & DNumber.Positive,
+	"strict"
+>;

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

@@ -0,0 +1,22 @@
+/**
+ * @title DDataStructure.record
+ *
+ * Construire une structure d’objet dont les clés et les valeurs sont structurées.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const structure = DDataStructure.record(
+	DDataStructure.string(),
+	DDataStructure.number(),
+);
+const result = structure.check({
+	first: 1,
+	second: 2,
+});
+
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	Partial<{ readonly [Prop in string]: number }>,
+	"strict"
+>;

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

@@ -0,0 +1,27 @@
+/**
+ * @title DDataStructure.refine
+ *
+ * Construire une contrainte personnalisée à partir d’un predicate DuploJS.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DString from "@duplojs/lang/string";
+
+const constraint = DDataStructure.refine(
+	DString.startsWith("user:"),
+);
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.RefineConstraint<string, `user:${string}`>,
+	"strict"
+>;
+
+const structure = DDataStructure.string([constraint]);
+const result = structure.check("user:42");
+
+// Le predicate affine la valeur validée vers le format du préfixe.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	`user:${string}`,
+	"strict"
+>;

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

@@ -0,0 +1,24 @@
+/**
+ * @title DDataStructure.regex
+ *
+ * Construire une contrainte de correspondance avec une expression régulière.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const constraint = DDataStructure.regex(/^user:[0-9]+$/);
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.RegexConstraint,
+	"strict"
+>;
+
+const structure = DDataStructure.string([constraint]);
+const result = structure.check("user:42");
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	string,
+	"strict"
+>;

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

@@ -0,0 +1,21 @@
+/**
+ * @title DDataStructure.required
+ *
+ * Rendre obligatoires les propriétés d’une structure objet qui peuvent être `undefined`.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const source = DDataStructure.object({
+	name: DDataStructure.optional(DDataStructure.string()),
+});
+const structure = DDataStructure.required(source);
+const result = structure.check({ name: "Jane" });
+
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	{
+		readonly name: string;
+	},
+	"strict"
+>;

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

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.safe
+ *
+ * Construire une contrainte d’entier sûr JavaScript.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DNumber from "@duplojs/lang/number";
+
+const constraint = DDataStructure.safe();
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.SafeConstraint,
+	"strict"
+>;
+
+const structure = DDataStructure.number([constraint]);
+const result = structure.check(42);
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	number & DNumber.Safe,
+	"strict"
+>;

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

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.segmentPath
+ *
+ * Construire une contrainte qui exige un segment de chemin.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DPath from "@duplojs/lang/path";
+
+const constraint = DDataStructure.segmentPath();
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.SegmentPathConstraint,
+	"strict"
+>;
+
+const structure = DDataStructure.string([constraint]);
+const result = structure.check("index.ts");
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	string & DPath.Segment,
+	"strict"
+>;

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

@@ -0,0 +1,24 @@
+/**
+ * @title DDataStructure.startsWith
+ *
+ * Construire une contrainte de préfixe et l’appliquer à une structure de chaîne.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const constraint = DDataStructure.startsWith("user:");
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.StartsWithConstraint<"user:">,
+	"strict"
+>;
+
+const structure = DDataStructure.string([constraint]);
+const result = structure.check("user:42");
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	`user:${string}`,
+	"strict"
+>;

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

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.strictNegative
+ *
+ * Construire une contrainte de nombre strictement négatif.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DNumber from "@duplojs/lang/number";
+
+const constraint = DDataStructure.strictNegative();
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.StrictNegativeConstraint,
+	"strict"
+>;
+
+const structure = DDataStructure.number([constraint]);
+const result = structure.check(-1);
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	number & DNumber.StrictNegative,
+	"strict"
+>;

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

@@ -0,0 +1,25 @@
+/**
+ * @title DDataStructure.strictPositive
+ *
+ * Construire une contrainte de nombre strictement positif.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DNumber from "@duplojs/lang/number";
+
+const constraint = DDataStructure.strictPositive();
+type _CheckConstraint = DCommon.ExpectType<
+	typeof constraint,
+	DDataStructure.StrictPositiveConstraint,
+	"strict"
+>;
+
+const structure = DDataStructure.number([constraint]);
+const result = structure.check(1);
+
+// Une validation réussie expose une valeur portant le type du contrat.
+type _CheckStructureValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof structure>,
+	number & DNumber.StrictPositive,
+	"strict"
+>;

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 | DDataStructure.FundamentalType,
+	"strict"
+>;

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