@scalar/json-magic 0.8.2 → 0.8.3

package/src/bundle/value-generator.test.ts

@@ -1,165 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { generateUniqueValue, uniqueValueGeneratorFactory } from './value-generator'
-
-describe('generateUniqueHash', () => {
-  it('should generate hash values from the function we pass in', async () => {
-    const hashFunction = (value: string) => {
-      if (value === 'a') {
-        return 'a'
-      }
-      throw 'Ops'
-    }
-
-    const result = await generateUniqueValue(hashFunction, 'a', {})
-
-    expect(result).toBe('a')
-  })
-
-  it('should return same value for the same input', async () => {
-    const hashFunction = (value: string) => {
-      if (value === 'a') {
-        return value
-      }
-      throw 'Ops'
-    }
-
-    const map = {}
-
-    const result1 = await generateUniqueValue(hashFunction, 'a', map)
-    expect(result1).toBe('a')
-
-    const result2 = await generateUniqueValue(hashFunction, 'a', map)
-    expect(result2).toBe('a')
-  })
-
-  it('should handle hash collisions', async () => {
-    const hashFunction = (value: string) => {
-      // Hash a, b and c will produce collisions
-      if (value === 'a' || value === 'b' || value === 'c') {
-        return 'd'
-      }
-
-      // Hashing the hashed result
-      if (value === 'd') {
-        return 'e'
-      }
-
-      if (value === 'e') {
-        return 'f'
-      }
-
-      if (value === 'f') {
-        return 'g'
-      }
-
-      if (value === 'g') {
-        return 'h'
-      }
-
-      throw 'Ops'
-    }
-
-    const map = {}
-
-    const res1 = await generateUniqueValue(hashFunction, 'd', map)
-    expect(res1).toBe('e')
-
-    const res2 = await generateUniqueValue(hashFunction, 'b', map)
-    expect(res2).toBe('d')
-
-    // Takes the first available spot
-    const res3 = await generateUniqueValue(hashFunction, 'a', map)
-    expect(res3).toBe('f')
-
-    // Produces the same output for the same input
-    const res4 = await generateUniqueValue(hashFunction, 'a', map)
-    expect(res4).toBe('f')
-
-    const res5 = await generateUniqueValue(hashFunction, 'c', map)
-    expect(res5).toBe('g')
-
-    const res6 = await generateUniqueValue(hashFunction, 'g', map)
-    expect(res6).toBe('h')
-  })
-
-  it('should throw when it reaches max depth', async () => {
-    const hashFunction = () => 'a'
-
-    const map = {}
-    const result1 = await generateUniqueValue(hashFunction, 'a', map)
-    expect(result1).toBe('a')
-
-    const result2 = await generateUniqueValue(hashFunction, 'a', map)
-    expect(result2).toBe('a')
-
-    await expect(() => generateUniqueValue(hashFunction, 'b', map)).rejects.toThrowError()
-  })
-})
-
-describe('uniqueValueGeneratorFactory', () => {
-  it('should generate unique values while caching the previously generated values', async () => {
-    let calls = 0
-    const compress = (value: string) => {
-      // Ensure we return the same value only once for the input 'b'
-      if (value === 'b' && calls === 0) {
-        calls++
-        return 'another-value'
-      }
-      calls++
-      return 'should not be returned'
-    }
-    const { generate } = uniqueValueGeneratorFactory(compress, {
-      'b': 'a',
-    })
-
-    // Should use the value from the cache
-    expect(await generate('a')).toBe('b')
-
-    // should use the generator function to generate a unique value
-    expect(await generate('b')).toBe('another-value')
-
-    // should generate the same value when we call generate with the same input
-    expect(await generate('b')).toBe('another-value')
-  })
-
-  it('should handle conflicts', async () => {
-    const compress = (value: string) => {
-      if (value === 'a') {
-        return 'c'
-      }
-
-      if (value === 'b') {
-        return 'c'
-      }
-
-      if (value === 'c') {
-        return 'd'
-      }
-      return 'should not be returned'
-    }
-    const { generate } = uniqueValueGeneratorFactory(compress, {})
-
-    expect(await generate('a')).toBe('c')
-    expect(await generate('b')).toBe('d')
-  })
-
-  it('should handle numeric strings by prefixing them with letters', async () => {
-    const compress = (value: string) => {
-      if (!value) {
-        return '92819102'
-      }
-      return 'radom value'
-    }
-
-    const { generate } = uniqueValueGeneratorFactory(compress, {})
-
-    // Prefix with a letter
-    expect(await generate('')).toBe('a92819102')
-
-    // Should return the same value for same input
-    expect(await generate('')).toBe('a92819102')
-
-    expect(await generate('abc')).toBe('radom value')
-  })
-})

