@scalar/mock-server 0.12.13 → 0.13.0

package/dist/utils/replace-circular-markers.js

@@ -0,0 +1,226 @@
+import { isObject } from '@scalar/helpers/object/is-object';
+/**
+ * The placeholder `getResolvedRefDeep` leaves behind wherever it had to cut a `$ref` cycle.
+ *
+ * The marker is owned by `@scalar/workspace-store`; the Ajv test in this file's suite resolves a real
+ * recursive schema, so it fails here if that sentinel ever changes.
+ */
+const CIRCULAR_MARKER = '[circular]';
+/**
+ * Keywords whose value is a schema, or an array of schemas.
+ *
+ * `items` covers the JSON Schema 2020-12 form as well as the older tuple form, which the walker reads
+ * structurally — a tuple `items` does not compile under 2020-12 either way, with or without a cut.
+ * `additionalItems` is listed for the same reason: Ajv 2020 ignores the keyword, but an older document
+ * carrying one still walks cleanly.
+ */
+const SCHEMA_KEYWORDS = new Set([
+    'additionalItems',
+    'additionalProperties',
+    'allOf',
+    'anyOf',
+    'contains',
+    'contentSchema',
+    'else',
+    'if',
+    'items',
+    'not',
+    'oneOf',
+    'prefixItems',
+    'propertyNames',
+    'then',
+    'unevaluatedItems',
+    'unevaluatedProperties',
+]);
+/**
+ * Keywords whose value maps names to schemas. Their keys are author-chosen names rather than
+ * keywords, so the walker must not read them as keywords of their own.
+ */
+const SCHEMA_MAP_KEYWORDS = new Set([
+    '$defs',
+    'definitions',
+    // Ajv 2020 still implements the draft-07 `dependencies`, so a marker under it has to be rewritten
+    // too. Its array form (`{ name: ['other'] }`) walks through untouched.
+    'dependencies',
+    'dependentSchemas',
+    'patternProperties',
+    'properties',
+]);
+/** Map keywords `additionalProperties` reads to decide which properties it still applies to */
+const PROPERTY_MAP_KEYWORDS = new Set(['patternProperties', 'properties']);
+/**
+ * Keywords that invert what a relaxed subschema means: matching more values there makes the schema as
+ * a whole reject more requests. Verified against Ajv — `not: {}` rejects every request, `if: {}`
+ * forces `then` onto every request, `oneOf: [{}, …]` rejects anything that also matches a sibling
+ * branch (a recursive union or a nullable recursive reference being the realistic cases), and a
+ * `contains` that matches more items can overshoot `maxContains`. Whenever the cycle was cut anywhere
+ * below one of these, the keyword is dropped instead, so a valid request is never turned away.
+ */
+const INVERTING_SCHEMA_KEYWORDS = new Set(['contains', 'if', 'not', 'oneOf']);
+/**
+ * In-place applicators, whose subschemas decide which properties and items count as evaluated. A
+ * relaxed branch stops contributing those annotations, so a sibling `unevaluatedProperties` or
+ * `unevaluatedItems` would start rejecting values it used to accept. `if` and `oneOf` are listed for
+ * completeness; a relaxed one of those is dropped by the inverting rule before it gets here, which
+ * clears the sibling anyway.
+ */
+const IN_PLACE_SCHEMA_KEYWORDS = new Set([
+    'allOf',
+    'anyOf',
+    'dependencies',
+    'dependentSchemas',
+    'else',
+    'if',
+    'oneOf',
+    'then',
+]);
+/**
+ * Keywords whose value has to be an array of schemas. A cut at the array itself cannot be answered
+ * with a schema, so the keyword is dropped rather than left as something Ajv refuses to compile.
+ * `oneOf` belongs here too but never reaches it, because the inverting rule already drops it.
+ */
+const SCHEMA_ARRAY_KEYWORDS = new Set(['allOf', 'anyOf', 'prefixItems']);
+/**
+ * Replace the `'[circular]'` markers `getResolvedRefDeep` leaves in schema positions with an empty
+ * (always-valid) schema.
+ *
+ * A recursive schema — a `Node` whose `child` is another `Node` — resolves to a document where the
+ * recursion point is the *string* `'[circular]'`. Ajv rejects the whole schema for it
+ * (`data/properties/child must be object,boolean`), so a single recursive type silently disabled
+ * validation of the request body, or of every parameter in the same location. Accepting anything at
+ * the point where the cycle was cut keeps the rest of the schema enforceable.
+ *
+ * The rewrite only ever loosens what is enforced, so it can lose a violation but never invent one.
+ * That is why relaxing is tracked as it goes: under `not`, `if`, `oneOf` or `contains` a looser
+ * subschema would make the schema *stricter*, so those keywords are dropped rather than rewritten,
+ * and a sibling `unevaluatedProperties`/`unevaluatedItems` goes with a relaxed in-place applicator
+ * for the same reason.
+ *
+ * Only known schema positions are rewritten. A marker anywhere else — `enum`, `const`, `default`,
+ * `example`, or a vendor extension — is data rather than a schema Ajv compiles, so it is copied
+ * through untouched.
+ */
+export const replaceCircularMarkers = (schema) => {
+    // `getResolvedRefDeep` returns a graph, not a tree: one resolved schema object is shared by every
+    // place that referenced it. Reusing the rewritten copy keeps a widely shared schema from being
+    // walked once per occurrence, and is what makes the walk terminate rather than recur forever should
+    // it ever be handed a genuinely cyclic object — which the resolver, having cut every cycle, is not
+    // able to produce.
+    //
+    // Schemas and schema maps are cached apart, because the same object read as one or the other
+    // rewrites differently: `{ not: … }` is a keyword in a schema and a schema named `not` in a map.
+    const rewritten = new WeakMap();
+    const rewrittenMaps = new WeakMap();
+    const asSchema = (value) => {
+        // The cycle was cut here, so nothing is known about the value any more: accept anything.
+        if (value === CIRCULAR_MARKER) {
+            return { value: {}, relaxed: true };
+        }
+        if (!isObject(value) && !Array.isArray(value)) {
+            return { value, relaxed: false };
+        }
+        const cached = rewritten.get(value);
+        if (cached) {
+            return cached;
+        }
+        // Register each copy before filling it, so a self-referencing value resolves to the copy itself.
+        if (Array.isArray(value)) {
+            const items = [];
+            const rewrite = { value: items, relaxed: false };
+            rewritten.set(value, rewrite);
+            for (const item of value) {
+                const child = asSchema(item);
+                items.push(child.value);
+                rewrite.relaxed ||= child.relaxed;
+            }
+            return rewrite;
+        }
+        const result = {};
+        const rewrite = { value: result, relaxed: false };
+        rewritten.set(value, rewrite);
+        let droppedIf = false;
+        let droppedContains = false;
+        let droppedPrefixItems = false;
+        let droppedPropertyMap = false;
+        // Whether this schema stopped saying which properties and items it accounted for — either a
+        // keyword was dropped outright, or a relaxed in-place branch no longer contributes what it did.
+        let annotationsLost = false;
+        for (const [keyword, child] of Object.entries(value)) {
+            if (!SCHEMA_KEYWORDS.has(keyword) && !SCHEMA_MAP_KEYWORDS.has(keyword)) {
+                // Data rather than a schema, so it is carried over as it stands. Nothing mutates the result,
+                // so sharing the value with the resolved document it came from is safe.
+                result[keyword] = child;
+                continue;
+            }
+            // A cut at an array-valued keyword itself cannot become a schema, so the keyword goes. A dropped
+            // keyword also stops saying which properties and items it accounted for, so any `unevaluated*`
+            // sibling has to go with it.
+            if (SCHEMA_ARRAY_KEYWORDS.has(keyword) && child === CIRCULAR_MARKER) {
+                droppedPrefixItems ||= keyword === 'prefixItems';
+                rewrite.relaxed = true;
+                annotationsLost = true;
+                continue;
+            }
+            // A cut at a schema map itself leaves an empty map, which accounts for nothing any more, so an
+            // `unevaluated*` sibling has to go the same way a dropped keyword takes it.
+            if (SCHEMA_MAP_KEYWORDS.has(keyword) && child === CIRCULAR_MARKER) {
+                result[keyword] = {};
+                droppedPropertyMap ||= PROPERTY_MAP_KEYWORDS.has(keyword);
+                rewrite.relaxed = true;
+                annotationsLost = true;
+                continue;
+            }
+            const rewrittenChild = SCHEMA_MAP_KEYWORDS.has(keyword) && isObject(child) ? asSchemaMap(child) : asSchema(child);
+            if (INVERTING_SCHEMA_KEYWORDS.has(keyword) && rewrittenChild.relaxed) {
+                droppedIf ||= keyword === 'if';
+                droppedContains ||= keyword === 'contains';
+                rewrite.relaxed = true;
+                annotationsLost = true;
+                continue;
+            }
+            result[keyword] = rewrittenChild.value;
+            rewrite.relaxed ||= rewrittenChild.relaxed;
+            annotationsLost ||= rewrittenChild.relaxed && IN_PLACE_SCHEMA_KEYWORDS.has(keyword);
+        }
+        // `then` and `else` only apply alongside an `if`, so they leave with the dropped condition, and
+        // `minContains`/`maxContains` only qualify a `contains`.
+        if (droppedIf) {
+            delete result.then;
+            delete result.else;
+        }
+        if (droppedContains) {
+            delete result.minContains;
+            delete result.maxContains;
+        }
+        // `additionalProperties` and `items` only apply to what their siblings did not cover, so once that
+        // sibling is gone they would start policing values it used to account for.
+        if (droppedPropertyMap) {
+            delete result.additionalProperties;
+        }
+        if (droppedPrefixItems) {
+            delete result.items;
+        }
+        if (annotationsLost) {
+            delete result.unevaluatedProperties;
+            delete result.unevaluatedItems;
+        }
+        return rewrite;
+    };
+    /** Rewrite every schema under a map keyword, keeping its author-chosen names as they are */
+    const asSchemaMap = (map) => {
+        const cached = rewrittenMaps.get(map);
+        if (cached) {
+            return cached;
+        }
+        const result = {};
+        const rewrite = { value: result, relaxed: false };
+        rewrittenMaps.set(map, rewrite);
+        for (const [name, sub] of Object.entries(map)) {
+            const child = asSchema(sub);
+            result[name] = child.value;
+            rewrite.relaxed ||= child.relaxed;
+        }
+        return rewrite;
+    };
+    return asSchema(schema).value;
+};

