@scalar/mock-server 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @scalar/mock-server
 
+## 0.17.0
+
+### Minor Changes
+
+- [#10192](https://github.com/scalar/scalar/pull/10192): Mock-server XML response bytes now use the shared schema-aware serializer instead of `json2xml`, including attributes, namespaces, and root naming. Existing XML response snapshots may need updating. Supplied serialized XML remains unchanged.
+
+  Generate XML examples from schema metadata, preserving attributes, namespaces, array wrappers, repeated elements, and OpenAPI 3.2 text and CDATA nodes. Use the same XML serialization for request bodies, code snippets, response examples, mock responses, and Markdown documentation. Preserve serialized media examples and escape schema string examples as element text.
+
+  Explain XML generation failures in response example panels, including the serialized-example escape hatch for large payloads. Expose XML generation failures in mock response headers with `X-Scalar-XML-Error`, containing the first error diagnostic code. Report diagnostics to other consumers through a callback or the developer console, and format element-only descendants within mixed content without changing text values.
+
+### Patch Changes
+
+- [#10343](https://github.com/scalar/scalar/pull/10343): Restrict AsyncAPI external references to the source directory and public network addresses, and preserve the source location for preloaded documents.
+
+  URL inputs to `createAsyncApiMockServer` also reject private network addresses, including localhost. Load local files or pass preloaded document content for local development. Docker documents supplied through `OPENAPI_DOCUMENT` resolve relative references from their temporary `/tmp/openapi.json` or `/tmp/openapi.yaml` file, confined to `/tmp`. Both OpenAPI and AsyncAPI Docker documents preserve the selected source origin.
+
+- [#10192](https://github.com/scalar/scalar/pull/10192): Apply edited XML bodies instead of their original serialized or data examples, render schema-free XML examples in Markdown, and share reference decoding and response provenance selection.
+
+## 0.16.0
+
+### Minor Changes
+
+- [#10189](https://github.com/scalar/scalar/pull/10189): Support OpenAPI 3.2 `in: querystring` parameters in request validation and custom handlers. Decode JSON, text, and form content from the entire query string, including inherited parameters and form property encoding.
+
+  Treat only null or undefined as absent validator schemas, preserving boolean `false` whole-query schemas that reject every value. Empty object schemas were already compiled and continue to accept unconstrained values.
+
+- [#10186](https://github.com/scalar/scalar/pull/10186): Support additionalOperations with case-sensitive custom HTTP methods, existing operation middleware, and CORS preflight responses.
+
+  Preserve QUERY in the default CORS method list when adding methods declared by the API description.
+
 ## 0.15.0
 
 ### Minor Changes

package/dist/create-asyncapi-mock-server.d.ts

@@ -9,6 +9,8 @@ export type AsyncApiMockServerOptions = {
      * string, or an already-parsed object.
      */
     document?: string | Record<string, any>;
+    /** Source file path or URL for resolving references in an already loaded document. */
+    origin?: string;
     /**
      * Additional transports appended after the built-in WebSocket and SSE transports. Use this to
      * support extra protocols (for example SignalR) without changing the core. The first transport

package/dist/create-asyncapi-mock-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-asyncapi-mock-server.d.ts","sourceRoot":"","sources":["../src/create-asyncapi-mock-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAoB,MAAM,mBAAmB,CAAA;AAC9E,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAK3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAoB,MAAM,oBAAoB,CAAA;AAC3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAM/C,oDAAoD;AACpD,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAEvC;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,EAAE,CAAA;IAE5B,yFAAyF;IACzF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;IAE/F;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAA;CACpC,CAAA;AAED,sDAAsD;AACtD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,sEAAsE;IACtE,GAAG,EAAE,IAAI,CAAA;IACT,wFAAwF;IACxF,SAAS,EAAE;QAAE,MAAM,EAAE,mBAAmB,CAAA;KAAE,CAAA;CAC3C,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAqC9G"}
+{"version":3,"file":"create-asyncapi-mock-server.d.ts","sourceRoot":"","sources":["../src/create-asyncapi-mock-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAoB,MAAM,mBAAmB,CAAA;AAC9E,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAK3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAoB,MAAM,oBAAoB,CAAA;AAC3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAM/C,oDAAoD;AACpD,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAEvC,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,EAAE,CAAA;IAE5B,yFAAyF;IACzF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;IAE/F;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAA;CACpC,CAAA;AAED,sDAAsD;AACtD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,sEAAsE;IACtE,GAAG,EAAE,IAAI,CAAA;IACT,wFAAwF;IACxF,SAAS,EAAE;QAAE,MAAM,EAAE,mBAAmB,CAAA;KAAE,CAAA;CAC3C,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAqC9G"}

package/dist/create-asyncapi-mock-server.js

@@ -22,7 +22,7 @@ import { resolveLogger } from './utils/resolve-logger.js';
  */
 export async function createAsyncApiMockServer(options) {
     const app = new Hono();
-    const document = await processAsyncApiDocument(options.document);
+    const document = await processAsyncApiDocument(options.document, options.origin);
     const channels = resolveChannels(document);
     const transports = [...defaultTransports, ...(options.transports ?? [])];
     const log = resolveLogger(options.logger, false);

package/dist/create-mock-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-mock-server.d.ts","sourceRoot":"","sources":["../src/create-mock-server.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,IAAI,EAA0B,MAAM,MAAM,CAAA;AAIjE,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAwD5D;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,aAAa,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8NtF"}
+{"version":3,"file":"create-mock-server.d.ts","sourceRoot":"","sources":["../src/create-mock-server.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,IAAI,EAA0B,MAAM,MAAM,CAAA;AAIjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAwDhD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,aAAa,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwOtF"}

package/dist/create-mock-server.js

@@ -103,7 +103,13 @@ export async function createMockServer(configuration) {
         }
     }
     // CORS headers
-    app.use(cors());
+    const allowedMethods = new Set(['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH', 'QUERY']);
+    for (const pathItem of Object.values(schema?.paths ?? {})) {
+        for (const method of Object.keys(getOperations(getResolvedRef(pathItem)))) {
+            allowedMethods.add(method);
+        }
+    }
+    app.use(cors({ origin: '*', allowMethods: [...allowedMethods], exposeHeaders: ['X-Scalar-XML-Error'] }));
     /** Authentication methods defined in the OpenAPI document */
     setUpAuthenticationRoutes(app, schema);
     // Only the instructions honor `logger` (on by default); the util still prints warnings and errors
@@ -136,19 +142,17 @@ export async function createMockServer(configuration) {
     orderedPathKeys.forEach(({ path, query }) => {
         // A path item may itself be a `$ref`, so resolve it before reading its operations.
         const pathItem = getResolvedRef(paths[path]);
-        const methods = Object.keys(getOperations(pathItem));
+        const operations = getOperations(pathItem);
         /** Keys for all operations of a specified path */
-        methods.forEach((method) => {
+        Object.entries(operations).forEach(([method, operation]) => {
             const route = honoRouteFromPath(path);
-            const operation = pathItem?.[method];
             // Remember which operation this route mocks, so the error handler can name it when something
             // fails downstream. Recorded on the context rather than mapped back from the request path,
             // which would not survive the app being mounted under a base path. Registered before the rest
             // of the route so a failure in request validation is named too. The OpenAPI path key is kept
             // (rather than the Hono route) because that is what the document author reads.
             const mockedOperation = {
-                // `toUpperCase` widens to `string`, so restate the narrower type the method union guarantees.
-                method: method.toUpperCase(),
+                method,
                 path,
                 ...(operation?.operationId ? { operationId: operation.operationId } : {}),
             };
@@ -188,21 +192,28 @@ export async function createMockServer(configuration) {
             const hasHandler = handlerCode && typeof handlerCode === 'string' && handlerCode.trim().length > 0;
             // Route to appropriate handler
             if (hasHandler) {
-                handlers.push(async (c) => await mockHandlerResponse(c, operation));
+                handlers.push(async (c) => await mockHandlerResponse(c, operation, pathItem?.parameters, schema.openapi));
             }
             else {
-                handlers.push(async (c) => await mockAnyResponse(c, operation));
-            }
-            if (query.length === 0) {
-                handlers.forEach((handler) => app[method](route, handler));
-                return;
+                handlers.push(async (c) => await mockAnyResponse(c, operation, schema.openapi));
             }
             // The pinned query parameters are not part of the route, so they are checked here. A request
             // that does not carry them is handed on to the next matching route — usually the sibling path
             // key without the query string.
             const operationChain = every(...handlers);
-            app[method](route, async (c, next) => {
-                if (!requestMatchesPinnedQuery(c, query)) {
+            // Hono uppercases methods during registration. Match the original method ourselves so
+            // additional operations such as COPY and copy remain distinct.
+            const register = (handler) => {
+                if (method === method.toUpperCase()) {
+                    app.on(method, route, handler);
+                }
+                else {
+                    app.all(route, handler);
+                }
+            };
+            register(async (c, next) => {
+                if ((c.req.method !== method && !(method === 'GET' && c.req.method === 'HEAD')) ||
+                    !requestMatchesPinnedQuery(c, query)) {
                     await next();
                     return;
                 }

package/dist/routes/mock-any-response.d.ts

@@ -3,5 +3,5 @@ import type { Context } from 'hono';
 /**
  * Mock any response
  */
-export declare function mockAnyResponse(c: Context, operation: OpenAPIV3_1.OperationObject): Response;
+export declare function mockAnyResponse(c: Context, operation: OpenAPIV3_1.OperationObject, openapiVersion?: string): Response;
 //# sourceMappingURL=mock-any-response.d.ts.map

package/dist/routes/mock-any-response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock-any-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-any-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAenC;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,YA6IjF"}
+{"version":3,"file":"mock-any-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-any-response.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAKxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAenC;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,EAAE,cAAc,CAAC,EAAE,MAAM,YA4J1G"}

package/dist/routes/mock-any-response.js

@@ -1,6 +1,7 @@
+import { isXmlMediaType } from '@scalar/helpers/http/is-xml-media-type';
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { getResolvedRefDeep } from '@scalar/workspace-store/helpers/get-resolved-ref-deep';
-import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
+import { getExampleFromSchema, getXmlBodyExample } from '@scalar/workspace-store/request-example';
 import { streamSSE } from 'hono/streaming';
 import { collectSseEvents, isEventStreamContentType } from '../utils/collect-sse-events.js';
 import { findPreferredResponseKey } from '../utils/find-preferred-response-key.js';
@@ -15,7 +16,7 @@ import { getStreamingResponse, sendStreamingResponse } from '../utils/streaming-
 /**
  * Mock any response
  */
-export function mockAnyResponse(c, operation) {
+export function mockAnyResponse(c, operation, openapiVersion) {
     // Note: the `onRequest` callback runs as middleware (see `create-mock-server`) so it also fires
     // for requests rejected before reaching this handler.
     // Parse the Prefer header (RFC 7240) so clients can request a specific
@@ -102,9 +103,24 @@ export function mockAnyResponse(c, operation) {
     // Body: a named/singular/first example if one is defined, otherwise generate
     // a value from the schema. `Prefer: example=<name>` picks a named example.
     const selectedExample = selectResponseExample(acceptedResponse, prefer.example);
+    c.status(statusCode);
+    if (isXmlMediaType(acceptedContentType)) {
+        const result = getXmlBodyExample(acceptedResponse?.schema, selectedExample, {
+            openapiVersion,
+            emptyString: 'string',
+            variables: pathParameters(c),
+            mode: 'read',
+        });
+        const error = result.diagnostics.find((diagnostic) => diagnostic.severity === 'error');
+        if (error) {
+            c.header('X-Scalar-XML-Error', error.code);
+        }
+        return result.xml === undefined ? c.body(null) : c.body(result.xml);
+    }
+    const provenance = selectedExample?.provenance;
     const body = (() => {
         if (selectedExample) {
-            return normalizeResponseBody(selectedExample.value, responseSchema);
+            return provenance ? selectedExample.value : normalizeResponseBody(selectedExample.value, responseSchema);
         }
         if (!responseSchema) {
             return null;
@@ -119,8 +135,7 @@ export function mockAnyResponse(c, operation) {
         // Re-inferring it from sibling items would wrap a selected primitive in an array.
         return generated;
     })();
-    c.status(statusCode);
-    const serializedBody = serializeResponseBody(body, acceptedContentType, responseSchema);
+    const serializedBody = serializeResponseBody(body, acceptedContentType, responseSchema, provenance);
     // `JSON.stringify` returns `undefined` for an `undefined` body, which is an empty response.
     if (serializedBody === undefined) {
         return c.body(null);

package/dist/routes/mock-handler-response.d.ts

@@ -4,5 +4,5 @@ import type { Context } from 'hono';
  * Mock response using x-handler code.
  * Executes the handler and returns its result as the response.
  */
-export declare function mockHandlerResponse(c: Context, operation: OpenAPIV3_1.OperationObject): Promise<Response>;
+export declare function mockHandlerResponse(c: Context, operation: OpenAPIV3_1.OperationObject, pathItemParameters?: OpenAPIV3_1.PathItemObject['parameters'], openapiVersion?: string): Promise<Response>;
 //# sourceMappingURL=mock-handler-response.d.ts.map

package/dist/routes/mock-handler-response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock-handler-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-handler-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AA4HnC;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,qBAoE3F"}
+{"version":3,"file":"mock-handler-response.d.ts","sourceRoot":"","sources":["../../src/routes/mock-handler-response.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAoJnC;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,EAAE,WAAW,CAAC,eAAe,EACtC,kBAAkB,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,EAC7D,cAAc,CAAC,EAAE,MAAM,qBA8ExB"}

package/dist/routes/mock-handler-response.js

@@ -1,4 +1,6 @@
+import { isXmlMediaType } from '@scalar/helpers/http/is-xml-media-type';
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { getXmlBodyExample } from '@scalar/workspace-store/request-example';
 import { buildHandlerContext } from '../utils/build-handler-context.js';
 import { executeHandler } from '../utils/execute-handler.js';
 import { generateResponseExample } from '../utils/generate-response-example.js';
@@ -7,16 +9,17 @@ import { normalizeResponseBody } from '../utils/normalize-response-body.js';
 import { parsePreferHeader } from '../utils/parse-prefer-header.js';
 import { pathParameters } from '../utils/path-parameters.js';
 import { selectResponseExample } from '../utils/select-response-example.js';
+import { serializeResponseBody } from '../utils/serialize-response-body.js';
 import { getStreamingResponse, sendStreamingResponse } from '../utils/streaming-response.js';
 /**
  * Get example response from OpenAPI spec for a given status code.
- * Returns the example value if found, or null if not available.
+ * Returns a serialized payload if found, or null if not available.
  *
  * Honors `Prefer: example=<name>` to pick a named example from the
  * `examples` map; otherwise it falls back to the singular `example`, the
  * first entry of the map, or a value generated from the schema.
  */
-function getExampleFromResponse(c, statusCode, responses, exampleName) {
+function getExampleFromResponse(c, statusCode, responses, exampleName, openapiVersion) {
     if (!responses) {
         return null;
     }
@@ -39,11 +42,32 @@ function getExampleFromResponse(c, statusCode, responses, exampleName) {
     const responseSchema = acceptedResponse.schema ? getResolvedRef(acceptedResponse.schema) : undefined;
     // Extract example (named, singular, or first) or generate from schema
     const selectedExample = selectResponseExample(acceptedResponse, exampleName);
-    return selectedExample
+    if (isXmlMediaType(acceptedContentType)) {
+        c.header('Content-Type', acceptedContentType);
+        const result = getXmlBodyExample(acceptedResponse.schema, selectedExample, {
+            openapiVersion,
+            emptyString: 'string',
+            variables: pathParameters(c),
+            mode: 'read',
+        });
+        const error = result.diagnostics.find((diagnostic) => diagnostic.severity === 'error');
+        if (error) {
+            c.header('X-Scalar-XML-Error', error.code);
+        }
+        return result.xml ?? null;
+    }
+    const provenance = selectedExample?.provenance;
+    if (selectedExample && provenance) {
+        c.header('Content-Type', acceptedContentType);
+        return serializeResponseBody(selectedExample.value, acceptedContentType, responseSchema, provenance) ?? null;
+    }
+    const value = selectedExample
         ? normalizeResponseBody(selectedExample.value, responseSchema)
         : responseSchema
             ? normalizeResponseBody(generateResponseExample(responseSchema, pathParameters(c)), responseSchema)
             : null;
+    // Legacy examples retain the handler fallback's JSON encoding policy.
+    return JSON.stringify(value) ?? null;
 }
 /**
  * Determine HTTP status code based on store operation tracking.
@@ -98,7 +122,7 @@ function determineStatusCode(tracking) {
  * Mock response using x-handler code.
  * Executes the handler and returns its result as the response.
  */
-export async function mockHandlerResponse(c, operation) {
+export async function mockHandlerResponse(c, operation, pathItemParameters, openapiVersion) {
     // Note: the `onRequest` callback runs as middleware (see `create-mock-server`) so it also fires
     // for requests rejected before reaching this handler.
     // Get x-handler code from operation
@@ -109,7 +133,7 @@ export async function mockHandlerResponse(c, operation) {
     }
     try {
         // Build handler context with tracking
-        const { context, tracking } = await buildHandlerContext(c, operation);
+        const { context, tracking } = await buildHandlerContext(c, operation, pathItemParameters);
         // Execute handler
         const { result } = await executeHandler(handlerCode, context);
         // Determine status code based on all store operations, prioritizing semantically meaningful ones
@@ -137,9 +161,12 @@ export async function mockHandlerResponse(c, operation) {
         if (result === undefined || result === null) {
             // Try to pick up example response from OpenAPI spec if available
             const prefer = parsePreferHeader(c.req.header('Prefer'));
-            const exampleResponse = getExampleFromResponse(c, statusCode, operation.responses, prefer.example);
+            const exampleResponse = getExampleFromResponse(c, statusCode, operation.responses, prefer.example, openapiVersion);
             if (exampleResponse !== null) {
-                return c.json(exampleResponse);
+                return c.body(exampleResponse);
+            }
+            if (isXmlMediaType(c.res.headers.get('Content-Type') ?? undefined)) {
+                return c.body(null);
             }
             return c.json(null);
         }

package/dist/types.d.ts

@@ -2,8 +2,6 @@ import type { OpenAPIV3_1 } from '@scalar/openapi-types';
 import type { Context } from 'hono';
 /** Available HTTP methods for Hono routes */
 export declare const httpMethods: readonly ["get", "put", "post", "delete", "options", "patch"];
-/** Valid HTTP method */
-export type HttpMethod = (typeof httpMethods)[number];
 /**
  * Represents a partial object where at least one of the given properties is required.
  */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,6CAA6C;AAC7C,eAAO,MAAM,WAAW,+DAAgE,CAAA;AAExF,wBAAwB;AACxB,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AAErD;;GAEG;AACH,KAAK,iBAAiB,CAAC,CAAC,EAAE,IAAI,SAAS,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,GACzF;KACG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;CACzE,CAAC,IAAI,CAAC,CAAA;AAET,uFAAuF;AACvF,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;AAErD,KAAK,qBAAqB,GAAG;IAC3B,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAE5C;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAEvC;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,WAAW,CAAC,eAAe,CAAA;KAAE,KAAK,IAAI,CAAA;IAExF;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IAEzB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,CAAC,qBAAqB,EAAE,eAAe,GAAG,UAAU,CAAC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,6CAA6C;AAC7C,eAAO,MAAM,WAAW,+DAAgE,CAAA;AAExF;;GAEG;AACH,KAAK,iBAAiB,CAAC,CAAC,EAAE,IAAI,SAAS,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,GACzF;KACG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;CACzE,CAAC,IAAI,CAAC,CAAA;AAET,uFAAuF;AACvF,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;AAErD,KAAK,qBAAqB,GAAG;IAC3B,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAE5C;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAEvC;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,WAAW,CAAC,eAAe,CAAA;KAAE,KAAK,IAAI,CAAA;IAExF;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IAEzB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,CAAC,qBAAqB,EAAE,eAAe,GAAG,UAAU,CAAC,CAAA"}

package/dist/utils/build-handler-context.d.ts

@@ -9,7 +9,8 @@ export type HandlerContext = {
     req: {
         body: any;
         params: Record<string, string>;
-        query: Record<string, string>;
+        /** Named query values, or the decoded content of an `in: querystring` parameter. */
+        query: unknown;
         headers: Record<string, string>;
     };
     res: Record<string, any>;
@@ -24,6 +25,6 @@ type HandlerContextResult = {
 /**
  * Build the handler context from a Hono context.
  */
-export declare function buildHandlerContext(c: Context, operation?: OpenAPIV3_1.OperationObject): Promise<HandlerContextResult>;
+export declare function buildHandlerContext(c: Context, operation?: OpenAPIV3_1.OperationObject, pathItemParameters?: OpenAPIV3_1.PathItemObject['parameters']): Promise<HandlerContextResult>;
 export {};
 //# sourceMappingURL=build-handler-context.d.ts.map

package/dist/utils/build-handler-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-handler-context.d.ts","sourceRoot":"","sources":["../../src/utils/build-handler-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAQnC,OAAO,EAAE,KAAK,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAGjF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,cAAc,CAAC,CAAA;IAC5D,GAAG,EAAE;QACH,IAAI,EAAE,GAAG,CAAA;QACT,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAChC,CAAA;IACD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CACzB,CAAA;AAED;;GAEG;AACH,KAAK,oBAAoB,GAAG;IAC1B,OAAO,EAAE,cAAc,CAAA;IACvB,QAAQ,EAAE,sBAAsB,CAAA;CACjC,CAAA;AA6DD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,GACtC,OAAO,CAAC,oBAAoB,CAAC,CA4C/B"}
+{"version":3,"file":"build-handler-context.d.ts","sourceRoot":"","sources":["../../src/utils/build-handler-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AASnC,OAAO,EAAE,KAAK,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAGjF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,cAAc,CAAC,CAAA;IAC5D,GAAG,EAAE;QACH,IAAI,EAAE,GAAG,CAAA;QACT,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC9B,oFAAoF;QACpF,KAAK,EAAE,OAAO,CAAA;QACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAChC,CAAA;IACD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CACzB,CAAA;AAED;;GAEG;AACH,KAAK,oBAAoB,GAAG;IAC1B,OAAO,EAAE,cAAc,CAAA;IACvB,QAAQ,EAAE,sBAAsB,CAAA;CACjC,CAAA;AA6DD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,EACvC,kBAAkB,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,GAC5D,OAAO,CAAC,oBAAoB,CAAC,CAuD/B"}

package/dist/utils/build-handler-context.js

@@ -6,6 +6,7 @@ import { generateResponseExample } from './generate-response-example.js';
 import { normalizeResponseBody } from './normalize-response-body.js';
 import { parsePreferHeader } from './parse-prefer-header.js';
 import { pathParameters } from './path-parameters.js';
+import { findQuerystringParameter, parseQuerystringParameter } from './querystring-parameter.js';
 import { createStoreWrapper } from './store-wrapper.js';
 import { getStreamingResponse } from './streaming-response.js';
 /**
@@ -55,7 +56,7 @@ function getExampleFromResponse(c, statusCode, responses) {
 /**
  * Build the handler context from a Hono context.
  */
-export async function buildHandlerContext(c, operation) {
+export async function buildHandlerContext(c, operation, pathItemParameters) {
     let body = undefined;
     try {
         // Compare case-insensitively, since media types are case-insensitive and request validation
@@ -77,6 +78,17 @@ export async function buildHandlerContext(c, operation) {
     catch {
         // Ignore parsing errors, body remains undefined
     }
+    const parameter = findQuerystringParameter(operation, pathItemParameters);
+    let query = Object.fromEntries(new URL(c.req.url).searchParams.entries());
+    if (parameter) {
+        try {
+            query = parseQuerystringParameter(c.req.url, parameter);
+        }
+        catch {
+            // With validation disabled, malformed content remains unavailable just like an invalid body.
+            query = undefined;
+        }
+    }
     const { wrappedStore, tracking } = createStoreWrapper(store);
     // Build res object with examples for all response status codes
     const res = {};
@@ -91,7 +103,7 @@ export async function buildHandlerContext(c, operation) {
             req: {
                 body,
                 params: pathParameters(c),
-                query: Object.fromEntries(new URL(c.req.url).searchParams.entries()),
+                query,
                 headers: Object.fromEntries(Object.entries(c.req.header()).map(([key, value]) => [key, value ?? ''])),
             },
             res,

package/dist/utils/get-operation.d.ts

@@ -1,8 +1,10 @@
 import type { OpenAPIV3_1 } from '@scalar/openapi-types';
-import { type HttpMethod } from '../types.js';
 /**
  * Takes a dereferenced OpenAPI document and returns all operations.
+ * Keys use their wire capitalization: fixed methods are uppercase, additional methods retain their case.
  * Ignores other attributes, like summary, parameters, etc.
  */
-export declare function getOperations(path?: OpenAPIV3_1.PathItemObject): Record<HttpMethod, OpenAPIV3_1.OperationObject>;
+export declare const getOperations: (path?: OpenAPIV3_1.PathItemObject & {
+    additionalOperations?: Record<string, OpenAPIV3_1.OperationObject>;
+}) => Record<string, OpenAPIV3_1.OperationObject>;
 //# sourceMappingURL=get-operation.d.ts.map

package/dist/utils/get-operation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-operation.d.ts","sourceRoot":"","sources":["../../src/utils/get-operation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,EAAE,KAAK,UAAU,EAAe,MAAM,SAAS,CAAA;AAEtD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,cAAc,GAAG,MAAM,CAAC,UAAU,EAAE,WAAW,CAAC,eAAe,CAAC,CAUhH"}
+{"version":3,"file":"get-operation.d.ts","sourceRoot":"","sources":["../../src/utils/get-operation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD;;;;GAIG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,WAAW,CAAC,cAAc,GAAG;IAClC,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,eAAe,CAAC,CAAA;CACnE,KACA,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,eAAe,CAc5C,CAAA"}

package/dist/utils/get-operation.js

@@ -1,14 +1,18 @@
 import { httpMethods } from '../types.js';
 /**
  * Takes a dereferenced OpenAPI document and returns all operations.
+ * Keys use their wire capitalization: fixed methods are uppercase, additional methods retain their case.
  * Ignores other attributes, like summary, parameters, etc.
  */
-export function getOperations(path) {
-    const operations = {};
+export const getOperations = (path) => {
+    const operations = new Map();
     for (const method of httpMethods) {
         if (path?.[method]) {
-            operations[method] = path?.[method];
+            operations.set(method.toUpperCase(), path[method]);
         }
     }
-    return operations;
-}
+    for (const [method, operation] of Object.entries(path?.additionalOperations ?? {})) {
+        operations.set(method, operation);
+    }
+    return Object.fromEntries(operations);
+};

package/dist/utils/process-asyncapi-document.d.ts

@@ -11,10 +11,11 @@ import type { AsyncApiDocument } from '@scalar/types/asyncapi/3.1';
  * Only AsyncAPI 3.1 is supported; 2.x documents should be upgraded before being passed in.
  *
  * @param document - The AsyncAPI document to process. Can be a string (URL/path) or an object.
+ * @param origin - Source file path or URL for resolving references in an already loaded document.
  * @returns A promise that resolves to the AsyncAPI document with lazily resolvable references.
  * @throws Error if the document cannot be processed or is invalid.
  */
-export declare function processAsyncApiDocument(document: string | Record<string, any> | undefined): Promise<AsyncApiDocument>;
+export declare function processAsyncApiDocument(document: string | Record<string, any> | undefined, origin?: string): Promise<AsyncApiDocument>;
 /**
  * Detects whether a loaded document describes an AsyncAPI API (rather than OpenAPI/Swagger).
  * Used to route an incoming document to the right mock engine.

package/dist/utils/process-asyncapi-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-asyncapi-document.d.ts","sourceRoot":"","sources":["../../src/utils/process-asyncapi-document.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAElE;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GACjD,OAAO,CAAC,gBAAgB,CAAC,CAiC3B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAE7D"}
+{"version":3,"file":"process-asyncapi-document.d.ts","sourceRoot":"","sources":["../../src/utils/process-asyncapi-document.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAElE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EAClD,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,CAAC,CAsC3B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAE7D"}

package/dist/utils/process-asyncapi-document.js

@@ -1,5 +1,8 @@
+import path from 'node:path';
+import { cwd } from 'node:process';
 import { bundle } from '@scalar/json-magic/bundle';
 import { fetchUrls, parseJson, parseYaml, readFiles } from '@scalar/json-magic/bundle/plugins/node';
+import { isFilePath } from '@scalar/json-magic/helpers/is-file-path';
 import { createMagicProxy } from '@scalar/json-magic/magic-proxy';
 /**
  * Processes an AsyncAPI document by bundling external references and wrapping it so internal
@@ -13,10 +16,11 @@ import { createMagicProxy } from '@scalar/json-magic/magic-proxy';
  * Only AsyncAPI 3.1 is supported; 2.x documents should be upgraded before being passed in.
  *
  * @param document - The AsyncAPI document to process. Can be a string (URL/path) or an object.
+ * @param origin - Source file path or URL for resolving references in an already loaded document.
  * @returns A promise that resolves to the AsyncAPI document with lazily resolvable references.
  * @throws Error if the document cannot be processed or is invalid.
  */
-export async function processAsyncApiDocument(document) {
+export async function processAsyncApiDocument(document, origin) {
     // Handle empty/undefined input gracefully with a minimal valid document.
     if (!document || (typeof document === 'object' && Object.keys(document).length === 0)) {
         return {
@@ -30,10 +34,14 @@ export async function processAsyncApiDocument(document) {
         };
     }
     let bundled;
+    // Keep references inside the source directory and prevent access to internal services.
+    const source = origin ?? document;
+    const basePath = typeof source === 'string' && isFilePath(source) ? path.dirname(path.resolve(source)) : cwd();
     try {
         // Bundle external references; parse string inputs (JSON or YAML) along the way.
         bundled = await bundle(document, {
-            plugins: [parseJson(), parseYaml(), readFiles(), fetchUrls()],
+            origin,
+            plugins: [parseJson(), parseYaml(), readFiles({ basePath }), fetchUrls({ blockPrivateNetworks: true })],
             treeShake: false,
         });
     }

package/dist/utils/querystring-parameter.d.ts

@@ -0,0 +1,11 @@
+import type { OpenAPIV3_2 } from '@scalar/openapi-types';
+/**
+ * Find the whole-query parameter, giving operation declarations precedence over path declarations.
+ * This module decodes incoming queries; workspace-store/src/helpers/querystring-parameter.ts serializes outgoing ones.
+ */
+export declare const findQuerystringParameter: (operation?: OpenAPIV3_2.OperationObject, pathParameters?: OpenAPIV3_2.PathItemObject["parameters"]) => OpenAPIV3_2.ParameterObject | undefined;
+/** Validate JSON-encoded form properties before the coercing form validator can alter their native types. */
+export declare const getQuerystringJsonSchema: (parameter: OpenAPIV3_2.ParameterObject | undefined) => Record<string, unknown> | null;
+/** Decode the complete query without introducing the parameter's documentary name. Throws on malformed JSON or URI escaping. */
+export declare const parseQuerystringParameter: (url: string, parameter: OpenAPIV3_2.ParameterObject) => unknown;
+//# sourceMappingURL=querystring-parameter.d.ts.map

package/dist/utils/querystring-parameter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"querystring-parameter.d.ts","sourceRoot":"","sources":["../../src/utils/querystring-parameter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAaxD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,GACnC,YAAY,WAAW,CAAC,eAAe,EACvC,iBAAiB,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,KACxD,WAAW,CAAC,eAAe,GAAG,SAMwB,CAAA;AAkBzD,6GAA6G;AAC7G,eAAO,MAAM,wBAAwB,GACnC,WAAW,WAAW,CAAC,eAAe,GAAG,SAAS,KACjD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAkC5B,CAAA;AAED,gIAAgI;AAChI,eAAO,MAAM,yBAAyB,GAAI,KAAK,MAAM,EAAE,WAAW,WAAW,CAAC,eAAe,KAAG,OA0E/F,CAAA"}

package/dist/utils/querystring-parameter.js

@@ -0,0 +1,135 @@
+import { getFirstMediaType } from '@scalar/helpers/http/get-first-media-type';
+import { isJsonMediaType } from '@scalar/helpers/http/is-json-media-type';
+import { parseMimeType } from '@scalar/helpers/http/mime-type';
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { getResolvedRefDeep } from '@scalar/workspace-store/helpers/get-resolved-ref-deep';
+import { deserializeArrayParameter, deserializeObjectParameter, getObjectPropertyNames, isArraySchema, isObjectSchema, resolveSerialization, } from './deserialize-parameter.js';
+/**
+ * Find the whole-query parameter, giving operation declarations precedence over path declarations.
+ * This module decodes incoming queries; workspace-store/src/helpers/querystring-parameter.ts serializes outgoing ones.
+ */
+export const findQuerystringParameter = (operation, pathParameters) => [
+    ...(Array.isArray(operation?.parameters) ? operation.parameters : []),
+    ...(Array.isArray(pathParameters) ? pathParameters : []),
+]
+    .map((parameter) => getResolvedRef(parameter))
+    .find((parameter) => parameter?.in === 'querystring');
+/** Collect form properties through compositions so nullable and composed objects retain their encoding. */
+const getPropertySchemas = (schema) => {
+    const properties = {};
+    for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
+        const branches = schema?.[keyword];
+        if (Array.isArray(branches)) {
+            for (const branch of branches) {
+                if (branch && typeof branch === 'object') {
+                    Object.assign(properties, getPropertySchemas(branch));
+                }
+            }
+        }
+    }
+    return { ...properties, ...schema?.properties };
+};
+/** Validate JSON-encoded form properties before the coercing form validator can alter their native types. */
+export const getQuerystringJsonSchema = (parameter) => {
+    const [contentType, media] = getFirstMediaType(parameter?.content) ?? [];
+    if (parseMimeType(contentType).essence !== 'application/x-www-form-urlencoded') {
+        return null;
+    }
+    const selectJsonProperties = (schema) => {
+        const properties = (schema?.properties ?? {});
+        const jsonProperties = Object.fromEntries(Object.entries(properties).filter(([name, property]) => {
+            const encoding = media?.encoding?.[name];
+            if (encoding?.style !== undefined || encoding?.explode !== undefined || encoding?.allowReserved !== undefined) {
+                return false;
+            }
+            const item = isArraySchema(property) ? property.items : property;
+            return isJsonMediaType(encoding?.contentType) || isObjectSchema(item) || isArraySchema(item);
+        }));
+        const result = { properties: jsonProperties };
+        for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
+            const branches = schema?.[keyword];
+            if (Array.isArray(branches)) {
+                // Non-JSON fields may distinguish oneOf branches. The complete validator enforces exclusivity.
+                const target = keyword === 'oneOf' ? 'anyOf' : keyword;
+                const selected = branches.map((branch) => selectJsonProperties(branch));
+                if (target in result) {
+                    result.allOf = [...(Array.isArray(result.allOf) ? result.allOf : []), { [target]: selected }];
+                }
+                else {
+                    result[target] = selected;
+                }
+            }
+        }
+        return result;
+    };
+    return selectJsonProperties(getResolvedRefDeep(media?.schema));
+};
+/** Decode the complete query without introducing the parameter's documentary name. Throws on malformed JSON or URI escaping. */
+export const parseQuerystringParameter = (url, parameter) => {
+    const query = new URL(url).search.slice(1);
+    if (!query) {
+        return undefined;
+    }
+    const [contentType, media] = getFirstMediaType(parameter.content) ?? [];
+    const mediaType = parseMimeType(contentType).essence;
+    if (mediaType !== 'application/x-www-form-urlencoded') {
+        const decoded = decodeURIComponent(query);
+        return isJsonMediaType(mediaType) ? JSON.parse(decoded) : decoded;
+    }
+    const params = new URLSearchParams(query);
+    const map = Object.fromEntries([...new Set(params.keys())].map((key) => {
+        const values = params.getAll(key);
+        return [key, values.length === 1 ? (values[0] ?? '') : values];
+    }));
+    const result = { ...map };
+    const schema = getResolvedRefDeep(media?.schema);
+    const properties = getPropertySchemas(schema);
+    for (const name of getObjectPropertyNames(schema)) {
+        const property = properties?.[name];
+        const encoding = media?.encoding?.[name];
+        const single = params.get(name) ?? undefined;
+        const styleBased = encoding?.style !== undefined || encoding?.explode !== undefined || encoding?.allowReserved !== undefined;
+        if (styleBased) {
+            const { style, explode } = resolveSerialization('query', encoding?.style, encoding?.explode);
+            const value = isObjectSchema(property)
+                ? deserializeObjectParameter({
+                    style,
+                    explode,
+                    single,
+                    map,
+                    name,
+                    propertyNames: getObjectPropertyNames(property),
+                    reservedKeys: new Set(Object.keys(properties)),
+                })
+                : isArraySchema(property)
+                    ? deserializeArrayParameter({
+                        style,
+                        explode,
+                        single,
+                        multi: params.has(name) ? params.getAll(name) : undefined,
+                    })
+                    : single;
+            if (value !== undefined) {
+                if (isObjectSchema(property) &&
+                    (style === 'deepObject' || (style === 'form' && explode)) &&
+                    typeof value === 'object' &&
+                    value !== null) {
+                    for (const key of Object.keys(value)) {
+                        delete result[style === 'deepObject' ? `${name}[${key}]` : key];
+                    }
+                }
+                result[name] = value;
+            }
+            continue;
+        }
+        if (single === undefined) {
+            continue;
+        }
+        const json = isJsonMediaType(encoding?.contentType);
+        const decode = (value, itemSchema) => json || isObjectSchema(itemSchema) || isArraySchema(itemSchema) ? JSON.parse(value) : value;
+        result[name] = isArraySchema(property)
+            ? params.getAll(name).map((value) => decode(value, property?.items))
+            : decode(single, property);
+    }
+    return result;
+};

package/dist/utils/select-response-example.d.ts

@@ -1,4 +1,9 @@
 import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { ExampleObject } from '@scalar/workspace-store/schemas/v3.2/strict/example';
+type SelectedResponseExample = ExampleObject & {
+    value: unknown;
+    provenance?: 'serialized' | 'data';
+};
 /**
  * Pick the example body for a response media type.
  *
@@ -18,7 +23,6 @@ import type { OpenAPIV3_1 } from '@scalar/openapi-types';
  */
 export declare const selectResponseExample: <T extends Pick<OpenAPIV3_1.MediaTypeObject, "example" | "examples"> & {
     schema?: unknown;
-}>(mediaType: T | undefined, exampleName?: string) => {
-    value: unknown;
-} | undefined;
+}>(mediaType: T | undefined, exampleName?: string) => SelectedResponseExample | undefined;
+export {};
 //# sourceMappingURL=select-response-example.d.ts.map

package/dist/utils/select-response-example.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"select-response-example.d.ts","sourceRoot":"","sources":["../../src/utils/select-response-example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,GAChC,CAAC,SAAS,IAAI,CAAC,WAAW,CAAC,eAAe,EAAE,SAAS,GAAG,UAAU,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,EAE1F,WAAW,CAAC,GAAG,SAAS,EACxB,cAAc,MAAM,KACnB;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,SAoCvB,CAAA"}
+{"version":3,"file":"select-response-example.d.ts","sourceRoot":"","sources":["../../src/utils/select-response-example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAA;AAExF,KAAK,uBAAuB,GAAG,aAAa,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,YAAY,GAAG,MAAM,CAAA;CAAE,CAAA;AAarG;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,GAChC,CAAC,SAAS,IAAI,CAAC,WAAW,CAAC,eAAe,EAAE,SAAS,GAAG,UAAU,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,EAE1F,WAAW,CAAC,GAAG,SAAS,EACxB,cAAc,MAAM,KACnB,uBAAuB,GAAG,SAkC5B,CAAA"}

package/dist/utils/select-response-example.js

@@ -1,4 +1,14 @@
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+/** Keep serialized/data examples distinguishable until the media serializer runs. */
+const exampleValue = (example) => {
+    if (example?.serializedValue !== undefined) {
+        return { serializedValue: example.serializedValue, value: example.serializedValue, provenance: 'serialized' };
+    }
+    if (example?.dataValue !== undefined) {
+        return { dataValue: example.dataValue, value: example.dataValue, provenance: 'data' };
+    }
+    return example?.value !== undefined ? { value: example.value } : undefined;
+};
 /**
  * Pick the example body for a response media type.
  *
@@ -23,9 +33,9 @@ export const selectResponseExample = (mediaType, exampleName) => {
     const { example, examples } = mediaType;
     // 1. A named example requested via `Prefer: example=<name>`
     if (exampleName && examples && exampleName in examples) {
-        const value = getResolvedRef(examples[exampleName])?.value;
-        if (value !== undefined) {
-            return { value };
+        const selected = exampleValue(getResolvedRef(examples[exampleName]));
+        if (selected) {
+            return selected;
         }
     }
     // 2. The singular `example` keyword
@@ -36,9 +46,9 @@ export const selectResponseExample = (mediaType, exampleName) => {
     if (examples) {
         const firstKey = Object.keys(examples)[0];
         if (firstKey !== undefined) {
-            const value = getResolvedRef(examples[firstKey])?.value;
-            if (value !== undefined) {
-                return { value };
+            const selected = exampleValue(getResolvedRef(examples[firstKey]));
+            if (selected) {
+                return selected;
             }
         }
     }

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

@@ -6,6 +6,6 @@ type Schema = NonNullable<OpenAPIV3_1.ComponentsObject['schemas']>[string];
  * 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 declare const serializeResponseBody: (body: unknown, contentType: string | undefined, schema?: Schema, provenance?: "data" | "serialized") => string | undefined;
 export {};
 //# sourceMappingURL=serialize-response-body.d.ts.map

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

@@ -1 +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"}
+{"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;AAKxD,KAAK,MAAM,GAAG,WAAW,CAAC,WAAW,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AA2D1E;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,OAAO,EACb,aAAa,MAAM,GAAG,SAAS,EAC/B,SAAS,MAAM,EACf,aAAa,MAAM,GAAG,YAAY,KACjC,MAAM,GAAG,SAsCX,CAAA"}

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

@@ -1,5 +1,8 @@
-import { json2xml } from '@scalar/helpers/file/json2xml';
+import { isXmlMediaType } from '@scalar/helpers/http/is-xml-media-type';
 import { parseMimeType } from '@scalar/helpers/http/mime-type';
+import { serializeXmlExample } from '@scalar/workspace-store/request-example';
+import { coerceValue } from '@scalar/workspace-store/schemas/typebox-coerce';
+import { SchemaObjectSchema } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
 /**
  * Whether a media type carries a single JSON document.
  *
@@ -13,11 +16,6 @@ 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.
  *
@@ -58,11 +56,17 @@ const isSerializedJsonDocument = (value) => {
  * 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);
+export const serializeResponseBody = (body, contentType, schema, provenance) => {
+    if (provenance === 'serialized' && typeof body === 'string') {
+        return body;
+    }
+    if (provenance === 'data' && isJsonDocumentContentType(contentType)) {
+        return JSON.stringify(body);
+    }
+    if (isXmlMediaType(contentType)) {
+        return typeof body === 'string'
+            ? body
+            : serializeXmlExample(body, coerceValue(SchemaObjectSchema, schema ?? {}), { mode: 'read' }).xml;
     }
     if (typeof body === 'string') {
         // Anywhere but a single JSON document, the characters are the payload: `text/plain`, `text/html`,

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;AAoStD;;;;;;;;;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":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,uBAAuB,CAAA;AAMrE,OAAO,KAAK,EAAW,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAuTtD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,WAAW,WAAW,CAAC,eAAe,EACtC,qBAAqB,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,KAC5D,iBAmLF,CAAA"}

package/dist/utils/validate-request.js

@@ -1,9 +1,12 @@
+import { getFirstMediaType } from '@scalar/helpers/http/get-first-media-type';
+import { parseMimeType } from '@scalar/helpers/http/mime-type';
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { getResolvedRefDeep } from '@scalar/workspace-store/helpers/get-resolved-ref-deep';
 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 { findQuerystringParameter, getQuerystringJsonSchema, parseQuerystringParameter } from './querystring-parameter.js';
 import { replaceCircularMarkers } from './replace-circular-markers.js';
 /**
  * Prepare a resolved schema for Ajv by replacing the `'[circular]'` markers a recursive schema leaves
@@ -113,7 +116,7 @@ const mergeParameters = (pathItemParameters, operationParameters) => {
  * in isolation so one broken schema never disables the others.
  */
 const compileSchema = (ajv, schema, label) => {
-    if (!schema) {
+    if (schema === null || schema === undefined) {
         return null;
     }
     try {
@@ -140,6 +143,9 @@ const compileValidators = (operation, pathItemParameters) => {
     const queryParameters = buildParameterSchema(parameters, 'query');
     const headerParameters = buildParameterSchema(parameters, 'header');
     const cookieParameters = buildParameterSchema(parameters, 'cookie');
+    const querystringParameter = findQuerystringParameter(operation, pathItemParameters);
+    const [querystringContentType, querystringMedia] = getFirstMediaType(querystringParameter?.content) ?? [];
+    const querystringSchema = querystringMedia?.schema;
     const requestBody = getResolvedRef(operation.requestBody);
     // Build the body schema defensively; resolving a malformed `$ref` should not crash setup.
     let bodySchema = null;
@@ -151,6 +157,9 @@ const compileValidators = (operation, pathItemParameters) => {
         console.error('Error resolving request body schema, skipping body validation:', error);
     }
     return {
+        querystringParameter,
+        querystringJson: compileSchema(bodyAjv, getQuerystringJsonSchema(querystringParameter), 'querystring JSON properties'),
+        querystring: compileSchema(parseMimeType(querystringContentType).essence === 'application/x-www-form-urlencoded' ? parameterAjv : bodyAjv, querystringSchema === undefined ? null : asCompilableSchema(getResolvedRefDeep(querystringSchema)), 'querystring parameter'),
         path: compileSchema(parameterAjv, pathParameters?.schema ?? null, 'path parameter'),
         query: compileSchema(parameterAjv, queryParameters?.schema ?? null, 'query parameter'),
         header: compileSchema(parameterAjv, headerParameters?.schema ?? null, 'header parameter'),
@@ -312,6 +321,25 @@ export const validateRequest = (operation, pathItemParameters) => {
                 violations.push(...mapErrors(validator.errors, location));
             }
         }
+        if (validators.querystringParameter) {
+            try {
+                const value = parseQuerystringParameter(c.req.url, validators.querystringParameter);
+                if (value === undefined) {
+                    if (validators.querystringParameter.required) {
+                        violations.push({ location: 'query', path: '', message: 'Query string is required' });
+                    }
+                }
+                else if (validators.querystringJson && !validators.querystringJson(value)) {
+                    violations.push(...mapErrors(validators.querystringJson.errors, 'query'));
+                }
+                else if (validators.querystring && !validators.querystring(value)) {
+                    violations.push(...mapErrors(validators.querystring.errors, 'query'));
+                }
+            }
+            catch {
+                violations.push({ location: 'query', path: '', message: 'Query string could not be decoded' });
+            }
+        }
         // Request body — only `application/json` in this slice
         if (validators.body || validators.bodyRequired) {
             // Read from a clone so the original request stream stays intact for the mock or `x-handler`

package/package.json

@@ -16,7 +16,7 @@
     "swagger",
     "cli"
   ],
-  "version": "0.15.0",
+  "version": "0.17.0",
   "engines": {
     "node": ">=22"
   },
@@ -53,12 +53,12 @@
   "dependencies": {
     "@faker-js/faker": "10.6.0",
     "@hono/node-server": "^2.1.1",
-    "@scalar/helpers": "0.13.0",
-    "@scalar/json-magic": "0.15.0",
+    "@scalar/helpers": "0.15.0",
+    "@scalar/json-magic": "0.15.2",
     "@scalar/openapi-types": "0.9.7",
-    "@scalar/openapi-upgrader": "0.3.0",
-    "@scalar/types": "0.21.0",
-    "@scalar/workspace-store": "0.65.0",
+    "@scalar/openapi-upgrader": "0.4.0",
+    "@scalar/types": "0.22.1",
+    "@scalar/workspace-store": "0.67.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "hono": "^4.13.8",
@@ -69,7 +69,7 @@
   "devDependencies": {
     "@types/node": "^24.1.0",
     "@types/ws": "8.18.1",
-    "undici": "7.24.4",
+    "undici": "7.29.0",
     "vite": "8.1.5"
   },
   "scripts": {