@jarenjs/validate 0.8.4 → 0.34.0

package/dist/types/messages.d.ts

@@ -0,0 +1,142 @@
+export { compileMessageTemplate, compileMessageCatalog, } from '@jarenjs/core/message';
+/**
+ * The built-in English catalog: one entry per message key the validator
+ * produces, rendering the exact strings of the historical `#convertErrors`
+ * if/else chain. Keywords without an entry (`const`, `enum`,
+ * `dependentRequired`, ...) fall back to the generic
+ * `validation failed for keyword '<keyword>'` - as before.
+ * @type {Record<string, string | ((params: object, error?: object) => string)>}
+ */
+export declare const messagesEn: Record<string, string | ((params: object, error?: object) => string)>;
+/**
+ * JSON Schema Validation Error
+ * Represents a validation error according to the JSON Schema specification.
+ * @see https://json-schema.org/draft/2020-12/json-schema-core.html#output
+ */
+export declare class ValidationError {
+    keyword: string;
+    instancePath: string;
+    schemaPath: string;
+    params: object;
+    msgid: string;
+    message: string;
+    /**
+     * @param {object} options - Error options
+     * @param {string} options.keyword - The keyword that failed validation
+     * @param {string} options.instancePath - JSON Pointer to the data location
+     * @param {string} options.schemaPath - JSON Pointer to the schema location
+     * @param {object} options.params - Keyword-specific parameters
+     * @param {string} [options.msgid] - Stable message key resolving this error in a catalog
+     * @param {string} [options.message] - Human-readable error message
+     */
+    constructor(options: {
+        keyword: string;
+        instancePath: string;
+        schemaPath: string;
+        params: object;
+        msgid?: string;
+        message?: string;
+    });
+    /**
+     * Convert error to a plain object
+     * @returns {object} Plain object representation
+     */
+    toJSON(): object;
+}
+/**
+ * Render the message of an error through a catalog - the tail of the
+ * resolution precedence chain (no `errorMessage` registry involvement):
+ * catalog[msgid], built-in English[msgid], catalog[keyword],
+ * built-in English[keyword], then the generic fallback text.
+ * @param {ValidationError | {keyword: string, msgid?: string, params?: object}} error - The error to render
+ * @param {Readonly<Record<string, (params: object, error?: object) => string>>} [catalog] - A compiled catalog (see {@link compileMessageCatalog})
+ * @returns {string} The rendered message
+ */
+export declare function renderErrorMessage(error: ValidationError | {
+    keyword: string;
+    msgid?: string;
+    params?: object;
+}, catalog?: Readonly<Record<string, (params: object, error?: object) => string>>): string;
+/**
+ * Re-render the `message` of every error from its `msgid` + `params`
+ * through the given catalog, with built-in English fallback. This is the
+ * whole post-hoc i18n story:
+ * `localizeErrors(validate(data).errors, compileMessageCatalog(nl))`.
+ *
+ * Inline schema-authored messages (a MessageSpec without `$msgid`) are
+ * single-language by definition and are NOT re-rendered - that is why
+ * `$msgid` exists. An error whose `msgid` resolves in no catalog keeps
+ * its current message (e.g. the spec's inline fallback text).
+ * @param {ValidationError[]} errors - Errors from a collect-mode validation
+ * @param {Readonly<Record<string, (params: object, error?: object) => string>>} catalog - A compiled catalog (see {@link compileMessageCatalog})
+ * @returns {ValidationError[]} The same array, messages re-rendered
+ */
+export declare function localizeErrors(errors: ValidationError[], catalog: Readonly<Record<string, (params: object, error?: object) => string>>): ValidationError[];
+export type CompiledMessageSpec = {
+    /**
+     * - Catalog key to resolve at render time
+     */
+    msgid: string | null;
+    /**
+     * - Compiled inline template
+     */
+    render: ((params: object, error?: object) => string) | null;
+    /**
+     * - Author params, merged OVER the error's params
+     */
+    params: object | null;
+};
+export type CompiledErrorMessageNode = {
+    /**
+     * - String-form spec: covers this node AND its subtree
+     */
+    all: CompiledMessageSpec | null;
+    /**
+     * - Map-form per-keyword specs (this node only)
+     */
+    keywords: Map<string, CompiledMessageSpec | {
+        perKey: Map<string, CompiledMessageSpec>;
+        fallback: CompiledMessageSpec | null;
+    }> | null;
+    /**
+     * - The '_' entry (this node only)
+     */
+    catchAll: CompiledMessageSpec | null;
+};
+/**
+ * A compiled 'errorMessage' node registered on the ValidationRoot.
+ * @typedef {object} CompiledErrorMessageNode
+ * @property {CompiledMessageSpec|null} all - String-form spec: covers this node AND its subtree
+ * @property {Map<string, CompiledMessageSpec | {perKey: Map<string, CompiledMessageSpec>, fallback: CompiledMessageSpec|null}>|null} keywords - Map-form per-keyword specs (this node only)
+ * @property {CompiledMessageSpec|null} catchAll - The '_' entry (this node only)
+ */
+/**
+ * Compile the value of an 'errorMessage' keyword into a registry node.
+ * Grammar (validated here, at schema compile time):
+ * - MessageSpec (string / `$msgid` object): covers the whole subtree;
+ * - map form: per-keyword MessageSpecs for this node, where `required`
+ *   also accepts a per-missing-property map, `$query` a per-runtime-code
+ *   map (with `default` for the EBV-false failure), and `_` is the
+ *   node-level catch-all.
+ * @param {unknown} errorMessage - The keyword's value
+ * @param {string} path - The schema path, for compile error messages
+ * @returns {CompiledErrorMessageNode} The compiled node
+ */
+export declare function compileErrorMessageSpec(errorMessage: unknown, path: string): CompiledErrorMessageNode;
+/**
+ * Convert internal validation errors to the public ValidationError format.
+ * Params extraction is table-driven off the failed keyword; message text
+ * goes through the errorMessage registry (if any) and the built-in
+ * English catalog. With `options.messages === false` no message is
+ * rendered at all (`message: ''`, params and msgid still set).
+ * @param {Array<{object: any, key: string|string[], expected: any, dataKey: any, value: any, rest: any[]}>} internalErrors - The root's internal error records
+ * @returns {ValidationError[]} The public errors
+ */
+export declare function convertInternalErrors(internalErrors: Array<{
+    object: any;
+    key: string | string[];
+    expected: any;
+    dataKey: any;
+    value: any;
+    rest: any[];
+}>): ValidationError[];

