@lakutata/core 1.0.60 → 3.0.0-beta.1

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

@@ -0,0 +1,622 @@
+/**
+ * lakutata: the validation fast path (not from upstream). A schema made of common constructs is compiled, for given
+ * validation settings, into a tree of closures which validates a value without the per node states, helpers and results
+ * of the interpreter (validator.ts). It only produces successful results: on a definite error it returns INVALID, and on
+ * anything it does not decide (a default computed by a function, a warning...) it returns FALLBACK; in both cases the
+ * value is validated by the interpreter, which produces the result (errors included). The fast path never changes its
+ * input, so falling back is always possible. INVALID lets alternatives try their next schema like the interpreter.
+ *
+ * The type, coercion and rule semantics are not reimplemented: the compiled nodes call the functions of the type
+ * definitions with fixed helpers, whose error() returns a marker. Only the flow of a node (validator.ts validate() and
+ * finalize()), the keys of objects and the items of arrays are compiled.
+ */
+import { clone } from '../utils/index.js';
+import * as Common from './common.js';
+import * as Errors from './errors.js';
+/**
+ * Returned by a compiled schema when the value must be validated by the interpreter
+ */
+export const FALLBACK = Symbol('fallback');
+/**
+ * Returned by a compiled schema when the value is invalid (the interpreter reports an error for it)
+ */
+export const INVALID = Symbol('invalid');
+/**
+ * Returned by the error() of the fixed helpers
+ */
+const errorMarker = Object.freeze({ fastPathError: true });
+/**
+ * Thrown by the fixed helpers for what the fast path does not handle (warnings)
+ */
+const unsupported = Symbol('unsupported');
+/**
+ * The types compiled, with the rules compiled for each (null: all its rules)
+ */
+const compiledTypes = new Map([
+    ['any', new Set()],
+    ['string', null],
+    ['number', null],
+    ['boolean', null],
+    ['date', null],
+    ['object', new Set(['min', 'max', 'length'])],
+    ['array', new Set(['items', 'min', 'max', 'length'])],
+    ['alternatives', new Set()]
+]);
+/**
+ * Flags which need the interpreter
+ */
+const interpretedFlags = ['empty', 'cast', 'result', 'artifact', '_endedSwitch', '_hasPatternMatch', 'single', 'match'];
+/**
+ * Terms which need the interpreter when set
+ */
+const interpretedTerms = ['whens', 'externals', 'renames', 'dependencies', '_exclusions', '_requireds'];
+/**
+ * The custom rule methods known to be pure: deterministic, without side effects, calling only error() of the helpers
+ */
+const pureMethods = new WeakSet();
+/**
+ * Mark the method of a custom rule as pure (deterministic, without side effects, calling only error() of the helpers),
+ * so the fast path can compile the schemas using it (for lakutata's own validators; other custom rules are interpreted)
+ * @param method
+ */
+export function pure(method) {
+    pureMethods.add(method);
+    return method;
+}
+/**
+ * The fixed helpers of a compiled node: the same members as the helpers of the interpreter, error() returns a marker
+ * @param schema
+ * @param prefs
+ */
+function fixedHelpers(schema, prefs) {
+    return {
+        original: undefined,
+        prefs,
+        schema,
+        state: undefined,
+        error: () => errorMarker,
+        errorsArray: () => {
+            const errors = [];
+            errors[Common.symbols.errors] = true;
+            return errors;
+        },
+        warn: () => {
+            throw unsupported;
+        },
+        message: () => errorMarker
+    };
+}
+/**
+ * Whether an outcome has errors (validator.ts: a non array error, or a non empty array)
+ * @param outcome
+ */
+function hasErrors(outcome) {
+    return !!outcome.errors && (!Array.isArray(outcome.errors) || outcome.errors.length > 0);
+}
+/**
+ * Whether a rule result is an error (validator.ts ruleResult())
+ * @param ret
+ */
+function isRuleError(ret) {
+    return ret === errorMarker || ret instanceof Errors.Report || (Array.isArray(ret) && !!ret[Common.symbols.errors]);
+}
+/**
+ * Whether a values set can be matched without a validation state (it holds no references)
+ * @param values
+ */
+function withoutReferences(values) {
+    return !values || values._refs.size === 0;
+}
+/**
+ * Compile the checks of a rule (null: not compiled)
+ * @param schema
+ * @param rule
+ * @param helpers
+ */
+function compileRule(schema, rule, helpers) {
+    const definition = schema._definition.rules[rule.method];
+    const validate = definition.validate;
+    if (!validate)
+        return null;
+    const args = rule.args;
+    return (value) => {
+        const ret = validate(value, helpers, args, rule);
+        return isRuleError(ret) ? INVALID : ret;
+    };
+}
+/**
+ * Compile the keys of an object schema (the validate() of the keys type and its unknown()), null: not compiled
+ * @param schema
+ * @param prefs
+ */
+function compileKeys(schema, prefs) {
+    const terms = schema.$_terms;
+    const keys = terms.keys;
+    const patterns = terms.patterns;
+    const type = schema.$_property('typeof');
+    //Skip if there are no other rules to test (null allows any keys)
+    if (!keys && !patterns) {
+        return (input) => (!input || typeof input !== type || Array.isArray(input)) ? INVALID : input;
+    }
+    const children = [];
+    for (const child of keys || []) {
+        const compiled = compileSchema(child.schema, prefs);
+        if (!compiled)
+            return null;
+        children.push({ key: child.key, compiled });
+    }
+    const compiledPatterns = [];
+    //The key schemas are matched like $_match() does it (abort early, without external rules)
+    const matchPrefs = Object.assign({}, prefs, { abortEarly: true, _externals: false });
+    for (const pattern of patterns || []) {
+        if (pattern.matches)
+            return null;
+        const rule = compileSchema(pattern.rule, prefs);
+        if (!rule)
+            return null;
+        if (pattern.regex) {
+            compiledPatterns.push({ regex: pattern.regex, rule, fallthrough: !!pattern.fallthrough });
+        }
+        else {
+            const matcher = compileSchema(pattern.schema, matchPrefs);
+            if (!matcher)
+                return null;
+            compiledPatterns.push({ matcher, rule, fallthrough: !!pattern.fallthrough });
+        }
+    }
+    const flags = schema._flags;
+    const stripUnknownPreference = prefs.stripUnknown ? (prefs.stripUnknown === true ? true : !!prefs.stripUnknown.objects) : false;
+    const handleUnknown = !!(prefs.stripUnknown && typeof flags.unknown === 'undefined' || prefs.skipFunctions);
+    const forbidUnknown = !Common.defaultValue(flags.unknown, prefs.allowUnknown);
+    //Without patterns, a forbidden unknown key makes the object invalid whatever its keys: it is found before them
+    const childKeys = forbidUnknown && !compiledPatterns.length ? new Set(children.map((child) => child.key)) : null;
+    return (input) => {
+        if (!input || typeof input !== type || Array.isArray(input))
+            return INVALID;
+        //Shallow clone value (keys.ts clone())
+        const value = Object.create(Object.getPrototypeOf(input));
+        Object.assign(value, input);
+        const unprocessed = new Set(Object.keys(value));
+        if (childKeys) {
+            for (const key of unprocessed) {
+                if (childKeys.has(key))
+                    continue;
+                if (handleUnknown && (stripUnknownPreference || typeof value[key] === 'function'))
+                    continue;
+                return INVALID;
+            }
+        }
+        for (const { key, compiled } of children) {
+            const item = value[key];
+            unprocessed.delete(key);
+            const result = compiled(item);
+            if (result === FALLBACK || result === INVALID)
+                return result;
+            if (result === undefined && item !== undefined) {
+                delete value[key];
+            }
+            else if (result !== undefined) {
+                value[key] = result;
+            }
+        }
+        //Unknown keys (keys.ts unknown())
+        if (unprocessed.size) {
+            for (const key of unprocessed) {
+                const item = value[key];
+                for (const pattern of compiledPatterns) {
+                    if (pattern.regex) {
+                        if (!pattern.regex.test(key))
+                            continue;
+                    }
+                    else {
+                        const matched = pattern.matcher(key);
+                        if (matched === INVALID)
+                            continue;
+                        if (matched === FALLBACK)
+                            return FALLBACK;
+                    }
+                    unprocessed.delete(key);
+                    const result = pattern.rule(item);
+                    if (result === FALLBACK || result === INVALID)
+                        return result;
+                    value[key] = result;
+                    if (!pattern.fallthrough)
+                        break;
+                }
+            }
+            if (unprocessed.size) {
+                if (handleUnknown) {
+                    for (const key of unprocessed) {
+                        if (stripUnknownPreference) {
+                            delete value[key];
+                            unprocessed.delete(key);
+                        }
+                        else if (typeof value[key] === 'function') {
+                            unprocessed.delete(key);
+                        }
+                    }
+                }
+                if (forbidUnknown && unprocessed.size)
+                    return INVALID;
+            }
+        }
+        return value;
+    };
+}
+/**
+ * Compile the items of an array schema (the items rule of the array type, for ordered items and at most one item
+ * schema, without required or forbidden item schemas), null: not compiled
+ * @param schema
+ * @param prefs
+ */
+function compileItems(schema, prefs) {
+    const terms = schema.$_terms;
+    const items = terms.items;
+    const inclusions = terms._inclusions;
+    if (items.length > 1 || inclusions.length !== items.length)
+        return null;
+    const inclusion = inclusions.length ? compileSchema(inclusions[0], prefs) : null;
+    if (inclusions.length && !inclusion)
+        return null;
+    const ordered = [];
+    for (const type of terms.ordered) {
+        const compiled = compileSchema(type, prefs);
+        if (!compiled)
+            return null;
+        ordered.push(compiled);
+    }
+    const sparse = !!schema._flags.sparse;
+    //A failing item is stripped instead (the interpreter decides)
+    const stripItems = !!(prefs.stripUnknown && prefs.stripUnknown.arrays);
+    return (input) => {
+        const value = input;
+        let position = 0;
+        for (let i = 0; i < value.length; ++i) {
+            const item = value[i];
+            if (!sparse && item === undefined)
+                return INVALID;
+            //Ordered
+            if (ordered.length) {
+                if (position < ordered.length) {
+                    const result = ordered[position++](item);
+                    if (result === FALLBACK || result === INVALID)
+                        return result;
+                    if (!sparse && result === undefined)
+                        return INVALID;
+                    value[i] = result;
+                    continue;
+                }
+                else if (!items.length) {
+                    //More items than ordered schemas
+                    return INVALID;
+                }
+            }
+            //Item schema (any item without one)
+            if (inclusion) {
+                const result = inclusion(item);
+                if (result === FALLBACK)
+                    return FALLBACK;
+                if (result === INVALID)
+                    return stripItems ? FALLBACK : INVALID;
+                if (!sparse && result === undefined)
+                    return INVALID;
+                value[i] = result;
+            }
+        }
+        //Missing ordered items (errors or defaults)
+        if (position < ordered.length)
+            return FALLBACK;
+        return value;
+    };
+}
+/**
+ * Whether a schema is made only of constructs the fast path handles (without looking at its children)
+ * @param schema
+ */
+function compilable(schema) {
+    if (!compiledTypes.has(schema.type))
+        return false;
+    if (schema._cache || schema._ids._schemaChain)
+        return false;
+    const flags = schema._flags;
+    for (const flag of interpretedFlags) {
+        if (flags[flag] !== undefined)
+            return false;
+    }
+    //A schema for the unknown keys
+    if (typeof flags.unknown === 'object')
+        return false;
+    const terms = schema.$_terms;
+    for (const term of interpretedTerms) {
+        const value = terms[term];
+        if (value && (!Array.isArray(value) || value.length))
+            return false;
+    }
+    if (!withoutReferences(schema._valids) || !withoutReferences(schema._invalids))
+        return false;
+    const rules = compiledTypes.get(schema.type);
+    for (const rule of schema._rules) {
+        if (rule._resolve.length || rule.warn)
+            return false;
+        if (rule.name === 'custom') {
+            if (!pureMethods.has(rule.args.method))
+                return false;
+            continue;
+        }
+        if (rule.name === 'warning')
+            return false;
+        if (rules && !rules.has(rule.name))
+            return false;
+    }
+    return true;
+}
+/**
+ * Compile a schema for the preferences of its parent (null: not compiled)
+ * @param schema
+ * @param parentPrefs
+ */
+function compileSchema(schema, parentPrefs) {
+    if (!compilable(schema))
+        return null;
+    const prefs = schema._preferences ? Common.preferences(parentPrefs, schema._preferences) : parentPrefs;
+    if (prefs.nonEnumerables || prefs.debug)
+        return null;
+    const def = schema._definition;
+    const flags = schema._flags;
+    const helpers = fixedHelpers(schema, prefs);
+    const prepare = prefs.convert ? def.prepare : undefined;
+    const coerce = prefs.convert ? def.coerce : undefined;
+    const presence = flags.presence || prefs.presence;
+    const hasDefault = flags.default !== undefined && !prefs.noDefaults;
+    const deepDefault = flags.default === Common.symbols.deepDefault;
+    const valids = schema._valids;
+    const invalids = schema._invalids;
+    const insensitive = flags.insensitive;
+    const only = !!flags.only;
+    const convert = !!prefs.convert;
+    //Base type
+    let base;
+    if (schema.type === 'object') {
+        base = compileKeys(schema, prefs);
+        if (!base)
+            return null;
+    }
+    else if (schema.type === 'alternatives') {
+        base = compileAlternatives(schema, prefs);
+        if (!base)
+            return null;
+    }
+    else {
+        const validate = def.validate;
+        base = validate
+            ? (value) => {
+                const outcome = validate(value, helpers);
+                if (!outcome)
+                    return value;
+                if (hasErrors(outcome))
+                    return INVALID;
+                return outcome.value;
+            }
+            : null;
+    }
+    //Rules
+    const steps = [];
+    for (const rule of schema._rules) {
+        const definition = def.rules[rule.method];
+        //Skip rules that are also applied in coerce step
+        if (definition.convert && convert)
+            continue;
+        const step = schema.type === 'array' && rule.name === 'items' ? compileItems(schema, prefs) : compileRule(schema, rule, helpers);
+        if (!step)
+            return null;
+        steps.push(step);
+    }
+    const source = flags.default;
+    //validator.ts defaultValue(): functions and references need the interpreter
+    const defaulted = () => {
+        if (!source)
+            return source;
+        if (typeof source === 'function')
+            return FALLBACK;
+        if (typeof source !== 'object')
+            return source;
+        if (source[Common.symbols.literal])
+            return source.literal;
+        if (Common.isResolvable(source))
+            return FALLBACK;
+        return clone(source);
+    };
+    const finalize = (value) => value === undefined && hasDefault ? defaulted() : value;
+    const node = (input) => {
+        let value = input;
+        //Prepare
+        if (prepare && value !== undefined) {
+            const prepared = prepare(value, helpers);
+            if (prepared) {
+                if (prepared.errors)
+                    return INVALID;
+                value = prepared.value;
+            }
+        }
+        //Type coercion
+        if (coerce && value !== undefined && (!coerce.from || coerce.from.includes(typeof value))) {
+            const coerced = coerce.method(value, helpers);
+            if (coerced) {
+                if (coerced.errors)
+                    return INVALID;
+                value = coerced.value;
+            }
+        }
+        //Presence requirements (required, optional, forbidden)
+        if (value === undefined) {
+            if (presence === 'forbidden')
+                return finalize(value);
+            if (presence === 'required')
+                return INVALID;
+            if (presence === 'optional')
+                return deepDefault ? FALLBACK : finalize(value);
+        }
+        else if (presence === 'forbidden') {
+            return INVALID;
+        }
+        //Allowed values
+        if (valids) {
+            const match = valids.get(value, null, prefs, insensitive);
+            if (match) {
+                if (convert)
+                    value = match.value;
+                return finalize(value);
+            }
+            if (only)
+                return INVALID;
+        }
+        //Denied values
+        if (invalids && invalids.get(value, null, prefs, insensitive))
+            return INVALID;
+        //Base type
+        if (base) {
+            value = base(value);
+            if (value === FALLBACK || value === INVALID)
+                return value;
+        }
+        //Rules
+        for (const step of steps) {
+            value = step(value);
+            if (value === FALLBACK || value === INVALID)
+                return value;
+        }
+        return finalize(value);
+    };
+    //A failover value replaces the errors (the interpreter computes it)
+    if (flags.failover === undefined)
+        return node;
+    return (input) => {
+        const value = node(input);
+        return value === INVALID ? FALLBACK : value;
+    };
+}
+/**
+ * Compile the alternatives of an alternatives schema (tried in order, the first valid one wins), null: not compiled
+ * @param schema
+ * @param prefs
+ */
+function compileAlternatives(schema, prefs) {
+    const alternatives = [];
+    for (const item of schema.$_terms.matches) {
+        //Conditions need the interpreter
+        if (!item.schema)
+            return null;
+        const compiled = compileSchema(item.schema, prefs);
+        if (!compiled)
+            return null;
+        alternatives.push(compiled);
+    }
+    return (value) => {
+        for (const alternative of alternatives) {
+            const result = alternative(value);
+            //A definitely invalid alternative lets the next one be tried, an undecided one does not
+            if (result !== INVALID)
+                return result;
+        }
+        return INVALID;
+    };
+}
+/**
+ * Compiled schemas, by schema then by settings (null: the schema is not compiled for these settings)
+ */
+const compiledSchemas = new WeakMap();
+/**
+ * The compiled schema for the validation settings (null: validate with the interpreter)
+ * @param schema
+ * @param settings the settings of a validation (defaults merged with the validate() options), which must not change
+ */
+export function compiledFor(schema, settings) {
+    let bySettings = compiledSchemas.get(schema);
+    if (!bySettings) {
+        bySettings = new WeakMap();
+        compiledSchemas.set(schema, bySettings);
+    }
+    let compiled = bySettings.get(settings);
+    if (compiled === undefined) {
+        const tree = settings.debug ? null : compileSchema(schema, settings);
+        compiled = tree ? guarded(tree) : null;
+        bySettings.set(settings, compiled);
+    }
+    return compiled;
+}
+/**
+ * A compiled schema which falls back on any exception (the interpreter then throws it, if it is a genuine one)
+ * @param tree
+ */
+function guarded(tree) {
+    return (value) => {
+        try {
+            return tree(value);
+        }
+        catch {
+            return FALLBACK;
+        }
+    };
+}
+/**
+ * The time of a date (undefined for anything else, objects with the Date prototype included)
+ * @param value
+ */
+function dateTime(value) {
+    try {
+        return Date.prototype.getTime.call(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether the fast path and the interpreter produced the same value: same primitives (Object.is), and objects with the
+ * same prototype, own keys (in order), property attributes and values, where the input is reused in the same places
+ * @param fast
+ * @param interpreted
+ * @param input the validated value at the same place
+ * @param seen
+ */
+export function sameResult(fast, interpreted, input, seen = new Map()) {
+    if (Object.is(fast, interpreted))
+        return true;
+    if (typeof fast !== 'object' || fast === null || typeof interpreted !== 'object' || interpreted === null)
+        return false;
+    //Different objects: none of them may be the input (the other one would reuse it)
+    if (fast === input || interpreted === input)
+        return false;
+    const known = seen.get(fast);
+    if (known)
+        return known === interpreted;
+    seen.set(fast, interpreted);
+    if (Object.getPrototypeOf(fast) !== Object.getPrototypeOf(interpreted))
+        return false;
+    if (Array.isArray(fast) !== Array.isArray(interpreted))
+        return false;
+    const fastTime = dateTime(fast);
+    const time = dateTime(interpreted);
+    if (fastTime !== undefined || time !== undefined)
+        return fastTime !== undefined && time !== undefined && Object.is(fastTime, time);
+    const fastKeys = Reflect.ownKeys(fast);
+    const keys = Reflect.ownKeys(interpreted);
+    if (fastKeys.length !== keys.length)
+        return false;
+    for (let i = 0; i < keys.length; ++i) {
+        const key = keys[i];
+        if (fastKeys[i] !== key)
+            return false;
+        const a = Object.getOwnPropertyDescriptor(fast, key);
+        const b = Object.getOwnPropertyDescriptor(interpreted, key);
+        if (a.enumerable !== b.enumerable || a.configurable !== b.configurable || a.writable !== b.writable)
+            return false;
+        if (a.get !== b.get || a.set !== b.set)
+            return false;
+        if ('value' in a) {
+            const inputChild = input !== null && typeof input === 'object' ? input[key] : undefined;
+            if (!sameResult(a.value, b.value, inputChild, seen))
+                return false;
+        }
+    }
+    return true;
+}