@scalar/json-magic 0.1.0

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

@@ -0,0 +1,166 @@
+import { generateUniqueValue, uniqueValueGeneratorFactory } from './value-generator'
+import { describe, expect, it } from 'vitest'
+
+describe('generateUniqueHash', () => {
+  it('should generate hash values from the function we pass in', async () => {
+    const hashFunction = async (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 = async (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 = async (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 = async () => {
+      return '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')
+
+    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

@@ -0,0 +1,147 @@
+/**
+ * Generates a short SHA-1 hash from a string value.
+ * This function is used to create unique identifiers for external references
+ * while keeping the hash length manageable. It uses the Web Crypto API to
+ * generate a SHA-1 hash and returns the first 7 characters of the hex string.
+ * If the hash would be all numbers, it ensures at least one letter is included.
+ *
+ * @param value - The string to hash
+ * @returns A 7-character hexadecimal hash with at least one letter
+ * @example
+ * // Returns "2ae91d7"
+ * await getHash("https://example.com/schema.json")
+ */
+export async function getHash(value: string) {
+  // Convert string to ArrayBuffer
+  const encoder = new TextEncoder()
+  const data = encoder.encode(value)
+
+  // Hash the data
+  const hashBuffer = await crypto.subtle.digest('SHA-1', data)
+
+  // Convert buffer to hex string
+  const hashArray = Array.from(new Uint8Array(hashBuffer))
+  const hashHex = hashArray.map((b) => b.toString(16).padStart(2, '0')).join('')
+
+  // 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

@@ -0,0 +1,137 @@
+import { dereference } from '@/dereference/dereference'
+import { fastify, type FastifyInstance } from 'fastify'
+import { setTimeout } from 'node:timers/promises'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+describe('dereference', () => {
+  describe('sync', () => {
+    it('should dereference JSON pointers', async () => {
+      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: {
+            'x-original-ref': '#/users',
+            name: 'John Doe',
+            age: 30,
+            address: {
+              city: 'New York',
+              street: '5th Avenue',
+            },
+          },
+          address: {
+            'x-original-ref': '#/users/address',
+            city: 'New York',
+            street: '5th Avenue',
+          },
+        },
+      })
+    })
+  })
+
+  describe('async', () => {
+    let server: FastifyInstance
+    const port = 7299
+    const url = `http://localhost:${port}`
+
+    beforeEach(() => {
+      server = fastify({ logger: false })
+    })
+
+    afterEach(async () => {
+      await server.close()
+      await setTimeout(100)
+    })
+
+    it('should dereference JSON pointers asynchronously', async () => {
+      const userProfile = {
+        name: 'Jane Doe',
+        age: 25,
+        address: {
+          city: 'Los Angeles',
+          street: 'Sunset Boulevard',
+        },
+      }
+      server.get('/users', async () => {
+        return 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: {
+            'x-original-ref': '#/x-ext/5bd1cdd',
+            name: 'Jane Doe',
+            age: 25,
+            address: {
+              city: 'Los Angeles',
+              street: 'Sunset Boulevard',
+            },
+          },
+          address: {
+            'x-original-ref': '#/x-ext/5bd1cdd/address',
+            city: 'Los Angeles',
+            street: 'Sunset Boulevard',
+          },
+          'x-ext': {
+            '5bd1cdd': userProfile,
+          },
+          'x-ext-urls': {
+            '5bd1cdd': `${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

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

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