@amritk/generate-parsers 0.7.2 → 0.9.0

package/src/helpers/collect-imports.ts

@@ -1,275 +0,0 @@
-import { refToFilename } from '@amritk/helpers/ref-to-filename'
-import { refToName } from '@amritk/helpers/ref-to-name'
-import { resolveRef } from '@amritk/helpers/resolve-ref'
-import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasItems, hasOneOf, hasRef } from '@amritk/helpers/schema-guards'
-import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
-
-const getImportPathForFilename = (filename: string): string => `./${filename}`
-
-/**
- * Options for controlling how imports are collected.
- */
-type CollectImportsOptions = {
-  /**
-   * When true, only generate type-only imports (no parser function imports).
-   * Use this when generating types-only files that do not include parser functions.
-   */
-  readonly typesOnly?: boolean
-  /**
-   * The $ref path of the schema being generated (e.g. `#/$defs/encoding`).
-   * When provided, any $ref that resolves to the same filename is excluded from
-   * the import list, preventing a file from importing itself.
-   */
-  readonly selfRef?: string | undefined
-  /**
-   * The root schema document. When provided, URI refs that cannot be resolved
-   * within the root schema's $defs are excluded from the import list, preventing
-   * imports for external schemas that were never generated as files.
-   */
-  readonly rootSchema?: Record<string, unknown> | undefined
-  /**
-   * Suffix appended to every type name derived from a `$ref`. Must match the
-   * suffix used when generating the referenced files so imports resolve.
-   * Defaults to `''` (no suffix).
-   */
-  readonly typeSuffix?: string
-}
-
-/**
- * Collects all import statements needed for a schema by finding $ref references
- * that are directly used in the type definition (from properties, items, etc.).
- * Does not include refs from nested schema definitions.
- *
- * Generates both type imports and parser function imports for each $ref.
- * The parser imports allow validators to delegate validation to the referenced
- * schema's parser instead of inlining the validation logic.
- *
- * Also detects when helper functions (isObject) and validators (validateRecord,
- * validateArray) are needed based on the schema structure.
- *
- * @param schema - The JSON Schema to collect imports from
- * @param options - Optional settings to control import generation
- * @returns An array of import statements
- *
- * @example
- * ```ts
- * const schema = {
- *   type: 'object',
- *   properties: {
- *     contact: { $ref: '#/$defs/contact' },
- *     server: { $ref: '#/$defs/server' }
- *   }
- * }
- * const imports = collectImports(schema)
- * // imports = [
- * //   "import { type Contact, parseContact } from './contact';",
- * //   "import { type Server, parseServer } from './server';"
- * // ]
- *
- * // With typesOnly, only type imports are generated:
- * const typeImports = collectImports(schema, { typesOnly: true })
- * // typeImports = [
- * //   "import type { Contact } from './contact';",
- * //   "import type { Server } from './server';"
- * // ]
- * ```
- */
-export const collectImports = (schema: JSONSchema, options?: CollectImportsOptions): string[] => {
-  const typesOnly = options?.typesOnly === true
-  const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : undefined
-  const rootSchema = options?.rootSchema
-  const typeSuffix = options?.typeSuffix
-  const refs = new Set<string>()
-
-  const collectRefsFromValue = (value: unknown): void => {
-    if (typeof value !== 'object' || value === null) {
-      return
-    }
-
-    if (Array.isArray(value)) {
-      for (const item of value) {
-        collectRefsFromValue(item)
-      }
-      return
-    }
-
-    const record = value as Record<string, unknown>
-
-    // If this is a $ref, add it — but skip:
-    // - Relative path refs (e.g. /components/messages/foo) which point into example data
-    // - URI refs with fragments pointing into `properties` (not standalone definitions)
-    if (hasRef(record)) {
-      const ref = record.$ref
-      const isInternal = ref.startsWith('#')
-      const isUri = ref.startsWith('http://') || ref.startsWith('https://')
-      const isPropertyFragment = isUri && ref.includes('#/properties/')
-      if (isInternal || (isUri && !isPropertyFragment)) {
-        refs.add(ref)
-      }
-      return // Don't traverse further into a $ref
-    }
-
-    // Check if this is an object type with additionalProperties that has a $ref
-    // This pattern requires validateRecord
-    if (hasAdditionalProperties(record) && hasRef(record.additionalProperties)) {
-      collectRefsFromValue(record.additionalProperties)
-      return
-    }
-
-    // Check if this is an array type with items that has a $ref
-    // This pattern requires validateArray
-    if (record.type === 'array' && hasItems(record) && hasRef(record.items)) {
-      collectRefsFromValue(record.items)
-      return
-    }
-
-    // Traverse nested properties regardless of whether `type` is explicitly set.
-    if ('properties' in record && typeof record.properties === 'object' && record.properties !== null) {
-      const props = record.properties as Record<string, unknown>
-      for (const key in props) {
-        collectRefsFromValue(props[key])
-      }
-    }
-
-    // Traverse into type composition keywords
-    if (hasOneOf(record)) {
-      for (const item of record.oneOf) {
-        collectRefsFromValue(item)
-      }
-    }
-    if (hasAnyOf(record)) {
-      for (const item of record.anyOf) {
-        collectRefsFromValue(item)
-      }
-    }
-    if (hasAllOf(record)) {
-      for (const item of record.allOf) {
-        collectRefsFromValue(item)
-      }
-    }
-
-    // Traverse into array items
-    if (hasItems(record)) {
-      collectRefsFromValue(record.items)
-    }
-
-    // Traverse into additionalProperties
-    if (hasAdditionalProperties(record)) {
-      collectRefsFromValue(record.additionalProperties)
-    }
-
-    // Traverse all patternProperties
-    if (
-      'patternProperties' in record &&
-      typeof record.patternProperties === 'object' &&
-      record.patternProperties !== null
-    ) {
-      const patternProps = record.patternProperties as Record<string, unknown>
-      for (const key in patternProps) {
-        collectRefsFromValue(patternProps[key])
-      }
-    }
-
-    // Traverse into if/then/else branches
-    if ('then' in record) {
-      collectRefsFromValue(record.then)
-    }
-    if ('else' in record) {
-      collectRefsFromValue(record.else)
-    }
-  }
-
-  // Collect refs from root-level $ref
-  if (typeof schema === 'object' && schema !== null && hasRef(schema)) {
-    const ref = schema.$ref
-    const isInternal = ref.startsWith('#')
-    const isUri = ref.startsWith('http://') || ref.startsWith('https://')
-    const isPropertyFragment = isUri && ref.includes('#/properties/')
-    if (isInternal || (isUri && !isPropertyFragment)) {
-      refs.add(ref)
-    }
-  }
-
-  // Collect refs from properties
-  if (typeof schema === 'object' && schema !== null && 'properties' in schema) {
-    const properties = schema.properties as Record<string, unknown>
-    for (const key in properties) {
-      collectRefsFromValue(properties[key])
-    }
-  }
-
-  // Collect refs from root-level additionalProperties
-  if (typeof schema === 'object' && schema !== null && 'additionalProperties' in schema) {
-    collectRefsFromValue(schema.additionalProperties)
-  }
-
-  // Collect refs from root-level patternProperties
-  if (typeof schema === 'object' && schema !== null && 'patternProperties' in schema) {
-    const patternProps = schema.patternProperties as Record<string, unknown>
-    for (const key in patternProps) {
-      collectRefsFromValue(patternProps[key])
-    }
-  }
-
-  // Collect refs from root-level items (when the schema itself is an array type)
-  if (typeof schema === 'object' && schema !== null && hasItems(schema)) {
-    collectRefsFromValue(schema.items)
-  }
-
-  // Collect refs from root-level composition keywords.
-  if (typeof schema === 'object' && schema !== null && hasOneOf(schema)) {
-    for (const item of schema.oneOf) {
-      collectRefsFromValue(item)
-    }
-  }
-  if (typeof schema === 'object' && schema !== null && hasAnyOf(schema)) {
-    for (const item of schema.anyOf) {
-      collectRefsFromValue(item)
-    }
-  }
-  if (typeof schema === 'object' && schema !== null && hasAllOf(schema)) {
-    for (const item of schema.allOf) {
-      collectRefsFromValue(item)
-    }
-  }
-
-  // Collect refs from root-level conditional branches.
-  if (typeof schema === 'object' && schema !== null && 'if' in schema) {
-    collectRefsFromValue(schema.if)
-  }
-  if (typeof schema === 'object' && schema !== null && 'then' in schema) {
-    collectRefsFromValue(schema.then)
-  }
-  if (typeof schema === 'object' && schema !== null && 'else' in schema) {
-    collectRefsFromValue(schema.else)
-  }
-
-  // Convert refs to combined import statements, deduplicating by filename
-  const importMap = new Map<string, string>()
-
-  for (const ref of refs) {
-    // For URI refs, skip if the base URI is not resolvable in the root schema.
-    // This prevents generating imports for external schemas that were never generated as files.
-    if (rootSchema !== undefined && (ref.startsWith('http://') || ref.startsWith('https://'))) {
-      if (!resolveRef(ref, rootSchema)) continue
-    }
-
-    const typeName = refToName(ref, typeSuffix)
-    const filename = refToFilename(ref)
-
-    // Skip self-referential imports — a file must not import from itself
-    if (selfFilename !== undefined && filename === selfFilename) {
-      continue
-    }
-
-    const importPath = getImportPathForFilename(filename)
-
-    // In types-only mode, omit the parser function import since there is no parser to call
-    const importStatement = typesOnly
-      ? `import type { ${typeName} } from '${importPath}';`
-      : `import { type ${typeName}, parse${typeName}, validate${typeName}Shape } from '${importPath}';`
-    importMap.set(filename, importStatement)
-  }
-
-  return Array.from(importMap.values()).sort()
-}

