@duplojs/agents-kit 0.1.0-beta.3 → 0.1.0-beta.6

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

@@ -3,6 +3,7 @@
  *
  * 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";
@@ -32,9 +33,6 @@ const tokenHandler = createTokenHandler({
 });
 
 // À 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",
@@ -46,50 +44,64 @@ const createdTokenResult = await tokenHandler.create(
 		},
 	},
 );
+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)) {
-	// string
 	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.
-// | 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");
+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 { payload, header } = DEither.unwrapRight(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 = payload.userId;
-	const role = payload.role;
-	const kid = header.kid;
+	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

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

@@ -1,3 +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.
+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

@@ -5,6 +5,7 @@
  * 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";
@@ -14,14 +15,22 @@ 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 });
+type _CheckWriteJsonResult = DCommon.ExpectType<typeof writeJsonResult, DSFile.WriteJsonFileResult, "strict">;
 
-// DEither.Error<unknown> | DEither.Success<string & DPath.Absolute>
 const currentWorkingDirectoryResult = DSCommon.getCurrentWorkDirectory();
+type _CheckCurrentWorkingDirectoryResultLine21 = DCommon.ExpectType<
+	typeof currentWorkingDirectoryResult,
+	DEither.Error<unknown> | DEither.Success<string & DPath.Absolute>,
+	"strict"
+>;
 
-// string[]
 const processArguments = DSCommon.getProcessArguments();
