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

package/docs/concepts/02-server/40-command/10-use.ts

@@ -0,0 +1,112 @@
+/**
+ * @title Définir une commande
+ *
+ * Définition des entrées et du traitement d’une commande CLI.
+ */
+import * as DSCommand from "@duplojs/server/command";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+// Une commande simple peut uniquement déclarer les arguments
+// dont elle a besoin.
+// `exec` interprète les entrées selon leurs déclarations, puis transmet les
+// valeurs typées au callback : les arguments dans `args`, les options dans `options`.
+await DSCommand.exec(
+	{
+		description: "Display a greeting",
+		subjects: [
+			DSCommand.createArgument(
+				"name",
+				DDataStructure.string(),
+			),
+		],
+	},
+	({ args: { name } }) => {
+		console.log(`Hello ${name}!`);
+	},
+);
+
+// Une commande peut combiner plusieurs arguments et différentes
+// formes d'options.
+await DSCommand.exec(
+	{
+		description: "Copy files to a destination",
+		options: [
+			// Une option classique attend une valeur qui sera
+			// interprétée avec sa `DataStructure`.
+			DSCommand.createOption(
+				"mode",
+				DDataStructure.literal([
+					"copy",
+					"move",
+				]),
+				{
+					aliases: ["m"],
+					description: "Operation to perform",
+				},
+			),
+			// Une option booléenne représente directement
+			// la présence ou non du flag.
+			DSCommand.createBooleanOption(
+				"force",
+				{
+					aliases: ["f"],
+					description: "Overwrite existing files",
+				},
+			),
+			// Une option tableau permet de recevoir plusieurs
+			// valeurs respectant une même `DataStructure`.
+			DSCommand.createArrayOption(
+				"include",
+				DDataStructure.string(),
+				{
+					description: "Files to include",
+					min: 1,
+					max: 5,
+				},
+			),
+		],
+		subjects: [
+			DSCommand.createArgument(
+				"source",
+				DDataStructure.string(),
+			),
+			DSCommand.createArgument(
+				"destination",
+				DDataStructure.string(),
+			),
+		],
+	},
+	({
+		args: { source, destination },
+		options: { mode, force, include },
+	}) => {
+		void source;
+		void destination;
+		void mode;
+		void force;
+		void include;
+	},
+);
+
+// Si ce fichier est exposé comme binaire, `DSCommand.exec` lit les arguments
+// transmis par le terminal. Le fichier peut être un `.ts` exécutable lorsque
+// son shebang indique l'interpréteur à utiliser.
+//
+// #!/usr/bin/env -S tsx
+//
+// package.json
+// {
+//   "bin": {
+//     "my-cli": "./scripts/bin.ts"
+//   }
+// }
+//
+// my-cli Jane
+// -> name: "Jane"
+//
+// my-cli ./src ./dist --mode=copy --force --include=a.ts,b.ts
+// -> source: "./src"
+// -> destination: "./dist"
+// -> mode: "copy"
+// -> force: true
+// -> include: ["a.ts", "b.ts"]

package/docs/concepts/02-server/40-command/20-sub-command.ts

@@ -0,0 +1,48 @@
+/**
+ * @title Créer des sous-commandes
+ *
+ * Composition de commandes sous forme d'arbre pour router l'exécution vers
+ * une branche spécialisée.
+ */
+import * as DSCommand from "@duplojs/server/command";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const installCommand = DSCommand.create(
+	"install",
+	{
+		description: "Install a package",
+		options: [
+			DSCommand.createBooleanOption(
+				"yes",
+				{
+					aliases: ["y"],
+					description: "Answer yes to prompts",
+				},
+			),
+		],
+		subjects: [
+			DSCommand.createArgument(
+				"packageName",
+				DDataStructure.string(),
+			),
+		],
+	},
+	({ options, args: { packageName } }) => {
+		console.log(
+			`install ${packageName}${options.yes ? " without prompt" : ""}`,
+		);
+	},
+);
+
+// La commande parente référence directement ses sous-commandes
+// dans ses `subjects`. Une commande avec sous-commandes ne déclare pas
+// d'arguments au même niveau.
+await DSCommand.exec(
+	{
+		description: "Package manager",
+		subjects: [installCommand],
+	},
+	() => {
+		console.log("select a package command");
+	},
+);

