@amritk/generate-validators 0.7.0 → 0.9.0

package/README.md

@@ -95,20 +95,39 @@ Returns: `Promise<GeneratedFile[]>` where `GeneratedFile = { filename: string; c
 ## Benchmarks
 
 Generated validators are straight-line, monomorphic TypeScript with no generic
-dispatch, so they validate as fast as an Ajv-compiled function once emitted —
-and emitting them is far cheaper than compiling a schema at startup. Measured
-on Bun 1.3 (Linux x64), validating valid input at steady state:
-
-| schema | mjst (generated) | ajv (compiled) | typebox (compiled) | zod |
-|:--|--:|--:|--:|--:|
-| small (4 fields) | **~9.5M** ops/s | ~9.3M ops/s | ~4.8M ops/s | ~1.7M ops/s |
-| order (nested + array) | **~3.7M** ops/s | ~3.5M ops/s | ~2.0M ops/s | ~0.4M ops/s |
-
-Preparing a validator costs ~0.15–0.20 ms for mjst codegen and ~0.12–0.21 ms for
-a TypeBox `TypeCompiler` compile, versus ~13–14 ms for an Ajv compile. All four
-libraries agree on every verdict; parity is asserted before timing (TypeBox is
-given uuid/email format checkers so every library does the same work).
-Micro-benchmark figures vary by machine and runtime — reproduce with:
+dispatch. The exported `validateX` is split into a hot and a cold half: on the
+happy path it runs a single allocation-free boolean guard — a pure `&&` chain of
+`typeof` checks (plus an `Object.keys().length` count when an object is closed
+with `additionalProperties: false`) — and `return true`s straight away, only
+calling a separate error-collecting function when something is actually wrong.
+Keeping the hot function tiny lets V8 optimise it aggressively, so a valid-input
+check beats every other library measured — including the build-time transformer
+typia — while still emitting full JSON-Pointer errors for invalid input, and
+emitting the validator stays far cheaper than compiling a schema at startup.
+Measured on Bun 1.3 (Linux x64), validating valid input at steady state:
+
+| schema | mjst (generated) | typia (transformed) | ajv (compiled) | typebox (compiled) | zod |
+|:--|--:|--:|--:|--:|--:|
+| small (4 fields) | **~22M** ops/s | ~4.2M ops/s | ~7.0M ops/s | ~4.0M ops/s | ~1.8M ops/s |
+| order (nested + array) | **~6.9M** ops/s | ~1.7M ops/s | ~2.5M ops/s | ~1.7M ops/s | ~0.4M ops/s |
+| assert-loose | **~110M** ops/s | ~100M ops/s | ~31M ops/s | ~41M ops/s | ~3.2M ops/s |
+| assert-strict | **~98M** ops/s | ~82M ops/s | ~13M ops/s | ~28M ops/s | ~1.1M ops/s |
+
+The `assert-loose` / `assert-strict` rows are the exact shape used by
+[`moltar/typescript-runtime-type-benchmarks`](https://github.com/moltar/typescript-runtime-type-benchmarks)
+(seven scalar roots plus a nested object); the boolean guard lets mjst edge past
+typia on both, with and without `additionalProperties: false`. (typia and
+TypeBox still win the *invalid* path, where they bail on the first error rather
+than collecting a full error list.)
+
+Preparing a validator costs ~0.1 ms for mjst codegen and ~0.05–0.12 ms for a
+TypeBox `TypeCompiler` compile, versus ~8–10 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
+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 —
+reproduce with:
 
 ```bash
 bun run bench

package/dist/generators/generate-validator-function.js

@@ -1,7 +1,9 @@
 import { escapeRegexPattern } from '@amritk/helpers/escape-regex-pattern';
 import { getMjstInstanceOf, getMjstPrimitive } from '@amritk/helpers/mjst-extension';
 import { refToName } from '@amritk/helpers/ref-to-name';
+import { safeAccessor } from '@amritk/helpers/safe-accessor';
 import { hasAdditionalProperties, hasConst, hasDependentRequired, hasEnum, hasExclusiveMaximum, hasExclusiveMinimum, hasItems, hasMaximum, hasMaxLength, hasMinimum, hasMinLength, hasMultipleOf, hasOneOf, hasPattern, hasProperties, hasPropertyNames, hasRef, hasRequired, hasStrictExclusiveMaximum, hasStrictExclusiveMinimum, hasType, isObjectSchema, isSchemaObject, } from '@amritk/helpers/schema-guards';
