@amritk/generate-parsers 0.7.1 → 0.8.0

package/src/generators/generate-files.test.ts

@@ -1,448 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { generateFile } from './generate-files'
-
-describe('generate-files', () => {
-  it('generates combined import for $ref property', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        contact: { $ref: '#/$defs/contact' },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Document')
-
-    expect(result).toContain("import { type Contact, parseContact, validateContactShape } from './contact';")
-  })
-
-  it('calls imported parser for optional $ref property', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        contact: { $ref: '#/$defs/contact' },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Document')
-
-    // With local variable caching, optional $ref properties use the cached variable
-    expect(result).toContain('_contact !== undefined && { contact: parseContact(_contact) }')
-  })
-
-  it('calls imported parser for required $ref property', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        contact: { $ref: '#/$defs/contact' },
-      },
-      required: ['contact'],
-    }
-
-    const { content: result } = generateFile(schema, 'Document')
-
-    // With local variable caching, required $ref properties use the cached variable
-    expect(result).toContain('contact: parseContact(_contact),')
-  })
-
-  it('generates combined imports for multiple $ref properties', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        contact: { $ref: '#/$defs/contact' },
-        server: { $ref: '#/$defs/server' },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Document')
-
-    expect(result).toContain("import { type Contact, parseContact, validateContactShape } from './contact';")
-    expect(result).toContain("import { type Server, parseServer, validateServerShape } from './server';")
-  })
-
-  it('generates correct parser name for multi-word $ref', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        externalDoc: { $ref: '#/$defs/external-documentation' },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Document')
-
-    expect(result).toContain(
-      "import { type ExternalDocumentation, parseExternalDocumentation, validateExternalDocumentationShape } from './external-documentation';",
-    )
-    expect(result).toContain('parseExternalDocumentation(_externalDoc)')
-  })
-
-  it('does not generate ref imports when no $ref properties exist', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        name: { type: 'string' },
-        age: { type: 'number' },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Simple')
-
-    // Should still import isObject helper
-    expect(result).toContain("import { isObject } from '@amritk/helpers/is-object';")
-    // But should not import any ref types (check for type imports specifically)
-    expect(result).not.toContain('import { type')
-  })
-
-  it('still validates non-ref properties inline', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        name: { type: 'string' },
-        contact: { $ref: '#/$defs/contact' },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Document')
-
-    // Non-ref property should have inline validation against the cached local
-    expect(result).toContain('typeof _name === "string"')
-    // Ref property should call imported parser using cached variable
-    expect(result).toContain('parseContact(_contact)')
-  })
-
-  it('generates a correct import for -or-reference style $ref names', () => {
-    // Without stripping, 'callbacks-or-reference' maps to the filename 'callbacks-or-reference'
-    const schema = {
-      type: 'object',
-      properties: {
-        callbacks: { $ref: '#/$defs/callbacks-or-reference' },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Document')
-
-    expect(result).toContain(
-      "import { type CallbacksOrReference, parseCallbacksOrReference, validateCallbacksOrReferenceShape } from './callbacks-or-reference';",
-    )
-    expect(result).toContain('parseCallbacksOrReference(_callbacks)')
-  })
-
-  it('generates arrow function parser', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        name: { type: 'string' },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Simple')
-
-    expect(result).toContain('export const parseSimple = (input: unknown): Simple =>')
-    expect(result).not.toContain('function parseSimple')
-  })
-
-  it('maps array items through imported parser for optional array with $ref items', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        servers: {
-          type: 'array',
-          items: { $ref: '#/$defs/server' },
-        },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Document')
-
-    expect(result).toContain("import { type Server, parseServer, validateServerShape } from './server';")
-    // With local variable caching, array validators use the cached variable
-    expect(result).toContain('validateArray(_servers, parseServer)')
-  })
-
-  it('maps array items through imported parser for required array with $ref items', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        servers: {
-          type: 'array',
-          items: { $ref: '#/$defs/server' },
-        },
-      },
-      required: ['servers'],
-    }
-
-    const { content: result } = generateFile(schema, 'Document')
-
-    // Check for required imports
-    expect(result).toContain("import { type Server, parseServer, validateServerShape } from './server';")
-    expect(result).toContain("import { validateArray } from '@amritk/helpers/validate-array';")
-    expect(result).toContain("import { isObject } from '@amritk/helpers/is-object';")
-
-    // Check for required array validation using cached variable
-    expect(result).toContain('servers: validateArray(_servers, parseServer),')
-
-    // Should not use spread operator for required fields
-    expect(result).not.toContain('...(_servers')
-  })
-
-  it('generates type and parser for schema with extension properties', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        name: { type: 'string' },
-        'x-enabled': { type: 'boolean' },
-        'x-internal': { type: 'boolean' },
-      },
-      required: ['name'],
-    }
-
-    const { content: result } = generateFile(schema, 'Parameter')
-
-    // Type should include extension properties as optional
-    expect(result).toContain("'x-enabled'?: boolean")
-    expect(result).toContain("'x-internal'?: boolean")
-    // Parser should validate extension properties
-    expect(result).toContain('x_enabled')
-    expect(result).toContain('x_internal')
-  })
-
-  it('generates type and parser for schema with complex extension property', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        summary: { type: 'string' },
-        'x-codegen': {
-          type: 'object',
-          properties: {
-            methodName: { type: 'string' },
-          },
-        },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Operation')
-
-    // Type should include the complex extension
-    expect(result).toContain("'x-codegen'")
-    expect(result).toContain('methodName')
-  })
-
-  it('omits parser function in types-only mode', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        name: { type: 'string' },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Simple', { typesOnly: true })
-
-    expect(result).toContain('export type Simple')
-    expect(result).not.toContain('export const parseSimple')
-  })
-
-  it('uses type-only imports for $ref properties in types-only mode', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        contact: { $ref: '#/$defs/contact' },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Document', { typesOnly: true })
-
-    expect(result).toContain("import type { Contact } from './contact';")
-    expect(result).not.toContain('parseContact')
-  })
-
-  it('does not include runtime helper imports in types-only mode', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        name: { type: 'string' },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Simple', { typesOnly: true })
-
-    // No parser helpers should be imported since there is no parser function
-    expect(result).not.toContain('import { isObject }')
-    expect(result).not.toContain('import { validateArray }')
-    expect(result).not.toContain('import { validateRecord }')
-  })
-
-  it('still generates the type definition in types-only mode', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        name: { type: 'string' },
-        age: { type: 'number' },
-      },
-      required: ['name'],
-    }
-
-    const { content: result } = generateFile(schema, 'User', { typesOnly: true })
-
-    expect(result).toContain('export type User')
-    expect(result).toContain('name: string')
-    expect(result).toContain('age?: number')
-  })
-
-  it('generates type-only import for array items $ref in types-only mode', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        servers: {
-          type: 'array',
-          items: { $ref: '#/$defs/server' },
-        },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Document', { typesOnly: true })
-
-    expect(result).toContain("import type { Server } from './server';")
-    expect(result).not.toContain('parseServer')
-    expect(result).not.toContain('validateArray')
-  })
-
-  it('generates type-only import for additionalProperties $ref in types-only mode', () => {
-    const schema = {
-      type: 'object',
-      additionalProperties: { $ref: '#/$defs/path-item' },
-    }
-
-    const { content: result } = generateFile(schema, 'Paths', { typesOnly: true })
-
-    expect(result).toContain("import type { PathItem } from './path-item';")
-    expect(result).not.toContain('parsePathItem')
-    expect(result).not.toContain('validateRecord')
-  })
-
-  it('generates type-only imports for oneOf $ref variants in types-only mode', () => {
-    const schema = {
-      oneOf: [{ $ref: '#/$defs/cat' }, { $ref: '#/$defs/dog' }],
-    }
-
-    const { content: result } = generateFile(schema, 'Pet', { typesOnly: true })
-
-    expect(result).toContain("import type { Cat } from './cat';")
-    expect(result).toContain("import type { Dog } from './dog';")
-    expect(result).not.toContain('parseCat')
-    expect(result).not.toContain('parseDog')
-  })
-
-  it('generates type-only imports for anyOf $ref variants in types-only mode', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        value: {
-          anyOf: [{ $ref: '#/$defs/string-value' }, { $ref: '#/$defs/number-value' }],
-        },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Wrapper', { typesOnly: true })
-
-    expect(result).toContain("import type { StringValue } from './string-value';")
-    expect(result).toContain("import type { NumberValue } from './number-value';")
-    expect(result).not.toContain('parseStringValue')
-    expect(result).not.toContain('parseNumberValue')
-  })
-
-  it('does not change default behavior when typesOnly is false', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        contact: { $ref: '#/$defs/contact' },
-      },
-    }
-
-    const { content: defaultResult } = generateFile(schema, 'Document')
-    const { content: explicitFalseResult } = generateFile(schema, 'Document', { typesOnly: false })
-
-    expect(defaultResult).toBe(explicitFalseResult)
-    expect(defaultResult).toContain("import { type Contact, parseContact, validateContactShape } from './contact';")
-    expect(defaultResult).toContain('export const parseDocument')
-  })
-
-  it('does not generate a self-import for recursive schemas in types-only mode', () => {
-    // Mirrors the 3.2.0 encoding schema: Encoding has properties itemEncoding, prefixEncoding,
-    // and encoding that all $ref back to #/$defs/encoding. The generated encoding.ts must not
-    // import Encoding from itself.
-    const schema = {
-      type: 'object',
-      properties: {
-        itemEncoding: { $ref: '#/$defs/encoding' },
-        prefixEncoding: {
-          type: 'array',
-          items: { $ref: '#/$defs/encoding' },
-        },
-        encoding: {
-          type: 'object',
-          additionalProperties: { $ref: '#/$defs/encoding' },
-        },
-        headers: {
-          type: 'object',
-          additionalProperties: { $ref: '#/$defs/header-or-reference' },
-        },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Encoding', {
-      typesOnly: true,
-      selfRef: '#/$defs/encoding',
-    })
-
-    expect(result).not.toContain("import type { Encoding } from './encoding';")
-    expect(result).toContain("import type { HeaderOrReference } from './header-or-reference';")
-    expect(result).toContain('export type Encoding')
-  })
-
-  it('does not generate a self-import for recursive schemas in full parser mode', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        itemEncoding: { $ref: '#/$defs/encoding' },
-        headers: {
-          type: 'object',
-          additionalProperties: { $ref: '#/$defs/header-or-reference' },
-        },
-      },
-    }
-
-    const { content: result } = generateFile(schema, 'Encoding', { selfRef: '#/$defs/encoding' })
-
-    expect(result).not.toContain("import { type Encoding, parseEncoding, validateEncodingShape } from './encoding';")
-    expect(result).toContain(
-      "import { type HeaderOrReference, parseHeaderOrReference, validateHeaderOrReferenceShape } from './header-or-reference';",
-    )
-  })
-
-  describe('typeSuffix', () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        contact: { $ref: '#/$defs/contact' },
-      },
-      required: ['contact'],
-    }
-
-    it('appends the suffix to ref-derived type, parser, and import names', () => {
-      const { content: result } = generateFile(schema, 'Document', { typeSuffix: 'Object' })
-
-      expect(result).toContain(
-        "import { type ContactObject, parseContactObject, validateContactObjectShape } from './contact';",
-      )
-      expect(result).toContain('contact: ContactObject;')
-      expect(result).toContain('contact: parseContactObject(_contact)')
-    })
-
-    it('emits no suffix by default', () => {
-      const { content: result } = generateFile(schema, 'Document')
-
-      expect(result).toContain("import { type Contact, parseContact, validateContactShape } from './contact';")
-      expect(result).not.toContain('ContactObject')
-    })
-  })
-})

