@zudojs/openapi 0.0.1 → 1.1.0

package/dist/openApiRegistry/openApiRegistry.core.d.ts

@@ -1,8 +1,12 @@
-import type { OpenAPIDocument, OpenAPIParameter, OpenAPIRequestBody, OpenAPISchema, OpenAPISecurityScheme, OpenAPITag, OpenAPIReference } from "../openApiTypes/openApiTypes.core.js";
+import type { OpenAPIDocument, OpenAPIExample, OpenAPIHeader, OpenAPIInfo, OpenAPILink, OpenAPIParameter, OpenAPIPathItem, OpenAPIRequestBody, OpenAPIResponse, OpenAPISchema, OpenAPISecurityRequirement, OpenAPISecurityScheme, OpenAPIServer, OpenAPITag, OpenAPIReference } from "../openApiTypes/openApiTypes.core.js";
 import type { OpenAPIRoute, OpenAPIRegistry } from "./openApiRegistry.type.js";
+import type { ComponentSection } from "../openApiSchema/references.core.js";
 /** Default OpenAPI registry implementation. */
 export declare class OpenAPIRegistryImpl implements OpenAPIRegistry {
     readonly version: string;
+    private info;
+    private readonly servers;
+    private readonly security;
     private readonly routes;
     private readonly schemas;
     private readonly responses;
@@ -15,16 +19,45 @@ export declare class OpenAPIRegistryImpl implements OpenAPIRegistry {
     private readonly links;
     private readonly callbacks;
     constructor(version?: string);
+    /** Sets the document's `info` object. */
+    setInfo(info: OpenAPIInfo): void;
+    /** The document's current `info` object. */
+    getInfo(): OpenAPIInfo;
+    addServer(server: OpenAPIServer): void;
+    addSecurityRequirement(requirement: OpenAPISecurityRequirement): void;
+    private static routeKey;
     registerRoute(route: OpenAPIRoute): void;
+    /**
+     * Registers a route, replacing any existing one.
+     *
+     * This is what makes regeneration idempotent: re-registering the same routes
+     * into a registry that already holds them used to throw, so calling
+     * `generate()` twice failed.
+     */
+    setRoute(route: OpenAPIRoute): void;
+    private static register;
     registerSchema(name: string, schema: OpenAPISchema): void;
-    registerResponse(name: string, response: unknown): void;
+    registerResponse(name: string, response: OpenAPIResponse): void;
     registerParameter(name: string, parameter: OpenAPIParameter): void;
     registerRequestBody(name: string, body: OpenAPIRequestBody): void;
-    registerHeader(name: string, header: unknown): void;
-    registerExample(name: string, example: unknown): void;
+    registerHeader(name: string, header: OpenAPIHeader): void;
+    registerExample(name: string, example: OpenAPIExample): void;
     registerSecurityScheme(name: string, scheme: OpenAPISecurityScheme): void;
+    registerLink(name: string, link: OpenAPILink): void;
+    registerCallback(name: string, callback: Readonly<Record<string, OpenAPIPathItem>>): void;
+    /**
+     * Registers a tag.
+     *
+     * Re-registering a tag name conflicts, like every other component: quietly
+     * keeping the first definition discarded corrected descriptions without a
+     * word.
+     */
     registerTag(tag: OpenAPITag): void;
-    ref(section: "schemas" | "responses" | "parameters" | "requestBodies" | "headers" | "examples" | "securitySchemes" | "links" | "callbacks", name: string): OpenAPIReference;
+    /** Registers a tag, replacing any existing one with the same name. */
+    setTag(tag: OpenAPITag): void;
+    ref(section: ComponentSection, name: string): OpenAPIReference;
+    hasComponent(section: ComponentSection, name: string): boolean;
+    private componentMap;
     generate(): OpenAPIDocument;
     clear(): void;
 }

package/dist/openApiRegistry/openApiRegistry.core.js

@@ -1,8 +1,14 @@
-import { COMPONENT_REF_PREFIX, DEFAULT_OPENAPI_VERSION, } from "../openApiConstants/openApiConstants.core.js";
-import { OpenAPIComponentConflictError, OpenAPIDocumentError, OpenAPIOperationError, OpenAPIVersionError, } from "../openApiErrors/openApiError.core.js";
+import { createComponentReference } from "../openApiSchema/references.core.js";
+import { DEFAULT_OPENAPI_VERSION, SUPPORTED_OPENAPI_VERSIONS, } from "../openApiConstants/openApiConstants.core.js";
+import { OpenAPIComponentConflictError, OpenAPIOperationError, OpenAPIVersionError, } from "../openApiErrors/openApiError.types.js";
+/** Placeholder used until {@link OpenAPIRegistryImpl.setInfo} is called. */
+const DEFAULT_INFO = { title: "API", version: "0.0.0" };
 /** Default OpenAPI registry implementation. */
 export class OpenAPIRegistryImpl {
     version;
+    info = DEFAULT_INFO;
+    servers = [];
+    security = [];
     routes = new Map();
     schemas = new Map();
     responses = new Map();
@@ -15,14 +21,55 @@ export class OpenAPIRegistryImpl {
     links = new Map();
     callbacks = new Map();
     constructor(version = DEFAULT_OPENAPI_VERSION) {
+        if (!SUPPORTED_OPENAPI_VERSIONS.includes(version)) {
+            // Fail where the version is chosen, not later inside generate().
+            throw new OpenAPIVersionError(version, SUPPORTED_OPENAPI_VERSIONS);
+        }
         this.version = version;
     }
+    /** Sets the document's `info` object. */
+    setInfo(info) {
+        this.info = { ...info };
+    }
+    /** The document's current `info` object. */
+    getInfo() {
+        return { ...this.info };
+    }
+    addServer(server) {
+        this.servers.push({ ...server });
+    }
+    addSecurityRequirement(requirement) {
+        this.security.push({ ...requirement });
+    }
+    static routeKey(route) {
+        return `${route.method.toLowerCase()}:${route.path}`;
+    }
     registerRoute(route) {
-        const key = `${route.method}:${route.path}`;
+        const key = OpenAPIRegistryImpl.routeKey(route);
         const existing = this.routes.get(key);
-        if (existing)
-            throw new OpenAPIOperationError(`Duplicate operation for ${route.method.toUpperCase()} ${route.path}: ${existing.operation.operationId ?? "unknown"}.`);
-        this.routes.set(key, {
+        if (existing) {
+            throw new OpenAPIOperationError(`Duplicate operation for ${route.method.toUpperCase()} ${route.path}` +
+                (existing.operation.operationId
+                    ? ` (already registered as "${existing.operation.operationId}")`
+                    : ""), {
+                metadata: {
+                    method: route.method,
+                    path: route.path,
+                    operationId: existing.operation.operationId,
+                },
+            });
+        }
+        this.setRoute(route);
+    }
+    /**
+     * Registers a route, replacing any existing one.
+     *
+     * This is what makes regeneration idempotent: re-registering the same routes
+     * into a registry that already holds them used to throw, so calling
+     * `generate()` twice failed.
+     */
+    setRoute(route) {
+        this.routes.set(OpenAPIRegistryImpl.routeKey(route), {
             ...route,
             operation: Object.freeze({
                 ...route.operation,
@@ -30,72 +77,121 @@ export class OpenAPIRegistryImpl {
             }),
         });
     }
+    static register(map, section, name, value) {
+        if (map.has(name)) {
+            throw new OpenAPIComponentConflictError(section, name);
+        }
+        map.set(name, Object.freeze(value));
+    }
     registerSchema(name, schema) {
-        if (this.schemas.has(name))
-            throw new OpenAPIComponentConflictError(`schemas/${name}`);
-        this.schemas.set(name, Object.freeze({ ...schema }));
+        OpenAPIRegistryImpl.register(this.schemas, "schemas", name, { ...schema });
     }
     registerResponse(name, response) {
-        if (this.responses.has(name))
-            throw new OpenAPIComponentConflictError(`responses/${name}`);
-        this.responses.set(name, Object.freeze({ ...response }));
+        OpenAPIRegistryImpl.register(this.responses, "responses", name, {
+            ...response,
+        });
     }
     registerParameter(name, parameter) {
-        if (this.parameters.has(name))
-            throw new OpenAPIComponentConflictError(`parameters/${name}`);
-        this.parameters.set(name, Object.freeze({ ...parameter }));
+        OpenAPIRegistryImpl.register(this.parameters, "parameters", name, {
+            ...parameter,
+        });
     }
     registerRequestBody(name, body) {
-        if (this.requestBodies.has(name))
-            throw new OpenAPIComponentConflictError(`requestBodies/${name}`);
-        this.requestBodies.set(name, Object.freeze({ ...body }));
+        OpenAPIRegistryImpl.register(this.requestBodies, "requestBodies", name, {
+            ...body,
+        });
     }
     registerHeader(name, header) {
-        if (this.headers.has(name))
-            throw new OpenAPIComponentConflictError(`headers/${name}`);
-        this.headers.set(name, Object.freeze({ ...header }));
+        OpenAPIRegistryImpl.register(this.headers, "headers", name, { ...header });
     }
     registerExample(name, example) {
-        if (this.examples.has(name))
-            throw new OpenAPIComponentConflictError(`examples/${name}`);
-        this.examples.set(name, Object.freeze({ ...example }));
+        OpenAPIRegistryImpl.register(this.examples, "examples", name, {
+            ...example,
+        });
     }
     registerSecurityScheme(name, scheme) {
-        if (this.securitySchemes.has(name))
-            throw new OpenAPIComponentConflictError(`securitySchemes/${name}`);
-        this.securitySchemes.set(name, Object.freeze({ ...scheme }));
+        OpenAPIRegistryImpl.register(this.securitySchemes, "securitySchemes", name, {
+            ...scheme,
+        });
+    }
+    registerLink(name, link) {
+        OpenAPIRegistryImpl.register(this.links, "links", name, { ...link });
+    }
+    registerCallback(name, callback) {
+        OpenAPIRegistryImpl.register(this.callbacks, "callbacks", name, {
+            ...callback,
+        });
     }
+    /**
+     * Registers a tag.
+     *
+     * Re-registering a tag name conflicts, like every other component: quietly
+     * keeping the first definition discarded corrected descriptions without a
+     * word.
+     */
     registerTag(tag) {
-        if (!this.tags.has(tag.name))
-            this.tags.set(tag.name, Object.freeze({ ...tag }));
+        if (this.tags.has(tag.name)) {
+            throw new OpenAPIComponentConflictError("tags", tag.name);
+        }
+        this.tags.set(tag.name, Object.freeze({ ...tag }));
+    }
+    /** Registers a tag, replacing any existing one with the same name. */
+    setTag(tag) {
+        this.tags.set(tag.name, Object.freeze({ ...tag }));
     }
     ref(section, name) {
-        return { $ref: `${COMPONENT_REF_PREFIX}/${section}/${name}` };
+        return createComponentReference(section, name);
+    }
+    hasComponent(section, name) {
+        return this.componentMap(section)?.has(name) ?? false;
+    }
+    componentMap(section) {
+        switch (section) {
+            case "schemas":
+                return this.schemas;
+            case "responses":
+                return this.responses;
+            case "parameters":
+                return this.parameters;
+            case "requestBodies":
+                return this.requestBodies;
+            case "headers":
+                return this.headers;
+            case "examples":
+                return this.examples;
+            case "securitySchemes":
+                return this.securitySchemes;
+            case "links":
+                return this.links;
+            case "callbacks":
+                return this.callbacks;
+            default:
+                return undefined;
+        }
     }
     generate() {
-        if (!["3.0.0", "3.0.1", "3.0.2", "3.0.3", "3.1.0", "3.1.1"].includes(this.version))
-            throw new OpenAPIVersionError(this.version);
-        const paths = {};
-        for (const [, route] of this.routes) {
+        // A `Map` rather than an object literal: a route registered at the path
+        // `__proto__` assigned to a literal sets the object's prototype instead
+        // of adding an entry, so the path disappears from the document with no
+        // error raised anywhere. `Object.fromEntries` defines own properties and
+        // has no such hole.
+        const paths = new Map();
+        for (const route of this.routes.values()) {
             const operation = Object.freeze({
                 ...route.operation,
                 responses: Object.freeze({ ...route.operation.responses }),
             });
-            const existing = paths[route.path] ?? {};
-            paths[route.path] = Object.freeze({
-                ...existing,
-                ...(route.method === "get" ? { get: operation } : {}),
-                ...(route.method === "put" ? { put: operation } : {}),
-                ...(route.method === "post" ? { post: operation } : {}),
-                ...(route.method === "delete" ? { delete: operation } : {}),
-                ...(route.method === "options" ? { options: operation } : {}),
-                ...(route.method === "head" ? { head: operation } : {}),
-                ...(route.method === "patch" ? { patch: operation } : {}),
-                ...(route.method === "trace" ? { trace: operation } : {}),
-                ...(route.operation.parameters?.length
-                    ? { parameters: Object.freeze([...route.operation.parameters]) }
-                    : {}),
-            });
+            // Operations keep their own parameters. Hoisting them to the path item
+            // makes them apply to every method on that path, so two methods with
+            // different parameters overwrote one another.
+            //
+            // The method is lower-cased here as well as in the cache key: a path
+            // item field is defined in lower case, and `GET` would emit a field no
+            // consumer recognises while still colliding on the key.
+            paths.set(route.path, Object.freeze({
+                ...(paths.get(route.path) ?? {}),
+                [route.method.toLowerCase()]: operation,
+            }));
         }
         const components = {};
         const componentMaps = [
@@ -113,24 +209,28 @@ export class OpenAPIRegistryImpl {
             if (map.size > 0)
                 components[key] = Object.freeze(Object.fromEntries(map));
         }
-        try {
-            return Object.freeze({
-                openapi: this.version,
-                info: { title: "Zudojs API", version: "1.0.0" },
-                paths: Object.freeze(paths),
-                ...(Object.keys(components).length > 0
-                    ? { components: Object.freeze(components) }
-                    : {}),
-                ...(this.tags.size > 0
-                    ? { tags: Object.freeze(Array.from(this.tags.values())) }
-                    : {}),
-            });
-        }
-        catch (error) {
-            throw new OpenAPIDocumentError(`Failed to generate OpenAPI document: ${error.message}`);
-        }
+        return Object.freeze({
+            openapi: this.version,
+            info: Object.freeze({ ...this.info }),
+            ...(this.servers.length > 0
+                ? { servers: Object.freeze([...this.servers]) }
+                : {}),
+            paths: Object.freeze(Object.fromEntries(paths)),
+            ...(Object.keys(components).length > 0
+                ? { components: Object.freeze(components) }
+                : {}),
+            ...(this.security.length > 0
+                ? { security: Object.freeze([...this.security]) }
+                : {}),
+            ...(this.tags.size > 0
+                ? { tags: Object.freeze([...this.tags.values()]) }
+                : {}),
+        });
     }
     clear() {
+        this.info = DEFAULT_INFO;
+        this.servers.length = 0;
+        this.security.length = 0;
         for (const map of [
             this.routes,
             this.schemas,
@@ -143,8 +243,9 @@ export class OpenAPIRegistryImpl {
             this.tags,
             this.links,
             this.callbacks,
-        ])
+        ]) {
             map.clear();
+        }
     }
 }
 //# sourceMappingURL=openApiRegistry.core.js.map

package/dist/openApiRegistry/openApiRegistry.type.d.ts

@@ -1,16 +1,11 @@
-import type { OpenAPIDocument } from "../openApiTypes/openApiTypes.core.js";
-import type { OpenAPIOperation } from "../openApiTypes/openApiTypes.core.js";
-import type { OpenAPIParameter } from "../openApiTypes/openApiTypes.core.js";
-import type { OpenAPIRequestBody } from "../openApiTypes/openApiTypes.core.js";
-import type { OpenAPISchema } from "../openApiTypes/openApiTypes.core.js";
-import type { OpenAPISecurityScheme } from "../openApiTypes/openApiTypes.core.js";
-import type { OpenAPITag } from "../openApiTypes/openApiTypes.core.js";
-import type { OpenAPIReference } from "../openApiTypes/openApiTypes.core.js";
+import type { OpenAPIDocument, OpenAPIInfo, OpenAPIOperation, OpenAPIParameter, OpenAPIRequestBody, OpenAPIResponse, OpenAPISchema, OpenAPISecurityRequirement, OpenAPISecurityScheme, OpenAPIServer, OpenAPITag, OpenAPIReference, OpenAPIHeader, OpenAPIExample, OpenAPILink, OpenAPIPathItem } from "../openApiTypes/openApiTypes.core.js";
+import type { OpenAPIHttpMethod } from "../openApiRouting/routeMetadata.type.js";
+import type { ComponentSection } from "../openApiSchema/references.core.js";
 /**
  * A registered route in the OpenAPI registry.
  */
 export interface OpenAPIRoute {
-    readonly method: "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
+    readonly method: OpenAPIHttpMethod;
     readonly path: string;
     readonly operation: OpenAPIOperation;
 }
@@ -26,16 +21,26 @@ export interface OpenAPIComponentRegistration<T> {
  */
 export interface OpenAPIRegistry {
     readonly version: string;
+    /** Document-level metadata. Defaults to a placeholder title and version. */
+    setInfo(info: OpenAPIInfo): void;
+    addServer(server: OpenAPIServer): void;
+    addSecurityRequirement(requirement: OpenAPISecurityRequirement): void;
     registerRoute(route: OpenAPIRoute): void;
+    /** Registers a route, replacing any existing one for the same method+path. */
+    setRoute(route: OpenAPIRoute): void;
     registerSchema(name: string, schema: OpenAPISchema): void;
-    registerResponse(name: string, response: unknown): void;
+    registerResponse(name: string, response: OpenAPIResponse): void;
     registerParameter(name: string, parameter: OpenAPIParameter): void;
     registerRequestBody(name: string, body: OpenAPIRequestBody): void;
-    registerHeader(name: string, header: unknown): void;
-    registerExample(name: string, example: unknown): void;
+    registerHeader(name: string, header: OpenAPIHeader): void;
+    registerExample(name: string, example: OpenAPIExample): void;
     registerSecurityScheme(name: string, scheme: OpenAPISecurityScheme): void;
+    registerLink(name: string, link: OpenAPILink): void;
+    registerCallback(name: string, callback: Readonly<Record<string, OpenAPIPathItem>>): void;
     registerTag(tag: OpenAPITag): void;
-    ref(section: "schemas" | "responses" | "parameters" | "requestBodies" | "headers" | "examples" | "securitySchemes" | "links" | "callbacks", name: string): OpenAPIReference;
+    ref(section: ComponentSection, name: string): OpenAPIReference;
+    /** True when a component is registered under that section and name. */
+    hasComponent(section: ComponentSection, name: string): boolean;
     generate(): OpenAPIDocument;
     clear(): void;
 }

package/dist/openApiRegistry/openApiRegistry.type.js

@@ -1,3 +1,2 @@
-import { COMPONENT_REF_PREFIX, DEFAULT_OPENAPI_VERSION, } from "../openApiConstants/openApiConstants.core.js";
-import { OpenAPIComponentConflictError, OpenAPIDocumentError, OpenAPIOperationError, } from "../openApiErrors/openApiError.core.js";
+export {};
 //# sourceMappingURL=openApiRegistry.type.js.map

package/dist/openApiRouting/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Route metadata, conversion, and scanning for OpenAPI generation.
  */
-export type { RouteMetadata, RouteOpenAPIMetadata, RouteParameterMetadata, RouteInfo, } from "./routeScanner.core.js";
-export { toOpenAPIPath, convertRouteToOpenAPI, ZUDOLIB_TO_OPENAPI_METHODS, } from "./routeConverter.core.js";
+export type { RouteMetadata, RouteOpenAPIMetadata, RouteParameterMetadata, RouteInfo, OpenAPIHttpMethod, } from "./routeMetadata.type.js";
+export { toOpenAPIPath, extractPathParameters, convertRouteToOpenAPI, buildResponses, isOpenAPIMethod, ZUDOLIB_TO_OPENAPI_METHODS, } from "./routeConverter.core.js";
 export { OpenAPIRouteScannerImpl } from "./routeScanner.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/openApiRouting/index.js

@@ -3,6 +3,6 @@
  *
  * Route metadata, conversion, and scanning for OpenAPI generation.
  */
-export { toOpenAPIPath, convertRouteToOpenAPI, ZUDOLIB_TO_OPENAPI_METHODS, } from "./routeConverter.core.js";
+export { toOpenAPIPath, extractPathParameters, convertRouteToOpenAPI, buildResponses, isOpenAPIMethod, ZUDOLIB_TO_OPENAPI_METHODS, } from "./routeConverter.core.js";
 export { OpenAPIRouteScannerImpl } from "./routeScanner.core.js";
 //# sourceMappingURL=index.js.map

package/dist/openApiRouting/routeConverter.core.d.ts

@@ -1,22 +1,40 @@
-import type { OpenAPIOperation } from "../openApiTypes/openApiTypes.core.js";
-import type { RouteMetadata } from "./routeMetadata.type.js";
+import type { OpenAPIOperation, OpenAPIResponses } from "../openApiTypes/openApiTypes.core.js";
+import type { OpenAPIHttpMethod, RouteMetadata } from "./routeMetadata.type.js";
+/**
+ * Maps Zudojs HTTP methods to OpenAPI methods.
+ */
+export declare const ZUDOLIB_TO_OPENAPI_METHODS: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+/** True when `method` is one an OpenAPI path item can carry. */
+export declare function isOpenAPIMethod(method: string): method is OpenAPIHttpMethod;
 /**
  * Converts a Zudojs-style route path to an OpenAPI path template.
  *
  * Example:
- *   "/users/:id" -> "/users/{id}"
- *   "/users/:id?": throws (optional path params not supported in OpenAPI)
+ *   `/users/:id` → `/users/{id}`
+ *   `/users/{id}` → unchanged (already a template)
+ *   `/users/:id?` → throws (OpenAPI has no optional path parameters)
+ *   `/files/*` → throws (OpenAPI has no wildcard paths)
+ *
+ * Anything it cannot convert throws rather than passing through: an
+ * unconvertible segment that reaches the document produces an invalid path
+ * template, and the failure then surfaces in whatever consumes the spec
+ * rather than at the route that caused it.
  */
 export declare function toOpenAPIPath(path: string): string;
+/** Extracts the parameter names from an OpenAPI path template. */
+export declare function extractPathParameters(path: string): readonly string[];
 /**
- * Maps Zudojs HTTP methods to OpenAPI methods.
+ * Builds the `responses` object for an operation.
+ *
+ * Every documented response is carried through. Only when a route documents
+ * none at all is a `200` synthesized, because `responses` is required.
  */
-export declare const ZUDOLIB_TO_OPENAPI_METHODS: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+export declare function buildResponses(metadata?: RouteMetadata): OpenAPIResponses;
 /**
  * Converts a route with metadata into an OpenAPI operation.
  */
 export declare function convertRouteToOpenAPI(method: string, path: string, metadata?: RouteMetadata): {
-    method: string;
+    method: OpenAPIHttpMethod;
     path: string;
     operation: OpenAPIOperation;
 };