@jarenjs/validate 0.8.4 → 0.34.0

package/src/dollar-data.js

@@ -0,0 +1,212 @@
+//@ts-check
+
+/**
+ * @fileoverview Ajv $data keyword implementation for referencing instance data.
+ *
+ * This implements the Ajv-style "$data" keyword, allowing constraint keyword values
+ * to be sourced from instance data at validation time using Relative JSON Pointers.
+ *
+ * Example:
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "smaller": {
+ *       "type": "number",
+ *       "maximum": { "$data": "1/larger" }
+ *     },
+ *     "larger": {
+ *       "type": "number"
+ *     }
+ *   }
+ * }
+ *
+ * The "$data" value is a Relative JSON Pointer that resolves from the current data location.
+ * Format: <non-negative-integer>("#" | <json-pointer>)
+ * - "0" - The current value itself
+ * - "0#" - The property name/index of the current value
+ * - "0/foo" - The "foo" property of the current value
+ * - "1" - The parent value
+ * - "1/foo" - The "foo" property of the parent value
+ * - "2/bar" - Go up 2 levels, then look for "bar"
+ *
+ * @see https://github.com/ajv-validator/ajv/tree/master/spec/extras/%24data
+ * @see https://datatracker.ietf.org/doc/html/draft-luff-relative-json-pointer-00
+ */
+
+import {
+  isObjectClass,
+  isStringType,
+  isObjectType,
+} from '@jarenjs/core';
+
+import {
+  equalsDeep,
+} from '@jarenjs/core/object';
+
+import {
+  NUMERIC_CONSTRAINTS, STRING_CONSTRAINTS,
+  ARRAY_CONSTRAINTS, OBJECT_CONSTRAINTS,
+} from '@jarenjs/core/schema';
+
+import {
+  compileDataRef,
+  JSONPOINTER_NOTHING,
+} from '@jarenjs/json';
+
+import {
+  createDataRefCompilers,
+} from './tools.js';
+
+/**
+ * Resolve a `$data` reference.
+ *
+ * Ajv's `$data` takes the same three forms the `data` keyword does — empty for
+ * the root, a Relative JSON Pointer, or an absolute JSON Pointer — and this
+ * used to compile only the relative form. An absolute `$data: '/limit'` threw,
+ * was swallowed by the catch, and became `resolveNothing`: the constraint
+ * silently never asserted, so a document that should have failed passed. A
+ * disabled constraint is worse than a rejected schema, which is why an
+ * uncompilable reference is now a compile-time error.
+ * @param {string} ref
+ * @returns {(dataRoot: any, dataPath: string) => any}
+ */
+function compileRefResolver(ref) {
+  return compileDataRef(ref);
+}
+
+/**
+ * Check if a value is a $data reference object
+ * @param {*} value - The value to check
+ * @returns {boolean} True if the value is a $data reference object
+ */
+function isDollarDataRef(value) {
+  return isObjectClass(value) && isStringType(value.$data);
+}
+
+// The fifteen keyword validators are shared with the `data` keyword;
+// only `compileRefResolver` above differs (see tools.js). uniqueItems
+// and required below are $data-only and stay local.
+const KEYWORD_COMPILERS = createDataRefCompilers(compileRefResolver);
+
+//#region $data-only Validators
+
+/**
+ * Compile $data reference for uniqueItems constraint
+ * @param {object} schemaObj - The validation object
+ * @param {string} ref - The $data reference (relative JSON Pointer)
+ * @returns {function|undefined} The compiled validator function
+ */
+function compileDollarDataUniqueItems(schemaObj, ref) {
+  const addError = schemaObj.createErrorHandler(ref, 'uniqueItems');
+  const resolveRef = compileRefResolver(ref);
+
+  return function validateDollarDataUniqueItems(data, dataPath, dataRoot) {
+    if (!Array.isArray(data)) return true;
+
+    const shouldBeUnique = resolveRef(dataRoot, dataPath);
+    if (shouldBeUnique === JSONPOINTER_NOTHING || !shouldBeUnique) return true;
+
+    // Check for duplicates using deep equality
+    for (let i = 0; i < data.length; i++) {
+      for (let j = i + 1; j < data.length; j++) {
+        if (equalsDeep(data[i], data[j])) {
+          return addError(data, dataPath);
+        }
+      }
+    }
+    return true;
+  };
+}
+
+/**
+ * Compile $data reference for required constraint
+ * @param {object} schemaObj - The validation object
+ * @param {string} ref - The $data reference (relative JSON Pointer)
+ * @returns {function|undefined} The compiled validator function
+ */
+function compileDollarDataRequired(schemaObj, ref) {
+  // Keyed handler: the missing property name travels as the dataKey, so
+  // error conversion extracts params.missingProperty like static required.
+  const addError = schemaObj.createErrorHandler(ref, ['required']);
+  const resolveRef = compileRefResolver(ref);
+
+  return function validateDollarDataRequired(data, dataPath, dataRoot) {
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) return true;
+
+    const requiredProps = resolveRef(dataRoot, dataPath);
+    if (requiredProps === JSONPOINTER_NOTHING || !Array.isArray(requiredProps)) return true;
+
+    for (const prop of requiredProps) {
+      if (!(prop in data)) {
+        return addError(prop, data, dataPath);
+      }
+    }
+    return true;
+  };
+}
+
+//#endregion
+
+//#region Main Compilation
+
+/** Application order of the $data-capable keywords (error order is part
+ * of the observable behavior; the shared groups' internal order IS the
+ * historical per-keyword dispatch sequence — `@jarenjs/core/schema`
+ * documents that order as contract). */
+const DOLLAR_KEYWORD_ORDER = [
+  ...NUMERIC_CONSTRAINTS,
+  ...STRING_CONSTRAINTS,
+  ...ARRAY_CONSTRAINTS,
+  ...OBJECT_CONSTRAINTS, 'required',
+  'enum', 'const',
+];
+
+const DOLLAR_ONLY_COMPILERS = {
+  __proto__: null,
+  uniqueItems: compileDollarDataUniqueItems,
+  required: compileDollarDataRequired,
+};
+
+/**
+ * Compile $data keyword validators for a schema object
+ * This detects when keyword values are { $data: "..." } objects and creates
+ * dynamic validators that resolve the reference at validation time.
+ *
+ * @param {object} schemaObj - The validation object
+ * @param {object} jsonSchema - The JSON schema to compile
+ * @returns {function|undefined} The compiled validator function or undefined
+ */
+export function compileDollarDataSchema(schemaObj, jsonSchema) {
+  const validators = [];
+
+  for (const keyword of DOLLAR_KEYWORD_ORDER) {
+    const value = jsonSchema[keyword];
+    if (!isDollarDataRef(value)) continue;
+
+    const compileKeyword = KEYWORD_COMPILERS[keyword] ?? DOLLAR_ONLY_COMPILERS[keyword];
+    const validator = compileKeyword(schemaObj, value.$data);
+    if (validator) validators.push(validator);
+  }
+
+  if (validators.length === 0) {
+    return undefined;
+  }
+
+  if (validators.length === 1) {
+    return validators[0];
+  }
+
+  return function validateDollarDataSchema(data, dataPath, dataRoot) {
+    for (let i = 0; i < validators.length; i++) {
+      if (!validators[i](data, dataPath, dataRoot)) {
+        return false;
+      }
+    }
+    return true;
+  };
+}
+
+export function isDollarDataReference(jsonSchema) {
+  return (jsonSchema !== null && (isObjectType(jsonSchema) && jsonSchema.$data));
+}
+//#endregion