package/src/helpers/find-discriminator.test.ts

@@ -1,88 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { findDiscriminator } from './find-discriminator'
-
-describe('find-discriminator', () => {
-  it('finds discriminator when each schema has a unique const value', () => {
-    const schemas = [
-      { type: 'object' as const, properties: { kind: { const: 'a' } } },
-      { type: 'object' as const, properties: { kind: { const: 'b' } } },
-      { type: 'object' as const, properties: { kind: { const: 'c' } } },
-    ]
-    expect(findDiscriminator(schemas)).toBe('kind')
-  })
-
-  it('finds discriminator when each schema has a single enum value', () => {
-    const schemas = [
-      { type: 'object' as const, properties: { type: { enum: ['cat'] } } },
-      { type: 'object' as const, properties: { type: { enum: ['dog'] } } },
-    ]
-    expect(findDiscriminator(schemas)).toBe('type')
-  })
-
-  it('returns null when schemas share the same const value', () => {
-    const schemas = [
-      { type: 'object' as const, properties: { kind: { const: 'a' } } },
-      { type: 'object' as const, properties: { kind: { const: 'a' } } },
-    ]
-    expect(findDiscriminator(schemas)).toBeNull()
-  })
-
-  it('returns null when schemas have no properties', () => {
-    const schemas = [{ type: 'object' as const }, { type: 'object' as const }]
-    expect(findDiscriminator(schemas)).toBeNull()
-  })
-
-  it('returns null for empty schemas array', () => {
-    expect(findDiscriminator([])).toBeNull()
-  })
-
-  it('returns null when schemas are boolean', () => {
-    expect(findDiscriminator([true, false])).toBeNull()
-  })
-
-  it('returns null when not all schemas have the discriminator property', () => {
-    const schemas = [
-      { type: 'object' as const, properties: { kind: { const: 'a' } } },
-      { type: 'object' as const, properties: { name: { type: 'string' as const } } },
-    ]
-    expect(findDiscriminator(schemas)).toBeNull()
-  })
-
-  it('returns null when property has multi-value enum', () => {
-    const schemas = [
-      { type: 'object' as const, properties: { type: { enum: ['a', 'b'] } } },
-      { type: 'object' as const, properties: { type: { enum: ['c'] } } },
-    ]
-    // Multi-value enum does not count as a discriminator value
-    expect(findDiscriminator(schemas)).toBeNull()
-  })
-
-  it('returns null when property schema has no const or enum', () => {
-    const schemas = [
-      { type: 'object' as const, properties: { kind: { type: 'string' as const } } },
-      { type: 'object' as const, properties: { kind: { type: 'string' as const } } },
-    ]
-    expect(findDiscriminator(schemas)).toBeNull()
-  })
-
-  it('prefers the first property that matches across all schemas', () => {
-    const schemas = [
-      { type: 'object' as const, properties: { a: { const: 1 }, b: { const: 'x' } } },
-      { type: 'object' as const, properties: { a: { const: 2 }, b: { const: 'y' } } },
-    ]
-    // Both 'a' and 'b' are valid discriminators; returns the first one found
-    const result = findDiscriminator(schemas)
-    expect(result === 'a' || result === 'b').toBe(true)
-  })
-
-  it('ignores schemas without type object', () => {
-    const schemas = [{ type: 'string' as const }, { type: 'object' as const, properties: { kind: { const: 'a' } } }]
-    expect(findDiscriminator(schemas)).toBeNull()
-  })
-
-  it('handles schemas identified as objects by having properties without explicit type', () => {
-    const schemas = [{ properties: { kind: { const: 'a' } } }, { properties: { kind: { const: 'b' } } }]
-    expect(findDiscriminator(schemas)).toBe('kind')
-  })
-})

