@amritk/generate-validators 0.2.1 → 0.2.3

package/dist/index.js

@@ -773,6 +773,9 @@ var generateTypeDefinition = (schema, typeName) => {
 };
 
 // ../helpers/dist/schema-guards.js
+var hasRef = (value) => {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && "$ref" in value && typeof value.$ref === "string";
+};
 var isSchemaObject3 = (schema) => {
   return typeof schema === "object" && schema !== null && typeof schema !== "boolean";
 };
@@ -830,9 +833,6 @@ var hasExclusiveMaximum = (schema) => {
 var hasMultipleOf = (schema) => {
   return isSchemaObject3(schema) && "multipleOf" in schema && typeof schema.multipleOf === "number";
 };
-var hasRef = (schema) => {
-  return isSchemaObject3(schema) && "$ref" in schema && typeof schema.$ref === "string";
-};
 
 // src/generators/collect-validator-imports.ts
 var buildImport = (ref) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-validators",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Generate TypeScript validation functions from JSON Schemas.",
   "module": "./dist/index.js",
   "type": "module",
@@ -24,7 +24,8 @@
     "url": "https://github.com/amritk/mjst/issues"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "publishConfig": {
     "access": "public"

package/src/generators/build-schema.test.ts

@@ -0,0 +1,163 @@
+import { validate } from '@scalar/openapi-parser'
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
+import { describe, expect, it } from 'vitest'
+
+import { buildValidatorSchema } from './build-schema'
+
+describe('build-schema', () => {
+  it('generates a validator file for the root schema', async () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: { title: { type: 'string' } },
+      required: ['title'],
+    }
+
+    const files = await buildValidatorSchema(schema, 'Document')
+    const filenames = files.map((f) => f.filename)
+
+    expect(filenames).toContain('document.ts')
+    expect(filenames).toContain('validation-result.ts')
+    expect(filenames).toContain('index.ts')
+  })
+
+  it('generates a file per $ref definition', async () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        info: { $ref: '#/$defs/info' },
+      },
+      $defs: {
+        info: {
+          type: 'object',
+          properties: { title: { type: 'string' } },
+          required: ['title'],
+        },
+      },
+    }
+
+    const files = await buildValidatorSchema(schema, 'Document')
+    const filenames = files.map((f) => f.filename)
+
+    expect(filenames).toContain('document.ts')
+    expect(filenames).toContain('info.ts')
+  })
+
+  it('generated document.ts exports a validateDocument function', async () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: { title: { type: 'string' } },
+      required: ['title'],
+    }
+
+    const files = await buildValidatorSchema(schema, 'Document')
+    const documentFile = files.find((f) => f.filename === 'document.ts')
+
+    expect(documentFile?.content).toContain('export const validateDocument')
+    expect(documentFile?.content).toContain('ValidationResult')
+  })
+
+  it('generated file imports the ref validator for $ref properties', async () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        info: { $ref: '#/$defs/info' },
+      },
+      $defs: {
+        info: {
+          type: 'object',
+          properties: { title: { type: 'string' } },
+        },
+      },
+    }
+
+    const files = await buildValidatorSchema(schema, 'Document')
+    const documentFile = files.find((f) => f.filename === 'document.ts')
+
+    expect(documentFile?.content).toContain("from './info'")
+    expect(documentFile?.content).toContain('validateInfoObject')
+  })
+
+  it('generates a valid index.ts with re-exports', async () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: { title: { type: 'string' } },
+    }
+
+    const files = await buildValidatorSchema(schema, 'Document')
+    const indexFile = files.find((f) => f.filename === 'index.ts')
+
+    expect(indexFile?.content).toContain("from './document'")
+    expect(indexFile?.content).toContain('validateDocument')
+  })
+
+  it('does not generate a file named validation-result for a schema ref', async () => {
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        result: { $ref: '#/$defs/validation-result' },
+      },
+      $defs: {
+        'validation-result': { type: 'object' },
+      },
+    }
+
+    const files = await buildValidatorSchema(schema, 'Document')
+    // Should still have exactly one validation-result.ts (the runtime contract)
+    const vrFiles = files.filter((f) => f.filename === 'validation-result.ts')
+    expect(vrFiles).toHaveLength(1)
+    expect(vrFiles[0]?.content).toContain('export type ValidationResult')
+  })
+
+  it('produces generated validators that agree with @scalar/openapi-parser on a valid document', async () => {
+    // Build validators for a minimal OpenAPI-like schema
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        openapi: { type: 'string' },
+        info: { $ref: '#/$defs/info' },
+      },
+      required: ['openapi', 'info'],
+      $defs: {
+        info: {
+          type: 'object',
+          properties: {
+            title: { type: 'string' },
+            version: { type: 'string' },
+          },
+          required: ['title', 'version'],
+        },
+      },
+    }
+
+    const files = await buildValidatorSchema(schema, 'Document')
+
+    // Sanity-check generated code shape
+    const documentFile = files.find((f) => f.filename === 'document.ts')
+    const infoFile = files.find((f) => f.filename === 'info.ts')
+
+    expect(documentFile?.content).toContain('validateDocument')
+    expect(infoFile?.content).toContain('validateInfoObject')
+
+    // Cross-check: @scalar/openapi-parser says a complete document is valid
+    const validDoc = { openapi: '3.1.0', info: { title: 'API', version: '1.0' }, paths: {} }
+    const refResult = await validate(validDoc)
+    expect(refResult.valid).toBe(true)
+
+    // Cross-check: @scalar/openapi-parser says a document missing info.title is invalid
+    const invalidDoc = { openapi: '3.1.0', info: { version: '1.0' }, paths: {} }
+    const refInvalid = await validate(invalidDoc)
+    expect(refInvalid.valid).toBe(false)
+    expect(refInvalid.errors.some((e) => e.message.includes('title'))).toBe(true)
+  })
+
+  it('emits a validation-result.ts with the runtime ValidationResult/ValidationError types', async () => {
+    const schema: JSONSchema = { type: 'object' }
+    const files = await buildValidatorSchema(schema, 'Doc')
+    const vrFile = files.find((f) => f.filename === 'validation-result.ts')
+
+    expect(vrFile?.content).toContain('export type ValidationError')
+    expect(vrFile?.content).toContain('export type ValidationResult')
+    expect(vrFile?.content).toContain('message: string')
+    expect(vrFile?.content).toContain('path: string')
+  })
+})

