@scalar/json-magic 0.8.2 → 0.8.4

package/src/helpers/get-schemas.ts

@@ -1,80 +0,0 @@
-/**
- * Retrieves the $id property from the input object if it exists and is a string.
- *
- * @param input - The object to extract the $id from.
- * @returns The $id string if present, otherwise undefined.
- */
-export const getId = (input: unknown): string | undefined => {
-  if (input && typeof input === 'object' && input['$id'] && typeof input['$id'] === 'string') {
-    return input['$id']
-  }
-  return undefined
-}
-
-/**
- * Joins an array of path segments into a single string separated by '/'.
- *
- * @param segments - The array of path segments.
- * @returns The joined path string.
- */
-const getPath = (segments: string[]): string => {
-  return segments.join('/')
-}
-
-/**
- * Recursively traverses the input object to collect all schemas identified by $id and $anchor properties.
- *
- * - If an object has a $id property, it is added to the map with its $id as the key.
- * - If an object has a $anchor property, it is added to the map with a key composed of the current base and the anchor.
- * - The function performs a depth-first search (DFS) through all nested objects.
- *
- * @param input - The input object to traverse.
- * @param base - The current base URI, used for resolving anchors.
- * @param map - The map collecting found schemas.
- * @returns A map of schema identifiers to their corresponding objects.
- */
-export const getSchemas = (
-  input: unknown,
-  base: string = '',
-  segments: string[] = [],
-  map = new Map<string, string>(),
-  visited = new WeakSet(),
-) => {
-  // Only process non-null objects
-  if (typeof input !== 'object' || input === null) {
-    return map
-  }
-
-  // If the object has already been visited, return the map
-  if (visited.has(input)) {
-    return map
-  }
-
-  // Add the object to the visited set
-  visited.add(input)
-
-  // Attempt to get $id from the current object
-  const id = getId(input)
-
-  // If $id exists, add the object to the map with $id as the key
-  if (id) {
-    map.set(id, getPath(segments))
-  }
-
-  // Update the base for nested anchors
-  const newBase = id ?? base
-
-  // If $anchor exists, add the object to the map with base#anchor as the key
-  if (input['$anchor'] && typeof input['$anchor'] === 'string') {
-    map.set(`${newBase}#${input['$anchor']}`, getPath(segments))
-  }
-
-  // Recursively traverse all properties (DFS)
-  for (const key in input) {
-    if (typeof input[key] === 'object' && input[key] !== null) {
-      getSchemas(input[key], newBase, [...segments, key], map, visited)
-    }
-  }
-
-  return map
-}

package/src/helpers/get-segments-from-path.test.ts

@@ -1,17 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { getSegmentsFromPath } from './get-segments-from-path'
-
-describe('getSegmentsFromPath', () => {
-  it('returns path segments', () => {
-    const result = getSegmentsFromPath('/paths/test')
-
-    expect(result).toEqual(['paths', 'test'])
-  })
-
-  it('unescaped slashes', () => {
-    const result = getSegmentsFromPath('/paths/~1test')
-
-    expect(result).toEqual(['paths', '/test'])
-  })
-})

package/src/helpers/get-segments-from-path.ts

@@ -1,17 +0,0 @@
-import { unescapeJsonPointer } from './unescape-json-pointer'
-
-/**
- * Translate `/paths/~1test` to `['paths', '/test']`
- */
-export function getSegmentsFromPath(path: string) {
-  return (
-    // /paths/~1test
-    path
-      // ['', 'paths', '~1test']
-      .split('/')
-      // ['paths', '~test']
-      .slice(1)
-      // ['paths', '/test']
-      .map(unescapeJsonPointer)
-  )
-}

package/src/helpers/get-value-by-path.test.ts

