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

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

@@ -0,0 +1,152 @@
+/**
+ * @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.
+
+// string
+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();
+
+// 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.
+
+// string
+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,
+);
+
+// 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,89 @@
+/**
+ * @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;
+
+// string | number | "empty"
+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,
+);
+
+// `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";
+
+// "known" | "unknown"
+const frameworkResult = DCommon.pipe(
+	framework,
+	DPattern.whenNot(
+		DCommon.equal("other"),
+		// "duplojs"
+		() => "known" as const,
+	),
+	DPattern.when(
+		DCommon.equal("other"),
+		// "other"
+		() => "unknown" as const,
+	),
+	DPattern.exhaustive,
+);
+
+// `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/index.md

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

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

@@ -0,0 +1,40 @@
+/**
+ * @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)) {
+	// DEither.Right<"file-system-read-text-file", string>
+	void readTextResourceResult;
+
+	// string
+	const textResource = DEither.unwrapRight(readTextResourceResult);
+} else {
+	// Le Left porte l'échec de l'opération ; sa valeur porte l'erreur précise.
+	// DEither.Left<"file-system-read-text-file-error", DSFile.ReadTextFileErrors>
+	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,56 @@
+/**
+ * @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)) {
+	// string & DPath.Path
+	const path = DEither.unwrapRight(pathResult);
+}
+
+// Les helpers extraient des parties contraintes sans retravailler la string.
+// (string & DPath.Segment) | null
+const fileName = DPath.getBaseName(imagePath);
+
+// (string & DPath.Segment) | null
+const extensionName = DPath.getExtensionName(imagePath);
+
+// (string & DPath.Path) | null
+const parentFolderPath = DPath.getParentFolderPath(imagePath);
+
+// Les fonctions de résolution assemblent des `Path` et `Segment` validés.
+// (string & DPath.Absolute) | null
+const resolvedPath = DPath.resolveFrom(
+	rootPath,
+	[
+		DCommon.infer("assets"),
+		fileSegment,
+	],
+	{
+		stayInOrigin: true,
+	},
+);
+
+// Résolution sans origine protectrice.
+// string & DPath.Path & DPath.Absolute
+const relativePath = DPath.resolveRelative(
+	[
+		rootPath,
+		DCommon.infer("assets/logo"),
+		DCommon.infer("logo1.png"),
+	],
+);

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,31 @@
+/**
+ * @title Créer une application HTTP
+ *
+ * Configuration d'un `Hub`, plugins et enregistrement des routes d'une application HTTP.
+ */
+import { createHub, routeStore } from "@duplojs/http";
+import { codeGeneratorPlugin } from "@duplojs/http/codeGenerator";
+import * as DCommon from "@duplojs/lang/common";
+
+export const hub = createHub({ environment: "DEV" })
+	.plug(
+		// Les plugins ajoutent des capacités au `Hub`.
+		codeGeneratorPlugin({
+			outputFile: DCommon.infer("types.d.ts"),
+		}),
+	)
+	// 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,174 @@
+/**
+ * @title Créer une route HTTP
+ *
+ * Construction du flux d’une route : entrées validées, contexte de traitement et réponses contextualisées.
+ */
+import { ResponseContract, useRouteBuilder, controlBodyAsFormData } from "@duplojs/http";
+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.
+useRouteBuilder("GET", "/users")
+	.extract({
+		query: {
+			page: DDataStructure.number([
+				DDataStructure.integer(),
+				DDataStructure.positive(),
+			]),
+			quantityPerPage: DDataStructure.number([
+				DDataStructure.integer(),
+				DDataStructure.greaterThanOrEqual(5),
+				DDataStructure.lessThanOrEqual(20),
+			]),
+		},
+	})
+	.handler(
+		ResponseContract.ok("users.findMany", DDataStructure.array(userStructure)),
+		async({ page, quantityPerPage }, { response }) => {
+			const users = await getUsers({
+				page,
+				quantityPerPage,
+			});
+
+			return response("users.findMany", users);
+		},
+	);
+
+// Un `ResponseContract` associe un statut HTTP, un body éventuel et une
+// `information` littérale.
+//
+// L'information contextualise la réponse et sert de discriminant principal.
+// Le statut HTTP garde son rôle de convention protocolaire, mais c'est
+// l'information qui identifie finement le résultat du flux, y compris lorsqu'une
+// réponse n'a pas besoin de body.
+ResponseContract.ok("superResponse", DDataStructure.string());
+ResponseContract.created("user.created", userStructure);
+ResponseContract.noContent("user.deleted");
+ResponseContract.conflict("email.alreadyUse");
+ResponseContract.notFound("user.notfound");
+ResponseContract.notFound("product.notfound");
+
+// `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(
+		ResponseContract.noContent("user.received"),
+		(
+			{
+				userId,
+				search,
+				token,
+				body,
+			},
+			{ response },
+		) => {
+			void userId;
+			void search;
+			void token;
+			void body.username;
+			void body.age;
+
+			return response("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(),
+		}),
+	})
+	.handler(
+		ResponseContract.noContent("profile.updated"),
+		({ body }, { response }) => {
+			void body.name;
+			void body.age;
+
+			return response("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(
+		ResponseContract.noContent("search.done"),
+		({ page, search }, { response }) => {
+			void page;
+			void search;
+
+			return response("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(
+		ResponseContract.noContent("documents.received"),
+		({ title, userId, files }, { response }) => {
+			void title;
+			void userId;
+			void files;
+
+			return response("documents.received");
+		},
+	);