package/src/generators/build-schema.ts

@@ -0,0 +1,140 @@
+import { buildDynamicRefMap } from '@amritk/helpers/build-dynamic-ref-map'
+import { extractRefs } from '@amritk/helpers/extract-refs'
+import { refToFilename } from '@amritk/helpers/ref-to-filename'
+import { refToName } from '@amritk/helpers/ref-to-name'
+import { resolveDynamicRefs } from '@amritk/helpers/resolve-dynamic-refs'
+import { resolveRef } from '@amritk/helpers/resolve-ref'
+import { upgradeDraft07Schema } from '@amritk/helpers/upgrade-draft07-schema'
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
+
+import { generateValidatorFile } from './generate-files'
+
+/**
+ * Represents a generated TypeScript file with its filename and content.
+ */
+export type GeneratedFile = {
+  filename: string
+  content: string
+}
+
+const VALIDATION_RESULT_CONTENT = `/**
+ * A single validation error with a human-readable message and a JSON Pointer
+ * path indicating where in the document the error occurred.
+ */
+export type ValidationError = {
+  message: string
+  path: string
+}
+
+/**
+ * The result of a generated validator function.
+ * Returns \`true\` when the input is valid, or an object with \`valid: false\`
+ * and a list of errors when it is not.
+ */
+export type ValidationResult = true | { valid: false; errors: ValidationError[] }
+`
+
+/**
+ * Builds all TypeScript validator files from a JSON Schema by traversing
+ * all $ref references recursively, mirroring the generate-parsers pipeline.
+ *
+ * Each generated file exports:
+ * - A TypeScript type definition
+ * - A `validateFoo(input: unknown, _path?: string): ValidationResult` function
+ *
+ * A `validation-result.ts` file containing the `ValidationResult` and `ValidationError`
+ * runtime contract is always emitted. An `index.ts` re-exports everything.
+ *
+ * @param rootSchema - The root JSON Schema to build from
+ * @param rootTypeName - The name for the root type (e.g. "Document")
+ * @returns An array of generated TypeScript files
+ *
+ * @example
+ * ```typescript
+ * const files = await buildValidatorSchema(schema, 'Document')
+ * // files → [{ filename: 'document.ts', content: '...' }, { filename: 'info.ts', ... }, ...]
+ * ```
+ */
+export const buildValidatorSchema = async (rootSchema: JSONSchema, rootTypeName: string): Promise<GeneratedFile[]> => {
+  rootSchema = upgradeDraft07Schema(rootSchema as Record<string, unknown>) as JSONSchema
+
+  const files: GeneratedFile[] = []
+  const processedRefs = new Set<string>()
+  const processedFilenames = new Set<string>()
+  const refsToProcess: string[] = []
+
+  const dynamicRefMap = buildDynamicRefMap(rootSchema)
+
+  // Root schema
+  const processedRootSchema = resolveDynamicRefs(rootSchema, dynamicRefMap)
+  const rootContent = generateValidatorFile(processedRootSchema, rootTypeName, {
+    rootSchema: rootSchema as Record<string, unknown>,
+  })
+  const rootFilename = rootTypeName.toLowerCase()
+
+  if (rootFilename !== 'validation-result') {
+    processedFilenames.add(rootFilename)
+    files.push({ filename: `${rootFilename}.ts`, content: rootContent })
+  }
+
+  const rootRefs = extractRefs(rootSchema)
+  refsToProcess.push(...rootRefs)
+
+  while (refsToProcess.length > 0) {
+    const ref = refsToProcess.shift()
+    if (!ref || processedRefs.has(ref)) continue
+    processedRefs.add(ref)
+
+    const resolvedSchema = resolveRef(ref, rootSchema as Record<string, unknown>)
+    if (!resolvedSchema) {
+      console.warn(`Warning: Could not resolve ref: ${ref}`)
+      continue
+    }
+
+    const typeName = refToName(ref)
+    const filename = refToFilename(ref)
+    const processedSchema = resolveDynamicRefs(resolvedSchema as JSONSchema, dynamicRefMap)
+    const content = generateValidatorFile(processedSchema, typeName, {
+      selfRef: ref,
+      rootSchema: rootSchema as Record<string, unknown>,
+    })
+
+    if (filename !== 'validation-result' && !processedFilenames.has(filename)) {
+      processedFilenames.add(filename)
+      files.push({ filename: `${filename}.ts`, content })
+    }
+
+    for (const nestedRef of extractRefs(resolvedSchema as JSONSchema)) {
+      if (!processedRefs.has(nestedRef)) refsToProcess.push(nestedRef)
+    }
+  }
+
+  // Emit the runtime contract for validators. ValidationResult is mjst-defined
+  // (not derived from the input schema), so its content is fixed.
+  files.push({ filename: 'validation-result.ts', content: VALIDATION_RESULT_CONTENT })
+
+  // Generate index.ts
+  const TYPE_EXPORT_RE = /^export type (\w+)/gm
+  const CONST_EXPORT_RE = /^export const (\w+)/gm
+
+  const sortedFiles = [...files].sort((a, b) => a.filename.localeCompare(b.filename))
+  let indexContent = ''
+
+  for (const file of sortedFiles) {
+    const moduleName = file.filename.replace(/\.ts$/, '')
+    const typeNames: string[] = []
+    const constNames: string[] = []
+
+    for (const match of file.content.matchAll(TYPE_EXPORT_RE)) typeNames.push(match[1] as string)
+    for (const match of file.content.matchAll(CONST_EXPORT_RE)) constNames.push(match[1] as string)
+
+    if (typeNames.length === 0 && constNames.length === 0) continue
+
+    const typeExports = typeNames.map((n) => `type ${n}`)
+    indexContent += `export { ${[...typeExports, ...constNames].join(', ')} } from './${moduleName}';\n`
+  }
+
+  files.push({ filename: 'index.ts', content: indexContent })
+
+  return files
+}

