@jarenjs/validate 0.9.2 → 0.34.0

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

@@ -8,13 +8,4 @@
  * @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/index.d.ts

@@ -1,6 +1,7 @@
 import { TraverseOptions } from './traverse.js';
 import { EvalLog } from './tools.js';
 export { registerFormatCompilers } from './format.js';
+export { ValidationError, messagesEn, compileMessageTemplate, compileMessageCatalog, renderErrorMessage, localizeErrors, } from './messages.js';
 export { TraverseOptions };
 export type DollarDataRef = {
     /**
@@ -472,38 +473,6 @@ declare class InternalValidationError {
     rest: any;
     constructor(obj: any, key: any, expected: any, dataKey: any, value: any, rest: any);
 }
-/**
- * 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;
-    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.message] - Human-readable error message
-     */
-    constructor(options: {
-        keyword: string;
-        instancePath: string;
-        schemaPath: string;
-        params: object;
-        message?: string;
-    });
-    /**
-     * Convert error to a plain object
-     * @returns {object} Plain object representation
-     */
-    toJSON(): object;
-}
 /**
  * ValidationOptions configures the behavior of the validation process.
  * @class
@@ -523,6 +492,10 @@ export declare class ValidationOptions {
     vocabValidation: boolean;
     /** @type {boolean|null} Whether the format keyword asserts (null = auto by draft) */
     formatAssertion: boolean | null;
+    /** @type {boolean} Whether collected errors carry rendered message text */
+    messages: boolean;
+    /** @type {'error'|'ignore'} What an asserting `format` with no registered compiler does */
+    unknownFormats: 'error' | 'ignore';
     /**
      * Creates validation options.
      * @param {boolean} [skipErrors=true] - Whether to stop at first error or continue
@@ -532,8 +505,10 @@ export declare class ValidationOptions {
      * @param {number} [draftVersion=7] - The JSON Schema draft version (6, 7, 2019, or 2020)
      * @param {boolean} [vocabValidation=true] - Whether the validation vocabulary is enabled (false when the schema's metaschema omits it via $vocabulary)
      * @param {boolean|null} [formatAssertion=null] - Whether format asserts (null = auto: asserts below draft 2020-12, annotation-only from 2020-12 on)
+     * @param {boolean} [messages=true] - Whether collected errors carry rendered message text; false skips rendering (message: '', params/msgid still set)
+     * @param {'error'|'ignore'} [unknownFormats='ignore'] - What to do when an ASSERTING `format` names something no compiler is registered for: 'ignore' (the default, and what the specification requires) accepts it as an annotation; 'error' throws at COMPILE time. Never affects instance validation, and never applies where format is annotation-only anyway.
      */
-    constructor(skipErrors?: boolean, useGrapheme?: boolean, collectErrors?: boolean, contentValidation?: boolean | null, draftVersion?: number, vocabValidation?: boolean, formatAssertion?: boolean | null);
+    constructor(skipErrors?: boolean, useGrapheme?: boolean, collectErrors?: boolean, contentValidation?: boolean | null, draftVersion?: number, vocabValidation?: boolean, formatAssertion?: boolean | null, messages?: boolean, unknownFormats?: 'error' | 'ignore');
 }
 /**
  * ValidationRoot manages the compilation and validation context for a schema.
@@ -554,8 +529,6 @@ export declare class ValidationRoot {
      *   `$ref`s resolve to the owner's `addSchema` registrations
      */
     constructor(origin: string, schemas: Map<any, any>, formats: Record<string, FormatCompiler>, opts?: ValidationOptions, traverse?: TraverseOptions, owner?: object | null);
-    /** @returns {string} The root schema origin/URI */
-    get rootOrigin(): string;
     /** @returns {TraverseOptions} Schema traversal options */
     get traverse(): TraverseOptions;
     /** @returns {ValidationOptions} Validation options */