package/docs/concepts/02-server/40-command/index.md

@@ -0,0 +1,3 @@
+## Créer des commandes
+
+Création d’interfaces en ligne de commande (CLI) pour les applications serveur.

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

@@ -0,0 +1 @@
+# Serveur

package/docs/concepts/03-client/10-http/10-init.ts

@@ -0,0 +1,52 @@
+/**
+ * @title Initialiser un client HTTP
+ *
+ * Configuration d'un client HTTP typé et des paramètres communs aux requêtes.
+ */
+import { createHttpClient } from "@duplojs/http/client";
+import { type RouteDeclarationToContract } from "@duplojs/http";
+import * as DCommon from "@duplojs/lang/common";
+import { type usersRoute } from "../../02-server/20-http/20-route";
+
+// L'import de type ne charge pas les déclarations de routes au runtime.
+// Les réponses incluent les retours du handler et les refus des étapes.
+export type Routes = RouteDeclarationToContract<typeof usersRoute>;
+
+// `baseUrl` suffit pour créer un client.
+// Les autres options configurent le comportement global.
+export const client = createHttpClient<Routes>({
+	baseUrl: "http://localhost:1506",
+});
+
+declare function getAuthToken(): string | undefined;
+
+// Un header par défaut peut être fixe ou recalculé à chaque requête.
+client.addDefaultHeader(
+	"authorization",
+	() => getAuthToken(),
+);
+
+// Le contrat limite les paths, paramètres et réponses disponibles.
+const response = await client
+	.get(
+		"/users",
+		{
+			query: {
+				page: DCommon.cast(1),
+				quantityPerPage: DCommon.cast(5),
+			},
+		},
+	)
+	.iWantInformationOrThrow("users.findMany");
+
+void response.body;
+void response.code;
+void response.information;
+void response.headers;
+void response.raw;
+
+// `information` est lue depuis le header `information`, sauf configuration.
+createHttpClient<Routes>({
+	baseUrl: "http://localhost:1506",
+	informationHeaderKey: "x-information",
+});

package/docs/concepts/03-client/10-http/20-request.ts

