@kizunajs/openapi 2.0.0-beta.1 → 2.0.0-beta.11

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 };
 };
 /**
+* What the wire carries for a type JSON Schema has no keyword for, which
+* `unrepresentable: 'any'` would otherwise leave as an empty schema.
+*/
+const JSON_ENCODING = {
+	date: {
+		type: "string",
+		format: "date-time"
+	},
+	bigint: { type: "string" }
+};
+/**
 * 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`.
 */
-const normalizeMeta = ({ jsonSchema }) => {
+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];
@@ -149,10 +162,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, routeTags, deprecated, hidden }) {
+			if (hidden && options.includeHidden !== true) return;
 			const openApiPath = convertPath(route.path);
 			const method = route.method.toLowerCase();
 			let operation = {
@@ -366,7 +380,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.
@@ -446,17 +460,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)
-	});
+	}, api));
 	const tags = tagsFromApi(api);
 	if (tags.length > 0) renderer("json").tags = tags;
 	return renderer;
@@ -548,22 +562,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 +571,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 +711,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;