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

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,104 @@
+/**
+ * @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é.
+
+// string | number
+const matchedEntity = DPattern.matchWithEntity(
+	entity,
+	{
+		// User
+		User: (user) => user.name,
+
+		// Admin
+		Admin: (admin) => admin.permissions.length,
+	},
+);
+
+// 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.
+
+// string | number
+const matchedEntityInPipe = DCommon.pipe(
+	entity,
+	DPattern.matchWithEntity({
+		// User
+		User: (user) => user.name,
+
+		// Admin
+		Admin: (admin) => admin.permissions.length,
+	}),
+);
+
+// `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.
+
+// string | number
+const matchedEntityOtherwise = DPattern.matchWithEntityOtherwise(
+	entity,
+	{
+		// User
+		User: (user) => user.name,
+	},
+	// Admin
+	(admin) => admin.permissions.length,
+);
+
+// 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.
+
+// string | number
+const matchedEntityOtherwiseInPipe = DCommon.pipe(
+	entity,
+	DPattern.matchWithEntityOtherwise(
+		{
+			// User
+			User: (user) => user.name,
+		},
+		// Admin
+		(admin) => admin.permissions.length,
+	),
+);

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

@@ -0,0 +1,142 @@
+/**
+ * @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.
+
+// string | number
+const matchedFact = DPattern.matchWithFact(
+	user,
+	{
+		// UserCreated
+		UserCreated: (createdUser) => (
+			DModeling.factKind.getValue(createdUser).payload.name
+		),
+
+		// UserDeleted
+		UserDeleted: (deletedUser) => (
+			DModeling.factKind.getValue(deletedUser).payload.reason.length
+		),
+	},
+);
+
+// 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.
+
+// string | number
+const matchedFactInPipe = DCommon.pipe(
+	user,
+	DPattern.matchWithFact({
+		// UserCreated
+		UserCreated: (createdUser) => (
+			DModeling.factKind.getValue(createdUser).payload.name
+		),
+
+		// UserDeleted
+		UserDeleted: (deletedUser) => (
+			DModeling.factKind.getValue(deletedUser).payload.reason.length
+		),
+	}),
+);
+
+// `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.
+
+// string | UserDeleted
+const matchedFactOtherwise = DPattern.matchWithFactOtherwise(
+	user,
+	{
+		// UserCreated
+		UserCreated: (createdUser) => (
+			DModeling.factKind.getValue(createdUser).payload.name
+		),
+	},
+	// UserDeleted
+	(deletedUser) => (
+		deletedUser
+	),
+);
+
+// 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.
+
+// string | UserDeleted
+const matchedFactOtherwiseInPipe = DCommon.pipe(
+	user,
+	DPattern.matchWithFactOtherwise(
+		{
+			// UserCreated
+			UserCreated: (createdUser) => (
+				DModeling.factKind.getValue(createdUser).payload.name
+			),
+		},
+		// UserDeleted
+		(deletedUser) => (
+			deletedUser
+		),
+	),
+);

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

@@ -0,0 +1,105 @@
+/**
+ * @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é.
+
+// string
+const matchedNotification = DPattern.matchWithTaggedObject(
+	notification,
+	{
+		// EmailNotification
+		EmailNotification: (emailNotification) => emailNotification.email,
+
+		// SmsNotification
+		SmsNotification: (smsNotification) => smsNotification.phone,
+	},
+);
+
+// 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.
+
+// string
+const matchedNotificationInPipe = DCommon.pipe(
+	notification,
+	DPattern.matchWithTaggedObject({
+		// EmailNotification
+		EmailNotification: (emailNotification) => emailNotification.email,
+
+		// SmsNotification
+		SmsNotification: (smsNotification) => smsNotification.phone,
+	}),
+);
+
+// `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.
+
+// string
+const matchedNotificationOtherwise = DPattern.matchWithTaggedObjectOtherwise(
+	notification,
+	{
+		// EmailNotification
+		EmailNotification: (emailNotification) => emailNotification.email,
+	},
+	// SmsNotification
+	(smsNotification) => smsNotification.phone,
+);
+
+// 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`.
+
+// string
+const matchedNotificationOtherwiseInPipe = DCommon.pipe(
+	notification,
+	DPattern.matchWithTaggedObjectOtherwise(
+		{
+			// EmailNotification
+			EmailNotification: (emailNotification) => emailNotification.email,
+		},
+		// SmsNotification
+		(smsNotification) => smsNotification.phone,
+	),
+);

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

@@ -0,0 +1,57 @@
+/**
+ * @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.
+
+// string | Error
+const matchedError = DPattern.matchWithError(
+	error,
+	{
+		// InvalidInputError ; cause est undefined.
+		"invalid-input": (invalidInput) => invalidInput.message,
+
+		// UnavailableServiceError ; cause est Error.
+		"unavailable-service": (unavailableService) => unavailableService.cause,
+	},
+);
+
+// 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.
+
+// string | Error
+const matchedErrorOtherwise = DCommon.pipe(
+	error,
+	DPattern.matchWithErrorOtherwise(
+		{
+			// InvalidInputError
+			"invalid-input": (invalidInput) => invalidInput.message,
+		},
+		// UnavailableServiceError
+		(unavailableService) => unavailableService.cause,
+	),
+);
+
+// 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,87 @@
+/**
+ * @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.
+
+// "wait" | "run" | "error"
+const matchedStatus = DPattern.matchWithString(
+	status,
+	{
+		// "pending"
+		pending: () => "wait" as const,
+
+		// "ready"
+		ready: () => "run" as const,
+
+		// "failed"
+		failed: () => "error" as const,
+	},
+);
+
+// La forme curried peut être utilisée directement dans un pipe.
+
+// "wait" | "run" | "error"
+const matchedStatusInPipe = DCommon.pipe(
+	status,
+	DPattern.matchWithString({
+		pending: () => "wait" as const,
+		ready: () => "run" as const,
+		failed: () => "error" as const,
+	}),
+);
+
+// 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.
+
+// "run" | "not-ready"
+const matchedStatusOtherwise = DPattern.matchWithStringOtherwise(
+	status,
+	{
+		ready: () => "run" as const,
+	},
+	// "pending" | "failed"
+	() => "not-ready" as const,
+);
+
+declare const code: 200 | 404 | 500;
+
+// `matchWithNumber` applique le même principe aux unions de number literals.
+
+// "success" | "not-found" | "error"
+const matchedCode = DPattern.matchWithNumber(
+	code,
+	{
+		200: () => "success" as const,
+		404: () => "not-found" as const,
+		500: () => "error" as const,
+	},
+);
+
+// `matchWithNumberOtherwise` permet également une sélection partielle.
+
+// "success" | "error"
+const matchedCodeOtherwise = DPattern.matchWithNumberOtherwise(
+	code,
+	{
+		200: () => "success" as const,
+	},
+	// 404 | 500
+	() => "error" as const,
+);
+
+// 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.