package/src/helpers/find-discriminator.ts

@@ -1,39 +0,0 @@
-import { hasConst, hasEnum, hasProperties, isObjectSchema, isSchemaObject } from '@amritk/helpers/schema-guards'
-import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
-
-/**
- * Attempts to find a discriminator property that can be used to distinguish between union types.
- * Returns the property name if a suitable discriminator is found, otherwise null.
- */
-export const findDiscriminator = (schemas: readonly JSONSchema[]): string | null => {
-  // Look for a property that has different constant/enum values in each schema
-  const propertyValues = new Map<string, Set<unknown>>()
-
-  for (const schema of schemas) {
-    if (isObjectSchema(schema) && hasProperties(schema)) {
-      for (const [key, propSchema] of Object.entries(schema.properties)) {
-        if (!propertyValues.has(key)) {
-          propertyValues.set(key, new Set())
-        }
-
-        // Check if property has a const value
-        if (isSchemaObject(propSchema) && hasConst(propSchema)) {
-          propertyValues.get(key)?.add(propSchema.const)
-        }
-        // Check if property has a single enum value
-        else if (isSchemaObject(propSchema) && hasEnum(propSchema) && propSchema.enum.length === 1) {
-          propertyValues.get(key)?.add(propSchema.enum[0])
-        }
-      }
-    }
-  }
-
-  // Find a property where each schema has a unique value
-  for (const [key, values] of propertyValues.entries()) {
-    if (values.size === schemas.length) {
-      return key
-    }
-  }
-
-  return null
-}