@@ -1,338 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { getValueByPath } from './get-value-by-path'
-
-describe('getValueByPath', () => {
-  it('should return the value at a simple path', () => {
-    const target = {
-      foo: 'bar',
-    }
-    const result = getValueByPath(target, ['foo'])
-
-    expect(result).toEqual({
-      context: '',
-      value: 'bar',
-    })
-  })
-
-  it('should return the value at a nested path', () => {
-    const target = {
-      foo: {
-        bar: {
-          baz: 42,
-        },
-      },
-    }
-    const result = getValueByPath(target, ['foo', 'bar', 'baz'])
-
-    expect(result).toEqual({
-      context: '',
-      value: 42,
-    })
-  })
-
-  it('should return context with $id when found', () => {
-    const target = {
-      foo: {
-        $id: 'https://example.com/schema',
-        bar: {
-          baz: 'value',
-        },
-      },
-    }
-    const result = getValueByPath(target, ['foo', 'bar', 'baz'])
-
-    expect(result).toEqual({
-      context: 'https://example.com/schema',
-      value: 'value',
-    })
-  })
-
-  it('should preserve context from parent when child has no $id', () => {
-    const target = {
-      foo: {
-        $id: 'https://example.com/parent',
-        bar: {
-          baz: 'value',
-        },
-      },
-    }
-    const result = getValueByPath(target, ['foo', 'bar', 'baz'])
-
-    expect(result).toEqual({
-      context: 'https://example.com/parent',
-      value: 'value',
-    })
-  })
-
-  it('should update context when child has $id', () => {
-    const target = {
-      foo: {
-        $id: 'https://example.com/parent',
-        bar: {
-          $id: 'https://example.com/child',
-          baz: 'value',
-        },
-      },
-    }
-    const result = getValueByPath(target, ['foo', 'bar', 'baz'])
-
-    expect(result).toEqual({
-      context: 'https://example.com/child',
-      value: 'value',
-    })
-  })
-
-  it('should return undefined value when path does not exist', () => {
-    const target = {
-      foo: 'bar',
-    }
-    const result = getValueByPath(target, ['nonexistent'])
-
-    expect(result).toEqual({
-      context: '',
-      value: undefined,
-    })
-  })
-
-  it('should return undefined value when path partially exists', () => {
-    const target = {
-      foo: {
-        bar: 'baz',
-      },
-    }
-    const result = getValueByPath(target, ['foo', 'nonexistent'])
-
-    expect(result).toEqual({
-      context: '',
-      value: undefined,
-    })
-  })
-
-  it('should return undefined value when traversing through null', () => {
-    const target = {
-      foo: null,
-    }
-    const result = getValueByPath(target, ['foo', 'bar'])
-
-    expect(result).toEqual({
-      context: '',
-      value: undefined,
-    })
-  })
-
-  it('should return undefined value when traversing through primitive', () => {
-    const target = {
-      foo: 'string',
-    }
-    const result = getValueByPath(target, ['foo', 'bar'])
-
-    expect(result).toEqual({
-      context: '',
-      value: undefined,
-    })
-  })
-
-  it('should handle empty segments array', () => {
-    const target = {
-      foo: 'bar',
-    }
-    const result = getValueByPath(target, [])
-
-    expect(result).toEqual({
-      context: '',
-      value: target,
-    })
-  })
-
-  it('should handle array indices in path', () => {
-    const target = {
-      items: [{ name: 'first' }, { name: 'second' }],
-    }
-    const result = getValueByPath(target, ['items', '0', 'name'])
-
-    expect(result).toEqual({
-      context: '',
-      value: 'first',
-    })
-  })
-
-  it('should handle objects with numeric keys', () => {
-    const target = {
-      '0': 'zero',
-      '1': 'one',
-    }
-    const result = getValueByPath(target, ['0'])
-
-    expect(result).toEqual({
-      context: '',
-      value: 'zero',
-    })
-  })
-
-  it('should handle deeply nested objects', () => {
-    const target = {
-      level1: {
-        level2: {
-          level3: {
-            level4: {
-              level5: {
-                value: 'deep',
-              },
-            },
-          },
-        },
-      },
-    }
-    const result = getValueByPath(target, ['level1', 'level2', 'level3', 'level4', 'level5', 'value'])
-
-    expect(result).toEqual({
-      context: '',
-      value: 'deep',
-    })
-  })
-
-  it('should handle mixed data types in path', () => {
-    const target = {
-      string: 'text',
-      number: 42,
-      boolean: true,
-      null: null,
-      array: [1, 2, 3],
-      object: { nested: 'value' },
-    }
-
-    expect(getValueByPath(target, ['string'])).toEqual({ context: '', value: 'text' })
-    expect(getValueByPath(target, ['number'])).toEqual({ context: '', value: 42 })
-    expect(getValueByPath(target, ['boolean'])).toEqual({ context: '', value: true })
-    expect(getValueByPath(target, ['null'])).toEqual({ context: '', value: null })
-    expect(getValueByPath(target, ['array'])).toEqual({ context: '', value: [1, 2, 3] })
-    expect(getValueByPath(target, ['object', 'nested'])).toEqual({ context: '', value: 'value' })
-  })
-
-  it('should handle $id with different formats', () => {
-    const target = {
-      schema1: {
-        $id: 'https://example.com/schema1',
-        value: 'test1',
-      },
-      schema2: {
-        $id: 'urn:uuid:123e4567-e89b-12d3-a456-426614174000',
-        value: 'test2',
-      },
-      schema3: {
-        $id: 'relative/path',
-        value: 'test3',
-      },
-    }
-
-    expect(getValueByPath(target, ['schema1', 'value'])).toEqual({
-      context: 'https://example.com/schema1',
-      value: 'test1',
-    })
-    expect(getValueByPath(target, ['schema2', 'value'])).toEqual({
-      context: 'urn:uuid:123e4567-e89b-12d3-a456-426614174000',
-      value: 'test2',
-    })
-    expect(getValueByPath(target, ['schema3', 'value'])).toEqual({
-      context: 'relative/path',
-      value: 'test3',
-    })
-  })
-
-  it('should ignore non-string $id values', () => {
-    const target = {
-      schema1: {
-        $id: 123, // number
-        value: 'test1',
-      },
-      schema2: {
-        $id: { nested: 'object' }, // object
-        value: 'test2',
-      },
-      schema3: {
-        $id: null, // null
-        value: 'test3',
-      },
-    }
-
-    expect(getValueByPath(target, ['schema1', 'value'])).toEqual({
-      context: '',
-      value: 'test1',
-    })
-    expect(getValueByPath(target, ['schema2', 'value'])).toEqual({
-      context: '',
-      value: 'test2',
-    })
-    expect(getValueByPath(target, ['schema3', 'value'])).toEqual({
-      context: '',
-      value: 'test3',
-    })
-  })
-
-  it('should handle context inheritance through multiple levels', () => {
-    const target = {
-      root: {
-        $id: 'https://example.com/root',
-        level1: {
-          level2: {
-            $id: 'https://example.com/level2',
-            level3: {
-              level4: {
-                value: 'nested',
-              },
-            },
-          },
-        },
-      },
-    }
-
-    // Should use root context when no intermediate $id
-    expect(getValueByPath(target, ['root', 'level1', 'level2', 'level3', 'level4', 'value'])).toEqual({
-      context: 'https://example.com/level2',
-      value: 'nested',
-    })
-  })
-
-  it('should handle edge case with empty string keys', () => {
-    const target = {
-      '': 'empty key',
-      normal: 'normal key',
-    }
-
-    expect(getValueByPath(target, [''])).toEqual({
-      context: '',
-      value: 'empty key',
-    })
-    expect(getValueByPath(target, ['normal'])).toEqual({
-      context: '',
-      value: 'normal key',
-    })
-  })
-
-  it('should handle special characters in keys', () => {
-    const target = {
-      'key-with-dash': 'dash',
-      'key_with_underscore': 'underscore',
-      'key.with.dots': 'dots',
-      'key with spaces': 'spaces',
-    }
-
-    expect(getValueByPath(target, ['key-with-dash'])).toEqual({
-      context: '',
-      value: 'dash',
-    })
-    expect(getValueByPath(target, ['key_with_underscore'])).toEqual({
-      context: '',
-      value: 'underscore',
-    })
-    expect(getValueByPath(target, ['key.with.dots'])).toEqual({
-      context: '',
-      value: 'dots',
-    })
-    expect(getValueByPath(target, ['key with spaces'])).toEqual({
-      context: '',
-      value: 'spaces',
-    })
-  })
-})

