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

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

@@ -0,0 +1,244 @@
+/**
+ * @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 = {
+	method: "POST";
+	path: "/users";
+	body: {
+		username: string;
+		age: number;
+	};
+	responses: {
+		code: "422";
+		information: "extract-error";
+		body?: undefined;
+	} | {
+		code: "204";
+		information: "user.created";
+		body?: undefined;
+	};
+} | {
+	method: "POST";
+	path: "/users/{userId}/posts";
+	params: {
+		userId: number;
+	};
+	body: {
+		title: string;
+		content: string;
+	};
+	responses: {
+		code: "422";
+		information: "extract-error";
+		body?: undefined;
+	} | {
+		code: "204";
+		information: "post.created";
+		body?: undefined;
+	};
+} | {
+	method: "POST";
+	path: "/documents";
+	body: DCommon.TheFormData<{
+		bool: boolean;
+		myFile: readonly File[] & DArray.LengthEqual<1>;
+		name: string;
+	}>;
+	responses: {
+		code: "422";
+		information: "extract-error";
+		body?: undefined;
+	} | {
+		code: "204";
+		information: "file.receive";
+		body?: undefined;
+	};
+} | {
+	method: "GET";
+	path: "/posts";
+	query: {
+		page: number;
+	};
+	responses: {
+		code: "422";
+		information: "extract-error";
+		body?: undefined;
+	} | {
+		code: "200";
+		information: "post.findMany";
+		body: {
+			title: string;
+			content: string;
+			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 }) => {
+			// body: {
+			//   title: string;
+			//   content: string;
+			//   authorId: number;
+			// }[]
+			void body;
+		},
+	)
+	.whenCode(
+		"422",
+		({ information }) => {
+			// information: "extract-error"
+			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);
+
+	// information: "post.created"
+	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");
+
+// `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);
+
+	// information: "post.findMany" | "extract-error"
+	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);
+
+	// body: {
+	//   title: string;
+	//   content: string;
+	//   authorId: number;
+	// }[]
+	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 = {
+	method: "GET";
+	path: "/profile";
+	responses: {
+		code: "401";
+		information: "auth.required";
+		body?: undefined;
+	} | {
+		code: "200";
+		information: "profile.found";
+		body: {
+			name: string;
+			email: string;
+		};
+	};
+} | {
+	method: "POST";
+	path: "/users";
+	body: {
+		username: string;
+		age: number;
+	};
+	responses: {
+		code: "422";
+		information: "extract-error";
+		body?: undefined;
+	} | {
+		code: "204";
+		information: "user.created";
+		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.

package/docs/concepts/03-client/20-form/10-init.ts

@@ -0,0 +1,95 @@
+/**
+ * @title Créer un formulaire
+ *
+ * Initialisation et cycle de vie d’un formulaire Vue typé.
+ */
+import { createForm, useCheckLayout, useMultiLayout } from "@duplojs/form/vue";
+import { templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect, useNumberInput, useTextInput } from "@duplojs/form/vueDesignSystem";
+import { createGridTemplates } from "@duplojs/form/vueGrid";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+// `createForm` fixe le système de rendu utilisé par cette famille de formulaires.
+// `repeat`, `step` et `union` demandent des composants dédiés pour ajouter,
+// retirer, changer d'étape ou sélectionner une variante.
+const gridTemplates = createGridTemplates({
+	repeat: {
+		addLabel: "Add another item",
+		removeLabel: "Remove this item",
+		addButton: templateFormAddButton,
+		removeButton: templateFormRemoveButton,
+		resetButton: templateFormResetButton,
+	},
+	step: {
+		nextLabel: "Continue",
+		previousLabel: "Back",
+		resetButton: templateFormResetButton,
+		nextButton: templateFormNextButton,
+		previousButton: templateFormPreviousButton,
+	},
+	union: { selectInputKind: templateFormSelect },
+});
+
+const useForm = createForm(
+	gridTemplates.useTemplates(),
+);
+
+// Le champ racine porte le schéma métier du formulaire.
+// Il peut être un input simple ou une composition de layouts et d'inputs.
+// Ce champ est un `FormField` : `useForm` l’associe aux templates configurés
+// pour exposer le composant Vue, la valeur courante et les opérations du formulaire.
+const { check, component: TheForm, currentValue, dispose, reset } = useForm(
+	useMultiLayout({
+		name: useTextInput({
+			label: "Name",
+			props: {
+				placeholder: "Your name",
+			},
+		}),
+		email: useCheckLayout(
+			useTextInput({
+				label: "Email",
+				props: {
+					placeholder: "yourEmail@mail.com",
+				},
+			}),
+			{
+				dataStructure: DDataStructure.string([DDataStructure.email()]),
+			},
+		),
+		age: useNumberInput({
+			label: "Age",
+			defaultValue: 18,
+		}),
+	}),
+);
+
+// Valeur brute synchronisée avec l'état Vue du formulaire.
+// Ref<{
+//   name: string;
+//   email: string;
+//   age: number;
+// }>
+void currentValue;
+
+// `check` applique les validations déclarées et type la valeur validée.
+// DEither.Error<DetailsError> | DEither.Success<{
+//   name: string;
+//   email: string & Email;
+//   age: number;
+// }>
+const checkedValue = await check();
+
+void checkedValue;
+
+// `reset` restaure les `defaultValue` et les états internes des champs.
+reset();
+
+// `dispose` libère les scopes internes, généralement au démontage.
+dispose();
+
+// `component` est le composant Vue à monter ; le submit reste applicatif.
+void TheForm;
+
+// <TheForm @submit="() => console.log(check())">
+//   <PrimaryButton type="submit" label="Submit" />
+// </TheForm>

