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

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

@@ -0,0 +1,92 @@
+## DNumber
+
+Prédicats et transformations fonctionnelles pour comparer, vérifier, agréger et trier des nombres tout en conservant leurs contraintes de typage.
+
+### [DNumber.betweenThan](10-betweenThan.ts)
+
+Vérifier qu’un nombre est strictement compris entre deux bornes.
+ 
+### [DNumber.betweenThanOrEqual](10-betweenThanOrEqual.ts)
+
+Vérifier qu’un nombre appartient à un intervalle fermé.
+ 
+### [DNumber.greaterThan](10-greaterThan.ts)
+
+Tester ou établir qu’un nombre est strictement supérieur à une borne.
+ 
+### [DNumber.greaterThanOrEqual](10-greaterThanOrEqual.ts)
+
+Tester ou établir qu’un nombre est supérieur ou égal à une borne.
+ 
+### [DNumber.isEven](10-isEven.ts)
+
+Vérifier qu’un nombre est pair et établir cette contrainte dans le type.
+ 
+### [DNumber.isInteger](10-isInteger.ts)
+
+Vérifier qu’un nombre est entier et établir cette contrainte dans le type.
+ 
+### [DNumber.isMultipleOf](10-isMultipleOf.ts)
+
+Tester ou établir qu’un nombre est un multiple d’une valeur donnée.
+ 
+### [DNumber.isNegative](10-isNegative.ts)
+
+Vérifier qu’un nombre est négatif ou nul et établir cette contrainte.
+ 
+### [DNumber.isNotZero](10-isNotZero.ts)
+
+Vérifier qu’un nombre est différent de zéro et établir cette contrainte.
+ 
+### [DNumber.isOdd](10-isOdd.ts)
+
+Vérifier qu’un nombre est impair et établir cette contrainte dans le type.
+ 
+### [DNumber.isPositive](10-isPositive.ts)
+
+Vérifier qu’un nombre est positif ou nul et établir cette contrainte.
+ 
+### [DNumber.isSafe](10-isSafe.ts)
+
+Vérifier qu’un nombre est fini, non-NaN et représentable avec une précision sûre.
+ 
+### [DNumber.isStrictNegative](10-isStrictNegative.ts)
+
+Vérifier qu’un nombre est strictement négatif et établir cette contrainte.
+ 
+### [DNumber.isStrictPositive](10-isStrictPositive.ts)
+
+Vérifier qu’un nombre est strictement positif et établir cette contrainte.
+ 
+### [DNumber.lessThan](10-lessThan.ts)
+
+Tester ou établir qu’un nombre est strictement inférieur à une borne.
+ 
+### [DNumber.lessThanOrEqual](10-lessThanOrEqual.ts)
+
+Tester ou établir qu’un nombre est inférieur ou égal à une borne.
+ 
+### [DNumber.max](10-max.ts)
+
+Retourner le plus grand nombre d’une collection non vide.
+ 
+### [DNumber.maxOf](10-maxOf.ts)
+
+Calculer le maximum d’une collection non vide avec un parcours explicite.
+ 
+### [DNumber.min](10-min.ts)
+
+Retourner le plus petit nombre d’une collection non vide.
+ 
+### [DNumber.minOf](10-minOf.ts)
+
+Calculer le minimum d’une collection non vide avec un parcours explicite.
+ 
+### [DNumber.sort](10-sort.ts)
+
+Trier une copie d’une collection de nombres dans l’ordre croissant ou décroissant.
+ 
+### [DNumber.sum](10-sum.ts)
+
+Additionner les nombres d’une collection.
+ 

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

@@ -0,0 +1,3 @@
+## DNumber
+
+Prédicats et transformations fonctionnelles pour comparer, vérifier, agréger et trier des nombres tout en conservant leurs contraintes de typage.

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

