@scalar/mock-server 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @scalar/mock-server
 
+## 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-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] }));
     /** 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));
             }
             else {
                 handlers.push(async (c) => await mockAnyResponse(c, operation));
             }
-            if (query.length === 0) {
-                handlers.forEach((handler) => app[method](route, handler));
-                return;
-            }
             // 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-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']): 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":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AA4HnC;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,EAAE,WAAW,CAAC,eAAe,EACtC,kBAAkB,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,qBAqE9D"}

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

@@ -98,7 +98,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) {
     // 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 +109,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

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/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/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.16.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.14.0",
+    "@scalar/json-magic": "0.15.1",
     "@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.3.1",
+    "@scalar/types": "0.22.0",
+    "@scalar/workspace-store": "0.66.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "hono": "^4.13.8",