package/src/helpers/get-value-by-path.ts

@@ -1,44 +0,0 @@
-import { getId } from '@/helpers/get-schemas'
-
-/**
- * Traverses an object using an array of string segments (path keys) and returns
- * the value at the specified path along with its context (id if available).
- *
- * @param target - The root object to traverse.
- * @param segments - An array of string keys representing the path to traverse.
- * @returns An object containing the final context (id or previous context) and the value at the path.
- *
- * @example
- * const obj = {
- *   foo: {
- *     bar: {
- *       baz: 42
- *     }
- *   }
- * };
- * // Returns: { context: '', value: 42 }
- * getValueByPath(obj, ['foo', 'bar', 'baz']);
- */
-export function getValueByPath(target: unknown, segments: string[]): { context: string; value: any } {
-  return segments.reduce<{ context: string; value: unknown }>(
-    (acc, key) => {
-      // If the accumulator is undefined, the path does not exist
-      if (acc.value === undefined) {
-        return { context: '', value: undefined }
-      }
-      // If the accumulator is not an object or is null, stop traversal
-      if (typeof acc.value !== 'object' || acc.value === null) {
-        return { context: '', value: undefined }
-      }
-      // Attempt to get the id from the current value for context tracking
-      const id = getId(acc.value)
-
-      // Return the next context and value for the next iteration
-      return { context: id ?? acc.context, value: acc.value?.[key] }
-    },
-    {
-      context: '',
-      value: target,
-    },
-  )
-}

