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

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");
+		},
+	);

package/docs/concepts/02-server/20-http/30-routine.ts

@@ -0,0 +1,188 @@
+/**
+ * @title Faire une routine de vérification
+ *
+ * Vérifications dans les flux HTTP, réutilisation des traitements et adaptation de leurs résultats au contexte.
+ */
+import { createPresetChecker, useCheckerBuilder, usePreflightBuilder, useProcessBuilder, useRouteBuilder } from "@duplojs/http";
+import * as DEither from "@duplojs/lang/either";
+import * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DObject from "@duplojs/lang/object";
+import type * as DString from "@duplojs/lang/string";
+
+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 checkToken(
+	token: string,
+): DEither.Success<User> | DEither.Fail;
+
+declare function findOneUser(id: string & DString.Uuid): Promise<DEither.Maybe<User>>;
+
+// Un checker encapsule une opération réutilisable et produit des résultats
+// génériques. Il ne choisit pas leur sens HTTP.
+//
+// Ce sens est donné au point d'utilisation : une route peut interpréter le
+// checker avec `check`, ou une interprétation récurrente peut être nommée
+// avec un preset. Le même checker peut donc servir plusieurs flux sans être
+// dupliqué pour chaque variation d'usage.
+export const userExist = useCheckerBuilder()
+	.handler(
+		async(input: string & DString.Uuid, { output }) => {
+			const result = await findOneUser(input);
+
+			return DEither.matchInformation(result, {
+				some: (user) => output("user.find", user),
+				none: () => output("user.notfound", null),
+			});
+		},
+	);
+
+// `cut` couvre les vérifications propres au flux courant.
+// Il peut interrompre avec `response` ou poursuivre avec `output`.
+useRouteBuilder("POST", "/users/{userId}/confirm-email")
+	.extract({
+		params: {
+			userId: DDataStructure.string([DDataStructure.uuid()]),
+		},
+		body: {
+			email: DDataStructure.string([DDataStructure.email()]),
+		},
+	})
+	.check(
+		userExist,
+		{
+			input: ({ userId }) => userId,
+			result: "user.find",
+			otherwise: ({ response }) => response.notFound("user.notfound"),
+			indexing: "user",
+		},
+	)
+	.cut(
+		({ user, email }, { response, output }) => {
+			if (user.email !== email) {
+				return response.conflict("user.emailConfirmation.mismatch");
+			}
+
+			return output({ confirmedUser: user });
+		},
+	)
+	.handler(
+		({ confirmedUser }, { response }) => response.ok("user.emailConfirmed", confirmedUser),
+	);
+
+// `check` interprète un checker pour un flux donné : input, résultat attendu,
+// réponse sinon, et donnée ajoutée au `floor`.
+useRouteBuilder("GET", "/users/{userId}")
+	.extract({
+		params: {
+			userId: DDataStructure.string([DDataStructure.uuid()]),
+		},
+	})
+	.check(
+		userExist,
+		{
+			input: ({ userId }) => userId,
+			result: "user.find",
+			otherwise: ({ response }) => response.notFound("user.notfound"),
+			indexing: "user",
+		},
+	)
+	.handler(
+		({ user }, { response }) => response.ok("user.find", user),
+	);
+
+// Un preset nomme une interprétation récurrente du checker.
+// Il fixe le sens habituel du résultat tout en laissant le flux fournir
+// son input et son indexation locale.
+export const iWantUserExist = createPresetChecker(
+	userExist,
+	{
+		result: "user.find",
+		otherwise: ({ response }) => response.notFound("user.notfound"),
+	},
+);
+
+// `presetCheck` applique le preset au flux courant.
+useRouteBuilder("GET", "/users/{userId}")
+	.extract({
+		params: {
+			userId: DDataStructure.string([DDataStructure.uuid()]),
+		},
+	})
+	.presetCheck(
+		iWantUserExist.indexing("user"),
+		({ userId }) => userId,
+	)
+	.handler(
+		({ user }, { response }) => response.ok("user.find", user),
+	);
+
+// Un `process` réutilise une séquence complète de steps.
+// Son `floor` reste local : seules les données déclarées avec `exports` sortent.
+export const authenticationProcess = useProcessBuilder()
+	.extract({
+		headers: {
+			authorization: DDataStructure.string(),
+		},
+	})
+	.cut(
+		({ authorization }, { response, output }) => DCommon.pipe(
+			authorization,
+			checkToken,
+			DEither.whenIsRightOtherwise(
+				(user) => output({
+					authenticatedUserId: user.id,
+				}),
+				() => response.unauthorized("token.invalid"),
+			),
+		),
+	)
+	.check(
+		userExist,
+		{
+			input: DObject.getProperty("authenticatedUserId"),
+			result: "user.find",
+			otherwise: ({ response }) => response.notFound("token.user.notfound"),
+			indexing: "user",
+		},
+	)
+	.exports(["user"]);
+
+// `exec` insère l'exécution du process dans le flux courant.
+useRouteBuilder("GET", "/some-action")
+	.exec(
+		authenticationProcess,
+		{
+			imports: ["user"],
+		},
+	)
+	.handler(
+		({ user }, { response }) => response.ok(
+			"some-information.send",
+			user,
+		),
+	);
+
+// Un preflight préfixe un builder par un process récurrent.
+export const useAuthenticatedRouteBuilder = usePreflightBuilder()
+	.exec(
+		authenticationProcess,
+		{
+			imports: ["user"],
+		},
+	)
+	.useRouteBuilder;
+
+useAuthenticatedRouteBuilder("GET", "/some-action")
+	.handler(
+		({ user }, { response }) => response.ok(
+			"some-information.send",
+			user,
+		),
+	);

