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

package/docs/concepts/01-fundamental/06-modeling/50-evidence.ts

@@ -0,0 +1,94 @@
+/**
+ * @title Preuves de passage par une opération.
+ *
+ * Exiger dans les types qu’une valeur soit passée par un traitement préalable.
+ */
+import * as DModeling from "@duplojs/lang/modeling";
+import * as DInvocation from "@duplojs/lang/invocation";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DCommon from "@duplojs/lang/common";
+import * as DEither from "@duplojs/lang/either";
+
+// Certaines règles portent sur le parcours d’une valeur plutôt que sur sa seule forme.
+const Id = DModeling.createNewType(
+	"Id",
+	DDataStructure.string(),
+	[DDataStructure.uuid()],
+);
+type Id = DDataStructure.StructureValue<typeof Id>;
+
+interface Entity {
+	id: Id;
+}
+
+interface IdGenerator {
+	// Evidence représente uniquement dans le typage la preuve produite par une opération.
+	// Le résultat ne porte pas seulement un Id, mais aussi la preuve "generated".
+	generateId(): Id & DInvocation.Evidence<"generated">;
+}
+
+const implementation: IdGenerator = {
+	generateId: () => DCommon.pipe(
+		"550e8400-e29b-41d4-a716-446655440000",
+		Id.map,
+		DEither.unwrapRightOrThrow,
+
+		// appendEvidence restitue la même valeur, sans propriété ni contrôle runtime.
+		// L'implémentation doit donc avoir établi la garantie avant d'ajouter la preuve.
+		// Cela fonctionne aussi avec les valeurs primitives.
+		DInvocation.appendEvidence("generated"),
+	),
+};
+
+// GetEvidenceResult extrait du retour d'une méthode la valeur portant l'évidence demandée.
+// createEntity exige ainsi l'Id avec la preuve "generated" du contrat de generateId.
+// Deux méthodes annonçant la même valeur et la même évidence restent compatibles :
+// pour distinguer leurs provenances, utiliser des noms d'évidence distincts.
+declare function createEntity(
+	params: {
+		id: DInvocation.GetEvidenceResult<IdGenerator["generateId"], "generated">;
+	},
+): Entity;
+
+// La relation entre génération et création est exprimée dans la signature.
+createEntity({ id: implementation.generateId() });
+
+declare const idWithoutEvidence: Id;
+// @ts-expect-error Un Id seul ne prouve pas le passage par la génération attendue.
+createEntity({ id: idWithoutEvidence });
+
+// Quand l'opération possède plusieurs issues, EvidenceResult associe chaque information
+// à une valeur portant l'évidence du même nom. Comme appendEvidence, cette construction
+// ne réalise pas la vérification : checkId doit réellement consulter le registre.
+interface Registry {
+	checkId(id: Id): Promise<
+		| DInvocation.EvidenceResult<"id-available", Id>
+		| DInvocation.EvidenceResult<"id-already-registered", Id>
+	>;
+}
+
+// GetEvidenceResult sélectionne ici une seule issue, même à travers la promesse et l'Either.
+type AvailableId = DInvocation.GetEvidenceResult<Registry["checkId"], "id-available">;
+type _CheckAvailableId = DCommon.ExpectType<AvailableId, Id & DInvocation.Evidence<"id-available">, "strict">;
+
+declare function createRegisteredEntity(id: AvailableId): Entity;
+
+// La couche appelante discrimine le résultat pour obtenir cette preuve.
+// La disponibilité autorise la création ; l'autre issue devient un Left,
+// propagé par rightAsyncPipe sans appeler createRegisteredEntity.
+function registerEntity(registry: Registry, id: Id) {
+	return DEither.rightAsyncPipe(
+		DCommon.asyncPipe(
+			registry.checkId(id),
+			DEither.keepAsRightByInformation("id-available"),
+		),
+		createRegisteredEntity,
+	);
+}
+
+declare const alreadyRegisteredId: DInvocation.GetEvidenceResult<Registry["checkId"], "id-already-registered">;
+// @ts-expect-error Le résultat d'une autre branche ne prouve pas la disponibilité.
+createRegisteredEntity(alreadyRegisteredId);
+
+// @ts-expect-error La méthode ne produit pas d'évidence nommée generated.
+type UnsupportedEvidence = DInvocation.GetEvidenceResult<Registry["checkId"], "generated">;

package/docs/concepts/01-fundamental/06-modeling/60-signed-function.ts

@@ -0,0 +1,26 @@
+/**
+ * @title Identité des fonctions dans les dépendances.
+ *
+ * Exiger une fonction identifiée au-delà de sa seule signature TypeScript.
+ */
+import * as DInvocation from "@duplojs/lang/invocation";
+
+interface ActionService {
+	// Deux fonctions () => void ne sont pas nécessairement interchangeables dans le modèle.
+	// SignedFunction ajoute à cette signature l’identité de l’opération attendue.
+	someAction: DInvocation.SignedFunction<"someAction", () => void>;
+}
+
+const implementation: ActionService = {
+	// signedFunction associe l’identité à l’implémentation.
+	// Cette information existe au runtime sur la fonction, contrairement à une Evidence.
+	someAction: DInvocation.signedFunction("someAction", () => void 0),
+};
+
+// La dépendance exige précisément l’opération identifiée comme someAction.
+declare function otherFunction(someFunction: ActionService["someAction"]): void;
+
+otherFunction(implementation.someAction);
+
+// @ts-expect-error Une même signature d’appel ne suffit pas sans l’identité attendue.
+otherFunction(() => void 0);

package/docs/concepts/01-fundamental/06-modeling/index.md

@@ -0,0 +1,3 @@
+## Modélisation
+
+Identités métier, modèles de données, états et transitions, preuves de passage et identité des opérations dans les contrats.

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.