package/src/generators/generate-files.ts

@@ -1,155 +0,0 @@
-import { generateTypeDefinition } from '@amritk/helpers/generate-type-definition'
-import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
-import {
-  type CollectedHelpers,
-  collectHelpers,
-  type HelpersMode,
-  type RuntimeHelperName,
-} from '#helpers/collect-helpers'
-import { collectImports } from '#helpers/collect-imports'
-
-import { generateParserFunction, generateShapeValidator } from './generate-parser-function'
-
-/**
- * Options for controlling what gets generated in a file.
- */
-type GenerateFileOptions = {
-  /**
-   * When true, only emit the TypeScript type definition and skip the parser function.
-   * Imports will be type-only as well, since there are no parsers to call.
-   */
-  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
-  /**
-   * The root schema document. When provided, URI refs that cannot be resolved
-   * within the root schema's $defs are excluded from the import list.
-   */
-  readonly rootSchema?: Record<string, unknown>
-  /**
-   * When true, the generated parser emits a console.warn for every input key
-   * that is not declared in the schema's properties.
-   */
-  readonly logWarnings?: boolean
-  /**
-   * When true, the generated parser throws on type/shape mismatches instead
-   * of coercing invalid input to default values.
-   */
-  readonly strict?: boolean
-  /**
-   * Controls how runtime helpers are referenced.
-   * - `'package'` (default): emit imports from `@amritk/helpers/...`.
-   * - `'embedded'`: emit imports from `./_helpers/...` so the helper sources can
-   *   be shipped alongside the generated files.
-   */
-  readonly helpersMode?: HelpersMode
-  /**
-   * Relative path prefix to the shared `_helpers/` directory in embedded mode.
-   * Defaults to `'./'`. The recursive multi-schema build passes `'../'`,
-   * `'../../'`, etc. so a nested parser can reach a single `_helpers/` directory
-   * at the output root.
-   */
-  readonly helpersImportPrefix?: string
-  /**
-   * When true, every property, array, and record in the generated type
-   * definitions is emitted as `readonly`.
-   */
-  readonly readonly?: boolean
-  /**
-   * Suffix appended to every type/parser name derived from a `$ref`.
-   * Defaults to `''` (no suffix). Set to e.g. `'Object'` to emit `ContactObject`.
-   */
-  readonly typeSuffix?: string
-}
-
-/** Result of generating a single parser file. */
-export type GeneratedFileContent = {
-  readonly content: string
-  readonly usedHelpers: ReadonlySet<RuntimeHelperName>
-}
-
-/**
- * Generates a complete TypeScript file from a JSON Schema.
- *
- * The generated file contains imports, type definition, and parser function.
- * When typesOnly is true, only the type definition is emitted without any parser.
- *
- * @param schema - The JSON Schema to generate code from
- * @param typeName - The name to use for the generated TypeScript type
- * @param options - Optional settings to control what gets generated
- * @returns The generated file content and the set of runtime helpers it references
- *
- * @example
- * ```typescript
- * const schema = {
- *   type: "object",
- *   properties: {
- *     name: { type: "string" },
- *     age: { type: "number" }
- *   },
- *   required: ["name"]
- * };
- *
- * const result = generateFile(schema, "User");
- * // result contains imports, type User, and parseUser function
- *
- * const typesOnly = generateFile(schema, "User", { typesOnly: true });
- * // typesOnly contains only type-only imports and type User (no parser)
- * ```
- */
-export const generateFile = (
-  schema: JSONSchema,
-  typeName: string,
-  options?: GenerateFileOptions,
-): GeneratedFileContent => {
-  const typesOnly = options?.typesOnly === true
-  const selfRef = options?.selfRef
-  const rootSchema = options?.rootSchema
-  const helpersMode: HelpersMode = options?.helpersMode ?? 'package'
-  const typeSuffix = options?.typeSuffix ?? ''
-  const typeDefinition = generateTypeDefinition(schema, typeName, { readonly: options?.readonly ?? false, typeSuffix })
-
-  if (typesOnly) {
-    // In types-only mode, skip the parser function and use type-only imports
-    const imports = collectImports(schema, { typesOnly: true, selfRef, rootSchema, typeSuffix })
-    let result = ''
-
-    if (imports.length > 0) {
-      result += imports[0]
-      for (let i = 1; i < imports.length; i++) {
-        result += '\n' + imports[i]
-      }
-      result += '\n\n'
-    }
-
-    return { content: result + typeDefinition, usedHelpers: new Set() }
-  }
-
-  const parserFunction = generateParserFunction(schema, typeName, {
-    useRefImports: true,
-    typeSuffix,
-    ...(options?.logWarnings !== undefined ? { logWarnings: options.logWarnings } : {}),
-    ...(options?.strict !== undefined ? { strict: options.strict } : {}),
-  })
-  const shapeValidator = generateShapeValidator(schema, typeName, true, typeSuffix)
-  const combinedFunctions = `${shapeValidator}\n\n${parserFunction}`
-  const helpers: CollectedHelpers = collectHelpers(combinedFunctions, helpersMode, options?.helpersImportPrefix)
-  const imports = [...collectImports(schema, { selfRef, rootSchema, typeSuffix }), ...helpers.imports]
-
-  // Build file output using string concatenation instead of array join for performance
-  let result = ''
-
-  if (imports.length > 0) {
-    result += imports[0]
-    for (let i = 1; i < imports.length; i++) {
-      result += '\n' + imports[i]
-    }
-    result += '\n\n'
-  }
-
-  return { content: result + typeDefinition + '\n\n' + combinedFunctions, usedHelpers: helpers.used }
-}

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

