@amritk/generate-validators 0.11.5 → 0.11.7

package/README.md

@@ -92,6 +92,27 @@ Returns: `Promise<GeneratedFile[]>` where `GeneratedFile = { filename: string; c
 
 ---
 
+## Semantics
+
+Generated validators track the `@amritk/runtime-validators` interpreter. Array
+items are validated in full — an item's type, `$ref`, nested `properties` /
+`required`, and scalar constraints (`minLength`, `minimum`, …) are all enforced,
+recursing to any depth — and the boolean guard (`isX`) reaches the identical
+verdict. Validating array item *contents* costs throughput proportional to the
+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.**
+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
+but differs from validators (e.g. Ajv) that reject `NaN` for `type: "number"`.
+`NaN` never appears in parsed JSON; guard against it upstream if your values can
+be non-JSON.
+
+---
+
 ## Benchmarks
 
 Generated validators are straight-line, monomorphic TypeScript with no generic
@@ -108,20 +129,21 @@ 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 |
+| small (4 fields) | **~48M** ops/s | ~5M ops/s | ~10.5M ops/s | ~5.3M ops/s | ~2M ops/s |
+| order (nested + array) | **~7.8M** ops/s | ~2.2M ops/s | ~3.5M ops/s | ~2.1M ops/s | ~0.5M ops/s |
+| assert-loose | **~184M** ops/s | ~183M ops/s | ~45M ops/s | ~63M ops/s | ~3.8M ops/s |
+| assert-strict | **~162M** ops/s | ~148M ops/s | ~22M ops/s | ~38M 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 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
+(seven scalar roots plus a nested object): the boolean guard puts mjst clearly
+ahead of typia on `assert-strict` (with `additionalProperties: false`) and
+neck-and-neck with it on `assert-loose` — the two trade the lead run-to-run
+within noise. (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.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
 timed in an isolated process over a pool of distinct inputs, reporting the median

package/dist/generators/build-schema.js

@@ -45,6 +45,35 @@ export const valuesEqual = (a: unknown, b: unknown): boolean => {
   }
   return true
 }
+
+/**
+ * True when every element of \`arr\` is distinct under structural equality
+ * ({@link valuesEqual}). Backs generated \`uniqueItems\` checks whose items may be
+ * objects or arrays, where a \`JSON.stringify\` dedupe key would be key-order
+ * sensitive and let a reordered-but-equal duplicate (\`{ a: 1, b: 2 }\` vs
+ * \`{ b: 2, a: 1 }\`) slip through. A native \`Set\` dedupes the all-primitive case
+ * in one linear pass; object/array elements fall back to an exact pairwise
+ * structural comparison.
+ */
+export const allUnique = (arr: readonly unknown[]): boolean => {
+  const len = arr.length
+  if (len < 2) return true
+  let allPrimitive = true
+  for (let i = 0; i < len; i++) {
+    const v = arr[i]
+    if (v !== null && typeof v === 'object') {
+      allPrimitive = false
+      break
+    }
+  }
+  if (allPrimitive) return new Set(arr).size === len
+  for (let i = 0; i < len; i++) {
+    for (let j = i + 1; j < len; j++) {
+      if (valuesEqual(arr[i], arr[j])) return false
+    }
+  }
+  return true
+}
 `;
 /**
  * Builds all TypeScript validator files from a JSON Schema by traversing all

package/dist/generators/collect-validator-imports.js

@@ -54,7 +54,11 @@ const collectDirectRefs = (value, refs = []) => {
     // generated files, not inlined by this validator. `collectDirectRefs`
     // self-guards on non-objects, so a keyword that is a boolean or missing is a
     // harmless no-op.
-    const subSchemaMaps = ['properties', 'patternProperties'];
+    // `dependencies` (draft-07) is dual-form: a string array (dependentRequired) or
+    // a subschema (dependentSchemas). The emitter delegates the schema form via
+    // `validateX`, so a `$ref` inside it must be imported; the string-array form is
+    // a harmless no-op here (its values are strings, not schemas).
+    const subSchemaMaps = ['properties', 'patternProperties', 'dependentSchemas', 'dependencies'];
     for (const mapKey of subSchemaMaps) {
         const map = schema[mapKey];
         if (typeof map === 'object' && map !== null && !Array.isArray(map)) {

package/dist/generators/generate-files.js

@@ -37,11 +37,14 @@ export const generateValidatorFile = (schema, typeName, options) => {
     const booleanGuard = generateBooleanGuard(schema, typeName, typeSuffix);
     // `.js` extension so the relative import resolves under Node ESM, not only Bun.
     let result = `import type { ValidationResult, ValidationError } from './validation-result.js'\n`;
-    // `const` checks on object/array values call the runtime `valuesEqual` helper.
-    // Only import it when the generated body actually uses it, so files without a
-    // structural `const` do not carry an unused import.
-    if (validatorFunction.includes('valuesEqual(')) {
-        result += `import { valuesEqual } from './validation-result.js'\n`;
+    // Structural `const` checks call the runtime `valuesEqual` helper; structural
+    // `uniqueItems` checks call `allUnique`. Both live in `validation-result.js`;
+    // import each only when the generated body (validator or boolean guard) uses
+    // it, so files that need neither carry no unused import.
+    const body = validatorFunction + booleanGuard;
+    const runtimeHelpers = ['valuesEqual', 'allUnique'].filter((name) => body.includes(`${name}(`));
+    if (runtimeHelpers.length > 0) {
+        result += `import { ${runtimeHelpers.join(', ')} } from './validation-result.js'\n`;
     }
     for (const imp of refImports) {
         result += imp + '\n';

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

@@ -3,7 +3,7 @@ import { getMjstInstanceOf, getMjstPrimitive } from '@amritk/helpers/mjst-extens
 import { multipleOfFailExpr, multipleOfPassExpr } from '@amritk/helpers/multiple-of-check';
 import { refToName } from '@amritk/helpers/ref-to-name';
 import { safeAccessor } from '@amritk/helpers/safe-accessor';
-import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasDependentRequired, hasEnum, hasExclusiveMaximum, hasExclusiveMinimum, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMinItems, hasMinimum, hasMinLength, hasMultipleOf, hasOneOf, hasPattern, hasProperties, hasPropertyNames, hasRef, hasRequired, hasStrictExclusiveMaximum, hasStrictExclusiveMinimum, hasType, hasUniqueItems, isObjectSchema, isSchemaObject, } from '@amritk/helpers/schema-guards';
+import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasDependentRequired, hasEnum, hasExclusiveMaximum, hasExclusiveMinimum, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMaxProperties, hasMinItems, hasMinimum, hasMinLength, hasMinProperties, hasMultipleOf, hasOneOf, hasPattern, hasProperties, hasPropertyNames, hasRef, hasRequired, hasStrictExclusiveMaximum, hasStrictExclusiveMinimum, hasType, hasUniqueItems, isObjectSchema, isSchemaObject, } from '@amritk/helpers/schema-guards';
 import { unknownKeyCheck } from '@amritk/helpers/unknown-key-check';
 /**
  * Derives the validator function name from a type name.
@@ -31,6 +31,43 @@ const constMismatchCondition = (accessor, value) => {
     }
     return `!valuesEqual(${accessor}, ${JSON.stringify(value)})`;
 };
+const SCALAR_ITEM_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'null']);
+/**
+ * True when a schema's values are provably JSON scalars — its `type` is present
+ * and every listed type is a primitive. Conservative: a `$ref`, a boolean/absent
+ * schema, an `object`/`array` type, or a missing `type` all fail this test.
+ */
+const schemaIsScalarOnly = (schema) => {
+    if (!isSchemaObject(schema))
+        return false;
+    const t = schema['type'];
+    if (t === undefined)
+        return false;
+    const types = Array.isArray(t) ? t : [t];
+    return types.length > 0 && types.every((x) => typeof x === 'string' && SCALAR_ITEM_TYPES.has(x));
+};
+/**
+ * True when an array's elements can only be JSON scalars, so a `uniqueItems`
+ * check can dedupe by the cheap `JSON.stringify` projection. When items may be
+ * objects or arrays this returns false, and the check must instead compare
+ * structurally (the `allUnique` runtime helper): `JSON.stringify` is key-order
+ * sensitive and would treat `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` as distinct,
+ * disagreeing with the interpreter's order-independent deep equality.
+ */
+const arrayItemsAreScalarOnly = (schema) => {
+    const prefix = schema['prefixItems'];
+    if (Array.isArray(prefix)) {
+        if (!prefix.every((p) => schemaIsScalarOnly(p)))
+            return false;
+        // Tuple tail: a closed tuple (`items`/`additionalItems: false`) has no tail;
+        // otherwise the tail schema must itself be scalar-only.
+        const tail = 'items' in schema ? schema['items'] : schema['additionalItems'];
+        if (tail === false)
+            return true;
+        return schemaIsScalarOnly(tail);
+    }
+    return schemaIsScalarOnly(schema['items']);
+};
 /**
  * Generates the inline condition that is TRUE when a value is the wrong type.
  */
