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

package/docs/concepts/01-fundamental/07-discrimination/10-entity.ts

@@ -0,0 +1,136 @@
+/**
+ * @title Discrimination des entités par identité.
+ *
+ * Sélection exhaustive ou partielle selon le nom métier, avec typage précis des branches.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DModeling from "@duplojs/lang/modeling";
+import * as DPattern from "@duplojs/lang/pattern";
+
+// Une Entity porte une identité associée à son nom. Le matcher utilise cette identité,
+// sans devoir déduire le cas à partir de la forme de l’objet ou de ses propriétés.
+interface User extends DModeling.Entity<"User"> {
+	readonly id: string;
+	readonly name: string;
+}
+
+interface Admin extends DModeling.Entity<"Admin"> {
+	readonly id: string;
+	readonly permissions: readonly string[];
+}
+
+type Entity =
+	| User
+	| Admin;
+
+declare const entity: Entity;
+
+// `matchWithEntity` discrimine une union à partir du nom de chaque `Entity`.
+//
+// La sélection est exhaustive : chaque entité présente dans l'union
+// doit posséder un handler.
+//
+// Chaque callback reçoit directement le type précis correspondant
+// au nom de l'entité.
+
+const matchedEntity = DPattern.matchWithEntity(
+	entity,
+	{
+		User: (user) => {
+			type _CheckUser = DCommon.ExpectType<typeof user, User, "strict">;
+			return user.name;
+		},
+
+		Admin: (admin) => {
+			type _CheckAdmin = DCommon.ExpectType<typeof admin, Admin, "strict">;
+			return admin.permissions.length;
+		},
+	},
+);
+type _CheckMatchedEntityLine37 = DCommon.ExpectType<
+	typeof matchedEntity,
+	string | number,
+	"strict"
+>;
+
+// La sélection exhaustive crée un point d'ancrage dans le typage.
+//
+// Si une nouvelle `Entity` est ajoutée à l'union, le matcher devra
+// également définir son traitement.
+//
+// À l'inverse, une clé ne correspondant à aucune entité de l'union
+// ne peut pas être ajoutée au matcher.
+
+// `matchWithEntity` possède également une forme curried afin d'être
+// directement utilisée dans un pipe.
+
+const matchedEntityInPipe = DCommon.pipe(
+	entity,
+	DPattern.matchWithEntity({
+		User: (user) => {
+			type _CheckUser = DCommon.ExpectType<typeof user, User, "strict">;
+			return user.name;
+		},
+
+		Admin: (admin) => {
+			type _CheckAdmin = DCommon.ExpectType<typeof admin, Admin, "strict">;
+			return admin.permissions.length;
+		},
+	}),
+);
+type _CheckMatchedEntityInPipeLine60 = DCommon.ExpectType<
+	typeof matchedEntityInPipe,
+	string | number,
+	"strict"
+>;
+
+// `matchWithEntityOtherwise` permet de ne sélectionner explicitement
+// qu'une partie des entités.
+//
+// `otherwise` reçoit uniquement les entités qui n'ont pas déjà
+// été prises en charge par le matcher.
+
+const matchedEntityOtherwise = DPattern.matchWithEntityOtherwise(
+	entity,
+	{
+		User: (user) => {
+			type _CheckUser = DCommon.ExpectType<typeof user, User, "strict">;
+			return user.name;
+		},
+	},
+	(admin) => {
+		type _CheckAdmin = DCommon.ExpectType<typeof admin, Admin, "strict">;
+		return admin.permissions.length;
+	},
+);
+type _CheckMatchedEntityOtherwiseLine78 = DCommon.ExpectType<
+	typeof matchedEntityOtherwise,
+	string | number,
+	"strict"
+>;
+
+// La forme curried est également disponible.
+//
+// Le typage de `otherwise` évolue avec les handlers déjà déclarés.
+// Il représente toujours précisément le reste de l'union.
+
+const matchedEntityOtherwiseInPipe = DCommon.pipe(
+	entity,
+	DPattern.matchWithEntityOtherwise(
+		{
+			User: (user) => {
+				type _CheckUser = DCommon.ExpectType<typeof user, User, "strict">;
+				return user.name;
+			},
+		},
+		(admin) => {
+			type _CheckAdmin = DCommon.ExpectType<typeof admin, Admin, "strict">;
+			return admin.permissions.length;
+		},
+	),
+);
+type _CheckMatchedEntityOtherwiseInPipeLine94 = DCommon.ExpectType<
+	typeof matchedEntityOtherwiseInPipe,
+	string | number,
+	"strict"
+>;

package/docs/concepts/01-fundamental/07-discrimination/20-fact.ts

@@ -0,0 +1,158 @@
+/**
+ * @title Discrimination selon le fait courant.
+ *
+ * Choisir une branche selon la Fact portée par une valeur et accéder aux données du fait.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DModeling from "@duplojs/lang/modeling";
+import * as DPattern from "@duplojs/lang/pattern";
+
+// Une Fact appliquée à une entité y conserve son nom et sa payload.
+// La sélection porte sur ce fait courant, même lorsque toutes les variantes sont la même Entity.
+interface UserCreatedFact extends DModeling.Fact<
+	"UserCreated",
+	{
+		name: string;
+	}
+> {}
+
+interface UserDeletedFact extends DModeling.Fact<
+	"UserDeleted",
+	{
+		reason: string;
+	}
+> {}
+
+type UserCreated = (
+	& DModeling.Entity<"User">
+	& {
+		readonly id: string;
+	}
+	& UserCreatedFact
+);
+
+type UserDeleted = (
+	& DModeling.Entity<"User">
+	& {
+		readonly id: string;
+	}
+	& UserDeletedFact
+);
+
+type User =
+	| UserCreated
+	| UserDeleted;
+
+declare const user: User;
+
+// `matchWithFact` discrimine une union à partir du nom de la `Fact`
+// portée par chaque valeur.
+//
+// La sélection est exhaustive : chaque fact présente dans l'union
+// doit posséder un handler.
+//
+// Chaque callback reçoit directement la valeur avec la `Fact` précise
+// correspondant au nom sélectionné. La payload est accessible sur cette valeur avec factKind.
+// Cette lecture fonctionne dans les formes directe et curifiée.
+
+const matchedFact = DPattern.matchWithFact(
+	user,
+	{
+		UserCreated: (createdUser) => {
+			type _CheckCreatedUser = DCommon.ExpectType<typeof createdUser, UserCreated, "strict">;
+			return DModeling.factKind.getValue(createdUser).payload.name;
+		},
+
+		UserDeleted: (deletedUser) => {
+			type _CheckDeletedUser = DCommon.ExpectType<typeof deletedUser, UserDeleted, "strict">;
+			return DModeling.factKind.getValue(deletedUser).payload.reason.length;
+		},
+	},
+);
+type _CheckMatchedFactLine59 = DCommon.ExpectType<
+	typeof matchedFact,
+	string | number,
+	"strict"
+>;
+
+// La sélection exhaustive crée un point d'ancrage dans le typage.
+//
+// Si une nouvelle `Fact` est ajoutée à l'union, le matcher devra
+// également définir son traitement.
+//
+// À l'inverse, une clé ne correspondant à aucune fact de l'union
+// ne peut pas être ajoutée au matcher.
+
+// `matchWithFact` possède également une forme curried afin d'être
+// directement utilisée dans un pipe.
+
+const matchedFactInPipe = DCommon.pipe(
+	user,
+	DPattern.matchWithFact({
+		UserCreated: (createdUser) => {
+			type _CheckCreatedUser = DCommon.ExpectType<typeof createdUser, UserCreated, "strict">;
+			return DModeling.factKind.getValue(createdUser).payload.name;
+		},
+
+		UserDeleted: (deletedUser) => {
+			type _CheckDeletedUser = DCommon.ExpectType<typeof deletedUser, UserDeleted, "strict">;
+			return DModeling.factKind.getValue(deletedUser).payload.reason.length;
+		},
+	}),
+);
+type _CheckMatchedFactInPipeLine86 = DCommon.ExpectType<
+	typeof matchedFactInPipe,
+	string | number,
+	"strict"
+>;
+
+// `matchWithFactOtherwise` permet de ne sélectionner explicitement
+// qu'une partie des facts.
+//
+// `otherwise` reçoit uniquement les valeurs portant les facts
+// qui n'ont pas déjà été prises en charge par le matcher.
+
+const matchedFactOtherwise = DPattern.matchWithFactOtherwise(
+	user,
+	{
+		UserCreated: (createdUser) => {
+			type _CheckCreatedUser = DCommon.ExpectType<typeof createdUser, UserCreated, "strict">;
+			return DModeling.factKind.getValue(createdUser).payload.name;
+		},
+	},
+	(deletedUser) => {
+		type _CheckDeletedUser = DCommon.ExpectType<typeof deletedUser, UserDeleted, "strict">;
+		return deletedUser;
+	},
+);
+type _CheckMatchedFactOtherwiseLine108 = DCommon.ExpectType<
+	typeof matchedFactOtherwise,
+	string | UserDeleted,
+	"strict"
+>;
+
+// La forme curried est également disponible.
+//
+// Le typage de `otherwise` évolue avec les handlers déjà déclarés.
+// Il représente toujours précisément le reste de l'union de facts.
+
+const matchedFactOtherwiseInPipe = DCommon.pipe(
+	user,
+	DPattern.matchWithFactOtherwise(
+		{
+			UserCreated: (createdUser) => {
+				type _CheckCreatedUser = DCommon.ExpectType<typeof createdUser, UserCreated, "strict">;
+				return DModeling.factKind.getValue(createdUser).payload.name;
+			},
+		},
+		(deletedUser) => {
+			type _CheckDeletedUser = DCommon.ExpectType<typeof deletedUser, UserDeleted, "strict">;
+			return deletedUser;
+		},
+	),
+);
+type _CheckMatchedFactOtherwiseInPipeLine128 = DCommon.ExpectType<
+	typeof matchedFactOtherwiseInPipe,
+	string | UserDeleted,
+	"strict"
+>;

package/docs/concepts/01-fundamental/07-discrimination/30-tagged-object.ts

@@ -0,0 +1,137 @@
+/**
+ * @title Discrimination des objets par tag.
+ *
+ * Identifier la forme d’un objet par son tag et traiter tout ou partie de l’union.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DModeling from "@duplojs/lang/modeling";
+import * as DPattern from "@duplojs/lang/pattern";
+
+// Le tag fait partie de la donnée et identifie chaque TaggedObject.
+// Le matcher l’utilise pour distinguer les variantes indépendamment de leurs propriétés.
+interface EmailNotification extends DModeling.ObjectTag<"EmailNotification"> {
+	readonly email: string;
+	readonly subject: string;
+}
+
+interface SmsNotification extends DModeling.ObjectTag<"SmsNotification"> {
+	readonly phone: string;
+	readonly message: string;
+}
+
+type Notification =
+	| EmailNotification
+	| SmsNotification;
+
+declare const notification: Notification;
+
+// `matchWithTaggedObject` discrimine une union à partir du tag
+// porté par chaque `TaggedObject`.
+//
+// La sélection est exhaustive : chaque tag présent dans l'union
+// doit posséder un handler.
+//
+// Chaque callback reçoit directement le `TaggedObject` précis
+// correspondant au tag sélectionné.
+
+const matchedNotification = DPattern.matchWithTaggedObject(
+	notification,
+	{
+		EmailNotification: (emailNotification) => {
+			type _CheckEmailNotification = DCommon.ExpectType<typeof emailNotification, EmailNotification, "strict">;
+			return emailNotification.email;
+		},
+
+		SmsNotification: (smsNotification) => {
+			type _CheckSmsNotification = DCommon.ExpectType<typeof smsNotification, SmsNotification, "strict">;
+			return smsNotification.phone;
+		},
+	},
+);
+type _CheckMatchedNotificationLine38 = DCommon.ExpectType<
+	typeof matchedNotification,
+	string,
+	"strict"
+>;
+
+// La sélection exhaustive crée un point d'ancrage dans le typage.
+//
+// Si un nouveau `TaggedObject` est ajouté à l'union, le matcher devra
+// également définir son traitement.
+//
+// À l'inverse, une clé ne correspondant à aucun tag de l'union
+// ne peut pas être ajoutée au matcher.
+
+// `matchWithTaggedObject` possède également une forme curried afin d'être
+// directement utilisée dans un pipe.
+
+const matchedNotificationInPipe = DCommon.pipe(
+	notification,
+	DPattern.matchWithTaggedObject({
+		EmailNotification: (emailNotification) => {
+			type _CheckEmailNotification = DCommon.ExpectType<typeof emailNotification, EmailNotification, "strict">;
+			return emailNotification.email;
+		},
+
+		SmsNotification: (smsNotification) => {
+			type _CheckSmsNotification = DCommon.ExpectType<typeof smsNotification, SmsNotification, "strict">;
+			return smsNotification.phone;
+		},
+	}),
+);
+type _CheckMatchedNotificationInPipeLine61 = DCommon.ExpectType<
+	typeof matchedNotificationInPipe,
+	string,
+	"strict"
+>;
+
+// `matchWithTaggedObjectOtherwise` permet de ne sélectionner explicitement
+// qu'une partie des tags.
+//
+// `otherwise` reçoit uniquement les `TaggedObject` qui n'ont pas déjà
+// été pris en charge par le matcher.
+
+const matchedNotificationOtherwise = DPattern.matchWithTaggedObjectOtherwise(
+	notification,
+	{
+		EmailNotification: (emailNotification) => {
+			type _CheckEmailNotification = DCommon.ExpectType<typeof emailNotification, EmailNotification, "strict">;
+			return emailNotification.email;
+		},
+	},
+	(smsNotification) => {
+		type _CheckSmsNotification = DCommon.ExpectType<typeof smsNotification, SmsNotification, "strict">;
+		return smsNotification.phone;
+	},
+);
+type _CheckMatchedNotificationOtherwiseLine79 = DCommon.ExpectType<
+	typeof matchedNotificationOtherwise,
+	string,
+	"strict"
+>;
+
+// La forme curried est également disponible.
+//
+// Le typage de `otherwise` évolue avec les handlers déjà déclarés.
+// Il représente toujours précisément le reste de l'union de `TaggedObject`.
+
+const matchedNotificationOtherwiseInPipe = DCommon.pipe(
+	notification,
+	DPattern.matchWithTaggedObjectOtherwise(
+		{
+			EmailNotification: (emailNotification) => {
+				type _CheckEmailNotification = DCommon.ExpectType<typeof emailNotification, EmailNotification, "strict">;
+				return emailNotification.email;
+			},
+		},
+		(smsNotification) => {
+			type _CheckSmsNotification = DCommon.ExpectType<typeof smsNotification, SmsNotification, "strict">;
+			return smsNotification.phone;
+		},
+	),
+);
+type _CheckMatchedNotificationOtherwiseInPipeLine95 = DCommon.ExpectType<
+	typeof matchedNotificationOtherwiseInPipe,
+	string,
+	"strict"
+>;

package/docs/concepts/01-fundamental/07-discrimination/40-error.ts

@@ -0,0 +1,73 @@
+/**
+ * @title Discrimination des erreurs par identifiant.
+ *
+ * Sélection exhaustive ou partielle des erreurs DuploJS, avec typage précis des branches et des cas restants.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DPattern from "@duplojs/lang/pattern";
+
+// Le matcher sélectionne l'identifiant porté par le kind d'une DuploJSError.
+// Cet identifiant est fixé ici par parentClass ; il ne dépend ni du message
+// ni du nom de la classe.
+class InvalidInputError extends DCommon.DuploJSError.parentClass("invalid-input") {}
+class UnavailableServiceError extends DCommon.DuploJSError.parentClass("unavailable-service", Error) {}
+
+type OperationError =
+	| InvalidInputError
+	| UnavailableServiceError;
+
+declare const error: OperationError;
+
+// matchWithError exige un handler pour chaque identifiant de l'union
+// et refuse les clés étrangères à celle-ci. Ajouter une erreur au contrat
+// impose donc de compléter le matcher.
+// Chaque callback reçoit l'erreur précise, avec ses propriétés et sa cause typées.
+
+const matchedError = DPattern.matchWithError(
+	error,
+	{
+		"invalid-input": (invalidInput) => {
+			type _CheckInvalidInput = DCommon.ExpectType<typeof invalidInput, InvalidInputError, "strict">;
+			return invalidInput.message;
+		},
+
+		"unavailable-service": (unavailableService) => {
+			type _CheckUnavailableService = DCommon.ExpectType<typeof unavailableService, UnavailableServiceError, "strict">;
+			return unavailableService.cause;
+		},
+	},
+);
+type _CheckMatchedErrorLine27 = DCommon.ExpectType<
+	typeof matchedError,
+	string | Error,
+	"strict"
+>;
+
+// matchWithErrorOtherwise sélectionne explicitement une partie des identifiants.
+// Le callback otherwise reçoit uniquement les erreurs non prises en charge.
+// Les deux fonctions existent en forme directe et curried, utilisable dans un pipe.
+
+const matchedErrorOtherwise = DCommon.pipe(
+	error,
+	DPattern.matchWithErrorOtherwise(
+		{
+			"invalid-input": (invalidInput) => {
+				type _CheckInvalidInput = DCommon.ExpectType<typeof invalidInput, InvalidInputError, "strict">;
+				return invalidInput.message;
+			},
+		},
+		(unavailableService) => {
+			type _CheckUnavailableService = DCommon.ExpectType<typeof unavailableService, UnavailableServiceError, "strict">;
+			return unavailableService.cause;
+		},
+	),
+);
+type _CheckMatchedErrorOtherwiseLine43 = DCommon.ExpectType<
+	typeof matchedErrorOtherwise,
+	string | Error,
+	"strict"
+>;
+
+// Ces matchers attendent des DuploJSError dont les identifiants sont des types
+// littéraux connus. Conserver l'union précise : Error natif et DuploJSError
+// sans identifiant littéral ne fournissent pas ce contrat de discrimination.

package/docs/concepts/01-fundamental/07-discrimination/50-literal.ts

@@ -0,0 +1,106 @@
+/**
+ * @title Discrimination des valeurs littérales.
+ *
+ * Traitement exhaustif ou partiel d’une union selon la valeur, avec branches typées.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DPattern from "@duplojs/lang/pattern";
+
+// Pour une union de valeurs littérales, privilégier les matchers dédiés aux string ou number.
+// Ils sélectionnent directement la valeur et affinent le type reçu dans chaque branche.
+
+declare const status: "pending" | "ready" | "failed";
+
+// `matchWithString` discrimine exhaustivement une union de string literals.
+//
+// Chaque valeur possible doit posséder un handler et chaque callback reçoit
+// précisément le literal correspondant.
+
+const matchedStatus = DPattern.matchWithString(
+	status,
+	{
+		pending: () => "wait" as const,
+
+		ready: () => "run" as const,
+
+		failed: () => "error" as const,
+	},
+);
+type _CheckMatchedStatusLine20 = DCommon.ExpectType<
+	typeof matchedStatus,
+	"wait" | "run" | "error",
+	"strict"
+>;
+
+// La forme curried peut être utilisée directement dans un pipe.
+
+const matchedStatusInPipe = DCommon.pipe(
+	status,
+	DPattern.matchWithString({
+		pending: () => "wait" as const,
+		ready: () => "run" as const,
+		failed: () => "error" as const,
+	}),
+);
+type _CheckMatchedStatusInPipeLine37 = DCommon.ExpectType<
+	typeof matchedStatusInPipe,
+	"wait" | "run" | "error",
+	"strict"
+>;
+
+// La variante `otherwise` permet de ne sélectionner qu'une partie de l'union.
+//
+// Le callback `otherwise` reçoit précisément les literals non traités.
+
+const matchedStatusOtherwise = DPattern.matchWithStringOtherwise(
+	status,
+	{
+		ready: () => "run" as const,
+	},
+	(otherStatus) => {
+		type _CheckOtherwiseStatus = DCommon.ExpectType<typeof otherStatus, "pending" | "failed", "strict">;
+		return "not-ready" as const;
+	},
+);
+type _CheckMatchedStatusOtherwiseLine51 = DCommon.ExpectType<
+	typeof matchedStatusOtherwise,
+	"run" | "not-ready",
+	"strict"
+>;
+
+declare const code: 200 | 404 | 500;
+
+// `matchWithNumber` applique le même principe aux unions de number literals.
+
+const matchedCode = DPattern.matchWithNumber(
+	code,
+	{
+		200: () => "success" as const,
+		404: () => "not-found" as const,
+		500: () => "error" as const,
+	},
+);
+type _CheckMatchedCodeLine65 = DCommon.ExpectType<
+	typeof matchedCode,
+	"success" | "not-found" | "error",
+	"strict"
+>;
+
+// `matchWithNumberOtherwise` permet également une sélection partielle.
+
+const matchedCodeOtherwise = DPattern.matchWithNumberOtherwise(
+	code,
+	{
+		200: () => "success" as const,
+	},
+	// 404 | 500
+	() => "error" as const,
+);
+type _CheckMatchedCodeOtherwiseLine77 = DCommon.ExpectType<
+	typeof matchedCodeOtherwise,
+	"success" | "error",
+	"strict"
+>;
+
+// Un matcher exhaustif doit couvrir chaque valeur possible et refuse les clés étrangères à l’union.
+// Ajouter une valeur au contrat impose de réviser les branches, contrairement à une sélection partielle.