@@ -1,74 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { generateNonDiscriminatedUnionValidation } from './generate-non-discriminated-union-validation'
-
-describe('generate-non-discriminated-union-validation', () => {
-  it('generates OR chain for multiple schema checks', () => {
-    const schemas = [{ type: 'string' as const }, { type: 'number' as const }]
-    const result = generateNonDiscriminatedUnionValidation('value', schemas, '""', true)
-    expect(result).toContain('typeof value === "string"')
-    expect(result).toContain('typeof value === "number"')
-    expect(result).toContain('||')
-  })
-
-  it('returns fallback with nullish coalescing when required and no checks', () => {
-    const schemas = [{ description: 'no type' }]
-    const result = generateNonDiscriminatedUnionValidation('value', schemas, '""', true)
-    expect(result).toBe('value ?? ""')
-  })
-
-  it('returns accessor when not required and no checks', () => {
-    const schemas = [{ description: 'no type' }]
-    const result = generateNonDiscriminatedUnionValidation('value', schemas, '""', false)
-    expect(result).toBe('value')
-  })
-
-  it('wraps valid check in ternary with default value when required', () => {
-    const schemas = [{ type: 'string' as const }]
-    const result = generateNonDiscriminatedUnionValidation('value', schemas, '""', true)
-    expect(result).toBe('((typeof value === "string")) ? value : ""')
-  })
-
-  it('uses undefined as fallback when not required', () => {
-    const schemas = [{ type: 'string' as const }]
-    const result = generateNonDiscriminatedUnionValidation('value', schemas, '""', false)
-    expect(result).toBe('((typeof value === "string")) ? value : undefined')
-  })
-
-  it('handles schemas with multiple constraints combined with &&', () => {
-    const schemas = [{ type: 'string' as const, minLength: 1, maxLength: 100 }]
-    const result = generateNonDiscriminatedUnionValidation('value', schemas, '""', true)
-    expect(result).toContain('typeof value === "string"')
-    expect(result).toContain('value.length >= 1')
-    expect(result).toContain('value.length <= 100')
-    expect(result).toContain('&&')
-  })
-
-  it('handles empty schemas array when required', () => {
-    const result = generateNonDiscriminatedUnionValidation('value', [], '""', true)
-    expect(result).toBe('value ?? ""')
-  })
-
-  it('handles empty schemas array when not required', () => {
-    const result = generateNonDiscriminatedUnionValidation('value', [], '""', false)
-    expect(result).toBe('value')
-  })
-
-  it('generates multiple OR groups for different types', () => {
-    const schemas = [{ type: 'string' as const }, { type: 'number' as const }, { type: 'boolean' as const }]
-    const result = generateNonDiscriminatedUnionValidation('value', schemas, 'null', true)
-    expect(result).toContain('typeof value === "string"')
-    expect(result).toContain('typeof value === "number"')
-    expect(result).toContain('typeof value === "boolean"')
-    // Should use || between groups
-    const orCount = (result.match(/\|\|/g) || []).length
-    expect(orCount).toBe(2)
-  })
-
-  it('uses the provided accessor throughout', () => {
-    const schemas = [{ type: 'string' as const }]
-    const result = generateNonDiscriminatedUnionValidation('input?.name', schemas, '""', true)
-    expect(result).toContain('typeof input?.name === "string"')
-    expect(result).toContain('input?.name :')
-  })
-})