@scalar/workspace-store 0.3.1 → 0.3.2

package/src/client.ts

@@ -1,254 +0,0 @@
-import { reactive, toRaw } from 'vue'
-import type { WorkspaceMeta, WorkspaceDocumentMeta, Workspace } from './schemas/server-workspace'
-import { createMagicProxy } from './helpers/proxy'
-import { isObject } from '@/helpers/general'
-import { getValueByPath } from '@/helpers/json-path-utils'
-import { bundle } from '@scalar/openapi-parser'
-import { fetchUrls } from '@scalar/openapi-parser/utils/bundle/plugins/fetch-urls'
-
-type WorkspaceDocumentMetaInput = { meta?: WorkspaceDocumentMeta; name: string }
-type WorkspaceDocumentInput =
-  | ({ document: Record<string, unknown> } & WorkspaceDocumentMetaInput)
-  | ({ url: 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 fetchUrls().exec(workspaceDocument.url)
-  }
-
-  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
- * @deprecated Use `createWorkspaceStore` instead.
- */
-export function createWorkspaceStoreSync(workspaceProps?: {
-  meta?: WorkspaceMeta
-}) {
-  // 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: {},
-    /**
-     * 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
-
-  // Cache to track visited nodes during reference resolution to prevent bundling the same subtree multiple times
-  // This is needed because we are doing partial bundle operations
-  const visitedNodesCache = new Set()
-
-  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'] ?? Object.keys(workspace.documents)[0] ?? '')
-            : 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[]) => {
-      const activeDocument = workspace.activeDocument
-
-      const target = getValueByPath(activeDocument, path)
-
-      if (!isObject(target)) {
-        console.error(
-          `Invalid path provided for resolution. Path: [${path.join(', ')}]. Found value of type: ${typeof target}. Expected an object.`,
-        )
-        return
-      }
-
-      // Bundle the target document with the active document as root, resolving any external references
-      // and tracking resolution status through hooks
-      return bundle(target, {
-        root: activeDocument,
-        treeShake: false,
-        plugins: [fetchUrls()],
-        urlMap: false,
-        hooks: {
-          onResolveStart: (node) => {
-            node['$status'] = 'loading'
-          },
-          onResolveError: (node) => {
-            node['$status'] = 'error'
-          },
-        },
-        visitedNodes: visitedNodesCache,
-      })
-    },
-    /**
-     * 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}'`)
-        workspace.documents[name] = {
-          ...meta,
-        }
-        return
-      }
-
-      workspace.documents[name] = createMagicProxy({ ...(resolve.data as Record<string, unknown>), ...meta })
-    },
-  }
-}
-
-/**
- * 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
- * @example
- * // Create a workspace store with metadata and documents
- * const store = await createWorkspaceStore({
- *   meta: {
- *     name: 'My Workspace',
- *     description: 'A workspace for my API'
- *   },
- *   documents: [
- *     {
- *       name: 'petstore',
- *       document: {
- *         openapi: '3.0.0',
- *         info: { title: 'Petstore API' }
- *       }
- *     }
- *   ]
- * })
- */
-export async function createWorkspaceStore(workspaceProps?: {
-  meta?: WorkspaceMeta
-  documents?: WorkspaceDocumentInput[]
-}) {
-  const store = createWorkspaceStoreSync({ meta: workspaceProps?.meta })
-
-  await Promise.all(workspaceProps?.documents?.map((it) => store.addDocument(it)) ?? [])
-
-  return store
-}

package/src/helpers/general.ts

@@ -1,30 +0,0 @@
-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 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('#')
-}

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

@@ -1,13 +0,0 @@
-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

@@ -1,38 +0,0 @@
-/**
- * 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

@@ -1,61 +0,0 @@
-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')
-  })
-})

package/src/helpers/proxy.ts

@@ -1,213 +0,0 @@
-import { isReactive, toRaw } from 'vue'
-import { getValueByPath, parseJsonPointer } from './json-path-utils'
-import { isLocalRef, isObject } from './general'
-import type { UnknownObject } from './general'
-
-export const TARGET_SYMBOL = Symbol('target')
-
-/**
- * Creates a proxy handler that automatically resolves JSON references ($ref) in an object.
- * The handler intercepts property access, assignment, and property enumeration to automatically
- * resolve any $ref references to their target values in the source document.
- *
- * @param sourceDocument - The source document containing the reference targets
- * @param resolvedProxyCache - Optional cache to store resolved proxies and prevent duplicate proxies
- * @returns A proxy handler that automatically resolves $ref references
- */
-function createProxyHandler(
-  sourceDocument: UnknownObject,
-  resolvedProxyCache?: WeakMap<object, UnknownObject>,
-): ProxyHandler<UnknownObject> {
-  return {
-    get(target, property, receiver) {
-      if (property === TARGET_SYMBOL) {
-        return target
-      }
-
-      if (property === '__isProxy') {
-        return true
-      }
-
-      const value = Reflect.get(target, property, receiver)
-
-      /**
-       * Recursively resolves nested references in an object.
-       * If the value is not an object, returns it as is.
-       * If the value has a $ref property:
-       *   - For local references: resolves the reference and continues resolving nested refs
-       *   - For all other objects: creates a proxy for lazy resolution
-       */
-      const deepResolveNestedRefs = (value: unknown) => {
-        if (!isObject(value)) {
-          return value
-        }
-
-        if ('$ref' in value) {
-          const ref = value.$ref as string
-
-          if (isLocalRef(ref)) {
-            const referencePath = parseJsonPointer(ref)
-            const resolvedValue = getValueByPath(sourceDocument, referencePath)
-
-            return deepResolveNestedRefs(resolvedValue)
-          }
-        }
-
-        return createMagicProxy(value, sourceDocument, resolvedProxyCache)
-      }
-
-      return deepResolveNestedRefs(value)
-    },
-
-    set(target: UnknownObject, property: string, newValue: unknown, receiver: UnknownObject) {
-      const rawTarget = isReactive(target) ? toRaw(target) : target
-      const currentValue = rawTarget[property]
-
-      if (
-        isObject(currentValue) &&
-        '$ref' in currentValue &&
-        typeof currentValue.$ref === 'string' &&
-        isLocalRef(currentValue.$ref)
-      ) {
-        const referencePath = parseJsonPointer(currentValue.$ref)
-        const targetObject = getValueByPath(sourceDocument, referencePath.slice(0, -1)) as UnknownObject
-        const lastPathSegment = referencePath[referencePath.length - 1]
-
-        if (targetObject && lastPathSegment) {
-          targetObject[lastPathSegment] = newValue
-        }
-      } else {
-        Reflect.set(rawTarget, property, newValue, receiver)
-      }
-      return true
-    },
-
-    has(target: UnknownObject, key: string) {
-      if (typeof key === 'string' && key !== '$ref' && typeof target.$ref === 'string' && isLocalRef(target.$ref)) {
-        const referencePath = parseJsonPointer(target['$ref'])
-        const resolvedValue = getValueByPath(sourceDocument, referencePath) as UnknownObject
-
-        return resolvedValue ? key in resolvedValue : false
-      }
-
-      return key in target
-    },
-
-    ownKeys(target: UnknownObject) {
-      if ('$ref' in target && typeof target.$ref === 'string' && isLocalRef(target.$ref)) {
-        const referencePath = parseJsonPointer(target['$ref'])
-        const resolvedValue = getValueByPath(sourceDocument, referencePath)
-
-        return resolvedValue ? Reflect.ownKeys(resolvedValue) : []
-      }
-
-      return Reflect.ownKeys(target)
-    },
-
-    getOwnPropertyDescriptor(target: UnknownObject, key: string) {
-      if ('$ref' in target && key !== '$ref' && typeof target.$ref === 'string' && isLocalRef(target.$ref)) {
-        const referencePath = parseJsonPointer(target['$ref'])
-        const resolvedValue = getValueByPath(sourceDocument, referencePath)
-
-        if (resolvedValue) {
-          return Object.getOwnPropertyDescriptor(resolvedValue, key)
-        }
-      }
-
-      return Object.getOwnPropertyDescriptor(target, key)
-    },
-  }
-}
-
-/**
- * Creates a proxy that automatically resolves JSON references ($ref) in an object.
- * The proxy intercepts property access and automatically resolves any $ref references
- * to their target values in the source document.
- *
- * @param targetObject - The object to create a proxy for
- * @param sourceDocument - The source document containing the reference targets (defaults to targetObject)
- * @param resolvedProxyCache - Optional cache to store resolved proxies and prevent duplicate proxies
- * @returns A proxy that automatically resolves $ref references
- *
- * @example
- * // Basic usage with local references
- * const doc = {
- *   components: {
- *     schemas: {
- *       User: { type: 'object', properties: { name: { type: 'string' } } }
- *     }
- *   },
- *   paths: {
- *     '/users': {
- *       get: {
- *         responses: {
- *           200: {
- *             content: {
- *               'application/json': {
- *                 schema: { $ref: '#/components/schemas/User' }
- *               }
- *             }
- *           }
- *         }
- *       }
- *     }
- *   }
- * }
- *
- * const proxy = createMagicProxy(doc)
- * // Accessing the schema will automatically resolve the $ref
- * console.log(proxy.paths['/users'].get.responses[200].content['application/json'].schema)
- * // Output: { type: 'object', properties: { name: { type: 'string' } } }
- *
- * @example
- * // Using with a cache to prevent duplicate proxies
- * const cache = new WeakMap()
- * const proxy1 = createMagicProxy(doc, doc, cache)
- * const proxy2 = createMagicProxy(doc, doc, cache)
- * // proxy1 and proxy2 are the same instance due to caching
- * console.log(proxy1 === proxy2) // true
- */
-export function createMagicProxy<T extends UnknownObject>(
-  targetObject: T,
-  sourceDocument: T = targetObject,
-  resolvedProxyCache?: WeakMap<object, T>,
-): T {
-  if (!isObject(targetObject)) {
-    return targetObject
-  }
-
-  const rawTarget = isReactive(targetObject) ? toRaw(targetObject) : targetObject
-
-  // check for cached results
-  if (resolvedProxyCache?.has(rawTarget)) {
-    const cachedValue = resolvedProxyCache.get(rawTarget)
-
-    if (cachedValue) {
-      return cachedValue
-    }
-  }
-
-  // Create a handler with the correct context
-  const handler = createProxyHandler(sourceDocument, resolvedProxyCache)
-  const proxy = new Proxy<T>(rawTarget, handler)
-
-  if (resolvedProxyCache) {
-    resolvedProxyCache.set(rawTarget, proxy)
-  }
-
-  return proxy
-}
-
-/**
- * Gets the raw (non-proxied) version of an object created by createMagicProxy.
- * This is useful when you need to access the original object without the magic proxy wrapper.
- *
- * @param obj - The magic proxy object to get the raw version of
- * @returns The raw version of the object
- * @example
- * const proxy = createMagicProxy({ foo: { $ref: '#/bar' } })
- * const raw = getRaw(proxy) // { foo: { $ref: '#/bar' } }
- */
-export function getRaw(obj: UnknownObject) {
-  return (obj as { [TARGET_SYMBOL]: UnknownObject })[TARGET_SYMBOL]
-}

package/src/schemas/callback.ts

@@ -1,13 +0,0 @@
-import { Type } from '@sinclair/typebox'
-import { PathItemObject } from './path-item'
-
-/**
- * A map of possible out-of band callbacks related to the parent operation. Each value in the map is a Path Item Object that describes a set of requests that may be initiated by the API provider and the expected responses. The key value used to identify the Path Item Object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.
- *
- * To describe incoming requests from the API provider independent from another API call, use the webhooks field.
- */
-export const CallbackObject = Type.Record(
-  Type.String(),
-  /** A Path Item Object used to define a callback request and expected responses. A complete example is available. */
-  PathItemObject,
-)

package/src/schemas/components.ts

@@ -1,36 +0,0 @@
-import { Type } from '@sinclair/typebox'
-import { SchemaObject } from './schema'
-import { ResponseObject } from './response'
-import { ReferenceObject } from './reference'
-import { ParameterObject } from './parameter'
-import { ExampleObject } from './example'
-import { RequestBodyObject } from './request-body'
-import { SecuritySchemeObject } from './security-scheme'
-import { LinkObject } from './link'
-import { CallbackObject } from './callback'
-import { PathItemObject } from './path-item'
-import { HeaderObject } from './header'
-
-/** Holds a set of reusable objects for different aspects of the OAS. All objects defined within the Components Object will have no effect on the API unless they are explicitly referenced from outside the Components Object. */
-export const ComponentsObject = Type.Object({
-  /** An object to hold reusable Schema Objects. */
-  schemas: Type.Optional(Type.Record(Type.String(), SchemaObject)),
-  /** An object to hold reusable Response Objects. */
-  responses: Type.Optional(Type.Record(Type.String(), Type.Union([ResponseObject, ReferenceObject]))),
-  /** An object to hold reusable Parameter Objects. */
-  parameters: Type.Optional(Type.Record(Type.String(), Type.Union([ParameterObject, ReferenceObject]))),
-  /** An object to hold reusable Example Objects. */
-  examples: Type.Optional(Type.Record(Type.String(), Type.Union([ExampleObject, ReferenceObject]))),
-  /** An object to hold reusable Request Body Objects. */
-  requestBodies: Type.Optional(Type.Record(Type.String(), Type.Union([RequestBodyObject, ReferenceObject]))),
-  /** An object to hold reusable Header Objects. */
-  headers: Type.Optional(Type.Record(Type.String(), Type.Union([HeaderObject, ReferenceObject]))),
-  /** An object to hold reusable Security Scheme Objects. */
-  securitySchemes: Type.Optional(Type.Record(Type.String(), Type.Union([SecuritySchemeObject, ReferenceObject]))),
-  /** An object to hold reusable Link Objects. */
-  links: Type.Optional(Type.Record(Type.String(), Type.Union([LinkObject, ReferenceObject]))),
-  /** An object to hold reusable Callback Objects. */
-  callbacks: Type.Optional(Type.Record(Type.String(), Type.Union([CallbackObject, ReferenceObject]))),
-  /** An object to hold reusable Path Item Objects. */
-  pathItems: Type.Optional(Type.Record(Type.String(), PathItemObject)),
-})

package/src/schemas/contact.ts

@@ -1,11 +0,0 @@
-import { Type } from '@sinclair/typebox'
-
-/** Contact information for the exposed API. */
-export const ContactObject = Type.Object({
-  /** The identifying name of the contact person/organization. */
-  name: Type.Optional(Type.String()),
-  /** The URI for the contact information. This MUST be in the form of a URI. */
-  url: Type.Optional(Type.String()),
-  /** The email address of the contact person/organization. This MUST be in the form of an email address. */
-  email: Type.Optional(Type.String()),
-})

package/src/schemas/discriminator.ts

@@ -1,13 +0,0 @@
-import { Type } from '@sinclair/typebox'
-
-/**
- * When request bodies or response payloads may be one of a number of different schemas, a Discriminator Object gives a hint about the expected schema of the document. This hint can be used to aid in serialization, deserialization, and validation. The Discriminator Object does this by implicitly or explicitly associating the possible values of a named property with alternative schemas.
- *
- * Note that discriminator MUST NOT change the validation outcome of the schema.
- */
-export const DiscriminatorObject = Type.Object({
-  /** REQUIRED. The name of the property in the payload that will hold the discriminating value. This property SHOULD be required in the payload schema, as the behavior when the property is absent is undefined. */
-  propertyName: Type.String(),
-  /** An object to hold mappings between payload values and schema names or URI references. */
-  mapping: Type.Optional(Type.Record(Type.String(), Type.String())),
-})