package/docs/concepts/02-server/20-http/40-jwt.ts

@@ -0,0 +1,149 @@
+/**
+ * @title Définir une politique de gestion de tokens
+ *
+ * Déclaration d'une politique unique pour créer et vérifier une famille de tokens.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import { Cipher, createTokenHandler, Signer } from "@duplojs/json-web-token";
+import * as DChrono from "@duplojs/lang/chrono";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+
+// Le `tokenHandler` est la source de vérité d'une famille de tokens :
+// propriétés standard, payload/header applicatifs, signature et chiffrement.
+const tokenHandler = createTokenHandler({
+	maxAge: DChrono.createTime(15, "minute"),
+	issuer: "my-application",
+	audience: "my-api",
+
+	signer: Signer.createHS256({
+		secret: "my-secret",
+	}),
+
+	customPayloadShape: {
+		userId: DDataStructure.string(),
+		role: DDataStructure.literal("admin"),
+	},
+
+	customHeaderShape: {
+		kid: DDataStructure.optional(
+			DDataStructure.string(),
+		),
+	},
+});
+
+// À la création, les structures du handler typent et valident header/payload.
+const createdTokenResult = await tokenHandler.create(
+	{
+		userId: "42",
+		role: "admin",
+	},
+	{
+		header: {
+			kid: "main",
+		},
+	},
+);
+type _CheckCreatedTokenResult = DCommon.ExpectType<
+	typeof createdTokenResult,
+	DEither.Right<"token-created", string> | DEither.Left<"header-encode-error", DDataStructure.Error> | DEither.Left<"payload-encode-error", DDataStructure.Error>,
+	"strict"
+>;
+
+if (DEither.isRight(createdTokenResult)) {
+	const token = DEither.unwrapRight(createdTokenResult);
+	type _CheckToken = DCommon.ExpectType<typeof token, string, "strict">;
+}
+
+// `verify` applique la même politique et restitue header/payload typés.
+const verifiedTokenResult = await tokenHandler.verify("receive-token");
+type _CheckVerifiedTokenResult = DCommon.ExpectType<typeof verifiedTokenResult,
+	DEither.Left<"token-format", unknown> | DEither.Left<"header-json-error", unknown> | DEither.Left<"header-decode-error", DDataStructure.Error> | DEither.Left<"payload-json-error", unknown> | DEither.Left<"payload-decode-error", DDataStructure.Error> | DEither.Left<"signature-invalid", unknown> | DEither.Left<"issue-invalid", unknown> | DEither.Left<"subject-invalid", unknown> | DEither.Left<"audience-invalid", unknown> | DEither.Left<"expired", unknown> | DEither.Right<"token-verified", {
+		readonly header: {
+			readonly typ: "JWT";
+			readonly alg: "HS256";
+			readonly kid?: string | undefined;
+		};
+		readonly payload: {
+			readonly iss: string;
+			readonly sub: undefined;
+			readonly aud: string;
+			readonly exp: number;
+			readonly iat: number;
+			readonly userId: string;
+			readonly role: "admin";
+		};
+	}>,
+	"strict"
+>;
+
+if (DEither.isRight(verifiedTokenResult)) {
+	const verifiedToken = DEither.unwrapRight(verifiedTokenResult);
+	type _CheckVerifiedToken = DCommon.ExpectType<typeof verifiedToken, {
+		readonly header: {
+			readonly typ: "JWT";
+			readonly alg: "HS256";
+			readonly kid?: string | undefined;
+		};
+		readonly payload: {
+			readonly iss: string;
+			readonly sub: undefined;
+			readonly aud: string;
+			readonly exp: number;
+			readonly iat: number;
+			readonly userId: string;
+			readonly role: "admin";
+		};
+	}, "strict">;
+
+	const userId = verifiedToken.payload.userId;
+	const role = verifiedToken.payload.role;
+	const kid = verifiedToken.header.kid;
+	type _CheckUserId = DCommon.ExpectType<typeof userId, string, "strict">;
+	type _CheckRole = DCommon.ExpectType<typeof role, "admin", "strict">;
+	type _CheckKid = DCommon.ExpectType<typeof kid, string | undefined, "strict">;
+}
+
+// Avec une factory de `Signer` ou `Cipher`, la configuration est fournie
+// au moment de chaque opération.
+const dynamicTokenHandler = createTokenHandler({
+	maxAge: DChrono.createTime(15, "minute"),
+
+	signer: Signer.createHS256,
+	cipher: Cipher.createRSAOAEP,
+
+	customPayloadShape: {
+		userId: DDataStructure.string(),
+	},
+});
+
+const dynamicTokenResult = await dynamicTokenHandler.create(
+	{
+		userId: "42",
+	},
+	{
+		signer: {
+			secret: "my-secret",
+		},
+		cipher: {
+			privateKey: "private-key",
+			publicKey: "public-key",
+		},
+	},
+);
+
+const dynamicVerifiedTokenResult = await dynamicTokenHandler.verify(
+	"receive-token",
+	{
+		signer: {
+			secret: "my-secret",
+		},
+		cipher: {
+			privateKey: "private-key",
+			publicKey: "public-key",
+		},
+	},
+);
+
+// `Signer` et `Cipher` encapsulent signature et chiffrement.
+// Les implémentations fournies peuvent être remplacées par des mécanismes personnalisés.

package/docs/concepts/02-server/20-http/50-open-api.ts

@@ -0,0 +1,44 @@
+/**
+ * @title Générer la documentation OpenAPI d'une API HTTP.
+ *
+ * Décrire les réponses des routes et exposer leur documentation.
+ */
+import { createHub, useRouteBuilder } from "@duplojs/http";
+import { OpenApiEndpointContractMetadata, openApiGeneratorPlugin } from "@duplojs/http/openApiGenerator";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+// Le plugin reprend les entrées déclarées dans les extractions. Décrire les
+// réponses à documenter avec `OpenApiEndpointContractMetadata` sur les étapes
+// concernées. Ces métadonnées servent à la documentation ; elles ne valident
+// pas les réponses envoyées par la route.
+const helloRoute = useRouteBuilder("GET", "/hello")
+	.extract(
+		{
+			query: { name: DDataStructure.string() },
+		},
+		({ response }) => response.badRequest("hello.invalid"),
+		OpenApiEndpointContractMetadata({
+			code: "400",
+			information: "hello.invalid",
+		}),
+	)
+	.handler(
+		({ name }, { response }) => response.ok("hello.received", { name }),
+		OpenApiEndpointContractMetadata({
+			code: "200",
+			information: "hello.received",
+			body: DDataStructure.object({ name: DDataStructure.string() }),
+		}),
+	);
+
+// Le plugin collecte les entrées des extractions et les métadonnées de sortie
+// des routes, de leurs étapes et de leurs processus, y compris le preflight.
+// Sans métadonnées de sortie, une réponse de handler n'est pas documentée.
+// Une extraction sans métadonnée locale documente par défaut 422 / extract-error.
+// Si le refus par défaut du Hub change, adapter aussi `defaultExtractMetadata`
+// dans les options du plugin ; un refus local se décrit comme ci-dessus.
+export const documentedHub = createHub({ environment: "DEV" })
+	.register(helloRoute)
+	.plug(openApiGeneratorPlugin({ routePath: "/swagger" }));
+
+// Le connecteur déclenche la génération en environnement DEV ou BUILD.

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

