@duplojs/agents-kit 0.1.0-beta.3 → 0.1.0-beta.7

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

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