@amritk/generate-validators 0.11.11 → 0.11.12

package/AI.md

@@ -34,5 +34,10 @@ const files = await buildValidatorSchema(schema, 'Document')
    `ValidationResult`, helpers) plus the `index.ts` barrel.
 4. **`NaN` satisfies numeric bounds** (`minimum`/`maximum`/`multipleOf`) — differs
    from Ajv. Draft-07 schemas are auto-upgraded to 2020-12.
+5. **`format` emits no check.** It stays an annotation, like the interpreter's
+   default — but *not* like the interpreter run with `{ formats: 'all' }`
+   (`@amritk/lint`, `createApi({ formats })`), which rejects strings a generated
+   validator accepts. `unevaluatedProperties`/`unevaluatedItems` go the other
+   way: unimplemented, so generation **throws** instead of widening the verdict.
 
 Only the `.` entry. Install: `bun add @amritk/generate-validators`.

package/README.md

@@ -23,6 +23,9 @@ Each generated file exports:
 
 - A TypeScript `type` definition for the schema
 - A `validateFoo(input: unknown, _path?: string): ValidationResult` function
+- An `isFoo(input: unknown): input is Foo` boolean type guard — a single flat
+  predicate (no error array, no cold-path call) reaching the same verdict as
+  `validateFoo`, for the common "is this valid?" question
 
 A shared `validation-result.ts` template and an `index.ts` barrel are emitted alongside the generated files.
 
@@ -81,12 +84,13 @@ if (!result.valid) {
 
 ## API
 
-### `buildValidatorSchema(rootSchema, rootTypeName)`
+### `buildValidatorSchema(rootSchema, rootTypeName, typeSuffix?)`
 
-| Parameter | Type | Description |
-|:---|:---|:---|
-| `rootSchema` | `JSONSchema` | The root schema to traverse. `$ref` and `$dynamicRef` are resolved recursively. Draft-07 schemas are upgraded to 2020-12 automatically. |
-| `rootTypeName` | `string` | Name used for the root type (e.g. `"Document"`). |
+| Parameter | Type | Default | Description |
+|:---|:---|:---|:---|
+| `rootSchema` | `JSONSchema` | — | The root schema to traverse. `$ref` and `$dynamicRef` are resolved recursively. Draft-07 schemas are upgraded to 2020-12 automatically. |
+| `rootTypeName` | `string` | — | Name used for the root type (e.g. `"Document"`). |
+| `typeSuffix` | `string` | `''` | Suffix appended to every `$ref`-derived type name (`'Object'` turns `Contact` into `ContactObject`). The root type name is unaffected. |
 
 Returns: `Promise<GeneratedFile[]>` where `GeneratedFile = { filename: string; content: string }`.
 
@@ -103,7 +107,17 @@ per-item work (a bare `string[]` is free; a closed object with several fields is
 meaningfully slower), which is why array-heavy schemas validate more slowly than
 scalar/object ones.
 
-One divergence is worth calling out: **`NaN` satisfies a constrained number.**
+**`format` emits no check.** JSON Schema treats `format` as an annotation, and so
+does this generator: `{ type: 'string', format: 'uuid' }` produces the `typeof`
+check and nothing more. That matches the interpreter's default, but *not* the
+interpreter run with `{ formats: 'all' }` — as `@amritk/lint` and
+`createApi({ formats })` do — so a generated validator accepts strings those
+reject. Two keywords are handled the other way: `unevaluatedProperties` and
+`unevaluatedItems` are not implemented and **throw at generation time** rather
+than silently widening the verdict, because unlike `format` there is no reading of
+the spec under which ignoring them is correct.
+
+One further divergence is worth calling out: **`NaN` satisfies a constrained number.**
 Because the numeric bound checks are the exact negation of the error condition
 (e.g. `!(x < minimum)`), and every comparison against `NaN` is `false`, a `NaN`
 passes `minimum`/`maximum`/`exclusive*`/`multipleOf`. This matches the interpreter
@@ -144,8 +158,15 @@ the first error rather than collecting a full error list.)
 
 Preparing a validator costs ~0.3–0.6 ms for mjst codegen and ~0.05–0.2 ms for a
 TypeBox `TypeCompiler` compile, versus ~9–12 ms for an Ajv compile. Every library
-agrees on every verdict; parity is asserted before timing (TypeBox is given
-uuid/email format checkers so every library does the same work). Each library is
+agrees on every verdict; parity is asserted before timing.
+
+One caveat on the first two rows: their schemas declare `format` (`uuid`,
+`email`), and Ajv, typia, zod, and TypeBox all check it, while mjst's generated
+validators treat it as an annotation (see [Semantics](#semantics)). So on `small`
+and `order`, mjst is doing slightly less work than the columns beside it — the
+parity samples fail other constraints too, which is why the verdicts still agree.
+The `assert-loose` / `assert-strict` rows carry no `format` and are the
+constraint-for-constraint comparison. Each library is
 timed in an isolated process over a pool of distinct inputs, reporting the median
 of many trials — so the optimiser can't hoist or eliminate the work and the
 numbers stay reproducible. Micro-benchmark figures vary by machine and runtime —

package/dist/generators/generate-files.js

@@ -8,7 +8,10 @@ const generateValidatorFile = (schema, typeName, options) => {
     rootSchema: options?.rootSchema,
     typeSuffix
   });
-  const typeDefinition = generateTypeDefinition(schema, typeName, { typeSuffix });
+  const typeDefinition = generateTypeDefinition(schema, typeName, {
+    typeSuffix,
+    ...options?.rootSchema !== void 0 ? { rootSchema: options.rootSchema } : {}
+  });
   const validatorFunction = generateValidatorFunction(schema, typeName, typeSuffix);
   const booleanGuard = generateBooleanGuard(schema, typeName, typeSuffix);
   let result = `import type { ValidationResult, ValidationError } from './validation-result.js'

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@amritk/generate-validators",
-  "version": "0.11.11",
+  "version": "0.11.12",
   "description": "Generate TypeScript validation functions from JSON Schemas.",
   "module": "./dist/index.js",
   "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
   "license": "MIT",
   "author": "amritk",
   "keywords": [
@@ -47,10 +51,10 @@
   },
   "dependencies": {
     "json-schema-typed": "^8.0.1",
-    "@amritk/helpers": "0.13.5"
+    "@amritk/helpers": "0.14.0"
   },
   "devDependencies": {
-    "@amritk/runtime-validators": "0.9.0",
+    "@amritk/runtime-validators": "0.9.1",
     "@ryoppippi/unplugin-typia": "^2.6.5",
     "@scalar/openapi-parser": "^0.26.1",
     "@sinclair/typebox": "^0.34.49",