@scalar/workspace-store 0.57.0 → 0.58.1

package/dist/server.js

@@ -1,20 +1,81 @@
 import fs from 'node:fs/promises';
 import { cwd } from 'node:process';
+import { upgrade as upgradeAsyncApi } from '@scalar/asyncapi-upgrader';
 import { parseJsonPointerSegments } from '@scalar/helpers/json/parse-json-pointer-segments';
 import { getValueAtPath } from '@scalar/helpers/object/get-value-at-path';
+import { preventPollution } from '@scalar/helpers/object/prevent-pollution';
+import { extensions as bundleExtensions } from '@scalar/json-magic/bundle';
 import { fetchUrls, readFiles } from '@scalar/json-magic/bundle/plugins/node';
 import { escapeJsonPointer } from '@scalar/json-magic/helpers/escape-json-pointer';
+import { createMagicProxy, getRaw } from '@scalar/json-magic/magic-proxy';
 import { upgrade } from '@scalar/openapi-upgrader';
+import { asyncApiObjectSchema } from '@scalar/schemas/asyncapi/3.1';
+import { coerce } from '@scalar/validation';
+import { deepClone } from './helpers/deep-clone.js';
 import { forEachPathItemOperation, getResolvedPathItem } from './helpers/for-each-path-item-operation.js';
 import { keyOf } from './helpers/general.js';
 import { getResolvedRef } from './helpers/get-resolved-ref.js';
-import { createNavigation } from './navigation/index.js';
+import { mergeObjects } from './helpers/merge-object.js';
+import { createNavigation, traverseAsyncApiDocument } from './navigation/index.js';
 import { extensions } from './schemas/extensions.js';
