ata-validator 1.31.2 → 1.32.0

package/index.d.ts

@@ -497,6 +497,16 @@ export interface Validator<T = unknown> {
   /** Parse JSON and validate against the schema. Returns the parsed value and the validation result. Works without the native addon. */
   validateAndParse(jsonString: string | Buffer): ValidateAndParseResult<T>;
 
+  /**
+   * Validate, then return a copy holding only the properties the schema declares, with defaults
+   * filled. The input is not modified. Throws an error named `AtaValidationError`, with `errors`,
+   * when the value is invalid, and a `TypeError` where the kept key set cannot be proven from the
+   * schema (a $ref it cannot inline, patternProperties, an object that allows unknown keys) or the
+   * validator rewrites input (`coerceTypes`, custom keywords). Same result as the `parse` export of
+   * a module built with `ata build`.
+   */
+  parse(data: unknown): T;
+
   /** Ultra-fast buffer validation via native addon */
   isValid(input: Buffer | Uint8Array | string): boolean;
 

package/index.js

@@ -244,26 +244,36 @@ function collectRemovals(schema, actions, path) {
 // Emit the in-place strip for one schema node and everything under its
 // `properties`. Scope matches collectRemovals(): object properties only, so
 // the two paths keep the same answer.
+// Each level's code, its own removal loop and its children's, sits inside the
+// guard for that level. A child used to be guarded only on itself, so its
+// access expression read through a parent that could be absent or null:
+// `{ c: { properties: { d: { additionalProperties: false } } } }` threw a
+// TypeError from validate({}) whenever the optional `c` was missing.
 function emitRemovals(node, access, lines, depth, seen) {
   if (!node || typeof node !== 'object' || !node.properties) return;
   if (seen.has(node)) return;
   seen.add(node);
   const keys = Object.keys(node.properties);
-  if (node.additionalProperties === false && keys.length > 0) {
+  const body = [];
+  // With no declared property every key is additional, as the interpreted
+  // engine's remover has it; this pass used to skip such a node entirely.
+  if (node.additionalProperties === false) {
     const kv = '_k' + depth;
     const checks = keys.map((k) => `${kv}!==${JSON.stringify(k)}`).join('&&');
-    const guard = depth === 0
-      ? ''
-      : `if(${access}!==null&&typeof ${access}==='object'&&!Array.isArray(${access}))`;
-    lines.push(`${guard}for(var ${kv} in ${access})if(${checks})delete ${access}[${kv}]`);
+    body.push(keys.length > 0
+      ? `for(var ${kv} in ${access})if(${checks})delete ${access}[${kv}]`
+      : `for(var ${kv} in ${access})delete ${access}[${kv}]`);
   }
   for (const key of keys) {
     const prop = node.properties[key];
     if (prop && typeof prop === 'object' && prop.properties) {
-      emitRemovals(prop, `${access}[${JSON.stringify(key)}]`, lines, depth + 1, seen);
+      emitRemovals(prop, `${access}[${JSON.stringify(key)}]`, body, depth + 1, seen);
     }
   }
   seen.delete(node);
+  if (body.length === 0) return;
+  if (depth === 0) lines.push(...body);
+  else lines.push(`if(${access}!==null&&typeof ${access}==='object'&&!Array.isArray(${access})){${body.join('\n')}}`);
 }
 
 // Generate a fast preprocess function via codegen instead of closure arrays
@@ -1306,6 +1316,23 @@ class Validator {
     this._mutatesInput = !!(preprocess || options.coerceTypes || options.removeAdditional);
     this._preprocess = preprocess;
 
+    // removeAdditional alone, the common parse-and-strip use: a verdict function
+    // that deletes unknown keys in the walk it already makes, where the pass
+    // above walks every object a second time just to find them. It answers
+    // the documents it accepts; anything it rejects takes the full path below,
+    // which removes, validates and reports exactly as before, so a rejected
+    // document is left as clean as it always was. The generator declines any
+    // schema where deleting during the walk could change an answer.
+    let fusedRemove = null;
+    if (preprocess && options.removeAdditional && !options.coerceTypes && !this._interpretOnly &&
+        !this._userFormats && !this._usesKeywords && !this._schemaStr.includes('"default"')) {
+      try {
+        fusedRemove = compileToJSCodegen(schemaObj, this._schemaMap.size > 0 ? this._schemaMap : null, null, { removeAdditional: true });
+      } catch {
+        fusedRemove = null;
+      }
+    }
+
     // Detect if schema is "selective" -- doesn't recurse into arrays/deep objects.
     const hasArrayTraversal =
       schemaObj &&
@@ -1577,9 +1604,11 @@ class Validator {
       // The verdict methods answer validate()'s question without building the
       // error list, so they run the same preprocess pass. Skipping it made the
       // two disagree on input that coercion or a default would have fixed.
-      _bindVerdict(this, preprocess
-        ? (data) => { preprocess(data); return jsFn(data) }
-        : jsFn);
+      _bindVerdict(this, fusedRemove
+        ? (data) => fusedRemove(data) || (preprocess(data), jsFn(data))
+        : preprocess
+          ? (data) => { preprocess(data); return jsFn(data) }
+          : jsFn);
       // Same preference as the object path: the combined function first, since
       // it validates and collects in one pass, and the error generator behind
       // it. `errPreferCombined` is that order, resolved on the first rejection
@@ -1794,7 +1823,12 @@ class Validator {
         : _validate;
       _bindVerdict(this, this._fastVerdict
         ? this._fastVerdict
-        : (data) => _validate(data).valid);
+        // The rewrite runs first here too, as it does for validate() above; a
+        // verdict without it disagreed with validate() on input that coercion,
+        // a default or a removed key would have fixed.
+        : preprocess
+          ? (data) => { preprocess(data); return _validate(data).valid; }
+          : (data) => _validate(data).valid);
       this.validateAndParse = (jsonStr) => this._compiled.validateAndParse(jsonStr);
       {
         const slot = this._fastSlot;
@@ -1927,12 +1961,22 @@ class Validator {
     // paths that only need a boolean.
     if (this.validate) {
       const _bare = this.validate;
-      this.validate = (data) => {
-        const r = _bare(data);
-        return (r.valid === true && r.data === undefined)
-          ? { valid: true, data, errors: r.errors }
-          : r;
-      };
+      this.validate = fusedRemove
+        // A document the removing verdict accepts is answered here, one call
+        // deep; anything else takes the full path, see fusedRemove above.
+        ? (data) => {
+            if (fusedRemove(data)) return { valid: true, data, errors: VALID_RESULT.errors };
+            const r = _bare(data);
+            return (r.valid === true && r.data === undefined)
+              ? { valid: true, data, errors: r.errors }
+              : r;
+          }
+        : (data) => {
+            const r = _bare(data);
+            return (r.valid === true && r.data === undefined)
+              ? { valid: true, data, errors: r.errors }
+              : r;
+          };
     }
 
     // Custom error messages: if any subschema declares an `errorMessage`
@@ -2851,6 +2895,59 @@ Validator.prototype._extendValidate = function (resolve) {
 // closure, where wrapping the five entry points cost a closure per entry point,
 // the wrappers themselves and an accessor, most of what building a wrapped
 // validator took.
+// parse(data): validate, then return a copy holding only what the schema
+// declares, the way the parse() export of an ahead-of-time module does, with
+// the same emitter behind both. Building the copy from the schema's own key
+// list costs less than finding and deleting unknown keys, and leaves the
+// caller's object alone. Where the key set cannot be proven (a $ref it cannot
+// inline, patternProperties, an open object) the method declines with an
+// error instead of guessing, as the module ships no parse() there; so it does
+// under options that rewrite input, whose answers a copy would not reproduce.
+Validator.prototype.parse = function (data) {
+  let fn = this._parseFn;
+  if (fn === undefined) {
+    fn = _buildParse(this);
+    Object.defineProperty(this, '_parseFn', { value: fn, writable: true, configurable: true, enumerable: false });
+  }
+  return fn(data);
+};
+
+function _buildParse(self) {
+  const decline = (why) => () => {
+    throw new TypeError(`parse() is not available for this validator: ${why}. Use validate() with removeAdditional instead.`);
+  };
+  const o = self._options;
+  if (o.coerceTypes || o.removeAdditional === 'all' || self._usesKeywords || self._verdictTail !== null || self._validateTail !== null) {
+    return decline('its options or keywords rewrite or extend what the schema checks');
+  }
+  const { cloneExprFor } = require('./lib/clone-emit');
+  const expr = cloneExprFor(self._schemaObj);
+  if (!expr) return decline('the set of keys to keep cannot be proven from the schema');
+  let copy;
+  try {
+    // eslint-disable-next-line no-new-func
+    copy = new Function('data', 'return ' + expr);
+  } catch {
+    return decline('code generation is not allowed here');
+  }
+  self._ensureCompiled();
+  const verdict = self._jsFn;
+  if (typeof verdict !== 'function') return decline('the schema has no generated verdict function');
+  return (data) => {
+    if (!verdict(data)) {
+      const e = new Error('validation failed');
+      e.name = 'AtaValidationError';
+      let target = data;
+      if (self._mutatesInput) {
+        try { target = structuredClone(data); } catch { target = data; }
+      }
+      e.errors = self.validate(target).errors;
+      throw e;
+    }
+    return copy(data);
+  };
+}
+
 Validator.prototype._extendChecks = function (resolve) {
   if (typeof resolve !== 'function') throw new TypeError('_extendChecks expects a function');
   this._extendValidate(resolve);

package/lib/aot-impl.js

@@ -189,277 +189,7 @@ function emitFormatDecls(closures, mode, declKW) {
   return { decls: out, exportsSetFormats: false };
 }
 
-// Emit an expression that rebuilds `access` from the properties the schema
-// declares, dropping everything else. This is the sanitising counterpart to
-// removeAdditional: instead of enumerating the input and deleting the keys
-// that do not belong, it reads only the keys that do. That is O(schema)
-// rather than O(input), it leaves the caller's object untouched, and it keeps
-// one hidden class instead of walking the object through a transition per
-// delete.
-//
-// Returns null when the clone cannot be proven exact, and the module then
-// simply has no parse(). Declining is recoverable; a sanitiser that quietly
-// drops a property the schema allows is not.
-// Resolve a local JSON pointer ('#', '#/$defs/x', draft-7 '#/definitions/x',
-// any '#/...' path) against the schema root. Returns null for anything else:
-// external documents, anchors, URNs. Those stay with the runtime engines.
-function resolveLocalPointer(root, ref) {
-  if (ref === '#') return root;
-  if (typeof ref !== 'string' || !ref.startsWith('#/')) return null;
-  let cur = root;
-  for (const raw of ref.slice(2).split('/')) {
-    let seg = raw.replace(/~1/g, '/').replace(/~0/g, '~');
-    if (cur === null || typeof cur !== 'object') return null;
-    if (!Object.prototype.hasOwnProperty.call(cur, seg)) {
-      try { seg = decodeURIComponent(seg); } catch (_) { return null; }
-      if (!Object.prototype.hasOwnProperty.call(cur, seg)) return null;
-    }
-    cur = cur[seg];
-  }
-  return cur;
-}
-
-// Inline local, acyclic $refs before the clone proof runs, so a generated
-// schema ($defs + $ref, the shape every schema generator emits) can still get
-// a parse(). Only a node that is exactly a $ref plus annotations is replaced;
-// a $ref with a constraining sibling, a cycle, an unresolvable target or an
-// external reference is left in place, and emitClone declines it as before.
-// The walk never mutates its input and never descends into data positions
-// (default, const, enum, examples), where an object holding a "$ref" key is
-// a value, not a schema.
-const _INLINE_ANNOTATIONS = new Set(['$ref', 'title', 'description', '$comment', 'examples', 'deprecated', 'readOnly', 'writeOnly', 'default']);
-const _INLINE_DATA_KEYS = new Set(['default', 'const', 'enum', 'examples']);
-function inlineRefsForClone(root) {
-  const state = { budget: 512 };
-  // `inRef` marks content brought in from behind a reference. The runtime's
-  // useDefaults fills a default written next to the $ref, and does not fill
-  // defaults written inside the referenced definition, so the inlined copy
-  // keeps the first and drops the second. parse() must stay exactly as
-  // generous as validate(); a parse that fills more is a disagreement, not a
-  // feature.
-  const walk = (node, active, inRef) => {
-    if (!node || typeof node !== 'object') return node;
-    if (Array.isArray(node)) return node.map((n) => walk(n, active, inRef));
-    let cur = node;
-    let entered = false;
-    let siblingDefault;
-    while (cur && typeof cur === 'object' && !Array.isArray(cur) && typeof cur.$ref === 'string') {
-      for (const k of Object.keys(cur)) if (!_INLINE_ANNOTATIONS.has(k)) return node;
-      if (active.has(cur.$ref) || state.budget-- <= 0) return node;
-      const target = resolveLocalPointer(root, cur.$ref);
-      if (!target || typeof target !== 'object' || Array.isArray(target)) return node;
-      if (!entered && !inRef && cur.default !== undefined) siblingDefault = cur.default;
-      active = new Set(active);
-      active.add(cur.$ref);
-      cur = target;
-      entered = true;
-    }
-    const strip = inRef || entered;
-    const out = {};
-    for (const k of Object.keys(cur)) {
-      if (strip && k === 'default') continue;
-      const v = cur[k];
-      if (_INLINE_DATA_KEYS.has(k) || k === '$defs' || k === 'definitions') { out[k] = v; continue; }
-      out[k] = walk(v, active, strip);
-    }
-    if (siblingDefault !== undefined) out.default = siblingDefault;
-    return out;
-  };
-  return walk(root, new Set(), false);
-}
-
-function emitClone(node, access, depth) {
-  if (!node || typeof node !== 'object') return null;
-  if (depth > 12) return null;
-  // Only plain object nodes are cloneable, and only when the schema names
-  // every property it keeps. A $ref means the set of allowed keys is not
-  // this node's to decide. In-place applicators (allOf, anyOf, oneOf,
-  // if/then/else) are admitted under the same proof the unevaluated* error
-  // generators use: every property name they contribute must already be
-  // declared in this node's own `properties`, so they constrain values but
-  // never widen the key set. `not` never widens it. `unevaluatedProperties`
-  // is admitted only as `false` under that proof, where it is exactly
-  // `additionalProperties: false`.
-  if (node.$ref || node.patternProperties || node.additionalProperties === true) {
-    return null;
-  }
-  // additionalProperties as a schema is the record shape (z.record and every
-  // generator's map type): the key set is open by declaration, so keeping
-  // every key is exact, and every undeclared value is rebuilt against that
-  // one schema. That is a proof, not a guess, so it is admitted. What stays
-  // out: applicators next to a record (a branch could constrain some keys'
-  // values beyond the record schema, and the rebuild would ignore it), and
-  // `additionalProperties: true`, where the value is unconstrained and this
-  // pass only copies what it can name. An open object with no
-  // `additionalProperties` at all also stays out, for the original reason:
-  // validate() accepts its unknown keys, so a parse() that strips them would
-  // silently drop allowed data, and one that keeps them raw would not be a
-  // sanitiser.
-  const apSchema = (node.additionalProperties && typeof node.additionalProperties === 'object')
-    ? node.additionalProperties
-    : null;
-  if (apSchema) {
-    if (node.unevaluatedProperties !== undefined) return null;
-    if (node.allOf || node.anyOf || node.oneOf || node.if || node.then || node.else ||
-        node.dependentSchemas !== undefined || node.dependencies !== undefined ||
-        node.$dynamicRef !== undefined || node.$recursiveRef !== undefined) return null;
-  }
-  if (node.unevaluatedProperties !== undefined && node.unevaluatedProperties !== false) return null;
-  if (node.type !== 'object') return null;
-  if (!node.properties && !apSchema) return null;
-  const keys = node.properties ? Object.keys(node.properties) : [];
-  if (keys.length === 0 && !apSchema) return null;
-  if (node.allOf || node.anyOf || node.oneOf || node.if || node.then || node.else ||
-      node.unevaluatedProperties === false) {
-    if (node.$dynamicRef !== undefined || node.$recursiveRef !== undefined ||
-        node.dependentSchemas !== undefined || node.dependencies !== undefined) return null;
-    const names = new Set();
-    const state = { prefix: 0 };
-    for (const k of ['allOf', 'anyOf', 'oneOf']) {
-      if (node[k] !== undefined) {
-        if (!Array.isArray(node[k])) return null;
-        for (const b of node[k]) if (!unevalContributions(b, 'props', names, state, 0)) return null;
-      }
-    }
-    for (const k of ['if', 'then', 'else']) {
-      if (node[k] !== undefined && !unevalContributions(node[k], 'props', names, state, 0)) return null;
-    }
-    for (const n of names) if (!Object.prototype.hasOwnProperty.call(node.properties, n)) return null;
-  }
-  const required = new Set(Array.isArray(node.required) ? node.required : []);
-
-  const fixed = [];
-  const conditional = [];
-  for (const key of keys) {
-    const prop = node.properties[key];
-    if (!prop || typeof prop !== 'object') return null;
-    if (prop.$ref) return null;
-    // A property that is required and carries a default is the one place the
-    // runtime and a raw-input validation disagree: the runtime fills the
-    // default before checking `required`, so `{}` validates there and would
-    // throw here. Declining keeps parse() exactly as strict as validate().
-    if (required.has(key) && prop.default !== undefined) return null;
-    // A default the property's own schema rejects would make parse() hand
-    // back a document validate() refuses: the runtime fills defaults before
-    // validating, so it catches the bad default, and a raw-input check here
-    // never sees it. Probe the default at emit time and decline when it does
-    // not hold, or when the subschema cannot be compiled to check it.
-    if (prop.default !== undefined) {
-      let probe = null;
-      try { probe = compileToJSCodegen(prop, null, null); } catch (_) { probe = null; }
-      if (!probe || !probe(prop.default)) return null;
-    }
-    const read = `${access}[${JSON.stringify(key)}]`;
-    const value = emitValueExpr(prop, read, depth);
-    if (value === null) return null;
-    // Computed key syntax: a plain `"__proto__":` in an object literal is
-    // the prototype slot, not a property; `["__proto__"]:` is a property.
-    if (required.has(key)) fixed.push(`[${JSON.stringify(key)}]: ${value}`);
-    else conditional.push({ key, value, dflt: prop.default });
-  }
-  if (fixed.length === 0 && conditional.length === 0 && !apSchema) return null;
-
-  const tmp = `_c${depth}`;
-  // The record loop: every key of the input that is not a declared property
-  // is kept, its value rebuilt against the additionalProperties schema. The
-  // input is already validated, so every such value satisfies that schema;
-  // the rebuild only strips inside it. Defaults under a record value are
-  // dropped before emission because the runtime's useDefaults does not fill
-  // them there, and parse() must equal validate().data, not improve on it.
-  let recordLoop = '';
-  if (apSchema) {
-    const kVar = `_k${depth}`;
-    const vVar = `_v${depth}`;
-    const valueExpr = emitValueExpr(stripDefaultsDeep(apSchema), vVar, depth);
-    if (valueExpr === null) return null;
-    let skip = '';
-    let declSet = '';
-    if (keys.length > 8) {
-      declSet = `const _d${depth} = new Set(${JSON.stringify(keys)}); `;
-      skip = `if (_d${depth}.has(${kVar})) continue; `;
-    } else if (keys.length > 0) {
-      skip = `if (${keys.map((k) => `${kVar} === ${JSON.stringify(k)}`).join(' || ')}) continue; `;
-    }
-    // The key comes from the input, so it can be the string "__proto__" (an
-    // own key only JSON.parse writes); assignment would hit the prototype
-    // setter, so that one key goes through defineProperty.
-    recordLoop = ` ${declSet}for (const ${kVar} of Object.keys(${access})) { ${skip}const ${vVar} = ${access}[${kVar}]; if (${kVar} === "__proto__") Object.defineProperty(${tmp}, ${kVar}, { value: ${valueExpr}, writable: true, enumerable: true, configurable: true }); else ${tmp}[${kVar}] = ${valueExpr}; }`;
-  }
-
-  const literal = `{ ${fixed.join(', ')} }`;
-  if (conditional.length === 0 && !recordLoop) return literal;
-  // Optional properties are added only when present, so the result never
-  // gains a key the input did not have.
-  const adds = conditional
-    .map(({ key, value, dflt }) => {
-      // Object.hasOwn, not `in`: `in` also answers for what the instance
-      // inherits, so a property named `constructor` would copy the inherited
-      // function into the output that validate().data does not carry. And a
-      // key named `__proto__` cannot be written by assignment, which hits
-      // the prototype setter; defineProperty writes an own key.
-      const assign = key === '__proto__'
-        ? `Object.defineProperty(${tmp}, ${JSON.stringify(key)}, { value: ${value}, writable: true, enumerable: true, configurable: true });`
-        : `${tmp}[${JSON.stringify(key)}] = ${value};`;
-      const set = `if (Object.hasOwn(${access}, ${JSON.stringify(key)})) ${assign}`;
-      // The default is emitted as a literal inside the call, so an object or
-      // array default is a fresh value on every parse, never shared state.
-      if (dflt === undefined) return set;
-      const setDflt = key === '__proto__'
-        ? `Object.defineProperty(${tmp}, ${JSON.stringify(key)}, { value: ${JSON.stringify(dflt)}, writable: true, enumerable: true, configurable: true });`
-        : `${tmp}[${JSON.stringify(key)}] = ${JSON.stringify(dflt)};`;
-      return `${set} else ${setDflt}`;
-    })
-    .join(' ');
-  return `(function(){ const ${tmp} = ${literal}; ${adds}${recordLoop} return ${tmp}; })()`;
-}
-
-// The value dispatch shared by declared properties and the record loop. A
-// value is copyable only when the emitter can name everything that may live
-// under it: a primitive holds nothing, an object with declared properties or
-// a record schema is rebuilt the same way, an array of primitives has
-// nowhere to hide a key. A $ref, a composition or an untyped node could all
-// carry keys this code cannot see, and copying the reference would smuggle
-// them into a value that claims to be sanitised, so the caller declines the
-// whole clone instead.
-// Drop every schema-position `default` in a subtree, leaving data positions
-// (const, enum, examples) untouched. Used on a record's value schema, where
-// the runtime's useDefaults fills nothing.
-function stripDefaultsDeep(node) {
-  if (!node || typeof node !== 'object') return node;
-  if (Array.isArray(node)) return node.map(stripDefaultsDeep);
-  const out = {};
-  for (const k of Object.keys(node)) {
-    if (k === 'default') continue;
-    out[k] = _INLINE_DATA_KEYS.has(k) ? node[k] : stripDefaultsDeep(node[k]);
-  }
-  return out;
-}
-
-const _CLONE_PRIMITIVE = new Set(['string', 'number', 'integer', 'boolean', 'null']);
-function emitValueExpr(prop, read, depth) {
-  if (!prop || typeof prop !== 'object') return null;
-  if (prop.$ref) return null;
-  const types = Array.isArray(prop.type) ? prop.type : [prop.type];
-  if (types.every((t) => _CLONE_PRIMITIVE.has(t))) return read;
-  const isRecordable = (s) => s.properties ||
-    (s.additionalProperties && typeof s.additionalProperties === 'object');
-  if (prop.type === 'object' && isRecordable(prop)) {
-    return emitClone(prop, read, depth + 1);
-  }
-  if (prop.type === 'array' && prop.items && typeof prop.items === 'object' &&
-      !Array.isArray(prop.items)) {
-    const it = prop.items;
-    const itemTypes = Array.isArray(it.type) ? it.type : [it.type];
-    if (itemTypes.every((t) => _CLONE_PRIMITIVE.has(t))) return read;
-    if (it.type === 'object' && isRecordable(it)) {
-      const el = '_e' + depth;
-      const inner = emitClone(it, el, depth + 1);
-      if (!inner) return null;
-      return `${read}.map((${el}) => (${inner}))`;
-    }
-  }
-  return null;
-}
+const { emitClone, inlineRefsForClone } = require('./clone-emit');
 
 function toStandaloneModule(validator, opts) {
   assertEmittable(validator, 'toStandaloneModule');