package/dist/utils/request-matches-pinned-query.d.ts

@@ -0,0 +1,10 @@
+import type { Context } from 'hono';
+import type { PinnedQueryParameter } from '../utils/split-path-key.js';
+/**
+ * Check whether a request carries every query parameter a path key pins.
+ *
+ * `/v1/messages?beta=true` describes a variant of `/v1/messages`, so it may only answer requests
+ * that actually send `beta=true`. A parameter pinned without a value (`?beta`) matches any value.
+ */
+export declare const requestMatchesPinnedQuery: (context: Context, query: PinnedQueryParameter[]) => boolean;
+//# sourceMappingURL=request-matches-pinned-query.d.ts.map

package/dist/utils/request-matches-pinned-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-matches-pinned-query.d.ts","sourceRoot":"","sources":["../../src/utils/request-matches-pinned-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAElE;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,OAAO,EAAE,OAAO,oBAAoB,EAAE,KAAG,OASxF,CAAA"}

package/dist/utils/request-matches-pinned-query.js

@@ -0,0 +1,13 @@
+/**
+ * Check whether a request carries every query parameter a path key pins.
+ *
+ * `/v1/messages?beta=true` describes a variant of `/v1/messages`, so it may only answer requests
+ * that actually send `beta=true`. A parameter pinned without a value (`?beta`) matches any value.
+ */
+export const requestMatchesPinnedQuery = (context, query) => query.every(({ name, value }) => {
+    const values = context.req.queries(name);
+    if (!values?.length) {
+        return false;
+    }
+    return value === undefined || values.includes(value);
+});

