@amritk/generate-parsers 0.1.0 → 0.3.0

package/src/helpers/collect-imports.ts

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

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

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

@@ -0,0 +1,135 @@
+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')
+  })
+})

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

@@ -0,0 +1,89 @@
+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)
+    }
+  }
+
+  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'
+  }
+}