@scalar/json-magic 0.6.1 → 0.8.0

package/src/bundle/bundle.ts

@@ -1,7 +1,8 @@
+import { path } from '@scalar/helpers/node/path'
+
 import { convertToLocalRef } from '@/helpers/convert-to-local-ref'
 import { getId, getSchemas } from '@/helpers/get-schemas'
 import { getValueByPath } from '@/helpers/get-value-by-path'
-import path from '@/polyfills/path'
 import type { UnknownObject } from '@/types'
 
 import { escapeJsonPointer } from '../helpers/escape-json-pointer'
@@ -65,7 +66,7 @@ export function isLocalRef(value: string): boolean {
   return value.startsWith('#')
 }
 
-export type ResolveResult = { ok: true; data: unknown } | { ok: false }
+export type ResolveResult = { ok: true; data: unknown; raw: string } | { ok: false }
 
 /**
  * Resolves a string by finding and executing the appropriate plugin.
@@ -80,16 +81,16 @@ export type ResolveResult = { ok: true; data: unknown } | { ok: false }
  * // No matching plugin returns { ok: false }
  * await resolveContents('#/components/schemas/User', [urlPlugin, filePlugin])
  */
-async function resolveContents(value: string, plugins: LoaderPlugin[]): Promise<ResolveResult> {
+function resolveContents(value: string, plugins: LoaderPlugin[]): Promise<ResolveResult> {
   const plugin = plugins.find((p) => p.validate(value))
 
   if (plugin) {
     return plugin.exec(value)
   }
 
-  return {
+  return Promise.resolve({
     ok: false,
-  }
+  })
 }
 
 /**

package/src/bundle/plugins/fetch-urls/index.test.ts

@@ -1,9 +1,10 @@
-import { fastify, type FastifyInstance } from 'fastify'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { fetchUrl } from '.'
-import assert from 'node:assert'
 import { setTimeout } from 'node:timers/promises'
 
+import { type FastifyInstance, fastify } from 'fastify'
+import { assert, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { fetchUrl } from '.'
+
 describe('fetchUrl', () => {
   const noLimit = <T>(fn: () => Promise<T>) => fn()
 
@@ -12,11 +13,11 @@ describe('fetchUrl', () => {
 
   beforeEach(() => {
     server = fastify({ logger: false })
-  })
 
-  afterEach(async () => {
-    await server.close()
-    await setTimeout(100)
+    return async () => {
+      await server.close()
+      await setTimeout(100)
+    }
   })
 
   it('reads json response', async () => {
@@ -71,14 +72,14 @@ describe('fetchUrl', () => {
 
   it('send headers to the specified domain', async () => {
     const url = `http://localhost:${PORT}`
-    const fn = vi.fn()
+    const headersSpy = vi.fn()
 
     const response = {
       message: '200OK',
     }
 
     server.get('/', (request, reply) => {
-      fn(request.headers)
+      headersSpy(request.headers)
       reply.send(response)
     })
 
@@ -87,8 +88,8 @@ describe('fetchUrl', () => {
       headers: [{ headers: { 'Authorization': 'Bearer <TOKEN>' }, domains: [`localhost:${PORT}`] }],
     })
 
-    expect(fn).toHaveBeenCalled()
-    expect(fn.mock.calls[0][0]).toEqual({
+    expect(headersSpy).toHaveBeenCalledOnce()
+    expect(headersSpy).toHaveBeenCalledWith({
       'accept': '*/*',
       'accept-encoding': 'gzip, deflate',
       'accept-language': '*',
@@ -102,14 +103,14 @@ describe('fetchUrl', () => {
 
   it('does not send headers to other domains', async () => {
     const url = `http://localhost:${PORT}`
-    const fn = vi.fn()
+    const headersSpy = vi.fn()
 
     const response = {
       message: '200OK',
     }
 
     server.get('/', (request, reply) => {
-      fn(request.headers)
+      headersSpy(request.headers)
       reply.send(response)
     })
 
@@ -118,8 +119,8 @@ describe('fetchUrl', () => {
       headers: [{ headers: { 'Authorization': 'Bearer <TOKEN>' }, domains: ['localhost:9932', 'localhost'] }],
     })
 
-    expect(fn).toHaveBeenCalled()
-    expect(fn.mock.calls[0][0]).toEqual({
+    expect(headersSpy).toHaveBeenCalledOnce()
+    expect(headersSpy).toHaveBeenNthCalledWith(1, {
       'accept': '*/*',
       'accept-encoding': 'gzip, deflate',
       'accept-language': '*',
@@ -131,17 +132,13 @@ describe('fetchUrl', () => {
   })
 
   it('runs custom fetcher', async () => {
-    const fn = vi.fn()
+    const customFetch = vi.fn().mockResolvedValue(new Response('{}', { status: 200 }))
 
     await fetchUrl('https://example.com', (fn) => fn(), {
-      fetch: async (input, init) => {
-        fn(input, init)
-
-        return new Response('{}', { status: 200 })
-      },
+      fetch: customFetch,
     })
 
-    expect(fn).toHaveBeenCalled()
-    expect(fn).toHaveBeenCalledWith('https://example.com', { headers: undefined })
+    expect(customFetch).toHaveBeenCalledOnce()
+    expect(customFetch).toHaveBeenCalledWith('https://example.com', { headers: undefined })
   })
 })

package/src/bundle/plugins/fetch-urls/index.ts

@@ -59,6 +59,7 @@ export async function fetchUrl(
       return {
         ok: true,
         data: normalize(body),
+        raw: body,
       }
     }
 

package/src/bundle/plugins/parse-json/index.test.ts

@@ -1,6 +1,7 @@
-import { parseJson } from '@/bundle/plugins/parse-json'
 import { describe, expect, it } from 'vitest'
 
+import { parseJson } from '@/bundle/plugins/parse-json'
+
 describe('parse-json', () => {
   it.each([
     ['{}', true],
@@ -17,6 +18,7 @@ describe('parse-json', () => {
     expect(await parseJson().exec('{ "message": "Hello World" }')).toEqual({
       ok: true,
       data: { message: 'Hello World' },
+      'raw': '{ "message": "Hello World" }',
     })
   })
 })

package/src/bundle/plugins/parse-json/index.ts

@@ -1,4 +1,4 @@
-import type { LoaderPlugin, ResolveResult } from '@/bundle'
+import type { LoaderPlugin } from '@/bundle'
 import { isJsonObject } from '@/helpers/is-json-object'
 
 /**
@@ -15,16 +15,17 @@ export function parseJson(): LoaderPlugin {
   return {
     type: 'loader',
     validate: isJsonObject,
-    exec: async (value): Promise<ResolveResult> => {
+    exec: (value) => {
       try {
-        return {
+        return Promise.resolve({
           ok: true,
           data: JSON.parse(value),
-        }
+          raw: value,
+        })
       } catch {
-        return {
+        return Promise.resolve({
           ok: false,
-        }
+        })
       }
     },
   }

package/src/bundle/plugins/parse-yaml/index.test.ts

@@ -1,6 +1,7 @@
-import { parseYaml } from '@/bundle/plugins/parse-yaml'
 import { describe, expect, it } from 'vitest'
 
+import { parseYaml } from '@/bundle/plugins/parse-yaml'
+
 describe('parse-yaml', () => {
   it.each([
     ['hi: hello\n', true],
@@ -19,6 +20,7 @@ describe('parse-yaml', () => {
     expect(await parseYaml().exec('{ "message": "Hello World" }')).toEqual({
       ok: true,
       data: { message: 'Hello World' },
+      'raw': '{ "message": "Hello World" }',
     })
   })
 })

package/src/bundle/plugins/parse-yaml/index.ts

@@ -1,6 +1,6 @@
 import YAML from 'yaml'
 
-import type { LoaderPlugin, ResolveResult } from '@/bundle'
+import type { LoaderPlugin } from '@/bundle'
 import { isYaml } from '@/helpers/is-yaml'
 
 /**
@@ -17,16 +17,17 @@ export function parseYaml(): LoaderPlugin {
   return {
     type: 'loader',
     validate: isYaml,
-    exec: async (value): Promise<ResolveResult> => {
+    exec: (value) => {
       try {
-        return {
+        return Promise.resolve({
           ok: true,
           data: YAML.parse(value, { merge: true, maxAliasCount: 10000 }),
-        }
+          raw: value,
+        })
       } catch {
-        return {
+        return Promise.resolve({
           ok: false,
-        }
+        })
       }
     },
   }

package/src/bundle/plugins/read-files/index.test.ts

@@ -1,8 +1,9 @@
-import fs from 'node:fs/promises'
 import { randomUUID } from 'node:crypto'
-import { describe, expect, it } from 'vitest'
+import fs from 'node:fs/promises'
+
+import { assert, describe, expect, it } from 'vitest'
+
 import { readFile } from '.'
-import assert from 'node:assert'
 
 describe('readFile', () => {
   it('reads json contents of a file', async () => {

package/src/bundle/plugins/read-files/index.ts

@@ -29,6 +29,7 @@ export async function readFile(path: string): Promise<ResolveResult> {
     return {
       ok: true,
       data: normalize(fileContents),
+      raw: fileContents,
     }
   } catch {
     return {

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

@@ -1,9 +1,10 @@
-import { generateUniqueValue, uniqueValueGeneratorFactory } from './value-generator'
 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 = async (value: string) => {
+    const hashFunction = (value: string) => {
       if (value === 'a') {
         return 'a'
       }
@@ -16,7 +17,7 @@ describe('generateUniqueHash', () => {
   })
 
   it('should return same value for the same input', async () => {
-    const hashFunction = async (value: string) => {
+    const hashFunction = (value: string) => {
       if (value === 'a') {
         return value
       }
@@ -33,7 +34,7 @@ describe('generateUniqueHash', () => {
   })
 
   it('should handle hash collisions', async () => {
-    const hashFunction = async (value: string) => {
+    const hashFunction = (value: string) => {
       // Hash a, b and c will produce collisions
       if (value === 'a' || value === 'b' || value === 'c') {
         return 'd'
@@ -83,9 +84,7 @@ describe('generateUniqueHash', () => {
   })
 
   it('should throw when it reaches max depth', async () => {
-    const hashFunction = async () => {
-      return 'a'
-    }
+    const hashFunction = () => 'a'
 
     const map = {}
     const result1 = await generateUniqueValue(hashFunction, 'a', map)
@@ -94,7 +93,7 @@ describe('generateUniqueHash', () => {
     const result2 = await generateUniqueValue(hashFunction, 'a', map)
     expect(result2).toBe('a')
 
-    expect(() => generateUniqueValue(hashFunction, 'b', map)).rejects.toThrowError()
+    await expect(() => generateUniqueValue(hashFunction, 'b', map)).rejects.toThrowError()
   })
 })
 

package/src/bundle/value-generator.ts

@@ -1,27 +1,23 @@
+import { generateHash } from '@/helpers/generate-hash'
+
 /**
- * Generates a short SHA-1 hash from a string value.
+ * 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 the Web Crypto API to
- * generate a SHA-1 hash and returns the first 7 characters of the hex string.
+ * 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 7-character hexadecimal hash with at least one letter
+ * @returns A Promise that resolves to 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('')
+export async function getHash(value: string): Promise<string> {
+  // Hash the data using xxhash
+  const hashHex = await generateHash(value)
 
   // Return first 7 characters of the hash, ensuring at least one letter
   const hash = hashHex.substring(0, 7)

package/src/dereference/dereference.test.ts

@@ -1,11 +1,13 @@
-import { dereference } from '@/dereference/dereference'
-import { fastify, type FastifyInstance } from 'fastify'
 import { setTimeout } from 'node:timers/promises'
+
+import { type FastifyInstance, fastify } from 'fastify'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 
+import { dereference } from '@/dereference/dereference'
+
 describe('dereference', () => {
   describe('sync', () => {
-    it('should dereference JSON pointers', async () => {
+    it('should dereference JSON pointers', () => {
       const data = {
         users: {
           name: 'John Doe',
@@ -82,9 +84,7 @@ describe('dereference', () => {
           street: 'Sunset Boulevard',
         },
       }
-      server.get('/users', async () => {
-        return userProfile
-      })
+      server.get('/users', () => userProfile)
 
       await server.listen({ port: port })
 
@@ -101,7 +101,7 @@ describe('dereference', () => {
         success: true,
         data: {
           profile: {
-            '$ref': '#/x-ext/5bd1cdd',
+            '$ref': '#/x-ext/f87db7e',
             '$ref-value': {
               name: 'Jane Doe',
               age: 25,
@@ -112,17 +112,17 @@ describe('dereference', () => {
             },
           },
           address: {
-            '$ref': '#/x-ext/5bd1cdd/address',
+            '$ref': '#/x-ext/f87db7e/address',
             '$ref-value': {
               city: 'Los Angeles',
               street: 'Sunset Boulevard',
             },
           },
           'x-ext': {
-            '5bd1cdd': userProfile,
+            'f87db7e': userProfile,
           },
           'x-ext-urls': {
-            '5bd1cdd': `${url}/users`,
+            'f87db7e': `${url}/users`,
           },
         },
       })

package/src/diff/diff.ts

@@ -76,7 +76,6 @@ export const diff = <T extends Record<string, unknown>>(doc1: Record<string, unk
       const keys = new Set([...Object.keys(el1), ...Object.keys(el2)])
 
       for (const key of keys) {
-        // @ts-ignore
         bfs(el1[key], el2[key], [...prefix, key])
       }
       return

package/src/diff/utils.test.ts

@@ -148,7 +148,7 @@ describe('isArrayEqual', () => {
       [1, 2, 3],
       [1, 2, 3],
     ],
-    // @ts-ignore
+    // @ts-expect-error
   ])('should return true', (a, b) => expect(isArrayEqual(a, b)).toEqual(true))
 
   test.each([
@@ -164,6 +164,6 @@ describe('isArrayEqual', () => {
       [2, 2, 4],
       [1, 2, 3],
     ],
-    // @ts-ignore
+    // @ts-expect-error
   ])('should return false', (a, b) => expect(isArrayEqual(a, b)).toEqual(false))
 })

package/src/diff/utils.ts

@@ -28,9 +28,7 @@ export const isKeyCollisions = (a: unknown, b: unknown) => {
     const keys = new Set([...Object.keys(a), ...Object.keys(b)])
 
     for (const key of keys) {
-      // @ts-ignore
       if (a[key] !== undefined && b[key] !== undefined) {
-        // @ts-ignore
         if (isKeyCollisions(a[key], b[key])) {
           return true
         }

package/src/helpers/escape-json-pointer.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 
 import { escapeJsonPointer } from './escape-json-pointer'
 
-describe('escapeJsonPointer', async () => {
+describe('escapeJsonPointer', () => {
   it('should escape a slash', () => {
     expect(escapeJsonPointer('application/json')).toBe('application~1json')
   })

package/src/helpers/generate-hash.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest'
+
+import { generateHash } from './generate-hash'
+
+describe('generateHash', () => {
+  it('generates a hash from a simple string', async () => {
+    const result = await generateHash('hello world')
+
+    // Should return a non-empty string
+    expect(result).toBeTruthy()
+    expect(typeof result).toBe('string')
+    expect(result.length).toBeGreaterThan(0)
+  })
+
+  it('produces consistent hashes for the same input', async () => {
+    const input = 'consistent-test-string'
+    const hash1 = await generateHash(input)
+    const hash2 = await generateHash(input)
+    const hash3 = await generateHash(input)
+
+    // Same input should always produce the same hash
+    expect(hash1).toBe(hash2)
+    expect(hash2).toBe(hash3)
+  })
+
+  it('produces different hashes for different inputs', async () => {
+    const hash1 = await generateHash('first string')
+    const hash2 = await generateHash('second string')
+    const hash3 = await generateHash('first strinG') // Case-sensitive
+
+    // Different inputs should produce different hashes
+    expect(hash1).not.toBe(hash2)
+    expect(hash1).not.toBe(hash3)
+    expect(hash2).not.toBe(hash3)
+  })
+
+  it('handles empty string', async () => {
+    const result = await generateHash('')
+
+    // Should handle empty strings without throwing
+    expect(result).toBeTruthy()
+    expect(typeof result).toBe('string')
+
+    // Empty string should produce a consistent hash
+    const result2 = await generateHash('')
+    expect(result).toBe(result2)
+  })
+
+  it('handles special characters and unicode', async () => {
+    const inputs = [
+      '🚀 emoji test',
+      'special chars: !@#$%^&*()',
+      'unicode: こんにちは世界',
+      'newlines\nand\ttabs',
+      'mixed: 👾 special!@# unicode: 你好',
+    ]
+
+    const hashes = await Promise.all(inputs.map((input) => generateHash(input)))
+
+    // All should produce valid hashes
+    hashes.forEach((hash) => {
+      expect(hash).toBeTruthy()
+      expect(typeof hash).toBe('string')
+    })
+
+    // All should be unique
+    const uniqueHashes = new Set(hashes)
+    expect(uniqueHashes.size).toBe(inputs.length)
+
+    // Should be consistent on repeated calls
+    const repeatedHash = await generateHash('🚀 emoji test')
+    expect(repeatedHash).toBe(hashes[0])
+  })
+})

package/src/helpers/generate-hash.ts

@@ -0,0 +1,29 @@
+import xxhash from 'xxhash-wasm'
+
+let hasherInstance: Awaited<ReturnType<typeof xxhash>> | null = null
+
+/**
+ * Initialize the xxhash hasher instance lazily
+ *
+ * This is just a workaround because we cannot use top level await in a UMD module (standalone references)
+ */
+const getHasher = async () => {
+  if (!hasherInstance) {
+    hasherInstance = await xxhash()
+  }
+  return hasherInstance
+}
+
+/**
+ * Generate a hash from a string using the xxhash algorithm
+ *
+ * We cannot use crypto.subtle because it is only available in secure contexts (HTTPS) or on localhost.
+ * So this is just a wrapper around the xxhash-wasm library instead.
+ *
+ * @param input - The string to hash
+ * @returns A Promise that resolves to the hash of the input string
+ */
+export const generateHash = async (input: string): Promise<string> => {
+  const { h64ToString } = await getHasher()
+  return h64ToString(input)
+}

package/src/helpers/unescape-json-pointer.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 
 import { unescapeJsonPointer } from './unescape-json-pointer'
 
-describe('unescapeJsonPointer', async () => {
+describe('unescapeJsonPointer', () => {
   it('unescapes a slash', () => {
     expect(unescapeJsonPointer('/foo~1bar~1baz')).toBe('/foo/bar/baz')
   })

package/src/magic-proxy/proxy.ts

@@ -140,6 +140,10 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
 
         // Resolve the reference and create a new magic proxy
         const resolvedValue = getValueByPath(args.root, parseJsonPointer(`#/${path}`))
+        // Return early if the value is already a magic proxy
+        if (isMagicProxyObject(resolvedValue.value)) {
+          return resolvedValue.value
+        }
         const proxiedValue = createMagicProxy(resolvedValue.value, options, {
           ...args,
           currentContext: resolvedValue.context,
@@ -152,6 +156,12 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
 
       // For all other properties, recursively wrap the value in a magic proxy
       const value = Reflect.get(target, prop, receiver)
+
+      // Return early if the value is already a magic proxy
+      if (isMagicProxyObject(value)) {
+        return value
+      }
+
       return createMagicProxy(value as T, options, { ...args, currentContext: id ?? args.currentContext })
     },
     /**
@@ -286,6 +296,10 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
   return proxied
 }
 
+export const isMagicProxyObject = (obj: unknown): boolean => {
+  return typeof obj === 'object' && obj !== null && (obj as { [isMagicProxy]: boolean })[isMagicProxy] === true
+}
+
 /**
  * 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.

package/dist/polyfills/index.d.ts

@@ -1,2 +0,0 @@
-export { resolve, normalize, isAbsolute, join, relative, sep, delimiter, dirname, basename, extname, } from './path.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/polyfills/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/polyfills/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,SAAS,EACT,UAAU,EACV,IAAI,EACJ,QAAQ,EACR,GAAG,EACH,SAAS,EACT,OAAO,EACP,QAAQ,EACR,OAAO,GACR,MAAM,QAAQ,CAAA"}

package/dist/polyfills/index.js

@@ -1,25 +0,0 @@
-import {
-  resolve,
-  normalize,
-  isAbsolute,
-  join,
-  relative,
-  sep,
-  delimiter,
-  dirname,
-  basename,
-  extname
-} from "./path.js";
-export {
-  basename,
-  delimiter,
-  dirname,
-  extname,
-  isAbsolute,
-  join,
-  normalize,
-  relative,
-  resolve,
-  sep
-};
-//# sourceMappingURL=index.js.map

package/dist/polyfills/index.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../src/polyfills/index.ts"],
-  "sourcesContent": ["export {\n  resolve,\n  normalize,\n  isAbsolute,\n  join,\n  relative,\n  sep,\n  delimiter,\n  dirname,\n  basename,\n  extname,\n} from './path'\n"],
-  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;",
-  "names": []
-}