package/src/helpers/get-default-value.test.ts

@@ -1,139 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { getDefaultValue } from './get-default-value'
-
-describe('get-default-value', () => {
-  it('returns undefined for boolean schema', () => {
-    expect(getDefaultValue(true)).toBe('undefined')
-    expect(getDefaultValue(false)).toBe('undefined')
-  })
-
-  it('returns explicit default value when present', () => {
-    expect(getDefaultValue({ default: 'hello' })).toBe('"hello"')
-  })
-
-  it('returns explicit default for numeric value', () => {
-    expect(getDefaultValue({ default: 42 })).toBe('42')
-  })
-
-  it('returns explicit default for boolean value', () => {
-    expect(getDefaultValue({ default: true })).toBe('true')
-  })
-
-  it('returns explicit default for null', () => {
-    expect(getDefaultValue({ default: null })).toBe('null')
-  })
-
-  it('returns explicit default for object value', () => {
-    expect(getDefaultValue({ default: { key: 'value' } })).toBe('{"key":"value"}')
-  })
-
-  it('returns first enum value when no default', () => {
-    expect(getDefaultValue({ enum: ['a', 'b', 'c'] })).toBe('"a"')
-  })
-
-  it('returns first example value when no default or enum', () => {
-    expect(getDefaultValue({ examples: ['example1', 'example2'] })).toBe('"example1"')
-  })
-
-  it('returns default from first oneOf schema', () => {
-    const schema = {
-      oneOf: [{ type: 'string' as const, default: 'from-oneof' }, { type: 'number' as const }],
-    }
-    expect(getDefaultValue(schema)).toBe('"from-oneof"')
-  })
-
-  it('recurses into oneOf when first schema has no explicit default', () => {
-    const schema = {
-      oneOf: [{ type: 'string' as const }, { type: 'number' as const }],
-    }
-    expect(getDefaultValue(schema)).toBe('""')
-  })
-
-  it('returns default from first anyOf schema', () => {
-    const schema = {
-      anyOf: [{ type: 'number' as const }],
-    }
-    expect(getDefaultValue(schema)).toBe('0')
-  })
-
-  it('returns default from first allOf schema', () => {
-    const schema = {
-      allOf: [{ type: 'boolean' as const }],
-    }
-    expect(getDefaultValue(schema)).toBe('false')
-  })
-
-  it('returns undefined when no type is specified', () => {
-    expect(getDefaultValue({ description: 'no type' })).toBe('undefined')
-  })
-
-  it('returns empty string for string type', () => {
-    expect(getDefaultValue({ type: 'string' })).toBe('""')
-  })
-
-  it('returns 0 for number type', () => {
-    expect(getDefaultValue({ type: 'number' })).toBe('0')
-  })
-
-  it('returns 0 for integer type', () => {
-    expect(getDefaultValue({ type: 'integer' })).toBe('0')
-  })
-
-  it('returns false for boolean type', () => {
-    expect(getDefaultValue({ type: 'boolean' })).toBe('false')
-  })
-
-  it('returns empty array for array type', () => {
-    expect(getDefaultValue({ type: 'array' })).toBe('[]')
-  })
-
-  it('returns empty object for object type', () => {
-    expect(getDefaultValue({ type: 'object' })).toBe('{}')
-  })
-
-  it('returns undefined for unknown type', () => {
-    expect(getDefaultValue({ type: 'null' })).toBe('undefined')
-  })
-
-  it('uses pattern-based default for string with email pattern', () => {
-    const schema = { type: 'string' as const, pattern: '^[a-z]+@[a-z]+\\.[a-z]+$' }
-    expect(getDefaultValue(schema)).toBe('"user@example.com"')
-  })
-
-  it('falls back to empty string when pattern is not recognized', () => {
-    const schema = { type: 'string' as const, pattern: '^[a-z]+$' }
-    expect(getDefaultValue(schema)).toBe('""')
-  })
-
-  it('prioritizes default over enum', () => {
-    const schema = { default: 'explicit', enum: ['a', 'b'] }
-    expect(getDefaultValue(schema)).toBe('"explicit"')
-  })
-
-  it('prioritizes enum over examples', () => {
-    const schema = { enum: ['enumVal'], examples: ['exampleVal'] }
-    expect(getDefaultValue(schema)).toBe('"enumVal"')
-  })
-
-  it('prioritizes examples over type-based default', () => {
-    const schema = { type: 'string' as const, examples: ['myExample'] }
-    expect(getDefaultValue(schema)).toBe('"myExample"')
-  })
-
-  it('handles empty enum array and falls back', () => {
-    expect(getDefaultValue({ enum: [], type: 'string' })).toBe('""')
-  })
-
-  it('handles empty examples array and falls back', () => {
-    expect(getDefaultValue({ examples: [], type: 'number' })).toBe('0')
-  })
-
-  it('handles empty oneOf array and falls back', () => {
-    expect(getDefaultValue({ oneOf: [], type: 'boolean' })).toBe('false')
-  })
-
-  it('returns 0n for an x-mjst bigint schema', () => {
-    expect(getDefaultValue({ 'x-mjst': { primitive: 'bigint' } })).toBe('0n')
-  })
-})