package/src/generators/collect-validator-imports.ts

@@ -0,0 +1,128 @@
+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'
+
+/**
+ * Options for controlling how validator imports are collected.
+ */
+type CollectValidatorImportsOptions = {
+  /**
+   * The $ref path of the schema being generated (e.g. `#/$defs/encoding`).
+   * Prevents a file from importing itself.
+   */
+  readonly selfRef?: string | undefined
+  /**
+   * The root schema document. URI refs that cannot be resolved within it
+   * are excluded from the import list (they were never generated as files).
+   */
+  readonly rootSchema?: Record<string, unknown> | undefined
+}
+
+/**
+ * Generates an import statement for a single $ref, importing both the type
+ * and the validator function from the ref's generated file.
+ */
+const buildImport = (ref: string): string => {
+  const filename = refToFilename(ref)
+  const typeName = refToName(ref)
+  const validatorName = `validate${typeName}`
+  return `import { type ${typeName}, ${validatorName} } from './${filename}'`
+}
+
+/**
+ * Resolves the canonical filename for a ref, stripping `-or-reference` suffixes
+ * so that `#/$defs/parameter-or-reference` maps to `parameter`.
+ */
+const canonicalFilename = (ref: string): string => {
+  const base = ref.endsWith('-or-reference') ? ref.replace('-or-reference', '') : ref
+  return refToFilename(base)
+}
+
+/**
+ * Walks one level of the schema and yields all direct $ref strings that should
+ * become imports: properties, additionalProperties, items, and union branches.
+ */
+const collectDirectRefs = (schema: JSONSchema): string[] => {
+  if (typeof schema === 'boolean' || schema === null) return []
+
+  const refs: string[] = []
+
+  if (hasRef(schema)) {
+    refs.push(schema.$ref)
+    return refs
+  }
+
+  const propSchemas =
+    'properties' in schema && typeof schema.properties === 'object' && schema.properties !== null
+      ? Object.values(schema.properties as Record<string, JSONSchema>)
+      : []
+
+  for (const prop of propSchemas) {
+    if (hasRef(prop)) refs.push((prop as { $ref: string }).$ref)
+    if (hasItems(prop) && hasRef(prop.items)) refs.push((prop.items as { $ref: string }).$ref)
+    if (hasAdditionalProperties(prop) && hasRef(prop.additionalProperties as JSONSchema)) {
+      refs.push((prop.additionalProperties as { $ref: string }).$ref)
+    }
+  }
+
+  if (hasItems(schema) && hasRef(schema.items)) {
+    refs.push((schema.items as { $ref: string }).$ref)
+  }
+
+  if (hasAdditionalProperties(schema) && hasRef(schema.additionalProperties as JSONSchema)) {
+    refs.push((schema.additionalProperties as { $ref: string }).$ref)
+  }
+
+  for (const branch of [
+    ...(hasOneOf(schema) ? schema.oneOf : []),
+    ...(hasAnyOf(schema) ? schema.anyOf : []),
+    ...(hasAllOf(schema) ? schema.allOf : []),
+  ]) {
+    if (hasRef(branch)) refs.push((branch as { $ref: string }).$ref)
+  }
+
+  return refs
+}
+
+/**
+ * Collects import statements for all $ref dependencies of a schema.
+ * Each import brings in both the generated TypeScript type and validator function.
+ *
+ * @example
+ * ```typescript
+ * const schema = { properties: { contact: { $ref: '#/$defs/contact' } } }
+ * collectValidatorImports(schema)
+ * // ["import { type ContactObject, validateContactObject } from './contact-object'"]
+ * ```
+ */
+export const collectValidatorImports = (schema: JSONSchema, options?: CollectValidatorImportsOptions): string[] => {
+  const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : null
+  const rootSchema = options?.rootSchema
+
+  const refs = collectDirectRefs(schema)
+  const seen = new Set<string>()
+  const imports: string[] = []
+
+  for (const ref of refs) {
+    const filename = canonicalFilename(ref)
+
+    if (seen.has(filename)) continue
+    if (selfFilename && filename === selfFilename) continue
+
+    // Skip refs that don't resolve in this schema (external / never generated)
+    if (rootSchema) {
+      const resolved = resolveRef(ref, rootSchema)
+      if (!resolved) continue
+    }
+
+    seen.add(filename)
+
+    // -or-reference unions import the base type's validator
+    const importRef = ref.endsWith('-or-reference') ? ref.replace('-or-reference', '') : ref
+    imports.push(buildImport(importRef))
+  }
+
+  return imports
+}

