@zudojs/openapi 0.1.0 → 1.1.0

package/dist/openApiConstants/openApiConstants.core.js

@@ -8,7 +8,20 @@
  */
 export const DEFAULT_OPENAPI_VERSION = "3.1.0";
 /**
- * Maximum operation ID length allowed by OpenAPI.
+ * Every specification version this package can emit and validate.
+ */
+export const SUPPORTED_OPENAPI_VERSIONS = [
+    "3.0.0",
+    "3.0.1",
+    "3.0.2",
+    "3.0.3",
+    "3.1.0",
+    "3.1.1",
+];
+/**
+ * Maximum operation ID length. Not a specification limit — a practical one:
+ * operation IDs become function names in generated clients, and tooling
+ * routinely truncates beyond this.
  */
 export const MAX_OPERATION_ID_LENGTH = 128;
 /**
@@ -20,7 +33,7 @@ export const COMPONENT_REF_PREFIX = "#/components";
  */
 export const DEFAULT_MEDIA_TYPE = "application/json";
 /**
- * Status code categories.
+ * Status code categories, usable as OpenAPI response keys.
  */
 export const STATUS_CODE_CATEGORIES = {
     INFORMATIONAL: "1XX",
@@ -29,12 +42,18 @@ export const STATUS_CODE_CATEGORIES = {
     CLIENT_ERROR: "4XX",
     SERVER_ERROR: "5XX",
 };
+/** A response key is valid when it is `default`, `NXX`, or a status code. */
+export const RESPONSE_KEY_PATTERN = /^(default|[1-5](XX|\d{2}))$/;
+/** OpenAPI path template parameter, e.g. `{orderId}`. */
+export const PATH_TEMPLATE_PARAMETER = /\{([^{}]+)\}/g;
 /**
  * Default server URL.
  */
 export const DEFAULT_SERVER_URL = "http://localhost";
 /**
- * Cache TTL for generated documents (5 minutes).
+ * Default time a generated document stays cached before it is rebuilt.
+ *
+ * Applied by `OpenAPIManager`; pass `cacheTtlMs` to change or disable it.
  */
 export const DOCUMENT_CACHE_TTL_MS = 5 * 60 * 1000;
 //# sourceMappingURL=openApiConstants.core.js.map

package/dist/openApiDocument/index.d.ts

@@ -4,5 +4,5 @@
  * OpenAPI document builder.
  */
 export type { OpenAPIDocumentOptions } from "./openApiDocument.builder.js";
-export { OpenAPIDocumentBuilder } from "./openApiDocument.builder.js";
+export { OpenAPIDocumentBuilder, createOpenAPIDocumentBuilder, } from "./openApiDocument.builder.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/openApiDocument/index.js

@@ -3,5 +3,5 @@
  *
  * OpenAPI document builder.
  */
-export { OpenAPIDocumentBuilder } from "./openApiDocument.builder.js";
+export { OpenAPIDocumentBuilder, createOpenAPIDocumentBuilder, } from "./openApiDocument.builder.js";
 //# sourceMappingURL=index.js.map

package/dist/openApiDocument/openApiDocument.builder.d.ts

@@ -1,60 +1,47 @@
-import type { OpenAPIDocument } from "../openApiTypes/openApiTypes.core.js";
+import type { OpenAPIDocument, OpenAPIExample, OpenAPIHeader, OpenAPIInfo, OpenAPIParameter, OpenAPIPathItem, OpenAPIRequestBody, OpenAPIResponse, OpenAPISchema, OpenAPISecurityRequirement, OpenAPISecurityScheme, OpenAPIServer, OpenAPITag } from "../openApiTypes/openApiTypes.core.js";
+import type { OpenAPIRoute } from "../openApiRegistry/openApiRegistry.type.js";
 export interface OpenAPIDocumentOptions {
-    readonly info: {
-        readonly title: string;
-        readonly version: string;
-        readonly description?: string;
-        readonly summary?: string;
-        readonly termsOfService?: string;
-        readonly contact?: {
-            readonly name?: string;
-            readonly url?: string;
-            readonly email?: string;
-        };
-        readonly license?: {
-            readonly name: string;
-            readonly url?: string;
-        };
-    };
+    readonly info: OpenAPIInfo;
     readonly openapi?: string;
-    readonly servers?: readonly {
-        readonly url: string;
-        readonly description?: string;
-        readonly variables?: Readonly<Record<string, {
-            readonly enum?: readonly string[];
-            readonly default: string;
-            readonly description?: string;
-        }>>;
-    }[];
-    readonly tags?: readonly {
-        readonly name: string;
-        readonly description?: string;
-    }[];
-    readonly security?: readonly Record<string, readonly string[]>[];
+    readonly servers?: readonly OpenAPIServer[];
+    readonly tags?: readonly OpenAPITag[];
+    readonly security?: readonly OpenAPISecurityRequirement[];
 }
+/**
+ * Fluent builder for a document assembled by hand.
+ *
+ * It is a thin facade over {@link OpenAPIRegistryImpl}, so a document built
+ * this way and one generated from routes go through the same assembly and
+ * validation rules. Two independent assemblers is how the generated documents
+ * ended up unable to express servers, tags or security at all.
+ */
 export declare class OpenAPIDocumentBuilder {
-    private readonly document;
+    private readonly registry;
     constructor(options: OpenAPIDocumentOptions);
-    version(version: string): this;
-    addServer(server: {
-        readonly url: string;
-        readonly description?: string;
-        readonly variables?: Readonly<Record<string, {
-            readonly enum?: readonly string[];
-            readonly default: string;
-            readonly description?: string;
-        }>>;
-    }): this;
-    addTag(tag: {
-        readonly name: string;
-        readonly description?: string;
-    }): this;
-    addSecurity(security: Record<string, readonly string[]>): this;
-    addPath(path: string, pathItem: Record<string, unknown>): this;
-    addSchema(name: string, schema: unknown): this;
-    addResponse(name: string, response: unknown): this;
-    addParameter(name: string, parameter: unknown): this;
-    addSecurityScheme(name: string, scheme: unknown): this;
+    /** The document's `info` object. */
+    info(info: OpenAPIInfo): this;
+    addServer(server: OpenAPIServer): this;
+    addTag(tag: OpenAPITag): this;
+    addSecurity(security: OpenAPISecurityRequirement): this;
+    /** Adds one operation. Repeated method+path combinations replace. */
+    addRoute(route: OpenAPIRoute): this;
+    /**
+     * Adds a whole path item.
+     *
+     * Each operation on it is registered individually, so the document keeps
+     * one path entry per path with the methods merged, as the specification
+     * requires.
+     */
+    addPath(path: string, pathItem: OpenAPIPathItem): this;
+    addSchema(name: string, schema: OpenAPISchema): this;
+    addResponse(name: string, response: OpenAPIResponse): this;
+    addParameter(name: string, parameter: OpenAPIParameter): this;
+    addRequestBody(name: string, body: OpenAPIRequestBody): this;
+    addHeader(name: string, header: OpenAPIHeader): this;
+    addExample(name: string, example: OpenAPIExample): this;
+    addSecurityScheme(name: string, scheme: OpenAPISecurityScheme): this;
     build(): Readonly<OpenAPIDocument>;
 }
+/** Creates a document builder. */
+export declare function createOpenAPIDocumentBuilder(options: OpenAPIDocumentOptions): OpenAPIDocumentBuilder;
 //# sourceMappingURL=openApiDocument.builder.d.ts.map

package/dist/openApiDocument/openApiDocument.builder.js

@@ -1,106 +1,107 @@
+import { OpenAPIRegistryImpl } from "../openApiRegistry/openApiRegistry.core.js";
 import { DEFAULT_OPENAPI_VERSION } from "../openApiConstants/openApiConstants.core.js";
+/**
+ * Fluent builder for a document assembled by hand.
+ *
+ * It is a thin facade over {@link OpenAPIRegistryImpl}, so a document built
+ * this way and one generated from routes go through the same assembly and
+ * validation rules. Two independent assemblers is how the generated documents
+ * ended up unable to express servers, tags or security at all.
+ */
 export class OpenAPIDocumentBuilder {
-    document;
+    registry;
     constructor(options) {
-        this.document = {
-            openapi: options.openapi ?? DEFAULT_OPENAPI_VERSION,
-            info: { ...options.info },
-            servers: options.servers?.map((s) => ({ ...s })),
-            paths: {},
-            components: {},
-            security: options.security?.map((s) => ({ ...s })),
-            tags: options.tags?.map((t) => ({ ...t })),
-        };
+        this.registry = new OpenAPIRegistryImpl(options.openapi ?? DEFAULT_OPENAPI_VERSION);
+        this.registry.setInfo(options.info);
+        for (const server of options.servers ?? [])
+            this.registry.addServer(server);
+        for (const tag of options.tags ?? [])
+            this.registry.setTag(tag);
+        for (const requirement of options.security ?? []) {
+            this.registry.addSecurityRequirement(requirement);
+        }
     }
-    version(version) {
-        this.document.openapi = version;
+    /** The document's `info` object. */
+    info(info) {
+        this.registry.setInfo(info);
         return this;
     }
     addServer(server) {
-        this.document.servers = [...(this.document.servers ?? []), { ...server }];
+        this.registry.addServer(server);
         return this;
     }
     addTag(tag) {
-        this.document.tags = [...(this.document.tags ?? []), { ...tag }];
+        this.registry.setTag(tag);
         return this;
     }
     addSecurity(security) {
-        this.document.security = [
-            ...(this.document.security ?? []),
-            { ...security },
-        ];
+        this.registry.addSecurityRequirement(security);
+        return this;
+    }
+    /** Adds one operation. Repeated method+path combinations replace. */
+    addRoute(route) {
+        this.registry.setRoute(route);
         return this;
     }
+    /**
+     * Adds a whole path item.
+     *
+     * Each operation on it is registered individually, so the document keeps
+     * one path entry per path with the methods merged, as the specification
+     * requires.
+     */
     addPath(path, pathItem) {
-        this.document.paths[path] = pathItem;
+        const methods = [
+            "get",
+            "put",
+            "post",
+            "delete",
+            "options",
+            "head",
+            "patch",
+            "trace",
+        ];
+        for (const method of methods) {
+            const operation = pathItem[method];
+            if (operation)
+                this.registry.setRoute({ method, path, operation });
+        }
         return this;
     }
     addSchema(name, schema) {
-        const components = this.document.components ?? {};
-        this.document.components = {
-            ...components,
-            schemas: { ...(components.schemas ?? {}), [name]: schema },
-        };
+        this.registry.registerSchema(name, schema);
         return this;
     }
     addResponse(name, response) {
-        const components = this.document.components ?? {};
-        this.document.components = {
-            ...components,
-            responses: { ...(components.responses ?? {}), [name]: response },
-        };
+        this.registry.registerResponse(name, response);
         return this;
     }
     addParameter(name, parameter) {
-        const components = this.document.components ?? {};
-        this.document.components = {
-            ...components,
-            parameters: { ...(components.parameters ?? {}), [name]: parameter },
-        };
+        this.registry.registerParameter(name, parameter);
+        return this;
+    }
+    addRequestBody(name, body) {
+        this.registry.registerRequestBody(name, body);
+        return this;
+    }
+    addHeader(name, header) {
+        this.registry.registerHeader(name, header);
+        return this;
+    }
+    addExample(name, example) {
+        this.registry.registerExample(name, example);
         return this;
     }
     addSecurityScheme(name, scheme) {
-        const components = this.document.components ?? {};
-        this.document.components = {
-            ...components,
-            securitySchemes: {
-                ...(components.securitySchemes ?? {}),
-                [name]: scheme,
-            },
-        };
+        this.registry.registerSecurityScheme(name, scheme);
         return this;
     }
     build() {
-        const paths = Object.keys(this.document.paths).length === 0
-            ? {}
-            : this.document.paths;
-        const components = {};
-        if (this.document.components) {
-            for (const [key, value] of Object.entries(this.document.components)) {
-                if (value &&
-                    typeof value === "object" &&
-                    Object.keys(value).length > 0) {
-                    components[key] = Object.freeze({ ...value });
-                }
-            }
-        }
-        return Object.freeze({
-            openapi: this.document.openapi,
-            info: Object.freeze(this.document.info),
-            servers: this.document.servers?.length
-                ? Object.freeze(this.document.servers)
-                : undefined,
-            paths: Object.freeze(paths),
-            ...(Object.keys(components).length > 0
-                ? { components: Object.freeze(components) }
-                : {}),
-            security: this.document.security?.length
-                ? Object.freeze(this.document.security)
-                : undefined,
-            tags: this.document.tags?.length
-                ? Object.freeze(this.document.tags)
-                : undefined,
-        });
+        return this.registry.generate();
     }
 }
+/** Creates a document builder. */
+export function createOpenAPIDocumentBuilder(options) {
+    return new OpenAPIDocumentBuilder(options);
+}
 //# sourceMappingURL=openApiDocument.builder.js.map

package/dist/openApiErrors/index.d.ts

@@ -3,6 +3,6 @@
  *
  * OpenAPI-specific error classes.
  */
-export { OpenAPIError, OpenAPIValidationError, OpenAPIDocumentError, OpenAPIComponentError, OpenAPIComponentConflictError, OpenAPIReferenceError, OpenAPIRouteError, OpenAPISchemaError, OpenAPISerializationError, OpenAPIVersionError, OpenAPIOperationError, createOpenAPIError, isOpenAPIError, } from "./openApiError.core.js";
-export type { OpenAPIErrorOptions, OpenAPIValidationIssue, } from "./openApiError.core.js";
+export { OpenAPIError, createOpenAPIError, isOpenAPIError, type OpenAPIErrorOptions, } from "./openApiError.base.js";
+export { OpenAPIValidationError, OpenAPIDocumentError, OpenAPIComponentError, OpenAPIComponentConflictError, OpenAPIReferenceError, OpenAPIRouteError, OpenAPISchemaError, OpenAPISerializationError, OpenAPIVersionError, OpenAPIOperationError, formatIssuePath, type OpenAPIValidationIssue, } from "./openApiError.types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/openApiErrors/index.js

@@ -3,5 +3,6 @@
  *
  * OpenAPI-specific error classes.
  */
-export { OpenAPIError, OpenAPIValidationError, OpenAPIDocumentError, OpenAPIComponentError, OpenAPIComponentConflictError, OpenAPIReferenceError, OpenAPIRouteError, OpenAPISchemaError, OpenAPISerializationError, OpenAPIVersionError, OpenAPIOperationError, createOpenAPIError, isOpenAPIError, } from "./openApiError.core.js";
+export { OpenAPIError, createOpenAPIError, isOpenAPIError, } from "./openApiError.base.js";
+export { OpenAPIValidationError, OpenAPIDocumentError, OpenAPIComponentError, OpenAPIComponentConflictError, OpenAPIReferenceError, OpenAPIRouteError, OpenAPISchemaError, OpenAPISerializationError, OpenAPIVersionError, OpenAPIOperationError, formatIssuePath, } from "./openApiError.types.js";
 //# sourceMappingURL=index.js.map

package/dist/openApiErrors/openApiError.base.d.ts

@@ -1,11 +1,20 @@
 /**
  * Base OpenAPI error and factory functions.
+ *
+ * Everything in this package runs while a service builds or validates its own
+ * specification — none of it is triggered by a client request. So the
+ * defaults are the server-side ones: status 500, not exposed. A document that
+ * fails to build is an operator's problem, and leaking component names or
+ * version mismatches into a client-visible body tells an attacker about the
+ * shape of the API rather than telling the operator anything.
  */
 import { BaseError } from "@zudojs/errors";
 /** Options for creating an OpenAPI error. */
 export interface OpenAPIErrorOptions {
     readonly code?: string;
+    /** Overrides the subclass's default status. */
     readonly statusCode?: number;
+    /** Overrides the subclass's default exposure. */
     readonly expose?: boolean;
     readonly cause?: unknown;
     readonly metadata?: Readonly<Record<string, unknown>>;

package/dist/openApiErrors/openApiError.base.js

@@ -1,5 +1,12 @@
 /**
  * Base OpenAPI error and factory functions.
+ *
+ * Everything in this package runs while a service builds or validates its own
+ * specification — none of it is triggered by a client request. So the
+ * defaults are the server-side ones: status 500, not exposed. A document that
+ * fails to build is an operator's problem, and leaking component names or
+ * version mismatches into a client-visible body tells an attacker about the
+ * shape of the API rather than telling the operator anything.
  */
 import { BaseError, ErrorCode, ErrorCategory, ErrorSeverity, } from "@zudojs/errors";
 /** Base error for all OpenAPI subsystem failures. */

package/dist/openApiErrors/openApiError.types.d.ts

@@ -1,10 +1,32 @@
 /**
  * Specific OpenAPI error subclasses.
+ *
+ * Each subclass supplies a default `code`, `statusCode` and `expose`, and each
+ * lets the caller override them — the options are spread *after* the defaults,
+ * so a value passed in is the value used.
  */
 import { OpenAPIError, type OpenAPIErrorOptions } from "./openApiError.base.js";
-/** Error thrown when OpenAPI validation fails. */
+/** A single validation issue. */
+export interface OpenAPIValidationIssue {
+    /** Location of the problem, as a path through the document. */
+    readonly path: readonly (string | number)[];
+    readonly message: string;
+    readonly severity: "error" | "warning";
+}
+/** Renders an issue path the way a reader would write it. */
+export declare function formatIssuePath(path: readonly (string | number)[]): string;
+/**
+ * Error thrown when OpenAPI validation fails.
+ *
+ * The issues are kept on the error. Discarding them left callers with the
+ * message "OpenAPI validation failed." and no way to learn what was wrong
+ * short of re-running the validator.
+ */
 export declare class OpenAPIValidationError extends OpenAPIError {
-    constructor(message: string, issues?: readonly unknown[], options?: OpenAPIErrorOptions);
+    readonly issues: readonly OpenAPIValidationIssue[];
+    constructor(message: string, issues?: readonly OpenAPIValidationIssue[], options?: OpenAPIErrorOptions);
+    /** A multi-line summary suitable for a log line or a CLI. */
+    format(): string;
 }
 /** Error thrown when the OpenAPI document is invalid. */
 export declare class OpenAPIDocumentError extends OpenAPIError {
@@ -14,15 +36,18 @@ export declare class OpenAPIDocumentError extends OpenAPIError {
 export declare class OpenAPIComponentError extends OpenAPIError {
     constructor(message: string, options?: OpenAPIErrorOptions);
 }
-/** Error thrown when an OpenAPI component conflicts with an existing component. */
+/** Error thrown when a component name is already registered. */
 export declare class OpenAPIComponentConflictError extends OpenAPIError {
-    constructor(message: string, options?: OpenAPIErrorOptions);
+    readonly section: string;
+    readonly componentName: string;
+    constructor(section: string, componentName: string, options?: OpenAPIErrorOptions);
 }
-/** Error thrown when an OpenAPI reference is invalid. */
+/** Error thrown when an OpenAPI reference is invalid or cannot be resolved. */
 export declare class OpenAPIReferenceError extends OpenAPIError {
-    constructor(message: string, options?: OpenAPIErrorOptions);
+    readonly reference: string;
+    constructor(reference: string, options?: OpenAPIErrorOptions);
 }
-/** Error thrown when an OpenAPI route is invalid. */
+/** Error thrown when an OpenAPI route cannot be converted. */
 export declare class OpenAPIRouteError extends OpenAPIError {
     constructor(message: string, options?: OpenAPIErrorOptions);
 }
@@ -36,16 +61,11 @@ export declare class OpenAPISerializationError extends OpenAPIError {
 }
 /** Error thrown when the OpenAPI version is unsupported. */
 export declare class OpenAPIVersionError extends OpenAPIError {
-    constructor(message: string, options?: OpenAPIErrorOptions);
+    readonly version: string;
+    constructor(version: string, supported?: readonly string[], options?: OpenAPIErrorOptions);
 }
 /** Error thrown when an OpenAPI operation is invalid. */
 export declare class OpenAPIOperationError extends OpenAPIError {
     constructor(message: string, options?: OpenAPIErrorOptions);
 }
-/** A single validation issue. */
-export interface OpenAPIValidationIssue {
-    readonly path: readonly (string | number)[];
-    readonly message: string;
-    readonly severity: "error" | "warning";
-}
 //# sourceMappingURL=openApiError.types.d.ts.map