@jarenjs/validate 0.8.4 → 0.34.0

package/src/query-keyword.js

@@ -0,0 +1,99 @@
+//@ts-check
+
+//#region '$query' - Jaren JSON Query assertions inside JSON Schema
+// The inverse arrow of ./query.js: where that module puts schemas inside
+// queries (the compileTypeTest hook of QUERY-FORMAT.md section 8.11),
+// this module puts queries inside schemas. The '$query' keyword's value
+// is a Jaren JSON Query document, compiled once at schema compile time
+// and evaluated per validation against the current instance location;
+// the instance is valid when the query result's effective boolean value
+// (QUERY-FORMAT.md section 2.2) is true. Like the 'data' keyword, the
+// extension asserts only when spelled - other validators treat '$query'
+// as an unknown-keyword annotation, so such schemas stay portable.
+//
+// Two externals are bound per call: 'root' (the instance root, so
+// "$root.currency" reaches across the document) and 'path' (the current
+// instance location as a JSON pointer string, comparable via "$path").
+// Any other free name in the query is a schema compile error - there is
+// nothing it could be bound to at validation time.
+
+import {
+  compileJsonQuery,
+  JsonQueryCompileError,
+  JsonQueryRuntimeError,
+} from '@jarenjs/json/query';
+
+import { createTypeTestCompiler } from './query.js';
+
+/**
+ * Compile the '$query' keyword of a schema into a validator.
+ *
+ * The query document compiles with a `compileTypeTest` hook backed by the
+ * owning `JarenValidator` instance (threaded through `ValidationRoot`), so
+ * schema literals inside the query (`$valid`/`$assert`/`$as`) may `$ref`
+ * schemas registered on that instance with `addSchema`. Malformed query
+ * documents (`JQ0xxx`) and externals other than `root`/`path` throw here,
+ * at schema compile time. At validation time the query never throws:
+ * a `JsonQueryRuntimeError` (`JQ2xxx` - a data-shaped failure such as the
+ * EBV of a multi-item result or arithmetic on a non-number) reports as a
+ * validation failure whose error params carry the `code` and the query
+ * `docPath`.
+ *
+ * @param {object} schemaObj - The validation object
+ * @param {object} jsonSchema - The JSON schema containing the '$query' keyword
+ * @returns {function|undefined} The compiled validator function or undefined
+ */
+export function compileQuerySchema(schemaObj, jsonSchema) {
+  const queryDoc = jsonSchema.$query;
+  if (queryDoc === undefined) return undefined;
+
+  const owner = schemaObj.root.owner;
+  const compileTypeTest = createTypeTestCompiler(owner ?? undefined);
+
+  let query;
+  try {
+    query = compileJsonQuery(queryDoc, { compileTypeTest });
+  }
+  catch (e) {
+    if (e instanceof JsonQueryCompileError)
+      throw new Error(`invalid '$query' document at '${schemaObj.path}': ${e.message}`, { cause: e });
+    throw e;
+  }
+
+  const externals = query.externals;
+  for (let i = 0; i < externals.length; ++i) {
+    const name = externals[i];
+    if (name !== 'root' && name !== 'path')
+      throw new Error(`'$query' cannot bind external '${name}' at '${schemaObj.path}' (only 'root' and 'path' are bound)`);
+  }
+
+  const addError = schemaObj.createErrorHandler(queryDoc, '$query');
+
+  // The compiled query copies externals into its frame before evaluating,
+  // so one bindings object per compiled keyword is safe to reuse across
+  // validations (a nested '$query' compiles into its own closure world
+  // and owns its own object).
+  const ext = { root: null, path: '' };
+
+  return function validateQuerySchema(data, dataPath, dataRoot) {
+    if (data === undefined) return true;
+    ext.root = dataRoot;
+    ext.path = dataPath;
+    try {
+      return query.ebv(data, ext) || addError(data, dataPath);
+    }
+    catch (e) {
+      // Validators must not throw on data: a runtime error is a failed
+      // assertion. Compile-time checks left JQ2003 (multi-item EBV) and
+      // JQ2001-class operator errors as the reachable conditions here.
+      if (e instanceof JsonQueryRuntimeError)
+        return addError(data, dataPath, e.code, e.docPath);
+      throw e;
+    }
+    finally {
+      ext.root = null; // do not pin the last validated document
+    }
+  };
+}
+
+//#endregion