@@ -0,0 +1,41 @@
+/**
+ * @title DObject.assign
+ *
+ * Fusionner les propriétés d’un objet dans une nouvelle valeur.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+
+const source = {
+	id: 1,
+	name: "Duplo",
+};
+const result = DObject.assign(source, { active: true });
+
+// La valeur obtenue est { id: 1, name: "Duplo", active: true }.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	{
+		id: number;
+		name: string;
+		active: boolean;
+	},
+	"strict"
+>;
+
+// La forme curifiée s’utilise comme étape de transformation.
+const piped = DCommon.pipe(
+	source,
+	DObject.assign({ active: true }),
+);
+
+// La valeur obtenue contient les mêmes propriétés fusionnées.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	{
+		id: number;
+		name: string;
+		active: boolean;
+	},
+	"strict"
+>;

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

@@ -0,0 +1,15 @@
+/**
+ * @title DObject.countKeys
+ *
+ * Compter les clés runtime d’un objet.
+ */
+import * as DObject from "@duplojs/lang/object";
+import type * as DCommon from "@duplojs/lang/common";
+
+const result = DObject.countKeys({
+	name: "Duplo",
+	version: 1,
+});
+
+// La valeur obtenue est 2.
+type _CheckResult = DCommon.ExpectType<typeof result, number, "strict">;

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

