@kamaalio/hono-standard-openapi 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kamaal Farah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# hono-standard-openapi
+
+Generate an OpenAPI document from a Hono app whose routes are described by
+[Standard Schema](https://standardschema.dev) and
+[Standard JSON Schema](https://standardschema.dev/json-schema).
+
+The package is schema-library neutral: it consumes the validation and JSON Schema interfaces defined
+by those specifications. Use your chosen implementation's normal mechanism to add JSON Schema
+metadata, and the document follows.
+
+```ts
+import { StandardOpenAPIHono, createRoute, type StandardSchema } from 'hono-standard-openapi';
+
+// Define these with any Standard Schema-compatible implementation.
+declare const CardSchema: StandardSchema;
+declare const CardParamsSchema: StandardSchema;
+
+const route = createRoute({
+  method: 'get',
+  path: '/cards/{cardId}',
+  request: { params: CardParamsSchema },
+  responses: {
+    200: { description: 'The card', content: { 'application/json': { schema: CardSchema } } },
+  },
+});
+
+const app = new StandardOpenAPIHono();
+app.openapi(route, c => c.json(findCard(c.req.valid('param').cardId)));
+app.doc('/spec.json', { openapi: '3.1.1', info: { title: 'Cards', version: '1.0.0' } });
+```
+
+`c.req.valid('param')` is typed from the schema, the request is validated before the handler runs,
+and `/spec.json` describes the route — path parameters, response body, and a `Card` component the
+response `$ref`s.
+
+## Naming components
+
+A schema becomes a named component by carrying `$id`. Anything without one is described inline.
+
+`$id` is an ordinary JSON Schema keyword, so it can name a component wherever the schema appears,
+including as a response root. See [docs/design.md](./docs/design.md) for the details.
+
+Schemas that carry neither can be named from the outside:
+
+```ts
+app.openAPIRegistry.register('Card', CardSchema);
+```
+
+## Validation
+
+Failures reach the route's hook, or the nearest `defaultHook` on the app or the app it is mounted
+under, and otherwise answer `400`:
+
+```ts
+const app = new StandardOpenAPIHono({
+  defaultHook: (result, c) => {
+    if (!result.success) throw new InvalidRequest(c, result.error.issues);
+  },
+});
+```
+
+`result.error.issues` is Standard Schema's issue list — `{ message, path? }` — plus whatever else the
+schema library reports on each issue.
+
+## Normalization
+
+Converted JSON Schema is adjusted to read as an idiomatic OpenAPI document: the strictness marker
+from stripping objects is dropped, a `pattern` implied by a `format` is dropped, a nullable union
+becomes a nullable type, `const` becomes a single-value `enum`, and keywords are emitted in a
+conventional order. Each is switchable:
+
+```ts
+app.getOpenAPIDocument(config, { normalization: { constToEnum: false } });
+```

package/dist/app.d.ts

@@ -0,0 +1,44 @@
+import { type Env, Hono, type Schema } from 'hono';
+import type { OpenAPIObject } from 'openapi3-ts/oas31';
+import { type DocumentConfig, type GeneratorOptions } from './generator.ts';
+import { OpenAPIRegistry } from './registry.ts';
+import type { RouteConfig } from './route.ts';
+import type { RouteHandler } from './type-inference.ts';
+import { PARAMETER_SOURCES } from './types.ts';
+import { type Hook } from './validator.ts';
+export interface StandardOpenAPIHonoOptions<E extends Env> {
+    /** Runs for every validation on this app, and on apps mounted under it that define none. */
+    readonly defaultHook?: Hook<unknown, E, string, unknown>;
+}
+type HonoInit<E extends Env> = ConstructorParameters<typeof Hono>[0] & StandardOpenAPIHonoOptions<E>;
+/**
+ * A Hono app that documents itself.
+ *
+ * Routes registered through {@link StandardOpenAPIHono.openapi} are both served and recorded, so the
+ * document can never drift from what the server actually accepts.
+ */
+export declare class StandardOpenAPIHono<E extends Env = Env, S extends Schema = {}, BasePath extends string = '/'> extends Hono<E, S, BasePath> {
+    #private;
+    readonly openAPIRegistry: OpenAPIRegistry;
+    readonly defaultHook: StandardOpenAPIHonoOptions<E>['defaultHook'];
+    constructor(init?: HonoInit<E>);
+    /** Registers a route: mounts it, validates its request, and records it in the document. */
+    openapi<R extends RouteConfig>(route: R, handler: RouteHandler<R, E>, hook?: Hook<unknown, E, string, unknown>): this;
+    /** Mounts another app, taking its documented routes along with its handlers. */
+    route<SubPath extends string, SubEnv extends Env, SubSchema extends Schema, SubBasePath extends string>(path: SubPath, app: Hono<SubEnv, SubSchema, SubBasePath>): this;
+    /** Builds the document for everything registered so far. */
+    getOpenAPIDocument(config: DocumentConfig, generatorConfig?: GeneratorOptions): OpenAPIObject;
+    /** Serves the document as JSON at `path`. */
+    doc(path: string, config: DocumentConfig, generatorConfig?: GeneratorOptions): this;
+}
+/**
+ * The documenting app type behind a plain Hono type.
+ *
+ * Hono's own chaining methods return `Hono`, which loses the registry from the type but not from the
+ * value; this names what the value actually is.
+ */
+export type HonoToStandardOpenAPIHono<T> = T extends Hono<infer E, infer S, infer BasePath> ? StandardOpenAPIHono<E, S, BasePath> : T;
+/** Restores an app's type after Hono's own chaining methods widen it. */
+export declare function $<T extends Hono<any, any, any>>(app: T): HonoToStandardOpenAPIHono<T>;
+export { PARAMETER_SOURCES };
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAAE,IAAI,EAA0B,KAAK,MAAM,EAA0B,MAAM,MAAM,CAAC;AAEnG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAoB,MAAM,gBAAgB,CAAC;AAE9F,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAsB,iBAAiB,EAAqB,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,KAAK,IAAI,EAAqB,MAAM,gBAAgB,CAAC;AAE9D,MAAM,WAAW,0BAA0B,CAAC,CAAC,SAAS,GAAG;IACvD,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1D;AAED,KAAK,QAAQ,CAAC,CAAC,SAAS,GAAG,IAAI,qBAAqB,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,0BAA0B,CAAC,CAAC,CAAC,CAAC;AAUrG;;;;;GAKG;AACH,qBAAa,mBAAmB,CAC9B,CAAC,SAAS,GAAG,GAAG,GAAG,EACnB,CAAC,SAAS,MAAM,GAAG,EAAE,EACrB,QAAQ,SAAS,MAAM,GAAG,GAAG,CAC7B,SAAQ,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC;;IAC5B,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IAGnE,YAAY,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EAI7B;IAED,2FAA2F;IAC3F,OAAO,CAAC,CAAC,SAAS,WAAW,EAC3B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,EAC3B,IAAI,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,GACvC,IAAI,CAmBN;IAED,gFAAgF;IAChF,KAAK,CAAC,OAAO,SAAS,MAAM,EAAE,MAAM,SAAS,GAAG,EAAE,SAAS,SAAS,MAAM,EAAE,WAAW,SAAS,MAAM,EACpG,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,GACxC,IAAI,CAUN;IAED,4DAA4D;IAC5D,kBAAkB,CAAC,MAAM,EAAE,cAAc,EAAE,eAAe,GAAE,gBAAqB,GAAG,aAAa,CAEhG;IAED,6CAA6C;IAC7C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,GAAE,gBAAqB,GAAG,IAAI,CAItF;CAsCF;AAwFD;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,CAAC,CAAC,IACrC,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,QAAQ,CAAC,GAAG,mBAAmB,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC;AAE7F,yEAAyE;AAEzE,wBAAgB,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,yBAAyB,CAAC,CAAC,CAAC,CAGrF;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/app.js

@@ -0,0 +1,169 @@
+import { Hono } from 'hono';
+import { mergePath } from 'hono/utils/url';
+import { OpenAPIGenerator } from './generator.js';
+import { ComponentCollector, convertSchema } from './json-schema.js';
+import { OpenAPIRegistry } from './registry.js';
+import { isStandardJSONSchema } from './standard-schema.js';
+import { PARAMETER_SOURCES } from './types.js';
+import { standardValidator } from './validator.js';
+const JSON_CONTENT_TYPE = /^application\/([a-z\-.]+\+)?json/;
+const FORM_CONTENT_TYPES = ['multipart/form-data', 'application/x-www-form-urlencoded'];
+/**
+ * A Hono app that documents itself.
+ *
+ * Routes registered through {@link StandardOpenAPIHono.openapi} are both served and recorded, so the
+ * document can never drift from what the server actually accepts.
+ */
+export class StandardOpenAPIHono extends Hono {
+    openAPIRegistry;
+    defaultHook;
+    #parentApp;
+    constructor(init) {
+        super(init);
+        this.openAPIRegistry = new OpenAPIRegistry();
+        this.defaultHook = init?.defaultHook;
+    }
+    /** Registers a route: mounts it, validates its request, and records it in the document. */
+    openapi(route, handler, hook) {
+        const { hide, middleware, ...documented } = route;
+        if (hide !== true)
+            this.openAPIRegistry.registerPath(documented);
+        const effectiveHook = (result, c) => {
+            const resolved = hook ?? this.#resolveDefaultHook();
+            return resolved?.(result, c);
+        };
+        const handlers = [
+            ...normalizeMiddleware(middleware),
+            ...this.#buildValidators(route.request, effectiveHook),
+            handler,
+        ];
+        // @ts-expect-error: the handler chain is validated by `RouteHandler`, not by Hono's own inference.
+        this.on([route.method], [toRoutingPath(route.path)], ...handlers);
+        return this;
+    }
+    /** Mounts another app, taking its documented routes along with its handlers. */
+    route(path, app) {
+        super.route(path, app);
+        if (app instanceof StandardOpenAPIHono) {
+            app.#parentApp ??= this;
+            const prefix = path.replaceAll(/:([^/]+)/g, '{$1}');
+            this.openAPIRegistry.absorb(app.openAPIRegistry, routePath => mergePath(prefix, routePath));
+        }
+        return this;
+    }
+    /** Builds the document for everything registered so far. */
+    getOpenAPIDocument(config, generatorConfig = {}) {
+        return new OpenAPIGenerator(this.openAPIRegistry, generatorConfig).generateDocument(config);
+    }
+    /** Serves the document as JSON at `path`. */
+    doc(path, config, generatorConfig = {}) {
+        this.get(path, c => c.json(this.getOpenAPIDocument(config, generatorConfig)));
+        return this;
+    }
+    /** The nearest hook, preferring this app's own and falling back to the app it is mounted under. */
+    #resolveDefaultHook() {
+        if (this.defaultHook != null)
+            return this.defaultHook;
+        const visited = new Set([this]);
+        let ancestor = this.#parentApp;
+        while (ancestor != null && !visited.has(ancestor)) {
+            if (ancestor.defaultHook != null)
+                return ancestor.defaultHook;
+            visited.add(ancestor);
+            ancestor = ancestor.#parentApp;
+        }
+        return undefined;
+    }
+    #buildValidators(request, hook) {
+        if (request == null)
+            return [];
+        const validators = [];
+        for (const { key, target } of VALIDATED_PARTS) {
+            const schema = request[key];
+            if (schema == null)
+                continue;
+            validators.push(standardValidator(target, schema, propertyNamesOf(schema), hook));
+        }
+        const body = request.body;
+        if (body != null)
+            validators.push(...buildBodyValidators(body.content, body.required === true, hook));
+        return validators;
+    }
+}
+const VALIDATED_PARTS = [
+    { key: 'query', target: 'query' },
+    { key: 'params', target: 'param' },
+    { key: 'headers', target: 'header' },
+    { key: 'cookies', target: 'cookie' },
+];
+function buildBodyValidators(content, required, hook) {
+    const validators = [];
+    for (const [mediaType, media] of Object.entries(content)) {
+        const schema = media.schema;
+        if (!isStandardJSONSchema(schema))
+            continue;
+        const target = JSON_CONTENT_TYPE.test(mediaType)
+            ? 'json'
+            : FORM_CONTENT_TYPES.some(formType => mediaType.startsWith(formType))
+                ? 'form'
+                : undefined;
+        if (target == null)
+            continue;
+        const validator = standardValidator(target, schema, propertyNamesOf(schema), hook);
+        validators.push(required ? validator : skipWhenBodyAbsent(validator, mediaType, target));
+    }
+    return validators;
+}
+/**
+ * Lets an optional body through when the request didn't send one.
+ *
+ * The handler still gets an empty value from `c.req.valid()`, so it can read the body the same way
+ * whether or not the caller supplied it.
+ */
+function skipWhenBodyAbsent(validator, mediaType, target) {
+    return async (c, next) => {
+        const contentType = c.req.header('content-type');
+        if (contentType != null && contentType.startsWith(mediaType.replace(/;.*/, ''))) {
+            return validator(c, next);
+        }
+        c.req.addValidatedData(target, {});
+        await next();
+        return undefined;
+    };
+}
+/** The property names a schema describes, used to match header names case-insensitively. */
+function propertyNamesOf(schema) {
+    try {
+        const converted = convertSchema(schema, {
+            components: new ComponentCollector(),
+            hoistRoot: false,
+            io: 'input',
+            target: 'draft-2020-12',
+        });
+        const properties = converted.properties;
+        if (typeof properties !== 'object' || properties == null)
+            return [];
+        return Object.keys(properties);
+    }
+    catch {
+        return [];
+    }
+}
+function normalizeMiddleware(middleware) {
+    if (middleware == null)
+        return [];
+    if (typeof middleware === 'function')
+        return [middleware];
+    return [...middleware];
+}
+function toRoutingPath(path) {
+    return path.replaceAll(/\/{(.+?)}/g, '/:$1');
+}
+/** Restores an app's type after Hono's own chaining methods widen it. */
+// oxlint-disable-next-line typescript/no-explicit-any
+export function $(app) {
+    // @ts-expect-error: chaining only widens the type; the value is still this package's app.
+    return app;
+}
+export { PARAMETER_SOURCES };
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+/** Base class for every error this package throws, so consumers can catch them as a group. */
+export declare class StandardOpenAPIError extends Error {
+    constructor(message: string);
+}
+/** Thrown when a schema cannot describe itself as JSON Schema. */
+export declare class UnsupportedSchemaError extends StandardOpenAPIError {
+    constructor(vendor?: string);
+}
+/** Thrown when two different schemas claim the same component name. */
+export declare class ComponentNameConflictError extends StandardOpenAPIError {
+    constructor(name: string);
+}
+/** Thrown when a schema used for parameters or headers is not a JSON Schema object type. */
+export declare class UnsupportedParameterSchemaError extends StandardOpenAPIError {
+    constructor(location: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,kEAAkE;AAClE,qBAAa,sBAAuB,SAAQ,oBAAoB;IAC9D,YAAY,MAAM,CAAC,EAAE,MAAM,EAK1B;CACF;AAED,uEAAuE;AACvE,qBAAa,0BAA2B,SAAQ,oBAAoB;IAClE,YAAY,IAAI,EAAE,MAAM,EAKvB;CACF;AAED,4FAA4F;AAC5F,qBAAa,+BAAgC,SAAQ,oBAAoB;IACvE,YAAY,QAAQ,EAAE,MAAM,EAK3B;CACF"}

package/dist/errors.js

@@ -0,0 +1,29 @@
+/** Base class for every error this package throws, so consumers can catch them as a group. */
+export class StandardOpenAPIError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** Thrown when a schema cannot describe itself as JSON Schema. */
+export class UnsupportedSchemaError extends StandardOpenAPIError {
+    constructor(vendor) {
+        super(`Schema${vendor == null ? '' : ` from "${vendor}"`} does not implement Standard JSON Schema. ` +
+            'Only schemas exposing `~standard.jsonSchema` can be turned into an OpenAPI document.');
+    }
+}
+/** Thrown when two different schemas claim the same component name. */
+export class ComponentNameConflictError extends StandardOpenAPIError {
+    constructor(name) {
+        super(`Two different schemas are both named "${name}". Component names must be unique; ` +
+            'give one of them a different `$id`.');
+    }
+}
+/** Thrown when a schema used for parameters or headers is not a JSON Schema object type. */
+export class UnsupportedParameterSchemaError extends StandardOpenAPIError {
+    constructor(location) {
+        super(`The schema for "${location}" must describe an object, because each of its properties becomes ` +
+            'one OpenAPI parameter.');
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AAED,kEAAkE;AAClE,MAAM,OAAO,sBAAuB,SAAQ,oBAAoB;IAC9D,YAAY,MAAe;QACzB,KAAK,CACH,SAAS,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,MAAM,GAAG,4CAA4C;YAC5F,sFAAsF,CACzF,CAAC;IACJ,CAAC;CACF;AAED,uEAAuE;AACvE,MAAM,OAAO,0BAA2B,SAAQ,oBAAoB;IAClE,YAAY,IAAY;QACtB,KAAK,CACH,yCAAyC,IAAI,qCAAqC;YAChF,qCAAqC,CACxC,CAAC;IACJ,CAAC;CACF;AAED,4FAA4F;AAC5F,MAAM,OAAO,+BAAgC,SAAQ,oBAAoB;IACvE,YAAY,QAAgB;QAC1B,KAAK,CACH,mBAAmB,QAAQ,oEAAoE;YAC7F,wBAAwB,CAC3B,CAAC;IACJ,CAAC;CACF"}

package/dist/generator.d.ts

@@ -0,0 +1,25 @@
+import type { OpenAPIObject } from 'openapi3-ts/oas31';
+import { type NormalizationOptions } from './json-schema.ts';
+import type { OpenAPIDefinition, OpenAPIRegistry } from './registry.ts';
+/** The OpenAPI version to emit. 3.1 is JSON Schema draft 2020-12; 3.0 is its own dialect. */
+export type OpenAPIVersion = '3.0' | '3.1';
+export interface GeneratorOptions {
+    readonly version?: OpenAPIVersion;
+    readonly normalization?: NormalizationOptions;
+    /**
+     * How `components.schemas` is ordered.
+     *
+     * `first-referenced` walks the finished document and orders components the way a reader meets
+     * them, which keeps the output stable as unrelated schemas come and go. `registration` keeps the
+     * order they were generated in.
+     */
+    readonly componentOrder?: 'first-referenced' | 'registration' | 'alphabetical';
+}
+export type DocumentConfig = Omit<OpenAPIObject, 'paths' | 'webhooks'>;
+/** Assembles an OpenAPI document from what a registry collected. */
+export declare class OpenAPIGenerator {
+    #private;
+    constructor(definitions: OpenAPIDefinition[] | OpenAPIRegistry, options?: GeneratorOptions);
+    generateDocument(config: DocumentConfig): OpenAPIObject;
+}
+//# sourceMappingURL=generator.d.ts.map

package/dist/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,aAAa,EAAmB,MAAM,mBAAmB,CAAC;AAG1F,OAAO,EAA6C,KAAK,oBAAoB,EAAiB,MAAM,kBAAkB,CAAC;AACvH,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAWxE,6FAA6F;AAC7F,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,KAAK,CAAC;AAE3C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAC;IAC9C;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,GAAG,cAAc,GAAG,cAAc,CAAC;CAChF;AAED,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,aAAa,EAAE,OAAO,GAAG,UAAU,CAAC,CAAC;AAevE,oEAAoE;AACpE,qBAAa,gBAAgB;;IAO3B,YAAY,WAAW,EAAE,iBAAiB,EAAE,GAAG,eAAe,EAAE,OAAO,GAAE,gBAAqB,EAO7F;IAED,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,CAmCtD;CA6HF"}

package/dist/generator.js

@@ -0,0 +1,231 @@
+import { UnsupportedParameterSchemaError, UnsupportedSchemaError } from './errors.js';
+import { ComponentCollector, convertSchema } from './json-schema.js';
+import { isStandardJSONSchema, isStandardSchema } from './standard-schema.js';
+import { PARAMETER_SOURCES, } from './types.js';
+const TARGETS = {
+    '3.0': 'openapi-3.0',
+    '3.1': 'draft-2020-12',
+};
+/** Assembles an OpenAPI document from what a registry collected. */
+export class OpenAPIGenerator {
+    #definitions;
+    #options;
+    #components = new ComponentCollector();
+    /** Names given to schemas from the outside, for schemas that carry no `$id` of their own. */
+    #names = new WeakMap();
+    constructor(definitions, options = {}) {
+        this.#definitions = Array.isArray(definitions) ? definitions : definitions.definitions;
+        this.#options = options;
+        for (const definition of this.#definitions) {
+            if (definition.type === 'schema')
+                this.#names.set(definition.schema, definition.name);
+        }
+    }
+    generateDocument(config) {
+        const paths = {};
+        const webhooks = {};
+        const rawComponents = {};
+        for (const definition of this.#definitions) {
+            switch (definition.type) {
+                case 'component':
+                    rawComponents[definition.componentType] = {
+                        ...rawComponents[definition.componentType],
+                        [definition.name]: definition.component,
+                    };
+                    break;
+                case 'schema':
+                    this.#convert(definition.schema, 'output');
+                    break;
+                case 'route':
+                    mergePathItem(paths, definition.route, this.#generateOperation(definition.route));
+                    break;
+                case 'webhook':
+                    mergePathItem(webhooks, definition.webhook, this.#generateOperation(definition.webhook));
+                    break;
+            }
+        }
+        const { components: configuredComponents, ...rest } = config;
+        const document = {
+            ...rest,
+            paths,
+            components: this.#buildComponents(configuredComponents, rawComponents, paths),
+        };
+        if (Object.keys(webhooks).length > 0)
+            document.webhooks = webhooks;
+        return document;
+    }
+    #buildComponents(configured, raw, paths) {
+        const schemas = orderSchemas(this.#components.schemas, this.#options.componentOrder ?? 'registration', paths);
+        const merged = { ...configured, ...raw };
+        return {
+            ...merged,
+            schemas: { ...merged.schemas, ...schemas },
+        };
+    }
+    #convert(schema, io, hoistRoot) {
+        return convertSchema(schema, {
+            components: this.#components,
+            hoistRoot,
+            io,
+            name: this.#names.get(schema),
+            normalization: this.#options.normalization,
+            target: TARGETS[this.#options.version ?? '3.1'],
+        });
+    }
+    #generateOperation(route) {
+        const { method, parameters: declaredParameters, path: _path, request, responses, ...operationConfig } = route;
+        const parameters = [...(declaredParameters ?? []), ...this.#generateParameters(request)];
+        const operation = { ...operationConfig, responses: this.#generateResponses(responses) };
+        if (parameters.length > 0)
+            operation.parameters = parameters;
+        const requestBody = request?.body;
+        if (requestBody != null) {
+            const { content, ...bodyConfig } = requestBody;
+            operation.requestBody = { ...bodyConfig, content: this.#generateContent(content, 'input') };
+        }
+        return { method, operation: reorderOperation(operation) };
+    }
+    #generateParameters(request) {
+        if (request == null)
+            return [];
+        return PARAMETER_SOURCES.flatMap(({ key, location }) => {
+            const schema = request[key];
+            if (schema == null)
+                return [];
+            return this.#generateParametersFor(schema, location);
+        });
+    }
+    #generateParametersFor(schema, location) {
+        const converted = this.#convert(schema, 'input', false);
+        const properties = converted.properties;
+        if (converted.type !== 'object' || !isRecord(properties))
+            throw new UnsupportedParameterSchemaError(location);
+        const required = Array.isArray(converted.required) ? converted.required : [];
+        return Object.entries(properties).map(([name, property]) => ({
+            ...describeParameter(property, location === 'path' || required.includes(name)),
+            name,
+            in: location,
+        }));
+    }
+    #generateResponses(responses) {
+        const generated = {};
+        for (const [status, response] of Object.entries(responses)) {
+            generated[status] = '$ref' in response ? response : this.#generateResponse(response);
+        }
+        return generated;
+    }
+    #generateResponse(response) {
+        const { content, description, headers, links } = response;
+        const generated = { description };
+        if (headers != null)
+            generated.headers = this.#generateResponseHeaders(headers);
+        if (content != null)
+            generated.content = this.#generateContent(content, 'output');
+        if (links != null)
+            generated.links = links;
+        return generated;
+    }
+    #generateResponseHeaders(headers) {
+        if (!isStandardJSONSchema(headers)) {
+            if (isStandardSchema(headers))
+                throw new UnsupportedSchemaError(headers['~standard'].vendor);
+            return headers;
+        }
+        const converted = this.#convert(headers, 'output', false);
+        const properties = converted.properties;
+        if (converted.type !== 'object' || !isRecord(properties))
+            throw new UnsupportedParameterSchemaError('headers');
+        const required = Array.isArray(converted.required) ? converted.required : [];
+        const generated = {};
+        for (const [name, property] of Object.entries(properties)) {
+            generated[name] = describeParameter(property, required.includes(name));
+        }
+        return generated;
+    }
+    /** Converts a schema, or passes an already-written OpenAPI schema through untouched. */
+    #describe(schema, io) {
+        if (isStandardJSONSchema(schema))
+            return this.#convert(schema, io);
+        if (isStandardSchema(schema))
+            throw new UnsupportedSchemaError(schema['~standard'].vendor);
+        return schema;
+    }
+    #generateContent(content, io) {
+        const generated = {};
+        for (const [mediaType, media] of Object.entries(content)) {
+            const { schema, ...rest } = media;
+            generated[mediaType] = { ...rest, ...(schema == null ? {} : { schema: this.#describe(schema, io) }) };
+        }
+        return generated;
+    }
+}
+/**
+ * Describes one parameter or response header.
+ *
+ * A description on the schema is repeated on the parameter itself, because tools read it from either
+ * place and OpenAPI has no notion of inheriting it.
+ */
+function describeParameter(property, required) {
+    const described = { schema: property, required };
+    if (isRecord(property) && typeof property.description === 'string')
+        described.description = property.description;
+    return described;
+}
+/** Puts an operation's keys in the order the OpenAPI specification presents them. */
+function reorderOperation(operation) {
+    const { parameters, requestBody, responses, ...rest } = operation;
+    const ordered = { ...rest };
+    if (parameters != null)
+        ordered.parameters = parameters;
+    if (requestBody != null)
+        ordered.requestBody = requestBody;
+    ordered.responses = responses;
+    return ordered;
+}
+function mergePathItem(paths, route, { method, operation }) {
+    paths[route.path] = { ...paths[route.path], [method]: operation };
+}
+function orderSchemas(schemas, order, paths) {
+    if (order === 'registration')
+        return schemas;
+    if (order === 'alphabetical') {
+        return Object.fromEntries(Object.entries(schemas).sort(([left], [right]) => left.localeCompare(right)));
+    }
+    const ordered = {};
+    for (const name of referencedNames(paths, schemas)) {
+        const schema = schemas[name];
+        if (schema != null)
+            ordered[name] = schema;
+    }
+    return { ...ordered, ...schemas };
+}
+/** Names of components in the order a depth-first read of the document first meets them. */
+function referencedNames(paths, schemas) {
+    const seen = [];
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            for (const entry of node)
+                visit(entry);
+            return;
+        }
+        if (!isRecord(node))
+            return;
+        const reference = node.$ref;
+        if (typeof reference === 'string') {
+            const name = reference.startsWith('#/components/schemas/') ? reference.slice(21) : undefined;
+            if (name == null || seen.includes(name))
+                return;
+            seen.push(name);
+            visit(schemas[name]);
+            return;
+        }
+        for (const value of Object.values(node))
+            visit(value);
+    };
+    visit(paths);
+    return seen;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value != null && !Array.isArray(value);
+}
+//# sourceMappingURL=generator.js.map