@amritk/generate-parsers 0.2.1 → 0.3.0

package/src/generators/build-schema.ts

@@ -0,0 +1,280 @@
+import { readFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, resolve as resolvePath } from 'node:path'
+import { buildDynamicRefMap } from '@amritk/helpers/build-dynamic-ref-map'
+import { extractRefs } from '@amritk/helpers/extract-refs'
+import { refToFilename } from '@amritk/helpers/ref-to-filename'
+import { refToName } from '@amritk/helpers/ref-to-name'
+import { resolveDynamicRefs } from '@amritk/helpers/resolve-dynamic-refs'
+import { resolveRef } from '@amritk/helpers/resolve-ref'
+import { upgradeDraft07Schema } from '@amritk/helpers/upgrade-draft07-schema'
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
+import { applySchemaExtensions } from '#helpers/apply-schema-extensions'
+import type { HelpersMode, RuntimeHelperName } from '#helpers/collect-helpers'
+import type { SchemaExtensions } from '#types/schema-extensions'
+
+import { generateFile } from './generate-files'
+
+/** Locate the @amritk/helpers package on disk so we can copy its runtime
+ * helper source files into the generated output when in embedded mode. */
+const readHelperSource = async (helper: RuntimeHelperName): Promise<string> => {
+  const require = createRequire(import.meta.url)
+  const helpersPkgPath = require.resolve('@amritk/helpers/package.json')
+  const helpersRoot = dirname(helpersPkgPath)
+  return readFile(resolvePath(helpersRoot, 'src', `${helper}.ts`), 'utf-8')
+}
+
+/**
+ * Represents a generated file with its filename and content.
+ */
+export type GeneratedFile = {
+  filename: string
+  content: string
+}
+
+/**
+ * Extracts all definitions from $defs that have a $dynamicAnchor.
+ * These definitions need to be generated even if not directly referenced by $ref.
+ */
+const extractDynamicAnchorDefs = (schema: JSONSchema): string[] => {
+  const refs: string[] = []
+
+  if (typeof schema !== 'object' || schema === null) {
+    return refs
+  }
+
+  // Check if schema has $defs
+  if (!('$defs' in schema) || typeof schema['$defs'] !== 'object' || schema['$defs'] === null) {
+    return refs
+  }
+
+  const defs = schema['$defs']
+
+  // Find all definitions with $dynamicAnchor
+  for (const [key, value] of Object.entries(defs)) {
+    if (typeof value === 'object' && value !== null) {
+      const defSchema = value as Record<string, unknown>
+      if ('$dynamicAnchor' in defSchema) {
+        // Convert to a $ref-style path
+        refs.push(`#/$defs/${key}`)
+      }
+    }
+  }
+
+  return refs
+}
+
+/**
+ * Builds all TypeScript files from a JSON Schema by traversing
+ * all $ref references recursively.
+ *
+ * Starting from the root schema, this function:
+ * 1. Generates a TypeScript file for the root type
+ * 2. Extracts all $ref references from the schema
+ * 3. Extracts all definitions with $dynamicAnchor (JSON Schema 2020-12 feature)
+ * 4. Resolves each ref and generates a TypeScript file for it
+ * 5. Recursively processes nested refs until all are handled
+ *
+ * @param rootSchema - The root JSON Schema to build from
+ * @param rootTypeName - The name for the root type (e.g., "Document")
+ * @param extensions - Optional map of custom extension properties to add to specific definitions.
+ *   Keys are definition names (matching $defs keys), values are records of extension property
+ *   names to their JSON Schema definitions. Extensions are merged as optional properties before
+ *   type and parser generation.
+ * @param typesOnly - When true, only generate TypeScript type definitions without parser functions.
+ * @param logWarnings - When true, the generated parsers emit a console.warn for every input key
+ *   that is not declared in the schema's properties.
+ * @param strict - When true, the generated parsers throw on type/shape mismatches
+ *   (wrong type, missing required property, enum/pattern/min/max violations) instead
+ *   of coercing invalid input to default values.
+ * @param helpersMode - `'package'` (default) emits `import ... from '@amritk/helpers/...'`.
+ *   `'embedded'` emits `import ... from './_helpers/...'` and appends the helper sources
+ *   as additional `GeneratedFile` entries so the output directory is self-contained.
+ * @returns An array of generated TypeScript files
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   type: "object",
+ *   properties: {
+ *     info: { $ref: "#/$defs/info" }
+ *   },
+ *   $defs: {
+ *     info: {
+ *       type: "object",
+ *       properties: {
+ *         title: { type: "string" }
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * const files = buildSchema(schema, "Document");
+ *
+ * // Types-only mode — no parser functions or runtime helpers included:
+ * const typesFiles = buildSchema(schema, "Document", undefined, true);
+ *
+ * // With extensions:
+ * const filesWithExtensions = buildSchema(schema, "Document", {
+ *   info: {
+ *     'x-internal': { type: 'boolean' },
+ *   },
+ * });
+ * ```
+ */
+export const buildSchema = async (
+  rootSchema: JSONSchema,
+  rootTypeName: string,
+  extensions?: SchemaExtensions,
+  typesOnly?: boolean,
+  logWarnings?: boolean,
+  strict?: boolean,
+  helpersMode: HelpersMode = 'package',
+): Promise<GeneratedFile[]> => {
+  // Upgrade draft-07 schemas to 2020-12 conventions before processing.
+  // This renames `definitions` → `$defs` recursively so the rest of the
+  // pipeline can resolve both short-name and URI-keyed refs uniformly.
+  rootSchema = upgradeDraft07Schema(rootSchema as Record<string, unknown>) as JSONSchema
+
+  const files: GeneratedFile[] = []
+  const processedRefs = new Set<string>()
+  const processedFilenames = new Set<string>()
+  const refsToProcess: string[] = []
+  const usedHelpers = new Set<RuntimeHelperName>()
+
+  // Build a map of $dynamicRef anchors to their $ref paths so we can
+  // convert $dynamicRef: "#meta" to $ref: "#/$defs/schema" before generating
+  const dynamicRefMap = buildDynamicRefMap(rootSchema)
+
+  // Generate file for the root schema, applying any matching extensions
+  const processedRootSchema = resolveDynamicRefs(rootSchema, dynamicRefMap)
+  const extendedRootSchema = extensions
+    ? applySchemaExtensions(processedRootSchema, rootTypeName.toLowerCase(), extensions)
+    : processedRootSchema
+  const rootResult = generateFile(extendedRootSchema, rootTypeName, {
+    typesOnly: typesOnly ?? false,
+    rootSchema: rootSchema as Record<string, unknown>,
+    helpersMode,
+    ...(logWarnings !== undefined ? { logWarnings } : {}),
+    ...(strict !== undefined ? { strict } : {}),
+  })
+  const rootFilename = rootTypeName.toLowerCase()
+
+  processedFilenames.add(rootFilename)
+  files.push({
+    filename: `${rootFilename}.ts`,
+    content: rootResult.content,
+  })
+  for (const helper of rootResult.usedHelpers) usedHelpers.add(helper)
+
+  // Extract all refs from the root schema
+  const rootRefs = extractRefs(rootSchema)
+  refsToProcess.push(...rootRefs)
+
+  // Extract all definitions with $dynamicAnchor
+  const dynamicAnchorRefs = extractDynamicAnchorDefs(rootSchema)
+  refsToProcess.push(...dynamicAnchorRefs)
+
+  // Process refs until none remain
+  while (refsToProcess.length > 0) {
+    const ref = refsToProcess.shift()
+
+    // Skip if already processed
+    if (!ref || processedRefs.has(ref)) {
+      continue
+    }
+
+    processedRefs.add(ref)
+
+    // Resolve the ref to get the actual schema
+    const resolvedSchema = resolveRef(ref, rootSchema as Record<string, unknown>)
+
+    if (!resolvedSchema) {
+      console.warn(`Warning: Could not resolve ref: ${ref}`)
+      continue
+    }
+
+    // Generate file for this ref, resolving any $dynamicRef to $ref first
+    // and applying any matching extensions for this definition
+    const typeName = refToName(ref)
+    const filename = refToFilename(ref)
+    const processedSchema = resolveDynamicRefs(resolvedSchema as JSONSchema, dynamicRefMap)
+    const extendedSchema = extensions ? applySchemaExtensions(processedSchema, filename, extensions) : processedSchema
+    const fileResult = generateFile(extendedSchema, typeName, {
+      typesOnly: typesOnly ?? false,
+      selfRef: ref,
+      rootSchema: rootSchema as Record<string, unknown>,
+      helpersMode,
+      ...(logWarnings !== undefined ? { logWarnings } : {}),
+      ...(strict !== undefined ? { strict } : {}),
+    })
+
+    if (!processedFilenames.has(filename)) {
+      processedFilenames.add(filename)
+      files.push({
+        filename: `${filename}.ts`,
+        content: fileResult.content,
+      })
+    }
+    for (const helper of fileResult.usedHelpers) usedHelpers.add(helper)
+
+    // Extract refs from this schema and add to queue
+    const nestedRefs = extractRefs(resolvedSchema as JSONSchema)
+    for (const nestedRef of nestedRefs) {
+      if (!processedRefs.has(nestedRef)) {
+        refsToProcess.push(nestedRef)
+      }
+    }
+  }
+
+  // In embedded mode, ship the runtime helper source files alongside the parsers so
+  // the output directory is self-contained (no `@amritk/helpers` install required).
+  // typesOnly skips parser generation entirely, so no runtime helpers are needed.
+  if (helpersMode === 'embedded' && !typesOnly) {
+    for (const helper of usedHelpers) {
+      const source = await readHelperSource(helper)
+      files.push({ filename: `_helpers/${helper}.ts`, content: source })
+    }
+  }
+
+  // Generate index.ts with named re-exports extracted from each generated file's content.
+  // Regex matches `export type Foo` and `export const foo` declarations.
+  const TYPE_EXPORT_RE = /^export type (\w+)/gm
+  const CONST_EXPORT_RE = /^export const (\w+)/gm
+
+  // _helpers/ is an internal directory; never re-export from it.
+  const sortedFiles = [...files]
+    .filter((f) => !f.filename.startsWith('_helpers/'))
+    .sort((a, b) => a.filename.localeCompare(b.filename))
+
+  let indexContent = ''
+  for (const file of sortedFiles) {
+    const moduleName = file.filename.replace(/\.ts$/, '')
+    const typeNames: string[] = []
+    const constNames: string[] = []
+
+    for (const match of file.content.matchAll(TYPE_EXPORT_RE)) {
+      typeNames.push(match[1] as string)
+    }
+    for (const match of file.content.matchAll(CONST_EXPORT_RE)) {
+      constNames.push(match[1] as string)
+    }
+
+    if (typeNames.length === 0 && constNames.length === 0) continue
+
+    if (typesOnly) {
+      indexContent += `export type { ${typeNames.join(', ')} } from './${moduleName}';\n`
+    } else {
+      const typeExports = typeNames.map((n) => `type ${n}`)
+      const allExports = [...typeExports, ...constNames]
+      indexContent += `export { ${allExports.join(', ')} } from './${moduleName}';\n`
+    }
+  }
+
+  files.push({
+    filename: 'index.ts',
+    content: indexContent,
+  })
+
+  return files
+}

