@scalar/workspace-store 0.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1,10 @@
+
+> @scalar/workspace-store@0.1.0 build /home/runner/work/scalar/scalar/packages/workspace-store
+> scalar-build-esbuild
+
+Updating package.json exports field…
+@scalar/workspace-store: Build completed in 41.47ms
+
+> @scalar/workspace-store@0.1.0 types:build /home/runner/work/scalar/scalar/packages/workspace-store
+> scalar-types-build
+

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @scalar/workspace-store
+
+## 0.1.0
+
+### Minor Changes
+
+- f7474ed: feat(workspace-store): openapi server side store
+
+### Patch Changes
+
+- Updated dependencies [1e87feb]
+  - @scalar/openapi-parser@0.13.0
+  - @scalar/openapi-types@0.3.1

package/README.md

@@ -0,0 +1,199 @@
+# @scalar/workspace-store
+
+A powerful data store for managing OpenAPI documents. This package provides a flexible solution for handling multiple OpenAPI documents in a workspace environment
+
+## Server-Side workspace store
+
+Server side data store which enables document chunking to reduce initial loading time specially when working with large openapi documents
+
+#### Usage
+Create a new store in SSR mode
+
+```ts
+// Create the store
+const store = createServerWorkspaceStore({
+  baseUrl: 'example.com',
+  mode: 'ssr',
+  meta: { 'x-scalar-active-document': 'document-name' },
+  documents: [
+    {
+      name: 'document-name',
+      meta: {},
+      document: {
+        openapi: '3.1.1',
+        info: {
+          title: 'Hello World',
+          version: '1.0.0',
+        },
+        components: {
+          schemas: {
+            Person: {
+              type: 'object',
+              properties: {
+                name: { type: 'string' },
+              },
+            },
+            User: {
+              $ref: '#/components/schemas/Person',
+            },
+          },
+        },
+      },
+    },
+  ],
+})
+
+// Add a new document to the store
+store.addDocument({
+  openapi: '3.1.1',
+  info: {
+    title: 'Hello World',
+    version: '1.0.0',
+  },
+  components: {
+    schemas: {
+      Person: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+        },
+      },
+      User: {
+        $ref: '#/components/schemas/Person',
+      },
+    },
+  },
+}, {
+  name: 'document-2',
+  "x-scalar-active-server": "server1"
+})
+
+// Get the workspace
+// Workspace is going to keep all the sparse documents
+const workspace = store.getWorkspace()
+
+// Get chucks using json pointers
+const chunk = store.get('#/document-name/components/schemas/Person')
+
+```
+
+
+Create a new store in static mode
+
+```ts
+// Create the store
+const store = createServerWorkspaceStore({
+  directory: 'assets',
+  mode: 'static',
+  meta: { 'x-scalar-active-document': 'document-name' },
+  documents: [
+    {
+      name: 'document-name',
+      meta: {},
+      document: {
+        openapi: '3.1.1',
+        info: {
+          title: 'Hello World',
+          version: '1.0.0',
+        },
+        components: {
+          schemas: {
+            Person: {
+              type: 'object',
+              properties: {
+                name: { type: 'string' },
+              },
+            },
+            User: {
+              $ref: '#/components/schemas/Person',
+            },
+          },
+        },
+      },
+    },
+  ],
+})
+
+// Add a new document to the store
+store.addDocument({
+  openapi: '3.1.1',
+  info: {
+    title: 'Hello World',
+    version: '1.0.0',
+  },
+  components: {
+    schemas: {
+      Person: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+        },
+      },
+      User: {
+        $ref: '#/components/schemas/Person',
+      },
+    },
+  },
+}, {
+  name: 'document-2',
+  "x-scalar-active-server": "server1"
+})
+
+// Generate the workspace file system
+// This will write in the filesystem the workspace and all the chucks
+// which can be resolved by the consumer
+const workspace = await store.generateWorkspaceChunks()
+```
+
+## Client-Side Workspace Store
+
+A reactive workspace store for managing OpenAPI documents with automatic reference resolution and chunked loading capabilities. Works seamlessly with server-side stores to handle large documents efficiently.
+
+#### Usage
+
+```ts
+
+// Initialize a new workspace store with default document
+const store = await createWorkspaceStore({
+  documents: [
+    {
+      name: 'default',
+      document: {
+        info: {
+          title: 'OpenApi document',
+          version: '1.0.0',
+        },
+      },
+    },
+  ],
+  meta: {
+    'x-scalar-active-document': 'default',
+  },
+})
+
+// Add another OpenAPI document to the workspace
+store.addDocument({
+  document: {
+    info: {
+      title: 'OpenApi document',
+      version: '1.0.0',
+    },
+  },
+  name: 'document',
+})
+
+// Get the currently active document
+store.workspace.activeDocument
+
+// Retrieve a specific document by name
+store.workspace.documents['document']
+
+// Update global workspace settings
+store.update('x-scalar-dark-mode', true)
+
+// Update settings for the active document
+store.updateDocument('active', "x-scalar-active-auth", '<value>')
+
+// Resolve and load document chunks including any $ref references
+await store.resolve(['paths', '/users', 'get'])
+```

package/dist/create-server-workspace-store.d.ts

