@kizunajs/openapi 2.0.0-beta.2 → 2.0.0-beta.21

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { z } from "zod";
-import { createPlugin } from "kizunajs/plugin";
+import { RoutePathSchema, definePlugin, route } from "kizunajs/plugin";
+import { cacheHeaders, defineGenerator, deprecationHeaders, globalRegistrySchemas, isBinarySchema, isFileSchema, isNamedStream, isStreamResponse, isVoidSchema, parsePath, readDef, readDiscriminatedUnion, readDiscriminatorLiteral, readMeta, readMetaId, readObjectShape, resolveResponseBody, resolveResponseCache, resolveResponseContentType, resolveResponseEtag, resolveResponseHeaders, streamContentType, streamMode, walkApi } from "kizunajs/generator";
 import { contractOf, rawResponse } from "kizunajs/adapter";
 import { stringify } from "yaml";
-import { cacheHeaders, createGenerator, deprecationHeaders, globalRegistrySchemas, isBinarySchema, isFileSchema, isNamedStream, isStreamResponse, isVoidSchema, parsePath, readDiscriminatedUnion, readDiscriminatorLiteral, readMeta, readMetaId, readObjectShape, resolveResponseBody, resolveResponseCache, resolveResponseContentType, resolveResponseEtag, resolveResponseHeaders, streamContentType, streamMode } from "kizunajs/generator";
 import { getStatusText } from "kizunajs";
 //#region src/generator.ts
 const streamJsonSchema = (response, toJsonSchema) => {
@@ -79,12 +79,25 @@ const buildDiscriminatorBlock = (propertyName, options) => {
 	} : { propertyName };
 };
 /**
-* kizuna's metadata widens JSON Schema: `deprecated` may carry a message and
-* `example` holds one value or several. Emit `deprecated: true` and an
-* `examples` array; the message stays in outputs with a place for it, like
-* Swift's `@available`.
+* What the wire carries for a type JSON Schema has no keyword for, which
+* `unrepresentable: 'any'` would otherwise leave as an empty schema.
 */