package/src/generators/generate-files.ts

@@ -0,0 +1,72 @@
+import { generateTypeDefinition } from '@amritk/helpers/generate-type-definition'
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
+
+import { collectValidatorImports } from './collect-validator-imports'
+import { generateValidatorFunction } from './generate-validator-function'
+
+/**
+ * Options for controlling what gets generated in a validator file.
+ */
+type GenerateValidatorFileOptions = {
+  /**
+   * The $ref path of the schema being generated (e.g. `#/$defs/info`).
+   * Prevents the file from importing itself.
+   */
+  readonly selfRef?: string
+  /**
+   * The root schema document. Used to filter out unresolvable refs.
+   */
+  readonly rootSchema?: Record<string, unknown>
+}
+
+/**
+ * Generates a complete TypeScript validator file from a JSON Schema.
+ *
+ * The file contains:
+ * - Imports for the ValidationResult/ValidationError types
+ * - Imports for any $ref types and their validator functions
+ * - The exported TypeScript type definition
+ * - The exported validator function
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   type: 'object',
+ *   properties: { title: { type: 'string' } },
+ *   required: ['title'],
+ * }
+ * generateValidatorFile(schema, 'Info')
+ * // import type { ValidationResult, ValidationError } from './validation-result'
+ * // export type Info = { title: string }
+ * // export const validateInfo = (input: unknown, _path = ''): ValidationResult => { ... }
+ * ```
+ */
+export const generateValidatorFile = (
+  schema: JSONSchema,
+  typeName: string,
+  options?: GenerateValidatorFileOptions,
+): string => {
+  const refImports = collectValidatorImports(schema, {
+    selfRef: options?.selfRef,
+    rootSchema: options?.rootSchema,
+  })
+
+  const typeDefinition = generateTypeDefinition(schema, typeName)
+  const validatorFunction = generateValidatorFunction(schema, typeName)
+
+  let result = `import type { ValidationResult, ValidationError } from './validation-result'\n`
+
+  for (const imp of refImports) {
+    result += imp + '\n'
+  }
+
+  if (refImports.length > 0) {
+    result += '\n'
+  } else {
+    result += '\n'
+  }
+
+  result += typeDefinition + '\n\n' + validatorFunction
+
+  return result
+}