@@ -564,8 +537,6 @@ export declare class ValidationRoot {
     get formats(): object;
     /** @returns {Array} Array of validation errors */
     get errors(): any[];
-    /** @returns {ValidationObject} The root schema's ValidationObject */
-    get firstSchema(): ValidationObject;
     /** @returns {boolean} Whether any schema in this compilation contains a $data reference */
     get usesDollarData(): boolean;
     /** @returns {boolean} Whether any schema in this compilation contains unevaluatedProperties/unevaluatedItems */
@@ -574,6 +545,16 @@ export declare class ValidationRoot {
     get evalLog(): EvalLog;
     /** @returns {object|null} The owning JarenValidator instance, or null when constructed standalone */
     get owner(): object | null;
+    /** @returns {Map<string, object>|null} Compiled 'errorMessage' specs by schema path, or null when the schema set has none */
+    get errorMessages(): Map<string, object> | null;
+    /**
+     * Register a compiled 'errorMessage' spec for a schema location.
+     * Called at schema compile time (see compileSchemaObject); the registry
+     * is only consulted at report time, over the already-failed set.
+     * @param {string} path - The schema path (ValidationObject.path)
+     * @param {object} spec - The compiled spec (see messages.js compileErrorMessageSpec)
+     */
+    registerErrorMessage(path: string, spec: object): void;
     /**
      * Creates a new ValidationObject for the given path and schema.
      * @param {string} path - The URI path for this schema object
@@ -588,18 +569,6 @@ export declare class ValidationRoot {
      * @returns {ValidationObject|null|undefined} The existing object, null if marked unresolved, or undefined if not known
      */
     unresolvedObject(path: string): ValidationObject | null | undefined;
-    /**
-     * Gets the raw schema object for a given reference without compiling it.
-     * Used to check schema properties (like $recursiveAnchor) at compile time.
-     * @param {string} ref - The reference URI to resolve
-     * @param {string} path - The current path (for error messages)
-     * @param {object} schema - The schema containing the $ref
-     * @returns {{id: string, schema: object}|null} The resolved schema info or null
-     */
-    getRawSchema(ref: string, path: string, schema: object): {
-        id: string;
-        schema: object;
-    } | null;
     /**
      * Gets the raw schema object by its URI/ID directly from the schemas map.
      * This performs a direct lookup without following references.
@@ -621,12 +590,41 @@ export declare class ValidationRoot {
      * @returns {boolean} Always returns false for convenience in validators
      */
     addError(error: InternalValidationError): boolean;
+    /**
+     * A checkpoint in the collected-error list.
+     *
+     * A SPECULATIVE applicator - an `anyOf` branch, an `if` condition, the
+     * subschema of a `not`, a `contains` candidate - runs a validator whose
+     * failure may be entirely expected. Those failures still call `addError`,
+     * so without a checkpoint they leak into the caller's issue list and blame
+     * a document for not matching a branch it was never required to match.
+     * Marking before the probe and rolling back after is the same discipline
+     * `EvalLog` already uses for annotations.
+     * @returns {number} The mark to pass to {@link rollbackErrors}
+     */
+    errorMark(): number;
+    /**
+     * Discard every error collected since `mark`.
+     * @param {number} mark - A value from {@link errorMark}
+     */
+    rollbackErrors(mark: number): void;
     /**
      * Validates data against the root schema.
      * @param {unknown} data - The data to validate
      * @returns {boolean} True if valid, false otherwise
      */
     validate(data: unknown): boolean;
+    /**
+     * Returns the fastest repeated-validation entry point for this root.
+     * Error collection and root-level dynamic anchors need the per-call
+     * bookkeeping of validate(); without them the compiled root validator
+     * only needs the annotation log cleared (when tracking is on) and can
+     * otherwise be invoked directly. Dynamic anchors pushed during
+     * validation are balanced by try/finally, so the anchor map needs no
+     * per-call clearing here.
+     * @returns {(data: unknown) => boolean} The validation entry point
+     */
+    createValidateFn(): (data: unknown) => boolean;
     /**
      * Get the stored validator for a dynamic anchor.
      * Used by $dynamicRef for runtime resolution.
@@ -702,8 +700,6 @@ export declare class ValidationObject {
     get path(): string;
     /** @returns {string} The effective base URI for resolving relative $refs */
     get baseUri(): string;
-    /** @returns {Array} The current validation errors from the root */
-    get errors(): any[];
     /** @returns {function} The compiled validator function */
     get validate(): Function;
     /** @returns {ValidationOptions} The validation options */
@@ -765,9 +761,103 @@ export declare class ValidatorOptions {
      */
     constructor(formats?: object | object[], schemas?: object[], validation?: ValidationOptions, traverse?: TraverseOptions);
 }
+export type ValidationResultObject = {
+    valid: boolean;
+    errors: import("./messages.js").ValidationError[];
+};
+export type CompiledPredicate<T> = (data: unknown) => data is T;
+export type CompiledCollector = (data: unknown) => ValidationResultObject;
+export type ValidatorInit<TCollect extends boolean = false> = {
+    /**
+     * - Format compilers to register
+     */
+    formats?: Record<string, FormatCompiler>;
+    /**
+     * - Schemas to register
+     */
+    schemas?: (JSONSchema | boolean)[];
+    /**
+     * - Validation behavior options
+     */
+    validation?: ValidationOptions;
+    /**
+     * - Schema traversal options
+     */
+    traverse?: TraverseOptions;
+    /**
+     * - Return `{ valid, errors }` instead of a boolean
+     */
+    collectErrors?: TCollect;
+    /**
+     * - Stop at the first failure (defaults to `!collectErrors`)
+     */
+    skipErrors?: boolean;
+    /**
+     * - Count grapheme clusters for string length
+     */
+    useGrapheme?: boolean;
+    /**
+     * - Assert contentEncoding/contentMediaType
+     */
+    contentValidation?: boolean;
+    /**
+     * - The JSON Schema draft version
+     */
+    draftVersion?: number;
+    /**
+     * - Assert the format keyword
+     */
+    formatAssertion?: boolean;
+    /**
+     * - Render English message text on collected errors
+     */
+    messages?: boolean;
+    /**
+     * - What an ASSERTING `format` with no registered compiler does: 'ignore' (default, per spec) accepts it as an annotation, 'error' throws at compile time
+     */
+    unknownFormats?: 'error' | 'ignore';
+};
+/**
+ * The object a compiled validator returns when `collectErrors` is enabled.
+ * @typedef {{ valid: boolean, errors: import("./messages.js").ValidationError[] }} ValidationResultObject
+ */
+/**
+ * A compiled validator in the default boolean mode. It is a type guard, so
+ * `T` is whatever the caller asserts the schema describes; with no `T` it
+ * behaves as an ordinary boolean predicate.
+ * @template T
+ * @typedef {(data: unknown) => data is T} CompiledPredicate
+ */
+/**
+ * A compiled validator in collect-errors mode.
+ * @typedef {(data: unknown) => ValidationResultObject} CompiledCollector
+ */
+/**
+ * The plain-object form accepted by the JarenValidator constructor, mixing
+ * validator-level settings with the ValidationOptions fields.
+ * @template {boolean} [TCollect=false]
+ * @typedef {object} ValidatorInit
+ * @property {Record<string, FormatCompiler>} [formats] - Format compilers to register
+ * @property {(JSONSchema | boolean)[]} [schemas] - Schemas to register
+ * @property {ValidationOptions} [validation] - Validation behavior options
+ * @property {TraverseOptions} [traverse] - Schema traversal options
+ * @property {TCollect} [collectErrors] - Return `{ valid, errors }` instead of a boolean
+ * @property {boolean} [skipErrors] - Stop at the first failure (defaults to `!collectErrors`)
+ * @property {boolean} [useGrapheme] - Count grapheme clusters for string length
+ * @property {boolean} [contentValidation] - Assert contentEncoding/contentMediaType
+ * @property {number} [draftVersion] - The JSON Schema draft version
+ * @property {boolean} [formatAssertion] - Assert the format keyword
+ * @property {boolean} [messages] - Render English message text on collected errors
+ * @property {'error'|'ignore'} [unknownFormats] - What an ASSERTING `format` with no registered compiler does: 'ignore' (default, per spec) accepts it as an annotation, 'error' throws at compile time
+ */
 /**
  * JarenValidator is the main entry point for JSON Schema validation.
  * It manages schema registration, format registration, and compilation.
+ *
+ * The `collectErrors` option decides what a compiled validator returns, and
+ * it is carried in the type parameter so the two shapes never have to be
+ * distinguished at runtime.
+ * @template {boolean} [TCollect=false]
  * @class
  * @example
  * const validator = new JarenValidator();
@@ -775,37 +865,37 @@ export declare class ValidatorOptions {
  * const validate = validator.compile({ $ref: 'http://example.com/schema' });
  * const valid = validate({ foo: 'bar' }); // true
  */
-export declare class JarenValidator {
+export declare class JarenValidator<TCollect extends boolean = false> {
     #private;
     /**
      * Creates a new JarenValidator instance.
-     * @param {ValidatorOptions} [options] - Validator options including formats, schemas, validation options, and traverse options
+     * @param {ValidatorOptions | ValidatorInit<TCollect>} [options] - Validator options including formats, schemas, validation options, and traverse options
      */
-    constructor(options?: ValidatorOptions);
+    constructor(options?: ValidatorOptions | ValidatorInit<TCollect>);
     /**
      * Adds a format validator.
      * @param {string} name - The format name (e.g., 'email', 'uri', 'date-time')
      * @param {FormatCompiler} formatCompiler - A function that compiles format validators
-     * @returns {JarenValidator} This validator instance for chaining
+     * @returns {this} This validator instance for chaining (the polymorphic `this` keeps the collectErrors type parameter across a chain)
      * @example
      * validator.addFormat('custom', (schemaObj, schema) => {
      *   return (data) => data.startsWith('custom:');
      * });
      */
-    addFormat(name: string, formatCompiler: FormatCompiler): JarenValidator;
+    addFormat(name: string, formatCompiler: FormatCompiler): this;
     /**
      * Adds multiple format validators at once.
      * @param {Record<string, FormatCompiler>} formatCompilers - Object mapping format names to compiler functions
-     * @returns {JarenValidator} This validator instance for chaining
+     * @returns {this} This validator instance for chaining (the polymorphic `this` keeps the collectErrors type parameter across a chain)
      */
-    addFormats(formatCompilers: Record<string, FormatCompiler>): JarenValidator;
+    addFormats(formatCompilers: Record<string, FormatCompiler>): this;
     /**
      * Adds schema(s) to the validator instance.
      * This method does not compile schemas - it only registers them for reference.
      * Dependencies can be added in any order, and circular dependencies are supported.
      * @param {JSONSchema | boolean | (JSONSchema | boolean)[]} schema - The schema(s) to add
      * @param {string} [key] - Optional key/URI to register the schema under
-     * @returns {JarenValidator} This validator instance for chaining
+     * @returns {this} This validator instance for chaining (the polymorphic `this` keeps the collectErrors type parameter across a chain)
      * @example
      * // Add a single schema
      * validator.addSchema({ $id: 'http://example.com/user', type: 'object' });
@@ -816,18 +906,18 @@ export declare class JarenValidator {
      * // Add with explicit key
      * validator.addSchema({ type: 'string' }, 'http://example.com/name');
      */
-    addSchema(schema: JSONSchema | boolean | (JSONSchema | boolean)[], key?: string): JarenValidator;
+    addSchema(schema: JSONSchema | boolean | (JSONSchema | boolean)[], key?: string): this;
     static normalizeUriKey(key: any): any;
     /**
      * Adds meta-schema(s) that can be used to validate schemas.
      * Meta-schemas are schemas that describe the structure of valid JSON schemas.
      * @param {JSONSchema | boolean | (JSONSchema | boolean)[]} schema - The meta-schema(s) to add
      * @param {string} [key] - Optional key/URI for the meta-schema
-     * @returns {JarenValidator} This validator instance for chaining
+     * @returns {this} This validator instance for chaining (the polymorphic `this` keeps the collectErrors type parameter across a chain)
      * @example
      * validator.addMetaSchema(draft7MetaSchema, 'http://json-schema.org/draft-07/schema');
      */
-    addMetaSchema(schema: JSONSchema | boolean | (JSONSchema | boolean)[], key?: string): JarenValidator;
+    addMetaSchema(schema: JSONSchema | boolean | (JSONSchema | boolean)[], key?: string): this;
     /**
      * Retrieves a registered schema by its key/URI.
      * @param {string} key - The schema URI/key
@@ -848,9 +938,16 @@ export declare class JarenValidator {
      * Compiles a schema into a validation function.
      * This is the main method for creating validators. It resolves all $ref references,
      * compiles the schema structure, and returns a function that validates data.
+     * The return type follows the instance's `collectErrors` setting: a type
+     * guard over `unknown` by default, or a function producing
+     * `{ valid, errors }` when errors are collected. Jaren does not infer `T`
+     * from the schema — the caller asserts what the schema describes, which is
+     * what a checked contract wrapper wants; pair it with a schema-to-type
+     * generator if you need the shape derived mechanically.
+     * @template [T=unknown]
      * @param {JSONSchema | boolean} schema - The schema to compile
      * @param {(JSONSchema | boolean)[]} [schemas] - Additional schemas to reference during compilation
-     * @returns {(data: any) => boolean | {valid: boolean, errors: ValidationError[]}} A validation function
+     * @returns {TCollect extends true ? CompiledCollector : CompiledPredicate<T>} A validation function
      * @example
      * const validate = validator.compile({
      *   type: 'object',
@@ -862,13 +959,14 @@ export declare class JarenValidator {
      * const valid = validate({ name: 'John' }); // true
      * const invalid = validate({ name: 123 }); // false
      *
+     * // Narrowing to a caller-asserted type
+     * const isUser = validator.compile<{ name: string }>(userSchema);
+     * if (isUser(input)) input.name; // input is { name: string } here
+     *
      * // With error collection
-     * validator = new JarenValidator({ collectErrors: true });
-     * const result = validate({ name: 123 });
+     * const collecting = new JarenValidator({ collectErrors: true });
+     * const result = collecting.compile(schema)({ name: 123 });
      * // result = { valid: false, errors: [...] }
      */
-    compile(schema: JSONSchema | boolean, schemas?: (JSONSchema | boolean)[]): (data: any) => boolean | {
-        valid: boolean;
-        errors: ValidationError[];
-    };
+    compile<T = unknown>(schema: JSONSchema | boolean, schemas?: (JSONSchema | boolean)[]): TCollect extends true ? CompiledCollector : CompiledPredicate<T>;
 }

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>;