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

package/docs/concepts/01-fundamental/07-discrimination/60-shape.ts

@@ -0,0 +1,160 @@
+/**
+ * @title Discrimination par la forme des données.
+ *
+ * Sélectionner les variantes sans identité explicite par des patterns, y compris imbriqués.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DPattern from "@duplojs/lang/pattern";
+
+// `match` est utile lorsque la donnée ne possède pas de discriminant propre.
+//
+// Ce type de structure est généralement à éviter dans le domaine,
+// mais peut être imposé par une API, une base de données ou un système externe.
+//
+// Ici, aucune propriété commune ne permet d'identifier directement le cas.
+// La discrimination doit donc être réalisée à partir de la shape de l'objet.
+
+type ExternalProduct =
+	| {
+		id: string;
+		price: number;
+		merchant: {
+			id: string;
+			name: string;
+		};
+	}
+	| {
+		id: string;
+		price: number;
+		secondHand: {
+			condition: "good" | "damaged";
+			discount: number;
+		};
+	}
+	| {
+		id: string;
+		unavailable: {
+			reason: "deleted" | "out-of-stock";
+			message: string;
+		};
+	};
+
+declare const externalProduct: ExternalProduct;
+
+// Le builder permet d'enchaîner plusieurs shapes.
+//
+// Après chaque `.with`, les valeurs correspondant au pattern sont retirées
+// du type restant.
+//
+// La dernière branche peut donc devenir exhaustive même sans discriminant
+// explicite sur la donnée.
+
+const productLabel = DPattern.match(externalProduct)
+	.with(
+		{
+			merchant: {
+				id: DCommon.isType("string"),
+			},
+		},
+		// ExternalProduct possédant `merchant`
+		(product) => `merchant:${product.merchant.name}`,
+	)
+	.with(
+		{
+			secondHand: {
+				condition: DPattern.union(
+					"good",
+					"damaged",
+				),
+			},
+		},
+		// ExternalProduct possédant `secondHand`
+		(product) => `second-hand:${product.secondHand.discount}`,
+	)
+	.with(
+		{
+			unavailable: {
+				reason: DPattern.union(
+					"deleted",
+					"out-of-stock",
+				),
+			},
+		},
+		// ExternalProduct possédant `unavailable`
+		(product) => `unavailable:${product.unavailable.reason}`,
+	)
+	.exhaustive();
+type _CheckProductLabelLine53 = DCommon.ExpectType<
+	typeof productLabel,
+	string,
+	"strict"
+>;
+
+// Les patterns peuvent être profondément imbriqués.
+//
+// Il est donc possible de discriminer à partir de propriétés internes,
+// de literals, de tableaux, de predicates ou de plusieurs conditions combinées.
+//
+// Cette puissance est surtout utile pour adapter des données dont la shape
+// n'a pas été conçue pour être facilement discriminable.
+
+// La même discrimination peut être réalisée sous forme de pipe.
+//
+// Lorsqu'un `match` réussit, son résultat devient un `PatternResult`.
+// Les étapes suivantes détectent ce résultat et ne tentent plus de le matcher.
+//
+// Chaque étape travaille donc uniquement avec les valeurs qui n'ont pas encore
+// été traitées.
+
+const productLabelInPipe = DCommon.pipe(
+	externalProduct,
+	DPattern.match(
+		{
+			merchant: {
+				id: DCommon.isType("string"),
+			},
+		},
+		(product) => `merchant:${product.merchant.name}`,
+	),
+	DPattern.match(
+		{
+			secondHand: {
+				condition: DPattern.union(
+					"good",
+					"damaged",
+				),
+			},
+		},
+		(product) => `second-hand:${product.secondHand.discount}`,
+	),
+	DPattern.match(
+		{
+			unavailable: {
+				reason: DPattern.union(
+					"deleted",
+					"out-of-stock",
+				),
+			},
+		},
+		(product) => `unavailable:${product.unavailable.reason}`,
+	),
+	DPattern.exhaustive,
+);
+type _CheckProductLabelInPipeLine106 = DCommon.ExpectType<
+	typeof productLabelInPipe,
+	`merchant:${string}` | `second-hand:${number}` | "unavailable:deleted" | "unavailable:out-of-stock",
+	"strict"
+>;
+
+// Une sélection partielle peut se terminer par otherwise plutôt que par exhaustive.
+// Le callback de repli reçoit précisément les formes qui restent à traiter.
+const productLabelWithFallback = DPattern.match(externalProduct)
+	.with(
+		{ merchant: { id: DCommon.isType("string") } },
+		(product) => `merchant:${product.merchant.name}`,
+	)
+	.otherwise((product) => product.id);
+
+// Lorsque le modèle est contrôlé, privilégier une identité explicite.
+// La sélection par forme sert surtout à adapter des données externes imposées par
+// une API, une base de données ou une librairie.

package/docs/concepts/01-fundamental/07-discrimination/70-predicate.ts

@@ -0,0 +1,101 @@
+/**
+ * @title Discrimination par prédicats et élimination.
+ *
+ * Affiner les branches et réduire les cas restants, avec sélection positive ou inverse.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DPattern from "@duplojs/lang/pattern";
+import * as DString from "@duplojs/lang/string";
+
+// when et whenNot discriminent par élimination
+// à partir d’un predicate, sans nécessiter de pattern décrivant la forme.
+//
+// Il est préférable de réutiliser les predicates fournis par `@duplojs/lang`
+// lorsqu'ils correspondent au besoin.
+//
+// Avec un type predicate, la branche traitée est retirée du type restant.
+
+declare const externalValue: string | number | null;
+
+const normalizedValue = DCommon.pipe(
+	externalValue,
+	DPattern.when(
+		DCommon.isType("number"),
+		// number
+		(value) => value * 2,
+	),
+	DPattern.whenNot(
+		DCommon.isType("string"),
+		// null
+		() => "empty" as const,
+	),
+	DPattern.when(
+		DCommon.isType("string"),
+		// string
+		DString.trim,
+	),
+	DPattern.exhaustive,
+);
+type _CheckNormalizedValueLine21 = DCommon.ExpectType<
+	typeof normalizedValue,
+	(string & DString.Trimmed) | number | "empty",
+	"strict"
+>;
+
+// `whenNot` applique le predicate de manière inverse.
+//
+// Dans l'exemple précédent, après l'élimination des `number`,
+// il ne reste que `string | null`.
+//
+// `whenNot(isType("string"))` sélectionne donc précisément `null`.
+
+// Les predicates de literals peuvent également être construits avec
+// les outils existants du package.
+
+declare const framework: "duplojs" | "other";
+
+const frameworkResult = DCommon.pipe(
+	framework,
+	DPattern.whenNot(
+		DCommon.equal("other"),
+		(value) => {
+			type _CheckKnownFramework = DCommon.ExpectType<typeof value, "duplojs", "strict">;
+			return "known" as const;
+		},
+	),
+	DPattern.when(
+		DCommon.equal("other"),
+		(value) => {
+			type _CheckUnknownFramework = DCommon.ExpectType<typeof value, "other", "strict">;
+			return "unknown" as const;
+		},
+	),
+	DPattern.exhaustive,
+);
+type _CheckFrameworkResultLine54 = DCommon.ExpectType<
+	typeof frameworkResult,
+	"known" | "unknown",
+	"strict"
+>;
+
+// `match`, `when` et `whenNot` sont donc principalement utiles lorsque
+// la discrimination doit être déduite de la donnée elle-même.
+//
+// Lorsque le modèle peut être contrôlé, préférer une identité explicite
+// (`Entity`, `Fact`, `TaggedObject`) ou une union de literals directement
+// discriminable avec `matchWithString` ou `matchWithNumber`.
+
+// Les étapes when et whenNot produisent aussi un PatternResult après sélection.
+// Les étapes suivantes le transmettent sans réexaminer sa valeur.
+// exhaustive termine le pipe uniquement lorsque le typage n’a plus de cas non traités.
+
+// Un predicate retournant seulement boolean ne permet pas d’éliminer une variante dans le typage.
+// otherwise termine alors le traitement avec une branche de repli sur les cas restants.
+const valueWithFallback = DCommon.pipe(
+	externalValue,
+	DPattern.when(
+		(value): boolean => value === null,
+		() => "empty" as const,
+	),
+	DPattern.otherwise((value) => value),
+);

package/docs/concepts/01-fundamental/07-discrimination/index.md

@@ -0,0 +1,3 @@
+## Discrimination
+
+Sélection et affinement des types dans les unions : identité, valeurs littérales, forme ou prédicats, traitement exhaustif ou partiel.

package/docs/concepts/01-fundamental/08-kind/01-identity.md

@@ -0,0 +1,7 @@
+### Identité des objets avec les kinds
+
+De nombreux objets DuploJS portent des kinds pour être reconnus et distingués malgré le typage structurel de TypeScript.
+
+Ces clés textuelles au runtime, représentées sous un symbole dans les types, portent identité et métadonnées. Leur reconnaissance survit au transport si la sérialisation les préserve.
+
+Les kinds servent surtout à construire les outils ; utiliser DuploJS ne demande généralement pas de les manipuler directement.

package/docs/concepts/01-fundamental/08-kind/20-metadata.md

@@ -0,0 +1,11 @@
+### Métadonnées internes des kinds
+
+Un petit store attaché à l'objet, exploitable dans les types ou au runtime selon son contrat.
+
+---
+
+Un objet peut porter plusieurs kinds. Dans un `Right`, ils contiennent notamment le statut, l'information contextuelle et la valeur. Un kind peut aussi n'être qu'un marqueur, avec une valeur `null`.
+
+Certaines informations associées au kind servent uniquement au typage et ne reflètent pas nécessairement la valeur stockée. Consulter le contrat du domaine avant de les exploiter au runtime. Contrairement aux kinds, les [contraintes de typage](../01-constraint/index.md) n'ajoutent aucune propriété à la valeur.
+
+Ces métadonnées sont internes, mais restent observables dans l'objet JavaScript. Le `has` d'un gestionnaire vérifie seulement la présence de sa clé ; la validation du contenu relève des [DataStructure](../04-data-structure/index.md).

package/docs/concepts/01-fundamental/08-kind/30-transport.md

@@ -0,0 +1,11 @@
+### Transport de l'identité entre programmes
+
+Reconnaître une donnée après désérialisation sans dépendre du constructeur de son runtime d'origine.
+
+---
+
+Les clés runtime des kinds dépendent de leur nom et de leur namespace. Un autre programme connaissant cette convention peut donc reconnaître la donnée, sans partager le gestionnaire en mémoire qui l'a créée.
+
+Une sérialisation JSON conserve ces clés textuelles énumérables et leurs valeurs compatibles. Un objet taggé peut ainsi rester reconnaissable après transport entre deux serveurs. À l'inverse, JSON ne rétablit pas le prototype permettant la reconnaissance habituelle d'une instance de classe par `instanceof`.
+
+Le transport doit préserver les marqueurs nécessaires : une propriété valant `undefined` est omise et une fonction n'est pas transportée. La présence d'un kind ne valide pas les données reçues ; utiliser le contrat de validation du domaine à la frontière externe.

package/docs/concepts/01-fundamental/08-kind/index.md

@@ -0,0 +1,3 @@
+## Kind
+
+Identité et métadonnées internes des objets de l'écosystème, reconnaissables au typage et au runtime.

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

@@ -0,0 +1 @@
+# Fondamentaux.

package/docs/concepts/02-server/10-file/10-manipulation.ts

@@ -0,0 +1,52 @@
+/**
+ * @title Manipuler le système de fichiers
+ *
+ * Lecture, écriture et opérations de système de fichiers avec chemins typés et résultats `Either`.
+ */
+import type * as DPath from "@duplojs/lang/path";
+import * as DCommon from "@duplojs/lang/common";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+const textResourcePath: string & DPath.Path = DCommon.cast("/path/to/text/resource");
+
+// Les fonctions de `@duplojs/server/file` prennent des chemins contraints
+// et retournent un `Either` discriminable.
+const readTextResourceResult = await DSFile.readTextFile(textResourcePath);
+
+if (DEither.isRight(readTextResourceResult)) {
+	type _CheckReadTextRight = DCommon.ExpectType<
+		typeof readTextResourceResult,
+		DEither.Right<"file-system-read-text-file", string>,
+		"strict"
+	>;
+	void readTextResourceResult;
+
+	const textResource = DEither.unwrapRight(readTextResourceResult);
+	type _CheckTextResourceLine23 = DCommon.ExpectType<
+	typeof textResource,
+	string,
+	"strict"
+	>;
+} else {
+	// Le Left porte l'échec de l'opération ; sa valeur porte l'erreur précise.
+	type _CheckReadTextLeft = DCommon.ExpectType<
+		typeof readTextResourceResult,
+		DEither.Left<"file-system-read-text-file-error", DSFile.ReadTextFileErrors>,
+		"strict"
+	>;
+	const error = DEither.unwrapLeft(readTextResourceResult);
+
+	type _CheckError = DCommon.ExpectType<typeof error, DSFile.ReadTextFileErrors, "strict">;
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-read-text-file-not-found": () => "missing-resource",
+			"file-system-read-text-file-permission-denied": () => "access-denied",
+		},
+		// Conserver les autres erreurs, au lieu de toutes les traiter comme une absence.
+		(otherError) => otherError,
+	);
+}