package/src/generators/generate-default-from-pattern.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest'
+
+import { generateDefaultFromPattern } from './generate-default-from-pattern'
+
+describe('generate-default-from-pattern', () => {
+  it('returns email default for pattern containing @', () => {
+    const result = generateDefaultFromPattern('^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$')
+    expect(result).toBe('"user@example.com"')
+  })
+
+  it('returns email default for pattern with character class and dot', () => {
+    const result = generateDefaultFromPattern('[a-zA-Z0-9].*\\.')
+    expect(result).toBe('"user@example.com"')
+  })
+
+  it('returns UUID default for hex pattern with {8}', () => {
+    const result = generateDefaultFromPattern('^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$')
+    expect(result).toBe('"00000000-0000-0000-0000-000000000000"')
+  })
+
+  it('returns UUID default for pattern with dash separator', () => {
+    const result = generateDefaultFromPattern('[0-9a-f]{8}\\-[0-9a-f]{4}')
+    expect(result).toBe('"00000000-0000-0000-0000-000000000000"')
+  })
+
+  it('returns null for hex pattern without dash or matching structure', () => {
+    const result = generateDefaultFromPattern('^[0-9a-fA-F]{8}')
+    expect(result).toBeNull()
+  })
+
+  it('returns URL default for https? pattern', () => {
+    const result = generateDefaultFromPattern('^https?://')
+    expect(result).toBe('"https://example.com"')
+  })
+
+  it('returns URL default for http pattern', () => {
+    const result = generateDefaultFromPattern('^http://')
+    expect(result).toBe('"https://example.com"')
+  })
+
+  it('returns semver default for version-like pattern with literal digits', () => {
+    // The regex looks for actual digit chars and escaped dots in the pattern string
+    const result = generateDefaultFromPattern('3\\.1\\.\\d+')
+    expect(result).toBe('"1.0.0"')
+  })
+
+  it('returns null for version pattern without literal digits', () => {
+    const result = generateDefaultFromPattern('^\\d+\\.\\d+\\.\\d+$')
+    expect(result).toBeNull()
+  })
+
+  it('returns ISO date default for date-like pattern', () => {
+    const result = generateDefaultFromPattern('^\\d{4}-\\d{2}-\\d{2}$')
+    expect(result).toBe('"2000-01-01"')
+  })
+
+  it('returns phone number default for phone-like pattern with {3} and {4}', () => {
+    const result = generateDefaultFromPattern('^\\+?\\d{3}\\d{4}$')
+    expect(result).toBe('"+1234567890"')
+  })
+
+  it('returns phone number default for phone-like pattern with {3} and {7}', () => {
+    const result = generateDefaultFromPattern('^\\d{3}\\d{7}$')
+    expect(result).toBe('"+1234567890"')
+  })
+
+  it('returns null for unrecognized pattern', () => {
+    const result = generateDefaultFromPattern('^[a-z]+$')
+    expect(result).toBeNull()
+  })
+
+  it('returns null for empty pattern', () => {
+    const result = generateDefaultFromPattern('')
+    expect(result).toBeNull()
+  })
+
+  it('returns null for simple wildcard pattern', () => {
+    const result = generateDefaultFromPattern('.*')
+    expect(result).toBeNull()
+  })
+})