@@ -0,0 +1,63 @@
+/**
+ * @title DObject.deepDiscriminate
+ *
+ * Discriminer une union d’objets à partir d’une propriété imbriquée.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+
+type Event =
+	| {
+		profile: {
+			role: "admin";
+			name: string;
+		};
+	}
+	| {
+		profile: {
+			role: "member";
+			name: string;
+		};
+	};
+interface AdminEvent {
+	profile: {
+		role: "admin";
+		name: string;
+	};
+}
+
+interface MemberEvent {
+	profile: {
+		role: "member";
+		name: string;
+	};
+}
+
+declare const event: Event;
+
+if (DObject.deepDiscriminate(event, "profile.role", "admin")) {
+	type _CheckIfEvent = DCommon.ExpectType<typeof event, AdminEvent, "strict">;
+	const name = DObject.getDeepProperty(event, "profile.name");
+	type _CheckIfName = DCommon.ExpectType<typeof name, string, "strict">;
+}
+
+const result = DObject.deepDiscriminate(event, "profile.role", "admin");
+
+// Le predicate retourne true uniquement pour l’événement administrateur.
+type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;
+
+// La forme curifiée est passée directement comme predicate à DCommon.when.
+const name = DCommon.pipe(
+	event,
+	DCommon.when(
+		DObject.deepDiscriminate("profile.role", "admin"),
+		(adminEvent) => {
+			type _CheckPredicatedInput = DCommon.ExpectType<typeof adminEvent, AdminEvent, "strict">;
+
+			return DObject.getDeepProperty(adminEvent, "profile.name");
+		},
+	),
+);
+
+// Le nom est lu pour l’administrateur ; sinon l’événement initial est conservé.
+type _CheckName = DCommon.ExpectType<typeof name, string | MemberEvent, "strict">;

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

@@ -0,0 +1,35 @@
+/**
+ * @title DObject.deepOverride
+ *
+ * Remplacer récursivement les valeurs définies d’un objet sans modifier la source.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+
+const source = {
+	profile: {
+		name: "Duplo",
+		active: false,
+	},
+};
+
+const result = DObject.deepOverride(source, {
+	profile: {
+		active: true,
+	},
+});
+
+// La valeur obtenue conserve la forme de la source avec active à true.
+type _CheckResult = DCommon.ExpectType<typeof result, typeof source, "strict">;
+
+const piped = DCommon.pipe(
+	source,
+	DObject.deepOverride({
+		profile: {
+			name: "AgentKit",
+		},
+	}),
+);
+
+// La forme curifiée effectue le même remplacement récursif dans un pipe.
+type _CheckPiped = DCommon.ExpectType<typeof piped, typeof source, "strict">;

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

@@ -0,0 +1,55 @@
+/**
+ * @title DObject.discriminate
+ *
+ * Discriminer une union d’objets à partir d’une propriété.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+
+type Event =
+	| {
+		type: "created";
+		id: string;
+	}
+	| {
+		type: "deleted";
+		id: number;
+	};
+interface CreatedEvent {
+	type: "created";
+	id: string;
+}
+
+interface DeletedEvent {
+	type: "deleted";
+	id: number;
+}
+
+declare const event: Event;
+
+if (DObject.discriminate(event, "type", "created")) {
+	type _CheckIfEvent = DCommon.ExpectType<typeof event, CreatedEvent, "strict">;
+	const id = event.id;
+	type _CheckIfId = DCommon.ExpectType<typeof id, string, "strict">;
+}
+
+const result = DObject.discriminate(event, "type", "created");
+
+// Le predicate retourne true pour l’événement created.
+type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;
+
+// La forme curifiée est passée directement comme predicate à DCommon.when.
+const id = DCommon.pipe(
+	event,
+	DCommon.when(
+		DObject.discriminate("type", "created"),
+		(createdEvent) => {
+			type _CheckPredicatedInput = DCommon.ExpectType<typeof createdEvent, CreatedEvent, "strict">;
+
+			return createdEvent.id;
+		},
+	),
+);
+
+// L’identifiant est une chaîne pour created ; sinon l’événement initial est conservé.
+type _CheckId = DCommon.ExpectType<typeof id, string | DeletedEvent, "strict">;

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

@@ -0,0 +1,43 @@
+/**
+ * @title DObject.discriminateEntryKey
+ *
+ * Tester ou affiner une entrée selon sa clé.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+
+type Entry =
+	| readonly ["name", DCommon.AnyValue]
+	| readonly ["version", DCommon.AnyValue];
+
+declare const entry: Entry;
+
+if (DObject.discriminateEntryKey(entry, DCommon.equal("name"))) {
+	const [key] = entry;
+	type _CheckIfKey = DCommon.ExpectType<typeof key, "name", "strict">;
+}
+
+const result = DObject.discriminateEntryKey(entry, DCommon.equal("name"));
+
+// La valeur obtenue est true pour l’entrée dont la clé vaut name.
+type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;
+
+// La forme curifiée est passée directement comme predicate à DCommon.when.
+const key = DCommon.pipe(
+	entry,
+	DCommon.when(
+		DObject.discriminateEntryKey(DCommon.equal("name")),
+		(narrowedEntry) => {
+			type _CheckPredicatedKey = DCommon.ExpectType<typeof narrowedEntry[0], "name", "strict">;
+
+			return narrowedEntry[0];
+		},
+	),
+);
+
+// La clé name est extraite lorsque le predicate réussit ; sinon l’entrée version est conservée.
+type _CheckPreserved = DCommon.ExpectType<
+	typeof key,
+	"name" | readonly ["version", DCommon.AnyValue],
+	"strict"
+>;

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

@@ -0,0 +1,44 @@
+/**
+ * @title DObject.discriminateEntryValue
+ *
+ * Tester ou affiner une entrée selon sa valeur.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+
+type Entry =
+	| readonly ["name", string]
+	| readonly ["version", number];
+
+declare const entry: Entry;
+
+if (DObject.discriminateEntryValue(entry, DCommon.isType("string"))) {
+	type _CheckIfValue = DCommon.ExpectType<typeof entry[1], string, "strict">;
+	const [, name] = entry;
+	type _CheckIfName = DCommon.ExpectType<typeof name, string, "strict">;
+}
+
+const result = DObject.discriminateEntryValue(entry, DCommon.isType("string"));
+
+// La valeur obtenue est true lorsque la valeur de l’entrée est une chaîne.
+type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;
+
+// La forme curifiée est passée directement comme predicate à DCommon.when.
+const value = DCommon.pipe(
+	entry,
+	DCommon.when(
+		DObject.discriminateEntryValue(DCommon.isType("string")),
+		(narrowedEntry) => {
+			type _CheckPredicatedValue = DCommon.ExpectType<typeof narrowedEntry[1], string, "strict">;
+
+			return narrowedEntry[1];
+		},
+	),
+);
+
+// La valeur est extraite avec le type string lorsque le predicate réussit ; sinon l’entrée version est conservée.
+type _CheckPreserved = DCommon.ExpectType<
+	typeof value,
+	string | readonly ["version", number],
+	"strict"
+>;

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

@@ -0,0 +1,19 @@
+/**
+ * @title DObject.entries
+ *
+ * Convertir les propriétés d’un objet en entrées typées.
+ */
+import * as DObject from "@duplojs/lang/object";
+import type * as DCommon from "@duplojs/lang/common";
+
+const result = DObject.entries({
+	name: "Duplo",
+	version: 1,
+});
+
+// La valeur obtenue contient les couples ["name", string] et ["version", number].
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	readonly (readonly ["name", string] | readonly ["version", number])[],
+	"strict"
+>;

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