package/src/dynamic-ref.js

@@ -0,0 +1,121 @@
+//@ts-check
+
+/**
+ * Dynamic Reference Resolution Module
+ * 
+ * This module handles $recursiveRef (draft 2019-09) and $dynamicRef (draft 2020-12)
+ * which require runtime resolution based on dynamic scope.
+ * 
+ * Key concepts:
+ * - $recursiveRef: References the nearest parent schema with $recursiveAnchor: true
+ * - $dynamicRef: References the nearest parent schema with matching $dynamicAnchor
+ * 
+ * Unlike regular $ref, these require runtime resolution because the target depends
+ * on the dynamic context where the schema is used.
+ */
+
+import { isObjectClass, isStringType } from '@jarenjs/core';
+
+/**
+ * Check if a schema has $recursiveAnchor: true.
+ * @param {object} schema - The schema object
+ * @returns {boolean}
+ */
+export function hasRecursiveAnchor(schema) {
+  return isObjectClass(schema) && schema.$recursiveAnchor === true;
+}
+
+/**
+ * Get the $dynamicAnchor name from a schema.
+ * @param {object} schema - The schema object
+ * @returns {string|null}
+ */
+export function getDynamicAnchorName(schema) {
+  if (!isObjectClass(schema)) return null;
+  return isStringType(schema.$dynamicAnchor) ? schema.$dynamicAnchor : null;
+}
+
+/**
+ * Collect ALL dynamic anchors of a schema RESOURCE: every $dynamicAnchor
+ * reachable from the given schema without crossing into an embedded
+ * resource (a subschema that declares its own $id).
+ *
+ * Per draft 2020-12, entering a schema resource during evaluation brings
+ * every $dynamicAnchor of that resource into the dynamic scope - wherever
+ * it sits ($defs, allOf branches, properties, ...), not just at the root.
+ *
+ * @param {object} schema - The resource root schema object
+ * @returns {Array<{name: string, schema: object, validator: (function|null)}>}
+ */
+export function collectDynamicAnchorsDeep(schema) {
+  const anchors = [];
+  if (!isObjectClass(schema)) return anchors;
+
+  const seen = new Set();
+  const queue = [{ node: schema, isRoot: true }];
+  while (queue.length > 0) {
+    const { node, isRoot } = queue.shift();
+    if (!isObjectClass(node) && !Array.isArray(node)) continue;
+    if (seen.has(node)) continue;
+    seen.add(node);
+
+    if (Array.isArray(node)) {
+      for (let i = 0; i < node.length; ++i) {
+        queue.push({ node: node[i], isRoot: false });
+      }
+      continue;
+    }
+
+    // A nested $id starts a new (embedded) resource - its anchors enter
+    // the dynamic scope only when that resource itself is entered.
+    if (!isRoot && isStringType(node.$id)) continue;
+
+    const anchorName = getDynamicAnchorName(node);
+    if (anchorName) {
+      anchors.push({ name: anchorName, schema: node, validator: null });
+    }
+
+    for (const key of Object.keys(node)) {
+      queue.push({ node: node[key], isRoot: false });
+    }
+  }
+
+  return anchors;
+}
+
+/**
+ * Collect all dynamic anchors from a schema's immediate definitions ($defs/definitions).
+ * This is used to find all $dynamicAnchor definitions that should be in scope
+ * when following a $ref from this schema.
+ *
+ * IMPORTANT: This only collects from the IMMEDIATE $defs of the given schema,
+ * not recursively.
+ *
+ * @param {object} schema - The schema object
+ * @returns {Array<{name: string, schema: object}>} Array of {name, schema} objects
+ */
+export function collectDynamicAnchors(schema) {
+  const anchors = [];
+  if (!isObjectClass(schema)) return anchors;
+
+  // Check $defs first (draft 2020-12), then definitions (draft 7 and earlier)
+  const defs = schema.$defs || schema.definitions;
+  if (isObjectClass(defs)) {
+    for (const key of Object.keys(defs)) {
+      const def = defs[key];
+      if (isObjectClass(def)) {
+        // Check if this definition has a $dynamicAnchor
+        const anchorName = getDynamicAnchorName(def);
+        if (anchorName) {
+          anchors.push({ name: anchorName, schema: def, key });
+        }
+        // Note: We do NOT recurse into nested $defs here.
+        // Dynamic anchors from nested $defs of a $ref target should NOT be
+        // automatically in scope - they should only be registered when that
+        // schema is actually evaluated.
+      }
+    }
+  }
+
+  return anchors;
+}

