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

package/dist/index.cjs

@@ -1,9 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let zod = require("zod");
 let kizunajs_plugin = require("kizunajs/plugin");
+let kizunajs_generator = require("kizunajs/generator");
 let kizunajs_adapter = require("kizunajs/adapter");
 let yaml = require("yaml");
-let kizunajs_generator = require("kizunajs/generator");
 let kizunajs = require("kizunajs");
 //#region src/generator.ts
 const streamJsonSchema = (response, toJsonSchema) => {
@@ -80,12 +80,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[(0, kizunajs_generator.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];
@@ -93,6 +106,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 = (0, kizunajs_generator.readMetaId)(schema);
@@ -149,10 +166,11 @@ const deriveHeadOperation = (getOperation) => {
 	for (const response of Object.values(operation.responses)) delete response.content;
 	return operation;
 };
-const openApiGenerator = (0, kizunajs_generator.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 = {
@@ -162,9 +180,8 @@ const openApiGenerator = (0, kizunajs_generator.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;
@@ -207,6 +224,15 @@ const openApiGenerator = (0, kizunajs_generator.createGenerator)((options, api)
 					schema: valueSchema
 				});
 			}
+			const streamsEvents = Object.values(route.responses).some((response) => (0, kizunajs_generator.isStreamResponse)(response) && (0, kizunajs_generator.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 && !(0, kizunajs_generator.isVoidSchema)(route.body)) {
 				const contentType = route.contentType ?? "application/json";
@@ -366,7 +392,7 @@ const openApiGenerator = (0, kizunajs_generator.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.
@@ -425,19 +451,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;
@@ -446,17 +482,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 = (0, kizunajs_generator.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;
@@ -548,22 +584,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";
@@ -573,24 +593,129 @@ 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((0, kizunajs_adapter.contractOf)(api), props);
-	return { router: {
-		page: () => (0, kizunajs_adapter.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: () => (0, kizunajs_adapter.rawResponse)(sent(JSON.stringify(spec("json")), JSON_TYPE)),
-		yaml: () => (0, kizunajs_adapter.rawResponse)(sent(spec("yaml"), YAML))
-	} };
+const openApiRoutes = (props, api) => {
+	let renderer;
+	const spec = ((format) => {
+		renderer ??= renderOpenApi((0, kizunajs_adapter.contractOf)(api), props);
+		return renderer(format);
+	});
+	const routes = {};
+	if (props.docsPath !== void 0) routes.page = (0, kizunajs_plugin.route)({
+		method: "GET",
+		path: props.docsPath,
+		summary: "API reference",
+		responses: { 200: zod.z.string() }
+	}).handler(() => (0, kizunajs_adapter.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 = (0, kizunajs_plugin.route)({
+		method: "GET",
+		path: props.jsonPath,
+		summary: "OpenAPI document",
+		responses: { 200: zod.z.unknown() }
+	}).handler(() => (0, kizunajs_adapter.rawResponse)(sent(JSON.stringify(spec("json")), JSON_TYPE)));
+	if (props.yamlPath !== void 0) routes.yaml = (0, kizunajs_plugin.route)({
+		method: "GET",
+		path: props.yamlPath,
+		summary: "OpenAPI document, as YAML",
+		responses: { 200: zod.z.string() }
+	}).handler(() => (0, kizunajs_adapter.rawResponse)(sent(spec("yaml"), YAML)));
+	return routes;
 };
+//#endregion
+//#region src/types.ts
+const GenerateOpenApiOptionsSchema = zod.z.object({
+	/**
+	* The OpenAPI Specification version to declare in the document's `openapi` field.
+	*
+	* Defaults to `'3.1.0'`.
+	*/
+	openApiVersion: zod.z.literal("3.1.0").optional(),
+	info: zod.z.object({
+		title: zod.z.string(),
+		version: zod.z.string(),
+		description: zod.z.string().optional()
+	}),
+	servers: zod.z.array(zod.z.object({
+		url: zod.z.string(),
+		description: zod.z.string().optional()
+	})).optional(),
+	externalDocs: zod.z.object({
+		url: zod.z.string(),
+		description: zod.z.string().optional()
+	}).optional(),
+	setOperationId: zod.z.union([zod.z.boolean(), zod.z.literal("concatenated-path")]).optional(),
+	/**
+	* Document `hidden` routes too, for a document your own team reads.
+	*
+	* @default false
+	*/
+	includeHidden: zod.z.boolean().optional(),
+	operationMapper: zod.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: zod.z.boolean().optional()
+});
+//#endregion
+//#region src/plugin.ts
+const OPENAPI_PLUGIN_SLUG = "openApi";
+const OpenApiPluginOptionsSchema = GenerateOpenApiOptionsSchema.extend({
+	/**
+	* Where `kizuna generate` writes the document. `.json` renders JSON,
+	* anything else YAML.
+	*
+	* @example
+	* output: './openapi.yaml',
+	*/
+	output: zod.z.string().optional(),
+	/**
+	* Where the reference UI is served.
+	*/
+	docsPath: kizunajs_plugin.RoutePathSchema.optional(),
+	/**
+	* Where the document is served. The UI embeds it, so this is only for
+	* publishing the file.
+	*/
+	jsonPath: zod.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: zod.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: zod.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: zod.z.string().optional(),
+	/**
+	* The page's `<title>`.
+	*
+	* @default the document's `info.title`
+	*/
+	pageTitle: zod.z.string().optional(),
+	/**
+	* Merged into `Scalar.createApiReference` or `SwaggerUIBundle`.
+	*/
+	configuration: zod.z.record(zod.z.string(), zod.z.unknown()).optional()
+});
 /**
 * Serve an API reference UI for the OpenAPI document, and the document itself
 * if you publish it.
@@ -608,42 +733,42 @@ const openApiServe = (props, api) => {
 *                 title: 'My API',
 *                 version: '1.0.0',
 *             },
+*             docsPath: '/docs',
 *         }),
 *     ],
 * });
 * ```
 */
-const declare = (slug, props) => (0, kizunajs_plugin.createPlugin)({
-	slug,
-	routes: {
-		...props.docsPath === void 0 ? {} : { page: {
-			method: "GET",
-			path: props.docsPath,
-			summary: "API reference",
-			responses: { 200: zod.z.string() }
-		} },
-		...props.jsonPath === void 0 ? {} : { json: {
-			method: "GET",
-			path: props.jsonPath,
-			summary: "OpenAPI document",
-			responses: { 200: zod.z.unknown() }
-		} },
-		...props.yamlPath === void 0 ? {} : { yaml: {
-			method: "GET",
-			path: props.yamlPath,
-			summary: "OpenAPI document, as YAML",
-			responses: { 200: zod.z.string() }
-		} }
-	},
-	props,
-	serve: (pluginProps, api) => openApiServe(pluginProps, api)
+const openApiPlugin = (0, kizunajs_plugin.definePlugin)({
+	slug: OPENAPI_PLUGIN_SLUG,
+	options: OpenApiPluginOptionsSchema,
+	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 = (0, kizunajs_generator.defineGenerator)({
+	options: zod.z.object({
+		json: zod.z.boolean(),
+		document: zod.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
 exports.generateOpenApi = generateOpenApi;
-exports.openApiDocument = openApiDocument;
 exports.openApiPlugin = openApiPlugin;
 exports.renderDocsHtml = renderDocsHtml;
 exports.renderOpenApi = renderOpenApi;