@zudojs/openapi 0.1.0 → 1.2.0

package/dist/openApiErrors/openApiError.types.js

@@ -1,27 +1,62 @@
 /**
  * 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 } from "./openApiError.base.js";
-/** Error thrown when OpenAPI validation fails. */
+/** Renders an issue path the way a reader would write it. */
+export function formatIssuePath(path) {
+    return path
+        .map((segment) => (typeof segment === "number" ? `[${segment}]` : segment))
+        .join(".")
+        .replace(/\.\[/g, "[");
+}
+/**
+ * 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 class OpenAPIValidationError extends OpenAPIError {
-    constructor(message, issues, options = {}) {
+    issues;
+    constructor(message, issues = [], options = {}) {
         super(message, {
+            code: "OPENAPI_VALIDATION",
+            statusCode: 500,
+            expose: false,
             ...options,
-            code: options.code ?? "OPENAPI_VALIDATION",
-            statusCode: 400,
-            expose: true,
+            metadata: {
+                issueCount: issues.length,
+                issues: issues.map((issue) => ({
+                    path: formatIssuePath(issue.path),
+                    message: issue.message,
+                    severity: issue.severity,
+                })),
+                ...(options.metadata ?? {}),
+            },
         });
         this.name = "OpenAPIValidationError";
+        this.issues = Object.freeze([...issues]);
+    }
+    /** A multi-line summary suitable for a log line or a CLI. */
+    format() {
+        if (this.issues.length === 0)
+            return this.message;
+        const lines = this.issues.map((issue) => `  ${issue.severity}: ${formatIssuePath(issue.path)} — ${issue.message}`);
+        return [this.message, ...lines].join("\n");
     }
 }
 /** Error thrown when the OpenAPI document is invalid. */
 export class OpenAPIDocumentError extends OpenAPIError {
     constructor(message, options = {}) {
         super(message, {
-            ...options,
-            code: options.code ?? "OPENAPI_DOCUMENT",
+            code: "OPENAPI_DOCUMENT",
             statusCode: 500,
             expose: false,
+            ...options,
         });
         this.name = "OpenAPIDocumentError";
     }
@@ -30,46 +65,55 @@ export class OpenAPIDocumentError extends OpenAPIError {
 export class OpenAPIComponentError extends OpenAPIError {
     constructor(message, options = {}) {
         super(message, {
-            ...options,
-            code: options.code ?? "OPENAPI_COMPONENT",
+            code: "OPENAPI_COMPONENT",
             statusCode: 500,
             expose: false,
+            ...options,
         });
         this.name = "OpenAPIComponentError";
     }
 }
-/** Error thrown when an OpenAPI component conflicts with an existing component. */
+/** Error thrown when a component name is already registered. */
 export class OpenAPIComponentConflictError extends OpenAPIError {
-    constructor(message, options = {}) {
-        super(message, {
+    section;
+    componentName;
+    constructor(section, componentName, options = {}) {
+        super(`A component named "${componentName}" is already registered under "${section}". ` +
+            `Component names must be unique within a section.`, {
+            code: "OPENAPI_COMPONENT_CONFLICT",
+            statusCode: 500,
+            expose: false,
             ...options,
-            code: options.code ?? "OPENAPI_COMPONENT_CONFLICT",
-            statusCode: 409,
-            expose: true,
+            metadata: { section, componentName, ...(options.metadata ?? {}) },
         });
         this.name = "OpenAPIComponentConflictError";
+        this.section = section;
+        this.componentName = componentName;
     }
 }
-/** Error thrown when an OpenAPI reference is invalid. */
+/** Error thrown when an OpenAPI reference is invalid or cannot be resolved. */
 export class OpenAPIReferenceError extends OpenAPIError {
-    constructor(message, options = {}) {
-        super(message, {
+    reference;
+    constructor(reference, options = {}) {
+        super(`Unresolvable OpenAPI reference: "${reference}".`, {
+            code: "OPENAPI_REFERENCE",
+            statusCode: 500,
+            expose: false,
             ...options,
-            code: options.code ?? "OPENAPI_REFERENCE",
-            statusCode: 400,
-            expose: true,
+            metadata: { reference, ...(options.metadata ?? {}) },
         });
         this.name = "OpenAPIReferenceError";
+        this.reference = reference;
     }
 }
-/** Error thrown when an OpenAPI route is invalid. */
+/** Error thrown when an OpenAPI route cannot be converted. */
 export class OpenAPIRouteError extends OpenAPIError {
     constructor(message, options = {}) {
         super(message, {
-            ...options,
-            code: options.code ?? "OPENAPI_ROUTE",
+            code: "OPENAPI_ROUTE",
             statusCode: 500,
             expose: false,
+            ...options,
         });
         this.name = "OpenAPIRouteError";
     }
@@ -78,10 +122,10 @@ export class OpenAPIRouteError extends OpenAPIError {
 export class OpenAPISchemaError extends OpenAPIError {
     constructor(message, options = {}) {
         super(message, {
-            ...options,
-            code: options.code ?? "OPENAPI_SCHEMA",
+            code: "OPENAPI_SCHEMA",
             statusCode: 500,
             expose: false,
+            ...options,
         });
         this.name = "OpenAPISchemaError";
     }
@@ -90,34 +134,38 @@ export class OpenAPISchemaError extends OpenAPIError {
 export class OpenAPISerializationError extends OpenAPIError {
     constructor(message, options = {}) {
         super(message, {
-            ...options,
-            code: options.code ?? "OPENAPI_SERIALIZATION",
+            code: "OPENAPI_SERIALIZATION",
             statusCode: 500,
             expose: false,
+            ...options,
         });
         this.name = "OpenAPISerializationError";
     }
 }
 /** Error thrown when the OpenAPI version is unsupported. */
 export class OpenAPIVersionError extends OpenAPIError {
-    constructor(message, options = {}) {
-        super(message, {
+    version;
+    constructor(version, supported = [], options = {}) {
+        super(`Unsupported OpenAPI version "${version}".` +
+            (supported.length > 0 ? ` Supported: ${supported.join(", ")}.` : ""), {
+            code: "OPENAPI_VERSION",
+            statusCode: 500,
+            expose: false,
             ...options,
-            code: options.code ?? "OPENAPI_VERSION",
-            statusCode: 400,
-            expose: true,
+            metadata: { version, supported, ...(options.metadata ?? {}) },
         });
         this.name = "OpenAPIVersionError";
+        this.version = version;
     }
 }
 /** Error thrown when an OpenAPI operation is invalid. */
 export class OpenAPIOperationError extends OpenAPIError {
     constructor(message, options = {}) {
         super(message, {
-            ...options,
-            code: options.code ?? "OPENAPI_OPERATION",
+            code: "OPENAPI_OPERATION",
             statusCode: 500,
             expose: false,
+            ...options,
         });
         this.name = "OpenAPIOperationError";
     }

package/dist/openApiHttp/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @zudojs/openapi/openApiHttp
  *
- * HTTP integration for OpenAPI document serving.
+ * Document coordination and HTTP serving.
  */
-export { OpenAPIManager } from "./openApiHttpAdapter.core.js";
+export { OpenAPIManager, createOpenAPIManager, type OpenAPIManagerOptions, type OpenAPIDocumentResponse, type OpenAPIUIResponse, } from "./openApiHttpAdapter.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/openApiHttp/index.js

@@ -1,7 +1,7 @@
 /**
  * @zudojs/openapi/openApiHttp
  *
- * HTTP integration for OpenAPI document serving.
+ * Document coordination and HTTP serving.
  */
-export { OpenAPIManager } from "./openApiHttpAdapter.core.js";
+export { OpenAPIManager, createOpenAPIManager, } from "./openApiHttpAdapter.core.js";
 //# sourceMappingURL=index.js.map

package/dist/openApiHttp/openApiHttpAdapter.core.d.ts

@@ -1,38 +1,142 @@
-import type { OpenAPIDocument } from "../openApiTypes/openApiTypes.core.js";
-import { OpenAPIRegistryImpl } from "../openApiRegistry/openApiRegistry.core.js";
-import { OpenAPIRouteScannerImpl } from "../openApiRouting/routeScanner.core.js";
+import type { OpenAPIDocument, OpenAPIInfo, OpenAPILogo, OpenAPISchema, OpenAPISecurityRequirement, OpenAPISecurityScheme, OpenAPIServer, OpenAPITag } from "../openApiTypes/openApiTypes.core.js";
+import type { RouteInfo, OpenAPIHttpMethod } from "../openApiRouting/routeMetadata.type.js";
+import { type OpenAPIValidationResult } from "../openApiValidation/openApiValidator.core.js";
+import { type OpenAPIUIOptions } from "../openApiUi/openApiUi.core.js";
+/** Options for {@link OpenAPIManager}. */
+export interface OpenAPIManagerOptions {
+    /** Specification version to emit. Default: 3.1.0. */
+    readonly version?: string;
+    /** Document metadata. Without it the document is titled "API" at 0.0.0. */
+    readonly info?: OpenAPIInfo;
+    readonly servers?: readonly OpenAPIServer[];
+    readonly tags?: readonly OpenAPITag[];
+    readonly security?: readonly OpenAPISecurityRequirement[];
+    /**
+     * How long a generated document is reused before it is rebuilt, in ms.
+     * Default: five minutes. `0` disables caching. Mutating the manager
+     * invalidates the cache regardless.
+     */
+    readonly cacheTtlMs?: number;
+    /** Reports what a schema conversion could not express. */
+    readonly onSchemaWarning?: (name: string, warnings: readonly string[]) => void;
+    /** Supplies the clock, for tests. */
+    readonly now?: () => number;
+    /**
+     * Logo written to `info["x-logo"]` so viewers such as ReDoc and Scalar
+     * show it, and used by {@link OpenAPIManager.toUIResponse}.
+     * Default: the Zudo mark. Pass `false` to emit no logo, or an
+     * {@link OpenAPILogo} to use your own.
+     */
+    readonly branding?: boolean | OpenAPILogo;
+}
+/** An HTTP response carrying a rendered documentation page. */
+export interface OpenAPIUIResponse {
+    readonly status: 200;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+/** An HTTP response carrying the specification document. */
+export interface OpenAPIDocumentResponse {
+    readonly status: 200;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
 /**
- * High-level OpenAPI manager that coordinates generation, validation, and serving.
+ * High-level OpenAPI manager that coordinates generation, validation, and
+ * serving.
+ *
+ * Every mutation invalidates the cached document, so a route added after a
+ * first `generate()` appears in the next one, and regeneration is idempotent
+ * rather than throwing on the routes it registered last time.
  */
 export declare class OpenAPIManager {
     private readonly registry;
     private readonly scanner;
     private readonly validator;
+    private readonly schemas;
+    private readonly cacheTtlMs;
+    private readonly now;
+    private readonly logo;
+    /** True when `branding` was a caller-supplied logo rather than the default. */
+    private readonly customLogo;
     private cachedDocument?;
-    constructor(version?: string);
-    get registryInstance(): OpenAPIRegistryImpl;
-    get scannerInstance(): OpenAPIRouteScannerImpl;
-    addRoute(route: {
-        readonly method: "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
-        readonly path: string;
-        readonly metadata?: {
-            readonly openapi?: {
-                readonly operationId?: string;
-                readonly summary?: string;
-                readonly description?: string;
-                readonly tags?: readonly string[];
-                readonly responses?: Record<string, unknown>;
-                readonly requestBody?: unknown;
-                readonly parameters?: readonly unknown[];
-                readonly security?: readonly Record<string, readonly string[]>[];
-            };
-        };
-    }): void;
-    addSchema(name: string, schema: unknown): void;
+    private cachedAt;
+    /** Whether the cached document was produced by a validating generate. */
+    private cachedValidated;
+    constructor(versionOrOptions?: string | OpenAPIManagerOptions);
+    /** The document version this manager emits. */
+    get version(): string;
+    /** Sets the document's `info` object. */
+    setInfo(info: OpenAPIInfo): this;
+    addServer(server: OpenAPIServer): this;
+    addTag(tag: OpenAPITag): this;
+    addSecurityRequirement(requirement: OpenAPISecurityRequirement): this;
+    addSecurityScheme(name: string, scheme: OpenAPISecurityScheme): this;
+    /** Registers a route. Duplicate method+path combinations are rejected. */
+    addRoute(route: RouteInfo): this;
+    /** Registers a route, replacing any existing one for the same method+path. */
+    setRoute(route: RouteInfo): this;
+    /** Removes a route. Returns whether one was removed. */
+    removeRoute(method: OpenAPIHttpMethod, path: string): boolean;
+    /**
+     * Registers a component schema.
+     *
+     * `schema` is converted from a `@zudojs/schema` schema; pass an already
+     * converted {@link OpenAPISchema} to {@link OpenAPIManager.addRawSchema}.
+     */
+    addSchema(name: string, schema: unknown): this;
+    /** Registers an already-converted OpenAPI schema. */
+    addRawSchema(name: string, schema: OpenAPISchema): this;
+    /** Conversion warnings, keyed by component name. */
+    schemaWarnings(): ReadonlyMap<string, readonly string[]>;
+    /**
+     * Builds the document from the registered routes and components.
+     *
+     * Safe to call repeatedly: routes are replaced rather than re-added.
+     */
     generate(validate?: boolean): OpenAPIDocument;
-    getDocument(validate?: boolean): Readonly<OpenAPIDocument>;
+    /**
+     * Returns the document, rebuilding it when the cache is stale, absent, or
+     * was produced without the validation this call asks for.
+     */
+    getDocument(validate?: boolean): OpenAPIDocument;
+    private isCacheFresh;
+    /** Validates the current document without throwing. */
+    validate(): OpenAPIValidationResult;
+    /** Drops the cached document. Called automatically by every mutation. */
+    invalidateCache(): this;
+    /** Drops every registered route, component and the cached document. */
+    reset(): this;
+    /**
+     * @deprecated Use {@link OpenAPIManager.reset} — the old name cleared all
+     * registered routes, which is not what "invalidate" suggests.
+     */
     invalidate(): void;
     toJSON(validate?: boolean): string;
     toYAML(validate?: boolean): string;
+    /**
+     * Builds an HTTP response carrying the document.
+     *
+     * Framework-agnostic on purpose: `{ status, headers, body }` is what every
+     * adapter in this monorepo can turn into its own response type.
+     */
+    toResponse(options?: {
+        readonly format?: "json" | "yaml";
+        readonly validate?: boolean;
+        readonly cacheControl?: string;
+    }): OpenAPIDocumentResponse;
+    /**
+     * Builds an HTTP response carrying a branded documentation page (Swagger UI
+     * by default, ReDoc on request) that loads the specification from
+     * `options.specUrl`. Pair it with {@link OpenAPIManager.toResponse}:
+     *
+     * ```ts
+     * app.get("/openapi.json", () => manager.toResponse());
+     * app.get("/docs", () => manager.toUIResponse({ specUrl: "/openapi.json" }));
+     * ```
+     */
+    toUIResponse(options: OpenAPIUIOptions): OpenAPIUIResponse;
 }
+/** Creates an OpenAPI manager. */
+export declare function createOpenAPIManager(options?: OpenAPIManagerOptions): OpenAPIManager;
 //# sourceMappingURL=openApiHttpAdapter.core.d.ts.map