@scalar/json-magic 0.1.0

package/src/bundle/create-limiter.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { createLimiter } from './create-limiter'
+
+describe('createLimiter', { timeout: 10000 }, () => {
+  const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+  it('run in order and no more than the specified number of concurrent requests', async () => {
+    const limiter = createLimiter(2)
+
+    let active = 0
+    const maxObserved: number[] = []
+
+    const makeTask = (id: number) =>
+      limiter(async () => {
+        active++
+        maxObserved.push(active)
+        await sleep(100)
+        active--
+        return id
+      })
+
+    const tasks = [1, 2, 3, 4, 5].map(makeTask)
+    const results = await Promise.all(tasks)
+
+    expect(results).toEqual([1, 2, 3, 4, 5])
+    expect(Math.max(...maxObserved)).toBeLessThanOrEqual(2)
+  })
+})

package/src/bundle/create-limiter.ts

@@ -0,0 +1,52 @@
+/**
+ * Creates a function that limits the number of concurrent executions of async functions.
+ *
+ * @param maxConcurrent - Maximum number of concurrent executions allowed
+ * @returns A function that wraps async functions to limit their concurrent execution
+ *
+ * @example
+ * ```ts
+ * const limiter = createLimiter(2) // Allow max 2 concurrent executions
+ *
+ * // These will run with max 2 at a time
+ * const results = await Promise.all([
+ *   limiter(() => fetch('/api/1')),
+ *   limiter(() => fetch('/api/2')),
+ *   limiter(() => fetch('/api/3')),
+ *   limiter(() => fetch('/api/4'))
+ * ])
+ * ```
+ */
+export function createLimiter(maxConcurrent: number) {
+  let activeCount = 0
+  const queue: (() => void)[] = []
+
+  const next = () => {
+    if (queue.length === 0 || activeCount >= maxConcurrent) {
+      return
+    }
+
+    const resolve = queue.shift()
+
+    if (resolve) {
+      resolve()
+    }
+  }
+
+  const run = async <T>(fn: () => Promise<T>): Promise<T> => {
+    if (activeCount >= maxConcurrent) {
+      await new Promise<void>((resolve) => queue.push(resolve))
+    }
+
+    activeCount++
+    try {
+      const result = await fn()
+      return result
+    } finally {
+      activeCount--
+      next()
+    }
+  }
+
+  return run
+}

package/src/bundle/index.ts

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

package/src/bundle/plugins/browser.ts

@@ -0,0 +1,4 @@
+// biome-ignore lint/performance/noBarrelFile: <explanation>
+export { fetchUrls } from './fetch-urls'
+export { parseJson } from './parse-json'
+export { parseYaml } from './parse-yaml'

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