package/src/query.js

@@ -0,0 +1,85 @@
+//@ts-check
+
+//#region @jarenjs/validate/query - the Jaren JSON Query type-test bridge
+// Wires this validator into the Jaren JSON Query engine's schema
+// operators ($valid/$assert/$as, QUERY-FORMAT.md section 8.11). The
+// engine (@jarenjs/json) defines only a hook contract - `compileTypeTest:
+// (schemaJson, docPath) => (value) => boolean` - and never imports this
+// package; the dependency runs validate -> json, one way, so no cycle
+// exists. This module turns a JarenValidator into that hook: every schema
+// literal in a query document compiles once, at query compile time, into
+// the same closure world the query engine lives in.
+
+import { JarenValidator } from './index.js';
+
+/**
+ * Project a diagnostic string from whatever the validator threw, without
+ * reading `.message` off a raw value or coercing it.
+ * @param {unknown} e
+ * @returns {string}
+ */
+function failureText(e) {
+  if (e instanceof Error && typeof e.message === 'string')
+    return e.message;
+  return typeof e === 'string' ? e : 'schema compilation failed';
+}
+
+/**
+ * Create a `compileTypeTest` hook for `compileJsonQuery` (see
+ * `@jarenjs/json/query`), backed by a `JarenValidator`.
+ *
+ * The hook compiles each schema literal with the validator and returns
+ * its boolean-mode validation function - errors off, the fast path of
+ * this package's architecture. Schema compile failures (an invalid
+ * schema literal, an unresolvable `$ref`) propagate as plain errors; the
+ * query engine wraps them into `JsonQueryCompileError` `JQ0009` with the
+ * operator's document pointer.
+ *
+ * @param {object | (() => object)} [validator] - a `JarenValidator`
+ *   instance to compile with, or a zero-argument factory producing one.
+ *   Supply an instance with registered schemas (`addSchema`) so `$ref`s
+ *   in query schema literals resolve against them. Omitted, a fresh
+ *   default (boolean-mode) instance is created.
+ * @returns {(schemaJson: any, docPath: string) => ((value: any) => boolean)}
+ *   a hook suitable for `compileJsonQuery(doc, { compileTypeTest })`
+ * @example
+ * import { compileJsonQuery } from '@jarenjs/json/query';
+ * import { createTypeTestCompiler } from '@jarenjs/validate/query';
+ *
+ * const query = compileJsonQuery({
+ *   "$for": { "b": "$.store.book[*]" },
+ *   "$as": { "b": { "type": "object", "required": ["price"] } },
+ *   "$return": "$b.title"
+ * }, { compileTypeTest: createTypeTestCompiler() });
+ */
+export function createTypeTestCompiler(validator = undefined) {
+  const instance = validator == null
+    ? new JarenValidator()
+    : (typeof validator === 'function' ? validator() : validator);
+  return function compileTypeTest(schemaJson, docPath) {
+    let validate;
+    try {
+      validate = instance.compile(schemaJson);
+    }
+    catch (err) {
+      // The engine's JQ0009 names the operator that owns the schema; this
+      // names the schema literal itself, which is what distinguishes one
+      // failing schema from the others in the same query document.
+      const where = typeof docPath === 'string' && docPath !== '' ? docPath : '';
+      throw new Error(
+        where === ''
+          ? failureText(err)
+          : `schema literal at '${where}': ${failureText(err)}`,
+        { cause: err });
+    }
+    // The default validator options are boolean mode (skipErrors on,
+    // collectErrors off): the compiled function IS the predicate. An
+    // error-collecting instance returns { valid, errors } objects
+    // instead - detect that shape once, per schema, and unwrap it.
+    if (typeof validate(null) === 'boolean')
+      return validate;
+    return (value) => validate(value).valid === true;
+  };
+}
+
+//#endregion