@jarenjs/validate 0.8.4 → 0.9.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Joham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,340 @@
-# Jaren Core Package
+# @jarenjs/validate
 
-**this is a working package in need of documentation**
+The JSON Schema validating compiler at the heart of [Jaren](https://github.com/jklarenbeek/jarenjs). It compiles JSON Schemas into optimized validation functions and fully supports `draft-06`, `draft-07`, `draft 2019-09` and `draft 2020-12` — passing 100% of the official [JSON-Schema-Test-Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite) for draft-07, 2019-09 and 2020-12.
+
+## Usage
+
+```javascript
+import { JarenValidator } from '@jarenjs/validate';
+
+const jaren = new JarenValidator();
+
+const validate = jaren.compile({
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    age: { type: 'integer', minimum: 0 }
+  },
+  required: ['name']
+});
+
+validate({ name: 'John', age: 30 }); // true
+```
+
+Key entry points:
+
+- `new JarenValidator(options)` — create a validator instance
+- `.addSchema(schema, key)` — register schemas for `$ref` resolution
+- `.addMetaSchema(schemas, key)` — register (custom) meta-schemas, honoring `$vocabulary`
+- `.addFormats(formats)` — register format validators (see [`@jarenjs/formats`](../formats))
+- `.compile(schema)` — compile a schema into a validation function
+
+Highlights:
+
+- Annotation-based `unevaluatedProperties`/`unevaluatedItems`
+- Spec-compliant dynamic scope for `$dynamicRef`/`$dynamicAnchor` and `$recursiveRef`/`$recursiveAnchor`
+- Per-document draft handling for cross-draft references
+- `$vocabulary`-aware keyword selection and per-draft `format`/content assertion defaults
+- Instance-data references via the `data` keyword (json-everything data-ref) and Ajv-style `$data`
+- Cross-field assertions via the `$query` extension keyword (a [Jaren JSON Query](../json/docs/QUERY-FORMAT.md) inside the schema)
+
+## 🔑 JSON Schema validation keywords
+
+Jaren supports the full set of JSON Schema validation keywords. Here's a quick overview:
+
+- JSON data type: `type`, `nullable`, `required`
+- Numbers: `maximum`, `minimum`, `multipleOf`
+- Strings: `maxLength`, `minLength`, `pattern`
+- Content: `contentEncoding`, `contentMediaType`
+- Arrays: `maxItems`, `minItems`, `uniqueItems`, `items`, `prefixItems`, `contains`, `unevaluatedItems`
+- Objects: `maxProperties`, `minProperties`, `required`, `properties`, `patternProperties`, `unevaluatedProperties`
+- All types: `enum`, `const`
+- Compound: `not`, `oneOf`, `anyOf`, `allOf`, `if/then/else`
+- Meta: `$schema`, `$id`, `$ref`, `$anchor`, `$dynamicRef`/`$dynamicAnchor`, `$recursiveRef`/`$recursiveAnchor`, `$vocabulary`
+- **Non-standard**: `data` (json-everything's [data-ref](https://docs.json-everything.net/schema/examples/data-ref/) proposal), Ajv-style `$data` references, and the [`$query` keyword](#query--cross-field-assertions) below
+
+<details>
+<summary>🔥 For a complete list of supported keywords and their implementation status, click here</summary>
+
+### 🔑 JSON data type
+
+- type
+- nullable | _(OpenAPI)_
+- required | _as boolean (OpenAPI)_
+
+### 🔑 Keywords for numbers
+
+- maximum / minimum<br />or exclusiveMaximum / exclusiveMinimum
+- multipleOf
+
+BigInt instance values are supported too: `maximum`/`minimum`/`exclusiveMaximum`/`exclusiveMinimum` and `multipleOf` compile dedicated BigInt comparators when the data is a `bigint`.
+
+### 🔑 Keywords for strings
+
+- maxLength / minLength
+- pattern
+
+### 🔑 Keywords for content
+
+- contentEncoding | asserts in `draft7`, annotation-only from `draft2019` on (spec default), controlled by the `contentValidation` option
+- contentMediaType | same assertion defaults; `application/json` content is parse-checked
+- ❌ contentSchema | annotation only (never asserted)
+
+### 🔑 Keywords for format
+
+- format
+- formatMinimum / formatMaximum<br />or formatExclusiveMinimum / formatExclusiveMaximum
+
+### 🔑 Keywords for array
+
+- maxItems / minItems
+- uniqueItems
+- items
+  - items | as schema or tuple _deprecated in `draft2020`_
+  - items | as schema only _new `draft2020`_
+- prefixItems | as tuple _new `draft2020`_
+- additionalItems | as schema _deprecated in `draft2020`_
+- contains
+- maxContains / minContains | _new `draft2019`_
+- unevaluatedItems | _new `draft2019`_
+
+### 🔑 Keywords for object
+
+- maxProperties / minProperties
+- required | _as array!_
+- properties
+- patternProperties
+- additionalProperties
+- dependencies | _deprecated in `draft2019`_
+- dependentRequired | _new `draft2019`_
+- dependentSchemas | _new `draft2019`_
+- propertyNames
+- unevaluatedProperties | _new `draft2019`_
+- ❌ [propertyDependencies](https://github.com/json-schema-org/json-schema-spec/blob/main/proposals/propertyDependencies.md)
+
+### 🔑 Keywords for all types
+
+- enum
+- const
+
+### 🔑 Compound keywords
+
+- not
+- oneOf
+- anyOf
+- allOf
+- if / then / else
+
+See also:
+- [Schema Composition](https://json-schema.org/understanding-json-schema/reference/combining)
+- [Applying Subschemas Conditionally](https://json-schema.org/understanding-json-schema/reference/conditionals)
+
+### 🔑 Meta keywords
+
+- $schema | used for draft detection, vocabulary selection and cross-draft references
+- $id
+- $ref
+- $anchor
+- $recursiveRef | _new `draft2019` &amp; deprecated in `draft2020`_
+- $recursiveAnchor | _new `draft2019` &amp; deprecated in `draft2020`_
+- $dynamicRef | _new `draft2020`_
+- $dynamicAnchor | _new `draft2020`_
+- $data | _(Ajv specific)_
+- [$vocabulary](https://github.com/json-schema-org/json-schema-spec/blob/main/proposals/vocabularies.md) | _new `draft2019`_ - a custom metaschema that omits the validation vocabulary turns keywords like `type` and `minimum` into annotations; a metaschema that declares the `format-assertion` vocabulary turns format assertion on
+
+### 🔑 Non-standard keywords
+
+- `data` | json-everything's [data-ref](https://docs.json-everything.net/schema/examples/data-ref/) proposal
+
+  The `data` keyword allows you to reference values from the instance being validated, enabling dynamic constraints based on other parts of the data.
+
+  **Example - Requiring B >= A:**
+  ```json
+  {
+    "type": "object",
+    "properties": {
+      "A": { "type": "number" },
+      "B": {
+        "type": "number",
+        "data": {
+          "minimum": "/A"
+        }
+      }
+    }
+  }
+  ```
+  - Passes: `{ "A": 5, "B": 10 }` (10 >= 5)
+  - Fails: `{ "A": 15, "B": 10 }` (10 < 15)
+
+  **Example - Enum from instance array:**
+  ```json
+  {
+    "type": "object",
+    "properties": {
+      "color": {
+        "data": {
+          "enum": "/validColors"
+        }
+      },
+      "validColors": {
+        "type": "array",
+        "items": { "type": "string" }
+      }
+    }
+  }
+  ```
+
+  **Supported keywords within `data`:**
+  - Number constraints: `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`
+  - String constraints: `minLength`, `maxLength`, `pattern`, `format`
+  - Array constraints: `minItems`, `maxItems`
+  - Object constraints: `minProperties`, `maxProperties`
+  - Value constraints: `enum`, `const`
+
+  Both absolute JSON Pointers (e.g., `/A`, `/limits/min`) and relative JSON Pointers (e.g., `0/parent`, `1/sibling`) are supported.
+
+- `$data` | Ajv-style instance references (`{ "minimum": { "$data": "1/limit" } }`) — supports every keyword the `data` list above supports, plus `uniqueItems` and `required`. Refs compile once at schema compile time through the compiled pointer engine of `@jarenjs/json`.
+
+- `$query` | Jaren's cross-field assertion keyword — see [below](#query--cross-field-assertions)
+
+### 🔑 Miscellaneous keywords
+
+- ❌ strict
+- ❌ strictFormat
+- ❌ strictTuple
+- ❌ errorMessage
+- definitions | used by initial schema traversal _deprecated in `draft2019`_
+- $defs | used by initial schema traversal _new `draft2019`_
+- components | _(OpenAPI)_
+
+</details>
+
+## 🛠️ Notable capabilities
+
+### 👉 Modelling Inheritance with JSON Schema
+
+Jaren fully supports `unevaluatedProperties`, so the inheritance patterns from the [Modelling Inheritance](https://json-schema.org/blog/posts/modelling-inheritance) blog post work out of the box. Annotations flow from `properties`, `patternProperties`, `additionalProperties` and every in-place applicator (`allOf`/`anyOf`/`oneOf`/`if-then-else`/`$ref`/`dependentSchemas`), with annotations from failed branches correctly discarded.
+
+See also:
+- [json-schema-core](https://json-schema.org/draft/2020-12/json-schema-core#name-unevaluatedproperties)
+- [Combining unevaluatedProperties and ref: # #375](https://github.com/orgs/json-schema-org/discussions/375)
+
+### 👉 Express array constraints more cleanly
+
+Jaren fully supports `unevaluatedItems`, covering the array patterns from the 2020-12 [release notes](https://json-schema.org/draft/2020-12/release-notes#contains-and-unevaluateditems): items evaluated by `items`, `prefixItems`, `additionalItems` and (in 2020-12) `contains` are tracked, and everything left over is validated by the `unevaluatedItems` schema.
+
+### 👉 Using Dynamic References to Support Generic Types
+
+Jaren fully supports `$dynamicRef`/`$dynamicAnchor` (2020-12) and `$recursiveRef`/`$recursiveAnchor` (2019-09), including the generic-type patterns from the [dynamicRef and generics](https://json-schema.org/blog/posts/dynamicref-and-generics) blog post. Resolution follows the specification's dynamic-scope rules: entering a schema resource brings all of its dynamic anchors into scope, and a `$dynamicRef` resolves to the anchor in the outermost resource of the dynamic scope.
+
+See also:
+- [Understanding lexical dynamic scopes](https://json-schema.org/blog/posts/understanding-lexical-dynamic-scopes)
+- [$dynamicRef and $dynamicAnchor](https://json-schema.org/draft/2020-12/release-notes#dollardynamicref-and-dollardynamicanchor)
+
+### 👉 Runtime schema manipulation of constraints
+
+Jaren supports the `data-ref` proposal from json-everything through the `data` keyword, plus Ajv-style `$data` references. Both allow a schema constraint to take its value from the instance being validated:
+
+- Absolute JSON Pointers (e.g., `/A`, `/limits/min`)
+- Relative JSON Pointers (e.g., `0/parent`, `1/sibling`)
+- All common constraint keywords: `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`, `minLength`, `maxLength`, `pattern`, `format`, `enum`, `const`, `minItems`, `maxItems`, `minProperties`, `maxProperties`
+
+The refs compile once at schema compile time through the compiled pointer engine of [`@jarenjs/json`](../json) and resolve allocation-free per validation.
+
+See also:
+- [$data](https://github.com/json-schema-org/json-schema-spec/issues/51)
+- [Ajv $data spec](https://github.com/ajv-validator/ajv/tree/master/spec/extras/%24data)
+- [data-ref](https://docs.json-everything.net/schema/examples/data-ref/)
+
+### 👉 Vocabularies and cross-draft references
+
+A schema's `$schema` declaration is honored per document: referenced documents that declare a different draft are processed with that draft's keyword set (a draft-07 document ignores `dependentRequired`; a 2019-09 document ignores `prefixItems`). Custom metaschemas with `$vocabulary` are respected — omitting the validation vocabulary turns validation keywords into annotations, and declaring `format-assertion` turns format assertion on.
+
+## `$query` — cross-field assertions
+
+`$query` is a **Jaren extension keyword**: its value is a
+[Jaren JSON Query](../json/docs/QUERY-FORMAT.md) 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](../json/docs/QUERY-FORMAT.md#22-effective-boolean-value-ebv)
+is true. This gives JSON Schema the class of constraint it is notoriously bad
+at — cross-field arithmetic, ordering, aggregate consistency, quantification —
+through the query engine that already sits underneath the stack. Other
+validators treat `$query` as an unknown-keyword annotation, so schemas using
+it stay portable; the constraint simply only asserts here.
+
+An invoice whose `total` must equal the sum of its line amounts:
+
+```javascript
+const validate = jaren.compile({
+  type: 'object',
+  properties: {
+    lines: { type: 'array', items: { type: 'object' } },
+    total: { type: 'number' }
+  },
+  $query: { $eq: ['$.total', { $sum: '$.lines[*].amount' }] }
+});
+
+validate({ lines: [{ amount: 12.5 }, { amount: 7.5 }], total: 20 }); // true
+validate({ lines: [{ amount: 12.5 }, { amount: 7.5 }], total: 21 }); // false
+```
+
+Date ordering (`$le` compares strings by code points, QUERY-FORMAT §8.4 —
+exactly right for ISO dates):
+
+```javascript
+jaren.compile({ $query: { $le: ['$.start', '$.end'] } });
+```
+
+Quantification over items:
+
+```javascript
+jaren.compile({
+  $query: { $every: { l: '$.lines[*]' }, $satisfies: { $gt: ['$l.qty', 0] } }
+});
+```
+
+Two external parameters are bound on every evaluation: `root` — the instance
+root — and `path` — the current instance location as a JSON pointer string.
+(The JSLT template layer reserves the same two names with one twist: its
+matching language is JSONPath, so its `path` is an RFC 9535 *normalized
+path*, not a pointer — see [JSLT-FORMAT §8.2](../json/docs/JSLT-FORMAT.md).)
+So a subschema can reach across the document:
+
+```javascript
+jaren.compile({
+  type: 'object',
+  properties: {
+    lines: {
+      type: 'array',
+      items: {
+        type: 'object',
+        // every line's currency must match the document-level currency
+        $query: { $eq: ['$.currency', '$root.currency'] }
+      }
+    }
+  }
+});
+```
+
+Semantics and composition:
+
+- `$query` works at **any subschema level** and composes like every other
+  keyword: under `properties`/`items` the query's `$` is that location's
+  value, `$path` its pointer (`/lines/0`, ...), `$root` the whole document.
+- A bare JSONPath string is the degenerate query: `{ "$query": "$.approved" }`
+  asserts the EBV of that member (missing → empty sequence → false).
+- Query **runtime** errors (`JQ2xxx` — e.g. arithmetic on a non-number, the
+  EBV of a multi-item result) are validation **failures**, never throws; in
+  `collectErrors` mode the error params carry the `code` and the query
+  `docPath`. Malformed query documents and free externals other than
+  `root`/`path` fail fast at `compile()`.
+- Schema literals inside the query (`$valid`/`$assert`/`$as`,
+  QUERY-FORMAT §8.11) compile against the **same validator instance**, so
+  their `$ref`s resolve to your `addSchema` registrations.
+
+## Development
+
+Unit tests live in `test/validate/` at the repository root (`npm run test:validate`). Performance against Ajv is measured over the official test suite with the [benchmark workspace](../../benchmark/README.md) (`node benchmark/profiler.js --profile-all`), which also houses the test-failure debugger, coverage and call-graph tools.
+
+This package's internals — the four-phase compile pipeline, ref flattening, annotation tracking, dynamic scope — are described in its own [ARCHITECTURE](./ARCHITECTURE.md) document. For practical usage recipes (options, lightweight setups, custom formats, pitfalls) see the repository [HOWTO](../../HOWTO.md); for the monorepo picture see the repository [README](../../README.md) and [ARCHITECTURE](../../ARCHITECTURE.md); for what is planned next see the [ROADMAP](../../ROADMAP.md).

package/dist/types/array.d.ts

@@ -0,0 +1,2 @@
+export declare function compileArrayPrimitives(schemaObj: any, jsonSchema: any): ((data: any, dataPath: any) => any) | undefined;
+export declare function compileArraySchema(schemaObj: any, jsonSchema: any): ((data: any, dataPath: any, dataRoot: any) => any) | undefined;

package/dist/types/bigint.d.ts

@@ -0,0 +1 @@
+export declare function compileBigIntBasic(schemaObj: any, jsonSchema: any): ((data: any, dataPath: any) => any) | undefined;

package/dist/types/combine.d.ts

@@ -0,0 +1 @@
+export declare function compileCombineSchema(schemaObj: any, jsonSchema: any): any;

package/dist/types/condition.d.ts

@@ -0,0 +1 @@
+export declare function compileConditionSchema(schemaObj: any, jsonSchema: any): ((data: any, dataPath: any, dataRoot: any, dataKey: any) => any) | undefined;

package/dist/types/content.d.ts

@@ -0,0 +1,3 @@
+export declare function compileContentEncoding(schemaObj: any, jsonSchema: any): ((data: any, dataPath: any) => any) | undefined;
+export declare function compileContentMediaType(schemaObj: any, jsonSchema: any): ((data: any, dataPath: any) => any) | undefined;
+export declare function compileContentSchema(schemaObj: any, jsonSchema: any): ((data: any, dataPath: any) => any) | undefined;

package/dist/types/data.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Compile the data keyword schema
+ * @param {object} schemaObj - The validation object
+ * @param {object} jsonSchema - The JSON schema containing the data keyword
+ * @returns {function|undefined} The compiled validator function or undefined
+ */
+export declare function compileDataSchema(schemaObj: object, jsonSchema: object): Function | undefined;

package/dist/types/dollar-data.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare function compileDollarDataSchema(schemaObj: object, jsonSchema: object): Function | undefined;
+/**
+ * Check if the schema has any $data references
+ * This is used to determine if we should use the $data-aware compilation path
+ * or the standard static compilation path.
+ *
+ * @param {object} jsonSchema - The JSON schema to check
+ * @returns {boolean} True if the schema has any $data references
+ */
+export declare function hasDollarDataReferences(jsonSchema: object): boolean;
+export declare function isDollarDataReference(jsonSchema: any): any;

package/dist/types/dynamic-ref.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Check if a schema has $recursiveAnchor: true.
+ * @param {object} schema - The schema object
+ * @returns {boolean}
+ */
+export declare function hasRecursiveAnchor(schema: object): boolean;
+/**
+ * Get the $dynamicAnchor name from a schema.
+ * @param {object} schema - The schema object
+ * @returns {string|null}
+ */
+export declare function getDynamicAnchorName(schema: object): string | 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 declare function collectDynamicAnchorsDeep(schema: object): Array<{
+    name: string;
+    schema: object;
+    validator: (Function | null);
+}>;
+/**
+ * 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 declare function collectDynamicAnchors(schema: object): Array<{
+    name: string;
+    schema: object;
+}>;

package/dist/types/enum.d.ts

@@ -0,0 +1 @@
+export declare function compileEnumBasic(schemaObj: any, jsonSchema: any): (((data: any, dataPath: any) => any) | undefined)[];

package/dist/types/format.d.ts

@@ -0,0 +1,21 @@
+export type FormatCompiler = import('./index.js').FormatCompiler;
+/** @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 declare function registerFormatCompiler(registered: Record<string, FormatCompiler>, name: string, formatCompiler: FormatCompiler): boolean;
+/**
+ * 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 declare function registerFormatCompilers(registered: Record<string, FormatCompiler>, formatCompilers: Record<string, FormatCompiler>): Record<string, FormatCompiler>;
+export declare function getSchemaFormatCompiler(registered: any, name: any): any;
+export declare function compileFormatBasic(schemaObj: any, jsonSchema: any): any;