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

package/docs/concepts/01-fundamental/06-modeling/30-tagged-object.ts

@@ -0,0 +1,204 @@
+/**
+ * @title Objets taggés et unions discriminées.
+ *
+ * Identité transportable, distinction des formes d’un objet et hydratation des données brutes.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DModeling from "@duplojs/lang/modeling";
+import * as DPattern from "@duplojs/lang/pattern";
+import * as DEither from "@duplojs/lang/either";
+
+// Sans `TaggedObject`, une union discriminée serait généralement construite
+// en ajoutant soi-même une propriété comme `type` ou `kind`.
+//
+// `createTaggedObject` normalise cette identité.
+// Le code métier n'a pas à choisir ni à manipuler la clé utilisée pour
+// enregistrer le tag.
+//
+const EmailNotification = DModeling.createTaggedObject(
+	"EmailNotification",
+	{
+		email: DDataStructure.string(),
+		subject: DDataStructure.string(),
+	},
+);
+type EmailNotification = DDataStructure.StructureValue<typeof EmailNotification>;
+type _CheckEmailNotification = DCommon.ExpectType<
+	EmailNotification,
+	DModeling.ObjectTag<"EmailNotification"> & {
+		readonly email: string;
+		readonly subject: string;
+	},
+	"strict"
+>;
+
+// Les propriétés peuvent être définies directement avec des `DataStructure`.
+//
+// Contrairement à une `Entity`, un `TaggedObject` n'impose pas que ses
+// propriétés soient des `NewType`.
+//
+const SmsNotification = DModeling.createTaggedObject(
+	"SmsNotification",
+	{
+		phone: DDataStructure.string(),
+		message: DDataStructure.string(),
+		attempts: DDataStructure.number(),
+	},
+);
+type SmsNotification = DDataStructure.StructureValue<typeof SmsNotification>;
+type _CheckSmsNotification = DCommon.ExpectType<SmsNotification, DModeling.ObjectTag<"SmsNotification"> & {
+	readonly phone: string;
+	readonly message: string;
+	readonly attempts: number;
+}, "strict">;
+
+// Plusieurs `TaggedObject` peuvent former une union discriminée.
+//
+// Leur identité permet de retrouver précisément la forme correspondante
+// sans ajouter manuellement une propriété discriminante au modèle.
+type Notification =
+	| EmailNotification
+	| SmsNotification;
+
+declare const notification: Notification;
+
+// `matchWithTaggedObject` discrimine directement l'union à partir du tag.
+//
+// Chaque callback reçoit la forme exacte associée à son identité.
+const destination = DPattern.matchWithTaggedObject(
+	notification,
+	{
+		EmailNotification: (emailNotification) => emailNotification.email,
+		SmsNotification: (smsNotification) => smsNotification.phone,
+	},
+);
+type _CheckDestination = DCommon.ExpectType<typeof destination, string, "strict">;
+
+// L'identité peut également être récupérée directement.
+//
+const notificationType = DModeling.getTagValue(notification);
+type _CheckNotificationType = DCommon.ExpectType<
+	typeof notificationType,
+	"EmailNotification" | "SmsNotification",
+	"strict"
+>;
+
+// `hasTagValue` permet de tester une identité et affine simultanément
+// le type de la valeur.
+//
+// Dans cette branche, `notification` est précisément un `EmailNotification`.
+if (DModeling.hasTagValue(notification, "EmailNotification")) {
+	type _CheckEmailBranch = DCommon.ExpectType<typeof notification, EmailNotification, "strict">;
+	const subject = notification.subject;
+	type _CheckSubject = DCommon.ExpectType<typeof subject, string, "strict">;
+}
+
+// `new` est utilisé lorsque les propriétés possèdent déjà le typage attendu.
+//
+// Il construit le `TaggedObject` et lui associe son identité.
+//
+const emailNotification = EmailNotification.new({
+	email: "user@example.com",
+	subject: "Account created",
+});
+type _CheckEmailNotificationValue = DCommon.ExpectType<typeof emailNotification, EmailNotification, "strict">;
+
+// L'identité fait partie de la structure du `TaggedObject`.
+//
+// Les opérations génériques comme `check`, `is`, `encode` ou `decode`
+// travaillent donc avec une valeur qui possède déjà cette identité.
+//
+// Une donnée brute provenant d'une base de données, d'une API externe
+// ou d'un autre système ne la possède généralement pas encore.
+declare const externalEmailNotification: {
+	email: string;
+	subject: string;
+};
+
+// `map` sert à hydrater cette donnée lorsqu'elle entre dans le domaine.
+//
+// Le mapping ajoute l'identité du `TaggedObject`, vérifie sa structure
+// et ses contraintes, puis retourne la valeur correctement typée.
+//
+// Le type demandé en entrée est volontairement moins précis que le type
+// métier final afin de représenter les données provenant de systèmes externes.
+//
+// L'hydratation peut échouer, son résultat est donc représenté par un `Either`.
+
+const maybeEmailNotification = EmailNotification.map(
+	externalEmailNotification,
+);
+type _CheckMaybeEmailNotificationLine121 = DCommon.ExpectType<
+	typeof maybeEmailNotification,
+	DEither.Left<"async-error", DDataStructure.ErrorPromise>
+| DEither.Left<"map-error", DDataStructure.Error>
+| DEither.Right<"map-success", EmailNotification>,
+	"strict"
+>;
+
+// Une fois hydraté, le tag fait partie de la donnée.
+//
+// Si ce `TaggedObject` est ensuite sérialisé et transporté vers un autre
+// consommateur, son identité est conservée.
+// Il n'a donc pas besoin d'être hydraté une seconde fois simplement
+// parce qu'il traverse une frontière entre deux services.
+//
+const mappedEmailNotification = DCommon.pipe(
+	EmailNotification.map({
+		email: "user@example.com",
+		subject: "Account created",
+	}),
+	DEither.unwrapRight,
+);
+type _CheckMappedEmailNotification = DCommon.ExpectType<
+	typeof mappedEmailNotification,
+	DEither.Left<"async-error", DDataStructure.ErrorPromise>
+		| DEither.Left<"map-error", DDataStructure.Error>
+		| DModeling.ObjectTag<"EmailNotification"> & {
+			readonly email: string;
+			readonly subject: string;
+		},
+	"strict"
+>;
+
+// `decodeMap` suit le même principe que `map`, mais commence par décoder
+// la représentation externe avec les codecs fournis.
+//
+// Ici, `attempts` provient par exemple d'une représentation string avant
+// de retrouver son type métier `number`.
+
+const maybeSmsNotification = SmsNotification.decodeMap(
+	DDataStructure.codecsString,
+	{
+		phone: "+33600000000",
+		message: "Account created",
+		attempts: DCommon.cast("1"),
+	},
+);
+type _CheckMaybeSmsNotificationLine155 = DCommon.ExpectType<
+	typeof maybeSmsNotification,
+	DEither.Left<"async-error", DDataStructure.ErrorPromise>
+| DEither.Left<"map-error", DDataStructure.Error>
+| DEither.Right<"map-success", SmsNotification>,
+	"strict"
+>;
+
+// `update` reconstruit un `TaggedObject` possédant la même identité
+// en remplaçant uniquement les propriétés fournies.
+//
+// Comme pour les autres structures de modeling, `undefined` ne remplace
+// pas une propriété déjà présente.
+const updatedSmsNotification = SmsNotification.update(
+	SmsNotification.new({
+		phone: "+33600000000",
+		message: "Account created",
+		attempts: 1,
+	}),
+	{
+		attempts: 2,
+	},
+);
+
+// Les variantes `asyncMap` et `asyncDecodeMap` permettent la même
+// hydratation lorsqu'une structure contient des traitements asynchrones.

package/docs/concepts/01-fundamental/06-modeling/40-entity-lifecycle.ts

@@ -0,0 +1,272 @@
+/**
+ * @title Cycle de vie des entités.
+ *
+ * États, préconditions et transitions métier représentés par des Flag et des Fact.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DModeling from "@duplojs/lang/modeling";
+import * as DChrono from "@duplojs/lang/chrono";
+import * as DPattern from "@duplojs/lang/pattern";
+import * as DEither from "@duplojs/lang/either";
+
+// Le modèle et les signatures expriment les états possibles, leurs preuves et les événements
+// qui font évoluer l’entité. Les préconditions deviennent des exigences de typage.
+export namespace User {
+	const namespace = DModeling.createEntityNamespace("User");
+
+	export const Id = namespace.createNewType(
+		"Id",
+		DDataStructure.string(),
+		[DDataStructure.uuid()],
+	);
+	export type Id = DDataStructure.StructureValue<typeof Id>;
+
+	export const Age = namespace.createNewType(
+		"Age",
+		DDataStructure.number(),
+		[
+			DDataStructure.integer(),
+			DDataStructure.positive(),
+		],
+	);
+	export type Age = DDataStructure.StructureValue<typeof Age>;
+
+	export const Name = namespace.createNewType(
+		"Name",
+		DDataStructure.string(),
+		[
+			DDataStructure.trimmed(),
+			DDataStructure.minCharacters(3),
+			DDataStructure.maxCharacters(45),
+		],
+	);
+	export type Name = DDataStructure.StructureValue<typeof Name>;
+
+	// Les `TaggedObject` décrivent les propriétés propres à chaque état.
+	// Leur tag permet de discriminer ces formes ; leur fonctionnement est détaillé
+	// dans le concept consacré aux objets taggés.
+	export const AwaitingValidationState = DModeling.createTaggedObject(
+		"AwaitingValidationState",
+		{
+			sendValidationAt: DDataStructure.date(),
+		},
+	);
+	export type AwaitingValidationState = DDataStructure.StructureValue<typeof AwaitingValidationState>;
+
+	export const Address = namespace.createNewType("Address", DDataStructure.string());
+	export type Address = DDataStructure.StructureValue<typeof Address>;
+
+	export const ValidateState = DModeling.createTaggedObject(
+		"ValidateState",
+		{
+			address: Address,
+			validateAt: DDataStructure.date(),
+		},
+	);
+	export type ValidateState = DDataStructure.StructureValue<typeof ValidateState>;
+
+	// La shape de l'entité reste fixe pendant son cycle de vie.
+	// Les propriétés dont la forme varie sont modélisées par des unions : ici,
+	// `state` contient soit `AwaitingValidationState`, soit `ValidateState`.
+	export const Entity = namespace.createEntity(
+		() => ({
+			id: Id,
+			age: Age,
+			name: Name,
+			state: DDataStructure.union([
+				AwaitingValidationState,
+				ValidateState,
+			]),
+		}),
+	);
+	export type Entity = DDataStructure.StructureValue<typeof Entity>;
+
+	// Un `Flag` certifie une condition sur l'entité actuelle : état, capacité ou relation.
+	// Plusieurs flags compatibles peuvent coexister, indépendamment des variantes de `state`.
+	// Ici, chacun porte au runtime la payload de l'état qu'il certifie.
+	// Une fonction exigeant `User.Entity & User.AwaitingValidationFlag` reçoit ainsi
+	// une entité dont l'état d'attente est prouvé, avec son `AwaitingValidationState`.
+	// Déclarer d'abord la factory avec le nom, la payload et la structure d'entité,
+	// puis en dériver le type avec `GetFlag`.
+	export const AwaitingValidationFlag = DModeling.createFlag<
+		"AwaitingValidation",
+		AwaitingValidationState,
+		typeof Entity
+	>("AwaitingValidation");
+	export type AwaitingValidationFlag = DModeling.GetFlag<typeof AwaitingValidationFlag>;
+
+	export const ValidateFlag = DModeling.createFlag<
+		"Validate",
+		ValidateState,
+		typeof Entity
+	>("Validate");
+	export type ValidateFlag = DModeling.GetFlag<typeof ValidateFlag>;
+
+	// Après hydratation, `state` reste typé comme l'union des états possibles.
+	// `refineState` inspecte sa valeur et ajoute le flag correspondant sans modifier
+	// les propriétés métier. Chaque branche retourne un Result : elle constate l'état,
+	// sans décider si celui-ci autorise l'opération envisagée par l'appelant.
+	export function refineState<
+		GenericEntity extends Entity,
+	>(entity: GenericEntity) {
+		return DPattern.matchWithTaggedObject(
+			entity.state,
+			{
+				AwaitingValidationState: (state) => DEither.result(
+					"AwaitingValidation",
+					AwaitingValidationFlag.append(entity, state),
+				),
+				ValidateState: (state) => DEither.result(
+					"Validate",
+					ValidateFlag.append(entity, state),
+				),
+			},
+		);
+	}
+}
+
+// Une `Fact` représente une création ou une modification métier de l'entité,
+// y compris un changement de propriété qui conserve le même état nommé.
+// Sa payload décrit l'événement et reste portée par l'entité après application du fait.
+// Ici, la création place toujours l'utilisateur en attente de validation.
+// `createFact` reçoit les mêmes trois génériques que `createFlag`, puis construit `run`
+// dans un second appel. `GetFact` extrait le type du fait depuis cette factory.
+export const UserCreateFact = DModeling.createFact<
+	"UserCreated",
+	{
+		id: User.Id;
+		age: User.Age;
+		name: User.Name;
+		state: User.AwaitingValidationState;
+	},
+	typeof User.Entity
+>("UserCreated")(
+	({ applyFact }) => (
+		params: {
+			id: User.Id;
+			age: User.Age;
+			name: User.Name;
+		},
+	) => {
+		// La payload décrit complètement le fait qui vient de se produire.
+		//
+		// Elle contient notamment l'état produit par cette étape du cycle de vie,
+		// ce qui permet de conserver cette information avec la `Fact`.
+		const payload = {
+			id: params.id,
+			age: params.age,
+			name: params.name,
+			state: User.AwaitingValidationState.new({
+				sendValidationAt: DChrono.now(),
+			}),
+		};
+
+		// La création exprime plusieurs propriétés métier en une seule opération :
+		//
+		// - l'entité est créée avec `AwaitingValidationState` ;
+		// - le `AwaitingValidationFlag` prouve immédiatement cet état ;
+		// - `UserCreated` est apposée comme fait courant sur l'entité.
+		return DCommon.pipe(
+			payload,
+			User.Entity.new,
+			User.AwaitingValidationFlag.append(payload.state),
+			applyFact(payload),
+		);
+	},
+);
+
+export type UserCreateFact = DModeling.GetFact<typeof UserCreateFact>;
+
+// Cette `Fact` représente la transition entre l'attente de validation
+// et l'état validé.
+//
+// Sa signature fait elle-même partie de la règle métier :
+// seules les entités possédant `AwaitingValidationFlag` peuvent effectuer
+// cette transition.
+export const ValidateUserFact = DModeling.createFact<
+	"ValidateUserFact",
+	{
+		state: User.ValidateState;
+	},
+	typeof User.Entity
+>("ValidateUserFact")(
+	({ applyFact }) => (
+		user: User.Entity & User.AwaitingValidationFlag,
+		params: {
+			address: User.Address;
+		},
+	) => {
+		// Le nouvel état appartient à la payload du fait.
+		//
+		// Le fait `ValidateUserFact` conserve donc également les informations
+		// produites lors de cette transition.
+		const payload = {
+			state: User.ValidateState.new({
+				address: params.address,
+				validateAt: DChrono.now(),
+			}),
+		};
+
+		// `Entity.update` reconstruit l'entité à partir de sa shape déclarée.
+		//
+		// Les anciens `Flag` et la précédente `Fact` ne sont donc pas conservés.
+		// La transition repart de l'entité dans son nouvel état, puis :
+		//
+		// - ajoute `ValidateFlag` pour prouver ce nouvel état ;
+		// - applique `ValidateUserFact` comme nouveau fait courant.
+		return DCommon.pipe(
+			user,
+			User.Entity.update({ state: payload.state }),
+			User.ValidateFlag.append(payload.state),
+			applyFact(payload),
+		);
+	},
+);
+
+export type ValidateUserFact = DModeling.GetFact<typeof ValidateUserFact>;
+
+declare const id: User.Id;
+declare const age: User.Age;
+declare const name: User.Name;
+
+const createdUser = DCommon.pipe(
+	UserCreateFact.run({
+		id,
+		age,
+		name,
+	}),
+	DEither.unwrapRight,
+);
+type _CheckCreatedUser = DCommon.ExpectType<
+	typeof createdUser.state,
+	User.AwaitingValidationState,
+	"strict"
+>;
+
+declare const address: User.Address;
+
+// Le type de `createdUser` prouve qu'il possède
+// `AwaitingValidationFlag`.
+//
+// Cette preuve satisfait directement la précondition de `ValidateUserFact`.
+// Aucun contrôle supplémentaire de l'état n'est nécessaire ici.
+
+// Après la transition :
+// - `state` est précisément `ValidateState` ;
+// - `AwaitingValidationFlag` a disparu ;
+// - `ValidateFlag` prouve le nouvel état ;
+// - `UserCreated` a été remplacée par `ValidateUserFact`.
+//
+const validateUser = DCommon.pipe(
+	ValidateUserFact.run(
+		createdUser,
+		{ address },
+	),
+	DEither.unwrapRight,
+);
+type _CheckValidatedUser = DCommon.ExpectType<
+	typeof validateUser.state,
+	User.ValidateState,
+	"strict"
+>;

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.