@@ -0,0 +1,151 @@
+import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { WorkspaceDocumentMeta, WorkspaceMeta } from './schemas/server-workspace.js';
+export declare const WORKSPACE_FILE_NAME = "scalar-workspace.json";
+type CreateServerWorkspaceStore = {
+    directory?: string;
+    mode: 'static';
+    documents: {
+        name: string;
+        document: Record<string, unknown> | string;
+        meta?: WorkspaceDocumentMeta;
+    }[];
+    meta?: WorkspaceMeta;
+} | {
+    baseUrl: string;
+    mode: 'ssr';
+    documents: {
+        name: string;
+        document: Record<string, unknown> | string;
+        meta?: WorkspaceDocumentMeta;
+    }[];
+    meta?: WorkspaceMeta;
+};
+/**
+ * Filters an OpenAPI PathsObject to only include standard HTTP methods.
+ * Removes any vendor extensions or other non-HTTP properties.
+ *
+ * @param paths - The OpenAPI PathsObject to filter
+ * @returns A new PathsObject containing only standard HTTP methods
+ *
+ * @example
+ * Input: {
+ *   "/users": {
+ *     "get": {...},
+ *     "x-custom": {...},
+ *     "post": {...}
+ *   }
+ * }
+ * Output: {
+ *   "/users": {
+ *     "get": {...},
+ *     "post": {...}
+ *   }
+ * }
+ */
+export declare function filterHttpMethodsOnly(paths: OpenAPIV3_1.PathsObject): OpenAPIV3_1.PathsObject<{}, {}>;
+/**
+ * Escapes path keys in an OpenAPI PathsObject to be JSON Pointer compatible.
+ * This is necessary because OpenAPI paths can contain characters that need to be escaped
+ * when used as JSON Pointer references (like '/' and '~').
+ *
+ * @example
+ * Input: { "/users/{id}": { ... } }
+ * Output: { "/users~1{id}": { ... } }
+ */
+export declare function escapePaths(paths: OpenAPIV3_1.PathsObject): OpenAPIV3_1.PathsObject<{}, {}>;
+/**
+ * Externalizes components by turning them into refs.
+ */
+export declare function externalizeComponentReferences(document: OpenAPIV3_1.Document, meta: {
+    mode: 'ssr';
+    name: string;
+    baseUrl: string;
+} | {
+    mode: 'static';
+    name: string;
+    directory: string;
+}): Record<string, any>;
+/**
+ * Externalizes paths operations by turning them into refs.
+ */
+export declare function externalizePathReferences(document: OpenAPIV3_1.Document, meta: {
+    mode: 'ssr';
+    name: string;
+    baseUrl: string;
+} | {
+    mode: 'static';
+    name: string;
+    directory: string;
+}): Record<string, any>;
+/**
+ * Create server state workspace store
+ */
+export declare function createServerWorkspaceStore(workspaceProps: CreateServerWorkspaceStore): {
+    /**
+     * Generates workspace chunks by writing components and operations to the filesystem.
+     *
+     * This method is only available in static mode. It creates a directory structure containing:
+     * - A workspace file with metadata and document references
+     * - Component chunks split by type (schemas, parameters, etc)
+     * - Operation chunks split by path and HTTP method
+     *
+     * The generated workspace references will be relative file paths pointing to these chunks.
+     *
+     * @throws {Error} If called when mode is not 'static'
+     */
+    generateWorkspaceChunks: () => Promise<void>;
+    /**
+     * Returns the workspace document containing metadata and all sparse documents.
+     *
+     * The workspace document includes:
+     * - Global workspace metadata (theme, active document, etc)
+     * - Document metadata and sparse document
+     * - In SSR mode: References point to in-memory chunks
+     * - In static mode: References point to filesystem chunks
+     *
+     * @returns The complete workspace document
+     */
+    getWorkspace: () => {
+        documents: Record<string, Record<string, unknown>>;
+        'x-scalar-dark-mode'?: boolean | undefined;
+        'x-scalar-default-client'?: string | undefined;
+        'x-scalar-active-document'?: string | undefined;
+        'x-scalar-theme'?: string | undefined;
+    };
+    /**
+     * Retrieves a chunk of data from the workspace using a JSON Pointer
+     *
+     * A JSON Pointer is a string that references a specific location in a JSON document.
+     * Only components and operations chunks can be retrieved.
+     *
+     * @example
+     * ```ts
+     * // Get a component
+     * get('#/document-name/components/schemas/User')
+     *
+     * // Get an operation
+     * get('#/document-name/operations/pets/get')
+     * ```
+     *
+     * @param pointer - The JSON Pointer string to locate the chunk
+     * @returns The chunk data if found, undefined otherwise
+     */
+    get: (pointer: string) => unknown;
+    /**
+     * Adds a new document to the workspace.
+     *
+     * The document will be:
+     * - Upgraded to OpenAPI 3.1 if needed
+     * - Split into components and operations chunks
+     * - Have its references externalized based on the workspace mode
+     * - Added to the workspace with its metadata
+     *
+     * @param document - The OpenAPI document to add
+     * @param meta - Document metadata including required name and optional settings
+     */
+    addDocument: (document: Record<string, unknown>, meta: {
+        name: string;
+    } & WorkspaceDocumentMeta) => void;
+};
+export {};
+//# sourceMappingURL=create-server-workspace-store.d.ts.map

