@amritk/generate-parsers 0.2.1 → 0.3.1

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

@@ -0,0 +1,435 @@
+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 ContactObject, parseContactObject, validateContactObjectShape } 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: parseContactObject(_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: parseContactObject(_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 ContactObject, parseContactObject, validateContactObjectShape } from './contact';",
+    )
+    expect(result).toContain(
+      "import { type ServerObject, parseServerObject, validateServerObjectShape } 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 ExternalDocumentationObject, parseExternalDocumentationObject, validateExternalDocumentationObjectShape } from './external-documentation';",
+    )
+    expect(result).toContain('parseExternalDocumentationObject(_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('parseContactObject(_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 CallbacksOrReferenceObject, parseCallbacksOrReferenceObject, validateCallbacksOrReferenceObjectShape } from './callbacks-or-reference';",
+    )
+    expect(result).toContain('parseCallbacksOrReferenceObject(_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 ServerObject, parseServerObject, validateServerObjectShape } from './server';",
+    )
+    // With local variable caching, array validators use the cached variable
+    expect(result).toContain('validateArray(_servers, parseServerObject)')
+  })
+
+  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 ServerObject, parseServerObject, validateServerObjectShape } 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, parseServerObject),')
+
+    // 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 { ContactObject } from './contact';")
+    expect(result).not.toContain('parseContactObject')
+  })
+
+  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 { ServerObject } from './server';")
+    expect(result).not.toContain('parseServerObject')
+    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 { PathItemObject } from './path-item';")
+    expect(result).not.toContain('parsePathItemObject')
+    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 { CatObject } from './cat';")
+    expect(result).toContain("import type { DogObject } from './dog';")
+    expect(result).not.toContain('parseCatObject')
+    expect(result).not.toContain('parseDogObject')
+  })
+
+  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 { StringValueObject } from './string-value';")
+    expect(result).toContain("import type { NumberValueObject } from './number-value';")
+    expect(result).not.toContain('parseStringValueObject')
+    expect(result).not.toContain('parseNumberValueObject')
+  })
+
+  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 ContactObject, parseContactObject, validateContactObjectShape } 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: EncodingObject has properties itemEncoding, prefixEncoding,
+    // and encoding that all $ref back to #/$defs/encoding. The generated encoding.ts must not
+    // import EncodingObject 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, 'EncodingObject', {
+      typesOnly: true,
+      selfRef: '#/$defs/encoding',
+    })
+
+    expect(result).not.toContain("import type { EncodingObject } from './encoding';")
+    expect(result).toContain("import type { HeaderOrReferenceObject } from './header-or-reference';")
+    expect(result).toContain('export type EncodingObject')
+  })
+
+  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, 'EncodingObject', { selfRef: '#/$defs/encoding' })
+
+    expect(result).not.toContain(
+      "import { type EncodingObject, parseEncodingObject, validateEncodingObjectShape } from './encoding';",
+    )
+    expect(result).toContain(
+      "import { type HeaderOrReferenceObject, parseHeaderOrReferenceObject, validateHeaderOrReferenceObjectShape } from './header-or-reference';",
+    )
+  })
+})

package/src/generators/generate-files.ts

@@ -0,0 +1,136 @@
+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
+}
+
+/** 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 typeDefinition = generateTypeDefinition(schema, typeName)
+
+  if (typesOnly) {
+    // In types-only mode, skip the parser function and use type-only imports
+    const imports = collectImports(schema, { typesOnly: true, selfRef, rootSchema })
+    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,
+    ...(options?.logWarnings !== undefined ? { logWarnings: options.logWarnings } : {}),
+    ...(options?.strict !== undefined ? { strict: options.strict } : {}),
+  })
+  const shapeValidator = generateShapeValidator(schema, typeName, true)
+  const combinedFunctions = `${shapeValidator}\n\n${parserFunction}`
+  const helpers: CollectedHelpers = collectHelpers(combinedFunctions, helpersMode)
+  const imports = [...collectImports(schema, { selfRef, rootSchema }), ...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

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

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

@@ -0,0 +1,40 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
+
+import { generateSchemaChecks } from './generate-schema-checks'
+
+/**
+ * Generates a non-discriminated union validation expression.
+ * Tries each schema in order until one matches.
+ */
+export const generateNonDiscriminatedUnionValidation = (
+  accessor: string,
+  schemas: readonly JSONSchema[],
+  defaultValue: string,
+  isRequired: boolean,
+): string => {
+  const cases: string[] = []
+
+  for (const schema of schemas) {
+    const checks = generateSchemaChecks(accessor, schema)
+
+    if (checks.length > 0) {
+      let combinedChecks = checks[0]
+      for (let i = 1; i < checks.length; i++) {
+        combinedChecks += ' && ' + checks[i]
+      }
+      cases.push('(' + combinedChecks + ')')
+    }
+  }
+
+  if (cases.length === 0) {
+    return isRequired ? `${accessor} ?? ${defaultValue}` : accessor
+  }
+
+  // Try each schema in order
+  let combinedCheck = cases[0]
+  for (let i = 1; i < cases.length; i++) {
+    combinedCheck += ' || ' + cases[i]
+  }
+  const finalDefault = isRequired ? defaultValue : 'undefined'
+  return `(${combinedCheck}) ? ${accessor} : ${finalDefault}`
+}