@@ -68,6 +105,21 @@ const getTypeArray = (schema) => {
     return schema.type;
 };
 const createRootContext = () => ({ objVar: 'obj', pathPrefix: '${_path}', depth: 0, hoisted: [] });
+/**
+ * Renders a schema-controlled property name as a static error-path segment.
+ *
+ * The name is appended to a backtick template-literal path (`` `${_path}/…` ``),
+ * so two independent escapings apply. First the JSON Pointer escape (`~`→`~0`,
+ * `/`→`~1`, `~` first) so a key containing `/` or `~` reads back unambiguously —
+ * matching the paths the runtime-validators interpreter emits. Then a
+ * template-literal escape of `` ` ``, `\`, and `$`, so a key like `` a`b `` or
+ * `${x}` cannot terminate the literal (a build failure) or inject an
+ * interpolation (a runtime `ReferenceError` / arbitrary expression).
+ */
+const pointerSegment = (key) => key
+    .replace(/~/g, '~0')
+    .replace(/\//g, '~1')
+    .replace(/[\\`$]/g, '\\$&');
 /**
  * Returns the `patternProperties` regex sources, or an empty array when the
  * schema declares none. The keys of `patternProperties` are the patterns.
@@ -146,31 +198,54 @@ const generateMissingRequiredChecks = (schema, ctx) => {
  * and recursion into inline nested objects.
  */
 const generatePropertyChecks = (key, propSchema, isRequired, suffix, ctx) => {
-    if (!isSchemaObject(propSchema))
+    if (!isSchemaObject(propSchema)) {
+        // A boolean `true` (accept-anything) schema carries no shape checks, but a
+        // required key must still be present. `false` never validates a present value,
+        // which the strict-key / additionalProperties path handles; here we only need
+        // to enforce presence for `true`.
+        if (isRequired && propSchema === true) {
+            const parentPath = ctx.depth === 0 ? '_path' : `\`${ctx.pathPrefix}\``;
+            return [
+                `  if (!(${JSON.stringify(key)} in ${ctx.objVar})) {`,
+                `    errors.push({ message: ${JSON.stringify(`must have required property '${key}'`)}, path: ${parentPath} })`,
+                `  }`,
+            ];
+        }
         return [];
+    }
     const raw = `${ctx.objVar}[${JSON.stringify(key)}]`;
-    const path = `\`${ctx.pathPrefix}/${key}\``;
+    const path = `\`${ctx.pathPrefix}/${pointerSegment(key)}\``;
     // Missing-property errors report at the parent object's path. At the root
     // that is the `_path` parameter itself; inside nested objects it is the
     // parent's accumulated static path.
     const parentPath = ctx.depth === 0 ? '_path' : `\`${ctx.pathPrefix}\``;
     const lines = [];
-    // $ref — delegate to the imported validator
+    // $ref — delegate to the imported validator. Per 2020-12, sibling keywords
+    // alongside `$ref` still apply to the same value, so any constraint/combinator
+    // siblings (e.g. `{ $ref, minLength: 5 }`) run after the delegation. A bare
+    // `{ $ref }` produces no siblings, leaving the output unchanged.
     if (hasRef(propSchema)) {
         const ref = propSchema.$ref;
         const vName = validatorName(refToName(ref, suffix));
+        const siblings = [
+            ...generateConstraintChecks(key, raw, path, propSchema, suffix, ctx),
+            ...generateCombinatorChecks(key, raw, path, propSchema, suffix, ctx),
+        ];
+        const delegate = [
+            `    const _r = ${vName}(${raw}, ${path})`,
+            `    if (_r !== true) errors.push(..._r.errors)`,
+            ...siblings,
+        ];
         if (isRequired) {
             lines.push(`  if (!(${JSON.stringify(key)} in ${ctx.objVar})) {`);
             lines.push(`    errors.push({ message: ${JSON.stringify(`must have required property '${key}'`)}, path: ${parentPath} })`);
             lines.push(`  } else {`);
-            lines.push(`    const _r = ${vName}(${raw}, ${path})`);
-            lines.push(`    if (_r !== true) errors.push(..._r.errors)`);
+            lines.push(...delegate);
             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(...delegate);
             lines.push(`  }`);
         }
         return lines;
@@ -310,20 +385,32 @@ const generatePropertyChecks = (key, propSchema, isRequired, suffix, ctx) => {
             ...generateConstraintChecks(key, raw, path, propSchema, suffix, ctx),
             ...generateCombinatorChecks(key, raw, path, propSchema, suffix, ctx),
         ];
-    if (extraLines.length > 0) {
-        if (!hasType(propSchema) && isRequired) {
-            // No `type` to anchor a missing-property check, so enforce presence here.
-            lines.push(`  if (!(${JSON.stringify(key)} in ${ctx.objVar})) {`);
-            lines.push(`    errors.push({ message: ${JSON.stringify(`must have required property '${key}'`)}, path: ${parentPath} })`);
-            lines.push(`  } else {`);
+    if (hasType(propSchema)) {
+        // Presence was already enforced in the `hasType` branch; only wrap the
+        // combinator siblings so they run when the value is present.
+        if (extraLines.length > 0) {
+            lines.push(`  if (${raw} !== undefined) {`);
             lines.push(...extraLines);
             lines.push(`  }`);
         }
-        else {
-            lines.push(`  if (${raw} !== undefined) {`);
+    }
+    else if (isRequired) {
+        // Type-less required property. Presence must be enforced even when the schema
+        // contributes no other checks (e.g. `{}` — an accept-anything schema), so a
+        // missing required key is still an error. Any extra checks run in the `else`.
+        lines.push(`  if (!(${JSON.stringify(key)} in ${ctx.objVar})) {`);
+        lines.push(`    errors.push({ message: ${JSON.stringify(`must have required property '${key}'`)}, path: ${parentPath} })`);
+        if (extraLines.length > 0) {
+            lines.push(`  } else {`);
             lines.push(...extraLines);
-            lines.push(`  }`);
         }
+        lines.push(`  }`);
+    }
+    else if (extraLines.length > 0) {
+        // Type-less optional property: run any checks only when the value is present.
+        lines.push(`  if (${raw} !== undefined) {`);
+        lines.push(...extraLines);
+        lines.push(`  }`);
     }
     return lines;
 };
@@ -405,40 +492,59 @@ const generateConstraintChecks = (key, raw, path, propSchema, suffix, ctx) => {
             lines.push(`  }`);
         }
     }
-    // Array with typed items
+    // Array items. `$ref` items delegate to the referenced validator. Any other
+    // item subschema is validated in full — matching the interpreter — but wrapped
+    // in a per-item boolean fast-check (`booleanLeafExpr`): a valid item passes the
+    // flat expression and skips the error-collecting body entirely, so the common
+    // valid case stays allocation-free (the same hot/cold split the top-level
+    // validator uses). This keeps array-heavy throughput close to a bare type check
+    // while still fully validating every item. The loop variables carry the nesting
+    // depth so item loops can nest (array-of-arrays) without colliding.
     if (hasItems(propSchema)) {
         const itemSchema = propSchema.items;
+        const iv = `_i${ctx.depth}`;
+        const itemPath = `\`${path.slice(1, -1)}/\${${iv}}\``;
         if (hasRef(itemSchema)) {
             const vName = validatorName(refToName(itemSchema.$ref, suffix));
             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)}/\${_i}\`)`);
+            lines.push(`    for (let ${iv} = 0; ${iv} < ${raw}.length; ${iv}++) {`);
+            lines.push(`      const _ir = ${vName}(${raw}[${iv}], ${itemPath})`);
             lines.push(`      if (_ir !== true) errors.push(..._ir.errors)`);
             lines.push(`    }`);
             lines.push(`  }`);
         }
-        else if (hasType(itemSchema)) {
-            const itemType = itemSchema.type;
-            const itemWrong = wrongTypeCondition('_item', itemType);
-            const itemLabel = typeofString(itemType);
-            if (itemWrong) {
+        else if (isSchemaObject(itemSchema)) {
+            const itemVar = `_item${ctx.depth}`;
+            const detail = generateValueChecks('', itemVar, itemPath, itemSchema, suffix, ctx, true);
+            if (detail.length > 0) {
                 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)}/\${_i}\` })`);
+                lines.push(`    for (let ${iv} = 0; ${iv} < ${raw}.length; ${iv}++) {`);
+                lines.push(`      const ${itemVar} = ${raw}[${iv}]`);
+                lines.push(...detail.map((l) => `    ${l}`));
                 lines.push(`    }`);
                 lines.push(`  }`);
             }
         }
     }