package/dist/create-server-workspace-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-server-workspace-store.d.ts","sourceRoot":"","sources":["../src/create-server-workspace-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAIxD,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAGtF,eAAO,MAAM,mBAAmB,0BAA0B,CAAA;AAE1D,KAAK,0BAA0B,GAC3B;IACE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,QAAQ,CAAA;IACd,SAAS,EAAE;QACT,IAAI,EAAE,MAAM,CAAA;QACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAA;QAC1C,IAAI,CAAC,EAAE,qBAAqB,CAAA;KAC7B,EAAE,CAAA;IACH,IAAI,CAAC,EAAE,aAAa,CAAA;CACrB,GACD;IACE,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,KAAK,CAAA;IACX,SAAS,EAAE;QACT,IAAI,EAAE,MAAM,CAAA;QACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAA;QAC1C,IAAI,CAAC,EAAE,qBAAqB,CAAA;KAC7B,EAAE,CAAA;IACH,IAAI,CAAC,EAAE,aAAa,CAAA;CACrB,CAAA;AAIL;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,CAAC,WAAW,mCAsBnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC,WAAW,mCAOzD;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,WAAW,CAAC,QAAQ,EAC9B,IAAI,EAAE;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,uBAqB3G;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,WAAW,CAAC,QAAQ,EAC9B,IAAI,EAAE;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,uBA8B3G;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,cAAc,EAAE,0BAA0B;IAkDjF;;;;;;;;;;;OAWG;;IAwCH;;;;;;;;;;OAUG;;;;;;;;IAIH;;;;;;;;;;;;;;;;;OAiBG;mBACY,MAAM;IAGrB;;;;;;;;;;;OAWG;4BACqB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,qBAAqB;EAwBlG"}

package/dist/create-server-workspace-store.js