package/src/generators/generate-default-from-pattern.ts

@@ -0,0 +1,39 @@
+/**
+ * Generates a best-guess default value from a regex pattern.
+ * Recognizes common patterns and returns appropriate defaults.
+ */
+export const generateDefaultFromPattern = (pattern: string): string | null => {
+  // Email pattern
+  if (pattern.includes('@') || (pattern.includes('[a-zA-Z0-9]') && pattern.includes('\\.'))) {
+    return '"user@example.com"'
+  }
+
+  // UUID pattern
+  if ((pattern.includes('[0-9a-f]') && pattern.includes('{8}')) || pattern.includes('\\-')) {
+    if (pattern.match(/[0-9a-f].*\{8\}/i) || pattern.match(/[0-9a-fA-F]{8}/)) {
+      return '"00000000-0000-0000-0000-000000000000"'
+    }
+  }
+
+  // URL pattern
+  if (pattern.includes('https?') || pattern.includes('http')) {
+    return '"https://example.com"'
+  }
+
+  // Semver pattern (3.1.x, x.y.z, etc)
+  if (pattern.match(/\d.*\\\.\.*\d/)) {
+    return '"1.0.0"'
+  }
+
+  // ISO date pattern
+  if (pattern.includes('\\d{4}') && pattern.includes('\\d{2}')) {
+    return '"2000-01-01"'
+  }
+
+  // Phone number patterns
+  if (pattern.includes('\\d{3}') && (pattern.includes('\\d{4}') || pattern.includes('\\d{7}'))) {
+    return '"+1234567890"'
+  }
+
+  return null
+}