package/dist/types/normalize.d.ts

@@ -0,0 +1,107 @@
+export type Normalizer<In = unknown, Out = In> = (data: In) => Out;
+export type NormalizeOptions = {
+    /**
+     * - Materialize `default` for absent object properties, recursively
+     */
+    useDefaults?: boolean | ((schemaNode: Record<string, unknown>) => boolean);
+    /**
+     * - Strip unknown properties: `true` only where `additionalProperties: false`, `'all'` wherever an object shape is declared
+     */
+    removeAdditional?: boolean | 'all';
+    /**
+     * - Convert a value to the node's declared scalar `type` when it is convertible
+     */
+    coerceTypes?: boolean | ((schemaNode: Record<string, unknown>) => boolean);
+    /**
+     * - Trim leading/trailing whitespace from strings, before coercion
+     */
+    trimStrings?: boolean | ((schemaNode: Record<string, unknown>) => boolean);
+};
+/**
+ * Collect the `$anchor` declarations of one schema document: a map from
+ * anchor name to the schema node that declares it. Exported because
+ * `@jarenjs/emit` resolves the same references when it derives types, and two
+ * walks with different scope rules would make a generated type disagree with
+ * this normalizer — the one defect class that package must not have.
+ *
+ * The scope is the same-document scope the rest of this module uses: a
+ * subtree that declares its own `$id` is an embedded resource with its own
+ * anchor scope, so it is not descended. First declaration wins, which keeps
+ * the map deterministic for a document that (invalidly) repeats a name.
+ * @param {object|boolean} root - The root schema of the document
+ * @returns {Map<string, object>} anchor name -> schema node
+ */
+export declare function collectSameDocumentAnchors(root: object | boolean): Map<string, object>;
+/**
+ * Resolve a same-document `$ref` — `#`, `#/` followed by a JSON Pointer, or
+ * `#name` for a plain `$anchor` — to the schema it addresses. Refs into other
+ * documents are not followed: a normalizer compiles one schema, and reaching
+ * a registered sibling would mean owning the whole resolution scope that
+ * `compile` owns. Exported for `@jarenjs/emit`, which must resolve references
+ * with exactly these rules when it derives the accepted/normalized variants.
+ * @param {string} ref - The reference
+ * @param {object|boolean} root - The root schema being compiled
+ * @param {Map<string, object>} [anchors] - The document's anchor map, from
+ *   {@link collectSameDocumentAnchors}; omit to skip anchor resolution
+ * @returns {object|boolean|undefined} The addressed schema, or undefined
+ */
+export declare function resolveSameDocumentRef(ref: string, root: object | boolean, anchors?: Map<string, object>): object | boolean | undefined;
+/**
+ * Resolve a per-node normalization switch at COMPILE time. Exported because
+ * `@jarenjs/emit` has to answer the same question when it derives the accepted
+ * and normalized type variants: two implementations of this rule would drift,
+ * and a type that disagrees with the normalizer is worse than no type. `true` turns the
+ * behavior on everywhere, `false` nowhere, and a predicate decides per schema
+ * node — which is how a consumer expresses "trim these 34 string fields, not
+ * the other 185" without the option becoming a whole-schema blunt instrument.
+ * Because it runs during compilation, a predicate costs nothing at runtime.
+ * @param {boolean|((node: Record<string, unknown>) => boolean)|undefined} option
+ * @param {object} node - The schema node the switch applies to
+ * @returns {boolean}
+ */
+export declare function resolveNormalizeSwitch(option: boolean | ((node: Record<string, unknown>) => boolean) | undefined, node: object): boolean;
+/**
+ * Compile a JSON Schema into a normalizer: a function that returns a
+ * normalized copy of its input, leaving the input untouched.
+ *
+ * Validation is unaffected and unchanged - normalize first, then hand the
+ * result to a compiled validator:
+ *
+ * ```javascript
+ * const normalize = compileNormalizer(schema, { useDefaults: true, trimStrings: true });
+ * const validate = new JarenValidator({ collectErrors: true }).compile(schema);
+ * const shaped = normalize(input);
+ * const result = validate(shaped);
+ * ```
+ *
+ * **What is normalized.** `properties`, `patternProperties`,
+ * `additionalProperties`, `items`/`prefixItems`/`additionalItems`, same-document
+ * `$ref` (`#`, `#/pointer` and plain `#anchor` forms), and `allOf` (composed,
+ * with stripping disabled inside it).
+ *
+ * **What is not, and why.** `anyOf`, `oneOf`, `if`/`then`/`else` and `not`
+ * are not descended: which branch applies is only known after validating,
+ * and normalizing under a branch can change which branch validates. Nothing
+ * arbitrary runs either - there is no transform hook, because an arbitrary
+ * transform is application code, not schema semantics, and belongs on the
+ * caller's side of the boundary.
+ * @template [In=unknown]
+ * @template [Out=In]
+ * @param {object|boolean} schema - The schema to compile
+ * @param {NormalizeOptions} [options] - Which normalizations to apply
+ * @returns {Normalizer<In, Out>} The compiled normalizer
+ * @example
+ * const normalize = compileNormalizer({
+ *   type: 'object',
+ *   properties: {
+ *     name: { type: 'string' },
+ *     port: { type: 'integer', default: 8080 },
+ *   },
+ *   additionalProperties: false,
+ * }, { useDefaults: true, removeAdditional: true, coerceTypes: true, trimStrings: true });
+ *
+ * const input = { name: '  jaren  ', port: '9000', stray: 1 };
+ * normalize(input);  // { name: 'jaren', port: 9000 }
+ * input;             // { name: '  jaren  ', port: '9000', stray: 1 } - untouched
+ */
+export declare function compileNormalizer<In = unknown, Out = In>(schema: object | boolean, options?: NormalizeOptions): Normalizer<In, Out>;