@@ -0,0 +1,17 @@
+/**
+ * @title DObject.entry
+ *
+ * Construire une entrée objet en conservant les types de sa clé et de sa valeur.
+ */
+import * as DObject from "@duplojs/lang/object";
+import type * as DCommon from "@duplojs/lang/common";
+
+declare const value: "Duplo";
+const result = DObject.entry("name", value);
+
+// La valeur obtenue est l’entrée readonly ["name", "Duplo"].
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	readonly ["name", "Duplo"],
+	"strict"
+>;

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

@@ -0,0 +1,23 @@
+/**
+ * @title DObject.fromEntries
+ *
+ * Reconstruire un objet typé à partir d’une collection d’entrées.
+ */
+import * as DObject from "@duplojs/lang/object";
+import type * as DCommon from "@duplojs/lang/common";
+
+const entries = [
+	DObject.entry("name", "Duplo"),
+	DObject.entry("version", 1),
+];
+const result = DObject.fromEntries(entries);
+
+// La valeur obtenue est un objet dont les propriétés name et version sont optionnelles dans le type inféré.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	{
+		name?: string;
+		version?: number;
+	},
+	"strict"
+>;

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

@@ -0,0 +1,26 @@
+/**
+ * @title DObject.getDeepProperty
+ *
+ * Lire une propriété imbriquée avec un chemin vérifié par TypeScript.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+
+const source = {
+	profile: {
+		name: "Duplo",
+	},
+};
+
+const result = DObject.getDeepProperty(source, "profile.name");
+
+// La valeur obtenue est "Duplo".
+type _CheckResult = DCommon.ExpectType<typeof result, string, "strict">;
+
+const piped = DCommon.pipe(
+	source,
+	DObject.getDeepProperty("profile.name"),
+);
+
+// Le chemin curifié lit la même propriété dans un pipe.
+type _CheckPiped = DCommon.ExpectType<typeof piped, string, "strict">;

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

@@ -0,0 +1,24 @@
+/**
+ * @title DObject.getProperty
+ *
+ * Lire une propriété d’un objet en conservant son type.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+
+const source = {
+	name: "Duplo",
+	version: 1,
+};
+const result = DObject.getProperty(source, "name");
+
+// La valeur obtenue est "Duplo".
+type _CheckResult = DCommon.ExpectType<typeof result, string, "strict">;
+
+const piped = DCommon.pipe(
+	source,
+	DObject.getProperty("version"),
+);
+
+// La forme curifiée lit version dans l’étape du pipe.
+type _CheckPiped = DCommon.ExpectType<typeof piped, number, "strict">;

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

@@ -0,0 +1,43 @@
+/**
+ * @title DObject.hasKeys
+ *
+ * Vérifier la présence de propriétés définies et affiner leur caractère obligatoire.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const source: {
+	name?: string;
+	version?: number;
+};
+interface CompleteSource {
+	name: string;
+	version: number;
+}
+
+if (DObject.hasKeys(source, ["name", "version"])) {
+	type _CheckIfSource = DCommon.ExpectType<typeof source, CompleteSource, "strict">;
+	const name = source.name;
+	type _CheckIfName = DCommon.ExpectType<typeof name, string, "strict">;
+}
+
+const result = DObject.hasKeys(source, ["name", "version"]);
+
+// Le test retourne true lorsque les deux propriétés sont définies.
+type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;
+
+// La forme curifiée est passée directement comme predicate à DCommon.when.
+const name = DCommon.pipe(
+	source,
+	DCommon.when(
+		DObject.hasKeys(["name", "version"]),
+		(completeSource) => {
+			type _CheckPredicatedInput = DCommon.ExpectType<typeof completeSource, CompleteSource, "strict">;
+
+			return completeSource.name;
+		},
+	),
+);
+
+// La propriété name est une chaîne lorsque les deux clés sont présentes ; sinon source est conservé.
+type _CheckName = DCommon.ExpectType<typeof name, string | typeof source, "strict">;

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

@@ -0,0 +1,38 @@
+/**
+ * @title DObject.isSimple
+ *
+ * Vérifier si un objet est simple sans affiner son type.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+
+// La fonction reçoit un objet déjà identifié et indique s’il est simple.
+declare const input: { name: string } | Date;
+const result = DObject.isSimple(input);
+
+type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;
+
+// Le booléen ne réduit le type d’entrée dans aucune des deux branches.
+if (DObject.isSimple(input)) {
+	type _CheckInput = DCommon.ExpectType<typeof input, { name: string } | Date, "strict">;
+} else {
+	// Une instance de Date reste un objet même si elle n’est pas simple.
+	type _CheckInput = DCommon.ExpectType<typeof input, { name: string } | Date, "strict">;
+}
+
+// Depuis unknown, DObject.is identifie l’objet avant de vérifier s’il est simple.
+declare const externalInput: unknown;
+if (DObject.is(externalInput) && DObject.isSimple(externalInput)) {
+	const count = DObject.countKeys(externalInput);
+
+	type _CheckInput = DCommon.ExpectType<typeof externalInput, object, "strict">;
+	type _CheckCount = DCommon.ExpectType<typeof count, number, "strict">;
+}
+
+// La fonction unaire peut servir d’étape produisant un booléen dans un pipe.
+const isSimple = DCommon.pipe(
+	input,
+	DObject.isSimple,
+);
+// Le résultat indique si l’objet fourni est simple.
+type _CheckIsSimple = DCommon.ExpectType<typeof isSimple, boolean, "strict">;

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

@@ -0,0 +1,19 @@
+/**
+ * @title DObject.keys
+ *
+ * Lister les clés d’un objet avec un type correspondant à ses propriétés.
+ */
+import * as DObject from "@duplojs/lang/object";
+import type * as DCommon from "@duplojs/lang/common";
+
+const result = DObject.keys({
+	name: "Duplo",
+	version: 1,
+});
+
+// La valeur obtenue est ["name", "version"] et ses clés sont conservées dans le type.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	readonly ("name" | "version")[],
+	"strict"
+>;

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

