@amritk/generate-parsers 0.7.1 → 0.8.0

package/src/generators/build-schema.ts

@@ -1,147 +0,0 @@
-import { readFile } from 'node:fs/promises'
-import { createRequire } from 'node:module'
-import { dirname, resolve as resolvePath } from 'node:path'
-import { generateIndexBarrel } from '@amritk/helpers/generate-index-barrel'
-import { walkRefGraph } from '@amritk/helpers/walk-ref-graph'
-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
-}
-
-/**
- * Builds all TypeScript files from a JSON Schema by traversing its entire
- * `$ref` / `$dynamicRef` graph (via the shared `@amritk/helpers/walk-ref-graph`
- * walker, which also seeds `$dynamicAnchor` definitions and rewrites
- * `$dynamicRef` to `$ref`).
- *
- * For the root schema and each reachable definition this function generates a
- * TypeScript file, then emits an `index.ts` barrel re-exporting them all.
- *
- * @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.
- * @param helpersImportPrefix - Relative path prefix to the `_helpers/` directory in
- *   embedded mode. Defaults to `'./'`. The recursive multi-schema build passes `'../'`,
- *   `'../../'`, etc. so nested parsers can import from a single shared `_helpers/`
- *   directory while the helper sources are emitted once at the output root.
- * @param readonly - When true, every property, array, and record in the generated type
- *   definitions is emitted as `readonly`.
- * @param typeSuffix - Suffix appended to every type/parser name derived from a `$ref`
- *   (e.g. `'Object'` → `ContactObject`). Defaults to `''` (no suffix). The root type name
- *   is used verbatim and is not affected by this suffix.
- * @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',
-  helpersImportPrefix = './',
-  readonly = false,
-  typeSuffix = '',
-): Promise<GeneratedFile[]> => {
-  const files: GeneratedFile[] = []
-  const usedHelpers = new Set<RuntimeHelperName>()
-
-  walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
-    // `index` is reserved for the barrel below, so never let a definition of
-    // that name overwrite it.
-    if (node.filename === 'index') return
-
-    // Extensions are keyed by definition name, which is the node's filename for
-    // both the root (the lowercased root type name) and every `$ref` target.
-    const extended = extensions ? applySchemaExtensions(node.schema, node.filename, extensions) : node.schema
-    const result = generateFile(extended, node.typeName, {
-      typesOnly: typesOnly ?? false,
-      rootSchema: node.rootSchema,
-      helpersMode,
-      helpersImportPrefix,
-      readonly,
-      typeSuffix,
-      ...(node.ref !== undefined ? { selfRef: node.ref } : {}),
-      ...(logWarnings !== undefined ? { logWarnings } : {}),
-      ...(strict !== undefined ? { strict } : {}),
-    })
-
-    files.push({ filename: `${node.filename}.ts`, content: result.content })
-    for (const helper of result.usedHelpers) usedHelpers.add(helper)
-  })
-
-  // 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 })
-    }
-  }
-
-  files.push({ filename: 'index.ts', content: generateIndexBarrel(files, { typesOnly: typesOnly ?? false }) })
-
-  return files
-}

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

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

@@ -1,39 +0,0 @@
-/**
- * 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

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

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

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

@@ -1,8 +0,0 @@
-/**
- * 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)`
-}