@amritk/generate-validators 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-validators",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Generate TypeScript validation functions from JSON Schemas.",
   "module": "./dist/index.js",
   "type": "module",
@@ -24,8 +24,7 @@
     "url": "https://github.com/amritk/mjst/issues"
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "publishConfig": {
     "access": "public"
@@ -33,23 +32,27 @@
   "scripts": {
     "build": "tsgo -p tsconfig.build.json && tsc-alias -p tsconfig.build.json -f",
     "types:check": "tsgo -p . --noEmit",
-    "test": "NODE_ENV=production vitest run --root ../.. generate-validators"
+    "test": "NODE_ENV=production vitest run --root ../.. generate-validators",
+    "bench": "bun run ./bench/run.ts"
   },
   "imports": {
     "#generators/*": "./src/generators/*.ts"
   },
   "exports": {
     ".": {
-      "development": "./src/index.ts",
       "default": "./dist/index.js",
       "types": "./dist/index.d.ts"
     }
   },
   "dependencies": {
     "json-schema-typed": "^8.0.1",
-    "@amritk/helpers": "0.8.0"
+    "@amritk/helpers": "0.10.0"
   },
   "devDependencies": {
-    "@scalar/openapi-parser": "^0.26.1"
+    "@scalar/openapi-parser": "^0.26.1",
+    "@sinclair/typebox": "^0.34.49",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "zod": "^4.4.3"
   }
 }

package/dist/generators/build-schema.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"build-schema.d.ts","sourceRoot":"","sources":["../../src/generators/build-schema.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAIjE;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAmBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,oBAAoB,eACnB,UAAU,gBACR,MAAM,0BAEnB,OAAO,CAAC,aAAa,EAAE,CAuBzB,CAAA"}

package/dist/generators/collect-validator-imports.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"collect-validator-imports.d.ts","sourceRoot":"","sources":["../../src/generators/collect-validator-imports.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAEjE;;GAEG;AACH,KAAK,8BAA8B,GAAG;IACpC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACzD;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B,CAAA;AAoED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,WAAY,UAAU,YAAY,8BAA8B,KAAG,MAAM,EA6B5G,CAAA"}

package/dist/generators/generate-files.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"generate-files.d.ts","sourceRoot":"","sources":["../../src/generators/generate-files.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAKjE;;GAEG;AACH,KAAK,4BAA4B,GAAG;IAClC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7C;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,qBAAqB,WACxB,UAAU,YACR,MAAM,YACN,4BAA4B,KACrC,MA0BF,CAAA"}

package/dist/generators/generate-validator-function.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"generate-validator-function.d.ts","sourceRoot":"","sources":["../../src/generators/generate-validator-function.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AA+ejE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,yBAAyB,WAAY,UAAU,YAAY,MAAM,sBAAgB,MAM7F,CAAA"}

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA"}

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

@@ -1,163 +0,0 @@
-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('validateInfo')
-  })
-
-  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('validateInfo')
-
-    // 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

@@ -1,81 +0,0 @@
-import { generateIndexBarrel } from '@amritk/helpers/generate-index-barrel'
-import { walkRefGraph } from '@amritk/helpers/walk-ref-graph'
-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` / `$dynamicRef` references recursively (via the shared
- * `@amritk/helpers/walk-ref-graph` walker).
- *
- * 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,
-  typeSuffix = '',
-): Promise<GeneratedFile[]> => {
-  const files: GeneratedFile[] = []
-
-  walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
-    // `validation-result` and `index` are reserved output filenames, so never
-    // let a definition of either name overwrite them.
-    if (node.filename === 'validation-result' || node.filename === 'index') return
-
-    const content = generateValidatorFile(node.schema, node.typeName, {
-      rootSchema: node.rootSchema,
-      typeSuffix,
-      ...(node.ref !== undefined ? { selfRef: node.ref } : {}),
-    })
-    files.push({ filename: `${node.filename}.ts`, content })
-  })
-
-  // 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 })
-
-  files.push({ filename: 'index.ts', content: generateIndexBarrel(files) })
-
-  return files
-}

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

@@ -1,134 +0,0 @@
-import { refToFilename } from '@amritk/helpers/ref-to-filename'
-import { refToName } from '@amritk/helpers/ref-to-name'
-import { resolveRef } from '@amritk/helpers/resolve-ref'
-import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasItems, hasOneOf, hasRef } from '@amritk/helpers/schema-guards'
-import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
-
-/**
- * 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
-  /**
-   * Suffix appended to every type/validator name derived from a `$ref`. Must
-   * match the suffix used when generating the referenced files. Defaults to `''`.
-   */
-  readonly typeSuffix?: string
-}
-
-/**
- * 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, suffix: string): string => {
-  const filename = refToFilename(ref)
-  const typeName = refToName(ref, suffix)
-  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 Contact, validateContact } from './contact'"]
- * ```
- */
-export const collectValidatorImports = (schema: JSONSchema, options?: CollectValidatorImportsOptions): string[] => {
-  const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : null
-  const rootSchema = options?.rootSchema
-  const typeSuffix = options?.typeSuffix ?? ''
-
-  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, typeSuffix))
-  }
-
-  return imports
-}

package/src/generators/generate-files.ts

@@ -1,79 +0,0 @@
-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>
-  /**
-   * Suffix appended to every type/validator name derived from a `$ref`.
-   * Defaults to `''` (no suffix).
-   */
-  readonly typeSuffix?: string
-}
-
-/**
- * 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 typeSuffix = options?.typeSuffix ?? ''
-  const refImports = collectValidatorImports(schema, {
-    selfRef: options?.selfRef,
-    rootSchema: options?.rootSchema,
-    typeSuffix,
-  })
-
-  const typeDefinition = generateTypeDefinition(schema, typeName, { typeSuffix })
-  const validatorFunction = generateValidatorFunction(schema, typeName, typeSuffix)
-
-  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
-}