-    // Array length / uniqueness. `uniqueItems` dedupes by a JSON projection — exact
-    // for primitives (what the type guard also uses); deep-but-key-ordered for
-    // objects, the same pragmatic trade-off the rest of the generator makes.
+    // Array length / uniqueness. `uniqueItems` dedupes scalar items by a cheap
+    // `JSON.stringify` projection (exact for primitives, what the type guard also
+    // uses), but falls back to the structural `allUnique` helper when items may be
+    // objects/arrays — `JSON.stringify` is key-order sensitive and would disagree
+    // with the interpreter's order-independent deep equality.
     if (hasMinItems(propSchema) ||
         hasMaxItems(propSchema) ||
         (hasUniqueItems(propSchema) && propSchema.uniqueItems === true) ||
         isSchemaObject(sp['contains']) ||
-        Array.isArray(sp['prefixItems'])) {
+        Array.isArray(sp['prefixItems']) ||
+        (sp['items'] === false && !Array.isArray(sp['prefixItems']))) {
+        // `items: false` with no `prefixItems` forbids every element, so the array
+        // must be empty. (With `prefixItems`, the tuple block below caps the length
+        // instead.) Without this the constraint was silently ignored.
+        if (sp['items'] === false && !Array.isArray(sp['prefixItems'])) {
+            lines.push(`  if (Array.isArray(${raw}) && ${raw}.length > 0) {`);
+            lines.push(`    errors.push({ message: 'must NOT have more than 0 items', path: ${path} })`);
+            lines.push(`  }`);
+        }
         if (hasMinItems(propSchema)) {
             lines.push(`  if (Array.isArray(${raw}) && ${raw}.length < ${propSchema.minItems}) {`);
             lines.push(`    errors.push({ message: 'must have at least ${propSchema.minItems} items', path: ${path} })`);
@@ -450,7 +556,10 @@ const generateConstraintChecks = (key, raw, path, propSchema, suffix, ctx) => {
             lines.push(`  }`);
         }
         if (hasUniqueItems(propSchema) && propSchema.uniqueItems === true) {
-            lines.push(`  if (Array.isArray(${raw}) && new Set((${raw} as unknown[]).map((_u) => JSON.stringify(_u))).size !== ${raw}.length) {`);
+            const dupCond = arrayItemsAreScalarOnly(sp)
+                ? `new Set((${raw} as unknown[]).map((_u) => JSON.stringify(_u))).size !== ${raw}.length`
+                : `!allUnique(${raw} as unknown[])`;
+            lines.push(`  if (Array.isArray(${raw}) && ${dupCond}) {`);
             lines.push(`    errors.push({ message: 'must NOT have duplicate items', path: ${path} })`);
             lines.push(`  }`);
         }
@@ -499,34 +608,49 @@ const generateConstraintChecks = (key, raw, path, propSchema, suffix, ctx) => {
 };
 /**
  * Validates a value located at a *dynamic* key (a `patternProperties` or
- * `additionalProperties` schema value) against `propSchema`. Mirrors the
- * optional-property branch of {@link generatePropertyChecks} — the value is
- * always present, so each check is the same `!== undefined`-guarded form — but
- * `raw` and `path` are caller-supplied expressions (e.g. `obj[_k]` and
- * `` `${_path}/${_k}` ``) so the checks read a runtime key.
+ * `additionalProperties` value), an array item, a combinator branch, or a
+ * `dependentSchemas` subschema against `propSchema`. `raw` and `path` are
+ * caller-supplied expressions (e.g. `obj[_k]` and `` `${_path}/${_k}` ``) so the
+ * checks read a runtime location. By default the leaf checks are
+ * `!== undefined`-guarded (an absent optional value is valid); pass
+ * `required = true` for values that must be present (array items — a sparse hole
+ * reads as `undefined` and must fail), which drops that guard. `_key` is unused
+ * (the location is fully encoded by `path`) but kept for positional-call parity
+ * with the combinator generators.
  */
-const generateValueChecks = (key, raw, path, propSchema, suffix, ctx) => {
+const generateValueChecks = (_key, raw, path, propSchema, suffix, ctx, required = false) => {
     if (!isSchemaObject(propSchema))
         return [];
     const lines = [];
+    // Optional values skip validation when absent, so their leaf checks are
+    // `!== undefined`-guarded. Array items are unconditionally present — a sparse
+    // hole reads as `undefined` and must FAIL its type/const/enum check — so
+    // `required` drops the guard.
+    const presence = required ? '' : `${raw} !== undefined && `;
     if (hasRef(propSchema)) {
         const vName = validatorName(refToName(propSchema.$ref, suffix));
-        lines.push(`  if (${raw} !== undefined) {`);
-        lines.push(`    const _r = ${vName}(${raw}, ${path})`);
-        lines.push(`    if (_r !== true) errors.push(..._r.errors)`);
-        lines.push(`  }`);
+        if (required) {
+            lines.push(`  const _r = ${vName}(${raw}, ${path})`);
+            lines.push(`  if (_r !== true) errors.push(..._r.errors)`);
+        }
+        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;
     }
     const instanceOf = getMjstInstanceOf(propSchema);
     if (instanceOf) {
-        lines.push(`  if (${raw} !== undefined && !(${raw} instanceof ${instanceOf})) {`);
+        lines.push(`  if (${presence}!(${raw} instanceof ${instanceOf})) {`);
         lines.push(`    errors.push({ message: 'must be ${instanceOf}', path: ${path} })`);
         lines.push(`  }`);
         return lines;
     }
     const primitive = getMjstPrimitive(propSchema);
     if (primitive) {
-        lines.push(`  if (${raw} !== undefined && typeof ${raw} !== "${primitive}") {`);
+        lines.push(`  if (${presence}typeof ${raw} !== "${primitive}") {`);
         lines.push(`    errors.push({ message: 'must be ${primitive}', path: ${path} })`);
         lines.push(`  }`);
         return lines;
@@ -534,7 +658,7 @@ const generateValueChecks = (key, raw, path, propSchema, suffix, ctx) => {
     if (hasConst(propSchema)) {
         const mismatch = constMismatchCondition(raw, propSchema.const);
         const msg = JSON.stringify(`must be ${JSON.stringify(propSchema.const)}`);
-        lines.push(`  if (${raw} !== undefined && ${mismatch}) {`);
+        lines.push(`  if (${presence}${mismatch}) {`);
         lines.push(`    errors.push({ message: ${msg}, path: ${path} })`);
         lines.push(`  }`);
         return lines;
@@ -542,7 +666,7 @@ const generateValueChecks = (key, raw, path, propSchema, suffix, ctx) => {
     if (hasEnum(propSchema)) {
         const allowed = JSON.stringify(propSchema.enum);
         const label = propSchema.enum.map((v) => JSON.stringify(v)).join(', ');
-        lines.push(`  if (${raw} !== undefined && !(${allowed} as unknown[]).includes(${raw})) {`);
+        lines.push(`  if (${presence}!(${allowed} as unknown[]).includes(${raw})) {`);
         lines.push(`    errors.push({ message: ${JSON.stringify(`must be one of: ${label}`)}, path: ${path} })`);
         lines.push(`  }`);
         return lines;
@@ -552,7 +676,7 @@ const generateValueChecks = (key, raw, path, propSchema, suffix, ctx) => {
         const wrongType = wrongTypeCondition(raw, t);
         const typLabel = typeofString(t);
         if (wrongType) {
-            lines.push(`  if (${raw} !== undefined && (${wrongType})) {`);
+            lines.push(`  if (${presence}(${wrongType})) {`);
             lines.push(`    errors.push({ message: 'must be ${typLabel}', path: ${path} })`);
             lines.push(`  }`);
         }
@@ -561,8 +685,20 @@ const generateValueChecks = (key, raw, path, propSchema, suffix, ctx) => {
     // gate on keyword presence + a runtime-type guard, so a type-less subschema
     // (a combinator branch like `{ required: [...] }` or `{ minItems: 2 }`) is
     // still validated rather than collapsing to "matches everything".
-    lines.push(...generateConstraintChecks(key, raw, path, propSchema, suffix, ctx));
-    lines.push(...generateCombinatorChecks(key, raw, path, propSchema, suffix, ctx));
+    //
+    // This value lives at `path` (a template literal), so anchor the recursion's
+    // context there and one nesting level deeper: any nested object/array it emits
+    // then builds paths relative to THIS value and mints collision-free variable
+    // names, independent of the caller's context. `key` is intentionally dropped
+    // (set to `''`) because `path` already locates the value.
+    const valueCtx = {
+        objVar: ctx.objVar,
+        pathPrefix: path.slice(1, -1),
+        depth: ctx.depth + 1,
+        hoisted: ctx.hoisted,
+    };
+    lines.push(...generateConstraintChecks('', raw, path, propSchema, suffix, valueCtx));
+    lines.push(...generateCombinatorChecks('', raw, path, propSchema, suffix, valueCtx));
     return lines;
 };
 /**
@@ -698,7 +834,10 @@ const generateInlineObjectChecks = (key, propSchema, raw, suffix, ctx) => {
         return [];
     const child = {
         objVar: `_obj${ctx.depth + 1}`,
-        pathPrefix: `${ctx.pathPrefix}/${key}`,
+        // When `key` is empty the value is located AT `ctx.pathPrefix` already (e.g. an
+        // inline object reached through a combinator branch or a dynamic-key value), so
+        // appending `/${key}` would emit a spurious `//` or trailing `/` in error paths.
+        pathPrefix: key === '' ? ctx.pathPrefix : `${ctx.pathPrefix}/${pointerSegment(key)}`,
         depth: ctx.depth + 1,
         hoisted: ctx.hoisted,
     };
@@ -712,6 +851,9 @@ const generateInlineObjectChecks = (key, propSchema, raw, suffix, ctx) => {
     innerLines.push(...generatePatternAndAdditionalChecks(propSchema, suffix, child));
     innerLines.push(...generateStrictKeyChecks(propSchema, child));
     innerLines.push(...generateDependentRequiredChecks(propSchema, child));
+    innerLines.push(...generateDependentSchemasChecks(propSchema, suffix, child));
+    innerLines.push(...generateDependenciesChecks(propSchema, suffix, child));
+    innerLines.push(...generateMinMaxPropertiesChecks(propSchema, child));
     if (hasPropertyNames(propSchema) && isSchemaObject(propSchema.propertyNames)) {
         innerLines.push(...generatePropertyNameChecks(propSchema.propertyNames, suffix, child));
     }
@@ -727,49 +869,29 @@ const generateInlineObjectChecks = (key, propSchema, raw, suffix, ctx) => {
     ];
 };
 /**
- * Generates the `propertyNames` loop: every object key is a string, so we apply
- * the string-relevant constraints of the subschema (or delegate to a `$ref`'s
- * validator). This keeps the generator in step with the interpreter, which runs
- * the whole subschema against each key — not just the `pattern` form.
+ * Generates the `propertyNames` loop: every object key is a string, and the
+ * *whole* subschema is validated against each key — not just the
+ * `pattern`/length/`enum`/`const`/`$ref` subset. Delegating to
+ * {@link generateValueChecks} keeps the generator in lockstep with the
+ * interpreter, which runs `matchesSchema(nameSchema, key)` per key, so a
+ * subschema carrying a combinator, `type`, `multipleOf`, etc. is enforced too.
+ * A key is always a present string, so the value checks run in `required` mode
+ * (no `!== undefined` guard).
  */
 const generatePropertyNameChecks = (nameSchema, suffix, ctx) => {
     if (!isSchemaObject(nameSchema))
         return [];
     const at = `\`${ctx.pathPrefix}/\${_name}\``;
-    const checks = [];
-    if (hasRef(nameSchema)) {
-        const vName = validatorName(refToName(nameSchema.$ref, suffix));
-        checks.push(`    const _nr = ${vName}(_name, ${at})`);
-        checks.push(`    if (_nr !== true) errors.push(..._nr.errors)`);
-    }
-    else {
-        if (hasPattern(nameSchema)) {
-            const re = escapeRegexPattern(nameSchema.pattern);
-            const msg = JSON.stringify(`property name must match pattern ${nameSchema.pattern}`);
-            checks.push(`    if (!/${re}/.test(_name)) errors.push({ message: ${msg}, path: ${at} })`);
-        }
-        if (hasMinLength(nameSchema)) {
-            const msg = JSON.stringify(`property name must have at least ${nameSchema.minLength} characters`);
-            checks.push(`    if (_name.length < ${nameSchema.minLength}) errors.push({ message: ${msg}, path: ${at} })`);
-        }
-        if (hasMaxLength(nameSchema)) {
-            const msg = JSON.stringify(`property name must have at most ${nameSchema.maxLength} characters`);
-            checks.push(`    if (_name.length > ${nameSchema.maxLength}) errors.push({ message: ${msg}, path: ${at} })`);
-        }
-        if (hasEnum(nameSchema)) {
-            const allowed = JSON.stringify(nameSchema.enum);
-            const label = nameSchema.enum.map((v) => JSON.stringify(v)).join(', ');
-            const msg = JSON.stringify(`property name must be one of: ${label}`);
-            checks.push(`    if (!(${allowed} as unknown[]).includes(_name)) errors.push({ message: ${msg}, path: ${at} })`);
-        }
-        if (hasConst(nameSchema)) {
-            const msg = JSON.stringify(`property name must be ${JSON.stringify(nameSchema.const)}`);
-            checks.push(`    if (_name !== ${JSON.stringify(nameSchema.const)}) errors.push({ message: ${msg}, path: ${at} })`);
-        }
-    }
+    const nameCtx = {
+        objVar: ctx.objVar,
+        pathPrefix: `${ctx.pathPrefix}/\${_name}`,
+        depth: ctx.depth + 1,
+        hoisted: ctx.hoisted,
+    };
+    const checks = generateValueChecks('', '_name', at, nameSchema, suffix, nameCtx, true);
     if (checks.length === 0)
         return [];
-    return [`  for (const _name of Object.keys(${ctx.objVar})) {`, ...checks, `  }`];
+    return [`  for (const _name of Object.keys(${ctx.objVar})) {`, ...checks.map((line) => `  ${line}`), `  }`];
 };
 /**
  * Emits `dependentRequired` checks: when a trigger key is present, each of its
@@ -794,6 +916,129 @@ const generateDependentRequiredChecks = (schema, ctx) => {
     }
     return lines;
 };
+/**
+ * Emits `dependentSchemas` checks (2020-12): when a trigger property is present,
+ * the *whole object* must also match the associated subschema. Mirrors the
+ * interpreter, which applies the subschema in place against the object. A `true`
+ * subschema permits everything (no-op); a `false` subschema makes the trigger's
+ * presence always invalid.
+ */
+const generateDependentSchemasChecks = (schema, suffix, ctx) => {
+    if (!isSchemaObject(schema))
+        return [];
+    const dep = schema['dependentSchemas'];
+    if (typeof dep !== 'object' || dep === null || Array.isArray(dep))
+        return [];
+    const obj = ctx.objVar;
+    const at = ctx.depth === 0 ? '_path' : `\`${ctx.pathPrefix}\``;
+    const objPath = `\`${ctx.pathPrefix}\``;
+    const lines = [];
+    for (const [trigger, sub] of Object.entries(dep)) {
+        if (sub === true)
+            continue;
+        if (sub === false) {
+            const msg = JSON.stringify(`must NOT have property '${trigger}'`);
+            lines.push(`  if (${JSON.stringify(trigger)} in ${obj}) {`);
+            lines.push(`    errors.push({ message: ${msg}, path: ${at} })`);
+            lines.push(`  }`);
+            continue;
+        }
+        if (!isSchemaObject(sub))
+            continue;
+        // The subschema applies to the object itself, so validate the current object
+        // variable against it and gate the whole block on the trigger's presence.
+        const checks = generateValueChecks('', obj, objPath, sub, suffix, ctx);
+        if (checks.length === 0)
+            continue;
+        lines.push(`  if (${JSON.stringify(trigger)} in ${obj}) {`);
+        lines.push(...checks.map((line) => `  ${line}`));
+        lines.push(`  }`);
+    }
+    return lines;
+};
+/**
+ * Emits draft-07 `dependencies` — the dual-form predecessor of
+ * `dependentRequired` + `dependentSchemas`. When a trigger property is present,
+ * an array value requires each listed key, and a schema value is applied to the
+ * *whole object*. Mirrors the interpreter, which branches on the value's shape.
+ * A `false` subschema makes the trigger's mere presence invalid; a `true`
+ * subschema is a no-op.
+ */
+const generateDependenciesChecks = (schema, suffix, ctx) => {
+    if (!isSchemaObject(schema))
+        return [];
+    const dep = schema['dependencies'];
+    if (typeof dep !== 'object' || dep === null || Array.isArray(dep))
+        return [];
+    const obj = ctx.objVar;
+    const at = ctx.depth === 0 ? '_path' : `\`${ctx.pathPrefix}\``;
+    const objPath = `\`${ctx.pathPrefix}\``;
+    const lines = [];
+    for (const [trigger, value] of Object.entries(dep)) {
+        // Array form: each listed key must be present when the trigger is.
+        if (Array.isArray(value)) {
+            for (const key of value) {
+                if (typeof key !== 'string')
+                    continue;
+                const msg = JSON.stringify(`must have property '${key}' when '${trigger}' is present`);
+                lines.push(`  if (${JSON.stringify(trigger)} in ${obj} && !(${JSON.stringify(key)} in ${obj})) {`);
+                lines.push(`    errors.push({ message: ${msg}, path: ${at} })`);
+                lines.push(`  }`);
+            }
+            continue;
+        }
+        // Schema form: the subschema applies to the object itself.
+        if (value === true)
+            continue;
+        if (value === false) {
+            const msg = JSON.stringify(`must NOT have property '${trigger}'`);
+            lines.push(`  if (${JSON.stringify(trigger)} in ${obj}) {`);
+            lines.push(`    errors.push({ message: ${msg}, path: ${at} })`);
+            lines.push(`  }`);
+            continue;
+        }
+        if (!isSchemaObject(value))
+            continue;
+        const checks = generateValueChecks('', obj, objPath, value, suffix, ctx);
+        if (checks.length === 0)
+            continue;
+        lines.push(`  if (${JSON.stringify(trigger)} in ${obj}) {`);
+        lines.push(...checks.map((line) => `  ${line}`));
+        lines.push(`  }`);
+    }
+    return lines;
+};
+/**
+ * Emits `minProperties` / `maxProperties` bounds on the object's key count,
+ * mirroring the interpreter (which counts the object's own enumerable keys and
+ * reports at the object node). Counting once into a depth-scoped local keeps the
+ * two bounds from re-walking the keys.
+ */
+const generateMinMaxPropertiesChecks = (schema, ctx) => {
+    if (!isSchemaObject(schema))
+        return [];
+    const hasMin = hasMinProperties(schema);
+    const hasMax = hasMaxProperties(schema);
+    if (!hasMin && !hasMax)
+        return [];
+    const obj = ctx.objVar;
+    const at = ctx.depth === 0 ? '_path' : `\`${ctx.pathPrefix}\``;
+    const count = `_pc${ctx.depth}`;
+    const lines = [`  const ${count} = Object.keys(${obj}).length`];
+    if (hasMin) {
+        const msg = JSON.stringify(`must have at least ${schema.minProperties} properties`);
+        lines.push(`  if (${count} < ${schema.minProperties}) {`);
+        lines.push(`    errors.push({ message: ${msg}, path: ${at} })`);
+        lines.push(`  }`);
+    }
+    if (hasMax) {
+        const msg = JSON.stringify(`must have at most ${schema.maxProperties} properties`);
+        lines.push(`  if (${count} > ${schema.maxProperties}) {`);
+        lines.push(`    errors.push({ message: ${msg}, path: ${at} })`);
+        lines.push(`  }`);
+    }
+    return lines;
+};
 /**
  * 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
@@ -803,6 +1048,17 @@ const generateDependentRequiredChecks = (schema, ctx) => {
  * input, never weakening a verdict. `objAcc` is the expression yielding the
  * parent object (already narrowed to a record); `key` indexes into it.
  */
+/**
+ * Whether an object schema carries a combinator keyword (`allOf`, `anyOf`,
+ * `oneOf`, `not`, `if`) that the error-collecting slow path enforces but neither
+ * flat guard can mirror. When present, both guards must bail so their early
+ * `return true` never accepts a document the combinator would reject.
+ */
+const hasObjectLevelCombinator = (schema) => {
+    if (!isSchemaObject(schema))
+        return false;
+    return hasAllOf(schema) || hasAnyOf(schema) || hasOneOf(schema) || 'not' in schema || 'if' in schema;
+};
 const guardPropConditions = (key, propSchema, objAcc) => {
     if (!isSchemaObject(propSchema))
         return null;
@@ -898,10 +1154,17 @@ const arrayRejectedByRequiredProp = (keys, required, properties) => {
 const guardObjectConditions = (schema, raw, objAcc) => {
     if (!isObjectSchema(schema))
         return null;
-    if (hasDependentRequired(schema) || hasPropertyNames(schema))
+    if (hasDependentRequired(schema) || hasPropertyNames(schema) || 'dependentSchemas' in schema)
+        return null;
+    if (hasMinProperties(schema) || hasMaxProperties(schema) || 'dependencies' in schema)
         return null;
     if (isSchemaObject(schema) && 'patternProperties' in schema)
         return null;
+    // Object-level combinators are enforced by the slow path but cannot be mirrored
+    // by this flat guard, so bail — otherwise the guard's early `return true` would
+    // accept documents the combinators reject.
+    if (hasObjectLevelCombinator(schema))
+        return null;
     let strict = false;
     if (hasAdditionalProperties(schema)) {
         // Only `additionalProperties: false` is guardable (via the key-count trick
@@ -969,6 +1232,14 @@ const generateObjectValidator = (schema, typeName, suffix) => {
     propertyLines.push(...generateStrictKeyChecks(schema, ctx));
     // dependentRequired — when a trigger property is present, its dependencies must be too.
     propertyLines.push(...generateDependentRequiredChecks(schema, ctx));
+    // dependentSchemas — when a trigger property is present, the whole object must
+    // also match the associated subschema.
+    propertyLines.push(...generateDependentSchemasChecks(schema, suffix, ctx));
+    // dependencies (draft-07) — the dual-form predecessor of dependentRequired +
+    // dependentSchemas.
+    propertyLines.push(...generateDependenciesChecks(schema, suffix, ctx));
+    // minProperties / maxProperties — bound the object's key count.
+    propertyLines.push(...generateMinMaxPropertiesChecks(schema, ctx));
     // propertyNames — every key (always a string) must satisfy the subschema. This
     // mirrors the interpreter, which runs the full subschema against each key.
     if (hasPropertyNames(schema) && isSchemaObject(schema.propertyNames)) {
@@ -1040,32 +1311,6 @@ const generateObjectValidator = (schema, typeName, suffix) => {
  * e.g. "InfoObject" → "isInfoObject"
  */
 const guardName = (typeName) => `is${typeName}`;
-/**
- * Positive type check for a value — the negation of {@link wrongTypeCondition}.
- * Used by the boolean type-guard, which proves validity with `&&` conditions
- * rather than collecting errors. Object is a shape-only check (matching the
- * validator, which never recurses into array items or untyped object values).
- */
-const rightTypeCondition = (accessor, type) => {
-    switch (type) {
-        case 'string':
-            return `typeof ${accessor} === 'string'`;
-        case 'number':
-            return `typeof ${accessor} === 'number'`;
-        case 'integer':
-            return `typeof ${accessor} === 'number' && Number.isInteger(${accessor})`;
-        case 'boolean':
-            return `typeof ${accessor} === 'boolean'`;
-        case 'array':
-            return `Array.isArray(${accessor})`;
-        case 'null':
-            return `${accessor} === null`;
-        case 'object':
-            return `typeof ${accessor} === 'object' && ${accessor} !== null && !Array.isArray(${accessor})`;
-        default:
-            return null;
-    }
-};
 /**
  * Builds the membership test for an `enum`, matching the slow path's
  * `[...].includes(value)` verdict exactly. For the common all-primitive case it
@@ -1163,10 +1408,10 @@ const booleanLeafExpr = (schema, acc) => {
     }
 };
 /**
- * Boolean expression for an array value. Mirrors the validator, which checks the
- * array shape and — for typed items — only each item's *type* (objects are shape-
- * checked, not recursed into); it never enforces `minItems`/`maxItems` or item
- * constraints. Returns `null` for `$ref` items (those defer to the validator).
+ * Boolean expression for an array value. Mirrors the validator: array shape,
+ * `minItems`/`maxItems`/`uniqueItems`, and each item validated in full via
+ * {@link booleanLeafExpr}. Returns `null` for `$ref` items, or when an item schema
+ * can't be expressed flat, so the whole guard defers to the validator.
  *
  * Item iteration goes through `Array.from` rather than `Array.prototype.every`
  * because `every` *skips holes* in a sparse array (`[, 'x']`), whereas the
@@ -1183,7 +1428,11 @@ const booleanArrayExpr = (schema, acc) => {
     if (hasMaxItems(schema))
         parts.push(`${acc}.length <= ${schema.maxItems}`);
     if (hasUniqueItems(schema) && schema.uniqueItems === true) {
-        parts.push(`new Set((${acc} as unknown[]).map((_u) => JSON.stringify(_u))).size === ${acc}.length`);
+        // Same scalar-vs-structural split as the validator, so the guard's verdict
+        // matches the slow path's for object items in a reordered key order.
+        parts.push(arrayItemsAreScalarOnly(schema)
+            ? `new Set((${acc} as unknown[]).map((_u) => JSON.stringify(_u))).size === ${acc}.length`
+            : `allUnique(${acc} as unknown[])`);
     }
     const base = parts.join(' && ');
     if (!hasItems(schema))
@@ -1193,12 +1442,14 @@ const booleanArrayExpr = (schema, acc) => {
         return base;
     if (hasRef(items))
         return null;
-    if (!hasType(items))
-        return base;
-    const itemCheck = rightTypeCondition('_it', items.type);
-    if (itemCheck === null)
-        return base;
-    return `${base} && Array.from(${acc} as unknown[]).every((_it) => ${itemCheck})`;
+    // Validate each item in full, mirroring the validator's per-item checks so the
+    // guard reaches the identical verdict. `booleanLeafExpr` returns `null` for item
+    // schemas it can't express flat — bail so the validator decides, keeping the
+    // guard from ever accepting what the slow path would reject.
+    const itemExpr = booleanLeafExpr(items, '_it');
+    if (itemExpr === null)
+        return null;
+    return `${base} && Array.from(${acc} as unknown[]).every((_it) => (${itemExpr}))`;
 };
 /**
  * Builds the `&&` conditions proving an object value is valid (same verdict as
@@ -1210,10 +1461,16 @@ const booleanObjectParts = (schema, raw, objAcc) => {
     if (!isObjectSchema(schema))
         return null;
     // These need per-key loops or cross-references the flat form can't express.
-    if (hasDependentRequired(schema) || hasPropertyNames(schema))
+    if (hasDependentRequired(schema) || hasPropertyNames(schema) || 'dependentSchemas' in schema)
+        return null;
+    if (hasMinProperties(schema) || hasMaxProperties(schema) || 'dependencies' in schema)
         return null;
     if (isSchemaObject(schema) && 'patternProperties' in schema)
         return null;
+    // Object-level combinators change the verdict but can't be expressed flat, so
+    // defer to the validator rather than emit a guard that ignores them.
+    if (hasObjectLevelCombinator(schema))
+        return null;
     let strict = false;
     if (hasAdditionalProperties(schema)) {
         // Only `additionalProperties: false` is expressible; a schema needs per-key
@@ -1272,8 +1529,12 @@ const booleanObjectParts = (schema, raw, objAcc) => {
 export const generateBooleanGuard = (schema, typeName, _suffix = '') => {
     const name = guardName(typeName);
     const fallback = `export const ${name} = (input: unknown): input is ${typeName} => ${validatorName(typeName)}(input) === true`;
-    if (isObjectSchema(schema)) {
-        const parts = booleanObjectParts(schema, 'input', 'obj');
+    // Fold `nullable: true` into `anyOf` so the guard's verdict matches the
+    // validator's (which applies the same rewrite). Without this a nullable node's
+    // guard would reject `null` while the validator accepts it.
+    const rewritten = rewriteNullable(schema);
+    if (isObjectSchema(rewritten)) {
+        const parts = booleanObjectParts(rewritten, 'input', 'obj');
         if (parts === null)
             return fallback;
         return [
@@ -1286,7 +1547,7 @@ export const generateBooleanGuard = (schema, typeName, _suffix = '') => {
         ].join('\n');
     }
     // Non-object roots (scalar, enum, array) can often be expressed inline too.
-    const expr = booleanLeafExpr(schema, 'input');
+    const expr = booleanLeafExpr(rewritten, 'input');
     if (expr === null)
         return fallback;
     return `export const ${name} = (input: unknown): input is ${typeName} => ${expr}`;
@@ -1364,10 +1625,44 @@ const generateScalarValidator = (schema, typeName, suffix) => {
     // (exactly one) and inline branches included, not just `$ref` branches.
     if (hasAllOf(schema) || hasAnyOf(schema) || hasOneOf(schema) || 'not' in schema || 'if' in schema) {
         const ctx = createRootContext();
-        const checks = generateCombinatorChecks('', 'input', '`${_path}`', schema, suffix, ctx);
+        const checks = [];
+        // The root path expression the shared emitters use, as a template literal body.
+        const rootPath = '`${_path}`';
+        // A `type` (and its sibling value constraints) alongside a combinator still
+        // applies — the value must satisfy BOTH. Emit the type/constraint checks first,
+        // then the combinator checks, so a schema like `{ type: 'string', not: {…} }`
+        // or `{ type: 'number', minimum: 10, allOf: [{ maximum: 100 }] }` no longer
+        // drops the `type` check and its siblings.
+        const rootTypeArray = getTypeArray(schema);
+        if (rootTypeArray) {
+            const allWrong = rootTypeArray
+                .map((t) => wrongTypeCondition('input', t))
+                .filter((c) => c !== '')
+                .map((c) => `(${c})`)
+                .join(' && ');
+            if (allWrong) {
+                const label = rootTypeArray.map((t) => typeofString(t)).join(' or ');
+                checks.push(`  if (${allWrong}) {`);
+                checks.push(`    errors.push({ message: ${JSON.stringify(`must be ${label}`)}, path: ${rootPath} })`);
+                checks.push(`  }`);
+            }
+            checks.push(...generateConstraintChecks('', 'input', rootPath, schema, suffix, ctx));
+        }
+        else if (hasType(schema)) {
+            const t = schema.type;
+            const wrongType = wrongTypeCondition('input', t);
+            if (wrongType) {
+                checks.push(`  if (${wrongType}) {`);
+                checks.push(`    errors.push({ message: 'must be ${typeofString(t)}', path: ${rootPath} })`);
+                checks.push(`  }`);
+            }
+            checks.push(...generateConstraintChecks('', 'input', rootPath, schema, suffix, ctx));
+        }
+        checks.push(...generateCombinatorChecks('', 'input', rootPath, schema, suffix, ctx));
         const body = checks.join('\n').replaceAll('errors.push(', '(errors ??= []).push(');
+        const hoistedBlock = ctx.hoisted.length > 0 ? `${ctx.hoisted.join('\n')}\n\n` : '';
         return [
-            `export const ${vName} = (input: unknown, _path = ''): ValidationResult => {`,
+            `${hoistedBlock}export const ${vName} = (input: unknown, _path = ''): ValidationResult => {`,
             `  let errors: ValidationError[] | undefined`,
             body,
             `  return errors !== undefined ? { valid: false, errors } : true`,
@@ -1487,6 +1782,76 @@ const assertNoUnsupportedKeywords = (schema, typeName) => {
     };
     visit(schema);
 };
+/** Keywords whose value is a single subschema (or a boolean schema). */
+const SINGLE_SUBSCHEMA_KEYS = new Set([
+    'additionalProperties',
+    'additionalItems',
+    'contains',
+    'propertyNames',
+    'not',
+    'if',
+    'then',
+    'else',
+    'unevaluatedProperties',
+    'unevaluatedItems',
+]);
+/** Keywords whose value is an array of subschemas. */
+const SUBSCHEMA_LIST_KEYS = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
+/** Keywords whose value is a map of names to subschemas. */
+const SUBSCHEMA_MAP_KEYS = new Set(['properties', 'patternProperties', 'dependentSchemas', '$defs', 'definitions']);
+/**
+ * Rewrites OpenAPI 3.0 `nullable: true` into a form the generator already
+ * enforces. A node `{ nullable: true, ...rest }` accepts a value iff the value is
+ * `null` OR it matches `rest` — exactly `{ anyOf: [{ type: 'null' }, rest] }`.
+ * Emitting that lets the existing `anyOf` machinery (and its guard bail-outs)
+ * mirror the interpreter, which short-circuits every keyword when a `nullable`
+ * node sees `null`.
+ *
+ * The walk descends only into genuine subschema positions (never into `enum` /
+ * `const` / `default` data), so a data value that merely looks like a schema is
+ * never rewritten. Returns a fresh tree; the caller's schema is untouched.
+ */
+const rewriteNullable = (node) => {
+    if (typeof node !== 'object' || node === null || Array.isArray(node))
+        return node;
+    const src = node;
+    const out = {};
+    for (const [key, value] of Object.entries(src)) {
+        if (key === 'nullable')
+            continue; // folded into the `anyOf` wrapper below
+        if (SINGLE_SUBSCHEMA_KEYS.has(key)) {
+            out[key] = rewriteNullable(value);
+        }
+        else if (key === 'items') {
+            // `items` is either a single subschema (2020-12) or a tuple array (draft).
+            out[key] = Array.isArray(value) ? value.map(rewriteNullable) : rewriteNullable(value);
+        }
+        else if (SUBSCHEMA_LIST_KEYS.has(key) && Array.isArray(value)) {
+            out[key] = value.map(rewriteNullable);
+        }
+        else if (SUBSCHEMA_MAP_KEYS.has(key) && typeof value === 'object' && value !== null) {
+            const mapped = {};
+            for (const [name, sub] of Object.entries(value))
+                mapped[name] = rewriteNullable(sub);
+            out[key] = mapped;
+        }
+        else if (key === 'dependencies' && typeof value === 'object' && value !== null) {
+            // Dual-form: an array value lists required keys (data), a schema value is a
+            // subschema.
+            const mapped = {};
+            for (const [name, sub] of Object.entries(value)) {
+                mapped[name] = Array.isArray(sub) ? sub : rewriteNullable(sub);
+            }
+            out[key] = mapped;
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    if (src['nullable'] === true)
+        return { anyOf: [{ type: 'null' }, out] };
+    return out;
+};
 /**
  * Generates a TypeScript validator function from a JSON Schema.
  *
@@ -1511,8 +1876,11 @@ const assertNoUnsupportedKeywords = (schema, typeName) => {
  */
 export const generateValidatorFunction = (schema, typeName, suffix = '') => {
     assertNoUnsupportedKeywords(schema, typeName);
-    if (isObjectSchema(schema)) {
-        return generateObjectValidator(schema, typeName, suffix);
+    // Fold OpenAPI `nullable: true` into the `anyOf` form the generator already
+    // enforces, so the emitted checks match the interpreter's null short-circuit.
+    const rewritten = rewriteNullable(schema);
+    if (isObjectSchema(rewritten)) {
+        return generateObjectValidator(rewritten, typeName, suffix);
     }
-    return generateScalarValidator(schema, typeName, suffix);
+    return generateScalarValidator(rewritten, typeName, suffix);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-validators",
-  "version": "0.11.5",
+  "version": "0.11.7",
   "description": "Generate TypeScript validation functions from JSON Schemas.",
   "module": "./dist/index.js",
   "type": "module",
@@ -46,9 +46,10 @@
   },
   "dependencies": {
     "json-schema-typed": "^8.0.1",
-    "@amritk/helpers": "0.12.0"
+    "@amritk/helpers": "0.13.1"
   },
   "devDependencies": {
+    "@amritk/runtime-validators": "0.7.1",
     "@ryoppippi/unplugin-typia": "^2.6.5",
     "@scalar/openapi-parser": "^0.26.1",
     "@sinclair/typebox": "^0.34.49",