+import { isAsyncApiDocument } from './schemas/type-guards.js';
 import { coerceValue } from './schemas/typebox-coerce.js';
 import { OpenAPIDocumentSchema, } from './schemas/v3.1/strict/openapi-document.js';
 const DEFAULT_ASSETS_FOLDER = 'assets';
 export const WORKSPACE_FILE_NAME = 'scalar-workspace.json';
 const httpMethods = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+/**
+ * Wraps a document so local `$ref`s resolve while the store inspects it.
+ *
+ * Navigation building and externalization both read through `getResolvedRef`, which needs the
+ * `$ref-value` the magic proxy supplies. Without it a `$ref`'d path item reads as a bare `{ $ref }`,
+ * so its operations reach neither the sidebar nor the generated chunks and disappear from the
+ * rendered document with no error. This is the same treatment the client store gives every document.
+ *
+ * Resolution is lazy and local, so this stays synchronous and never fetches. The proxy is only ever
+ * read through: everything the store keeps is unwrapped with `getRaw` first, because `$ref-value` is
+ * enumerable on a proxy and serializing one would inline every referenced value beside its `$ref`.
+ */
+const resolveLocalReferences = (document) => createMagicProxy(document);
+/**
+ * The keys `@scalar/json-magic` bundling parks external documents under.
+ *
+ * Sourced straight from the bundler's own `extensions` defaults so the two cannot drift: if bundling
+ * ever renames a bucket, this follows without a silent break.
+ *
+ * Both are needed. `x-ext` holds the bundled documents that rewritten references resolve against,
+ * and `x-ext-urls` maps each bucket key back to the URL it came from — `restoreOriginalRefs` reads it
+ * to turn the local pointers back into the references the author wrote.
+ *
+ * Note that both are served: they stay on the stored document and ship in the workspace payload,
+ * because the generated chunks keep their `#/x-ext/…` pointers and the client resolves those against
+ * the document root. Only the client's export path (`purgeInternalDocumentKeys`) strips them.
+ */
+const BUNDLED_EXTERNAL_KEYS = [bundleExtensions.externalDocuments, bundleExtensions.externalDocumentsMappings];
+/**
+ * Copies the buckets bundling parks external documents in onto the coerced document.
+ *
+ * Bundling does not inline an external reference — it moves the target under `x-ext` and rewrites the
+ * `$ref` to a local pointer into that bucket. The OpenAPI schema does not model those keys, so
+ * coercion drops them and leaves every rewritten reference dangling, which is how a split-file
+ * document loses the operations it keeps in its other files.
+ *
+ * Copied by reference, deliberately. `upgrade` hands back the very object it was given when the
+ * document is already 3.1, so the served workspace ends up sharing these buckets with the caller's
+ * document — but that is what the store already does with every other field coercion passes through
+ * untouched (`info` among them), so cloning only these two would buy consistency nowhere. It would
+ * also be the worst place to pay for it: `x-ext` holds every external document that was bundled in,
+ * so cloning it roughly doubles peak memory at ingest, and `deepClone` recurses per level and throws
+ * on input nested a few thousand deep. Cloning the caller's document as a whole is the fix, and it
+ * belongs with the aliasing the store already has rather than here.
+ */
+const preserveBundledExternals = (source, target) => {
+    for (const key of BUNDLED_EXTERNAL_KEYS) {
+        if (source[key] !== undefined) {
+            target[key] = source[key];
+        }
+    }
+};
 /**
  * Filters an OpenAPI PathsObject to only include standard HTTP methods.
  * Removes any vendor extensions or other non-HTTP properties.
@@ -44,7 +105,12 @@ export function filterHttpMethodsOnly(paths) {
         const filteredMethods = {};
         forEachPathItemOperation(pathItemRef, (method, operation) => {
             if (httpMethods.has(method.toLowerCase())) {
-                filteredMethods[method] = getResolvedRef(operation) ?? operation;
+                // Unwrapped because the caller hands us a resolved document. A magic proxy enumerates a
+                // virtual `$ref-value`, so storing one would inline every referenced component beside its
+                // `$ref` when the chunk is written — and a self-referential schema would never finish
+                // serializing. Unwrapping one level is enough: the proxy wraps lazily, so a raw target's
+                // children are already raw.
+                filteredMethods[method] = getRaw(getResolvedRef(operation) ?? operation);
             }
         });
         if (Object.keys(filteredMethods).length > 0) {
@@ -116,11 +182,14 @@ export function externalizePathReferences(document, meta) {
                     : `./chunks/${meta.name}/operations/${escapedPath}/${type}.json#`;
                 result[path][type] = { '$ref': ref, $global: true };
             }
-            else if (type !== '$ref') {
-                // Skip the path-item `$ref` merged in by getResolvedPathItem: the referenced component is
-                // externalized on its own and the operations are externalized above, so keeping it would
-                // emit a hybrid entry with both a component `$ref` and inlined operation references.
-                result[path][type] = pathItemRecord[type];
+            else if (type !== '$ref' && type !== '$ref-value') {
+                // Skip the reference plumbing merged in by getResolvedPathItem. The referenced path item is
+                // externalized on its own and its operations are externalized above, so keeping the `$ref`
+                // would emit a hybrid entry carrying both a component reference and inlined operation
+                // references. `$ref-value` is meant to be virtual and never belongs in a stored document.
+                //
+                // Unwrapped for the same reason as in filterHttpMethodsOnly: what is kept here is stored.
+                result[path][type] = getRaw(pathItemRecord[type]);
             }
         });
     });
@@ -184,6 +253,55 @@ export async function createServerWorkspaceStore(workspaceProps) {
      * for that document.
      */
     const assets = {};