@@ -0,0 +1,3 @@
+## HTTP
+
+Développement d’API HTTP avec DuploJS, de la définition des routes au démarrage du serveur.

package/docs/concepts/02-server/30-environment/10-platform.ts

@@ -0,0 +1,47 @@
+/**
+ * @title Capacités de plateforme
+ *
+ * Utilisation des abstractions communes et des connecteurs pour garder le code
+ * applicatif indépendant du runtime.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DEither from "@duplojs/lang/either";
+import type * as DPath from "@duplojs/lang/path";
+import * as DSCommon from "@duplojs/server/common";
+import * as DSFile from "@duplojs/server/file";
+import { createHub } from "@duplojs/http";
+import { createHttpServer } from "@duplojs/http/node";
+
+// Les capacités proches entre runtimes sont exposées par une même API.
+const resourcePath: string & DPath.Path = DCommon.cast("/resources/config.json");
+
+const writeJsonResult = await DSFile.writeJsonFile(resourcePath, { version: 1.0 });
+type _CheckWriteJsonResult = DCommon.ExpectType<typeof writeJsonResult, DSFile.WriteJsonFileResult, "strict">;
+
+const currentWorkingDirectoryResult = DSCommon.getCurrentWorkDirectory();
+type _CheckCurrentWorkingDirectoryResultLine21 = DCommon.ExpectType<
+	typeof currentWorkingDirectoryResult,
+	DEither.Error<unknown> | DEither.Success<string & DPath.Absolute>,
+	"strict"
+>;
+
+const processArguments = DSCommon.getProcessArguments();
+type _CheckProcessArgumentsLine24 = DCommon.ExpectType<
+	typeof processArguments,
+	string[],
+	"strict"
+>;
+
+const hub = createHub({
+	environment: "DEV",
+});
+
+// Les capacités plus liées au runtime passent par un connecteur.
+// Ici, le hub HTTP reste générique et le démarrage utilise le connecteur Node.
+await createHttpServer(
+	hub,
+	{
+		host: "localhost",
+		port: 1506,
+	},
+);

package/docs/concepts/02-server/30-environment/20-variable.ts

@@ -0,0 +1,47 @@
+/**
+ * @title Manipuler les variables d'environnement
+ *
+ * Chargement de sources d'environnement, validation par `DataStructure` et
+ * obtention d'une configuration typée.
+ */
+import * as DSCommon from "@duplojs/server/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DCommon from "@duplojs/lang/common";
+import type * as DNumber from "@duplojs/lang/number";
+import type * as DString from "@duplojs/lang/string";
+
+// `environmentVariableOrThrow` est adaptée au démarrage d'une application :
+// une configuration invalide interrompt directement l'initialisation.
+const envs = await DSCommon.environmentVariableOrThrow(
+	{
+		host: DDataStructure.literal(["0.0.0.0", "127.0.0.1", "localhost"]),
+		port: DDataStructure.number([DDataStructure.positive()]),
+		name: DDataStructure.string(),
+		ENVIRONMENT: DDataStructure.literal(["DEV", "PROD"]),
+		DATABASE_URL: DDataStructure.string([DDataStructure.url()]),
+	},
+	{
+		// Fichiers `.env` à lire en plus des variables déjà présentes
+		// dans l'environnement du runtime.
+		includedEnvironmentFiles: [DCommon.infer(".env"), DCommon.infer(".env.local")],
+
+		// `false` garde la priorité aux valeurs déjà présentes.
+		// `true` autorise les fichiers à remplacer ces valeurs.
+		override: false,
+
+		// `true` renvoie la configuration validée sans réécrire
+		// `process.env` ou `Deno.env`.
+		justRead: true,
+	},
+);
+type _CheckEnvs = DCommon.ExpectType<
+	typeof envs,
+	{
+		readonly host: "0.0.0.0" | "127.0.0.1" | "localhost";
+		readonly name: string;
+		readonly port: number & DNumber.Positive;
+		readonly ENVIRONMENT: "DEV" | "PROD";
+		readonly DATABASE_URL: string & DString.Url;
+	},
+	"strict"
+>;

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

@@ -0,0 +1,3 @@
+## Environnement
+
+Exploitation des capacités de l’environnement serveur et adaptation aux API des différentes plateformes d’exécution.