package/dist/types/number.d.ts

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

package/dist/types/object.d.ts

@@ -0,0 +1,3 @@
+export declare function compileObjectPrimitives(schemaObj: any, jsonSchema: any): ((data: any, dataPath: any, dataRoot: any, dataKeys: any) => any) | undefined;
+export declare function compileObjectChildren(schemaObj: any, jsonSchema: any): ((data: any, dataPath: any, dataRoot: any, dataKeys: any) => boolean) | undefined;
+export declare function compileObjectSchema(schemaObj: any, jsonSchema: any): ((data: any, dataPath: any, dataRoot: any) => any) | undefined;

package/dist/types/query-keyword.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare function compileQuerySchema(schemaObj: object, jsonSchema: object): Function | undefined;

package/dist/types/query.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 declare function createTypeTestCompiler(validator?: object | (() => object)): (schemaJson: any, docPath: string) => ((value: any) => boolean);

package/dist/types/schema.d.ts

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

package/dist/types/string.d.ts

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

package/dist/types/tools.d.ts

@@ -0,0 +1,109 @@
+import { isBooleanType } from '@jarenjs/core';
+import { isRegExpType } from '@jarenjs/core/string';
+export declare function isBoolOrObjectClass(obj: any): boolean;
+/**
+ * getBoolOrObjectClass
+ * extract the data of first parameter if data is boolean or object type otherwise return default
+ * @param {any} obj any data data has to be tested on boolean or object type
+ * @param {boolean | object | undefined} def default return type if not boolean or object type
+ * @returns {boolean | undefined} return value when boolean or object otherwise def
+ */
+export declare function getBoolOrObjectClass(obj: any, def?: boolean | object | undefined): boolean | undefined;
+export declare function getArrayClassMinItems(obj: any, len?: number, def?: undefined): any;
+export declare function isOfSchemaType(schema: any, type: any): boolean;
+export declare function hasSchemaRef(schema: any): boolean;
+export declare function hasSchemaRecursiveRef(schema: any): boolean;
+export declare function hasSchemaDynamicRef(schema: any): boolean;
+/**
+ * Whether a sibling keyword of unevaluatedProperties already evaluates every
+ * property of the instance. additionalProperties (boolean or schema) applies
+ * to each property not matched by properties/patternProperties, so once it
+ * has passed no property is left unevaluated.
+ * @param {object} schema - The schema holding the unevaluatedProperties keyword
+ * @returns {boolean} True when the unevaluatedProperties check can never match
+ */
+export declare function hasUnevaluatedPropertiesCoverage(schema: object): boolean;
+/**
+ * Whether a sibling keyword of unevaluatedItems already evaluates every item
+ * of the instance: a uniform items schema (boolean or object) covers all
+ * items beyond any prefixItems, and a tuple-form items with additionalItems
+ * covers the items beyond the tuple.
+ * @param {object} schema - The schema holding the unevaluatedItems keyword
+ * @returns {boolean} True when the unevaluatedItems check can never match
+ */
+export declare function hasUnevaluatedItemsCoverage(schema: object): boolean;
+export declare function createIsSchemaTypeHandler(type: any, isStrict?: boolean): typeof isBooleanType | typeof isRegExpType | undefined;
+/**
+ * The fallback resolver of the data-reference keywords (`data`, `$data`):
+ * a ref that fails the strict compile keeps the lax keyword semantics, so
+ * it resolves as not-found and the keyword asserts nothing.
+ * @returns {any} the JSON Pointer not-found sentinel
+ */
+export declare const resolveNothing: () => any;
+/**
+ * Build the keyword validators the two data-reference keywords share
+ * verbatim. The `data` keyword (json-everything, absolute + relative
+ * pointers via `compileDataRef`) and the Ajv-style `$data` keyword
+ * (relative pointers only) differ ONLY in which pointer compiler
+ * resolves a ref, so each module passes its own `compileRefResolver`
+ * and gets the same fifteen compilers back.
+ *
+ * Every validator follows one lax contract: a data instance outside the
+ * keyword's type, an unresolvable ref, or a resolved constraint of the
+ * wrong type asserts nothing.
+ *
+ * @param {(ref: string) => (dataRoot: any, dataPath: string) => any} compileRefResolver
+ * @returns {Record<string, (schemaObj: object, ref: string) => ((data: any, dataPath: string, dataRoot: any) => boolean) | undefined>}
+ */
+export declare function createDataRefCompilers(compileRefResolver: (ref: string) => (dataRoot: any, dataPath: string) => any): Record<string, (schemaObj: object, ref: string) => ((data: any, dataPath: string, dataRoot: any) => boolean) | undefined>;
+/**
+ * Records which properties (string keys) and items (numeric indexes) of a
+ * data instance were successfully evaluated during validation, so that
+ * unevaluatedProperties/unevaluatedItems can be checked afterwards.
+ *
+ * Entries are (data reference, key) pairs appended in application order.
+ * Applicators that discard annotations (failed anyOf/oneOf branches, not,
+ * failed if) take a mark() before running and rollback(mark) afterwards.
+ * The numeric key -1 means "all items of this array were evaluated".
+ */
+export declare class EvalLog {
+    #private;
+    /** Clears the log; called at the start of each root validation. */
+    reset(): void;
+    /** @returns {number} The current log position */
+    mark(): number;
+    /** Discards all entries recorded after the given mark. */
+    rollback(mark: any): void;
+    /** Records that `key` of instance `data` was evaluated. */
+    add(data: any, key: any): void;
+    /** @returns {boolean} True when property `key` of `data` was evaluated at or after `from` */
+    hasKey(data: any, key: any, from: any): boolean;
+    /** @returns {boolean} True when item `index` of `data` was evaluated at or after `from` (-1 entries cover all items) */
+    hasItem(data: any, index: any, from: any): boolean;
+}
+/**
+ * Combine INDEPENDENT keyword validators without short-circuiting.
+ *
+ * `a(...) && b(...)` is the right composition in boolean mode: the answer is
+ * known at the first failure and nothing is gained by continuing. When errors
+ * are recorded it is wrong, because each validator is the only thing that can
+ * report its own fault, so the first failure hides every sibling's. This runs
+ * all of them and ANDs the results — the boolean answer is identical, the
+ * error list is complete.
+ *
+ * Only use it where the validators genuinely are independent. A precondition
+ * (a type guard before a length check) must keep its short-circuit: running
+ * past it is meaningless at best and throws at worst.
+ * @param {Function[]} validators - Independent validators, in report order
+ * @returns {Function} A validator that runs every one of them
+ */
+export declare function combineIndependent(validators: Function[]): Function;
+export declare class ValidationResult {
+    match: boolean;
+    errors: number;
+    static undefThat(): ValidationResult;
+    constructor(match?: boolean, errors?: number);
+    addValid(valid?: boolean): this;
+    addMatch(valid?: boolean): this;
+    addResult(result?: ValidationResult): this;
+}