package/src/helpers/is-json-object.ts

@@ -1,31 +0,0 @@
-import { isObject } from '@/helpers/is-object'
-
-/**
- * Determines if a string represents a valid JSON object (i.e., a plain object, not an array, primitive, or null).
- * The function first checks if the string appears to start with an opening curly brace (ignoring leading whitespace),
- * which is a quick heuristic to rule out arrays, primitives, and most invalid JSON. If this check passes,
- * it attempts to parse the string with JSON.parse. The result is then checked to ensure it is a plain object
- * (not an array, null, or primitive) using the isObject utility.
- *
- * @param value - The string to evaluate
- * @returns true if the string is valid JSON and parses to a plain object, false otherwise
- *
- * @example
- * isJsonObject('{"foo": "bar"}') // true
- * isJsonObject('[1,2,3]') // false
- * isJsonObject('not json') // false
- * isJsonObject('42') // false
- */
-export function isJsonObject(value: string) {
-  // Quickly rule out anything that doesn't start with an object brace
-  if (!/^\s*(\{)/.test(value.slice(0, 500))) {
-    return false
-  }
-
-  try {
-    const val = JSON.parse(value)
-    return isObject(val)
-  } catch {
-    return false
-  }
-}

package/src/helpers/is-object.test.ts

@@ -1,27 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { isObject } from './is-object'
-
-describe('isObject', () => {
-  it('returns true for an object', () => {
-    const result = isObject({
-      foo: 'bar',
-    })
-    expect(result).toBe(true)
-  })
-
-  it('returns true for an empty object', () => {
-    const result = isObject({})
-    expect(result).toBe(true)
-  })
-
-  it('returns false for a string', () => {
-    const result = isObject('foo')
-    expect(result).toBe(false)
-  })
-
-  it('returns false for an array', () => {
-    const result = isObject([])
-    expect(result).toBe(false)
-  })
-})

package/src/helpers/is-object.ts

@@ -1,4 +0,0 @@
-/**
- * Check if the given value is an object
- */
-export const isObject = (obj: any): obj is object => typeof obj === 'object' && !Array.isArray(obj) && obj !== null

package/src/helpers/is-yaml.ts

@@ -1,18 +0,0 @@
-/**
- * Checks if a string appears to be YAML content.
- * This function uses a simple heuristic: it looks for a line that starts with an optional dash,
- * followed by a key (alphanumeric or dash), a colon, and a value, and then at least one more line.
- * This is not a full YAML parser, but works for basic detection.
- *
- * @param value - The string to check
- * @returns true if the string looks like YAML, false otherwise
- *
- * @example
- * isYaml('openapi: 3.0.0\ninfo:\n  title: Example') // true
- * isYaml('{"openapi": "3.0.0", "info": {"title": "Example"}}') // false
- * isYaml('- name: value\n- name: value2') // true
- * isYaml('type: object') // false (only one line)
- */
-export function isYaml(value: string): boolean {
-  return /^\s*(?:-\s*)?[\w\-]+\s*:\s*.+\n.*/.test(value)
-}

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

@@ -1,57 +0,0 @@
-import { describe, expect, test } from 'vitest'
-
-import { createPathFromSegments, parseJsonPointer } from './json-path-utils'
-
-describe('parseJsonPointer', () => {
-  test.each([
-    ['#/users/name', ['users', 'name']],
-    ['#/', []],
-    ['', []],
-    ['users/name', ['users', 'name']],
-  ])('should correctly parse json pointers', (a, b) => {
-    expect(parseJsonPointer(a)).toEqual(b)
-  })
-})
-
-describe('createPathFromSegments', () => {
-  test('creates nested objects for non-numeric segments', () => {
-    const obj: any = {}
-    const leaf = createPathFromSegments(obj, ['components', 'schemas', 'User'])
-
-    expect(obj).toEqual({ components: { schemas: { User: {} } } })
-    expect(leaf).toBe(obj.components.schemas.User)
-  })
-
-  test('creates arrays for numeric segments', () => {
-    const obj: any = {}
-    const arr = createPathFromSegments(obj, ['items', '0'])
-
-    expect(Array.isArray(obj.items['0'])).toBe(true)
-    expect(arr).toBe(obj.items['0'])
-  })
-
-  test('does not overwrite existing values along the path', () => {
-    const obj: any = { a: { b: { c: { existing: true } } } }
-    const leaf = createPathFromSegments(obj, ['a', 'b', 'c'])
-
-    expect(leaf).toEqual({ existing: true })
-    expect(obj.a.b.c).toEqual({ existing: true })
-  })
-
-  test('returns root object when segments array is empty', () => {
-    const obj: any = { pre: true }
-    const result = createPathFromSegments(obj, [])
-
-    expect(result).toBe(obj)
-    expect(obj).toEqual({ pre: true })
-  })
-
-  test('creates nested arrays for consecutive numeric segments', () => {
-    const obj: any = {}
-    const leaf = createPathFromSegments(obj, ['arr', '0', '1'])
-
-    expect(Array.isArray(obj.arr['0'])).toBe(true)
-    expect(Array.isArray(obj.arr['0']['1'])).toBe(true)
-    expect(leaf).toBe(obj.arr['0']['1'])
-  })
-})

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

@@ -1,50 +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)
-  )
-}
-
-/**
- * Creates a nested path in an object from an array of path segments.
- * Only creates intermediate objects/arrays if they don't already exist.
- *
- * @param obj - The target object to create the path in
- * @param segments - Array of path segments to create
- * @returns The final nested object/array at the end of the path
- *
- * @example
- * ```ts
- * const obj = {}
- * createPathFromSegments(obj, ['components', 'schemas', 'User'])
- * // Creates: { components: { schemas: { User: {} } } }
- *
- * createPathFromSegments(obj, ['items', '0', 'name'])
- * // Creates: { items: [{ name: {} }] }
- * ```
- */
-export function createPathFromSegments(obj: any, segments: string[]) {
-  return segments.reduce((acc, part) => {
-    if (acc[part] === undefined) {
-      if (isNaN(Number(part))) {
-        acc[part] = {}
-      } else {
-        acc[part] = []
-      }
-    }
-    return acc[part]
-  }, obj)
-}