+type _CheckProcessArgumentsLine24 = DCommon.ExpectType<
+	typeof processArguments,
+	string[],
+	"strict"
+>;
 
 const hub = createHub({
 	environment: "DEV",

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

@@ -7,6 +7,8 @@
 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.
@@ -32,10 +34,14 @@ const envs = await DSCommon.environmentVariableOrThrow(
 		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;
-// }
+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/03-client/10-http/10-init.ts

@@ -1,29 +1,16 @@
 /**
  * @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.
+ * 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";
 
-// 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;
-	};
-}
+// 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.
@@ -42,14 +29,15 @@ client.addDefaultHeader(
 // Le contrat limite les paths, paramètres et réponses disponibles.
 const response = await client
 	.get(
-		"/hello-world",
+		"/users",
 		{
 			query: {
-				name: "William",
+				page: DCommon.cast(1),
+				quantityPerPage: DCommon.cast(5),
 			},
 		},
 	)
-	.iWantInformationOrThrow("helloWorld.send");
+	.iWantInformationOrThrow("users.findMany");
 
 void response.body;
 void response.code;

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

@@ -9,74 +9,74 @@ 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;
+	readonly method: "POST";
+	readonly path: "/users";
+	readonly body: {
+		readonly username: string;
+		readonly age: number;
 	};
-	responses: {
-		code: "422";
-		information: "extract-error";
-		body?: undefined;
+	readonly responses: {
+		readonly code: "422";
+		readonly information: "extract-error";
+		readonly body: Error;
 	} | {
-		code: "204";
-		information: "user.created";
-		body?: undefined;
+		readonly code: "204";
+		readonly information: "user.created";
+		readonly body: undefined;
 	};
 } | {
-	method: "POST";
-	path: "/users/{userId}/posts";
-	params: {
-		userId: number;
+	readonly method: "POST";
+	readonly path: "/users/{userId}/posts";
+	readonly params: {
+		readonly userId: number;
 	};
-	body: {
-		title: string;
-		content: string;
+	readonly body: {
+		readonly title: string;
+		readonly content: string;
 	};
-	responses: {
-		code: "422";
-		information: "extract-error";
-		body?: undefined;
+	readonly responses: {
+		readonly code: "422";
+		readonly information: "extract-error";
+		readonly body: Error;
 	} | {
-		code: "204";
-		information: "post.created";
-		body?: undefined;
+		readonly code: "204";
+		readonly information: "post.created";
+		readonly body: undefined;
 	};
 } | {
-	method: "POST";
-	path: "/documents";
-	body: DCommon.TheFormData<{
-		bool: boolean;
-		myFile: readonly File[] & DArray.LengthEqual<1>;
-		name: string;
+	readonly method: "POST";
+	readonly path: "/documents";
+	readonly body: DCommon.TheFormData<{
+		readonly bool: boolean;
+		readonly myFile: readonly File[] & DArray.LengthEqual<1>;
+		readonly name: string;
 	}>;
-	responses: {
-		code: "422";
-		information: "extract-error";
-		body?: undefined;
+	readonly responses: {
+		readonly code: "422";
+		readonly information: "extract-error";
+		readonly body: Error;
 	} | {
-		code: "204";
-		information: "file.receive";
-		body?: undefined;
+		readonly code: "204";
+		readonly information: "file.receive";
+		readonly body: undefined;
 	};
 } | {
-	method: "GET";
-	path: "/posts";
-	query: {
-		page: number;
+	readonly method: "GET";
+	readonly path: "/posts";
+	readonly query: {
+		readonly page: number;
 	};
-	responses: {
-		code: "422";
-		information: "extract-error";
-		body?: undefined;
+	readonly responses: {
+		readonly code: "422";
+		readonly information: "extract-error";
+		readonly body: Error;
 	} | {
-		code: "200";
-		information: "post.findMany";
-		body: {
-			title: string;
-			content: string;
-			authorId: number;
+		readonly code: "200";
+		readonly information: "post.findMany";
+		readonly body: readonly {
+			readonly title: string;
+			readonly content: string;
+			readonly authorId: number;
 		}[];
 	};
 };
@@ -138,18 +138,22 @@ await client
 	.whenInformation(
 		"post.findMany",
 		({ body }) => {
-			// body: {
-			//   title: string;
-			//   content: string;
-			//   authorId: number;
-			// }[]
+			type _CheckPostBody = DCommon.ExpectType<
+				typeof body,
+				readonly {
+					readonly title: string;
+					readonly content: string;
+					readonly authorId: number;
+				}[],
+				"strict"
+			>;
 			void body;
 		},
 	)
 	.whenCode(
 		"422",
 		({ information }) => {
-			// information: "extract-error"
+			type _CheckErrorInformation = DCommon.ExpectType<typeof information, "extract-error", "strict">;
 			void information;
 		},
 	);
@@ -173,8 +177,7 @@ const maybeCreatedPost = await client
 
 if (DEither.isRight(maybeCreatedPost)) {
 	const response = DEither.unwrapRight(maybeCreatedPost);
-
-	// information: "post.created"
+	type _CheckCreatedInformation = DCommon.ExpectType<typeof response.information, "post.created", "strict">;
 	void response.information;
 }
 
@@ -193,6 +196,11 @@ const createdPostResponse = await client
 		},
 	)
 	.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
@@ -208,8 +216,11 @@ const maybeExpectedResponse = await client
 
 if (DEither.isRight(maybeExpectedResponse)) {
 	const response = DEither.unwrapRight(maybeExpectedResponse);
-
-	// information: "post.findMany" | "extract-error"
+	type _CheckExpectedInformation = DCommon.ExpectType<
+		typeof response.information,
+		"post.findMany" | "extract-error",
+		"strict"
+	>;
 	void response.information;
 }
 
@@ -230,12 +241,11 @@ const maybePosts = await client
 
 if (DEither.isRight(maybePosts)) {
 	const response = DEither.unwrapRight(maybePosts);
-
-	// body: {
-	//   title: string;
-	//   content: string;
-	//   authorId: number;
-	// }[]
+	type _CheckPostsBody = DCommon.ExpectType<typeof response.body, readonly {
+		readonly title: string;
+		readonly content: string;
+		readonly authorId: number;
+	}[], "strict">;
 	void response.body;
 }
 

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

@@ -6,35 +6,35 @@
 import { createHttpClient } from "@duplojs/http/client";
 
 export type Routes = {
-	method: "GET";
-	path: "/profile";
-	responses: {
-		code: "401";
-		information: "auth.required";
-		body?: undefined;
+	readonly method: "GET";
+	readonly path: "/profile";
+	readonly responses: {
+		readonly code: "401";
+		readonly information: "auth.required";
+		readonly body: undefined;
 	} | {
-		code: "200";
-		information: "profile.found";
-		body: {
-			name: string;
-			email: string;
+		readonly code: "200";
+		readonly information: "profile.found";
+		readonly body: {
+			readonly name: string;
+			readonly email: string;
 		};
 	};
 } | {
-	method: "POST";
-	path: "/users";
-	body: {
-		username: string;
-		age: number;
+	readonly method: "POST";
+	readonly path: "/users";
+	readonly body: {
+		readonly username: string;
+		readonly age: number;
 	};
-	responses: {
-		code: "422";
-		information: "extract-error";
-		body?: undefined;
+	readonly responses: {
+		readonly code: "422";
+		readonly information: "extract-error";
+		readonly body: Error;
 	} | {
-		code: "204";
-		information: "user.created";
-		body?: undefined;
+		readonly code: "204";
+		readonly information: "user.created";
+		readonly body: undefined;
 	};
 };
 

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

@@ -3,10 +3,13 @@
  *
  * Initialisation et cycle de vie d’un formulaire Vue typé.
  */
-import { createForm, useCheckLayout, useMultiLayout } from "@duplojs/form/vue";
+import { createForm, useCheckLayout, useMultiLayout, type DetailsError } 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";
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DEither from "@duplojs/lang/either";
+import type * as DString from "@duplojs/lang/string";
 
 // `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,
@@ -64,20 +67,24 @@ const { check, component: TheForm, currentValue, dispose, reset } = useForm(
 );
 
 // Valeur brute synchronisée avec l'état Vue du formulaire.
-// Ref<{
-//   name: string;
-//   email: string;
-//   age: number;
-// }>
+type _CheckCurrentValue = DCommon.ExpectType<
+	typeof currentValue.value,
+	{
+		name: string;
+		email: string;
+		age: number;
+	},
+	"strict"
+>;
 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();
+type _CheckValue = DCommon.ExpectType<typeof checkedValue, DEither.Error<DetailsError> | DEither.Success<{
+	name: string;
+	email: string & DString.Email;
+	age: number;
+}>, "strict">;
 
 void checkedValue;
 
@@ -89,7 +96,3 @@ 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

@@ -3,10 +3,13 @@
  *
  * Création, intégration et validation des champs de saisie d’un formulaire Vue.
  */
-import { createForm, createInput, useMultiLayout } from "@duplojs/form/vue";
+import { createForm, createInput, type DetailsError, 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";
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DEither from "@duplojs/lang/either";
+import type * as DString from "@duplojs/lang/string";
 
 const gridTemplates = createGridTemplates({
 	repeat: {
@@ -50,10 +53,10 @@ const { component: TheForm, currentValue } = useForm(
 	}),
 );
 
-// Ref<{
-//   name: string;
-//   age: number;
-// }>
+type _CheckCurrentValue = DCommon.ExpectType<typeof currentValue.value, {
+	name: string;
+	age: number;
+}, "strict">;
 void currentValue;
 void TheForm;
 
@@ -90,7 +93,11 @@ const { check } = useForm(
 
 // 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();
+type _CheckCheckedEmail = DCommon.ExpectType<
+	typeof checkedEmail,
+	DEither.Error<DetailsError> | DEither.Success<string & DString.Email>,
+	"strict"
+>;
 
 void checkedEmail;