@@ -0,0 +1,199 @@
+import { escapeJsonPointer, upgrade } from "@scalar/openapi-parser";
+import { getValueByPath, parseJsonPointer } from "./helpers/json-path-utils.js";
+import fs from "node:fs/promises";
+import { cwd } from "node:process";
+const DEFAULT_ASSETS_FOLDER = "assets";
+const WORKSPACE_FILE_NAME = "scalar-workspace.json";
+const httpMethods = /* @__PURE__ */ new Set(["get", "put", "post", "delete", "options", "head", "patch", "trace"]);
+function filterHttpMethodsOnly(paths) {
+  const result = {};
+  for (const [path, methods] of Object.entries(paths)) {
+    if (!methods) {
+      continue;
+    }
+    const filteredMethods = {};
+    for (const [method, operation] of Object.entries(methods)) {
+      if (httpMethods.has(method.toLowerCase())) {
+        filteredMethods[method] = operation;
+      }
+    }
+    if (Object.keys(filteredMethods).length > 0) {
+      result[path] = filteredMethods;
+    }
+  }
+  return result;
+}
+function escapePaths(paths) {
+  const result = {};
+  Object.keys(paths).forEach((path) => {
+    result[escapeJsonPointer(path)] = paths[path];
+  });
+  return result;
+}
+function externalizeComponentReferences(document, meta) {
+  const result = {};
+  if (!document.components) {
+    return result;
+  }
+  Object.entries(document.components).forEach(([type, component]) => {
+    result[type] = {};
+    Object.keys(component).forEach((name) => {
+      const ref = meta.mode === "ssr" ? `${meta.baseUrl}/${meta.name}/components/${type}/${name}#` : `${meta.directory}/chunks/${meta.name}/components/${type}/${name}.json#`;
+      result[type][name] = { "$ref": ref };
+    });
+  });
+  return result;
+}
+function externalizePathReferences(document, meta) {
+  const result = {};
+  if (!document.paths) {
+    return result;
+  }
+  Object.entries(document.paths).forEach(([path, pathItem]) => {
+    if (!pathItem) {
+      return result;
+    }
+    result[path] = {};
+    const escapedPath = escapeJsonPointer(path);
+    Object.keys(pathItem).forEach((type) => {
+      if (httpMethods.has(type)) {
+        const ref = meta.mode === "ssr" ? `${meta.baseUrl}/${meta.name}/operations/${escapedPath}/${type}#` : `${meta.directory}/chunks/${meta.name}/operations/${escapedPath}/${type}.json#`;
+        result[path][type] = { "$ref": ref };
+      }
+    });
+  });
+  return result;
+}
+function createServerWorkspaceStore(workspaceProps) {
+  const documents = workspaceProps.documents.map((el) => {
+    const document = upgrade(el.document).specification;
+    return { ...el, document };
+  });
+  const assets = documents.reduce((acc, { name, document }) => {
+    acc[name] = {
+      components: document.components,
+      operations: document.paths && escapePaths(filterHttpMethodsOnly(document.paths))
+    };
+    return acc;
+  }, {});
+  const workspace = {
+    ...workspaceProps.meta,
+    documents: documents.reduce((acc, { name, document, meta }) => {
+      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(document, options);
+      const paths = externalizePathReferences(document, options);
+      acc[name] = { ...meta, ...document, components, paths };
+      return acc;
+    }, {})
+  };
+  return {
+    /**
+     * Generates workspace chunks by writing components and operations to the filesystem.
+     *
+     * This method is only available in static mode. It creates a directory structure containing:
+     * - A workspace file with metadata and document references
+     * - Component chunks split by type (schemas, parameters, etc)
+     * - Operation chunks split by path and HTTP method
+     *
+     * The generated workspace references will be relative file paths pointing to these chunks.
+     *
+     * @throws {Error} If called when mode is not 'static'
+     */
+    generateWorkspaceChunks: async () => {
+      if (workspaceProps.mode !== "static") {
+        throw "Mode has to be set to `static` to generate filesystem workspace chunks";
+      }
+      const basePath = `${cwd()}/${workspaceProps.directory ?? DEFAULT_ASSETS_FOLDER}`;
+      await fs.mkdir(basePath, { recursive: true });
+      await fs.writeFile(`${basePath}/${WORKSPACE_FILE_NAME}`, JSON.stringify(workspace));
+      for (const [name, { components, operations }] of Object.entries(assets)) {
+        if (components) {
+          for (const [type, component] of Object.entries(components)) {
+            const componentPath = `${basePath}/chunks/${name}/components/${type}`;
+            await fs.mkdir(componentPath, { recursive: true });
+            for (const [key, value] of Object.entries(component)) {
+              await fs.writeFile(`${componentPath}/${key}.json`, JSON.stringify(value));
+            }
+          }
+        }
+        if (operations) {
+          for (const [path, methods] of Object.entries(operations)) {
+            const operationPath = `${basePath}/chunks/${name}/operations/${path}`;
+            await fs.mkdir(operationPath, { recursive: true });
+            for (const [method, operation] of Object.entries(methods)) {
+              await fs.writeFile(`${operationPath}/${method}.json`, JSON.stringify(operation));
+            }
+          }
+        }
+      }
+    },
+    /**
+     * Returns the workspace document containing metadata and all sparse documents.
+     *
+     * The workspace document includes:
+     * - Global workspace metadata (theme, active document, etc)
+     * - Document metadata and sparse document
+     * - In SSR mode: References point to in-memory chunks
+     * - In static mode: References point to filesystem chunks
+     *
+     * @returns The complete workspace document
+     */
+    getWorkspace: () => {
+      return workspace;
+    },
+    /**
+     * Retrieves a chunk of data from the workspace using a JSON Pointer
+     *
+     * A JSON Pointer is a string that references a specific location in a JSON document.
+     * Only components and operations chunks can be retrieved.
+     *
+     * @example
+     * ```ts
+     * // Get a component
+     * get('#/document-name/components/schemas/User')
+     *
+     * // Get an operation
+     * get('#/document-name/operations/pets/get')
+     * ```
+     *
+     * @param pointer - The JSON Pointer string to locate the chunk
+     * @returns The chunk data if found, undefined otherwise
+     */
+    get: (pointer) => {
+      return getValueByPath(assets, parseJsonPointer(pointer));
+    },
+    /**
+     * Adds a new document to the workspace.
+     *
+     * The document will be:
+     * - Upgraded to OpenAPI 3.1 if needed
+     * - Split into components and operations chunks
+     * - Have its references externalized based on the workspace mode
+     * - Added to the workspace with its metadata
+     *
+     * @param document - The OpenAPI document to add
+     * @param meta - Document metadata including required name and optional settings
+     */
+    addDocument: (document, meta) => {
+      const { name, ...documentMeta } = meta;
+      const documentV3 = upgrade(document).specification;
+      assets[meta.name] = {
+        components: documentV3.schema?.components,
+        operations: documentV3.schema?.paths && escapePaths(filterHttpMethodsOnly(documentV3.schema.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);
+      workspace.documents[meta.name] = { ...documentMeta, ...documentV3, components, paths };
+    }
+  };
+}
+export {
+  WORKSPACE_FILE_NAME,
+  createServerWorkspaceStore,
+  escapePaths,
+  externalizeComponentReferences,
+  externalizePathReferences,
+  filterHttpMethodsOnly
+};
+//# sourceMappingURL=create-server-workspace-store.js.map

package/dist/create-server-workspace-store.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/create-server-workspace-store.ts"],
+  "sourcesContent": ["import { escapeJsonPointer, upgrade } from '@scalar/openapi-parser'\nimport type { OpenAPIV3_1 } from '@scalar/openapi-types'\nimport { getValueByPath, parseJsonPointer } from './helpers/json-path-utils'\nimport fs from 'node:fs/promises'\nimport { cwd } from 'node:process'\nimport type { WorkspaceDocumentMeta, WorkspaceMeta } from './schemas/server-workspace'\n\nconst DEFAULT_ASSETS_FOLDER = 'assets'\nexport const WORKSPACE_FILE_NAME = 'scalar-workspace.json'\n\ntype CreateServerWorkspaceStore =\n  | {\n      directory?: string\n      mode: 'static'\n      documents: {\n        name: string\n        document: Record<string, unknown> | string\n        meta?: WorkspaceDocumentMeta\n      }[]\n      meta?: WorkspaceMeta\n    }\n  | {\n      baseUrl: string\n      mode: 'ssr'\n      documents: {\n        name: string\n        document: Record<string, unknown> | string\n        meta?: WorkspaceDocumentMeta\n      }[]\n      meta?: WorkspaceMeta\n    }\n\nconst httpMethods = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'])\n\n/**\n * Filters an OpenAPI PathsObject to only include standard HTTP methods.\n * Removes any vendor extensions or other non-HTTP properties.\n *\n * @param paths - The OpenAPI PathsObject to filter\n * @returns A new PathsObject containing only standard HTTP methods\n *\n * @example\n * Input: {\n *   \"/users\": {\n *     \"get\": {...},\n *     \"x-custom\": {...},\n *     \"post\": {...}\n *   }\n * }\n * Output: {\n *   \"/users\": {\n *     \"get\": {...},\n *     \"post\": {...}\n *   }\n * }\n */\nexport function filterHttpMethodsOnly(paths: OpenAPIV3_1.PathsObject) {\n  const result: OpenAPIV3_1.PathsObject = {}\n\n  for (const [path, methods] of Object.entries(paths)) {\n    if (!methods) {\n      continue\n    }\n\n    const filteredMethods: Record<string, any> = {}\n\n    for (const [method, operation] of Object.entries(methods)) {\n      if (httpMethods.has(method.toLowerCase())) {\n        filteredMethods[method] = operation\n      }\n    }\n\n    if (Object.keys(filteredMethods).length > 0) {\n      result[path] = filteredMethods\n    }\n  }\n\n  return result\n}\n\n/**\n * Escapes path keys in an OpenAPI PathsObject to be JSON Pointer compatible.\n * This is necessary because OpenAPI paths can contain characters that need to be escaped\n * when used as JSON Pointer references (like '/' and '~').\n *\n * @example\n * Input: { \"/users/{id}\": { ... } }\n * Output: { \"/users~1{id}\": { ... } }\n */\nexport function escapePaths(paths: OpenAPIV3_1.PathsObject) {\n  const result: OpenAPIV3_1.PathsObject = {}\n  Object.keys(paths).forEach((path) => {\n    result[escapeJsonPointer(path)] = paths[path]\n  })\n\n  return result\n}\n\n/**\n * Externalizes components by turning them into refs.\n */\nexport function externalizeComponentReferences(\n  document: OpenAPIV3_1.Document,\n  meta: { mode: 'ssr'; name: string; baseUrl: string } | { mode: 'static'; name: string; directory: string },\n) {\n  const result: Record<string, any> = {}\n\n  if (!document.components) {\n    return result\n  }\n\n  Object.entries(document.components).forEach(([type, component]) => {\n    result[type] = {}\n    Object.keys(component).forEach((name) => {\n      const ref =\n        meta.mode === 'ssr'\n          ? `${meta.baseUrl}/${meta.name}/components/${type}/${name}#`\n          : `${meta.directory}/chunks/${meta.name}/components/${type}/${name}.json#`\n\n      result[type][name] = { '$ref': ref }\n    })\n  })\n\n  return result\n}\n\n/**\n * Externalizes paths operations by turning them into refs.\n */\nexport function externalizePathReferences(\n  document: OpenAPIV3_1.Document,\n  meta: { mode: 'ssr'; name: string; baseUrl: string } | { mode: 'static'; name: string; directory: string },\n) {\n  const result: Record<string, any> = {}\n\n  if (!document.paths) {\n    return result\n  }\n\n  Object.entries(document.paths).forEach(([path, pathItem]) => {\n    if (!pathItem) {\n      return result\n    }\n\n    result[path] = {}\n\n    const escapedPath = escapeJsonPointer(path)\n\n    Object.keys(pathItem).forEach((type) => {\n      if (httpMethods.has(type)) {\n        const ref =\n          meta.mode === 'ssr'\n            ? `${meta.baseUrl}/${meta.name}/operations/${escapedPath}/${type}#`\n            : `${meta.directory}/chunks/${meta.name}/operations/${escapedPath}/${type}.json#`\n\n        result[path][type] = { '$ref': ref }\n      }\n    })\n  })\n\n  return result\n}\n\n/**\n * Create server state workspace store\n */\nexport function createServerWorkspaceStore(workspaceProps: CreateServerWorkspaceStore) {\n  const documents = workspaceProps.documents.map((el) => {\n    const document = upgrade(el.document).specification\n\n    return { ...el, document }\n  })\n\n  /**\n   * A map of document chunks that can be loaded asynchronously by the client.\n   * Each document is split into components and operations to enable lazy loading.\n   * The keys are document names and values contain the components and operations\n   * for that document.\n   */\n  const assets = documents.reduce<\n    Record<string, { components?: OpenAPIV3_1.ComponentsObject; operations?: Record<string, unknown> }>\n  >((acc, { name, document }) => {\n    acc[name] = {\n      components: document.components,\n      operations: document.paths && escapePaths(filterHttpMethodsOnly(document.paths)),\n    }\n    return acc\n  }, {})\n\n  /**\n   * Base workspace document containing essential metadata and document references.\n   *\n   * This workspace document provides the minimal information needed for initial rendering.\n   * All components and path operations are replaced with references to enable lazy loading.\n   *\n   * In SSR mode, references point to API endpoints.\n   * In static mode, references point to filesystem chunks.\n   */\n  const workspace = {\n    ...workspaceProps.meta,\n    documents: documents.reduce<Record<string, Record<string, unknown>>>((acc, { name, document, meta }) => {\n      const options =\n        workspaceProps.mode === 'ssr'\n          ? { mode: workspaceProps.mode, name, baseUrl: workspaceProps.baseUrl }\n          : { mode: workspaceProps.mode, name, directory: workspaceProps.directory ?? DEFAULT_ASSETS_FOLDER }\n\n      // Transform the original document by setting all the components and paths operations on refs\n      const components = externalizeComponentReferences(document, options)\n      const paths = externalizePathReferences(document, options)\n\n      acc[name] = { ...meta, ...document, components, paths }\n      return acc\n    }, {}),\n  }\n\n  return {\n    /**\n     * Generates workspace chunks by writing components and operations to the filesystem.\n     *\n     * This method is only available in static mode. It creates a directory structure containing:\n     * - A workspace file with metadata and document references\n     * - Component chunks split by type (schemas, parameters, etc)\n     * - Operation chunks split by path and HTTP method\n     *\n     * The generated workspace references will be relative file paths pointing to these chunks.\n     *\n     * @throws {Error} If called when mode is not 'static'\n     */\n    generateWorkspaceChunks: async () => {\n      if (workspaceProps.mode !== 'static') {\n        throw 'Mode has to be set to `static` to generate filesystem workspace chunks'\n      }\n\n      // Write the workspace document\n      const basePath = `${cwd()}/${workspaceProps.directory ?? DEFAULT_ASSETS_FOLDER}`\n      await fs.mkdir(basePath, { recursive: true })\n\n      // Write the workspace contents on the file system\n      await fs.writeFile(`${basePath}/${WORKSPACE_FILE_NAME}`, JSON.stringify(workspace))\n\n      // Write the chunks\n      for (const [name, { components, operations }] of Object.entries(assets)) {\n        // Write the components chunks\n        if (components) {\n          for (const [type, component] of Object.entries(components as Record<string, Record<string, unknown>>)) {\n            const componentPath = `${basePath}/chunks/${name}/components/${type}`\n            await fs.mkdir(componentPath, { recursive: true })\n\n            for (const [key, value] of Object.entries(component)) {\n              await fs.writeFile(`${componentPath}/${key}.json`, JSON.stringify(value))\n            }\n          }\n        }\n\n        // Write the operations chunks\n        if (operations) {\n          for (const [path, methods] of Object.entries(operations as Record<string, Record<string, unknown>>)) {\n            const operationPath = `${basePath}/chunks/${name}/operations/${path}`\n            await fs.mkdir(operationPath, { recursive: true })\n\n            for (const [method, operation] of Object.entries(methods)) {\n              await fs.writeFile(`${operationPath}/${method}.json`, JSON.stringify(operation))\n            }\n          }\n        }\n      }\n    },\n    /**\n     * Returns the workspace document containing metadata and all sparse documents.\n     *\n     * The workspace document includes:\n     * - Global workspace metadata (theme, active document, etc)\n     * - Document metadata and sparse document\n     * - In SSR mode: References point to in-memory chunks\n     * - In static mode: References point to filesystem chunks\n     *\n     * @returns The complete workspace document\n     */\n    getWorkspace: () => {\n      return workspace\n    },\n    /**\n     * Retrieves a chunk of data from the workspace using a JSON Pointer\n     *\n     * A JSON Pointer is a string that references a specific location in a JSON document.\n     * Only components and operations chunks can be retrieved.\n     *\n     * @example\n     * ```ts\n     * // Get a component\n     * get('#/document-name/components/schemas/User')\n     *\n     * // Get an operation\n     * get('#/document-name/operations/pets/get')\n     * ```\n     *\n     * @param pointer - The JSON Pointer string to locate the chunk\n     * @returns The chunk data if found, undefined otherwise\n     */\n    get: (pointer: string) => {\n      return getValueByPath(assets, parseJsonPointer(pointer))\n    },\n    /**\n     * Adds a new document to the workspace.\n     *\n     * The document will be:\n     * - Upgraded to OpenAPI 3.1 if needed\n     * - Split into components and operations chunks\n     * - Have its references externalized based on the workspace mode\n     * - Added to the workspace with its metadata\n     *\n     * @param document - The OpenAPI document to add\n     * @param meta - Document metadata including required name and optional settings\n     */\n    addDocument: (document: Record<string, unknown>, meta: { name: string } & WorkspaceDocumentMeta) => {\n      const { name, ...documentMeta } = meta\n\n      const documentV3 = upgrade(document).specification\n\n      // add the assets\n      assets[meta.name] = {\n        components: documentV3.schema?.components,\n        operations: documentV3.schema?.paths && escapePaths(filterHttpMethodsOnly(documentV3.schema.paths as any)),\n      }\n\n      const options =\n        workspaceProps.mode === 'ssr'\n          ? { mode: workspaceProps.mode, name, baseUrl: workspaceProps.baseUrl }\n          : { mode: workspaceProps.mode, name, directory: workspaceProps.directory ?? DEFAULT_ASSETS_FOLDER }\n\n      const components = externalizeComponentReferences(documentV3, options)\n      const paths = externalizePathReferences(documentV3, options)\n\n      // The document is now a minimal version with externalized references to components and operations.\n      // These references will be resolved asynchronously when needed through the workspace's get() method.\n      workspace.documents[meta.name] = { ...documentMeta, ...documentV3, components, paths }\n    },\n  }\n}\n"],
+  "mappings": "AAAA,SAAS,mBAAmB,eAAe;AAE3C,SAAS,gBAAgB,wBAAwB;AACjD,OAAO,QAAQ;AACf,SAAS,WAAW;AAGpB,MAAM,wBAAwB;AACvB,MAAM,sBAAsB;AAwBnC,MAAM,cAAc,oBAAI,IAAI,CAAC,OAAO,OAAO,QAAQ,UAAU,WAAW,QAAQ,SAAS,OAAO,CAAC;AAwB1F,SAAS,sBAAsB,OAAgC;AACpE,QAAM,SAAkC,CAAC;AAEzC,aAAW,CAAC,MAAM,OAAO,KAAK,OAAO,QAAQ,KAAK,GAAG;AACnD,QAAI,CAAC,SAAS;AACZ;AAAA,IACF;AAEA,UAAM,kBAAuC,CAAC;AAE9C,eAAW,CAAC,QAAQ,SAAS,KAAK,OAAO,QAAQ,OAAO,GAAG;AACzD,UAAI,YAAY,IAAI,OAAO,YAAY,CAAC,GAAG;AACzC,wBAAgB,MAAM,IAAI;AAAA,MAC5B;AAAA,IACF;AAEA,QAAI,OAAO,KAAK,eAAe,EAAE,SAAS,GAAG;AAC3C,aAAO,IAAI,IAAI;AAAA,IACjB;AAAA,EACF;AAEA,SAAO;AACT;AAWO,SAAS,YAAY,OAAgC;AAC1D,QAAM,SAAkC,CAAC;AACzC,SAAO,KAAK,KAAK,EAAE,QAAQ,CAAC,SAAS;AACnC,WAAO,kBAAkB,IAAI,CAAC,IAAI,MAAM,IAAI;AAAA,EAC9C,CAAC;AAED,SAAO;AACT;AAKO,SAAS,+BACd,UACA,MACA;AACA,QAAM,SAA8B,CAAC;AAErC,MAAI,CAAC,SAAS,YAAY;AACxB,WAAO;AAAA,EACT;AAEA,SAAO,QAAQ,SAAS,UAAU,EAAE,QAAQ,CAAC,CAAC,MAAM,SAAS,MAAM;AACjE,WAAO,IAAI,IAAI,CAAC;AAChB,WAAO,KAAK,SAAS,EAAE,QAAQ,CAAC,SAAS;AACvC,YAAM,MACJ,KAAK,SAAS,QACV,GAAG,KAAK,OAAO,IAAI,KAAK,IAAI,eAAe,IAAI,IAAI,IAAI,MACvD,GAAG,KAAK,SAAS,WAAW,KAAK,IAAI,eAAe,IAAI,IAAI,IAAI;AAEtE,aAAO,IAAI,EAAE,IAAI,IAAI,EAAE,QAAQ,IAAI;AAAA,IACrC,CAAC;AAAA,EACH,CAAC;AAED,SAAO;AACT;AAKO,SAAS,0BACd,UACA,MACA;AACA,QAAM,SAA8B,CAAC;AAErC,MAAI,CAAC,SAAS,OAAO;AACnB,WAAO;AAAA,EACT;AAEA,SAAO,QAAQ,SAAS,KAAK,EAAE,QAAQ,CAAC,CAAC,MAAM,QAAQ,MAAM;AAC3D,QAAI,CAAC,UAAU;AACb,aAAO;AAAA,IACT;AAEA,WAAO,IAAI,IAAI,CAAC;AAEhB,UAAM,cAAc,kBAAkB,IAAI;AAE1C,WAAO,KAAK,QAAQ,EAAE,QAAQ,CAAC,SAAS;AACtC,UAAI,YAAY,IAAI,IAAI,GAAG;AACzB,cAAM,MACJ,KAAK,SAAS,QACV,GAAG,KAAK,OAAO,IAAI,KAAK,IAAI,eAAe,WAAW,IAAI,IAAI,MAC9D,GAAG,KAAK,SAAS,WAAW,KAAK,IAAI,eAAe,WAAW,IAAI,IAAI;AAE7E,eAAO,IAAI,EAAE,IAAI,IAAI,EAAE,QAAQ,IAAI;AAAA,MACrC;AAAA,IACF,CAAC;AAAA,EACH,CAAC;AAED,SAAO;AACT;AAKO,SAAS,2BAA2B,gBAA4C;AACrF,QAAM,YAAY,eAAe,UAAU,IAAI,CAAC,OAAO;AACrD,UAAM,WAAW,QAAQ,GAAG,QAAQ,EAAE;AAEtC,WAAO,EAAE,GAAG,IAAI,SAAS;AAAA,EAC3B,CAAC;AAQD,QAAM,SAAS,UAAU,OAEvB,CAAC,KAAK,EAAE,MAAM,SAAS,MAAM;AAC7B,QAAI,IAAI,IAAI;AAAA,MACV,YAAY,SAAS;AAAA,MACrB,YAAY,SAAS,SAAS,YAAY,sBAAsB,SAAS,KAAK,CAAC;AAAA,IACjF;AACA,WAAO;AAAA,EACT,GAAG,CAAC,CAAC;AAWL,QAAM,YAAY;AAAA,IAChB,GAAG,eAAe;AAAA,IAClB,WAAW,UAAU,OAAgD,CAAC,KAAK,EAAE,MAAM,UAAU,KAAK,MAAM;AACtG,YAAM,UACJ,eAAe,SAAS,QACpB,EAAE,MAAM,eAAe,MAAM,MAAM,SAAS,eAAe,QAAQ,IACnE,EAAE,MAAM,eAAe,MAAM,MAAM,WAAW,eAAe,aAAa,sBAAsB;AAGtG,YAAM,aAAa,+BAA+B,UAAU,OAAO;AACnE,YAAM,QAAQ,0BAA0B,UAAU,OAAO;AAEzD,UAAI,IAAI,IAAI,EAAE,GAAG,MAAM,GAAG,UAAU,YAAY,MAAM;AACtD,aAAO;AAAA,IACT,GAAG,CAAC,CAAC;AAAA,EACP;AAEA,SAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAaL,yBAAyB,YAAY;AACnC,UAAI,eAAe,SAAS,UAAU;AACpC,cAAM;AAAA,MACR;AAGA,YAAM,WAAW,GAAG,IAAI,CAAC,IAAI,eAAe,aAAa,qBAAqB;AAC9E,YAAM,GAAG,MAAM,UAAU,EAAE,WAAW,KAAK,CAAC;AAG5C,YAAM,GAAG,UAAU,GAAG,QAAQ,IAAI,mBAAmB,IAAI,KAAK,UAAU,SAAS,CAAC;AAGlF,iBAAW,CAAC,MAAM,EAAE,YAAY,WAAW,CAAC,KAAK,OAAO,QAAQ,MAAM,GAAG;AAEvE,YAAI,YAAY;AACd,qBAAW,CAAC,MAAM,SAAS,KAAK,OAAO,QAAQ,UAAqD,GAAG;AACrG,kBAAM,gBAAgB,GAAG,QAAQ,WAAW,IAAI,eAAe,IAAI;AACnE,kBAAM,GAAG,MAAM,eAAe,EAAE,WAAW,KAAK,CAAC;AAEjD,uBAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,SAAS,GAAG;AACpD,oBAAM,GAAG,UAAU,GAAG,aAAa,IAAI,GAAG,SAAS,KAAK,UAAU,KAAK,CAAC;AAAA,YAC1E;AAAA,UACF;AAAA,QACF;AAGA,YAAI,YAAY;AACd,qBAAW,CAAC,MAAM,OAAO,KAAK,OAAO,QAAQ,UAAqD,GAAG;AACnG,kBAAM,gBAAgB,GAAG,QAAQ,WAAW,IAAI,eAAe,IAAI;AACnE,kBAAM,GAAG,MAAM,eAAe,EAAE,WAAW,KAAK,CAAC;AAEjD,uBAAW,CAAC,QAAQ,SAAS,KAAK,OAAO,QAAQ,OAAO,GAAG;AACzD,oBAAM,GAAG,UAAU,GAAG,aAAa,IAAI,MAAM,SAAS,KAAK,UAAU,SAAS,CAAC;AAAA,YACjF;AAAA,UACF;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAYA,cAAc,MAAM;AAClB,aAAO;AAAA,IACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAmBA,KAAK,CAAC,YAAoB;AACxB,aAAO,eAAe,QAAQ,iBAAiB,OAAO,CAAC;AAAA,IACzD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAaA,aAAa,CAAC,UAAmC,SAAmD;AAClG,YAAM,EAAE,MAAM,GAAG,aAAa,IAAI;AAElC,YAAM,aAAa,QAAQ,QAAQ,EAAE;AAGrC,aAAO,KAAK,IAAI,IAAI;AAAA,QAClB,YAAY,WAAW,QAAQ;AAAA,QAC/B,YAAY,WAAW,QAAQ,SAAS,YAAY,sBAAsB,WAAW,OAAO,KAAY,CAAC;AAAA,MAC3G;AAEA,YAAM,UACJ,eAAe,SAAS,QACpB,EAAE,MAAM,eAAe,MAAM,MAAM,SAAS,eAAe,QAAQ,IACnE,EAAE,MAAM,eAAe,MAAM,MAAM,WAAW,eAAe,aAAa,sBAAsB;AAEtG,YAAM,aAAa,+BAA+B,YAAY,OAAO;AACrE,YAAM,QAAQ,0BAA0B,YAAY,OAAO;AAI3D,gBAAU,UAAU,KAAK,IAAI,IAAI,EAAE,GAAG,cAAc,GAAG,YAAY,YAAY,MAAM;AAAA,IACvF;AAAA,EACF;AACF;",
+  "names": []
+}