@@ -0,0 +1,254 @@
+/**
+ * @title Effectuer une requête HTTP
+ *
+ * Envoi de données et traitement des réponses typées d’une API HTTP.
+ */
+import { createHttpClient } from "@duplojs/http/client";
+import type * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DEither from "@duplojs/lang/either";
+
+export type Routes = {
+	readonly method: "POST";
+	readonly path: "/users";
+	readonly body: {
+		readonly username: string;
+		readonly age: number;
+	};
+	readonly responses: {
+		readonly code: "422";
+		readonly information: "extract-error";
+		readonly body: Error;
+	} | {
+		readonly code: "204";
+		readonly information: "user.created";
+		readonly body: undefined;
+	};
+} | {
+	readonly method: "POST";
+	readonly path: "/users/{userId}/posts";
+	readonly params: {
+		readonly userId: number;
+	};
+	readonly body: {
+		readonly title: string;
+		readonly content: string;
+	};
+	readonly responses: {
+		readonly code: "422";
+		readonly information: "extract-error";
+		readonly body: Error;
+	} | {
+		readonly code: "204";
+		readonly information: "post.created";
+		readonly body: undefined;
+	};
+} | {
+	readonly method: "POST";
+	readonly path: "/documents";
+	readonly body: DCommon.TheFormData<{
+		readonly bool: boolean;
+		readonly myFile: readonly File[] & DArray.LengthEqual<1>;
+		readonly name: string;
+	}>;
+	readonly responses: {
+		readonly code: "422";
+		readonly information: "extract-error";
+		readonly body: Error;
+	} | {
+		readonly code: "204";
+		readonly information: "file.receive";
+		readonly body: undefined;
+	};
+} | {
+	readonly method: "GET";
+	readonly path: "/posts";
+	readonly query: {
+		readonly page: number;
+	};
+	readonly responses: {
+		readonly code: "422";
+		readonly information: "extract-error";
+		readonly body: Error;
+	} | {
+		readonly code: "200";
+		readonly information: "post.findMany";
+		readonly body: readonly {
+			readonly title: string;
+			readonly content: string;
+			readonly authorId: number;
+		}[];
+	};
+};
+
+const client = createHttpClient<Routes>({
+	baseUrl: "http://localhost:1506",
+});
+
+// La méthode choisie filtre les paths et paramètres autorisés.
+// L’appel retourne une `PromiseRequest` sur laquelle composer le traitement
+// des réponses avant d’attendre le résultat avec `await`.
+const promiseRequestCreateUser = client
+	.post(
+		"/users",
+		{
+			body: {
+				username: "math",
+				age: 23,
+			},
+		},
+	);
+
+const promiseRequestFindManyPost = client
+	.get(
+		"/posts",
+		{
+			query: {
+				page: 3,
+			},
+		},
+	);
+
+// `TheFormData` se construit avec `createFormData`; le client l'envoie en
+// `FormData` natif.
+declare function getSelectedDocumentFile(): File;
+
+const promiseRequestSendDocument = client
+	.post(
+		"/documents",
+		{
+			body: DCommon.createFormData({
+				bool: true,
+				myFile: DCommon.cast([getSelectedDocumentFile()]),
+				name: "client/document.send",
+			}),
+		},
+	);
+
+// `when*` branche des effets de bord sur les réponses ciblées.
+await client
+	.get(
+		"/posts",
+		{
+			query: {
+				page: 3,
+			},
+		},
+	)
+	.whenInformation(
+		"post.findMany",
+		({ body }) => {
+			type _CheckPostBody = DCommon.ExpectType<
+				typeof body,
+				readonly {
+					readonly title: string;
+					readonly content: string;
+					readonly authorId: number;
+				}[],
+				"strict"
+			>;
+			void body;
+		},
+	)
+	.whenCode(
+		"422",
+		({ information }) => {
+			type _CheckErrorInformation = DCommon.ExpectType<typeof information, "extract-error", "strict">;
+			void information;
+		},
+	);
+
+// `iWant*` retourne un `Either` : réponse voulue en `right`, transport error
+// ou réponse non voulue en `left`.
+const maybeCreatedPost = await client
+	.post(
+		"/users/{userId}/posts",
+		{
+			params: {
+				userId: 1,
+			},
+			body: {
+				title: "Super article",
+				content: "Super content of article",
+			},
+		},
+	)
+	.iWantInformation("post.created");
+
+if (DEither.isRight(maybeCreatedPost)) {
+	const response = DEither.unwrapRight(maybeCreatedPost);
+	type _CheckCreatedInformation = DCommon.ExpectType<typeof response.information, "post.created", "strict">;
+	void response.information;
+}
+
+// `OrThrow` interrompt le flux lorsqu'une réponse inattendue apparaît.
+const createdPostResponse = await client
+	.post(
+		"/users/{userId}/posts",
+		{
+			params: {
+				userId: 1,
+			},
+			body: {
+				title: "Super article",
+				content: "Super content of article",
+			},
+		},
+	)
+	.iWantInformationOrThrow("post.created");
+type _CheckCreatedPostInformation = DCommon.ExpectType<
+	typeof createdPostResponse.information,
+	"post.created",
+	"strict"
+>;
+
+// `expected` regroupe les succès `2xx` et erreurs client `4xx`.
+const maybeExpectedResponse = await client
+	.get(
+		"/posts",
+		{
+			query: {
+				page: 3,
+			},
+		},
+	)
+	.iWantExpectedResponse();
+
+if (DEither.isRight(maybeExpectedResponse)) {
+	const response = DEither.unwrapRight(maybeExpectedResponse);
+	type _CheckExpectedInformation = DCommon.ExpectType<
+		typeof response.information,
+		"post.findMany" | "extract-error",
+		"strict"
+	>;
+	void response.information;
+}
+
+// Le sélecteur par `information` force un choix pour chaque réponse attendue.
+const maybePosts = await client
+	.get(
+		"/posts",
+		{
+			query: {
+				page: 3,
+			},
+		},
+	)
+	.iSelectExpectedResponseByInformation({
+		"post.findMany": true,
+		"extract-error": false,
+	});
+
+if (DEither.isRight(maybePosts)) {
+	const response = DEither.unwrapRight(maybePosts);
+	type _CheckPostsBody = DCommon.ExpectType<typeof response.body, readonly {
+		readonly title: string;
+		readonly content: string;
+		readonly authorId: number;
+	}[], "strict">;
+	void response.body;
+}
+
+// Les familles `when*`, `iWant*` et `*OrThrow` ciblent une `information`, un
+// code HTTP, une classe de statut ou les réponses attendues. Prioriser
+// `information` pour exprimer un cas précis.