package/src/enum.js

@@ -0,0 +1,147 @@
+//@ts-check
+
+import {
+  isScalarType,
+} from '@jarenjs/core';
+
+import {
+  equalsDeep,
+} from '@jarenjs/core/object';
+
+import {
+  getArrayClassMinItems,
+} from './tools.js';
+import { isDollarDataReference } from './dollar-data.js';
+
+// export const exampleEnumDataStructure = {
+//   allOf: [
+//     {
+//       enum: {
+//         source: false, // jsonpath!!
+//         data: [
+//           { color: 0xFFFFFF, name: 'white', type: 'greys' },
+//           { color: 0x000000, name: 'black', type: 'greys' },
+//           null, // this null will not be included in resulting enum array.
+//           { color: 0xFF0000, name: 'red', type: 'reds' },
+//           { color: 0x00FF00, name: 'green', type: 'greens' },
+//           { color: 0x0000FF, name: 'blue', type: 'blues' },
+//         ],
+//         group: 'type',
+//         label: 'name',
+//         value: 'color',
+//       },
+//     },
+//     {
+//       enum: {
+//         source: false, // jsonpath!!
+//         data: [
+//           [0xFFFFFF, 'white', 'greys'],
+//           [0x000000, 'black', 'greys'],
+//           null, // null will be ignored
+//           [0xFF0000, 'red', 'reds'],
+//           [0x00FF00, 'green', 'greens'],
+//           [0x0000FF, 'blue', 'blues'],
+//         ],
+//         group: 2,
+//         label: 1,
+//         value: 0,
+//       },
+//     },
+//     {
+//       enum: {
+//         data: [
+//           { value: 0xFFFFFF, label: 'white', group: 'greys' },
+//           { value: 0x000000, label: 'black', group: 'greys' },
+//           null, // null will be ignored
+//           { value: 0xFF0000, label: 'red', group: 'reds' },
+//           { value: 0x00FF00, label: 'green', group: 'greens' },
+//           { value: 0x0000FF, label: 'blue', group: 'blues' },
+//         ],
+//       },
+//     },
+//     {
+//       enum: {
+//         data: [
+//           [0xFFFFFF, 'white', 'greys'],
+//           [0x000000, 'black', 'greys'],
+//           null, // null will be ignored
+//           [0xFF0000, 'red', 'reds'],
+//           [0x00FF00, 'green', 'greens'],
+//           [0x0000FF, 'blue', 'blues'],
+//         ],
+//       },
+//     },
+//   ],
+// };
+
+function compileConst(schemaObj, jsonSchema) {
+  const constant = jsonSchema.const;
+  if (constant === undefined)
+    return undefined;
+
+  if (isDollarDataReference(constant))
+    return undefined;
+
+  const addError = schemaObj.createErrorHandler(constant, 'const');
+
+  if (constant === null || isScalarType(constant)) {
+    return function validatePrimitiveConst(data, dataPath) {
+      return constant === data
+        || addError(data, dataPath);
+    };
+  }
+  else {
+    return function validateComplexConst(data, dataPath) {
+      return equalsDeep(constant, data)
+        || addError(data, dataPath);
+    };
+  }
+}
+
+function compileEnum(schemaObj, jsonSchema) {
+  const enums = getArrayClassMinItems(jsonSchema.enum, 1);
+  if (enums == null) return undefined;
+
+  let hasObjects = false;
+  for (let i = 0; i < enums.length; ++i) {
+    const e = enums[i];
+    if (e != null && typeof e === 'object') {
+      hasObjects = true;
+      break;
+    }
+  }
+
+  const addError = schemaObj.createErrorHandler(enums, 'enum');
+
+  if (hasObjects === false) {
+    return function validateEnumSimple(data, dataPath) {
+      return data === undefined
+        ? true
+        : enums.includes(data)
+          ? true
+          : addError(data, dataPath);
+    };
+  }
+  else {
+    return function validateEnumDeep(data, dataPath) {
+      if (data === undefined) return true;
+      if (data === null || typeof data !== 'object')
+        return enums.includes(data)
+          ? true
+          : addError(data, dataPath);
+
+      for (let i = 0; i < enums.length; ++i) {
+        if (equalsDeep(enums[i], data) === true)
+          return true;
+      }
+      return addError(data, dataPath);
+    };
+  }
+}
+
+export function compileEnumBasic(schemaObj, jsonSchema) {
+  return [
+    compileConst(schemaObj, jsonSchema),
+    compileEnum(schemaObj, jsonSchema),
+  ];
+}