@@ -0,0 +1,147 @@
+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'
+
+describe('fetchUrl', () => {
+  const noLimit = <T>(fn: () => Promise<T>) => fn()
+
+  let server: FastifyInstance
+  const PORT = 7291
+
+  beforeEach(() => {
+    server = fastify({ logger: false })
+  })
+
+  afterEach(async () => {
+    await server.close()
+    await setTimeout(100)
+  })
+
+  it('reads json response', async () => {
+    const url = `http://localhost:${PORT}`
+
+    const response = {
+      message: '200OK',
+    }
+
+    server.get('/', (_, reply) => {
+      reply.send(response)
+    })
+
+    await server.listen({ port: PORT })
+
+    const result = await fetchUrl(url, noLimit)
+
+    expect(result.ok).toBe(true)
+    assert(result.ok === true)
+    expect(result.data).toEqual(response)
+  })
+
+  it('reads yaml response', async () => {
+    const url = `http://localhost:${PORT}`
+
+    server.get('/', (_, reply) => {
+      reply.header('content-type', 'application/yml').send('a: a')
+    })
+
+    await server.listen({ port: PORT })
+
+    const result = await fetchUrl(url, noLimit)
+
+    expect(result.ok).toBe(true)
+    assert(result.ok === true)
+    expect(result.data).toEqual({ a: 'a' })
+  })
+
+  it('returns error on non-200 response', async () => {
+    const url = `http://localhost:${PORT}`
+
+    server.get('/', (_, reply) => {
+      reply.status(404).send()
+    })
+
+    await server.listen({ port: PORT })
+
+    const result = await fetchUrl(url, noLimit)
+
+    expect(result.ok).toBe(false)
+  })
+
+  it('send headers to the specified domain', async () => {
+    const url = `http://localhost:${PORT}`
+    const fn = vi.fn()
+
+    const response = {
+      message: '200OK',
+    }
+
+    server.get('/', (request, reply) => {
+      fn(request.headers)
+      reply.send(response)
+    })
+
+    await server.listen({ port: PORT })
+    await fetchUrl(url, noLimit, {
+      headers: [{ headers: { 'Authorization': 'Bearer <TOKEN>' }, domains: [`localhost:${PORT}`] }],
+    })
+
+    expect(fn).toHaveBeenCalled()
+    expect(fn.mock.calls[0][0]).toEqual({
+      'accept': '*/*',
+      'accept-encoding': 'gzip, deflate',
+      'accept-language': '*',
+      'authorization': 'Bearer <TOKEN>',
+      'connection': 'keep-alive',
+      'host': `localhost:${PORT}`,
+      'sec-fetch-mode': 'cors',
+      'user-agent': 'node',
+    })
+  })
+
+  it('does not send headers to other domains', async () => {
+    const url = `http://localhost:${PORT}`
+    const fn = vi.fn()
+
+    const response = {
+      message: '200OK',
+    }
+
+    server.get('/', (request, reply) => {
+      fn(request.headers)
+      reply.send(response)
+    })
+
+    await server.listen({ port: PORT })
+    await fetchUrl(url, noLimit, {
+      headers: [{ headers: { 'Authorization': 'Bearer <TOKEN>' }, domains: ['localhost:9932', 'localhost'] }],
+    })
+
+    expect(fn).toHaveBeenCalled()
+    expect(fn.mock.calls[0][0]).toEqual({
+      'accept': '*/*',
+      'accept-encoding': 'gzip, deflate',
+      'accept-language': '*',
+      'connection': 'keep-alive',
+      'host': `localhost:${PORT}`,
+      'sec-fetch-mode': 'cors',
+      'user-agent': 'node',
+    })
+  })
+
+  it('runs custom fetcher', async () => {
+    const fn = vi.fn()
+
+    await fetchUrl('https://example.com', (fn) => fn(), {
+      fetch: async (input, init) => {
+        fn(input, init)
+
+        return new Response('{}', { status: 200 })
+      },
+    })
+
+    expect(fn).toHaveBeenCalled()
+    expect(fn).toHaveBeenCalledWith('https://example.com', { headers: undefined })
+  })
+})

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