@@ -0,0 +1,39 @@
+/**
+ * @title DObject.omit
+ *
+ * Créer un objet en retirant les propriétés sélectionnées.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+
+const source = {
+	name: "Duplo",
+	version: 1,
+	active: true,
+};
+const result = DObject.omit(source, ["version"]);
+
+// La valeur obtenue est { name: "Duplo", active: true }.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	{
+		name: string;
+		active: boolean;
+	},
+	"strict"
+>;
+
+const piped = DCommon.pipe(
+	source,
+	DObject.omit({ active: true }),
+);
+
+// Une sélection par objet de drapeaux est également utilisable dans un pipe.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	{
+		name: string;
+		version: number;
+	},
+	"strict"
+>;

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

@@ -0,0 +1,24 @@
+/**
+ * @title DObject.override
+ *
+ * Remplacer les propriétés définies d’un objet par de nouvelles valeurs.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+
+const source = {
+	name: "Duplo",
+	version: 1,
+};
+const result = DObject.override(source, { version: 2 });
+
+// La valeur obtenue est { name: "Duplo", version: 2 }.
+type _CheckResult = DCommon.ExpectType<typeof result, typeof source, "strict">;
+
+const piped = DCommon.pipe(
+	source,
+	DObject.override({ name: "AgentKit" }),
+);
+
+// La forme curifiée remplace seulement les propriétés définies dans la valeur d’override.
+type _CheckPiped = DCommon.ExpectType<typeof piped, typeof source, "strict">;