package/src/helpers/get-default-value.ts

@@ -1,95 +0,0 @@
-import { getMjstPrimitive } from '@amritk/helpers/mjst-extension'
-import {
-  hasAllOf,
-  hasAnyOf,
-  hasDefault,
-  hasEnum,
-  hasExamples,
-  hasOneOf,
-  hasPattern,
-  hasType,
-  isSchemaObject,
-} from '@amritk/helpers/schema-guards'
-import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
-import { generateDefaultFromPattern } from '#generators/generate-default-from-pattern'
-
-/**
- * Returns the default value for a JSON Schema property.
- * Priority order: explicit default > first enum value > first example > union first schema > pattern-based > type-based.
- * These defaults ensure that parsing never fails, even with missing data.
- */
-export const getDefaultValue = (schema: JSONSchema): string => {
-  if (!isSchemaObject(schema)) {
-    return 'undefined'
-  }
-
-  // Explicit default takes highest priority
-  if (hasDefault(schema)) {
-    return JSON.stringify(schema.default)
-  }
-
-  // Use first enum value if available
-  if (hasEnum(schema) && schema.enum.length > 0) {
-    return JSON.stringify(schema.enum[0])
-  }
-
-  // Use first example if available
-  if (hasExamples(schema) && schema.examples.length > 0) {
-    return JSON.stringify(schema.examples[0])
-  }
-
-  // Handle union types - use first schema's default
-  if (hasOneOf(schema) && schema.oneOf.length > 0) {
-    const firstSchema = schema.oneOf[0]
-    if (firstSchema !== undefined) {
-      return getDefaultValue(firstSchema)
-    }
-  }
-
-  if (hasAnyOf(schema) && schema.anyOf.length > 0) {
-    const firstSchema = schema.anyOf[0]
-    if (firstSchema !== undefined) {
-      return getDefaultValue(firstSchema)
-    }
-  }
-
-  // Handle allOf - use first schema's default
-  if (hasAllOf(schema) && schema.allOf.length > 0) {
-    const firstSchema = schema.allOf[0]
-    if (firstSchema !== undefined) {
-      return getDefaultValue(firstSchema)
-    }
-  }
-
-  // x-mjst bigint has no native JSON type but a sensible zero default.
-  if (getMjstPrimitive(schema) === 'bigint') {
-    return '0n'
-  }
-
-  if (!hasType(schema)) {
-    return 'undefined'
-  }
-
-  switch (schema.type) {
-    case 'string': {
-      if (hasPattern(schema)) {
-        const patternDefault = generateDefaultFromPattern(schema.pattern)
-        if (patternDefault) {
-          return patternDefault
-        }
-      }
-      return '""'
-    }
-    case 'number':
-    case 'integer':
-      return '0'
-    case 'boolean':
-      return 'false'
-    case 'array':
-      return '[]'
-    case 'object':
-      return '{}'
-    default:
-      return 'undefined'
-  }
-}