@lakutata/core 1.0.60 → 3.0.0-beta.0

package/dist/esm/lib/validation/engine/schema/validator.js

@@ -0,0 +1,638 @@
+/**
+ * Derived from the upstream lib/validator.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+import { clone, ignore, reach } from '../utils/index.js';
+import { assert, setMessage } from './assert.js';
+import * as Common from './common.js';
+import * as Errors from './errors.js';
+import { State } from './state.js';
+import { compiledFor, FALLBACK, INVALID, sameResult } from './fastpath.js';
+/**
+ * Validation-wide state shared by all the states of one validation
+ */
+export class Mainstay {
+    constructor(tracer, debug, links) {
+        this.externals = [];
+        this.warnings = [];
+        this.tracer = tracer;
+        this.debug = debug;
+        this.links = links;
+        this.shadow = null;
+        this.artifacts = null;
+        this._snapshots = [];
+    }
+    snapshot() {
+        this._snapshots.push({
+            externals: this.externals.slice(),
+            warnings: this.warnings.slice()
+        });
+    }
+    restore() {
+        const snapshot = this._snapshots.pop();
+        this.externals = snapshot.externals;
+        this.warnings = snapshot.warnings;
+    }
+    commit() {
+        this._snapshots.pop();
+    }
+}
+/**
+ * Validate a value (synchronously)
+ * @param value
+ * @param schema
+ * @param prefs
+ */
+export function entry(value, schema, prefs) {
+    let settings = Common.defaults;
+    if (prefs) {
+        assert(prefs.warnings === undefined, 'Cannot override warnings preference in synchronous validation');
+        assert(prefs.artifacts === undefined, 'Cannot override artifacts preference in synchronous validation');
+        settings = entrySettings(prefs);
+    }
+    const fast = fastPath(value, schema, settings);
+    if (fast !== FALLBACK && fast !== INVALID && fastPathMode === 'on')
+        return { value: fast };
+    const result = validateEntry(value, schema, settings);
+    if (fastPathMode === 'verify')
+        verifyFastPath(value, fast, result);
+    assert(!result.mainstay.externals.length, 'Schema with external rules must use validateAsync()');
+    const outcome = { value: result.value };
+    if (result.error)
+        outcome.error = result.error;
+    if (result.mainstay.warnings.length)
+        outcome.warning = Errors.details(result.mainstay.warnings);
+    if (result.mainstay.debug)
+        outcome.debug = result.mainstay.debug;
+    if (result.mainstay.artifacts)
+        outcome.artifacts = result.mainstay.artifacts;
+    return outcome;
+}
+/**
+ * Validate a value, running the external rules; throws the validation error
+ * @param value
+ * @param schema
+ * @param prefs
+ */
+export async function entryAsync(value, schema, prefs) {
+    let settings = Common.defaults;
+    if (prefs)
+        settings = entrySettings(prefs);
+    const fast = fastPath(value, schema, settings);
+    if (fast !== FALLBACK && fast !== INVALID && fastPathMode === 'on') {
+        if (!settings.warnings && !settings.debug && !settings.artifacts)
+            return fast;
+        return { value: fast };
+    }
+    const result = validateEntry(value, schema, settings);
+    if (fastPathMode === 'verify')
+        verifyFastPath(value, fast, result);
+    const mainstay = result.mainstay;
+    if (result.error) {
+        if (mainstay.debug)
+            result.error.debug = mainstay.debug;
+        throw result.error;
+    }
+    if (mainstay.externals.length) {
+        let root = result.value;
+        const errors = [];
+        for (const external of mainstay.externals) {
+            const path = external.state.path;
+            const linked = external.schema.type === 'link' ? mainstay.links.get(external.schema) : null;
+            let node = root;
+            let key;
+            let parent;
+            const ancestors = path.length ? [root] : [];
+            const original = path.length ? reach(value, path) : value;
+            if (path.length) {
+                key = path[path.length - 1];
+                let current = root;
+                for (const segment of path.slice(0, -1)) {
+                    current = current[segment];
+                    ancestors.unshift(current);
+                }
+                parent = ancestors[0];
+                node = parent[key];
+            }
+            try {
+                const createError = (code, local) => (linked || external.schema).$_createError(code, node, local, external.state, settings);
+                const output = await external.method(node, {
+                    schema: external.schema,
+                    linked,
+                    state: external.state,
+                    prefs,
+                    original,
+                    error: createError,
+                    errorsArray,
+                    warn: (code, local) => {
+                        mainstay.warnings.push((linked || external.schema).$_createError(code, node, local, external.state, settings));
+                    },
+                    message: (messages, local) => (linked || external.schema).$_createError('external', node, local, external.state, settings, { messages })
+                });
+                if (output === undefined || output === node)
+                    continue;
+                if (output instanceof Errors.Report) {
+                    mainstay.tracer.log(external.schema, external.state, 'rule', 'external', 'error');
+                    errors.push(output);
+                    if (settings.abortEarly)
+                        break;
+                    continue;
+                }
+                if (Array.isArray(output) && output[Common.symbols.errors]) {
+                    mainstay.tracer.log(external.schema, external.state, 'rule', 'external', 'error');
+                    errors.push(...output);
+                    if (settings.abortEarly)
+                        break;
+                    continue;
+                }
+                if (parent) {
+                    mainstay.tracer.value(external.state, 'rule', node, output, 'external');
+                    parent[key] = output;
+                }
+                else {
+                    mainstay.tracer.value(external.state, 'rule', root, output, 'external');
+                    root = output;
+                }
+            }
+            catch (err) {
+                //Change message to include path
+                if (settings.errors.label)
+                    setMessage(err, `${err.message} (${(external.label)})`);
+                throw err;
+            }
+        }
+        result.value = root;
+        if (errors.length) {
+            result.error = Errors.process(errors, value, settings);
+            if (mainstay.debug)
+                result.error.debug = mainstay.debug;
+            throw result.error;
+        }
+    }
+    if (!settings.warnings && !settings.debug && !settings.artifacts)
+        return result.value;
+    const outcome = { value: result.value };
+    if (mainstay.warnings.length)
+        outcome.warning = Errors.details(mainstay.warnings);
+    if (mainstay.debug)
+        outcome.debug = mainstay.debug;
+    if (mainstay.artifacts)
+        outcome.artifacts = mainstay.artifacts;
+    return outcome;
+}
+/**
+ * Validate a value, asynchronously when the schema is asynchronous (Standard Schema)
+ * @param value
+ * @param schema
+ */
+export function standard(value, schema) {
+    if (schema.isAsync())
+        return entryAsync(value, schema);
+    return entry(value, schema);
+}
+function validateEntry(value, schema, prefs) {
+    //Prepare state
+    const { tracer, cleanup } = tracerOf(schema, prefs);
+    const debug = prefs.debug ? [] : null;
+    const links = schema._ids._schemaChain ? new Map() : null;
+    const mainstay = new Mainstay(tracer, debug, links);
+    const schemas = schema._ids._schemaChain ? [{ schema }] : null;
+    const state = new State([], [], { mainstay, schemas });
+    //Validate value
+    const result = validate(value, schema, state, prefs);
+    //Process value and errors
+    if (cleanup)
+        schema.$_root.untrace();
+    const error = Errors.process(result.errors, value, prefs);
+    return { value: result.value, error, mainstay };
+}
+function tracerOf(schema, prefs) {
+    if (schema.$_root._tracer)
+        return { tracer: schema.$_root._tracer._register(schema) };
+    if (prefs.debug) {
+        assert(schema.$_root.trace, 'Debug mode not supported');
+        return { tracer: schema.$_root.trace()._register(schema), cleanup: true };
+    }
+    return { tracer: ignoreTracer };
+}
+/**
+ * Validate a value against a schema, in the state of a validation
+ * @param value
+ * @param schema
+ * @param state
+ * @param prefs
+ * @param overrides
+ */
+export function validate(value, schema, state, prefs, overrides = {}) {
+    if (schema.$_terms.whens)
+        schema = schema._generate(value, state, prefs).schema;
+    //Setup state and settings
+    if (schema._preferences)
+        prefs = prefsOf(schema, prefs);
+    //Cache
+    if (schema._cache && prefs.cache) {
+        const result = schema._cache.get(value);
+        state.mainstay.tracer.debug(state, 'validate', 'cached', !!result);
+        if (result)
+            return result;
+    }
+    //Helpers
+    const createError = (code, local, localState) => schema.$_createError(code, value, local, localState || state, prefs);
+    const helpers = {
+        original: value,
+        prefs,
+        schema,
+        state,
+        error: createError,
+        errorsArray,
+        warn: (code, local, localState) => {
+            state.mainstay.warnings.push(createError(code, local, localState));
+        },
+        message: (messages, local) => schema.$_createError('custom', value, local, state, prefs, { messages })
+    };
+    //Prepare
+    state.mainstay.tracer.entry(schema, state);
+    const def = schema._definition;
+    if (def.prepare && value !== undefined && prefs.convert) {
+        const prepared = def.prepare(value, helpers);
+        if (prepared) {
+            state.mainstay.tracer.value(state, 'prepare', value, prepared.value);
+            //Prepare error always aborts early
+            if (prepared.errors)
+                return finalize(prepared.value, [].concat(prepared.errors), helpers);
+            value = prepared.value;
+        }
+    }
+    //Type coercion
+    if (def.coerce && value !== undefined && prefs.convert && (!def.coerce.from || def.coerce.from.includes(typeof value))) {
+        const coerced = def.coerce.method(value, helpers);
+        if (coerced) {
+            state.mainstay.tracer.value(state, 'coerced', value, coerced.value);
+            //Coerce error always aborts early
+            if (coerced.errors)
+                return finalize(coerced.value, [].concat(coerced.errors), helpers);
+            value = coerced.value;
+        }
+    }
+    //Empty value
+    const empty = schema._flags.empty;
+    if (empty && empty.$_match(trim(value, schema), state.nest(empty), Common.defaults)) {
+        state.mainstay.tracer.value(state, 'empty', value, undefined);
+        value = undefined;
+    }
+    //Presence requirements (required, optional, forbidden)
+    const presence = overrides.presence || schema._flags.presence || (schema._flags._endedSwitch ? null : prefs.presence);
+    if (value === undefined) {
+        if (presence === 'forbidden')
+            return finalize(value, null, helpers);
+        if (presence === 'required')
+            return finalize(value, [schema.$_createError('any.required', value, null, state, prefs)], helpers);
+        if (presence === 'optional') {
+            if (schema._flags.default !== Common.symbols.deepDefault)
+                return finalize(value, null, helpers);
+            state.mainstay.tracer.value(state, 'default', value, {});
+            value = {};
+        }
+    }
+    else if (presence === 'forbidden') {
+        return finalize(value, [schema.$_createError('any.unknown', value, null, state, prefs)], helpers);
+    }
+    //Allowed values
+    const errors = [];
+    if (schema._valids) {
+        const match = schema._valids.get(value, state, prefs, schema._flags.insensitive);
+        if (match) {
+            if (prefs.convert) {
+                state.mainstay.tracer.value(state, 'valids', value, match.value);
+                value = match.value;
+            }
+            state.mainstay.tracer.filter(schema, state, 'valid', match);
+            return finalize(value, null, helpers);
+        }
+        if (schema._flags.only) {
+            const report = schema.$_createError('any.only', value, { valids: schema._valids.values({ display: true }) }, state, prefs);
+            if (prefs.abortEarly)
+                return finalize(value, [report], helpers);
+            errors.push(report);
+        }
+    }
+    //Denied values
+    if (schema._invalids) {
+        const match = schema._invalids.get(value, state, prefs, schema._flags.insensitive);
+        if (match) {
+            state.mainstay.tracer.filter(schema, state, 'invalid', match);
+            const report = schema.$_createError('any.invalid', value, { invalids: schema._invalids.values({ display: true }) }, state, prefs);
+            if (prefs.abortEarly)
+                return finalize(value, [report], helpers);
+            errors.push(report);
+        }
+    }
+    //Base type
+    if (def.validate) {
+        const base = def.validate(value, helpers);
+        if (base) {
+            state.mainstay.tracer.value(state, 'base', value, base.value);
+            value = base.value;
+            if (base.errors) {
+                if (!Array.isArray(base.errors)) {
+                    errors.push(base.errors);
+                    //Base error always aborts early
+                    return finalize(value, errors, helpers);
+                }
+                if (base.errors.length) {
+                    errors.push(...base.errors);
+                    //Base error always aborts early
+                    return finalize(value, errors, helpers);
+                }
+            }
+        }
+    }
+    //Validate tests
+    if (!schema._rules.length)
+        return finalize(value, errors, helpers);
+    return rules(value, errors, helpers);
+}
+function rules(value, errors, helpers) {
+    const { schema, state, prefs } = helpers;
+    for (const rule of schema._rules) {
+        const definition = schema._definition.rules[rule.method];
+        //Skip rules that are also applied in coerce step
+        if (definition.convert && prefs.convert) {
+            state.mainstay.tracer.log(schema, state, 'rule', rule.name, 'full');
+            continue;
+        }
+        //Resolve references
+        let ret;
+        let args = rule.args;
+        if (rule._resolve.length) {
+            //Shallow copy
+            args = Object.assign({}, args);
+            for (const key of rule._resolve) {
+                const resolver = definition.argsByName.get(key);
+                const resolved = args[key].resolve(value, state, prefs);
+                const normalized = resolver.normalize ? resolver.normalize(resolved) : resolved;
+                //Like upstream: a reference argument is expected to have an assertion
+                const invalid = Common.validateArg(normalized, undefined, resolver);
+                if (invalid) {
+                    ret = schema.$_createError('any.ref', resolved, { arg: key, ref: args[key], reason: invalid }, state, prefs);
+                    break;
+                }
+                args[key] = normalized;
+            }
+        }
+        //Test rule
+        //Use ret if already set to reference error
+        ret = ret || definition.validate(value, helpers, args, rule);
+        const result = ruleResult(ret, rule);
+        if (result.errors) {
+            state.mainstay.tracer.log(schema, state, 'rule', rule.name, 'error');
+            if (rule.warn) {
+                state.mainstay.warnings.push(...result.errors);
+                continue;
+            }
+            if (prefs.abortEarly)
+                return finalize(value, result.errors, helpers);
+            errors.push(...result.errors);
+        }
+        else {
+            state.mainstay.tracer.log(schema, state, 'rule', rule.name, 'pass');
+            state.mainstay.tracer.value(state, 'rule', value, result.value, rule.name);
+            value = result.value;
+        }
+    }
+    return finalize(value, errors, helpers);
+}
+function ruleResult(ret, rule) {
+    if (ret instanceof Errors.Report) {
+        error(ret, rule);
+        return { errors: [ret], value: null };
+    }
+    if (Array.isArray(ret) && ret[Common.symbols.errors]) {
+        ret.forEach((report) => error(report, rule));
+        return { errors: ret, value: null };
+    }
+    return { errors: null, value: ret };
+}
+function error(report, rule) {
+    if (rule.message)
+        report._setTemplate(rule.message);
+    return report;
+}
+function finalize(value, errors, helpers) {
+    errors = errors || [];
+    const { schema, state, prefs } = helpers;
+    //Failover value
+    if (errors.length) {
+        const failover = defaultValue('failover', undefined, errors, helpers);
+        if (failover !== undefined) {
+            state.mainstay.tracer.value(state, 'failover', value, failover);
+            value = failover;
+            errors = [];
+        }
+    }
+    //Error override
+    const override = schema._flags.error;
+    if (errors.length && override) {
+        if (typeof override === 'function') {
+            const overridden = override(errors);
+            errors = Array.isArray(overridden) ? overridden : [overridden];
+            for (const error of errors)
+                assert(error instanceof Error || error instanceof Errors.Report, 'error() must return an Error object');
+        }
+        else {
+            errors = [override];
+        }
+    }
+    //Default
+    if (value === undefined) {
+        const defaulted = defaultValue('default', value, errors, helpers);
+        state.mainstay.tracer.value(state, 'default', value, defaulted);
+        value = defaulted;
+    }
+    //Cast
+    if (schema._flags.cast && value !== undefined) {
+        const caster = schema._definition.cast[schema._flags.cast];
+        if (caster.from(value)) {
+            const casted = caster.to(value, helpers);
+            state.mainstay.tracer.value(state, 'cast', value, casted, schema._flags.cast);
+            value = casted;
+        }
+    }
+    //Externals
+    //Disabled for matching
+    if (schema.$_terms.externals && prefs.externals && prefs._externals !== false) {
+        for (const { method } of schema.$_terms.externals)
+            state.mainstay.externals.push({ method, schema, state, label: Errors.label(schema._flags, state, prefs, undefined) });
+    }
+    //Result
+    const result = { value, errors: errors.length ? errors : null };
+    if (schema._flags.result) {
+        result.value = schema._flags.result === 'strip' ? undefined : /* raw */ helpers.original;
+        state.mainstay.tracer.value(state, schema._flags.result, value, result.value);
+        state.shadow(value, schema._flags.result);
+    }
+    //Cache
+    if (schema._cache && prefs.cache !== false && !schema._refs.length)
+        schema._cache.set(helpers.original, result);
+    //Artifacts
+    if (value !== undefined && !result.errors && schema._flags.artifact !== undefined) {
+        state.mainstay.artifacts = state.mainstay.artifacts || new Map();
+        if (!state.mainstay.artifacts.has(schema._flags.artifact))
+            state.mainstay.artifacts.set(schema._flags.artifact, []);
+        state.mainstay.artifacts.get(schema._flags.artifact).push(state.path);
+    }
+    return result;
+}
+/**
+ * The preferences of schemas merged with their parent preferences, by schema preferences then by parent preferences
+ * (lakutata: upstream caches only the merge with the default preferences). Merged preferences are never mutated.
+ */
+const mergedPreferences = new WeakMap();
+function prefsOf(schema, prefs) {
+    const preferences = schema._preferences;
+    const isDefaultOptions = prefs === Common.defaults;
+    if (isDefaultOptions && preferences[Common.symbols.prefs])
+        return preferences[Common.symbols.prefs];
+    let byParent = mergedPreferences.get(preferences);
+    const cached = byParent && byParent.get(prefs);
+    if (cached)
+        return cached;
+    const merged = Common.preferences(prefs, preferences);
+    if (isDefaultOptions) {
+        preferences[Common.symbols.prefs] = merged;
+    }
+    else {
+        if (!byParent) {
+            byParent = new WeakMap();
+            mergedPreferences.set(preferences, byParent);
+        }
+        byParent.set(prefs, merged);
+    }
+    return merged;
+}
+/**
+ * The validation settings (the defaults merged with the validate() options) by options, for the options which cannot
+ * change: frozen, with primitive values only (lakutata: the settings are reused across validations, so the schema
+ * preferences merged with them are reused too). Merged preferences are never mutated.
+ */
+const settingsByOptions = new WeakMap();
+/**
+ * The validation settings which never change (the defaults, and the settings of options which cannot change): the fast
+ * path compiles the schemas for them
+ */
+const stableSettings = new WeakSet([Common.defaults]);
+let fastPathMode = 'on';
+/**
+ * Set the mode of the validation fast path
+ * @param mode
+ */
+export function setFastPathMode(mode) {
+    fastPathMode = mode;
+}
+/**
+ * The value validated by the fast path, or FALLBACK (the interpreter must validate it)
+ * @param value
+ * @param schema
+ * @param settings
+ */
+function fastPath(value, schema, settings) {
+    if (fastPathMode === 'off' || schema.$_root._tracer)
+        return FALLBACK;
+    if (fastPathMode === 'on' && !stableSettings.has(settings))
+        return FALLBACK;
+    const compiled = compiledFor(schema, settings);
+    return compiled ? compiled(value) : FALLBACK;
+}
+/**
+ * Check (verify mode) that the interpreter validated the value like the fast path
+ * @param value
+ * @param fast
+ * @param result
+ */
+function verifyFastPath(value, fast, result) {
+    if (fast === FALLBACK)
+        return;
+    if (fast === INVALID) {
+        if (!result.error)
+            throw new Error('Validation fast path mismatch: invalid for the fast path, valid for the interpreter');
+        return;
+    }
+    if (result.error || !sameResult(fast, result.value, value))
+        throw new Error(`Validation fast path mismatch: ${result.error ? result.error.message : 'different value'}`);
+}
+/**
+ * Whether options cannot change: frozen, without symbol keys, with primitive values only
+ * @param prefs
+ */
+function isImmutableOptions(prefs) {
+    if (!Object.isFrozen(prefs) || Object.getOwnPropertySymbols(prefs).length)
+        return false;
+    for (const name of Object.keys(prefs)) {
+        const value = prefs[name];
+        if ((value !== null && typeof value === 'object') || typeof value === 'function')
+            return false;
+    }
+    return true;
+}
+/**
+ * The defaults merged with the validate() options
+ * @param prefs
+ */
+function entrySettings(prefs) {
+    const cached = settingsByOptions.get(prefs);
+    if (cached)
+        return cached;
+    const settings = Common.preferences(Common.defaults, prefs);
+    if (isImmutableOptions(prefs)) {
+        settingsByOptions.set(prefs, settings);
+        stableSettings.add(settings);
+    }
+    return settings;
+}
+function defaultValue(flag, value, errors, helpers) {
+    const { schema, state, prefs } = helpers;
+    const source = schema._flags[flag];
+    if (prefs.noDefaults || source === undefined)
+        return value;
+    state.mainstay.tracer.log(schema, state, 'rule', flag, 'full');
+    if (!source)
+        return source;
+    if (typeof source === 'function') {
+        const args = source.length ? [clone(state.ancestors[0]), helpers] : [];
+        try {
+            return source(...args);
+        }
+        catch (err) {
+            errors.push(schema.$_createError(`any.${flag}`, null, { error: err }, state, prefs));
+            return;
+        }
+    }
+    if (typeof source !== 'object')
+        return source;
+    if (source[Common.symbols.literal])
+        return source.literal;
+    if (Common.isResolvable(source))
+        return source.resolve(value, state, prefs);
+    return clone(source);
+}
+function trim(value, schema) {
+    if (typeof value !== 'string')
+        return value;
+    const trimRule = schema.$_getRule('trim');
+    if (!trimRule || !trimRule.args.enabled)
+        return value;
+    return value.trim();
+}
+const ignoreTracer = {
+    active: false,
+    debug: ignore,
+    entry: ignore,
+    filter: ignore,
+    log: ignore,
+    resolve: ignore,
+    value: ignore
+};
+function errorsArray() {
+    const errors = [];
+    errors[Common.symbols.errors] = true;
+    return errors;
+}