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

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

@@ -0,0 +1,102 @@
+/**
+ * @title DObject.discriminate
+ *
+ * Tester une propriété avec un predicate et affiner l’objet par intersection.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+import * as DNumber from "@duplojs/lang/number";
+
+// Le predicate reçoit la valeur de la propriété. S’il affine cette valeur,
+// l’objet conserve son type initial en intersection avec la propriété affinée.
+declare const input: {
+	value: string | number;
+	id: number;
+};
+
+// Appel classique : affiner une propriété, même sans union d’objets.
+if (DObject.discriminate(input, "value", DCommon.isType("string"))) {
+	type _CheckInput = DCommon.ExpectType<
+		typeof input,
+		{
+			value: string | number;
+			id: number;
+		} & { value: string },
+		"strict"
+	>;
+	const value = input.value;
+
+	type _CheckValue = DCommon.ExpectType<typeof value, string, "strict">;
+}
+
+// Appel curifié : lire la chaîne si elle est présente, sinon conserver l’objet.
+const result = DCommon.pipe(
+	input,
+	DCommon.when(
+		DObject.discriminate("value", DCommon.isType("string")),
+		(value) => {
+			type _CheckValue = DCommon.ExpectType<
+				typeof value,
+				{
+					value: string | number;
+					id: number;
+				} & { value: string },
+				"strict"
+			>;
+
+			return value.value;
+		},
+	),
+);
+
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	string | {
+		value: string | number;
+		id: number;
+	},
+	"strict"
+>;
+
+// Les contraintes établies par le predicate sont portées par la propriété.
+declare const person: {
+	age: number;
+	name: string;
+};
+
+if (DObject.discriminate(person, "age", DNumber.greaterThan(18))) {
+	type _CheckPerson = DCommon.ExpectType<
+		typeof person,
+		{
+			age: number;
+			name: string;
+		} & { age: number & DNumber.GreaterThan<18> },
+		"strict"
+	>;
+}
+
+// Composer les predicates pour une propriété imbriquée.
+// DCommon.equal permet de conserver une vérification d’égalité.
+declare const account: {
+	profile: { role: string };
+	id: number;
+};
+
+if (DObject.discriminate(account, "profile", DObject.discriminate("role", DCommon.equal("admin")))) {
+	type _CheckAccount = DCommon.ExpectType<
+		typeof account,
+		{
+			profile: { role: string };
+			id: number;
+		} & { profile: { role: string } & { role: "admin" } },
+		"strict"
+	>;
+}
+
+// Un predicate booléen reste accepté, sans affiner l’objet.
+declare const threshold: number;
+
+const isAboveThreshold = DObject.discriminate(person, "age", DNumber.greaterThan(threshold));
+
+// true uniquement si l’âge dépasse le seuil fourni à l’exécution.
+type _CheckIsAboveThreshold = DCommon.ExpectType<typeof isAboveThreshold, boolean, "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">;

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

@@ -0,0 +1,41 @@
+/**
+ * @title DObject.pick
+ *
+ * Créer un objet avec 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.pick(source, ["name", "active"]);
+
+// 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.pick({
+		name: true,
+		version: false,
+	}),
+);
+
+// Une sélection par objet de drapeaux conserve seulement name.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	{
+		name: string;
+	},
+	"strict"
+>;

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

@@ -0,0 +1,40 @@
+/**
+ * @title DObject.to
+ *
+ * Construire un nouvel objet en appliquant une forme de transformations à une même entrée.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+import type * as DNumber from "@duplojs/lang/number";
+import * as DString from "@duplojs/lang/string";
+
+const result = DObject.to("Duplo", {
+	upper: DString.toUpperCase,
+	length: DString.length,
+});
+
+// La valeur obtenue est { upper: "DUPLO", length: 5 }.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	{
+		upper: Uppercase<string>;
+		length: number & DNumber.Positive;
+	},
+	"strict"
+>;
+
+const piped = DCommon.pipe(
+	"AgentKit",
+	DObject.to({
+		upper: DString.toUpperCase,
+	}),
+);
+
+// La forme curifiée applique la forme au texte reçu par le pipe.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	{
+		upper: "AGENTKIT";
+	},
+	"strict"
+>;

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

@@ -0,0 +1,43 @@
+/**
+ * @title DObject.transformProperties
+ *
+ * Transformer plusieurs propriétés d’un objet en conservant les autres.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+const source = {
+	name: "duplo",
+	version: 1,
+};
+const result = DObject.transformProperties(source, {
+	name: DString.toUpperCase,
+});
+
+// La valeur obtenue est { name: "DUPLO", version: 1 }.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	{
+		name: Uppercase<string>;
+		version: number;
+	},
+	"strict"
+>;
+
+const piped = DCommon.pipe(
+	source,
+	DObject.transformProperties({
+		name: DString.toUpperCase,
+	}),
+);
+
+// La forme curifiée place la description des transformations dans l’étape du pipe.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	{
+		name: Uppercase<string>;
+		version: number;
+	},
+	"strict"
+>;

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

@@ -0,0 +1,39 @@
+/**
+ * @title DObject.transformProperty
+ *
+ * Transformer une propriété précise d’un objet.
+ */
+import * as DObject from "@duplojs/lang/object";
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+const source = {
+	name: "duplo",
+	version: 1,
+};
+const result = DObject.transformProperty(source, "name", DString.toUpperCase);
+
+// La valeur obtenue est { name: "DUPLO", version: 1 }.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	{
+		name: Uppercase<string>;
+		version: number;
+	},
+	"strict"
+>;
+
+const piped = DCommon.pipe(
+	source,
+	DObject.transformProperty("name", DString.toUpperCase),
+);
+
+// La forme curifiée ne remplace que la propriété ciblée.
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	{
+		name: Uppercase<string>;
+		version: number;
+	},
+	"strict"
+>;

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

@@ -0,0 +1,19 @@
+/**
+ * @title DObject.values
+ *
+ * Extraire les valeurs d’un objet avec l’union des types de ses propriétés.
+ */
+import * as DObject from "@duplojs/lang/object";
+import type * as DCommon from "@duplojs/lang/common";
+
+const result = DObject.values({
+	name: "Duplo",
+	version: 1,
+});
+
+// La valeur obtenue est ["Duplo", 1] et son type contient string | number.
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	readonly (string | number)[],
+	"strict"
+>;