package/dist/utils/resolve-logger.d.ts

@@ -0,0 +1,12 @@
+import type { MockServerLogger } from '../types.js';
+/**
+ * Resolve the `logger` option accepted by the mock server factories into a concrete sink.
+ *
+ * The option is a superset of a plain sink:
+ * - a function is used as-is,
+ * - `true` logs each line to the console,
+ * - `false` drops every line,
+ * - `undefined` falls back to the factory's default (`enabledByDefault`).
+ */
+export declare const resolveLogger: (logger: boolean | MockServerLogger | undefined, enabledByDefault: boolean) => MockServerLogger;
+//# sourceMappingURL=resolve-logger.d.ts.map

package/dist/utils/resolve-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-logger.d.ts","sourceRoot":"","sources":["../../src/utils/resolve-logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,OAAO,GAAG,gBAAgB,GAAG,SAAS,EAC9C,kBAAkB,OAAO,KACxB,gBAQF,CAAA"}

package/dist/utils/resolve-logger.js

@@ -0,0 +1,16 @@
+/**
+ * Resolve the `logger` option accepted by the mock server factories into a concrete sink.
+ *
+ * The option is a superset of a plain sink:
+ * - a function is used as-is,
+ * - `true` logs each line to the console,
+ * - `false` drops every line,
+ * - `undefined` falls back to the factory's default (`enabledByDefault`).
+ */
+export const resolveLogger = (logger, enabledByDefault) => {
+    const value = logger ?? enabledByDefault;
+    if (typeof value === 'function') {
+        return value;
+    }
+    return value ? (line) => console.log(line) : () => undefined;
+};