package/src/bundle/value-generator.ts

@@ -1,143 +0,0 @@
-import { generateHash } from '@scalar/helpers/string/generate-hash'
-
-/**
- * Generates a short hash from a string value using xxhash.
- *
- * This function is used to create unique identifiers for external references
- * while keeping the hash length manageable. It uses xxhash-wasm instead of
- * crypto.subtle because crypto.subtle is only available in secure contexts (HTTPS) or on localhost.
- * Returns the first 7 characters of the hash string.
- * If the hash would be all numbers, it ensures at least one letter is included.
- *
- * @param value - The string to hash
- * @returns A Promise that resolves to a 7-character hexadecimal hash with at least one letter
- * @example
- * // Returns "2ae91d7"
- * getHash("https://example.com/schema.json")
- */
-export function getHash(value: string): string {
-  // Hash the data using xxhash
-  const hashHex = generateHash(value)
-
-  // Return first 7 characters of the hash, ensuring at least one letter
-  const hash = hashHex.substring(0, 7)
-  return hash.match(/^\d+$/) ? 'a' + hash.substring(1) : hash
-}
-
-/**
- * Generates a unique compressed value for a string, handling collisions by recursively compressing
- * until a unique value is found. This is used to create unique identifiers for external
- * references in the bundled OpenAPI document.
- *
- * @param compress - Function that generates a compressed value from a string
- * @param value - The original string value to compress
- * @param compressedToValue - Object mapping compressed values to their original values
- * @param prevCompressedValue - Optional previous compressed value to use as input for generating a new value
- * @param depth - Current recursion depth to prevent infinite loops
- * @returns A unique compressed value that doesn't conflict with existing values
- *
- * @example
- * const valueMap = {}
- * // First call generates compressed value for "example.com/schema.json"
- * const value1 = await generateUniqueValue(compress, "example.com/schema.json", valueMap)
- * // Returns something like "2ae91d7"
- *
- * // Second call with same value returns same compressed value
- * const value2 = await generateUniqueValue(compress, "example.com/schema.json", valueMap)
- * // Returns same value as value1
- *
- * // Call with different value generates new unique compressed value
- * const value3 = await generateUniqueValue(compress, "example.com/other.json", valueMap)
- * // Returns different value like "3bf82e9"
- */
-export async function generateUniqueValue(
-  compress: (value: string) => Promise<string> | string,
-  value: string,
-  compressedToValue: Record<string, string>,
-  prevCompressedValue?: string,
-  depth = 0,
-) {
-  // Prevent infinite recursion by limiting depth
-  const MAX_DEPTH = 100
-
-  if (depth >= MAX_DEPTH) {
-    throw 'Can not generate unique compressed values'
-  }
-
-  // Compress the value, using previous compressed value if provided
-  const compressedValue = await compress(prevCompressedValue ?? value)
-
-  // Handle collision by recursively trying with compressed value as input
-  if (compressedToValue[compressedValue] !== undefined && compressedToValue[compressedValue] !== value) {
-    return generateUniqueValue(compress, value, compressedToValue, compressedValue, depth + 1)
-  }
-
-  // Store mapping and return unique compressed value
-  compressedToValue[compressedValue] = value
-  return compressedValue
-}
-
-/**
- * Factory function that creates a value generator with caching capabilities.
- * The generator maintains a bidirectional mapping between original values and their compressed forms.
- *
- * @param compress - Function that generates a compressed value from a string
- * @param compressedToValue - Initial mapping of compressed values to their original values
- * @returns An object with a generate method that produces unique compressed values
- *
- * @example
- * const compress = (value) => value.substring(0, 6) // Simple compression example
- * const initialMap = { 'abc123': 'example.com/schema.json' }
- * const generator = uniqueValueGeneratorFactory(compress, initialMap)
- *
- * // Generate compressed value for new string
- * const compressed = await generator.generate('example.com/other.json')
- * // Returns something like 'example'
- *
- * // Generate compressed value for existing string
- * const cached = await generator.generate('example.com/schema.json')
- * // Returns 'abc123' from cache
- */
-export const uniqueValueGeneratorFactory = (
-  compress: (value: string) => Promise<string> | string,
-  compressedToValue: Record<string, string>,
-) => {
-  // Create a reverse mapping from original values to their compressed forms
-  const valueToCompressed = Object.fromEntries(Object.entries(compressedToValue).map(([key, value]) => [value, key]))
-
-  return {
-    /**
-     * Generates a unique compressed value for the given input string.
-     * First checks if a compressed value already exists in the cache.
-     * If not, generates a new unique compressed value and stores it in the cache.
-     *
-     * @param value - The original string value to compress
-     * @returns A Promise that resolves to the compressed string value
-     *
-     * @example
-     * const generator = uniqueValueGeneratorFactory(compress, {})
-     * const compressed = await generator.generate('example.com/schema.json')
-     * // Returns a unique compressed value like 'example'
-     */
-    generate: async (value: string) => {
-      // Check if we already have a compressed value for this input
-      const cache = valueToCompressed[value]
-      if (cache) {
-        return cache
-      }
-
-      // Generate a new unique compressed value
-      const generatedValue = await generateUniqueValue(compress, value, compressedToValue)
-
-      // Ensure the generated string contains at least one non-numeric character
-      // This prevents the `setValueAtPath` function from interpreting the value as an array index
-      // by forcing it to be treated as an object property name
-      const compressedValue = generatedValue.match(/^\d+$/) ? `a${generatedValue}` : generatedValue
-
-      // Store the new mapping in our cache
-      valueToCompressed[value] = compressedValue
-
-      return compressedValue
-    },
-  }
-}