@@ -0,0 +1,94 @@
+import { normalize } from '@/utils/normalize'
+import { createLimiter } from '@/bundle/create-limiter'
+import type { Plugin, ResolveResult } from '@/bundle'
+import { isRemoteUrl } from '@/bundle/bundle'
+
+type FetchConfig = Partial<{
+  headers: { headers: HeadersInit; domains: string[] }[]
+  fetch: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>
+}>
+
+/**
+ * Safely checks for host from a URL
+ * Needed because we cannot create a URL from a relative remote URL ex: examples/openapi.json
+ */
+const getHost = (url: string): string | null => {
+  try {
+    return new URL(url).host
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Fetches and normalizes data from a remote URL
+ * @param url - The URL to fetch data from
+ * @returns A promise that resolves to either the normalized data or an error result
+ * @example
+ * ```ts
+ * const result = await fetchUrl('https://api.example.com/data.json')
+ * if (result.ok) {
+ *   console.log(result.data) // The normalized data
+ * } else {
+ *   console.log('Failed to fetch data')
+ * }
+ * ```
+ */
+export async function fetchUrl(
+  url: string,
+  limiter: <T>(fn: () => Promise<T>) => Promise<T>,
+  config?: FetchConfig,
+): Promise<ResolveResult> {
+  try {
+    const host = getHost(url)
+
+    // Get the headers that match the domain
+    const headers = config?.headers?.find((a) => a.domains.find((d) => d === host) !== undefined)?.headers
+
+    const exec = config?.fetch ?? fetch
+
+    const result = await limiter(() =>
+      exec(url, {
+        headers,
+      }),
+    )
+
+    if (result.ok) {
+      const body = await result.text()
+
+      return {
+        ok: true,
+        data: normalize(body),
+      }
+    }
+
+    return {
+      ok: false,
+    }
+  } catch {
+    return {
+      ok: false,
+    }
+  }
+}
+
+/**
+ * Creates a plugin for handling remote URL references.
+ * This plugin validates and fetches data from HTTP/HTTPS URLs.
+ *
+ * @returns A plugin object with validate and exec functions
+ * @example
+ * const urlPlugin = fetchUrls()
+ * if (urlPlugin.validate('https://example.com/schema.json')) {
+ *   const result = await urlPlugin.exec('https://example.com/schema.json')
+ * }
+ */
+export function fetchUrls(config?: FetchConfig & Partial<{ limit: number | null }>): Plugin {
+  // If there is a limit specified we limit the number of concurrent calls
+  const limiter = config?.limit ? createLimiter(config.limit) : <T>(fn: () => Promise<T>) => fn()
+
+  return {
+    validate: isRemoteUrl,
+    exec: (value) => fetchUrl(value, limiter, config),
+  }
+}

package/src/bundle/plugins/node.ts

@@ -0,0 +1,5 @@
+// biome-ignore lint/performance/noBarrelFile: <explanation>
+export { fetchUrls } from './fetch-urls'
+export { readFiles } from './read-files'
+export { parseJson } from './parse-json'
+export { parseYaml } from './parse-yaml'

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

@@ -0,0 +1,22 @@
+import { parseJson } from '@/bundle/plugins/parse-json'
+import { describe, expect, it } from 'vitest'
+
+describe('parse-json', () => {
+  it.each([
+    ['{}', true],
+    ['{ "a": "b" }', true],
+    ['{ "a": 2 }', true],
+    ["{ 'a': 2 }", false],
+    ['{ some string', false],
+    ['{ ', false],
+  ])('should validate if strings are json valid format', (a, b) => {
+    expect(parseJson().validate(a)).toBe(b)
+  })
+
+  it('should parse json string', async () => {
+    expect(await parseJson().exec('{ "message": "Hello World" }')).toEqual({
+      ok: true,
+      data: { message: 'Hello World' },
+    })
+  })
+})

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

@@ -0,0 +1,30 @@
+import { isJsonObject } from '@/utils/is-json-object'
+import type { Plugin, ResolveResult } from '@/bundle'
+
+/**
+ * Creates a plugin that parses JSON strings into JavaScript objects.
+ * @returns A plugin object with validate and exec functions
+ * @example
+ * ```ts
+ * const jsonPlugin = parseJson()
+ * const result = jsonPlugin.exec('{"name": "John", "age": 30}')
+ * // result = { name: 'John', age: 30 }
+ * ```
+ */
+export function parseJson(): Plugin {
+  return {
+    validate: isJsonObject,
+    exec: async (value): Promise<ResolveResult> => {
+      try {
+        return {
+          ok: true,
+          data: JSON.parse(value),
+        }
+      } catch {
+        return {
+          ok: false,
+        }
+      }
+    },
+  }
+}

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

@@ -0,0 +1,24 @@
+import { parseYaml } from '@/bundle/plugins/parse-yaml'
+import { describe, expect, it } from 'vitest'
+
+describe('parse-yaml', () => {
+  it.each([
+    ['hi: hello\n', true],
+    ['- some: 1\n', true],
+    ['valid: value\nhey: hi\n', true],
+    ["{ 'a': 2 }", false],
+    ['{ some string', false],
+    ['{ ', false],
+    ['{}', false],
+    ['{ "json": "" }', false],
+  ])('should validate if strings are yaml valid format', (a, b) => {
+    expect(parseYaml().validate(a)).toBe(b)
+  })
+
+  it('should parse yaml string', async () => {
+    expect(await parseYaml().exec('{ "message": "Hello World" }')).toEqual({
+      ok: true,
+      data: { message: 'Hello World' },
+    })
+  })
+})

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

@@ -0,0 +1,31 @@
+import type { Plugin, ResolveResult } from '@/bundle/bundle'
+import { isYaml } from '@/utils/is-yaml'
+import YAML from 'yaml'
+
+/**
+ * Creates a plugin that parses YAML strings into JavaScript objects.
+ * @returns A plugin object with validate and exec functions
+ * @example
+ * ```ts
+ * const yamlPlugin = parseYaml()
+ * const result = yamlPlugin.exec('name: John\nage: 30')
+ * // result = { name: 'John', age: 30 }
+ * ```
+ */
+export function parseYaml(): Plugin {
+  return {
+    validate: isYaml,
+    exec: async (value): Promise<ResolveResult> => {
+      try {
+        return {
+          ok: true,
+          data: YAML.parse(value),
+        }
+      } catch {
+        return {
+          ok: false,
+        }
+      }
+    },
+  }
+}

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

@@ -0,0 +1,35 @@
+import fs from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { describe, expect, it } from 'vitest'
+import { readFile } from '.'
+import assert from 'node:assert'
+
+describe('readFile', () => {
+  it('reads json contents of a file', async () => {
+    const contents = { message: 'ok' }
+    const path = randomUUID()
+    await fs.writeFile(path, JSON.stringify(contents))
+
+    const result = await readFile(path)
+    await fs.rm(path)
+
+    expect(result.ok).toBe(true)
+    assert(result.ok === true)
+
+    expect(result.data).toEqual(contents)
+  })
+
+  it('reads yml contents of a file', async () => {
+    const contents = 'a: a'
+    const path = randomUUID()
+    await fs.writeFile(path, contents)
+
+    const result = await readFile(path)
+    await fs.rm(path)
+
+    expect(result.ok).toBe(true)
+    assert(result.ok === true)
+
+    expect(result.data).toEqual({ a: 'a' })
+  })
+})

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

@@ -0,0 +1,55 @@
+import { normalize } from '@/utils/normalize'
+import { isFilePath, type Plugin, type ResolveResult } from '@/bundle/bundle'
+
+/**
+ * Reads and normalizes data from a local file
+ * @param path - The file path to read from
+ * @returns A promise that resolves to either the normalized data or an error result
+ * @example
+ * ```ts
+ * const result = await readFile('./schemas/user.json')
+ * if (result.ok) {
+ *   console.log(result.data) // The normalized data
+ * } else {
+ *   console.log('Failed to read file')
+ * }
+ * ```
+ */
+export async function readFile(path: string): Promise<ResolveResult> {
+  const fs = typeof window === 'undefined' ? await import('node:fs/promises') : undefined
+
+  if (fs === undefined) {
+    throw 'Can not use readFiles plugin outside of a node environment'
+  }
+
+  try {
+    const fileContents = await fs.readFile(path, { encoding: 'utf-8' })
+
+    return {
+      ok: true,
+      data: normalize(fileContents),
+    }
+  } catch {
+    return {
+      ok: false,
+    }
+  }
+}
+
+/**
+ * Creates a plugin for handling local file references.
+ * This plugin validates and reads data from local filesystem paths.
+ *
+ * @returns A plugin object with validate and exec functions
+ * @example
+ * const filePlugin = readFiles()
+ * if (filePlugin.validate('./local-schema.json')) {
+ *   const result = await filePlugin.exec('./local-schema.json')
+ * }
+ */
+export function readFiles(): Plugin {
+  return {
+    validate: isFilePath,
+    exec: readFile,
+  }
+}