@scalar/mock-server 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @scalar/mock-server
 
+## 0.11.1
+
+### Patch Changes
+
+- [#9518](https://github.com/scalar/scalar/pull/9518): fix: compact generated JSON mock responses so finite JSONL and NDJSON bodies stay valid as single-line events.
+- [#9517](https://github.com/scalar/scalar/pull/9517): fix: improve default response selection when mocking operations with multiple response codes. The mock server now prefers the lowest 2xx success, then the lowest non-informational code, then the `default` catch-all, only falling back to a 1xx response when nothing else is defined. Status code range patterns like `2XX` are supported and treated as their lowest member, with explicit codes taking precedence over the range that covers them.
+- [#9519](https://github.com/scalar/scalar/pull/9519): fix: wrap singular examples in arrays when the response schema is an array.
+
 ## 0.11.0
 
 ### Minor Changes

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":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAMxD;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe;;4PAiGjF"}
+{"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;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAOxD;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe;;4PAwGjF"}

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

@@ -4,6 +4,7 @@ import { getResolvedRefDeep } from '@scalar/workspace-store/helpers/get-resolved
 import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
 import { accepts } from 'hono/accepts';
 import { findPreferredResponseKey } from '../utils/find-preferred-response-key.js';
+import { normalizeResponseBody } from '../utils/normalize-response-body.js';
 import { parsePreferHeader } from '../utils/parse-prefer-header.js';
 import { selectResponseExample } from '../utils/select-response-example.js';
 /**
@@ -26,8 +27,8 @@ export function mockAnyResponse(c, operation) {
         c.status(500);
         return c.json({ error: 'No response defined for this operation.' });
     }
-    // Status code
-    const statusCode = Number.parseInt(responseKey === 'default' ? '200' : (responseKey ?? '200'), 10);
+    // Status code. `default` and range patterns like `2XX` map to their lowest concrete code (e.g. 200).
+    const statusCode = Number.parseInt(responseKey && responseKey !== 'default' ? responseKey.replace(/XX$/i, '00') : '200', 10);
     // Headers
     const headers = selectedResponse?.headers ?? {};
     Object.keys(headers).forEach((header) => {
@@ -63,14 +64,15 @@ 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);
+    const responseSchema = acceptedResponse?.schema ? getResolvedRefDeep(acceptedResponse.schema) : undefined;
     const body = selectedExample
-        ? selectedExample.value
-        : acceptedResponse?.schema
-            ? getExampleFromSchema(getResolvedRefDeep(acceptedResponse.schema), {
+        ? normalizeResponseBody(selectedExample.value, responseSchema)
+        : responseSchema
+            ? normalizeResponseBody(getExampleFromSchema(responseSchema, {
                 emptyString: 'string',
                 variables: c.req.param(),
                 mode: 'read',
-            })
+            }), responseSchema)
             : null;
     c.status(statusCode);
     return c.body(
@@ -82,7 +84,7 @@ export function mockAnyResponse(c, operation) {
             acceptedContentType?.includes('xml')
                 ? json2xml(body)
                 : // JSON
-                    JSON.stringify(body, null, 2)
+                    JSON.stringify(body)
         : typeof body === 'string'
             ? // String
                 body

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;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AA8HxD;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,gMA8D3F"}
+{"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;AAGxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAoIxD;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,gMA8D3F"}

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

@@ -1,9 +1,9 @@
 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 { accepts } from 'hono/accepts';
 import { buildHandlerContext } from '../utils/build-handler-context.js';
 import { executeHandler } from '../utils/execute-handler.js';
+import { normalizeResponseBody } from '../utils/normalize-response-body.js';
 import { parsePreferHeader } from '../utils/parse-prefer-header.js';
 import { selectResponseExample } from '../utils/select-response-example.js';
 /**
@@ -40,16 +40,17 @@ function getExampleFromResponse(c, statusCode, responses, exampleName) {
     if (!acceptedResponse) {
         return null;
     }
+    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
-        ? selectedExample.value
-        : acceptedResponse.schema
-            ? getExampleFromSchema(getResolvedRefDeep(acceptedResponse.schema), {
+        ? normalizeResponseBody(selectedExample.value, responseSchema)
+        : responseSchema
+            ? normalizeResponseBody(getExampleFromSchema(responseSchema, {
                 emptyString: 'string',
                 variables: c.req.param(),
                 mode: 'read',
-            })
+            }), responseSchema)
             : null;
 }
 /**

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,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAInC,OAAO,EAAE,KAAK,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAEjF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,cAAc,CAAC,CAAA;IAC5D,KAAK,EAAE,OAAO,KAAK,CAAA;IACnB,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;AAuDD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,GACtC,OAAO,CAAC,oBAAoB,CAAC,CAiD/B"}
+{"version":3,"file":"build-handler-context.d.ts","sourceRoot":"","sources":["../../src/utils/build-handler-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAKnC,OAAO,EAAE,KAAK,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAEjF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,cAAc,CAAC,CAAA;IAC5D,KAAK,EAAE,OAAO,KAAK,CAAA;IACnB,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;AA4DD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,GACtC,OAAO,CAAC,oBAAoB,CAAC,CAiD/B"}

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

@@ -4,6 +4,7 @@ import { getResolvedRefDeep } from '@scalar/workspace-store/helpers/get-resolved
 import { getExampleFromSchema } from '@scalar/workspace-store/request-example';
 import { accepts } from 'hono/accepts';
 import { store } from '../libs/store.js';
+import { normalizeResponseBody } from './normalize-response-body.js';
 import { createStoreWrapper } from './store-wrapper.js';
 /**
  * Get example response from OpenAPI spec for a given status code.
@@ -34,15 +35,16 @@ function getExampleFromResponse(c, statusCode, responses) {
     if (!acceptedResponse) {
         return null;
     }
+    const responseSchema = acceptedResponse.schema ? getResolvedRefDeep(acceptedResponse.schema) : undefined;
     // Extract example from example property or generate from schema
     return acceptedResponse.example !== undefined
-        ? acceptedResponse.example
-        : acceptedResponse.schema
-            ? getExampleFromSchema(getResolvedRefDeep(acceptedResponse.schema), {
+        ? normalizeResponseBody(acceptedResponse.example, responseSchema)
+        : responseSchema
+            ? normalizeResponseBody(getExampleFromSchema(responseSchema, {
                 emptyString: 'string',
                 variables: c.req.param(),
                 mode: 'read',
-            })
+            }), responseSchema)
             : null;
 }
 /**

package/dist/utils/find-preferred-response-key.d.ts

@@ -1,5 +1,18 @@
 /**
- * Find the preferred response key: default, 200, 201 …
+ * Find the preferred response key to mock.
+ *
+ * Preference order:
+ * 1. The lowest 2xx success response
+ * 2. The lowest non-informational code (3xx/4xx/5xx)
+ * 3. `default` — the catch-all for undeclared responses (typically an error)
+ * 4. An informational 1xx response, only when nothing else is defined
+ *
+ * Within each tier an explicit code wins over the range pattern that covers it (e.g. `200` over
+ * `2XX`), and range patterns are treated as their lowest member (e.g. `2XX` → `200`). `default`
+ * is the catch-all for codes not covered individually, so a defined success or error is preferred
+ * over it.
+ *
+ * @see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#responses-object
  */
 export declare function findPreferredResponseKey(responses?: string[]): string | undefined;
 //# sourceMappingURL=find-preferred-response-key.d.ts.map

package/dist/utils/find-preferred-response-key.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find-preferred-response-key.d.ts","sourceRoot":"","sources":["../../src/utils/find-preferred-response-key.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,sBAQ5D"}
+{"version":3,"file":"find-preferred-response-key.d.ts","sourceRoot":"","sources":["../../src/utils/find-preferred-response-key.ts"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAiBjF"}

package/dist/utils/find-preferred-response-key.js

@@ -1,11 +1,45 @@
+/** Matches an explicit HTTP status code (e.g. `200`) or a range pattern (e.g. `2XX`). */
+const STATUS_CODE_REGEX = /^[1-5](\d{2}|XX)$/i;
+/** Whether a status key is a range pattern (e.g. `2XX`) rather than an explicit code. */
+const isRange = (response) => /XX$/i.test(response);
+/** Whether a status key is an informational 1xx response. */
+const isInformational = (response) => response.startsWith('1');
+/** Whether a status key is a 2xx success response. */
+const isSuccess = (response) => response.startsWith('2');
+/** Turn a status key into a comparable number, treating a range like `2XX` as its lowest member (`200`). */
+const toComparableStatus = (response) => Number.parseInt(response.replace(/XX$/i, '00'), 10);
+const sortStatusCodes = (responses) => responses
+    .filter((response) => STATUS_CODE_REGEX.test(response))
+    .sort((left, right) => {
+    const difference = toComparableStatus(left) - toComparableStatus(right);
+    // On a tie, prefer an explicit code over a range pattern (e.g. `200` before `2XX`).
+    return difference !== 0 ? difference : Number(isRange(left)) - Number(isRange(right));
+});
 /**
- * Find the preferred response key: default, 200, 201 …
+ * Find the preferred response key to mock.
+ *
+ * Preference order:
+ * 1. The lowest 2xx success response
+ * 2. The lowest non-informational code (3xx/4xx/5xx)
+ * 3. `default` — the catch-all for undeclared responses (typically an error)
+ * 4. An informational 1xx response, only when nothing else is defined
+ *
+ * Within each tier an explicit code wins over the range pattern that covers it (e.g. `200` over
+ * `2XX`), and range patterns are treated as their lowest member (e.g. `2XX` → `200`). `default`
+ * is the catch-all for codes not covered individually, so a defined success or error is preferred
+ * over it.
+ *
+ * @see https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#responses-object
  */
 export function findPreferredResponseKey(responses) {
-    return (
-    // Regular status codes
-    ['default', '200', '201', '204', '404', '500'].find((key) => responses?.includes(key) ?? false) ??
-        // Lowest status code
-        responses?.sort()[0] ??
-        undefined);
+    if (!responses?.length) {
+        return undefined;
+    }
+    const statusCodes = sortStatusCodes(responses);
+    // Within a tier, prefer an explicit status code over the range pattern that covers it.
+    const byPreference = (predicate) => statusCodes.find((response) => predicate(response) && !isRange(response)) ?? statusCodes.find(predicate);
+    return (byPreference(isSuccess) ??
+        byPreference((response) => !isInformational(response)) ??
+        (responses.includes('default') ? 'default' : undefined) ??
+        byPreference(isInformational));
 }

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

@@ -0,0 +1,5 @@
+import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+type Schema = NonNullable<OpenAPIV3_1.ComponentsObject['schemas']>[string];
+export declare const normalizeResponseBody: (body: unknown, schema: Schema) => unknown;
+export {};
+//# sourceMappingURL=normalize-response-body.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-response-body.d.ts","sourceRoot":"","sources":["../../src/utils/normalize-response-body.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,KAAK,MAAM,GAAG,WAAW,CAAC,WAAW,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AA0B1E,eAAO,MAAM,qBAAqB,GAAI,MAAM,OAAO,EAAE,QAAQ,MAAM,KAAG,OAMrE,CAAA"}

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

@@ -0,0 +1,25 @@
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+const isArrayResponseSchema = (schema) => {
+    if (!schema) {
+        return false;
+    }
+    const resolvedSchema = getResolvedRef(schema);
+    if (!resolvedSchema || typeof resolvedSchema !== 'object') {
+        return false;
+    }
+    if ('type' in resolvedSchema) {
+        if (resolvedSchema.type === 'array') {
+            return true;
+        }
+        if (Array.isArray(resolvedSchema.type) && resolvedSchema.type.includes('array')) {
+            return true;
+        }
+    }
+    return 'items' in resolvedSchema;
+};
+export const normalizeResponseBody = (body, schema) => {
+    if (body === null || body === undefined || Array.isArray(body) || !isArrayResponseSchema(schema)) {
+        return body;
+    }
+    return [body];
+};

package/package.json

@@ -16,7 +16,7 @@
     "swagger",
     "cli"
   ],
-  "version": "0.11.0",
+  "version": "0.11.1",
   "engines": {
     "node": ">=22"
   },
@@ -57,10 +57,10 @@
     "hono": "^4.12.7",
     "yaml": "^2.8.3",
     "@scalar/helpers": "0.8.2",
-    "@scalar/json-magic": "0.12.16",
     "@scalar/openapi-types": "0.9.1",
+    "@scalar/json-magic": "0.12.16",
     "@scalar/openapi-upgrader": "0.2.9",
-    "@scalar/workspace-store": "0.54.3"
+    "@scalar/workspace-store": "0.54.4"
   },
   "devDependencies": {
     "@types/node": "^24.1.0",