package/src/generators/generate-validator-function.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, it } from 'vitest'
+
+import { generateValidatorFunction } from './generate-validator-function'
+
+// Eval helper: compiles a generated function string in context of a minimal
+// ValidationResult runtime so we can actually run the generated code.
+const _evalValidator = (code: string): ((input: unknown, path?: string) => unknown) => {
+  const _wrapped = `
+    const ValidationResult = null // type-only
+    ${code}
+  `
+  // eslint-disable-next-line no-new-func
+  return new Function(`
+    ${code}
+    return validate${code.match(/export const validate(\w+)/)?.[1] ?? ''}
+  `)() as (input: unknown, path?: string) => unknown
+}
+
+describe('generate-validator-function', () => {
+  it('generates a validator for a required string property', () => {
+    const schema = {
+      type: 'object' as const,
+      properties: { name: { type: 'string' as const } },
+      required: ['name'],
+    }
+    const code = generateValidatorFunction(schema, 'Info')
+
+    expect(code).toContain('export const validateInfo')
+    expect(code).toContain('"name" in obj')
+    expect(code).toContain("must have required property 'name'")
+    expect(code).toContain('typeof obj["name"] !== \'string\'')
+    expect(code).toContain('must be string')
+  })
+
+  it('generates a validator for an optional number property', () => {
+    const schema = {
+      type: 'object' as const,
+      properties: { count: { type: 'number' as const } },
+    }
+    const code = generateValidatorFunction(schema, 'Stats')
+
+    expect(code).toContain('obj["count"] !== undefined')
+    expect(code).toContain('typeof obj["count"] !== \'number\'')
+    expect(code).toContain('must be number')
+  })
+
+  it('generates a validator for a boolean property', () => {
+    const schema = {
+      type: 'object' as const,
+      properties: { enabled: { type: 'boolean' as const } },
+      required: ['enabled'],
+    }
+    const code = generateValidatorFunction(schema, 'Config')
+
+    expect(code).toContain('typeof obj["enabled"] !== \'boolean\'')
+    expect(code).toContain('must be boolean')
+  })
+
+  it('generates required-property check at parent path', () => {
+    const schema = {
+      type: 'object' as const,
+      properties: { title: { type: 'string' as const } },
+      required: ['title'],
+    }
+    const code = generateValidatorFunction(schema, 'Doc')
+
+    // Required errors use _path (parent), not a child path
+    expect(code).toContain('path: _path')
+    expect(code).toContain("must have required property 'title'")
+  })
+
+  it('generates type error at child path', () => {
+    const schema = {
+      type: 'object' as const,
+      properties: { title: { type: 'string' as const } },
+      required: ['title'],
+    }
+    const code = generateValidatorFunction(schema, 'Doc')
+
+    // Type errors use the child path
+    expect(code).toContain('`${_path}/title`')
+  })
+
+  it('generates an enum validator', () => {
+    const schema = {
+      enum: ['get', 'post', 'put', 'delete'],
+    }
+    const code = generateValidatorFunction(schema as Parameters<typeof generateValidatorFunction>[0], 'Method')
+
+    expect(code).toContain('must be one of')
+    expect(code).toContain('"get"')
+    expect(code).toContain('"post"')
+  })
+
+  it('generates a string pattern check', () => {
+    const schema = {
+      type: 'object' as const,
+      properties: { version: { type: 'string' as const, pattern: '^\\d+\\.\\d+' } },
+      required: ['version'],
+    }
+    const code = generateValidatorFunction(schema, 'Info')
+
+    expect(code).toContain('must match pattern')
+    expect(code).toContain('.test(')
+  })
+
+  it('generates min/maxLength checks', () => {
+    const schema = {
+      type: 'object' as const,
+      properties: { name: { type: 'string' as const, minLength: 1, maxLength: 100 } },
+      required: ['name'],
+    }
+    const code = generateValidatorFunction(schema, 'Info')
+
+    expect(code).toContain('must have at least 1 characters')
+    expect(code).toContain('must have at most 100 characters')
+  })
+
+  it('generates minimum/maximum checks', () => {
+    const schema = {
+      type: 'object' as const,
+      properties: { port: { type: 'number' as const, minimum: 0, maximum: 65535 } },
+    }
+    const code = generateValidatorFunction(schema, 'Server')
+
+    expect(code).toContain('>= 0')
+    expect(code).toContain('<= 65535')
+  })
+
+  it('generates a $ref property delegation', () => {
+    const schema = {
+      type: 'object' as const,
+      properties: { info: { $ref: '#/$defs/info' } },
+      required: ['info'],
+    }
+    const code = generateValidatorFunction(schema, 'Document')
+
+    expect(code).toContain('validateInfoObject(')
+    expect(code).toContain('"info" in obj')
+  })
+
+  it('generates a scalar string validator', () => {
+    const schema = { type: 'string' as const }
+    const code = generateValidatorFunction(schema, 'StringValue')
+
+    expect(code).toContain("typeof input !== 'string'")
+    expect(code).toContain('must be string')
+  })
+
+  it('returns true for empty object schemas', () => {
+    const schema = { type: 'object' as const }
+    const code = generateValidatorFunction(schema, 'Empty')
+
+    expect(code).toContain('validateEmpty')
+    expect(code).toContain('must be object')
+    expect(code).toContain('return errors.length > 0')
+  })
+
+  it('generates object guard at top of object validator', () => {
+    const schema = { type: 'object' as const, properties: { x: { type: 'string' as const } } }
+    const code = generateValidatorFunction(schema, 'Foo')
+
+    expect(code).toContain("typeof input !== 'object'")
+    expect(code).toContain('Array.isArray(input)')
+    expect(code).toContain('must be object')
+  })
+})

package/src/generators/generate-validator-function.ts