package/docs/concepts/02-server/10-file/20-path.ts

@@ -0,0 +1,72 @@
+/**
+ * @title Chemins typés
+ *
+ * Contraintes `Path`, `Absolute` et `Segment` pour valider, extraire et résoudre des chemins Unix.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DEither from "@duplojs/lang/either";
+import * as DPath from "@duplojs/lang/path";
+
+// Un chemin reste une string, enrichie par des contraintes de typage.
+const imagePath: string & DPath.Path = DCommon.cast("resources/images/avatar.png");
+const rootPath: string & DPath.Path & DPath.Absolute = DCommon.cast("/resources");
+const fileSegment: string & DPath.Segment = DCommon.cast("avatar.png");
+
+// Une string dynamique doit être validée avant d'être utilisée comme `Path`.
+declare const unsafePath: string;
+
+const pathResult = DPath.create(unsafePath);
+
+if (DEither.isRight(pathResult)) {
+	const path = DEither.unwrapRight(pathResult);
+	type _CheckPathLine22 = DCommon.ExpectType<
+	typeof path,
+	string & DPath.Path,
+	"strict"
+	>;
+}
+
+// Les helpers extraient des parties contraintes sans retravailler la string.
+const fileName = DPath.getBaseName(imagePath);
+type _CheckFileName = DCommon.ExpectType<typeof fileName, (string & DPath.Segment & DPath.Path) | null, "strict">;
+
+const extensionName = DPath.getExtensionName(imagePath);
+type _CheckExtensionNameLine30 = DCommon.ExpectType<
+	typeof extensionName,
+	(string & DPath.Segment & DPath.Path) | null,
+	"strict"
+>;
+
+const parentFolderPath = DPath.getParentFolderPath(imagePath);
+type _CheckParentFolderPathLine33 = DCommon.ExpectType<
+	typeof parentFolderPath,
+	(string & DPath.Path) | null,
+	"strict"
+>;
+
+// Les fonctions de résolution assemblent des `Path` et `Segment` validés.
+const resolvedPath = DPath.resolveFrom(
+	rootPath,
+	[
+		DCommon.infer("assets"),
+		fileSegment,
+	],
+	{
+		stayInOrigin: true,
+	},
+);
+type _CheckResolvedPath = DCommon.ExpectType<
+	typeof resolvedPath,
+	(string & DPath.Path & DPath.Absolute) | null,
+	"strict"
+>;
+
+// Résolution sans origine protectrice.
+const relativePath = DPath.resolveRelative(
+	[
+		rootPath,
+		DCommon.infer("assets/logo"),
+		DCommon.infer("logo1.png"),
+	],
+);
+type _CheckRelativePath = DCommon.ExpectType<typeof relativePath, string & DPath.Path & DPath.Absolute, "strict">;

package/docs/concepts/02-server/10-file/index.md

@@ -0,0 +1,3 @@
+## Manipuler des fichiers
+
+Accès cross-platform au système de fichiers : chemins typés avec `Path`, opérations sur fichiers/dossiers/liens et erreurs représentées par `Either`.

package/docs/concepts/02-server/20-http/10-init.ts

@@ -0,0 +1,23 @@
+/**
+ * @title Créer une application HTTP
+ *
+ * Configuration d'un `Hub` et enregistrement des routes d'une application HTTP.
+ */
+import { createHub, routeStore } from "@duplojs/http";
+
+export const hub = createHub({ environment: "DEV" })
+	// Les modules de routes doivent être chargés avant l'enregistrement du store.
+	.register(
+		routeStore.getAll(),
+	);
+
+// Le connecteur démarre le `Hub` sur la plateforme ciblée.
+import { createHttpServer } from "@duplojs/http/node";
+
+await createHttpServer(
+	hub,
+	{
+		host: "localhost",
+		port: 1506,
+	},
+);