package/docs/concepts/03-client/20-form/20-input.ts

@@ -0,0 +1,96 @@
+/**
+ * @title Inputs de formulaire réutilisables
+ *
+ * Création, intégration et validation des champs de saisie d’un formulaire Vue.
+ */
+import { createForm, createInput, useMultiLayout } from "@duplojs/form/vue";
+import { TextInput, templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect, useNumberInput, useTextInput } from "@duplojs/form/vueDesignSystem";
+import { createGridTemplates } from "@duplojs/form/vueGrid";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+const gridTemplates = createGridTemplates({
+	repeat: {
+		addLabel: "Add another item",
+		removeLabel: "Remove this item",
+		addButton: templateFormAddButton,
+		removeButton: templateFormRemoveButton,
+		resetButton: templateFormResetButton,
+	},
+	step: {
+		nextLabel: "Continue",
+		previousLabel: "Back",
+		resetButton: templateFormResetButton,
+		nextButton: templateFormNextButton,
+		previousButton: templateFormPreviousButton,
+	},
+	union: { selectInputKind: templateFormSelect },
+});
+
+const useForm = createForm(
+	gridTemplates.useTemplates(),
+);
+
+// Les inputs du design system sont déjà des briques de formulaire.
+// Ils retournent directement des champs composables dans `useForm`, avec des
+// props inférées depuis leur composant Vue.
+// Leur association composant/input peut aussi servir de référence pour créer
+// les inputs propres à une application.
+const { component: TheForm, currentValue } = useForm(
+	useMultiLayout({
+		name: useTextInput({
+			label: "Name",
+			props: {
+				placeholder: "Your name",
+			},
+		}),
+		age: useNumberInput({
+			label: "Age",
+			defaultValue: 18,
+		}),
+	}),
+);
+
+// Ref<{
+//   name: string;
+//   age: number;
+// }>
+void currentValue;
+void TheForm;
+
+// `createInput` transforme un composant Vue compatible en input de formulaire.
+// Le composant seul ne fournit pas de `FormField` : la fonction obtenue avec
+// `createInput` crée ce champ, composable dans un layout ou directement dans `useForm`.
+// Le contrat minimal du composant est de porter sa valeur avec `modelValue`
+// et `update:modelValue`. Il peut aussi exposer `check`, `reset` ou `dispose`
+// si son comportement interne en a besoin.
+const useCustomTextInput = createInput(
+	TextInput,
+	{
+		defaultValue: "custom text",
+		props: {
+			placeholder: "Your text",
+		},
+	},
+);
+
+// `defaultValue` est obligatoire : c'est la valeur initiale de l'input.
+// Elle peut être une valeur directe ou une fonction.
+// Les paramètres passés à l'utilisation complètent ou remplacent ensuite
+// les valeurs par défaut de `createInput`.
+const { check } = useForm(
+	useCustomTextInput({
+		label: "Email",
+		defaultValue: "",
+		props: {
+			placeholder: "yourEmail@mail.com",
+		},
+		dataStructure: DDataStructure.string([DDataStructure.email()]),
+	}),
+);
+
+// Lors du `check`, la librairie appelle d'abord le `check` exposé par le
+// composant s'il existe, puis applique la `dataStructure` de l'input.
+// DEither.Error<DetailsError> | DEither.Success<string & Email>
+const checkedEmail = await check();
+
+void checkedEmail;