@scalar/workspace-store 0.1.0

package/src/create-workspace-store.ts

@@ -0,0 +1,282 @@
+import { reactive, toRaw } from 'vue'
+import type { WorkspaceMeta, WorkspaceDocumentMeta, Workspace } from './schemas/server-workspace'
+import { createMagicProxy, getRaw } from './helpers/proxy'
+import { fetchUrl, isObject, readLocalFile, resolveContents } from '@/helpers/general'
+import { getValueByPath, parseJsonPointer } from '@/helpers/json-path-utils'
+
+type WorkspaceDocumentMetaInput = { meta?: WorkspaceDocumentMeta; name: string }
+type WorkspaceDocumentInput =
+  | ({ document: Record<string, unknown> } & WorkspaceDocumentMetaInput)
+  | ({ url: string } & WorkspaceDocumentMetaInput)
+  | ({ path: string } & WorkspaceDocumentMetaInput)
+
+/**
+ * Resolves a workspace document from various input sources (URL, local file, or direct document object).
+ *
+ * @param workspaceDocument - The document input to resolve, which can be:
+ *   - A URL to fetch the document from
+ *   - A local file path to read the document from
+ *   - A direct document object
+ * @returns A promise that resolves to an object containing:
+ *   - ok: boolean indicating if the resolution was successful
+ *   - data: The resolved document data
+ *
+ * @example
+ * // Resolve from URL
+ * const urlDoc = await loadDocument({ name: 'api', url: 'https://api.example.com/openapi.json' })
+ *
+ * // Resolve from local file
+ * const fileDoc = await loadDocument({ name: 'local', path: './openapi.json' })
+ *
+ * // Resolve direct document
+ * const directDoc = await loadDocument({
+ *   name: 'inline',
+ *   document: { openapi: '3.0.0', paths: {} }
+ * })
+ */
+async function loadDocument(workspaceDocument: WorkspaceDocumentInput) {
+  if ('url' in workspaceDocument) {
+    return fetchUrl(workspaceDocument.url)
+  }
+
+  if ('path' in workspaceDocument) {
+    return readLocalFile(workspaceDocument.path)
+  }
+
+  return {
+    ok: true as const,
+    data: workspaceDocument.document,
+  }
+}
+
+/**
+ * Creates a reactive workspace store that manages documents and their metadata.
+ * The store provides functionality for accessing, updating, and resolving document references.
+ *
+ * @param workspaceProps - Configuration object for the workspace
+ * @param workspaceProps.meta - Optional metadata for the workspace
+ * @param workspaceProps.documents - Optional record of documents to initialize the workspace with
+ * @returns An object containing methods and getters for managing the workspace
+ */
+export async function createWorkspaceStore(workspaceProps?: {
+  meta?: WorkspaceMeta
+  documents?: WorkspaceDocumentInput[]
+}) {
+  // Create a reactive workspace object with proxied documents
+  // Each document is wrapped in a proxy to enable reactive updates and reference resolution
+  const workspace = reactive({
+    ...workspaceProps?.meta,
+    documents: (
+      await Promise.all(
+        (workspaceProps?.documents ?? []).map<
+          Promise<{ name: string; meta?: WorkspaceDocumentMeta; document: Record<string, unknown> }>
+        >(async (data) => {
+          const resolved = await loadDocument(data)
+
+          if (!resolved.ok) {
+            console.error(`Can not load the document '${data.name}'`)
+            return {
+              name: data.name,
+              meta: data.meta,
+              document: {},
+            }
+          }
+
+          return {
+            name: data.name,
+            meta: data.meta,
+            document: isObject(resolved.data) ? (resolved.data as Record<string, unknown>) : {},
+          }
+        }),
+      )
+    ).reduce<Record<string, Record<string, unknown>>>((acc, { name, meta, document }) => {
+      /**
+       * We wrap each document in the magic proxy to enable auto-resolving of references
+       */
+      acc[name] = createMagicProxy({ ...document, ...meta })
+      return acc
+    }, {}),
+    /**
+     * Returns the currently active document from the workspace.
+     * The active document is determined by the 'x-scalar-active-document' metadata field,
+     * falling back to the first document in the workspace if no active document is specified.
+     *
+     * @returns The active document or undefined if no document is found
+     */
+    get activeDocument(): (typeof workspace.documents)[number] | undefined {
+      const activeDocumentKey = workspace['x-scalar-active-document'] ?? Object.keys(workspace.documents)[0] ?? ''
+      return workspace.documents[activeDocumentKey]
+    },
+  }) as Workspace
+
+  return {
+    /**
+     * Returns the raw (non-reactive) workspace object
+     */
+    get rawWorkspace() {
+      return toRaw(workspace)
+    },
+    /**
+     * Returns the reactive workspace object with an additional activeDocument getter
+     */
+    get workspace() {
+      return workspace
+    },
+    /**
+     * Updates a specific metadata field in the workspace
+     * @param key - The metadata field to update
+     * @param value - The new value for the field
+     * @example
+     * // Update the workspace title
+     * update('x-scalar-active-document', 'document-name')
+     */
+    update<K extends keyof WorkspaceMeta>(key: K, value: WorkspaceMeta[K]) {
+      // @ts-ignore
+      if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+        throw new Error('Invalid key: cannot modify prototype')
+      }
+      Object.assign(workspace, { [key]: value })
+    },
+    /**
+     * Updates a specific metadata field in a document
+     * @param name - The name of the document to update ('active' or a specific document name)
+     * @param key - The metadata field to update
+     * @param value - The new value for the field
+     * @throws Error if the specified document doesn't exist
+     * @example
+     * // Update the auth of the active document
+     * updateDocument('active', 'x-scalar-active-auth', 'Bearer')
+     * // Update the auth of a specific document
+     * updateDocument('document-name', 'x-scalar-active-auth', 'Bearer')
+     */
+    updateDocument<K extends keyof WorkspaceDocumentMeta>(
+      name: 'active' | (string & {}),
+      key: K,
+      value: WorkspaceDocumentMeta[K],
+    ) {
+      const currentDocument =
+        workspace.documents[
+          name === 'active'
+            ? (workspace['x-scalar-active-document'] ?? workspaceProps?.documents?.[0].name ?? '')
+            : name
+        ]
+
+      if (!currentDocument) {
+        throw 'Please select a valid document'
+      }
+
+      Object.assign(currentDocument, { [key]: value })
+    },
+    /**
+     * Resolves a reference in the active document by following the provided path and resolving any external $ref references.
+     * This method traverses the document structure following the given path and resolves any $ref references it encounters.
+     * During resolution, it sets a loading status and updates the reference with the resolved content.
+     *
+     * @param path - Array of strings representing the path to the reference (e.g. ['paths', '/users', 'get', 'responses', '200'])
+     * @throws Error if the path is invalid or empty
+     * @example
+     * // Resolve a reference in the active document
+     * resolve(['paths', '/users', 'get', 'responses', '200'])
+     */
+    resolve: async (path: string[]) => {
+      if (path.length <= 1) {
+        throw 'Please provide a valid path'
+      }
+
+      const lastPathSegment = path.pop()! // We are sure there is at least an element on the array
+
+      const activeDocument =
+        workspace.documents[workspace['x-scalar-active-document'] ?? Object.keys(workspace.documents)[0] ?? '']
+
+      let parent = activeDocument as Record<string, any>
+
+      for (const p of path) {
+        parent = parent[p]
+      }
+
+      // Keep track of objects we've already processed to prevent infinite loops
+      const processedObjects = new WeakSet()
+
+      const resolveRecursive = async (root: unknown, targetKey: string) => {
+        if (!root && !isObject(root)) {
+          return
+        }
+
+        const target = (root as Record<string, unknown>)[targetKey]
+
+        if (!target || !isObject(target)) {
+          return
+        }
+
+        // Unwrap the target from the proxy
+        const rawTarget = getRaw(target)
+
+        // Skip if we've already processed this object
+        if (processedObjects.has(rawTarget)) {
+          return
+        }
+
+        // Mark this object as processed
+        processedObjects.add(rawTarget)
+
+        if (typeof target === 'object' && '$ref' in target && typeof target['$ref'] === 'string') {
+          const ref = target['$ref']
+
+          // Set the status to loading while we resolve the ref
+          Object.assign(target, { '$status': 'loading' })
+
+          const [path, pointer] = ref.split('#')
+          const result = await resolveContents(path)
+
+          if (result.ok) {
+            if (targetKey === '__proto__' || targetKey === 'constructor' || targetKey === 'prototype') {
+              throw new Error('Invalid key: cannot modify prototype')
+            }
+
+            Object.assign(root as object, { [targetKey]: getValueByPath(result.data, parseJsonPointer(pointer)) })
+
+            await resolveRecursive(root, targetKey)
+          } else {
+            Object.assign(target, { '$status': 'error' })
+          }
+
+          return
+        }
+
+        await Promise.all(Object.keys(target).map((key) => resolveRecursive(target, key)))
+      }
+
+      return resolveRecursive(parent, lastPathSegment)
+    },
+    /**
+     * Adds a new document to the workspace
+     * @param document - The document content to add. This should be a valid OpenAPI/Swagger document or other supported format
+     * @param meta - Metadata for the document, including its name and other properties defined in WorkspaceDocumentMeta
+     * @example
+     * // Add a new OpenAPI document to the workspace
+     * store.addDocument({
+     *   name: 'name',
+     *   document: {
+     *     openapi: '3.0.0',
+     *     info: { title: 'title' },
+     *   },
+     *   meta: {
+     *     'x-scalar-active-auth': 'Bearer',
+     *     'x-scalar-active-server': 'production'
+     *   }
+     * })
+     */
+    addDocument: async (input: WorkspaceDocumentInput) => {
+      const { name, meta } = input
+
+      const resolve = await loadDocument(input)
+
+      if (!resolve.ok || !isObject(resolve.data)) {
+        console.error(`Can not load the document '${name}'`)
+        return
+      }
+
+      workspace.documents[name] = createMagicProxy({ ...(resolve.data as Record<string, unknown>), ...meta })
+    },
+  }
+}