@@ -0,0 +1,399 @@
+import { refToName } from '@amritk/helpers/ref-to-name'
+import {
+  hasAdditionalProperties,
+  hasEnum,
+  hasExclusiveMaximum,
+  hasExclusiveMinimum,
+  hasItems,
+  hasMaximum,
+  hasMaxLength,
+  hasMinimum,
+  hasMinLength,
+  hasMultipleOf,
+  hasOneOf,
+  hasPattern,
+  hasProperties,
+  hasRef,
+  hasRequired,
+  hasType,
+  isObjectSchema,
+  isSchemaObject,
+} from '@amritk/helpers/schema-guards'
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
+
+/**
+ * Derives the validator function name from a type name.
+ * e.g. "InfoObject" → "validateInfoObject"
+ */
+const validatorName = (typeName: string): string => `validate${typeName}`
+
+/**
+ * Returns the TypeScript typeof string for a JSON Schema primitive type.
+ */
+const typeofString = (type: string): string => {
+  if (type === 'integer') return 'number'
+  return type
+}
+
+/**
+ * Generates the inline condition that is TRUE when a value is the wrong type.
+ */
+const wrongTypeCondition = (accessor: string, type: string): string => {
+  switch (type) {
+    case 'string':
+      return `typeof ${accessor} !== 'string'`
+    case 'number':
+    case 'integer':
+      return `typeof ${accessor} !== 'number'`
+    case 'boolean':
+      return `typeof ${accessor} !== 'boolean'`
+    case 'array':
+      return `!Array.isArray(${accessor})`
+    case 'object':
+      return `typeof ${accessor} !== 'object' || ${accessor} === null || Array.isArray(${accessor})`
+    default:
+      return ''
+  }
+}
+
+/**
+ * Generates validation lines for a single property in an object schema.
+ * Handles $ref delegation, enum checks, type checks, and string/number constraints.
+ */
+const generatePropertyChecks = (key: string, propSchema: JSONSchema, isRequired: boolean): string[] => {
+  if (!isSchemaObject(propSchema)) return []
+
+  const raw = `obj[${JSON.stringify(key)}]`
+  const path = `\`\${_path}/${key}\``
+  const lines: string[] = []
+
+  // $ref — delegate to the imported validator
+  if (hasRef(propSchema)) {
+    const ref = propSchema.$ref
+    const vName = validatorName(refToName(ref))
+
+    if (isRequired) {
+      lines.push(`  if (!(${JSON.stringify(key)} in obj)) {`)
+      lines.push(`    errors.push({ message: "must have required property '${key}'", path: _path })`)
+      lines.push(`  } else {`)
+      lines.push(`    const _r = ${vName}(${raw}, ${path})`)
+      lines.push(`    if (_r !== true) errors.push(..._r.errors)`)
+      lines.push(`  }`)
+    } else {
+      lines.push(`  if (${raw} !== undefined) {`)
+      lines.push(`    const _r = ${vName}(${raw}, ${path})`)
+      lines.push(`    if (_r !== true) errors.push(..._r.errors)`)
+      lines.push(`  }`)
+    }
+    return lines
+  }
+
+  // enum
+  if (hasEnum(propSchema)) {
+    const allowed = JSON.stringify(propSchema.enum)
+    const label = (propSchema.enum as unknown[]).map((v) => JSON.stringify(v)).join(', ')
+
+    if (isRequired) {
+      lines.push(`  if (!(${JSON.stringify(key)} in obj)) {`)
+      lines.push(`    errors.push({ message: "must have required property '${key}'", path: _path })`)
+      lines.push(`  } else if (!(${allowed} as unknown[]).includes(${raw})) {`)
+      lines.push(`    errors.push({ message: \`must be one of: ${label}\`, path: ${path} })`)
+      lines.push(`  }`)
+    } else {
+      lines.push(`  if (${raw} !== undefined && !(${allowed} as unknown[]).includes(${raw})) {`)
+      lines.push(`    errors.push({ message: \`must be one of: ${label}\`, path: ${path} })`)
+      lines.push(`  }`)
+    }
+    return lines
+  }
+
+  // typed property
+  if (hasType(propSchema)) {
+    const t = propSchema.type as string
+    const wrongType = wrongTypeCondition(raw, t)
+    const typLabel = typeofString(t)
+
+    if (isRequired) {
+      lines.push(`  if (!(${JSON.stringify(key)} in obj)) {`)
+      lines.push(`    errors.push({ message: "must have required property '${key}'", path: _path })`)
+      if (wrongType) {
+        lines.push(`  } else if (${wrongType}) {`)
+        lines.push(`    errors.push({ message: 'must be ${typLabel}', path: ${path} })`)
+      }
+      lines.push(`  }`)
+    } else if (wrongType) {
+      lines.push(`  if (${raw} !== undefined && (${wrongType})) {`)
+      lines.push(`    errors.push({ message: 'must be ${typLabel}', path: ${path} })`)
+      lines.push(`  }`)
+    }
+
+    // String constraints
+    if (t === 'string') {
+      if (hasPattern(propSchema)) {
+        lines.push(`  if (typeof ${raw} === 'string' && !/${propSchema.pattern}/.test(${raw})) {`)
+        lines.push(`    errors.push({ message: 'must match pattern ${propSchema.pattern}', path: ${path} })`)
+        lines.push(`  }`)
+      }
+      if (hasMinLength(propSchema)) {
+        lines.push(`  if (typeof ${raw} === 'string' && ${raw}.length < ${propSchema.minLength}) {`)
+        lines.push(
+          `    errors.push({ message: 'must have at least ${propSchema.minLength} characters', path: ${path} })`,
+        )
+        lines.push(`  }`)
+      }
+      if (hasMaxLength(propSchema)) {
+        lines.push(`  if (typeof ${raw} === 'string' && ${raw}.length > ${propSchema.maxLength}) {`)
+        lines.push(
+          `    errors.push({ message: 'must have at most ${propSchema.maxLength} characters', path: ${path} })`,
+        )
+        lines.push(`  }`)
+      }
+    }
+
+    // Number constraints
+    if (t === 'number' || t === 'integer') {
+      if (hasMinimum(propSchema)) {
+        lines.push(`  if (typeof ${raw} === 'number' && ${raw} < ${propSchema.minimum}) {`)
+        lines.push(`    errors.push({ message: 'must be >= ${propSchema.minimum}', path: ${path} })`)
+        lines.push(`  }`)
+      }
+      if (hasMaximum(propSchema)) {
+        lines.push(`  if (typeof ${raw} === 'number' && ${raw} > ${propSchema.maximum}) {`)
+        lines.push(`    errors.push({ message: 'must be <= ${propSchema.maximum}', path: ${path} })`)
+        lines.push(`  }`)
+      }
+      if (hasExclusiveMinimum(propSchema)) {
+        lines.push(`  if (typeof ${raw} === 'number' && ${raw} <= ${propSchema.exclusiveMinimum}) {`)
+        lines.push(`    errors.push({ message: 'must be > ${propSchema.exclusiveMinimum}', path: ${path} })`)
+        lines.push(`  }`)
+      }
+      if (hasExclusiveMaximum(propSchema)) {
+        lines.push(`  if (typeof ${raw} === 'number' && ${raw} >= ${propSchema.exclusiveMaximum}) {`)
+        lines.push(`    errors.push({ message: 'must be < ${propSchema.exclusiveMaximum}', path: ${path} })`)
+        lines.push(`  }`)
+      }
+      if (hasMultipleOf(propSchema)) {
+        lines.push(`  if (typeof ${raw} === 'number' && ${raw} % ${propSchema.multipleOf} !== 0) {`)
+        lines.push(`    errors.push({ message: 'must be a multiple of ${propSchema.multipleOf}', path: ${path} })`)
+        lines.push(`  }`)
+      }
+    }
+
+    // Array with typed items
+    if (t === 'array' && hasItems(propSchema)) {
+      const itemSchema = propSchema.items
+      if (hasRef(itemSchema)) {
+        const vName = validatorName(refToName(itemSchema.$ref))
+        lines.push(`  if (Array.isArray(${raw})) {`)
+        lines.push(`    for (let _i = 0; _i < ${raw}.length; _i++) {`)
+        lines.push(`      const _ir = ${vName}(${raw}[_i], \`${path.slice(1, -1)}/${key}/\${_i}\`)`)
+        lines.push(`      if (_ir !== true) errors.push(..._ir.errors)`)
+        lines.push(`    }`)
+        lines.push(`  }`)
+      } else if (hasType(itemSchema)) {
+        const itemType = itemSchema.type as string
+        const itemWrong = wrongTypeCondition('_item', itemType)
+        const itemLabel = typeofString(itemType)
+        if (itemWrong) {
+          lines.push(`  if (Array.isArray(${raw})) {`)
+          lines.push(`    for (let _i = 0; _i < ${raw}.length; _i++) {`)
+          lines.push(`      const _item = ${raw}[_i]`)
+          lines.push(
+            `      if (${itemWrong}) errors.push({ message: 'items must be ${itemLabel}', path: \`${path.slice(1, -1)}/${key}/\${_i}\` })`,
+          )
+          lines.push(`    }`)
+          lines.push(`  }`)
+        }
+      }
+    }
+  }
+
+  return lines
+}
+
+/**
+ * Generates a validator function body for an object schema, checking each
+ * property's presence and type and collecting all errors.
+ */
+const generateObjectValidator = (schema: JSONSchema, typeName: string): string => {
+  const vName = validatorName(typeName)
+  const required = new Set(hasRequired(schema) ? schema.required : [])
+  const properties = hasProperties(schema) ? schema.properties : {}
+
+  const propertyLines: string[] = []
+
+  for (const [key, propSchema] of Object.entries(properties)) {
+    const checks = generatePropertyChecks(key, propSchema as JSONSchema, required.has(key))
+    if (checks.length > 0) {
+      propertyLines.push(...checks)
+    }
+  }
+
+  // additionalProperties with a $ref schema validates all extra keys
+  if (
+    hasAdditionalProperties(schema) &&
+    isSchemaObject(schema.additionalProperties) &&
+    hasRef(schema.additionalProperties)
+  ) {
+    const vRefName = validatorName(refToName(schema.additionalProperties.$ref))
+    propertyLines.push(`  for (const _key of Object.keys(obj)) {`)
+    propertyLines.push(`    if (${JSON.stringify(Object.keys(properties))}.includes(_key)) continue`)
+    propertyLines.push(`    const _r = ${vRefName}(obj[_key as keyof typeof obj], \`\${_path}/\${_key}\`)`)
+    propertyLines.push(`    if (_r !== true) errors.push(..._r.errors)`)
+    propertyLines.push(`  }`)
+  }
+
+  const body = propertyLines.length > 0 ? '\n' + propertyLines.join('\n') + '\n' : ''
+
+  return [
+    `export const ${vName} = (input: unknown, _path = ''): ValidationResult => {`,
+    `  if (typeof input !== 'object' || input === null || Array.isArray(input)) {`,
+    `    return { valid: false, errors: [{ message: 'must be object', path: _path }] }`,
+    `  }`,
+    ``,
+    `  const errors: ValidationError[] = []`,
+    `  const obj = input as Record<string, unknown>`,
+    body,
+    `  return errors.length > 0 ? { valid: false, errors } : true`,
+    `}`,
+  ].join('\n')
+}
+
+/**
+ * Generates a validator function for a non-object schema (primitive, array, enum, $ref).
+ */
+const generateScalarValidator = (schema: JSONSchema, typeName: string): string => {
+  const vName = validatorName(typeName)
+
+  if (!isSchemaObject(schema)) {
+    return [`export const ${vName} = (_input: unknown, _path = ''): ValidationResult => {`, `  return true`, `}`].join(
+      '\n',
+    )
+  }
+
+  // Top-level $ref — delegate entirely
+  if (hasRef(schema)) {
+    const delegateName = validatorName(refToName(schema.$ref))
+    return [
+      `export const ${vName} = (input: unknown, _path = ''): ValidationResult => {`,
+      `  return ${delegateName}(input, _path)`,
+      `}`,
+    ].join('\n')
+  }
+
+  // Top-level enum
+  if (hasEnum(schema)) {
+    const allowed = JSON.stringify(schema.enum)
+    const label = (schema.enum as unknown[]).map((v) => JSON.stringify(v)).join(', ')
+    return [
+      `export const ${vName} = (input: unknown, _path = ''): ValidationResult => {`,
+      `  if (!(${allowed} as unknown[]).includes(input)) {`,
+      `    return { valid: false, errors: [{ message: \`must be one of: ${label}\`, path: _path }] }`,
+      `  }`,
+      `  return true`,
+      `}`,
+    ].join('\n')
+  }
+
+  // oneOf — try each branch, return errors from all if none match
+  if (hasOneOf(schema)) {
+    const branches = schema.oneOf
+      .map((branch, i) => {
+        if (!hasRef(branch)) return null
+        const bName = validatorName(refToName((branch as { $ref: string }).$ref))
+        return `  const _r${i} = ${bName}(input, _path)\n  if (_r${i} === true) return true`
+      })
+      .filter(Boolean)
+      .join('\n')
+
+    return [
+      `export const ${vName} = (input: unknown, _path = ''): ValidationResult => {`,
+      branches,
+      `  return { valid: false, errors: [{ message: 'must match one of the expected schemas', path: _path }] }`,
+      `}`,
+    ].join('\n')
+  }
+
+  // Top-level typed schema (string, number, boolean, array)
+  if (hasType(schema)) {
+    const t = schema.type as string
+    const wrongType = wrongTypeCondition('input', t)
+    const typLabel = typeofString(t)
+
+    const constraintLines: string[] = []
+
+    if (t === 'string') {
+      if (hasPattern(schema)) {
+        constraintLines.push(`  if (typeof input === 'string' && !/${schema.pattern}/.test(input)) {`)
+        constraintLines.push(
+          `    return { valid: false, errors: [{ message: 'must match pattern ${schema.pattern}', path: _path }] }`,
+        )
+        constraintLines.push(`  }`)
+      }
+      if (hasMinLength(schema)) {
+        constraintLines.push(`  if (typeof input === 'string' && input.length < ${schema.minLength}) {`)
+        constraintLines.push(
+          `    return { valid: false, errors: [{ message: 'must have at least ${schema.minLength} characters', path: _path }] }`,
+        )
+        constraintLines.push(`  }`)
+      }
+      if (hasMaxLength(schema)) {
+        constraintLines.push(`  if (typeof input === 'string' && input.length > ${schema.maxLength}) {`)
+        constraintLines.push(
+          `    return { valid: false, errors: [{ message: 'must have at most ${schema.maxLength} characters', path: _path }] }`,
+        )
+        constraintLines.push(`  }`)
+      }
+    }
+
+    const body = constraintLines.length > 0 ? '\n' + constraintLines.join('\n') + '\n' : ''
+
+    return wrongType
+      ? [
+          `export const ${vName} = (input: unknown, _path = ''): ValidationResult => {`,
+          `  if (${wrongType}) {`,
+          `    return { valid: false, errors: [{ message: 'must be ${typLabel}', path: _path }] }`,
+          `  }`,
+          body,
+          `  return true`,
+          `}`,
+        ].join('\n')
+      : [`export const ${vName} = (_input: unknown, _path = ''): ValidationResult => {`, `  return true`, `}`].join(
+          '\n',
+        )
+  }
+
+  return [`export const ${vName} = (_input: unknown, _path = ''): ValidationResult => {`, `  return true`, `}`].join(
+    '\n',
+  )
+}
+
+/**
+ * Generates a TypeScript validator function from a JSON Schema.
+ *
+ * The generated function accepts `unknown` input and returns `true` if valid,
+ * or `{ valid: false, errors }` with a list of errors if not.
+ *
+ * Object schemas check that required properties are present and that all
+ * provided properties match their declared types. Non-object schemas (strings,
+ * numbers, enums, $refs) emit an inline type check.
+ *
+ * @example
+ * ```typescript
+ * generateValidatorFunction({ type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }, 'Info')
+ * // export const validateInfo = (input: unknown, _path = ''): ValidationResult => {
+ * //   if (typeof input !== 'object' || ...) return { valid: false, ... }
+ * //   const errors: ValidationError[] = []
+ * //   const obj = input as Record<string, unknown>
+ * //   if (!('name' in obj)) { errors.push(...) } else if (typeof obj['name'] !== 'string') { errors.push(...) }
+ * //   return errors.length > 0 ? { valid: false, errors } : true
+ * // }
+ * ```
+ */
+export const generateValidatorFunction = (schema: JSONSchema, typeName: string): string => {
+  if (isObjectSchema(schema)) {
+    return generateObjectValidator(schema, typeName)
+  }
+
+  return generateScalarValidator(schema, typeName)
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export type { GeneratedFile } from './generators/build-schema'
+export { buildValidatorSchema } from './generators/build-schema'