package/dist/types/traverse.d.ts

@@ -0,0 +1,32 @@
+export declare function encodeJsonPointerPath(path: any, key: any, index: any): string;
+export declare function decodeJsonPointerPath(path: any): any;
+declare class JsonPointerOptions {
+    anchorsGlobal: boolean;
+    anchorsAllowed: boolean;
+    skipErrors: boolean;
+    constructor(anchorsGlobal?: boolean, anchorsAllowed?: boolean, skipErrors?: boolean);
+}
+declare class JsonPointer {
+    id: any;
+    search: any;
+    leftUri: any;
+    fragment: any;
+    constructor(id: any, search: any, leftUri: any, fragment: any);
+}
+export declare function createJsonPointer(refUri: any, baseUri: any, opts?: JsonPointerOptions): JsonPointer;
+export declare function storeSchemaIdsInMap(schemas: any, baseUri: any, schema: any, opts?: JsonPointerOptions): any;
+export declare function resolveRefSchemaShallow(schemas: any, refUri: any, baseUri: any, opts?: JsonPointerOptions): {
+    id: any;
+    schema: any;
+};
+export declare function restoreSchemaRefsInMap(schemas: any, opts?: JsonPointerOptions): void;
+export declare class TraverseOptions extends JsonPointerOptions {
+    origin: string;
+    mergeSchemas: boolean;
+    constructor(origin?: string, mergeSchemas?: boolean, anchorsGlobal?: boolean, anchorsAllowed?: boolean, skipErrors?: boolean);
+}
+export declare function resolveRefSchemaDeep(schemas: any, baseUri: any, refschema: any, opts?: TraverseOptions): {
+    id: any;
+    schema: any;
+};
+export {};

package/dist/types/unevaluated.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Wraps a compiled schema validator so unevaluatedProperties/unevaluatedItems
+ * run last, seeing every annotation produced on this instance by the schema's
+ * own keywords and its in-place applicators (allOf/anyOf/oneOf/if/$ref/...).
+ * Returns the validator unchanged when evaluation tracking is off or the
+ * schema has no unevaluated* keywords.
+ * @param {import('./index.js').ValidationObject} schemaObj
+ * @param {object} jsonSchema
+ * @param {function} validator - The compiled validator for all other keywords
+ * @returns {function} The wrapped (or original) validator
+ */
+export declare function wrapUnevaluated(schemaObj: import('./index.js').ValidationObject, jsonSchema: object, validator: Function): Function;