@zudojs/openapi 1.1.0 → 1.2.0

package/README.md

@@ -101,9 +101,12 @@ manager.toUIResponse({ specUrl: "/openapi.json", assetsBaseUrl: "/vendor/swagger
 ```
 
 Caller-supplied text is escaped, and input that would break out of the page is
-refused rather than mangled: a `javascript:` or `vbscript:` URL throws, an
-empty `specUrl` throws, and `customCss` containing `</style>` throws — that
-sequence ends the style block and lets the rest be parsed as HTML.
+refused rather than mangled: a `javascript:` or `vbscript:` URL throws (the
+scheme is read after stripping the control characters browsers ignore, so
+`java\nscript:` is caught too), a `data:` URL that is not an image throws
+(the assets base lands in `<script src>`), an empty `specUrl` throws, and
+`customCss` containing `</style>` throws — that sequence ends the style block
+and lets the rest be parsed as HTML.
 
 ## Branding
 
@@ -180,9 +183,16 @@ produces
 
 Objects, arrays, enums, literals, unions, discriminated unions,
 intersections, records, tuples, sets, optionals, nullables, defaults,
-refinements, transforms, lazy schemas and the coercion wrappers are all
-converted, along with string and number constraints (`min`, `max`, `length`,
-`pattern`, `format`, `int`, `multipleOf`, `gt`, `lt`).
+refinements, transforms, lazy schemas, bigints and the coercion wrappers are
+all converted, along with string and number constraints (`min`, `max`,
+`length`, `pattern`, `format`, `int`, `multipleOf`, `gt`, `lt`). Constraints
+on a coercing schema (`coerce.number().int().min(1)`) are carried through.
+
+A property is listed in `required` exactly when the object parser rejects
+its absence: fields wrapped in `optional`, fields with a `default`, and
+`any` / `unknown` fields are left out, and `.required()` forces every key
+back on. A default supplied as a factory (`.default(() => new Date())`) is
+invoked once and its value emitted.
 
 Anything that cannot be expressed exactly produces a **warning** rather than a
 silent `{}`:
@@ -259,7 +269,10 @@ The validator checks:
 - that path templates and `in: "path"` parameters agree in both directions —
   the classic "`{id}` is in the path but nowhere in `parameters`" mistake
 - that path parameters are marked required, and that no parameter is declared
-  twice
+  twice in one list (an operation-level parameter may override a path-level
+  one with the same name and location)
+- that no two paths are identical apart from their template parameter names
+  (`/users/{id}` next to `/users/{userId}`)
 - `operationId` uniqueness and length
 - that every `security` requirement names a scheme declared in
   `components.securitySchemes` — a typo there yields a document that _looks_

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

@@ -57,6 +57,8 @@ export declare class OpenAPIManager {
     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?;
     private cachedAt;
     /** Whether the cached document was produced by a validating generate. */

package/dist/openApiHttp/openApiHttpAdapter.core.js

@@ -21,6 +21,8 @@ export class OpenAPIManager {
     cacheTtlMs;
     now;
     logo;
+    /** True when `branding` was a caller-supplied logo rather than the default. */
+    customLogo;
     cachedDocument;
     cachedAt = 0;
     /** Whether the cached document was produced by a validating generate. */
@@ -44,6 +46,8 @@ export class OpenAPIManager {
                 : options.branding === true || options.branding === undefined
                     ? zudoLogo()
                     : options.branding;
+        this.customLogo =
+            typeof options.branding === "object" && options.branding !== null;
         if (options.info)
             this.registry.setInfo(options.info);
         for (const server of options.servers ?? [])
@@ -124,6 +128,11 @@ export class OpenAPIManager {
      * Safe to call repeatedly: routes are replaced rather than re-added.
      */
     generate(validate = false) {
+        // The scanner is the source of truth for routes. Re-setting on top of
+        // the previous route set kept routes that had since been removed or
+        // hidden, so `removeRoute()` had no effect once a document had been
+        // generated.
+        this.registry.clearRoutes();
         for (const route of this.scanner.scan()) {
             this.registry.setRoute(route);
         }
@@ -234,11 +243,16 @@ export class OpenAPIManager {
                 ? `${info.title} · API reference`
                 : undefined,
             ...options,
+            // Precedence: an explicit page logo, then the manager's `branding`
+            // (a custom logo is used as-is; `false` renders none), then the
+            // page's own default wordmark.
             logo: options.logo !== undefined
                 ? options.logo
                 : this.logo === undefined
                     ? false
-                    : undefined,
+                    : this.customLogo
+                        ? this.logo
+                        : undefined,
         });
         return Object.freeze({
             status: 200,

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

@@ -35,6 +35,15 @@ export declare class OpenAPIRegistryImpl implements OpenAPIRegistry {
      * `generate()` twice failed.
      */
     setRoute(route: OpenAPIRoute): void;
+    /** Removes a route. Returns whether one was registered. */
+    removeRoute(method: string, path: string): boolean;
+    /**
+     * Drops every registered route while keeping components, servers, tags
+     * and security. `OpenAPIManager.generate()` rebuilds the route set from
+     * its scanner on each call; without this a route removed from the
+     * scanner lived on in the registry and in every later document.
+     */
+    clearRoutes(): void;
     private static register;
     registerSchema(name: string, schema: OpenAPISchema): void;
     registerResponse(name: string, response: OpenAPIResponse): void;

package/dist/openApiRegistry/openApiRegistry.core.js

@@ -77,6 +77,19 @@ export class OpenAPIRegistryImpl {
             }),
         });
     }
+    /** Removes a route. Returns whether one was registered. */
+    removeRoute(method, path) {
+        return this.routes.delete(OpenAPIRegistryImpl.routeKey({ method, path }));
+    }
+    /**
+     * Drops every registered route while keeping components, servers, tags
+     * and security. `OpenAPIManager.generate()` rebuilds the route set from
+     * its scanner on each call; without this a route removed from the
+     * scanner lived on in the registry and in every later document.
+     */
+    clearRoutes() {
+        this.routes.clear();
+    }
     static register(map, section, name, value) {
         if (map.has(name)) {
             throw new OpenAPIComponentConflictError(section, name);

package/dist/openApiSchema/schemaConverter.core.d.ts

@@ -14,14 +14,24 @@ import type { OpenAPISchema } from "../openApiTypes/openApiTypes.core.js";
  *   array    `_config.itemSchema`, `_config.min`, `_config.max`, `_config.length`
  *   string   `_config.min|max|length|pattern|format`
  *   number   `_config.min|max|int|gt|lt|multipleOf`
+ *   coerce.string / coerce.number
+ *            `_constraints` — the wrapped StringSchema / NumberSchema that
+ *            carries the `_config` above
  *   union    `_schemas`          intersection `_left` / `_right`
  *   enum     `_values`           literal      `_expected`
  *   optional `_inner`            nullable     `_inner`
- *   default  `_inner`, `_defaultValue`        refine `_inner`
- *   transform `_base`            lazy         `_factory` / `_inner`
+ *   default  `_inner`, `_defaultValue` (a value or a factory function)
+ *   refine   `_inner`
+ *   transform `_inner` (`schema.transform(...)`, TransformModifierSchema)
+ *             or `_base` (the standalone TransformSchema class)
+ *   lazy     `_factory` / `_inner`
  *   record   `_keySchema`, `_valueSchema`     tuple  `_schemas`
  *   map      `_keySchema`, `_valueSchema`     set    `_valueSchema`
  *   metadata `_metadata` (description, example, title, deprecated)
+ *
+ * Object parsing accepts a missing key when the field schema is one of
+ * `optional`, `default`, `any` or `unknown` (`ACCEPTS_UNDEFINED` in
+ * schemaObject.core.ts), so exactly those are left out of `required`.
  */
 export interface SchemaConversionResult {
     readonly schema: OpenAPISchema;

package/dist/openApiSchema/schemaConverter.core.js

@@ -33,8 +33,50 @@ function isSchemaLike(value) {
         value !== null &&
         typeof value._type === "string");
 }
-function isOptionalSchema(value) {
-    return isSchemaLike(value) && value._type === "optional";
+/**
+ * Field schemas for which `ObjectSchema` accepts a missing key. Mirrors
+ * `ACCEPTS_UNDEFINED` in `@zudojs/schema`: a field with a default is filled
+ * in when absent, so documenting it as `required` publishes a contract
+ * stricter than the code that validates against it.
+ */
+const ACCEPTS_MISSING_KEY = new Set([
+    "optional",
+    "default",
+    "any",
+    "unknown",
+]);
+function acceptsMissingKey(value) {
+    return isSchemaLike(value) && ACCEPTS_MISSING_KEY.has(value._type);
+}
+/**
+ * The schema a `coerce.*` wrapper delegates its constraints to.
+ *
+ * `s.coerce.number().int().min(1)` keeps `int` and `min` on the wrapped
+ * `NumberSchema` under `_constraints`, not on the wrapper's own `_config`;
+ * reading the wrapper alone yields a bare `{ type: "number" }`.
+ */
+function coercionTarget(schema) {
+    const constraints = schema["_constraints"];
+    return isSchemaLike(constraints) ? constraints : schema;
+}
+/**
+ * Resolves a `default` schema's value, which may be a factory function.
+ *
+ * A factory (`.default(() => new Date())`) is invoked once for the document.
+ * Emitting the function itself produces a `default` that `JSON.stringify`
+ * silently drops and the YAML serializer renders as source text.
+ */
+function resolveDefaultValue(schema, state) {
+    const raw = schema["_defaultValue"];
+    if (typeof raw !== "function")
+        return raw;
+    try {
+        return raw();
+    }
+    catch (error) {
+        state.warnings.push(`A \`default\` factory threw and its value was omitted: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
 }
 function extractMeta(schema) {
     const meta = schema._metadata;
@@ -225,14 +267,17 @@ function convertSchemaNode(schema, state) {
     const c = config(schema);
     switch (schema._type) {
         case "string":
-        case "coerce.string":
             return convertString(schema, state);
+        case "coerce.string":
+            return convertString(coercionTarget(schema), state);
         case "number":
-        case "coerce.number":
             return convertNumber(schema, state);
+        case "coerce.number":
+            return convertNumber(coercionTarget(schema), state);
         case "boolean":
         case "coerce.boolean":
             return { type: "boolean" };
+        case "bigint":
         case "coerce.bigint":
             return { type: "string", format: "int64" };
         case "null":
@@ -256,10 +301,11 @@ function convertSchemaNode(schema, state) {
             const required = [];
             for (const [key, value] of Object.entries(shape)) {
                 defineProperty(properties, key, convertNode(value, state));
-                // A field is required unless it is wrapped in `optional`. An explicit
+                // A field is required unless the object parser accepts its absence
+                // (`optional`, `default`, `any`, `unknown`). An explicit
                 // `requiredKeys` set (from `.required()`) forces it back on.
                 const forced = requiredKeys instanceof Set && requiredKeys.has(key);
-                if (forced || !isOptionalSchema(value))
+                if (forced || !acceptsMissingKey(value))
                     required.push(key);
             }
             const unknownKeys = c["unknownKeys"];
@@ -403,7 +449,7 @@ function convertSchemaNode(schema, state) {
             return applyNullable(convertInner(schema["_inner"], state, "nullable"), state.version);
         case "default": {
             const inner = convertInner(schema["_inner"], state, "default");
-            const defaultValue = schema["_defaultValue"];
+            const defaultValue = resolveDefaultValue(schema, state);
             return defaultValue === undefined
                 ? inner
                 : { ...inner, default: defaultValue };
@@ -413,7 +459,10 @@ function convertSchemaNode(schema, state) {
             // inner shape is still the right description of the data.
             return convertInner(schema["_inner"], state, "refine");
         case "transform":
-            return convertInner(schema["_base"], state, "transform");
+            // `schema.transform(fn)` / `s.transform(schema, fn)` build a
+            // TransformModifierSchema, whose source is `_inner`; the standalone
+            // TransformSchema class names it `_base`.
+            return convertInner(schema["_inner"] ?? schema["_base"], state, "transform");
         case "lazy": {
             const resolved = schema["_inner"] ?? resolveLazy(schema, state);
             if (resolved === undefined)

package/dist/openApiSerialization/openApiSerializer.core.js

@@ -31,8 +31,30 @@ const YAML_RESERVED = new Set([
 ]);
 /** A bare (unquoted) YAML scalar may not start with these. */
 const YAML_UNSAFE_START = /^[-?:,[\]{}#&*!|>'"%@`\s]/;
-const YAML_UNSAFE_ANYWHERE = /[:#\n\r\t]|: |\s#/;
-const YAML_NUMERIC = /^[-+]?(\d+\.?\d*|\.\d+)([eE][-+]?\d+)?$/;
+// Control characters have no plain-scalar form; `JSON.stringify` escapes them.
+const YAML_UNSAFE_ANYWHERE = /[:#\u0000-\u001f\u007f]|: |\s#/;
+const YAML_NUMERIC = /^[-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?$/;
+/**
+ * Other strings a YAML parser resolves to a non-string: the infinity and
+ * not-a-number forms, hexadecimal, octal and binary integers (1.1 and 1.2
+ * core schema), digit groups with `_`, sexagesimal numbers, timestamps
+ * and dates (1.1), the `=` value key and the `<<` merge key. A `version:
+ * 2024-01-01` or an enum value of `0x1F` came back from the parser as a
+ * date or the number 31.
+ */
+const YAML_SPECIAL_SCALARS = [
+    /^[-+]?\.(?:inf|nan)$/i,
+    /^[-+]?0x[0-9a-f_]+$/i,
+    /^[-+]?0o?[0-7_]+$/i,
+    /^[-+]?0b[01_]+$/i,
+    /^[-+]?[0-9][0-9_]*(?:\.[0-9_]*)?(?:[eE][-+]?[0-9]+)?$/,
+    /^[-+]?[0-9][0-9_]*(?::[0-5]?[0-9])+(?:\.[0-9_]*)?$/,
+    /^\d{4}-\d{1,2}-\d{1,2}(?:[Tt ]|$)/,
+    /^(?:=|<<)$/,
+];
+function isSpecialScalar(value) {
+    return YAML_SPECIAL_SCALARS.some((pattern) => pattern.test(value));
+}
 function quoteYamlString(value) {
     // Double quotes with JSON escaping is always valid YAML and needs no
     // decision about block scalars or line folding.
@@ -43,6 +65,7 @@ function yamlScalar(value) {
         YAML_UNSAFE_START.test(value) ||
         YAML_UNSAFE_ANYWHERE.test(value) ||
         YAML_NUMERIC.test(value) ||
+        isSpecialScalar(value) ||
         value !== value.trim()) {
         return quoteYamlString(value);
     }

package/dist/openApiUi/openApiUi.core.js

@@ -38,11 +38,25 @@ function jsLiteral(value) {
         .replace(/\u2028/g, "\\u2028")
         .replace(/\u2029/g, "\\u2029");
 }
-/** Rejects URLs that could execute script when placed in `src`/`href`. */
+/**
+ * Rejects URLs that could execute script when placed in `src`/`href`.
+ *
+ * The scheme is read after stripping ASCII control characters, because the
+ * URL parser browsers apply does the same: `java\nscript:alert(1)` is a
+ * `javascript:` URL to every browser and nothing to a regex that only
+ * looks at the string as written. `data:` is accepted for images only —
+ * the assets base is interpolated into `<script src>`, where a
+ * `data:text/javascript,` base would run inline.
+ */
 function safeUrl(value) {
     const trimmed = value.trim();
-    if (/^\s*(javascript|vbscript):/i.test(trimmed)) {
-        throw new TypeError(`Refusing to render a "${trimmed.split(":")[0]}:" URL`);
+    const normalized = trimmed.replace(/[\u0000-\u0020\u007f]/g, "");
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(normalized)?.[1]?.toLowerCase();
+    if (scheme === "javascript" || scheme === "vbscript") {
+        throw new TypeError(`Refusing to render a "${scheme}:" URL`);
+    }
+    if (scheme === "data" && !/^data:image\//i.test(normalized)) {
+        throw new TypeError('Refusing to render a non-image "data:" URL; only data:image/* is allowed.');
     }
     // Attributes are always double-quoted here, so a single quote (common in
     // data URIs) can stay as-is.
@@ -118,14 +132,14 @@ export function renderOpenAPIUI(options) {
     const title = options.title ?? DEFAULT_TITLE;
     const renderer = options.renderer ?? "swagger";
     if (renderer === "redoc") {
-        const base = (options.assetsBaseUrl ?? REDOC_ASSETS).replace(/\/+$/, "");
+        const base = (options.assetsBaseUrl ?? REDOC_ASSETS).replace(/(?<!\/)\/+$/, "");
         return (head(options, title, "") +
             `<body>${header(options, title)}` +
             `<redoc spec-url="${safeUrl(options.specUrl)}" hide-hostname></redoc>` +
             `<script src="${safeUrl(base)}/redoc.standalone.js"></script>` +
             `${footer()}</body></html>`);
     }
-    const base = (options.assetsBaseUrl ?? SWAGGER_ASSETS).replace(/\/+$/, "");
+    const base = (options.assetsBaseUrl ?? SWAGGER_ASSETS).replace(/(?<!\/)\/+$/, "");
     const config = {
         url: options.specUrl,
         dom_id: "#zudo-openapi",

package/dist/openApiValidation/openApiValidator.core.js

@@ -1,5 +1,5 @@
 import { OpenAPIValidationError } from "../openApiErrors/openApiError.types.js";
-import { MAX_OPERATION_ID_LENGTH, RESPONSE_KEY_PATTERN, SUPPORTED_OPENAPI_VERSIONS, } from "../openApiConstants/openApiConstants.core.js";
+import { MAX_OPERATION_ID_LENGTH, PATH_TEMPLATE_PARAMETER, RESPONSE_KEY_PATTERN, SUPPORTED_OPENAPI_VERSIONS, } from "../openApiConstants/openApiConstants.core.js";
 import { extractPathParameters } from "../openApiRouting/routeConverter.core.js";
 import { unescapeJsonPointerSegment } from "../openApiSchema/references.core.js";
 const OPERATIONS = [
@@ -77,9 +77,22 @@ export class OpenAPIValidatorImpl {
         }
     }
     validatePaths(document, collector) {
+        /** Paths seen so far, keyed by their template with parameter names erased. */
+        const shapes = new Map();
         for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
             if (!pathItem)
                 continue;
+            // "/users/{id}" and "/users/{userId}" have the same hierarchy and
+            // differ only in template names; the specification forbids both
+            // existing, since a router cannot tell them apart.
+            const shape = path.replace(PATH_TEMPLATE_PARAMETER, "{}");
+            const twin = shapes.get(shape);
+            if (twin !== undefined && twin !== path) {
+                error(collector, ["paths", path], `Path "${path}" is identical to "${twin}" apart from its template parameter names; such paths must not both exist.`);
+            }
+            else {
+                shapes.set(shape, path);
+            }
             if (!path.startsWith("/")) {
                 error(collector, ["paths", path], `Path "${path}" must start with "/".`);
             }
@@ -121,28 +134,33 @@ export class OpenAPIValidatorImpl {
             operation.operationId.length > MAX_OPERATION_ID_LENGTH) {
             error(collector, [...base, "operationId"], `operationId "${operation.operationId}" exceeds the maximum length of ${MAX_OPERATION_ID_LENGTH}.`);
         }
-        const parameters = [
-            ...(pathItem.parameters ?? []),
-            ...(operation.parameters ?? []),
-        ];
-        const seen = new Set();
-        for (const parameter of parameters) {
-            if (!parameter.name) {
-                error(collector, [...base, "parameters"], "Every parameter must have a name.");
-                continue;
-            }
-            const key = `${parameter.in}:${parameter.name}`;
-            if (seen.has(key)) {
-                error(collector, [...base, "parameters"], `Duplicate parameter "${parameter.name}" in "${parameter.in}".`);
-            }
-            seen.add(key);
-            if (parameter.in === "path" && parameter.required !== true) {
-                error(collector, [...base, "parameters"], `Path parameter "${parameter.name}" must be required.`);
+        // Uniqueness is per list: the specification forbids duplicates within
+        // the path item's list and within the operation's list, while an
+        // operation-level parameter *overrides* a path-level one with the same
+        // name and location. Treating that override as a duplicate rejected
+        // legal documents.
+        const parameters = new Map();
+        for (const list of [pathItem.parameters, operation.parameters]) {
+            const seen = new Set();
+            for (const parameter of list ?? []) {
+                if (!parameter.name) {
+                    error(collector, [...base, "parameters"], "Every parameter must have a name.");
+                    continue;
+                }
+                const key = `${parameter.in}:${parameter.name}`;
+                if (seen.has(key)) {
+                    error(collector, [...base, "parameters"], `Duplicate parameter "${parameter.name}" in "${parameter.in}".`);
+                }
+                seen.add(key);
+                parameters.set(key, parameter);
+                if (parameter.in === "path" && parameter.required !== true) {
+                    error(collector, [...base, "parameters"], `Path parameter "${parameter.name}" must be required.`);
+                }
             }
         }
         // The classic OpenAPI mistake: a templated path with no matching
         // parameter, or a path parameter that no template slot refers to.
-        const declaredPathParameters = new Set(parameters
+        const declaredPathParameters = new Set([...parameters.values()]
             .filter((parameter) => parameter.in === "path")
             .map((parameter) => parameter.name));
         for (const name of templateParameters) {
@@ -309,7 +327,10 @@ function resolvePointer(document, ref) {
             current = current[index];
             continue;
         }
-        if (!(segment in current))
+        // Own properties only: `in` walks the prototype chain, so a reference
+        // to `#/components/schemas/constructor` resolved to
+        // `Object.prototype.constructor` and validated as present.
+        if (!Object.prototype.hasOwnProperty.call(current, segment))
             return false;
         current = current[segment];
     }

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/openapi",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "OpenAPI 3.0 and 3.1 specification generation, validation, and serialization for Zudojs applications.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -22,7 +26,7 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.0"
+    "@zudojs/errors": "1.0.1"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",