package/src/generators/generate-discriminated-union-validation.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest'
+
+import { generateDiscriminatedUnionValidation } from './generate-discriminated-union-validation'
+
+describe('generate-discriminated-union-validation', () => {
+  it('generates ternary chain for schemas with discriminator values', () => {
+    const schemas = [
+      {
+        type: 'object' as const,
+        properties: { kind: { const: 'a' }, name: { type: 'string' as const } },
+      },
+      {
+        type: 'object' as const,
+        properties: { kind: { const: 'b' }, count: { type: 'number' as const } },
+      },
+    ]
+    const result = generateDiscriminatedUnionValidation('value', schemas, 'kind', '{}', true)
+    expect(result).toContain('value?.kind === "a"')
+    expect(result).toContain('value?.kind === "b"')
+  })
+
+  it('returns fallback expression when no schemas have discriminator values', () => {
+    const schemas = [{ type: 'object' as const, properties: { name: { type: 'string' as const } } }]
+    const result = generateDiscriminatedUnionValidation('value', schemas, 'kind', '{}', true)
+    expect(result).toBe('value ?? {}')
+  })
+
+  it('returns accessor when not required and no discriminator values', () => {
+    const schemas = [{ type: 'object' as const, properties: { name: { type: 'string' as const } } }]
+    const result = generateDiscriminatedUnionValidation('value', schemas, 'kind', '{}', false)
+    expect(result).toBe('value')
+  })
+
+  it('includes schema checks in ternary when type checks exist', () => {
+    const schemas = [
+      {
+        type: 'object' as const,
+        properties: { kind: { const: 'user' } },
+      },
+    ]
+    const result = generateDiscriminatedUnionValidation('input', schemas, 'kind', '{}', true)
+    expect(result).toContain('input?.kind === "user"')
+    // Should include object type checks
+    expect(result).toContain('typeof input === "object"')
+  })
+
+  it('handles schemas with single enum values as discriminators', () => {
+    const schemas = [
+      {
+        type: 'object' as const,
+        properties: { type: { enum: ['cat'] } },
+      },
+      {
+        type: 'object' as const,
+        properties: { type: { enum: ['dog'] } },
+      },
+    ]
+    const result = generateDiscriminatedUnionValidation('value', schemas, 'type', '{}', true)
+    expect(result).toContain('value?.type === "cat"')
+    expect(result).toContain('value?.type === "dog"')
+  })
+
+  it('handles empty schemas array', () => {
+    const result = generateDiscriminatedUnionValidation('value', [], 'type', '{}', true)
+    expect(result).toBe('value ?? {}')
+  })
+
+  it('skips schemas without a discriminator value', () => {
+    const schemas = [
+      {
+        type: 'object' as const,
+        properties: { kind: { const: 'a' } },
+      },
+      {
+        type: 'object' as const,
+        properties: { name: { type: 'string' as const } },
+      },
+    ]
+    const result = generateDiscriminatedUnionValidation('value', schemas, 'kind', '{}', true)
+    expect(result).toContain('value?.kind === "a"')
+    // The second schema has no discriminator, so it does not appear in the ternary chain
+    expect(result).not.toContain('value?.kind === undefined')
+  })
+})