package/src/helpers/general.ts

@@ -0,0 +1,115 @@
+import fs from 'node:fs/promises'
+
+export type UnknownObject = Record<string, unknown>
+
+/**
+ * Returns true if the value is a non-null object (but not an array).
+ *
+ * @example
+ * ```ts
+ * isObject({}) // true
+ * isObject([]) // false
+ * isObject(null) // false
+ * ```
+ */
+export function isObject(value: unknown): value is UnknownObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Checks if a string is a remote URL (starts with http:// or https://)
+ * @param value - The URL string to check
+ * @returns true if the string is a remote URL, false otherwise
+ * @example
+ * ```ts
+ * isRemoteUrl('https://example.com/schema.json') // true
+ * isRemoteUrl('http://api.example.com/schemas/user.json') // true
+ * isRemoteUrl('#/components/schemas/User') // false
+ * isRemoteUrl('./local-schema.json') // false
+ * ```
+ */
+export function isRemoteUrl(value: string): boolean {
+  return value.startsWith('http://') || value.startsWith('https://')
+}
+
+/**
+ * Checks if a string is a local reference (starts with #)
+ * @param value - The reference string to check
+ * @returns true if the string is a local reference, false otherwise
+ * @example
+ * ```ts
+ * isLocalRef('#/components/schemas/User') // true
+ * isLocalRef('https://example.com/schema.json') // false
+ * isLocalRef('./local-schema.json') // false
+ * ```
+ */
+export function isLocalRef(value: string): boolean {
+  return value.startsWith('#')
+}
+
+type ResolveResult = { ok: false } | { ok: true; data: unknown }
+
+/**
+ * Fetches and parses JSON data from a remote URL.
+ *
+ * @param value - The URL to fetch data from
+ * @returns A result object containing either the parsed JSON data or an error indicator
+ * @example
+ * ```ts
+ * const result = await fetchUrl('https://api.example.com/data')
+ * if (result.ok) {
+ *   console.log(result.data) // The parsed JSON data
+ * }
+ * ```
+ */
+export async function fetchUrl(value: string): Promise<ResolveResult> {
+  const response = await fetch(value)
+
+  if (response.ok) {
+    const body = await response.json()
+    return { ok: true, data: body }
+  }
+
+  return { ok: false }
+}
+
+/**
+ * Reads and parses a local JSON file from the filesystem.
+ *
+ * @param value - The file path to read from
+ * @returns A result object containing either the parsed JSON data or an error indicator
+ * @example
+ * ```ts
+ * const result = await readLocalFile('./data.json')
+ * if (result.ok) {
+ *   console.log(result.data) // The parsed JSON data
+ * }
+ * ```
+ */
+export async function readLocalFile(value: string): Promise<ResolveResult> {
+  try {
+    const contents = await fs.readFile(value, 'utf-8')
+
+    return { ok: true, data: JSON.parse(contents) }
+  } catch {
+    return { ok: false }
+  }
+}
+
+/**
+ * Resolves a reference by attempting to fetch data from either a remote URL or local filesystem.
+ * The function automatically determines whether to use fetchUrl() for remote URLs or readLocalFile() for local paths.
+ *
+ * @param value - The reference string to resolve (URL or file path)
+ * @returns A result object containing either the resolved data or an error indicator
+ * @example
+ * ```ts
+ * const result = await resolveContents('https://api.example.com/data')
+ * if (result.ok) {
+ *   console.log(result.data) // The resolved data
+ * }
+ * ```
+ */
+export async function resolveContents(value: string): Promise<ResolveResult> {
+  return isRemoteUrl(value) ? await fetchUrl(value) : await readLocalFile(value)
+}

package/src/helpers/json-path-utils.test.ts

@@ -0,0 +1,13 @@
+import { parseJsonPointer } from '@/helpers/json-path-utils'
+import { describe, expect, test } from 'vitest'
+
+describe('parseJsonPointer', () => {
+  test.each([
+    ['#/users/name', ['users', 'name']],
+    ['#/', []],
+    ['', []],
+    ['users/name', ['users', 'name']],
+  ])('should correctly parse json pointers', (a, b) => {
+    expect(parseJsonPointer(a)).toEqual(b)
+  })
+})

package/src/helpers/json-path-utils.ts

@@ -0,0 +1,38 @@
+/**
+ * Parses a JSON Pointer string into an array of path segments
+ *
+ * @example
+ * ```ts
+ * parseJsonPointer('#/components/schemas/User')
+ *
+ * ['components', 'schemas', 'User']
+ * ```
+ */
+export function parseJsonPointer(pointer: string): string[] {
+  return (
+    pointer
+      // Split on '/'
+      .split('/')
+      // Remove the leading '#' if present
+      .filter((segment, index) => (index !== 0 || segment !== '#') && segment)
+  )
+}
+
+/**
+ * Retrieves a nested value from the source document using a path array
+ *
+ * @example
+ * ```ts
+ * getValueByPath(document, ['components', 'schemas', 'User'])
+ *
+ * { id: '123', name: 'John Doe' }
+ * ```
+ */
+export function getValueByPath(obj: any, pointer: string[]): unknown {
+  return pointer.reduce((acc, part) => {
+    if (acc === undefined || acc === null) {
+      return undefined
+    }
+    return acc[part]
+  }, obj)
+}

package/src/helpers/proxy.test.ts

@@ -0,0 +1,61 @@
+import { createMagicProxy } from '@/helpers/proxy'
+import { describe, expect, test } from 'vitest'
+
+describe('createMagicProxy', () => {
+  test('should correctly proxy internal refs', () => {
+    const input = {
+      a: 'hello',
+      b: {
+        '$ref': '#/a',
+      },
+    }
+
+    const result = createMagicProxy(input)
+
+    expect(result.b).toBe('hello')
+  })
+
+  test('should correctly proxy deep nested refs', () => {
+    const input = {
+      a: {
+        b: {
+          c: {
+            d: {
+              prop: 'hello',
+            },
+            e: {
+              '$ref': '#/a/b/c/d',
+            },
+          },
+        },
+      },
+    }
+
+    const result = createMagicProxy(input) as any
+    expect(result.a.b.c.e.prop).toBe('hello')
+  })
+
+  test('should correctly proxy multi refs', () => {
+    const input = {
+      a: {
+        b: {
+          c: {
+            prop: 'hello',
+          },
+        },
+      },
+      e: {
+        f: {
+          $ref: '#/a/b/c/prop',
+        },
+      },
+      d: {
+        $ref: '#/e/f',
+      },
+    }
+
+    const result = createMagicProxy(input)
+
+    expect(result.d).toBe('hello')
+  })
+})