-const normalizeMeta = ({ jsonSchema }) => {
+const JSON_ENCODING = {
+	date: {
+		type: "string",
+		format: "date-time"
+	},
+	bigint: { type: "string" }
+};
+/**
+* kizuna's metadata widens JSON Schema: `deprecated` may carry a message,
+* `example` holds one value or several, and `brand` has no keyword. Emit
+* `deprecated: true`, an `examples` array and `x-kizuna-brand`; the message
+* stays in outputs with a place for it, like Swift's `@available`.
+*/
+const normalizeMeta = ({ zodSchema, jsonSchema }) => {
+	const encoding = JSON_ENCODING[readDef(zodSchema).type ?? ""];
+	if (encoding && Object.keys(jsonSchema).length === 0) Object.assign(jsonSchema, encoding);
 	if (typeof jsonSchema.deprecated === "string") jsonSchema.deprecated = true;
 	if ("example" in jsonSchema) {
 		const given = Array.isArray(jsonSchema.example) ? jsonSchema.example : [jsonSchema.example];
@@ -92,6 +105,10 @@ const normalizeMeta = ({ jsonSchema }) => {
 		jsonSchema.examples = [...given, ...declared];
 		delete jsonSchema.example;
 	}
+	if ("brand" in jsonSchema) {
+		jsonSchema["x-kizuna-brand"] = jsonSchema.brand;
+		delete jsonSchema.brand;
+	}
 };
 const toJsonSchema = (schema, io = "output") => {
 	const id = readMetaId(schema);
@@ -148,10 +165,11 @@ const deriveHeadOperation = (getOperation) => {
 	for (const response of Object.values(operation.responses)) delete response.content;
 	return operation;
 };
-const openApiGenerator = createGenerator((options, api) => {
+const openApiWalk = (options, api) => {
 	const paths = {};
 	return {
-		processRoute({ routeKey, route, routeTags, deprecated }) {
+		processRoute({ routeKey, route, routeGroups, deprecated, hidden }) {
+			if (hidden && options.includeHidden !== true) return;
 			const openApiPath = convertPath(route.path);
 			const method = route.method.toLowerCase();
 			let operation = {
@@ -161,9 +179,8 @@ const openApiGenerator = createGenerator((options, api) => {
 			};
 			if (options.setOperationId) operation.operationId = options.setOperationId === "concatenated-path" ? routeKey : routeKey.slice(routeKey.lastIndexOf(".") + 1);
 			if (deprecated) operation.deprecated = true;
-			const resolveTagTitle = (key) => options.tagLookup?.get(key)?.title ?? key;
-			const mergedTags = [...new Set([...routeTags, ...route.tags ?? []].map(resolveTagTitle))];
-			if (mergedTags.length > 0) operation.tags = mergedTags;
+			const tags = [...new Set(routeGroups.flatMap((group) => options.groupTags?.get(group) ?? [group]))];
+			if (tags.length > 0) operation.tags = tags;
 			if (route.security && route.security.length > 0) {
 				const emittedSecurity = toOpenApiSecurity(route.security, api);
 				if (emittedSecurity.length > 0) operation.security = emittedSecurity;
@@ -206,6 +223,15 @@ const openApiGenerator = createGenerator((options, api) => {
 					schema: valueSchema
 				});
 			}
+			const streamsEvents = Object.values(route.responses).some((response) => isStreamResponse(response) && streamContentType(response) === "text/event-stream");
+			const declaresLastEventId = parameters.some((parameter) => parameter.in === "header" && parameter.name.toLowerCase() === "last-event-id");
+			if (streamsEvents && !declaresLastEventId) parameters.push({
+				name: "Last-Event-ID",
+				in: "header",
+				required: false,
+				description: "The id of the last event received, to resume a dropped stream after it",
+				schema: { type: "string" }
+			});
 			if (parameters.length > 0) operation.parameters = parameters;
 			if (route.body && !isVoidSchema(route.body)) {
 				const contentType = route.contentType ?? "application/json";
@@ -365,7 +391,7 @@ const openApiGenerator = createGenerator((options, api) => {
 			return renderer;
 		}
 	};
-});
+};
 /**
 * The permissions a route requires, as `x-kizuna-requires`: what is acted on,
 * mapped to the verbs the caller has to hold.
@@ -424,19 +450,29 @@ const buildSecuritySchemes = (api) => {
 	}
 	return Object.keys(result).length > 0 ? result : void 0;
 };
-const buildTagLookup = (api) => new Map(Object.entries(api.tags?.tags ?? {}));
 /**
-* Document-level tag definitions from the api's declared tag set, one
-* entry per declared tag, in declaration order, named by its `title`.
+* The tag for each group path: its top-level group's title, since OpenAPI 3.1.0
+* has no nested tags.
+*/
+const buildGroupTags = (api) => {
+	const groups = api.groups?.groups;
+	const tags = /* @__PURE__ */ new Map();
+	if (!groups) return tags;
+	for (const group of groups.values()) tags.set(group.path, [groups.get(group.lineage[0]).title]);
+	return tags;
+};
+/**
+* One tag per top-level group.
 */
 const tagsFromApi = (api) => {
-	const declared = api.tags?.tags;
-	if (!declared) return [];
+	const groups = api.groups?.groups;
+	if (!groups) return [];
 	const tags = [];
-	for (const options of Object.values(declared)) {
-		const entry = { name: options.title };
-		if (options.description) entry.description = options.description;
-		if (options.externalDocs) entry.externalDocs = options.externalDocs;
+	for (const group of groups.values()) {
+		if (group.lineage.length > 1) continue;
+		const entry = { name: group.title };
+		if (group.description) entry.description = group.description;
+		if (group.externalDocs) entry.externalDocs = group.externalDocs;
 		tags.push(entry);
 	}
 	return tags;
@@ -445,17 +481,17 @@ const tagsFromApi = (api) => {
 * So a build step does not restate the options and drift from what is served.
 */
 const optionsFromInstalledPlugin = (api) => {
-	for (const declaration of Object.values(api.plugins ?? {})) if (declaration.slug === "openApi") return declaration.props;
+	for (const plugin of Object.values(api.plugins ?? {})) if (plugin.definedSlug === "openApi") return plugin.options;
 	throw new Error("generateOpenApi reads its options from the config. Name `openApiPlugin` under `plugins` with the API's `info`.");
 };
 /**
 * Render from options held directly, for the plugin's own routes.
 */
 function renderOpenApi(api, options) {
-	const renderer = openApiGenerator(api, {
+	const renderer = walkApi(api, openApiWalk({
 		...options,
-		tagLookup: buildTagLookup(api)
-	});
+		groupTags: buildGroupTags(api)
+	}, api));
 	const tags = tagsFromApi(api);
 	if (tags.length > 0) renderer("json").tags = tags;
 	return renderer;
@@ -547,22 +583,6 @@ const renderDocsHtml = (options) => {
 	});
 };
 //#endregion
-//#region src/document-target.ts
-/**
-* An OpenAPI document target for `kizuna.config.ts`.
-*
-* @example
-* openApiDocument({ output: './openapi.yaml' });
-*/
-const openApiDocument = ({ output, ...overrides }) => ({
-	kind: "openapi",
-	output,
-	generate: (contract) => {
-		const render = generateOpenApi(contract, overrides);
-		return output.endsWith(".json") ? `${JSON.stringify(render("json"), null, 4)}\n` : render("yaml");
-	}
-});
-//#endregion
 //#region src/server.ts
 const HTML = "text/html; charset=utf-8";
 const JSON_TYPE = "application/json";
@@ -572,23 +592,43 @@ const sent = (body, contentType) => new Response(body, {
 	headers: { "content-type": contentType }
 });
 /**
-* What answers the routes `openApiPlugin` declares: the reference UI, and the
-* document itself where the declaration published it.
+* The routes `openApiPlugin` serves: the reference UI, and the document itself
+* where the options publish it. The document is rendered on the first request,
+* once the api it describes has assembled.
 */
-const openApiServe = (props, api) => {
-	const spec = renderOpenApi(contractOf(api), props);
-	return { router: {
-		page: () => rawResponse(sent(renderDocsHtml({
-			specUrl: props.jsonPath,
-			specContent: props.jsonPath === void 0 ? spec("json") : void 0,
-			provider: props.provider,
-			pageTitle: props.pageTitle ?? spec("json").info.title,
-			cdnUrl: props.cdnUrl,
-			configuration: props.configuration
-		}), HTML)),
-		json: () => rawResponse(sent(JSON.stringify(spec("json")), JSON_TYPE)),
-		yaml: () => rawResponse(sent(spec("yaml"), YAML))
-	} };
+const openApiRoutes = (props, api) => {
+	let renderer;
+	const spec = ((format) => {
+		renderer ??= renderOpenApi(contractOf(api), props);
+		return renderer(format);
+	});
+	const routes = {};
+	if (props.docsPath !== void 0) routes.page = route({
+		method: "GET",
+		path: props.docsPath,
+		summary: "API reference",
+		responses: { 200: z.string() }
+	}).handler(() => rawResponse(sent(renderDocsHtml({
+		specUrl: props.jsonPath,
+		specContent: props.jsonPath === void 0 ? spec("json") : void 0,
+		provider: props.provider,
+		pageTitle: props.pageTitle ?? spec("json").info.title,
+		cdnUrl: props.cdnUrl,
+		configuration: props.configuration
+	}), HTML)));
+	if (props.jsonPath !== void 0) routes.json = route({
+		method: "GET",
+		path: props.jsonPath,
+		summary: "OpenAPI document",
+		responses: { 200: z.unknown() }
+	}).handler(() => rawResponse(sent(JSON.stringify(spec("json")), JSON_TYPE)));
+	if (props.yamlPath !== void 0) routes.yaml = route({
+		method: "GET",
+		path: props.yamlPath,
+		summary: "OpenAPI document, as YAML",
+		responses: { 200: z.string() }
+	}).handler(() => rawResponse(sent(spec("yaml"), YAML)));
+	return routes;
 };
 /**
 * Serve an API reference UI for the OpenAPI document, and the document itself
@@ -607,38 +647,117 @@ const openApiServe = (props, api) => {
 *                 title: 'My API',
 *                 version: '1.0.0',
 *             },
+*             docsPath: '/docs',
 *         }),
 *     ],
 * });
 * ```
 */
-const declare = (slug, props) => createPlugin({
-	slug,
-	routes: {
-		...props.docsPath === void 0 ? {} : { page: {
-			method: "GET",
-			path: props.docsPath,
-			summary: "API reference",
-			responses: { 200: z.string() }
-		} },
-		...props.jsonPath === void 0 ? {} : { json: {
-			method: "GET",
-			path: props.jsonPath,
-			summary: "OpenAPI document",
-			responses: { 200: z.unknown() }
-		} },
-		...props.yamlPath === void 0 ? {} : { yaml: {
-			method: "GET",
-			path: props.yamlPath,
-			summary: "OpenAPI document, as YAML",
-			responses: { 200: z.string() }
-		} }
-	},
-	props,
-	serve: (pluginProps, api) => openApiServe(pluginProps, api)
+const openApiPlugin = definePlugin({
+	slug: "openApi",
+	options: z.object({
+		/**
+		* The OpenAPI Specification version to declare in the document's `openapi` field.
+		*
+		* Defaults to `'3.1.0'`.
+		*/
+		openApiVersion: z.literal("3.1.0").optional(),
+		info: z.object({
+			title: z.string(),
+			version: z.string(),
+			description: z.string().optional()
+		}),
+		servers: z.array(z.object({
+			url: z.string(),
+			description: z.string().optional()
+		})).optional(),
+		externalDocs: z.object({
+			url: z.string(),
+			description: z.string().optional()
+		}).optional(),
+		setOperationId: z.union([z.boolean(), z.literal("concatenated-path")]).optional(),
+		/**
+		* Document `hidden` routes too, for a document your own team reads.
+		*
+		* @default false
+		*/
+		includeHidden: z.boolean().optional(),
+		operationMapper: z.custom((value) => typeof value === "function", { error: "must be a function" }).optional(),
+		/**
+		* Document the derived `head` operation on every `GET` path without a declared one.
+		*
+		* @default false
+		*/
+		derivedHead: z.boolean().optional()
+	}).extend({
+		/**
+		* Where `kizuna generate` writes the document. `.json` renders JSON,
+		* anything else YAML.
+		*
+		* @example
+		* output: './openapi.yaml',
+		*/
+		output: z.string().optional(),
+		/**
+		* Where the reference UI is served.
+		*/
+		docsPath: RoutePathSchema.optional(),
+		/**
+		* Where the document is served. The UI embeds it, so this is only for
+		* publishing the file.
+		*/
+		jsonPath: z.custom((value) => typeof value === "string" && value.startsWith("/") && value.endsWith(".json"), { error: "must start with / and end in .json" }).optional(),
+		/**
+		* Where the document is served as YAML.
+		*/
+		yamlPath: z.custom((value) => typeof value === "string" && value.startsWith("/") && value.endsWith(".yaml"), { error: "must start with / and end in .yaml" }).optional(),
+		/**
+		* Which API reference UI to render.
+		*
+		* @default 'scalar'
+		*/
+		provider: z.enum(["scalar", "swagger"]).optional(),
+		/**
+		* Where to load the UI's assets from, for a self-hosted copy. The script
+		* URL for `'scalar'`; the directory holding `swagger-ui.css` and
+		* `swagger-ui-bundle.js` for `'swagger'`.
+		*/
+		cdnUrl: z.string().optional(),
+		/**
+		* The page's `<title>`.
+		*
+		* @default the document's `info.title`
+		*/
+		pageTitle: z.string().optional(),
+		/**
+		* Merged into `Scalar.createApiReference` or `SwaggerUIBundle`.
+		*/
+		configuration: z.record(z.string(), z.unknown()).optional()
+	}),
+	setup: ({ options, api }) => {
+		const { output, ...document } = options;
+		return {
+			routes: openApiRoutes(options, api),
+			generators: output === void 0 ? [] : [openApiDocumentGenerator({
+				output,
+				json: output.endsWith(".json"),
+				document
+			})]
+		};
+	}
+});
+/**
+* Writes one document, in the format its `output` names.
+*/
+const openApiDocumentGenerator = defineGenerator({
+	options: z.object({
+		json: z.boolean(),
+		document: z.custom()
+	}),
+	generate: ({ options, api }) => ({ finalize: () => {
+		const render = renderOpenApi(api, options.document);
+		return options.json ? `${JSON.stringify(render("json"), null, 4)}\n` : render("yaml");
+	} })
 });
-function openApiPlugin(props) {
-	return declare(props.slug ?? "openApi", props);
-}
 //#endregion
-export { generateOpenApi, openApiDocument, openApiPlugin, renderDocsHtml, renderOpenApi };
+export { generateOpenApi, openApiPlugin, renderDocsHtml, renderOpenApi };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kizunajs/openapi",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.21",
   "description": "OpenAPI 3.1 generation for Kizuna.js APIs",
   "keywords": [
     "kizunajs",
@@ -59,17 +59,17 @@
     "yaml": "^2.8.4"
   },
   "peerDependencies": {
-    "zod": "^4.0.0",
-    "kizunajs": "2.0.0-beta.2"
+    "kizunajs": "2.0.0-beta.21",
+    "zod": "^4.0.0"
   },
   "devDependencies": {
+    "kizunajs": "2.0.0-beta.21",
+    "@kizunajs/express": "2.0.0-beta.21",
     "@types/express": "^5.0.0",
     "express": "^5.0.0",
     "tsdown": "^0.21.0",
     "typescript": "^6.0.3",
-    "zod": "^4.0.0",
-    "kizunajs": "2.0.0-beta.2",
-    "@kizunajs/express": "2.0.0-beta.2"
+    "zod": "^4.0.0"
   },
   "scripts": {
     "build": "tsdown src/index.ts --format esm,cjs --dts --clean --external kizunajs --external zod",