package/src/generators/generate-discriminated-union-validation.ts

@@ -0,0 +1,54 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
+import { getDefaultValue } from '#helpers/get-default-value'
+import { getDiscriminatorValue } from '#helpers/get-discriminator-value'
+
+import { generateSchemaChecks } from './generate-schema-checks'
+
+/**
+ * Generates a discriminated union validation expression.
+ * Uses a discriminator property to efficiently choose the correct schema.
+ */
+export const generateDiscriminatedUnionValidation = (
+  accessor: string,
+  schemas: readonly JSONSchema[],
+  discriminatorKey: string,
+  defaultValue: string,
+  isRequired: boolean,
+): string => {
+  const cases: string[] = []
+
+  for (const schema of schemas) {
+    const discriminatorValue = getDiscriminatorValue(schema, discriminatorKey)
+    if (discriminatorValue !== null) {
+      const schemaDefault = getDefaultValue(schema)
+      const checks = generateSchemaChecks(accessor, schema)
+
+      if (checks.length > 0) {
+        // checks[0] is safe: we guard with checks.length > 0 above
+        let combinedChecks = checks[0] as string
+        for (let i = 1; i < checks.length; i++) {
+          combinedChecks += ' && ' + checks[i]
+        }
+        cases.push(
+          `${accessor}?.${discriminatorKey} === ${JSON.stringify(discriminatorValue)} && ${combinedChecks} ? ${accessor} : ${schemaDefault}`,
+        )
+      } else {
+        cases.push(
+          `${accessor}?.${discriminatorKey} === ${JSON.stringify(discriminatorValue)} ? ${accessor} : ${schemaDefault}`,
+        )
+      }
+    }
+  }
+
+  if (cases.length === 0) {
+    return isRequired ? `${accessor} ?? ${defaultValue}` : accessor
+  }
+
+  // Chain the cases together with ternary operators using a for loop instead of .reduce()
+  // cases[0] is safe: we guard with cases.length === 0 above
+  let result = cases[0] as string
+  for (let i = 1; i < cases.length; i++) {
+    result = cases[i] + ' : ' + result
+  }
+  return result
+}