+import { unknownKeyCheck } from '@amritk/helpers/unknown-key-check';
 /**
  * Derives the validator function name from a type name.
  * e.g. "InfoObject" → "validateInfoObject"
@@ -49,29 +51,51 @@ const wrongTypeCondition = (accessor, type) => {
     }
 };
 const createRootContext = () => ({ objVar: 'obj', pathPrefix: '${_path}', depth: 0, hoisted: [] });
+/**
+ * Returns the `patternProperties` regex sources, or an empty array when the
+ * schema declares none. The keys of `patternProperties` are the patterns.
+ */
+const patternPropertySources = (schema) => {
+    if (!isSchemaObject(schema) || !('patternProperties' in schema))
+        return [];
+    const patterns = schema.patternProperties;
+    if (typeof patterns !== 'object' || patterns === null)
+        return [];
+    return Object.keys(patterns);
+};
 /**
  * Generates the unknown-key sweep for `additionalProperties: false`, mirroring
  * the interpreter's behaviour (same error message, one error per extra key).
- * The known-keys Set is hoisted to module scope and the sweep uses `for...in`
- * — the same allocation-free shape Ajv compiles to — so the hot path costs one
- * Set lookup per key. Schemas that combine it with `patternProperties` are
- * skipped: the generator does not evaluate key patterns yet, so rejecting
- * every undeclared key would wrongly fail keys the patterns allow.
+ * The sweep uses `for...in` — the same allocation-free shape Ajv compiles to.
+ * The per-key "is this declared" test comes from `unknownKeyCheck`, which
+ * inlines `!==` comparisons for small key counts (faster than `Set.has` and
+ * allocation-free) and hoists a known-keys `Set` only when the list is long.
+ * When the schema also declares `patternProperties`, a key matching any pattern
+ * is not "additional": the patterns are compiled once at module scope (the same
+ * regex-caching the interpreter does) and a key survives the sweep if it is a
+ * known key or matches any pattern.
  */
 const generateStrictKeyChecks = (schema, ctx) => {
     if (!isSchemaObject(schema))
         return [];
     if (!hasAdditionalProperties(schema) || schema.additionalProperties !== false)
         return [];
-    if ('patternProperties' in schema)
-        return [];
     const known = Object.keys(hasProperties(schema) ? schema.properties : {});
-    const setName = `_knownKeys${ctx.hoisted.length}`;
-    ctx.hoisted.push(`const ${setName} = new Set(${JSON.stringify(known)})`);
     const d = ctx.depth;
+    const check = unknownKeyCheck(known, `_knownKeys${ctx.hoisted.length}`);
+    ctx.hoisted.push(...check.declarations);
+    // A key that matches any `patternProperties` regex is allowed, so only keys
+    // outside both the known keys and every pattern count as additional.
+    const patterns = patternPropertySources(schema);
+    let patternGuard = '';
+    if (patterns.length > 0) {
+        const patternsName = `_patterns${ctx.hoisted.length}`;
+        ctx.hoisted.push(`const ${patternsName} = [${patterns.map((p) => `new RegExp(${JSON.stringify(p)})`).join(', ')}]`);
+        patternGuard = ` && !${patternsName}.some((re) => re.test(_key${d}))`;
+    }
     return [
         `  for (const _key${d} in ${ctx.objVar}) {`,
-        `    if (!${setName}.has(_key${d})) {`,
+        `    if (${check.isUnknown(`_key${d}`)}${patternGuard}) {`,
         `      errors.push({ message: 'must NOT have additional properties', path: \`${ctx.pathPrefix}/\${_key${d}}\` })`,
         `    }`,
         `  }`,
@@ -370,6 +394,145 @@ const generatePropertyNameChecks = (nameSchema, suffix) => {
         return [];
     return [`  for (const _name of Object.keys(obj)) {`, ...checks, `  }`];
 };
+/**
+ * Builds the `&&` conditions that prove a single property is valid, or `null`
+ * when the property carries any keyword the slow path enforces beyond a bare
+ * type check (pattern, min/max, enum, const, `$ref`, items, x-mjst, …). A `null`
+ * makes the whole guard bail so that input still flows through the slow,
+ * error-collecting path — the guard only ever returns true for *provably* valid
+ * input, never weakening a verdict. `objAcc` is the expression yielding the
+ * parent object (already narrowed to a record); `key` indexes into it.
+ */
+const guardPropConditions = (key, propSchema, objAcc) => {
+    if (!isSchemaObject(propSchema))
+        return null;
+    // Dotted access (`obj.number`) for identifier keys, bracket access otherwise.
+    const raw = safeAccessor(objAcc, key);
+    // Anything the slow path enforces past a typeof is cheaper to leave to the
+    // slow path than to mirror here, so bail and keep the guard sound.
+    if (hasRef(propSchema) ||
+        hasEnum(propSchema) ||
+        hasConst(propSchema) ||
+        hasOneOf(propSchema) ||
+        getMjstInstanceOf(propSchema) !== undefined ||
+        getMjstPrimitive(propSchema) !== undefined ||
+        hasPattern(propSchema) ||
+        hasMinLength(propSchema) ||
+        hasMaxLength(propSchema) ||
+        hasMinimum(propSchema) ||
+        hasMaximum(propSchema) ||
+        hasExclusiveMinimum(propSchema) ||
+        hasExclusiveMaximum(propSchema) ||
+        hasMultipleOf(propSchema) ||
+        hasItems(propSchema)) {
+        return null;
+    }
+    if (!hasType(propSchema))
+        return null;
+    switch (propSchema.type) {
+        case 'string':
+            return [`typeof ${raw} === 'string'`];
+        // mjst treats `integer` like `number` (it never enforces integrality), so a
+        // `typeof === 'number'` guard matches the slow path's verdict exactly.
+        case 'number':
+        case 'integer':
+            return [`typeof ${raw} === 'number'`];
+        case 'boolean':
+            return [`typeof ${raw} === 'boolean'`];
+        case 'object':
+            // Member access into the nested record is only reached after the shape
+            // check ahead of it in the `&&` chain, so the cast is always safe.
+            return guardObjectConditions(propSchema, raw, `(${raw} as Record<string, unknown>)`);
+        // Arrays need a per-item loop the guard can't express, and any other type
+        // (null, multi-type, untyped) is left to the slow path.
+        default:
+            return null;
+    }
+};
+/** A property key an array carries with a non-`undefined` value: `length`, or a
+ * canonical array index. A required prop on one of these can't be used to rule
+ * out arrays (an array's `length` is a number, an index can be anything). */
+const ARRAY_INDEX_KEY = /^(0|[1-9]\d*)$/;
+/** Schema types whose guard is a `typeof` check `typeof undefined` never passes. */
+const TYPEOF_CHECKABLE_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'object']);
+/**
+ * Whether some required, typeof-guarded property proves the value can't be an
+ * array — letting the object shape-check drop its `!Array.isArray(...)` term. An
+ * array indexed by a normal key yields `undefined` (or an inherited method),
+ * which no `typeof === 'string' | 'number' | 'boolean' | 'object'` accepts, so
+ * that field check already rejects arrays. Keys an array does carry a real value
+ * for (`length`, numeric indices) are excluded, since those could slip through.
+ */
+const arrayRejectedByRequiredProp = (keys, required, properties) => {
+    for (const key of keys) {
+        if (!required.has(key) || key === 'length' || ARRAY_INDEX_KEY.test(key))
+            continue;
+        const propSchema = properties[key];
+        if (propSchema !== undefined &&
+            isSchemaObject(propSchema) &&
+            hasType(propSchema) &&
+            TYPEOF_CHECKABLE_TYPES.has(propSchema.type)) {
+            return true;
+        }
+    }
+    return false;
+};
+/**
+ * Builds the allocation-free boolean guard for an object schema as a list of
+ * `&&` conditions, or `null` when the schema can't be proven valid by a cheap
+ * expression. The conditions are ordered so every member access is guarded by
+ * the object-shape check that precedes it in the `&&` chain.
+ *
+ * The guard only handles the happy path: every declared property must be
+ * required and a bare-typed scalar or a likewise-guardable nested object. Any
+ * optional property, object-level constraint the slow path enforces
+ * (`patternProperties`, `propertyNames`, `dependentRequired`, an
+ * `additionalProperties` *schema*), or unguardable property makes it bail, and
+ * the validator falls back to its full error-collecting body.
+ */
+const guardObjectConditions = (schema, raw, objAcc) => {
+    if (!isObjectSchema(schema))
+        return null;
+    if (hasDependentRequired(schema) || hasPropertyNames(schema))
+        return null;
+    if (isSchemaObject(schema) && 'patternProperties' in schema)
+        return null;
+    let strict = false;
+    if (hasAdditionalProperties(schema)) {
+        // Only `additionalProperties: false` is guardable (via the key-count trick
+        // below); an additional-properties *schema* needs per-key validation.
+        if (schema.additionalProperties === false)
+            strict = true;
+        else
+            return null;
+    }
+    const required = new Set(hasRequired(schema) ? schema.required : []);
+    const properties = hasProperties(schema) ? schema.properties : {};
+    const keys = Object.keys(properties);
+    // The object shape-check only needs `!Array.isArray` when no required field
+    // check would already reject an array (see `arrayRejectedByRequiredProp`).
+    const arrayCheck = arrayRejectedByRequiredProp(keys, required, properties) ? '' : ` && !Array.isArray(${raw})`;
+    const conditions = [`typeof ${raw} === 'object' && ${raw} !== null${arrayCheck}`];
+    for (const key of keys) {
+        // An optional property would need an `=== undefined ||` branch and breaks
+        // the key-count trick, so the guard only covers all-required objects.
+        if (!required.has(key))
+            return null;
+        const propConditions = guardPropConditions(key, properties[key], objAcc);
+        if (propConditions === null)
+            return null;
+        conditions.push(...propConditions);
+    }
+    if (strict) {
+        // `additionalProperties: false` with every declared property required: once
+        // the typeof checks confirm each key is present, an exact key count proves
+        // there are no extras — TypeBox's trick, with no loop and no Set.
+        if (!keys.every((key) => required.has(key)))
+            return null;
+        conditions.push(`Object.keys(${objAcc}).length === ${keys.length}`);
+    }
+    return conditions;
+};
 /**
  * Generates a validator function body for an object schema, checking each
  * property's presence and type and collecting all errors.
@@ -421,18 +584,54 @@ const generateObjectValidator = (schema, typeName, suffix) => {
     // Hoisted statements (e.g. known-keys Sets) come first so every call of the
     // validator reuses them instead of rebuilding them.
     const hoistedBlock = ctx.hoisted.length > 0 ? `${ctx.hoisted.join('\n')}\n\n` : '';
-    return [
-        `${hoistedBlock}export const ${vName} = (input: unknown, _path = ''): ValidationResult => {`,
+    // A pure boolean guard for the happy path: when every property is present and
+    // well-typed (and, for strict objects, there are no extras) it returns true
+    // without allocating an `errors` array or touching the slow path. It returns
+    // true only for provably valid input; anything it can't prove cheaply falls
+    // through to the error-collecting path, which produces the same verdict and
+    // full JSON-Pointer errors. Schemas with constraints the guard can't express
+    // produce no guard at all (`null`), leaving behaviour unchanged.
+    const guard = guardObjectConditions(schema, 'input', 'obj');
+    // The cold, error-collecting body. When there's a guard this is a separate
+    // (unexported) function reached only on failure; the hot path never enters it
+    // unless input is actually invalid, so its size never costs the happy path.
+    const collectBody = (name, exported) => [
+        `${exported ? 'export ' : ''}const ${name} = (input: unknown, _path = ''): ValidationResult => {`,
+        `  const obj = input as Record<string, unknown>`,
         `  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');
+    // No guard: the exported validator is the error-collecting function itself.
+    if (!guard) {
+        return `${hoistedBlock}${collectBody(vName, true)}`;
+    }
+    // With a guard, keep the happy path inside the exported function — the guard
+    // is inlined as an early `return true`, so a valid input never pays an extra
+    // call — and move only the cold, error-collecting body into a separate
+    // (unexported) function. That keeps `validateX` itself tiny (guard + a single
+    // tail call) so V8 optimises it well, without the giant error body bloating
+    // the hot path. The exported `(input, _path?) => ValidationResult` contract
+    // is unchanged.
+    const collectName = `${vName}Errors`;
+    return [
+        `${hoistedBlock}${collectBody(collectName, false)}`,
+        ``,
+        `export const ${vName} = (input: unknown, _path = ''): ValidationResult => {`,
+        `  const obj = input as Record<string, unknown>`,
+        `  if (`,
+        guard.map((condition) => `    ${condition}`).join(' &&\n'),
+        `  ) {`,
+        `    return true`,
+        `  }`,
+        `  return ${collectName}(input, _path)`,
+        `}`,
+    ].join('\n');
 };
 /**
  * Generates a validator function for a non-object schema (primitive, array, enum, $ref).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-validators",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Generate TypeScript validation functions from JSON Schemas.",
   "module": "./dist/index.js",
   "type": "module",
@@ -33,7 +33,7 @@
     "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",
-    "bench": "bun run ./bench/run.ts"
+    "bench": "bun --conditions development ./bench/run.ts"
   },
   "imports": {
     "#generators/*": "./src/generators/*.ts"
@@ -46,13 +46,15 @@
   },
   "dependencies": {
     "json-schema-typed": "^8.0.1",
-    "@amritk/helpers": "0.9.0"
+    "@amritk/helpers": "0.10.0"
   },
   "devDependencies": {
+    "@ryoppippi/unplugin-typia": "^2.6.5",
     "@scalar/openapi-parser": "^0.26.1",
     "@sinclair/typebox": "^0.34.49",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
+    "typia": "^12.1.1",
     "zod": "^4.4.3"
   }
 }