+    /**
+     * Adds an AsyncAPI document to the workspace.
+     *
+     * AsyncAPI keeps its content under `channels` and `operations` instead of `paths`, so none of the
+     * OpenAPI externalization applies: there are no path operations to split into chunks, and the
+     * consumers read channels and operations straight off the stored document. The document is
+     * therefore kept whole, and only the AsyncAPI upgrader runs so 1.x/2.x documents reach the 3.x
+     * shape the traversal and renderer expect.
+     *
+     * @param document - The AsyncAPI document to process and add
+     * @param meta - The document name plus any metadata to merge onto the stored document
+     */
+    const addAsyncApiDocumentSync = (document, { name, documentMeta }, navigationOptions) => {
+        // Capture the original version before the upgrader bumps `asyncapi` to the latest.
+        const originalAasVersion = document.asyncapi;
+        // Clone first: the upgrader and the traversal both write to the document they are handed, and
+        // the caller may keep using the object it passed in.
+        // The upgrader is typed against the loose `UnknownObject` shape; the result is a valid 3.x
+        // AsyncAPI document, so cast it back.
+        const asyncApiDocument = upgradeAsyncApi(deepClone(document));
+        // Coerced against the AsyncAPI schema for the same reason the OpenAPI path coerces against its
+        // own: the traversal and every consumer downstream expect a normalized document. Skipping it
+        // leaves `info` missing on a partial document (which the traversal reads unguarded) and passes
+        // shapes like `channels: null` straight through to the browser. Merged rather than assigned, so
+        // nothing the schema does not model is dropped.
+        mergeObjects(asyncApiDocument, coerce(asyncApiObjectSchema, deepClone(asyncApiDocument)));
+        // Nothing is externalized, so the document owns no chunks. The empty entry keeps `get()` and
+        // chunk generation well defined for the document name.
+        assets[name] = {};
+        // Traversed before the spread below: its last act is a top-level `x-scalar-order` write on the
+        // document, and a snapshot taken first would both miss it and preserve whatever stale order the
+        // input arrived with.
+        const navigation = traverseAsyncApiDocument(name, 
+        // Resolved so the traversal can follow references the same way the client store does. A
+        // channel names its messages by `$ref` into `components.messages`, and an unresolved
+        // traversal falls back to the map key — so the sidebar reads `planetCreated` where the
+        // rendered page reads "Planet Created".
+        resolveLocalReferences(asyncApiDocument), navigationOptions ?? workspaceProps.navigationOptions);
+        workspace.documents[name] = {
+            ...documentMeta,
+            ...asyncApiDocument,
+            'x-original-aas-version': originalAasVersion,
+            [extensions.document.navigation]: navigation,
+        };
+        // A document carrying both discriminators is ingested as AsyncAPI here, but `getDocumentType`
+        // checks OpenAPI first — so leaving `openapi` in place would hand an OpenAPI renderer a
+        // navigation tree of channel entries. The document is stored as the type it was read as.
+        delete workspace.documents[name]['openapi'];
+    };
     /**
      * Adds a new document to the workspace.
      *
@@ -201,19 +319,37 @@ export async function createServerWorkspaceStore(workspaceProps) {
      */
     const addDocumentSync = (document, meta, navigationOptions) => {
         const { name, ...documentMeta } = meta;
-        const documentV3 = coerceValue(OpenAPIDocumentSchema, upgrade(document, '3.1'));
+        // The name is caller-supplied and used as a computed key on both `workspace.documents` and
+        // `assets`, so a name like `__proto__` would write straight onto Object.prototype. Rejected
+        // here rather than filtered, and `addDocument` turns the throw into a skipped document.
+        preventPollution(name, 'server workspace document name');
+        // AsyncAPI documents get their own ingestion path, mirroring the client store. The OpenAPI
+        // upgrade and coerce steps would strip `channels` and `operations`, inject an empty
+        // `openapi: ''` that breaks the type discriminator, and add an empty `paths` object.
+        if (isAsyncApiDocument(document)) {
+            addAsyncApiDocumentSync(document, { name, documentMeta }, navigationOptions);
+            return;
+        }
+        const upgradedDocument = upgrade(document, '3.1');
+        const documentV3 = coerceValue(OpenAPIDocumentSchema, upgradedDocument);
+        preserveBundledExternals(upgradedDocument, documentV3);
+        // Everything that inspects the document reads through this; everything that stores a piece of it
+        // stores the raw `documentV3` or a `getRaw` of the piece.
+        const resolvedDocument = resolveLocalReferences(documentV3);
         // add the assets
         assets[meta.name] = {
+            // Components need no resolution: they are externalized as authored, and the client resolves the
+            // references inside them the same way it resolves the ones this store leaves behind.
             components: documentV3.components,
-            operations: documentV3.paths && escapePaths(filterHttpMethodsOnly(documentV3.paths)),
+            operations: resolvedDocument.paths && escapePaths(filterHttpMethodsOnly(resolvedDocument.paths)),
         };
         const options = workspaceProps.mode === 'ssr'
             ? { mode: workspaceProps.mode, name, baseUrl: workspaceProps.baseUrl }
             : { mode: workspaceProps.mode, name, directory: workspaceProps.directory ?? DEFAULT_ASSETS_FOLDER };
         const components = externalizeComponentReferences(documentV3, options);
-        const paths = externalizePathReferences(documentV3, options);
+        const paths = externalizePathReferences(resolvedDocument, options);
         // Build the sidebar entries
-        const navigation = createNavigation(name, documentV3, navigationOptions ?? workspaceProps.navigationOptions);
+        const navigation = createNavigation(name, resolvedDocument, navigationOptions ?? workspaceProps.navigationOptions);
         // The document is now a minimal version with externalized references to components and operations.
         // These references will be resolved asynchronously when needed through the workspace's get() method.
         workspace.documents[meta.name] = {
@@ -235,12 +371,37 @@ export async function createServerWorkspaceStore(workspaceProps) {
      * @param input - The document input containing the document source and metadata
      */
     const addDocument = async (input, navigationOptions) => {
-        const document = await loadDocument(input);
-        if (!document.ok) {
-            console.warn(`Failed to load document "${input.name}`);
-            return;
+        // Captured so a failed add restores exactly what was there. The assets are written partway
+        // through, and several steps throw before that point, so clearing the key outright would strip
+        // a working document's chunks whenever a name is reused — leaving the workspace pointing at
+        // references that resolve to nothing.
+        //
+        // The snapshot is taken before the first await, so two adds racing under the same name would
+        // both capture the pre-state and the failing one could put back what the other just replaced.
+        // Adds are not serialized per name: concurrent adds sharing a name are already last-write-wins,
+        // and callers are expected to await one before starting another.
+        const assetsBeforeAdd = assets[input.name];
+        try {
+            const document = await loadDocument(input);
+            if (!document.ok) {
+                console.warn(`Failed to load document "${input.name}"`);
+                return;
+            }
+            addDocumentSync(document.data, { name: input.name, ...input.meta }, navigationOptions);
+        }
+        catch (error) {
+            // Honours the contract above: a document that cannot be processed is skipped rather than
+            // taking the workspace with it, since the initial documents are ingested together and one
+            // malformed description should not fail an entire documentation build. Loading is inside the
+            // try too, so a document that cannot even be serialized is skipped the same way.
+            if (assetsBeforeAdd === undefined) {
+                delete assets[input.name];
+            }
+            else {
+                assets[input.name] = assetsBeforeAdd;
+            }
+            console.warn(`Failed to process document "${input.name}"`, error);
         }
-        addDocumentSync(document.data, { name: input.name, ...input.meta }, navigationOptions);
     };
     // Load and process all initial documents in parallel
     await Promise.all(workspaceProps.documents.map((document) => addDocument(document)));

package/package.json

@@ -16,7 +16,7 @@
     "openapi",
     "scalar"
   ],
-  "version": "0.57.0",
+  "version": "0.58.1",
   "engines": {
     "node": ">=22"
   },
@@ -144,23 +144,23 @@
   ],
   "dependencies": {
     "@scalar/typebox": "0.1.3",
-    "js-base64": "^3.7.8",
-    "type-fest": "^5.3.1",
+    "js-base64": "^3.9.2",
+    "type-fest": "^5.8.0",
     "vue": "^3.5.40",
     "yaml": "^2.9.0",
-    "@scalar/asyncapi-upgrader": "0.1.5",
-    "@scalar/json-magic": "0.12.20",
-    "@scalar/openapi-upgrader": "0.2.13",
-    "@scalar/helpers": "0.10.0",
-    "@scalar/schemas": "0.8.1",
-    "@scalar/snippetz": "0.9.26",
-    "@scalar/types": "0.18.0",
-    "@scalar/validation": "0.6.2"
+    "@scalar/asyncapi-upgrader": "0.1.7",
+    "@scalar/helpers": "0.11.1",
+    "@scalar/json-magic": "0.13.2",
+    "@scalar/openapi-upgrader": "0.2.15",
+    "@scalar/schemas": "0.8.3",
+    "@scalar/snippetz": "0.9.28",
+    "@scalar/types": "0.18.2",
+    "@scalar/validation": "0.6.3"
   },
   "devDependencies": {
-    "@google-cloud/storage": "7.16.0",
-    "fake-indexeddb": "6.2.3",
-    "fastify": "^5.8.1",
+    "@google-cloud/storage": "7.21.0",
+    "fake-indexeddb": "6.2.5",
+    "fastify": "^5.11.2",
     "vite": "8.1.5",
     "vitest": "4.1.10"
   },