package/src/format.js

@@ -0,0 +1,108 @@
+import {
+  isStringType,
+  isFn,
+} from '@jarenjs/core';
+
+/** @typedef {import('./index.js').FormatCompiler} FormatCompiler */
+
+/**
+ * Registers a single format compiler under a name.
+ * Existing registrations are never overwritten.
+ * @param {Record<string, FormatCompiler>} registered - The formats registry object
+ * @param {string} name - The format name (e.g. 'email', 'uri', 'date-time')
+ * @param {FormatCompiler} formatCompiler - The compiler to register
+ * @returns {boolean} True when the compiler was registered
+ */
+export function registerFormatCompiler(registered, name, formatCompiler) {
+  if (registered[name] == null) {
+    if (isFn(formatCompiler)) {
+      registered[name] = formatCompiler;
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Registers multiple format compilers at once.
+ * Existing registrations are never overwritten.
+ * @param {Record<string, FormatCompiler>} registered - The formats registry object
+ * @param {Record<string, FormatCompiler>} formatCompilers - Object mapping format names to compiler functions
+ * @returns {Record<string, FormatCompiler>} The registry object passed in
+ */
+export function registerFormatCompilers(registered, formatCompilers) {
+  const keys = Object.keys(formatCompilers);
+  for (let i = 0; i < keys.length; ++i) {
+    const key = keys[i];
+    const item = formatCompilers[key];
+    registerFormatCompiler(registered, key, item);
+  }
+  return registered;
+}
+
+/** Named once: both wrong-shape paths end at the same mistake. */
+const WRONG_SHAPE_HINT = 'Register the format COMPILERS (stringFormats, dateTimeFormats, '
+  + 'numberFormats, jsonFormats, geoFormats) rather than the raw testers (formatTesters) — '
+  + 'both are objects full of functions, and only the compilers take (schemaObj, jsonSchema).';
+
+export function getSchemaFormatCompiler(registered, name) {
+  if (isStringType(name))
+    return registered[name];
+  else
+    return undefined;
+}
+
+export function compileFormatBasic(schemaObj, jsonSchema) {
+  if (!isStringType(jsonSchema.format))
+    return undefined;
+
+  // From draft 2020-12 on, format is annotation-only unless assertion is
+  // enabled (formatAssertion option or format-assertion vocabulary).
+  // Nothing is lost by an unregistered name here — the keyword would not
+  // have asserted even with a compiler — so the unknownFormats check
+  // below deliberately does not run in this branch. Complaining here
+  // would be complaining about the spec.
+  if (schemaObj.options.formatAssertion === false)
+    return undefined;
+  const compiler = getSchemaFormatCompiler(
+    schemaObj.formats,
+    jsonSchema.format);
+
+  // An unregistered name with assertion ON is the silent failure this
+  // check exists to end: the author asked for the value to be checked,
+  // the registry has nothing to check it with, and without this the
+  // schema compiles to a validator that accepts everything. Raising it
+  // at COMPILE time keeps instance validation spec-exact — no data is
+  // ever invalidated by an unknown format, the schema's AUTHOR is told.
+  if (compiler == null) {
+    if (schemaObj.options.unknownFormats === 'ignore')
+      return undefined;
+    throw new Error(`Unknown format '${jsonSchema.format}': no compiler is registered for it, `
+      + 'so this schema would accept every value for that keyword. Register one '
+      + '(addFormats(dateTimeFormats) etc. from @jarenjs/formats, or addFormat(name, compiler) '
+      + "for your own), or pass { unknownFormats: 'ignore' } to accept it as an annotation.");
+  }
+
+  // A format COMPILER is called once per schema location and returns the
+  // per-value validator. Handing it a bare tester — `formatTesters`
+  // instead of `dateTimeFormats`, an easy mistake since both are objects
+  // full of functions — either returns a boolean (which the caller
+  // silently drops, so the format checks nothing again) or throws deep
+  // inside the tester on an argument it never expected. Both become one
+  // legible complaint here.
+  let validator;
+  try {
+    validator = compiler(schemaObj, jsonSchema);
+  }
+  catch (err) {
+    throw new Error(`Format '${jsonSchema.format}' failed to compile: ${err?.message ?? err}. `
+      + `${WRONG_SHAPE_HINT}`, { cause: err });
+  }
+  // Nullish stays legal: a compiler may decline a schema it cannot serve.
+  if (validator != null && !isFn(validator) && !Array.isArray(validator)) {
+    throw new Error(`Format '${jsonSchema.format}' is registered with something that is not a `
+      + `format compiler: calling it returned ${typeof validator}, not a validator function. `
+      + `${WRONG_SHAPE_HINT}`);
+  }
+  return validator;
+}