package/docs/concepts/02-server/20-http/20-route.ts

@@ -0,0 +1,182 @@
+/**
+ * @title Créer une route HTTP
+ *
+ * Définir les entrées d'une route, préparer les données du traitement et produire sa réponse HTTP.
+ */
+import { useRouteBuilder, controlBodyAsFormData, type RouteDeclarationToContract } from "@duplojs/http";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DSDataStructure from "@duplojs/server/dataStructure";
+
+const userStructure = DDataStructure.object({
+	id: DDataStructure.string([DDataStructure.uuid()]),
+	name: DDataStructure.string(),
+	email: DDataStructure.string([DDataStructure.email()]),
+});
+
+type User = DDataStructure.StructureValue<typeof userStructure>;
+
+declare function getUsers(params: {
+	page: number;
+	quantityPerPage: number;
+}): Promise<User[]>;
+
+// Une route est une suite de steps exécutées dans l'ordre.
+// Elles partagent leurs données via le `floor`; `handler` clôture la route.
+export const usersRoute = useRouteBuilder("GET", "/users")
+	.extract({
+		query: {
+			page: DDataStructure.number([
+				DDataStructure.integer(),
+				DDataStructure.positive(),
+			]),
+			quantityPerPage: DDataStructure.number([
+				DDataStructure.integer(),
+				DDataStructure.greaterThanOrEqual(5),
+				DDataStructure.lessThanOrEqual(20),
+			]),
+		},
+	})
+	.handler(
+		async({ page, quantityPerPage }, { response }) => {
+			const users = await getUsers({
+				page,
+				quantityPerPage,
+			});
+
+			return response.ok("users.findMany", users);
+		},
+	);
+
+// `response.ok` construit une réponse 200 avec une information et un body.
+// L'information identifie le résultat de l'opération, même lorsque plusieurs
+// réponses partagent le même statut HTTP.
+// Le type de la route reprend les réponses retournées par ses étapes :
+// ici le résultat du handler et le refus d'extraction par défaut.
+export type UsersRouteContract = RouteDeclarationToContract<typeof usersRoute>;
+
+type _CheckResponses = DCommon.ExpectType<
+	UsersRouteContract["responses"],
+	| {
+		readonly code: "200";
+		readonly information: "users.findMany";
+		readonly body: User[];
+	}
+	| {
+		readonly code: "422";
+		readonly information: "extract-error";
+		readonly body: string;
+	},
+	"strict"
+>;
+
+// `extract` valide les entrées de requête avant de les ajouter au `floor`.
+// Il peut cibler params, query, headers et body.
+useRouteBuilder("POST", "/users/{userId}")
+	.extract({
+		params: {
+			userId: DDataStructure.number([DDataStructure.positive()]),
+		},
+		query: {
+			search: DDataStructure.string(),
+		},
+	})
+	.extract({
+		headers: {
+			token: DDataStructure.string(),
+		},
+		body: DDataStructure.object({
+			username: DDataStructure.string(),
+			age: DDataStructure.number(),
+		}),
+	})
+	.handler(
+		(
+			{
+				userId,
+				search,
+				token,
+				body,
+			},
+			{ response },
+		) => {
+			void userId;
+			void search;
+			void token;
+			void body.username;
+			void body.age;
+
+			return response.noContent("user.received");
+		},
+	);
+
+// Si une source utilise directement une `DataStructure`, elle garde son nom :
+// le body sera disponible dans `floor.body`.
+useRouteBuilder("POST", "/profile")
+	.extract(
+		{
+			body: DDataStructure.object({
+				name: DDataStructure.string(),
+				age: DDataStructure.number(),
+			}),
+		},
+		// Cette réponse locale remplace le refus d'extraction du Hub pour cette étape.
+		({ response }) => response.badRequest("profile.invalid"),
+	)
+	.handler(
+		({ body }, { response }) => {
+			void body.name;
+			void body.age;
+
+			return response.noContent("profile.updated");
+		},
+	);
+
+// Si une source contient plusieurs `DataStructure`, chaque propriété est
+// ajoutée au `floor` : ici `floor.page` et `floor.search`.
+useRouteBuilder("GET", "/search")
+	.extract({
+		query: {
+			page: DDataStructure.number(),
+			search: DDataStructure.string(),
+		},
+	})
+	.handler(
+		({ page, search }, { response }) => {
+			void page;
+			void search;
+
+			return response.noContent("search.done");
+		},
+	);
+
+// `bodyController` remplace le body JSON par défaut, par exemple pour recevoir
+// du `FormData`.
+useRouteBuilder(
+	"POST",
+	"/documents",
+	{
+		bodyController: controlBodyAsFormData({
+			maxFileQuantity: 5,
+		}),
+	},
+)
+	.extract({
+		body: {
+			title: DDataStructure.string(),
+			userId: DDataStructure.number(),
+			files: DDataStructure.array(
+				DSDataStructure.file(),
+				[DDataStructure.maxElements(3)],
+			),
+		},
+	})
+	.handler(
+		({ title, userId, files }, { response }) => {
+			void title;
+			void userId;
+			void files;
+
+			return response.noContent("documents.received");
+		},
+	);