package/docs/concepts/03-client/10-http/30-hook.ts

@@ -0,0 +1,139 @@
+/**
+ * @title Utiliser les hooks du client HTTP
+ *
+ * Comportements transversaux et instrumentation du cycle des échanges HTTP.
+ */
+import { createHttpClient } from "@duplojs/http/client";
+
+export type Routes = {
+	readonly method: "GET";
+	readonly path: "/profile";
+	readonly responses: {
+		readonly code: "401";
+		readonly information: "auth.required";
+		readonly body: undefined;
+	} | {
+		readonly code: "200";
+		readonly information: "profile.found";
+		readonly body: {
+			readonly name: string;
+			readonly email: string;
+		};
+	};
+} | {
+	readonly method: "POST";
+	readonly path: "/users";
+	readonly body: {
+		readonly username: string;
+		readonly age: number;
+	};
+	readonly responses: {
+		readonly code: "422";
+		readonly information: "extract-error";
+		readonly body: Error;
+	} | {
+		readonly code: "204";
+		readonly information: "user.created";
+		readonly body: undefined;
+	};
+};
+
+interface HookParams {
+	readonly [key: string]: unknown;
+	readonly requestId: string;
+	readonly startedAt: number;
+}
+
+const client = createHttpClient<Routes, HookParams>({
+	baseUrl: "http://localhost:1506",
+});
+
+declare function toast(message: string): void;
+declare function startLoader(): void;
+declare function stopLoader(): void;
+declare function createRequestId(): string;
+declare function getCurrentTime(): number;
+declare function sendMetric(name: string, requestId: string, value: number): void;
+
+// Les hooks de cycle portent bien les effets globaux : loader, toast, métrique.
+client.addRequestHook(
+	(requestParams) => {
+		startLoader();
+
+		return requestParams;
+	},
+);
+
+client.addResponseHook(
+	(response) => {
+		stopLoader();
+
+		return response;
+	},
+);
+
+client.addErrorHook(
+	() => {
+		stopLoader();
+	},
+);
+
+function getErrorMessage(information: string | undefined) {
+	if (information === "auth.required") {
+		return "Vous devez être connecté.";
+	}
+
+	if (information === "extract-error") {
+		return "Certaines données sont invalides.";
+	}
+
+	return undefined;
+}
+
+// Un hook de type de réponse applique une règle à toute une famille.
+client.addClientErrorResponseTypeHook(
+	(response) => {
+		const message = getErrorMessage(response.information);
+
+		if (message) {
+			toast(message);
+		}
+	},
+);
+
+// Un hook de transformation peut enrichir le contexte technique des hooks
+// suivants, sans modifier le contrat métier typé.
+client.addRequestHook(
+	(requestParams) => ({
+		...requestParams,
+		hookParams: {
+			...requestParams.hookParams,
+			requestId: createRequestId(),
+			startedAt: getCurrentTime(),
+		},
+	}),
+);
+
+client.addResponseHook(
+	(response) => {
+		const hookParams = response.requestParams.hookParams;
+
+		if (hookParams) {
+			sendMetric(
+				"http.request.duration",
+				hookParams.requestId,
+				getCurrentTime() - hookParams.startedAt,
+			);
+		}
+
+		return response;
+	},
+);
+
+// La réponse reste traitée localement ; les hooks retirent les réactions
+// globales répétitives.
+const profile = await client
+	.get("/profile")
+	.iWantInformationOrThrow("profile.found");
+
+void profile.body;

package/docs/concepts/03-client/10-http/index.md

@@ -0,0 +1,3 @@
+## Client HTTP
+
+Communication typée avec des API HTTP.