package/src/dereference/dereference.test.ts

@@ -1,142 +0,0 @@
-import { type FastifyInstance, fastify } from 'fastify'
-import { beforeEach, describe, expect, it } from 'vitest'
-
-import { dereference } from '@/dereference/dereference'
-
-describe('dereference', () => {
-  describe('sync', () => {
-    it('should dereference JSON pointers', () => {
-      const data = {
-        users: {
-          name: 'John Doe',
-          age: 30,
-          address: {
-            city: 'New York',
-            street: '5th Avenue',
-          },
-        },
-        profile: {
-          $ref: '#/users',
-        },
-        address: {
-          $ref: '#/users/address',
-        },
-      }
-
-      const result = dereference(data, { sync: true })
-
-      expect(result).toEqual({
-        success: true,
-        data: {
-          users: {
-            name: 'John Doe',
-            age: 30,
-            address: {
-              city: 'New York',
-              street: '5th Avenue',
-            },
-          },
-          profile: {
-            '$ref': '#/users',
-            '$ref-value': {
-              name: 'John Doe',
-              age: 30,
-              address: {
-                city: 'New York',
-                street: '5th Avenue',
-              },
-            },
-          },
-          address: {
-            '$ref': '#/users/address',
-            '$ref-value': {
-              city: 'New York',
-              street: '5th Avenue',
-            },
-          },
-        },
-      })
-    })
-  })
-
-  describe('async', () => {
-    let server: FastifyInstance
-    const port = 7299
-    const url = `http://localhost:${port}`
-
-    beforeEach(() => {
-      server = fastify({ logger: false })
-
-      return async () => {
-        await server.close()
-      }
-    })
-
-    it('should dereference JSON pointers asynchronously', async () => {
-      const userProfile = {
-        name: 'Jane Doe',
-        age: 25,
-        address: {
-          city: 'Los Angeles',
-          street: 'Sunset Boulevard',
-        },
-      }
-      server.get('/users', () => userProfile)
-
-      await server.listen({ port: port })
-
-      const data = {
-        profile: {
-          $ref: `${url}/users#`,
-        },
-        address: {
-          $ref: `${url}/users#/address`,
-        },
-      }
-      const result = await dereference(data, { sync: false })
-      expect(result).toEqual({
-        success: true,
-        data: {
-          profile: {
-            '$ref': '#/x-ext/f053c6d',
-            '$ref-value': {
-              name: 'Jane Doe',
-              age: 25,
-              address: {
-                city: 'Los Angeles',
-                street: 'Sunset Boulevard',
-              },
-            },
-          },
-          address: {
-            '$ref': '#/x-ext/f053c6d/address',
-            '$ref-value': {
-              city: 'Los Angeles',
-              street: 'Sunset Boulevard',
-            },
-          },
-          'x-ext': {
-            'f053c6d': userProfile,
-          },
-          'x-ext-urls': {
-            'f053c6d': `${url}/users`,
-          },
-        },
-      })
-    })
-
-    it('should handle errors when dereferencing remote refs', async () => {
-      const data = {
-        profile: {
-          $ref: `${url}/nonexistent`,
-        },
-      }
-
-      const result = await dereference(data, { sync: false })
-      expect(result).toEqual({
-        success: false,
-        errors: [`Failed to resolve ${url}/nonexistent`],
-      })
-    })
-  })
-})

