@amritk/generate-validators 0.7.0 → 0.8.0

package/README.md

@@ -95,17 +95,30 @@ 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:
+dispatch. On the happy path they run 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 only fall back to the
+error-collecting body when something is actually wrong. That makes a valid-input
+check as cheap as TypeBox's compiled checker 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) | 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
+| small (4 fields) | **~37M** ops/s | ~10M ops/s | ~4.9M ops/s | ~2.0M ops/s |
+| order (nested + array) | **~11M** ops/s | ~3.7M ops/s | ~2.0M ops/s | ~0.5M ops/s |
+| assert-loose | **~67M** ops/s | ~40M ops/s | ~57M ops/s | ~3.2M ops/s |
+| assert-strict | **~47M** ops/s | ~19M ops/s | ~36M ops/s | ~1.3M 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 out
+TypeBox's compiled checker on both, with and without `additionalProperties:
+false`.
+
+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. 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:

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

@@ -2,6 +2,7 @@ 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 { 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 +50,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 +393,113 @@ 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;
+    const raw = `${objAcc}[${JSON.stringify(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;
+    }
+};
+/**
+ * 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);
+    const conditions = [`typeof ${raw} === 'object' && ${raw} !== null && !Array.isArray(${raw})`];
+    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,14 +551,26 @@ 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` : '';
+    // 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 walking the slow path. It returns
+    // true only for provably valid input; anything it can't prove cheaply falls
+    // through to the error-collecting body below, 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');
+    const guardBlock = guard
+        ? [`  if (`, guard.map((condition) => `    ${condition}`).join(' &&\n'), `  ) {`, `    return true`, `  }`, ``]
+        : [];
     return [
         `${hoistedBlock}export const ${vName} = (input: unknown, _path = ''): ValidationResult => {`,
+        `  const obj = input as Record<string, unknown>`,
+        ...guardBlock,
         `  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`,
         `}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-validators",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Generate TypeScript validation functions from JSON Schemas.",
   "module": "./dist/index.js",
   "type": "module",
@@ -46,7 +46,7 @@
   },
   "dependencies": {
     "json-schema-typed": "^8.0.1",
-    "@amritk/helpers": "0.9.0"
+    "@amritk/helpers": "0.10.0"
   },
   "devDependencies": {
     "@scalar/openapi-parser": "^0.26.1",