package/dist/utils/serialize-response-body.d.ts

@@ -0,0 +1,11 @@
+import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+type Schema = NonNullable<OpenAPIV3_1.ComponentsObject['schemas']>[string];
+/**
+ * Serializes a mocked response body for the negotiated media type.
+ *
+ * Returns `undefined` for an `undefined` body, mirroring `JSON.stringify`, so the caller can send an
+ * empty body rather than the characters `undefined`.
+ */
+export declare const serializeResponseBody: (body: unknown, contentType: string | undefined, schema?: Schema) => string | undefined;
+export {};
+//# sourceMappingURL=serialize-response-body.d.ts.map

package/dist/utils/serialize-response-body.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize-response-body.d.ts","sourceRoot":"","sources":["../../src/utils/serialize-response-body.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,KAAK,MAAM,GAAG,WAAW,CAAC,WAAW,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AAkE1E;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,OAAO,EACb,aAAa,MAAM,GAAG,SAAS,EAC/B,SAAS,MAAM,KACd,MAAM,GAAG,SAgCX,CAAA"}

package/dist/utils/serialize-response-body.js

@@ -0,0 +1,88 @@
+import { json2xml } from '@scalar/helpers/file/json2xml';
+import { parseMimeType } from '@scalar/helpers/http/mime-type';
+/**
+ * Whether a media type carries a single JSON document.
+ *
+ * Matched on the parsed subtype, so suffixed types (`application/problem+json`) and parameterized ones
+ * (`application/json; charset=utf-8`) count, while a type that merely mentions JSON in a parameter does
+ * not. Line-delimited relatives (`application/jsonl`, `application/x-ndjson`) are deliberately excluded:
+ * their payload is a sequence of documents, so a string body already carries the framing. A missing
+ * media type parses as `text/plain`, which is the safe answer here: the body is written as it is.
+ */
+const isJsonDocumentContentType = (contentType) => {
+    const { subtype } = parseMimeType(contentType);
+    return subtype === 'json' || subtype.endsWith('+json');
+};
+/** Whether a media type carries XML, including suffixed types such as `application/xhtml+xml`. */
+const isXmlContentType = (contentType) => {
+    const { subtype } = parseMimeType(contentType);
+    return subtype === 'xml' || subtype.endsWith('+xml');
+};
+/**
+ * How the resolved response schema describes the body: as a string, as something else, or not at all.
+ *
+ * Composite schemas (`allOf`, an `enum` without a type) land on `unknown`, which is the honest answer:
+ * they say nothing this decision can act on.
+ */
+const declaredBodyKind = (schema) => {
+    if (!schema || typeof schema !== 'object' || !('type' in schema) || schema.type === undefined) {
+        return 'unknown';
+    }
+    const { type } = schema;
+    if (Array.isArray(type)) {
+        if (type.length === 0) {
+            return 'unknown';
+        }
+        return type.includes('string') ? 'string' : 'other';
+    }
+    return type === 'string' ? 'string' : 'other';
+};
+/** Whether a string holds serialized JSON of any shape, a bare scalar included. */
+const isSerializedJson = (value) => {
+    try {
+        JSON.parse(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Whether a string holds a serialized JSON object or array. */
+const isSerializedJsonDocument = (value) => {
+    const trimmed = value.trim();
+    return (trimmed.startsWith('{') || trimmed.startsWith('[')) && isSerializedJson(trimmed);
+};
+/**
+ * Serializes a mocked response body for the negotiated media type.
+ *
+ * Returns `undefined` for an `undefined` body, mirroring `JSON.stringify`, so the caller can send an
+ * empty body rather than the characters `undefined`.
+ */
+export const serializeResponseBody = (body, contentType, schema) => {
+    // XML: only an object tree can be turned into a document. `null` is `typeof 'object'` too, but it is
+    // not a valid XML root, so it falls through to `JSON.stringify` below rather than into `json2xml`.
+    if (body !== null && typeof body === 'object' && isXmlContentType(contentType)) {
+        return json2xml(body);
+    }
+    if (typeof body === 'string') {
+        // Anywhere but a single JSON document, the characters are the payload: `text/plain`, `text/html`,
+        // XML, `text/event-stream`, line-delimited JSON, and anything else the mock does not recognize.
+        if (!isJsonDocumentContentType(contentType)) {
+            return body;
+        }
+        // Under a JSON media type a string has to be encoded, or a `type: string` response arrives as the
+        // bare characters `string`, which no JSON client can parse. What survives unencoded is text that is
+        // already the body the document describes: whatever parses when the schema declares a non-string
+        // type, and an object or array when the schema says nothing, both of which are documents the author
+        // serialized by hand. A quoted scalar without a schema behind it stays a string, since the author
+        // quoting `'123'` is the only signal available about what they meant.
+        const kind = declaredBodyKind(schema);
+        if (kind === 'other' && isSerializedJson(body)) {
+            return body;
+        }
+        if (kind === 'unknown' && isSerializedJsonDocument(body)) {
+            return body;
+        }
+    }
+    return JSON.stringify(body);
+};

package/dist/utils/split-path-key.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Matches a `{parameterName}` template inside a path key.
+ *
+ * A template has to be balanced and non-empty, so a stray brace counts as literal path text.
+ */
+export declare const PATH_KEY_TEMPLATE: RegExp;
+/** A query parameter that an OpenAPI path key pins, for example `beta=true` in `/v1/messages?beta=true`. */
+export type PinnedQueryParameter = {
+    /** Decoded name of the query parameter. */
+    name: string;
+    /** Decoded value the request has to send, or `undefined` when the path key only pins the name. */
+    value: string | undefined;
+};
+/** An OpenAPI path key taken apart into the portion Hono can route and the query it pins. */
+type SplitPathKey = {
+    /** The path portion of the key, without the query string. */
+    path: string;
+    /** Query parameters the key pins. Empty for a regular path key. */
+    query: PinnedQueryParameter[];
+};
+/**
+ * Split an OpenAPI path key into its path and its pinned query parameters.
+ *
+ * Some documents carry a literal query string in the path key to describe a variant of an operation,
+ * for example `/v1/messages?beta=true` next to `/v1/messages`. That is not a routable path, so the
+ * query has to be peeled off and matched against the incoming request separately.
+ */
+export declare const splitPathKey: (pathKey: string) => SplitPathKey;
+export {};
+//# sourceMappingURL=split-path-key.d.ts.map

package/dist/utils/split-path-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"split-path-key.d.ts","sourceRoot":"","sources":["../../src/utils/split-path-key.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,QAAkB,CAAA;AAKhD,4GAA4G;AAC5G,MAAM,MAAM,oBAAoB,GAAG;IACjC,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAA;IACZ,kGAAkG;IAClG,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1B,CAAA;AAED,6FAA6F;AAC7F,KAAK,YAAY,GAAG;IAClB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAA;IACZ,mEAAmE;IACnE,KAAK,EAAE,oBAAoB,EAAE,CAAA;CAC9B,CAAA;AAyCD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,KAAG,YA+B9C,CAAA"}

package/dist/utils/split-path-key.js

@@ -0,0 +1,77 @@
+/**
+ * Matches a `{parameterName}` template inside a path key.
+ *
+ * A template has to be balanced and non-empty, so a stray brace counts as literal path text.
+ */
+export const PATH_KEY_TEMPLATE = /\{([^{}]+)\}/g;
+/** Matches a query value that is nothing but a template, as in `?status={status}`. */
+const TEMPLATE_VALUE = /^\{[^{}]+\}$/;
+/**
+ * Decode one part of a query string the way `URLSearchParams` does.
+ *
+ * A malformed escape sequence is kept verbatim instead of throwing, so a single odd path key cannot
+ * take the whole server down.
+ */
+const decodeQueryPart = (value) => {
+    try {
+        return decodeURIComponent(value.replace(/\+/g, ' '));
+    }
+    catch {
+        return value;
+    }
+};
+/**
+ * Find the `?` that starts the query string of a path key.
+ *
+ * Only a `?` outside a `{…}` template counts, so a path parameter whose name contains a `?` does not
+ * accidentally cut the key in half. An unbalanced brace is literal path text rather than an open
+ * template, so it cannot hide the query string of the rest of the key. Returns `-1` when the key
+ * carries no query string.
+ */
+const findQueryStart = (pathKey) => {
+    // A fresh instance, because `matchAll` reads the `lastIndex` of the regular expression it is
+    // given and `PATH_KEY_TEMPLATE` is shared with other modules.
+    const templates = [...pathKey.matchAll(new RegExp(PATH_KEY_TEMPLATE))].map((match) => ({
+        start: match.index,
+        end: match.index + match[0].length,
+    }));
+    for (let index = pathKey.indexOf('?'); index !== -1; index = pathKey.indexOf('?', index + 1)) {
+        if (!templates.some(({ start, end }) => index > start && index < end)) {
+            return index;
+        }
+    }
+    return -1;
+};
+/**
+ * Split an OpenAPI path key into its path and its pinned query parameters.
+ *
+ * Some documents carry a literal query string in the path key to describe a variant of an operation,
+ * for example `/v1/messages?beta=true` next to `/v1/messages`. That is not a routable path, so the
+ * query has to be peeled off and matched against the incoming request separately.
+ */
+export const splitPathKey = (pathKey) => {
+    const queryStart = findQueryStart(pathKey);
+    if (queryStart === -1) {
+        return { path: pathKey, query: [] };
+    }
+    const query = pathKey
+        .slice(queryStart + 1)
+        .split('&')
+        .filter((pair) => pair !== '')
+        .map((pair) => {
+        const separator = pair.indexOf('=');
+        // `?beta` pins the name only, `?beta=true` pins the name and the value.
+        if (separator === -1) {
+            return { name: decodeQueryPart(pair), value: undefined };
+        }
+        const value = pair.slice(separator + 1);
+        return {
+            name: decodeQueryPart(pair.slice(0, separator)),
+            // A value that is nothing but a template (`?status={status}`) names the parameter rather
+            // than fixing it, so any value the request sends satisfies it.
+            value: TEMPLATE_VALUE.test(value) ? undefined : decodeQueryPart(value),
+        };
+    })
+        .filter(({ name }) => name !== '');
+    return { path: pathKey.slice(0, queryStart), query };
+};

package/dist/utils/validate-request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-request.d.ts","sourceRoot":"","sources":["../../src/utils/validate-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAMxD,OAAO,KAAK,EAAW,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAuRtD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,WAAW,WAAW,CAAC,eAAe,EACtC,qBAAqB,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,KAC5D,iBAkKF,CAAA"}
+{"version":3,"file":"validate-request.d.ts","sourceRoot":"","sources":["../../src/utils/validate-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAMxD,OAAO,KAAK,EAAW,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAoStD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,WAAW,WAAW,CAAC,eAAe,EACtC,qBAAqB,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,KAC5D,iBAkKF,CAAA"}

package/dist/utils/validate-request.js

@@ -4,6 +4,17 @@ import Ajv2020 from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
 import { getCookie } from 'hono/cookie';
 import { deserializeArrayParameter, deserializeObjectParameter, getObjectPropertyNames, isArraySchema, isObjectSchema, resolveSerialization, } from './deserialize-parameter.js';
+import { replaceCircularMarkers } from './replace-circular-markers.js';
+/**
+ * Prepare a resolved schema for Ajv by replacing the `'[circular]'` markers a recursive schema leaves
+ * behind. Ajv refuses to compile a schema that still carries one, which makes the body — or the whole
+ * parameter location built around it — fail open.
+ *
+ * Only Ajv sees this copy. Everything that reads the *shape* of a schema keeps reading the resolved
+ * one, because the rewrite may drop a keyword (a `oneOf` the cycle ran through, say) that the shape
+ * still depends on.
+ */
+const asCompilableSchema = (resolved) => replaceCircularMarkers(resolved);
 /**
  * Header parameters named `Accept`, `Content-Type`, or `Authorization` are defined elsewhere in
  * OpenAPI (through `content` and `security`), so the spec says such parameter definitions SHALL be
@@ -61,7 +72,7 @@ const buildParameterSchema = (parameters, location) => {
             propertyNames,
         });
         if (resolvedSchema) {
-            properties[parameter.name] = resolvedSchema;
+            properties[parameter.name] = asCompilableSchema(resolvedSchema);
         }
         if (parameter.required) {
             required.push(parameter.name);
@@ -134,7 +145,7 @@ const compileValidators = (operation, pathItemParameters) => {
     let bodySchema = null;
     try {
         const jsonSchema = getResolvedRef(requestBody?.content?.['application/json'])?.schema;
-        bodySchema = jsonSchema ? getResolvedRefDeep(jsonSchema) : null;
+        bodySchema = jsonSchema ? asCompilableSchema(getResolvedRefDeep(jsonSchema)) : null;
     }
     catch (error) {
         console.error('Error resolving request body schema, skipping body validation:', error);

package/package.json

@@ -16,7 +16,7 @@
     "swagger",
     "cli"
   ],
-  "version": "0.12.13",
+  "version": "0.13.0",
   "engines": {
     "node": ">=22"
   },
@@ -53,16 +53,16 @@
   "dependencies": {
     "@faker-js/faker": "10.4.0",
     "@hono/node-ws": "^1.2.0",
-    "ajv": "^8.18.0",
+    "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "hono": "^4.12.7",
     "yaml": "^2.9.0",
-    "@scalar/helpers": "0.11.1",
+    "@scalar/helpers": "0.11.2",
+    "@scalar/json-magic": "0.13.3",
     "@scalar/openapi-types": "0.9.5",
     "@scalar/openapi-upgrader": "0.2.15",
-    "@scalar/types": "0.18.2",
-    "@scalar/json-magic": "0.13.2",
-    "@scalar/workspace-store": "0.58.1"
+    "@scalar/workspace-store": "0.59.0",
+    "@scalar/types": "0.18.3"
   },
   "devDependencies": {
     "@types/node": "^24.1.0",