package/src/dereference/dereference.ts

@@ -1,84 +0,0 @@
-import { bundle } from '@/bundle'
-import { fetchUrls } from '@/bundle/plugins/fetch-urls'
-import { createMagicProxy } from '@/magic-proxy'
-import type { UnknownObject } from '@/types'
-
-type DereferenceResult =
-  | {
-      success: true
-      data: UnknownObject
-    }
-  | {
-      success: false
-      errors: string[]
-    }
-
-type ReturnDereferenceResult<Opt extends { sync?: boolean }> = Opt['sync'] extends true
-  ? DereferenceResult
-  : Promise<DereferenceResult>
-
-/**
- * Dereferences a JSON object, resolving all $ref pointers.
- *
- * This function can operate synchronously (no remote refs, no async plugins) or asynchronously (with remote refs).
- * If `options.sync` is true, it simply wraps the input in a magic proxy and returns it.
- * Otherwise, it bundles the document, resolving all $refs (including remote ones), and returns a promise.
- *
- * @param input - JSON Schema object to dereference.
- * @param options - Optional settings. If `sync` is true, dereferencing is synchronous.
- * @returns A DereferenceResult (or Promise thereof) indicating success and the dereferenced data, or errors.
- *
- * @example
- * // Synchronous dereference (no remote refs)
- * const result = dereference({ openapi: '3.0.0', info: { title: 'My API', version: '1.0.0' } }, { sync: true });
- * if (result.success) {
- *   console.log(result.data); // Magic proxy-wrapped document
- * }
- *
- * @example
- * // Asynchronous dereference (with remote refs)
- * dereference({ $ref: 'https://example.com/api.yaml' })
- *   .then(result => {
- *     if (result.success) {
- *       console.log(result.data); // Fully dereferenced document
- *     } else {
- *       console.error(result.errors);
- *     }
- *   });
- */
-export const dereference = <Opts extends { sync?: boolean }>(
-  input: UnknownObject,
-  options?: Opts,
-): ReturnDereferenceResult<Opts> => {
-  if (options?.sync) {
-    return {
-      success: true,
-      data: createMagicProxy(input),
-    } as ReturnDereferenceResult<Opts>
-  }
-
-  const errors: string[] = []
-
-  return bundle(input, {
-    plugins: [fetchUrls()],
-    treeShake: false,
-    urlMap: true,
-    hooks: {
-      onResolveError(node) {
-        errors.push(`Failed to resolve ${node.$ref}`)
-      },
-    },
-  }).then((result) => {
-    if (errors.length > 0) {
-      return {
-        success: false,
-        errors,
-      }
-    }
-
-    return {
-      success: true,
-      data: createMagicProxy(result as UnknownObject),
-    }
-  }) as ReturnDereferenceResult<Opts>
-}

package/src/dereference/index.ts

@@ -1,2 +0,0 @@
-// biome-ignore lint/performance/noBarrelFile: <explanation>
-export { dereference } from './dereference'