package/src/generators/generate-enum-check.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest'
+
+import { generateEnumCheck } from './generate-enum-check'
+
+describe('generate-enum-check', () => {
+  it('generates an includes check for string enum values', () => {
+    const result = generateEnumCheck('value', ['a', 'b', 'c'])
+    expect(result).toBe('["a","b","c"].includes(value as never)')
+  })
+
+  it('generates an includes check for numeric enum values', () => {
+    const result = generateEnumCheck('value', [1, 2, 3])
+    expect(result).toBe('[1,2,3].includes(value as never)')
+  })
+
+  it('generates an includes check for mixed type enum values', () => {
+    const result = generateEnumCheck('value', ['a', 1, true, null])
+    expect(result).toBe('["a",1,true,null].includes(value as never)')
+  })
+
+  it('handles a single enum value', () => {
+    const result = generateEnumCheck('value', ['only'])
+    expect(result).toBe('["only"].includes(value as never)')
+  })
+
+  it('handles an empty enum array', () => {
+    const result = generateEnumCheck('value', [])
+    expect(result).toBe('[].includes(value as never)')
+  })
+
+  it('uses the provided accessor in the expression', () => {
+    const result = generateEnumCheck('input?.type', ['a', 'b'])
+    expect(result).toBe('["a","b"].includes(input?.type as never)')
+  })
+
+  it('handles enum values with special characters', () => {
+    const result = generateEnumCheck('value', ['hello world', 'foo"bar'])
+    expect(result).toBe('["hello world","foo\\"bar"].includes(value as never)')
+  })
+
+  it('handles boolean enum values', () => {
+    const result = generateEnumCheck('value', [true, false])
+    expect(result).toBe('[true,false].includes(value as never)')
+  })
+})

package/src/generators/generate-enum-check.ts

@@ -0,0 +1,8 @@
+/**
+ * Generates an enum validation check expression.
+ * Returns a string that checks if the value is in the allowed enum values.
+ */
+export const generateEnumCheck = (accessor: string, enumValues: readonly unknown[]): string => {
+  const serializedEnum = JSON.stringify(enumValues)
+  return `${serializedEnum}.includes(${accessor} as never)`
+}