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

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

@@ -0,0 +1,195 @@
+/**
+ * @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 { ResponseContract, 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: ResponseContract.notFound("user.notfound"),
+			indexing: "user",
+		},
+	)
+	.cut(
+		ResponseContract.conflict("user.emailConfirmation.mismatch"),
+		({ user, email }, { response, output }) => {
+			if (user.email !== email) {
+				return response("user.emailConfirmation.mismatch");
+			}
+
+			return output({ confirmedUser: user });
+		},
+	)
+	.handler(
+		ResponseContract.ok("user.emailConfirmed", userStructure),
+		({ confirmedUser }, { response }) => response("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: ResponseContract.notFound("user.notfound"),
+			indexing: "user",
+		},
+	)
+	.handler(
+		ResponseContract.ok("user.find", userStructure),
+		({ user }, { response }) => response("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: ResponseContract.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(
+		ResponseContract.ok("user.find", userStructure),
+		({ user }, { response }) => response("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(
+		ResponseContract.unauthorized("token.invalid"),
+		({ authorization }, { response, output }) => DCommon.pipe(
+			authorization,
+			checkToken,
+			DEither.whenIsRightOtherwise(
+				(user) => output({
+					authenticatedUserId: user.id,
+				}),
+				() => response("token.invalid"),
+			),
+		),
+	)
+	.check(
+		userExist,
+		{
+			input: DObject.getProperty("authenticatedUserId"),
+			result: "user.find",
+			otherwise: ResponseContract.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(
+		ResponseContract.ok("some-information.send", userStructure),
+		({ user }, { response }) => response(
+			"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(
+		ResponseContract.ok("some-information.send", userStructure),
+		({ user }, { response }) => response(
+			"some-information.send",
+			user,
+		),
+	);

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

@@ -0,0 +1,137 @@
+/**
+ * @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 { 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.
+// | Right<"token-created", string>
+// | Left<"header-encode-error", Error>
+// | Left<"payload-encode-error", Error>;
+const createdTokenResult = await tokenHandler.create(
+	{
+		userId: "42",
+		role: "admin",
+	},
+	{
+		header: {
+			kid: "main",
+		},
+	},
+);
+
+if (DEither.isRight(createdTokenResult)) {
+	// string
+	const token = DEither.unwrapRight(createdTokenResult);
+}
+
+// `verify` applique la même politique et restitue header/payload typés.
+// | Left<"token-format", unknown>
+// | Left<"header-json-error", unknown>
+// | Left<"header-decode-error", Error>
+// | Left<"payload-json-error", unknown>
+// | Left<"payload-decode-error", Error>
+// | Left<"signature-invalid", unknown>
+// | Left<"issue-invalid", unknown>
+// | Left<"subject-invalid", unknown>
+// | Left<"audience-invalid", unknown>
+// | Left<"expired", unknown>
+// | 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";
+//    };
+//  }
+// >;
+const verifiedTokenResult = await tokenHandler.verify("receive-token");
+
+if (DEither.isRight(verifiedTokenResult)) {
+	const { payload, header } = DEither.unwrapRight(verifiedTokenResult);
+
+	const userId = payload.userId;
+	const role = payload.role;
+	const kid = header.kid;
+}
+
+// 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-codegen.ts

@@ -0,0 +1,29 @@
+/**
+ * @title Comment partager des ressources
+ *
+ * Génération du typage des routes et des `DataStructure` pour partager un contrat statique.
+ */
+import { createHub, routeStore } from "@duplojs/http";
+import { codeGeneratorPlugin } from "@duplojs/http/codeGenerator";
+import * as DCommon from "@duplojs/lang/common";
+
+const hub = createHub({ environment: "BUILD" })
+	.register(routeStore.getAll())
+	.plug(
+		codeGeneratorPlugin({
+			// Génère le typage des routes.
+			outputFile: DCommon.infer("types.d.ts"),
+
+			// Génère les `DataStructure` utilisées par les routes.
+			generateStructure: {
+				outputFolder: DCommon.infer("dataStructures"),
+			},
+		}),
+	);
+
+// La génération produit des fichiers autonomes à distribuer aux consommateurs.
+// Les `DataStructure` peuvent être générées depuis les routes ou sélectionnées explicitement.
+
+// `codeGeneratorPlugin` exécute sa génération sur le hook `beforeStartServer`.
+// Le `Hub` doit donc disposer d'un connecteur HTTP.
+// En environnement `BUILD`, le cycle s'exécute sans démarrer le serveur HTTP.

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

@@ -0,0 +1,3 @@
+## HTTP
+
+Interfaces HTTP côté serveur : réception et validation des requêtes, orchestration des traitements et contrats de réponse typés partageables avec les clients.

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

@@ -0,0 +1,38 @@
+/**
+ * @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 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");
+
+// DEither.Right<file-system-write-json-file, void> | DEither.Left<...> | ...
+const writeJsonResult = await DSFile.writeJsonFile(resourcePath, { version: 1.0 });
+
+// DEither.Error<unknown> | DEither.Success<string & DPath.Absolute>
+const currentWorkingDirectoryResult = DSCommon.getCurrentWorkDirectory();
+
+// string[]
+const processArguments = DSCommon.getProcessArguments();
+
+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,41 @@
+/**
+ * @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";
+
+// `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,
+	},
+);
+// {
+//     readonly host: "0.0.0.0" | "127.0.0.1" | "localhost";
+//     readonly name: string;
+//     readonly port: number & Positive;
+//     readonly ENVIRONMENT: "DEV" | "PROD";
+//     readonly DATABASE_URL: string & Url;
+// }

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.

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,64 @@
+/**
+ * @title Initialiser un client HTTP
+ *
+ * Création d'un client à partir du contrat statique des routes, configuration
+ * globale et conservation du typage des requêtes et réponses exposées par le
+ * serveur.
+ */
+import { createHttpClient } from "@duplojs/http/client";
+
+// Exemple réduit du contrat produit par `codeGeneratorPlugin`.
+export interface Routes {
+	method: "GET";
+	path: "/hello-world";
+	query: {
+		name: string;
+	};
+	responses: {
+		code: "422";
+		information: "extract-error";
+		body?: undefined;
+	} | {
+		code: "200";
+		information: "helloWorld.send";
+		body: string;
+	};
+}
+
+// `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(
+		"/hello-world",
+		{
+			query: {
+				name: "William",
+			},
+		},
+	)
+	.iWantInformationOrThrow("helloWorld.send");
+
+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",
+});