@scalar/mock-server 0.10.15 → 0.10.17

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @scalar/mock-server
 
+## 0.10.17
+
+### Patch Changes
+
+- [#9437](https://github.com/scalar/scalar/pull/9437): chore(mock-server): resolve OpenAPI references with `@scalar/workspace-store` instead of `@scalar/openapi-parser`
+
+  The mock server no longer eagerly dereferences the whole document. It now keeps `$ref` nodes intact via the `@scalar/json-magic` magic proxy and resolves them lazily with `getResolvedRef`/`getResolvedRefDeep` from `@scalar/workspace-store`. The `/openapi.{json,yaml}` endpoints use `@scalar/json-magic` and `yaml` for normalization and serialization. This drops the `@scalar/openapi-parser` dependency. Behavior is unchanged.
+
+## 0.10.16
+
 ## 0.10.15
 
 ## 0.10.14

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":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAG3B,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAgB5D;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,aAAa,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoFtF"}
+{"version":3,"file":"create-mock-server.d.ts","sourceRoot":"","sources":["../src/create-mock-server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAG3B,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAgB5D;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,aAAa,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuFtF"}

package/dist/create-mock-server.js

@@ -1,3 +1,4 @@
+import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 import { buildSeedContext } from './utils/build-seed-context.js';
@@ -25,7 +26,8 @@ export async function createMockServer(configuration) {
     const schemas = schema?.components?.schemas;
     if (schemas) {
         for (const [schemaName, schemaObject] of Object.entries(schemas)) {
-            const seedCode = schemaObject?.['x-seed'];
+            // Merge `$ref` siblings so an `x-seed` placed next to a `$ref` is preserved (OpenAPI 3.1 semantics)
+            const seedCode = getResolvedRef(schemaObject, mergeSiblingReferences)?.['x-seed'];
             if (seedCode && typeof seedCode === 'string') {
                 try {
                     // Check if collection is empty (idempotent seeding)
@@ -53,11 +55,13 @@ export async function createMockServer(configuration) {
     /** Paths specified in the OpenAPI document */
     const paths = schema?.paths ?? {};
     Object.keys(paths).forEach((path) => {
-        const methods = Object.keys(getOperations(paths[path]));
+        // 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));
         /** Keys for all operations of a specified path */
         methods.forEach((method) => {
             const route = honoRouteFromPath(path);
-            const operation = schema?.paths?.[path]?.[method];
+            const operation = pathItem?.[method];
             // Check if authentication is required for this operation
             if (isAuthenticationRequired(operation.security)) {
                 app[method](route, handleAuthentication(schema, operation));

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;AAExD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAExD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAGhD;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,EAAE,OAAO,EAAE,iBAAiB;;yPAqF7G"}
+{"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;AAExD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAGhD;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,eAAe,EAAE,OAAO,EAAE,iBAAiB;;yPAwF7G"}

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

@@ -1,4 +1,6 @@
 import { json2xml } from '@scalar/helpers/file/json2xml';
+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 { findPreferredResponseKey } from '../utils/find-preferred-response-key.js';
@@ -16,7 +18,7 @@ export function mockAnyResponse(c, operation, options) {
     // Response
     // default, 200, 201 …
     const preferredResponseKey = findPreferredResponseKey(Object.keys(operation.responses ?? {}));
-    const preferredResponse = preferredResponseKey ? operation.responses?.[preferredResponseKey] : null;
+    const preferredResponse = preferredResponseKey ? getResolvedRef(operation.responses?.[preferredResponseKey]) : null;
     if (!preferredResponse) {
         c.status(500);
         return c.json({ error: 'No response defined for this operation.' });
@@ -26,7 +28,10 @@ export function mockAnyResponse(c, operation, options) {
     // Headers
     const headers = preferredResponse?.headers ?? {};
     Object.keys(headers).forEach((header) => {
-        const value = headers[header].schema ? getExampleFromSchema(headers[header].schema) : null;
+        const headerObject = getResolvedRef(headers[header]);
+        const value = headerObject?.schema
+            ? getExampleFromSchema(getResolvedRefDeep(headerObject.schema))
+            : null;
         if (value !== null) {
             c.header(header, value);
         }
@@ -56,7 +61,7 @@ export function mockAnyResponse(c, operation, options) {
     const body = acceptedResponse?.example
         ? acceptedResponse.example
         : acceptedResponse?.schema
-            ? getExampleFromSchema(acceptedResponse.schema, {
+            ? getExampleFromSchema(getResolvedRefDeep(acceptedResponse.schema), {
                 emptyString: 'string',
                 variables: c.req.param(),
                 mode: 'read',

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;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAExD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAoHhD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,EAAE,WAAW,CAAC,eAAe,EACtC,OAAO,EAAE,iBAAiB,gMAkE3B"}
+{"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;AAExD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAoHhD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,CAAC,EAAE,OAAO,EACV,SAAS,EAAE,WAAW,CAAC,eAAe,EACtC,OAAO,EAAE,iBAAiB,gMAkE3B"}

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

@@ -1,3 +1,5 @@
+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';
@@ -11,7 +13,7 @@ function getExampleFromResponse(c, statusCode, responses) {
         return null;
     }
     const statusCodeStr = statusCode.toString();
-    const response = responses[statusCodeStr] || responses.default;
+    const response = getResolvedRef(responses[statusCodeStr] || responses.default);
     if (!response) {
         return null;
     }
@@ -36,7 +38,7 @@ function getExampleFromResponse(c, statusCode, responses) {
     return acceptedResponse.example !== undefined
         ? acceptedResponse.example
         : acceptedResponse.schema
-            ? getExampleFromSchema(acceptedResponse.schema, {
+            ? getExampleFromSchema(getResolvedRefDeep(acceptedResponse.schema), {
                 emptyString: 'string',
                 variables: c.req.param(),
                 mode: 'read',

package/dist/routes/respond-with-openapi-document.d.ts

@@ -2,17 +2,7 @@ import type { Context } from 'hono';
 /**
  * OpenAPI endpoints
  */
-export declare function respondWithOpenApiDocument(c: Context, input?: string | Record<string, any>, format?: 'json' | 'yaml'): (Response & import("hono").TypedResponse<"Not found", 404, "text">) | (Response & import("hono").TypedResponse<{
-    [x: string]: import("hono/utils/types").JSONValue;
-} | {
-    dir: string;
-    isEntrypoint: boolean;
-    references: string[];
-    filename: string;
-    specification: {
-        [x: string]: import("hono/utils/types").JSONValue;
-    };
-}[], import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<string, 200, "text">) | (Response & import("hono").TypedResponse<{
+export declare function respondWithOpenApiDocument(c: Context, input?: string | Record<string, any>, format?: 'json' | 'yaml'): (Response & import("hono").TypedResponse<"Not found", 404, "text">) | (Response & import("hono").TypedResponse<import("hono/utils/types").JSONValue, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<string, 200, "text">) | (Response & import("hono").TypedResponse<{
     error: string;
     message: string;
 }, 500, "json">) | (Response & import("hono").TypedResponse<{

package/dist/routes/respond-with-openapi-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"respond-with-openapi-document.d.ts","sourceRoot":"","sources":["../../src/routes/respond-with-openapi-document.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAEnC;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,CAAC,EAAE,OAAO,EACV,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACpC,MAAM,GAAE,MAAM,GAAG,MAAe;;;;;;;;;;;;;;;;iBAwCjC"}
+{"version":3,"file":"respond-with-openapi-document.d.ts","sourceRoot":"","sources":["../../src/routes/respond-with-openapi-document.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAGnC;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,CAAC,EAAE,OAAO,EACV,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACpC,MAAM,GAAE,MAAM,GAAG,MAAe;;;;;;iBAwCjC"}

package/dist/routes/respond-with-openapi-document.js

@@ -1,4 +1,5 @@
-import { normalize, toYaml } from '@scalar/openapi-parser';
+import { normalize } from '@scalar/json-magic/helpers/normalize';
+import { stringify as toYaml } from 'yaml';
 /**
  * OpenAPI endpoints
  */

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;AAExD,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,CA4C/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;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,CA4C/B"}

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

@@ -1,4 +1,6 @@
 import { faker } from '@faker-js/faker';
+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 { store } from '../libs/store.js';
@@ -11,7 +13,7 @@ function getExampleFromResponse(c, statusCode, responses) {
     if (!responses) {
         return null;
     }
-    const response = responses[statusCode] || responses.default;
+    const response = getResolvedRef(responses[statusCode] || responses.default);
     if (!response) {
         return null;
     }
@@ -36,7 +38,7 @@ function getExampleFromResponse(c, statusCode, responses) {
     return acceptedResponse.example !== undefined
         ? acceptedResponse.example
         : acceptedResponse.schema
-            ? getExampleFromSchema(acceptedResponse.schema, {
+            ? getExampleFromSchema(getResolvedRefDeep(acceptedResponse.schema), {
                 emptyString: 'string',
                 variables: c.req.param(),
                 mode: 'read',

package/dist/utils/get-open-auth-token-urls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-open-auth-token-urls.d.ts","sourceRoot":"","sources":["../../src/utils/get-open-auth-token-urls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAE5E;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAYlD;AAiBD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,EAAE,CAoCxE"}
+{"version":3,"file":"get-open-auth-token-urls.d.ts","sourceRoot":"","sources":["../../src/utils/get-open-auth-token-urls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAG5E;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAYlD;AAiBD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,EAAE,CAuCxE"}

package/dist/utils/get-open-auth-token-urls.js

@@ -1,3 +1,4 @@
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 /**
  * Extract path from URL
  */
@@ -33,8 +34,10 @@ export function getOpenAuthTokenUrls(schema) {
     // Use Set from the start for better memory efficiency
     const oauthUrls = new Set();
     // Iterate through all security schemes
-    for (const scheme of Object.values(securitySchemes)) {
-        if (!isOAuth2Scheme(scheme)) {
+    for (const rawScheme of Object.values(securitySchemes)) {
+        const scheme = getResolvedRef(rawScheme);
+        // Skip schemes that could not be resolved (e.g. a `$ref` to a missing component)
+        if (!scheme || !isOAuth2Scheme(scheme)) {
             continue;
         }
         const flows = scheme.flows; // Type assertion no longer needed

package/dist/utils/handle-authentication.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handle-authentication.d.ts","sourceRoot":"","sources":["../../src/utils/handle-authentication.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAGnC;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,IAC3F,GAAG,OAAO,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA6H/E"}
+{"version":3,"file":"handle-authentication.d.ts","sourceRoot":"","sources":["../../src/utils/handle-authentication.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAGnC;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,WAAW,CAAC,eAAe,IAC3F,GAAG,OAAO,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAwH/E"}

package/dist/utils/handle-authentication.js

@@ -1,3 +1,4 @@
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { getCookie } from 'hono/cookie';
 /**
  * Handles authentication for incoming requests based on the OpenAPI document.
@@ -11,11 +12,7 @@ export function handleAuthentication(schema, operation) {
             for (const securityRequirement of operationSecuritySchemes) {
                 let securitySchemeAuthenticated = true;
                 for (const [schemeName] of Object.entries(securityRequirement)) {
-                    const scheme = schema?.components?.securitySchemes?.[schemeName];
-                    // Skip if scheme is a reference object (should be dereferenced already, but check to be safe)
-                    if (scheme && '$ref' in scheme) {
-                        continue;
-                    }
+                    const scheme = getResolvedRef(schema?.components?.securitySchemes?.[schemeName]);
                     if (scheme && 'type' in scheme) {
                         const securityScheme = scheme;
                         switch (securityScheme.type) {

package/dist/utils/log-authentication-instructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log-authentication-instructions.d.ts","sourceRoot":"","sources":["../../src/utils/log-authentication-instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,oBAAoB,CAAC,QAmH9G"}
+{"version":3,"file":"log-authentication-instructions.d.ts","sourceRoot":"","sources":["../../src/utils/log-authentication-instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAKxD;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,oBAAoB,CAAC,QA0H9G"}

package/dist/utils/log-authentication-instructions.js

@@ -1,3 +1,4 @@
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { getPathFromUrl } from './get-open-auth-token-urls.js';
 /**
  * Log authentication instructions for different security schemes
@@ -8,7 +9,12 @@ export function logAuthenticationInstructions(securitySchemes) {
     }
     console.log('Authentication:');
     console.log();
-    Object.entries(securitySchemes).forEach(([_, scheme]) => {
+    Object.entries(securitySchemes).forEach(([_, rawScheme]) => {
+        const scheme = getResolvedRef(rawScheme);
+        // Skip schemes that could not be resolved (e.g. a `$ref` to a missing component)
+        if (!scheme) {
+            return;
+        }
         switch (scheme.type) {
             case 'apiKey':
                 if (scheme.in === 'header') {

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

@@ -1,10 +1,15 @@
 import type { OpenAPIV3_1 } from '@scalar/openapi-types';
 /**
  * Processes an OpenAPI document by bundling external references, upgrading to OpenAPI 3.1,
- * and dereferencing the document.
+ * and wrapping it so internal references stay intact but resolve lazily.
+ *
+ * Unlike a full dereference, the returned document keeps `$ref` nodes in place. Consumers
+ * resolve them on demand with `getResolvedRef` from `@scalar/workspace-store`, which reads the
+ * `$ref-value` exposed by the magic proxy. This avoids eagerly flattening (and duplicating)
+ * the whole document up front.
  *
  * @param document - The OpenAPI document to process. Can be a string (URL/path) or an object.
- * @returns A promise that resolves to the dereferenced OpenAPI 3.1 document.
+ * @returns A promise that resolves to the OpenAPI 3.1 document with lazily resolvable references.
  * @throws Error if the document cannot be processed or is invalid.
  */
 export declare function processOpenApiDocument(document: string | Record<string, any> | undefined): Promise<OpenAPIV3_1.Document>;

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

@@ -1 +1 @@
-{"version":3,"file":"process-openapi-document.d.ts","sourceRoot":"","sources":["../../src/utils/process-openapi-document.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GACjD,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAoE/B"}
+{"version":3,"file":"process-openapi-document.d.ts","sourceRoot":"","sources":["../../src/utils/process-openapi-document.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GACjD,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAiD/B"}

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

@@ -1,16 +1,18 @@
 import { bundle } from '@scalar/json-magic/bundle';
-import { parseJson } from '@scalar/json-magic/bundle/plugins/node';
-import { parseYaml } from '@scalar/json-magic/bundle/plugins/node';
-import { readFiles } from '@scalar/json-magic/bundle/plugins/node';
-import { fetchUrls } from '@scalar/json-magic/bundle/plugins/node';
-import { dereference } from '@scalar/openapi-parser';
+import { fetchUrls, parseJson, parseYaml, readFiles } from '@scalar/json-magic/bundle/plugins/node';
+import { createMagicProxy } from '@scalar/json-magic/magic-proxy';
 import { upgrade } from '@scalar/openapi-upgrader';
 /**
  * Processes an OpenAPI document by bundling external references, upgrading to OpenAPI 3.1,
- * and dereferencing the document.
+ * and wrapping it so internal references stay intact but resolve lazily.
+ *
+ * Unlike a full dereference, the returned document keeps `$ref` nodes in place. Consumers
+ * resolve them on demand with `getResolvedRef` from `@scalar/workspace-store`, which reads the
+ * `$ref-value` exposed by the magic proxy. This avoids eagerly flattening (and duplicating)
+ * the whole document up front.
  *
  * @param document - The OpenAPI document to process. Can be a string (URL/path) or an object.
- * @returns A promise that resolves to the dereferenced OpenAPI 3.1 document.
+ * @returns A promise that resolves to the OpenAPI 3.1 document with lazily resolvable references.
  * @throws Error if the document cannot be processed or is invalid.
  */
 export async function processOpenApiDocument(document) {
@@ -52,21 +54,7 @@ export async function processOpenApiDocument(document) {
     if (!upgraded) {
         throw new Error('Upgraded document is invalid: upgrade returned null or undefined');
     }
-    // Dereference the document
-    const dereferenceResult = dereference(upgraded);
-    // Check for dereference errors
-    if (dereferenceResult.errors && dereferenceResult.errors.length > 0) {
-        const errorMessages = dereferenceResult.errors.map((err) => err.message).join(', ');
-        throw new Error(`Failed to dereference OpenAPI document: ${errorMessages}`);
-    }
-    // Extract the schema from the dereference result
-    const schema = dereferenceResult.schema;
-    if (!schema) {
-        throw new Error('Dereference result does not contain a schema');
-    }
-    // Ensure the schema is a valid OpenAPI 3.1 document
-    if (typeof schema !== 'object') {
-        throw new Error('Dereferenced schema is invalid: expected an object');
-    }
-    return schema;
+    // Wrap the document in a magic proxy so internal references resolve lazily via `$ref-value`.
+    // External references were already pulled inline by `bundle` above, so only local `$ref`s remain.
+    return createMagicProxy(upgraded);
 }

package/dist/utils/set-up-authentication-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"set-up-authentication-routes.d.ts","sourceRoot":"","sources":["../../src/utils/set-up-authentication-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAC5E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAOhC;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,QA4F7E"}
+{"version":3,"file":"set-up-authentication-routes.d.ts","sourceRoot":"","sources":["../../src/utils/set-up-authentication-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,uBAAuB,CAAA;AAE5E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAOhC;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,QAmG7E"}

package/dist/utils/set-up-authentication-routes.js

@@ -1,3 +1,4 @@
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 import { respondWithAuthorizePage } from '../routes/respond-with-authorize-page.js';
 import { respondWithToken } from '../routes/respond-with-token.js';
 import { getOpenAuthTokenUrls, getPathFromUrl } from './get-open-auth-token-urls.js';
@@ -28,7 +29,12 @@ export function setUpAuthenticationRoutes(app, schema) {
     // Set up routes for different OAuth 2.0 flows
     const authorizeUrls = new Set();
     const tokenUrls = new Set();
-    Object.entries(securitySchemes).forEach(([_, scheme]) => {
+    Object.entries(securitySchemes).forEach(([_, rawScheme]) => {
+        const scheme = getResolvedRef(rawScheme);
+        // Skip schemes that could not be resolved (e.g. a `$ref` to a missing component)
+        if (!scheme) {
+            return;
+        }
         if (scheme.type === 'oauth2') {
             if (scheme.flows?.authorizationCode) {
                 const authorizeRoute = scheme.flows.authorizationCode.authorizationUrl ?? '/oauth/authorize';

package/package.json

@@ -16,7 +16,7 @@
     "swagger",
     "cli"
   ],
-  "version": "0.10.15",
+  "version": "0.10.17",
   "engines": {
     "node": ">=22"
   },
@@ -53,12 +53,12 @@
   "dependencies": {
     "@faker-js/faker": "10.4.0",
     "hono": "^4.12.7",
-    "@scalar/helpers": "0.8.0",
-    "@scalar/json-magic": "0.12.14",
-    "@scalar/openapi-parser": "0.28.5",
-    "@scalar/openapi-upgrader": "0.2.8",
-    "@scalar/openapi-types": "0.9.0",
-    "@scalar/workspace-store": "0.52.0"
+    "yaml": "^2.8.3",
+    "@scalar/helpers": "0.8.1",
+    "@scalar/json-magic": "0.12.15",
+    "@scalar/openapi-types": "0.9.1",
+    "@scalar/openapi-upgrader": "0.2.9",
+    "@scalar/workspace-store": "0.54.0"
   },
   "devDependencies": {
     "@types/node": "^24.1.0",