@lakutata/core 1.0.59 → 3.0.0-beta.0

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

@@ -0,0 +1,240 @@
+/**
+ * Derived from the upstream lib/trace.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+import { deepEqual } from '../utils/index.js';
+import { location as callLocation } from '../location/index.js';
+import * as Errors from './errors.js';
+const codes = {
+    error: 1,
+    pass: 2,
+    full: 3
+};
+const labels = {
+    0: 'never used',
+    1: 'always error',
+    2: 'always pass'
+};
+/**
+ * Add trace() and untrace() to the root object
+ * @param root
+ */
+export function setup(root) {
+    const trace = function () {
+        root._tracer = root._tracer || new Tracer();
+        return root._tracer;
+    };
+    root.trace = trace;
+    root.untrace = () => {
+        root._tracer = null;
+    };
+}
+/**
+ * Record the location of the caller of schema.tracer()
+ * @param schema
+ */
+export function location(schema) {
+    //base.tracer(), caller
+    return schema.$_setFlag('_tracerLocation', callLocation(2));
+}
+/**
+ * Collects the coverage of the traced schemas
+ */
+export class Tracer {
+    constructor() {
+        this.name = 'lakutata';
+        this._schemas = new Map();
+    }
+    _register(schema) {
+        const existing = this._schemas.get(schema);
+        if (existing)
+            return existing.store;
+        const store = new Store(schema);
+        //internals.tracer(), internals.entry(), $exports.entry(), validate(), caller
+        const { filename, line } = schema._flags._tracerLocation || callLocation(5);
+        this._schemas.set(schema, { filename, line, store });
+        return store;
+    }
+    _combine(merged, sources) {
+        for (const { store } of this._schemas.values())
+            store._combine(merged, sources);
+    }
+    report(file) {
+        const coverage = [];
+        //Process each registered schema
+        for (const { filename, line, store } of this._schemas.values()) {
+            if (file && file !== filename)
+                continue;
+            //Process sub schemas of the registered root
+            const missing = [];
+            const skipped = [];
+            for (const [schema, log] of store._sources.entries()) {
+                //Check if sub schema parent skipped
+                if (sub(log.paths, skipped))
+                    continue;
+                //Check if sub schema reached
+                if (!log.entry) {
+                    missing.push({
+                        status: 'never reached',
+                        paths: [...log.paths]
+                    });
+                    skipped.push(...log.paths);
+                    continue;
+                }
+                //Check values
+                for (const type of ['valid', 'invalid']) {
+                    const set = schema[`_${type}s`];
+                    if (!set)
+                        continue;
+                    const values = new Set(set._values);
+                    const refs = new Set(set._refs);
+                    for (const { value, ref } of log[type]) {
+                        values.delete(value);
+                        refs.delete(ref);
+                    }
+                    if (values.size || refs.size) {
+                        missing.push({
+                            status: [...values, ...[...refs].map((ref) => ref.display)],
+                            rule: `${type}s`
+                        });
+                    }
+                }
+                //Check rules status
+                const rules = schema._rules.map((rule) => rule.name);
+                for (const type of ['default', 'failover']) {
+                    if (schema._flags[type] !== undefined)
+                        rules.push(type);
+                }
+                for (const name of rules) {
+                    const status = labels[log.rule[name] || 0];
+                    if (status) {
+                        const report = { rule: name, status };
+                        if (log.paths.size)
+                            report.paths = [...log.paths];
+                        missing.push(report);
+                    }
+                }
+            }
+            if (missing.length) {
+                coverage.push({
+                    filename,
+                    line,
+                    missing,
+                    severity: 'error',
+                    message: `Schema missing tests for ${missing.map(message).join(', ')}`
+                });
+            }
+        }
+        return coverage.length ? coverage : null;
+    }
+}
+/**
+ * The coverage store of a registered schema, recording the validations of its sub schemas
+ */
+export class Store {
+    constructor(schema) {
+        this.active = true;
+        this._sources = new Map();
+        this._combos = new Map();
+        this._scan(schema);
+    }
+    debug(state, source, name, result) {
+        state.mainstay.debug && state.mainstay.debug.push({ type: source, name, result, path: state.path });
+    }
+    entry(schema, state) {
+        debug(state, { type: 'entry' });
+        this._record(schema, (log) => {
+            log.entry = true;
+        });
+    }
+    filter(schema, state, source, value) {
+        debug(state, { type: source, ...value });
+        this._record(schema, (log) => {
+            log[source].add(value);
+        });
+    }
+    log(schema, state, source, name, result) {
+        debug(state, { type: source, name, result: result === 'full' ? 'pass' : result });
+        this._record(schema, (log) => {
+            log[source][name] = log[source][name] || 0;
+            log[source][name] |= codes[result];
+        });
+    }
+    resolve(state, ref, to) {
+        if (!state.mainstay.debug)
+            return;
+        const log = { type: 'resolve', ref: ref.display, to, path: state.path };
+        state.mainstay.debug.push(log);
+    }
+    value(state, by, from, to, name) {
+        if (!state.mainstay.debug || deepEqual(from, to))
+            return;
+        const log = { type: 'value', by, from, to, path: state.path };
+        if (name)
+            log.name = name;
+        state.mainstay.debug.push(log);
+    }
+    _record(schema, each) {
+        const log = this._sources.get(schema);
+        if (log) {
+            each(log);
+            return;
+        }
+        //Like upstream: a schema neither scanned nor combined is not expected here
+        const sources = this._combos.get(schema);
+        for (const source of sources)
+            this._record(source, each);
+    }
+    _scan(schema, _path) {
+        const path = _path || [];
+        let log = this._sources.get(schema);
+        if (!log) {
+            log = {
+                paths: new Set(),
+                entry: false,
+                rule: {},
+                valid: new Set(),
+                invalid: new Set()
+            };
+            this._sources.set(schema, log);
+        }
+        if (path.length)
+            log.paths.add(path);
+        const each = (sub, source) => {
+            const subId = id(sub, source);
+            this._scan(sub, path.concat(subId));
+        };
+        schema.$_modify({ each, ref: false });
+    }
+    _combine(merged, sources) {
+        this._combos.set(merged, sources);
+    }
+}
+function message(item) {
+    const path = item.paths ? Errors.path(item.paths[0]) + (item.rule ? ':' : '') : '';
+    return `${path}${item.rule || ''} (${item.status})`;
+}
+function id(schema, { source, name, path, key }) {
+    if (schema._flags.id)
+        return schema._flags.id;
+    if (key)
+        return key;
+    name = `@${name}`;
+    if (source === 'terms')
+        return [name, path[Math.min(path.length - 1, 1)]];
+    return name;
+}
+function sub(paths, skipped) {
+    for (const path of paths) {
+        for (const skip of skipped) {
+            if (deepEqual(path.slice(0, skip.length), skip))
+                return true;
+        }
+    }
+    return false;
+}
+function debug(state, event) {
+    if (state.mainstay.debug) {
+        event.path = state.debug ? [...state.path, state.debug] : state.path;
+        state.mainstay.debug.push(event);
+    }
+}

package/dist/esm/lib/validation/engine/schema/types/alternatives.js

@@ -0,0 +1,294 @@
+/**
+ * Derived from the upstream lib/types/alternatives.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+import { merge } from '../../utils/index.js';
+import { assert } from '../assert.js';
+import * as Common from '../common.js';
+import * as Compile from '../compile.js';
+import * as Errors from '../errors.js';
+import * as Ref from '../ref.js';
+import Any from './any.js';
+const Alternatives = Any.extend({
+    type: 'alternatives',
+    flags: {
+        //'any', 'one', 'all'
+        match: { default: 'any' }
+    },
+    terms: {
+        matches: { init: [], register: Ref.toSibling }
+    },
+    args(schema, ...schemas) {
+        if (schemas.length === 1) {
+            if (Array.isArray(schemas[0])) {
+                return schema.try(...schemas[0]);
+            }
+        }
+        return schema.try(...schemas);
+    },
+    validate(value, helpers) {
+        const { schema, error, state, prefs } = helpers;
+        //Match none (lakutata's own): the value must not match any alternative
+        if (schema._flags.match === 'none') {
+            for (let i = 0; i < schema.$_terms.matches.length; ++i) {
+                const item = schema.$_terms.matches[i];
+                if (item.schema.$_match(value, state.nest(item.schema, `match.${i}`), prefs))
+                    return { errors: error('alternatives.none') };
+            }
+            return { value };
+        }
+        //Match all or one
+        if (schema._flags.match) {
+            const matched = [];
+            const failed = [];
+            for (let i = 0; i < schema.$_terms.matches.length; ++i) {
+                const item = schema.$_terms.matches[i];
+                const localState = state.nest(item.schema, `match.${i}`);
+                localState.snapshot();
+                const result = item.schema.$_validate(value, localState, prefs);
+                if (!result.errors) {
+                    matched.push(result.value);
+                    localState.commit();
+                }
+                else {
+                    failed.push(result.errors);
+                    localState.restore();
+                }
+            }
+            if (matched.length === 0) {
+                const context = {
+                    details: failed.map((f) => Errors.details(f, { override: false }))
+                };
+                return { errors: error('alternatives.any', context) };
+            }
+            //Match one
+            if (schema._flags.match === 'one') {
+                return matched.length === 1 ? { value: matched[0] } : { errors: error('alternatives.one') };
+            }
+            //Match all
+            if (matched.length !== schema.$_terms.matches.length) {
+                const context = {
+                    details: failed.map((f) => Errors.details(f, { override: false }))
+                };
+                return { errors: error('alternatives.all', context) };
+            }
+            const isAnyObj = (alternative) => {
+                return alternative.$_terms.matches.some((v) => {
+                    //Like upstream: conditions of nested alternatives have no schema
+                    return v.schema.type === 'object' ||
+                        (v.schema.type === 'alternatives' && isAnyObj(v.schema));
+                });
+            };
+            //Only plain objects are merged, into a new object (upstream merges into the first matched value, which may
+            //be the validated value itself: an array is emptied; and it merges the null an object schema allows, and throws)
+            const objects = matched.every((v) => v !== null && typeof v === 'object' && !Array.isArray(v));
+            return isAnyObj(schema) && objects ? { value: matched.reduce((acc, v) => merge(acc, v, { mergeArrays: false }), Object.create(Object.getPrototypeOf(matched[0]))) } : { value: matched[matched.length - 1] };
+        }
+        //Match any
+        const errors = [];
+        for (let i = 0; i < schema.$_terms.matches.length; ++i) {
+            const item = schema.$_terms.matches[i];
+            //Try
+            if (item.schema) {
+                const localState = state.nest(item.schema, `match.${i}`);
+                localState.snapshot();
+                const result = item.schema.$_validate(value, localState, prefs);
+                if (!result.errors) {
+                    localState.commit();
+                    return result;
+                }
+                localState.restore();
+                errors.push({ schema: item.schema, reports: result.errors });
+                continue;
+            }
+            //Conditional
+            const input = item.ref ? item.ref.resolve(value, state, prefs, undefined) : value;
+            const tests = item.is ? [item] : item.switch;
+            for (let j = 0; j < tests.length; ++j) {
+                const test = tests[j];
+                const { is, then, otherwise } = test;
+                const id = `match.${i}${item.switch ? '.' + j : ''}`;
+                if (!is.$_match(input, state.nest(is, `${id}.is`), prefs)) {
+                    if (otherwise) {
+                        return otherwise.$_validate(value, state.nest(otherwise, `${id}.otherwise`), prefs);
+                    }
+                }
+                else if (then) {
+                    return then.$_validate(value, state.nest(then, `${id}.then`), prefs);
+                }
+            }
+        }
+        return reportErrors(errors, helpers);
+    },
+    rules: {
+        conditional: {
+            method(condition, options) {
+                assert(!this._flags._endedSwitch, 'Unreachable condition');
+                assert(!this._flags.match, 'Cannot combine match mode', this._flags.match, 'with conditional rule');
+                assert(options.break === undefined, 'Cannot use break option with alternatives conditional');
+                const obj = this.clone();
+                const match = Compile.when(obj, condition, options);
+                const conditions = match.is ? [match] : match.switch;
+                for (const item of conditions) {
+                    if (item.then &&
+                        item.otherwise) {
+                        obj.$_setFlag('_endedSwitch', true, { clone: false });
+                        break;
+                    }
+                }
+                obj.$_terms.matches.push(match);
+                return obj.$_mutateRebuild();
+            }
+        },
+        match: {
+            method(mode) {
+                assert(['any', 'one', 'all', 'none'].includes(mode), 'Invalid alternatives match mode', mode);
+                if (mode !== 'any') {
+                    for (const match of this.$_terms.matches) {
+                        assert(match.schema, 'Cannot combine match mode', mode, 'with conditional rules');
+                    }
+                }
+                return this.$_setFlag('match', mode);
+            }
+        },
+        try: {
+            method(...schemas) {
+                assert(schemas.length, 'Missing alternative schemas');
+                Common.verifyFlat(schemas, 'try');
+                assert(!this._flags._endedSwitch, 'Unreachable condition');
+                const obj = this.clone();
+                for (const schema of schemas) {
+                    obj.$_terms.matches.push({ schema: obj.$_compile(schema) });
+                }
+                return obj.$_mutateRebuild();
+            }
+        }
+    },
+    overrides: {
+        label(name) {
+            const obj = this.$_parent('label', name);
+            const each = (item, source) => {
+                return source.path[0] !== 'is' && typeof item._flags.label !== 'string' ? item.label(name) : undefined;
+            };
+            return obj.$_modify({ each, ref: false });
+        },
+        isAsync() {
+            if (this.$_terms.externals?.length) {
+                return true;
+            }
+            for (const match of this.$_terms.matches) {
+                if (match.schema?.isAsync()) {
+                    return true;
+                }
+                if (match.then?.isAsync()) {
+                    return true;
+                }
+                if (match.otherwise?.isAsync()) {
+                    return true;
+                }
+            }
+            return false;
+        }
+    },
+    rebuild(schema) {
+        //Flag when an alternative type is an array
+        const each = (item) => {
+            if (Common.isSchema(item) &&
+                item.type === 'array') {
+                schema.$_setFlag('_arrayItems', true, { clone: false });
+            }
+        };
+        schema.$_modify({ each });
+    },
+    manifest: {
+        build(obj, desc) {
+            if (desc.matches) {
+                for (const match of desc.matches) {
+                    const { schema, ref, is, not, then, otherwise } = match;
+                    if (schema) {
+                        obj = obj.try(schema);
+                    }
+                    else if (ref) {
+                        obj = obj.conditional(ref, { is, then, not, otherwise, switch: match.switch });
+                    }
+                    else {
+                        obj = obj.conditional(is, { then, otherwise });
+                    }
+                }
+            }
+            return obj;
+        }
+    },
+    messages: {
+        'alternatives.all': '{{#label}} does not match all of the required types',
+        'alternatives.any': '{{#label}} does not match any of the allowed types',
+        'alternatives.match': '{{#label}} does not match any of the allowed types',
+        'alternatives.none': '{{#label}} matches a type which is not allowed',
+        'alternatives.one': '{{#label}} matches more than one allowed type',
+        'alternatives.types': '{{#label}} must be one of {{#types}}'
+    }
+});
+export default Alternatives;
+//Helpers
+function reportErrors(failures, { error, state }) {
+    //Nothing matched due to type criteria rules
+    if (!failures.length) {
+        return { errors: error('alternatives.any') };
+    }
+    //Single error
+    if (failures.length === 1) {
+        return { errors: failures[0].reports };
+    }
+    //Analyze reasons
+    const valids = new Set();
+    const complex = [];
+    for (const { reports, schema } of failures) {
+        //Multiple errors (!abortEarly)
+        if (reports.length > 1) {
+            return unmatched(failures, error);
+        }
+        //Custom error
+        const report = reports[0];
+        if (report instanceof Errors.Report === false) {
+            return unmatched(failures, error);
+        }
+        //Internal object or array error
+        if (report.state.path.length !== state.path.length) {
+            complex.push({ type: schema.type, report });
+            continue;
+        }
+        //Valids
+        if (report.code === 'any.only') {
+            for (const valid of report.local.valids) {
+                valids.add(valid);
+            }
+            continue;
+        }
+        //Base type
+        const [type, code] = report.code.split('.');
+        if (code !== 'base') {
+            complex.push({ type: schema.type, report });
+        }
+        else if (report.code === 'object.base') {
+            valids.add(report.local.type);
+        }
+        else {
+            valids.add(type);
+        }
+    }
+    //All errors are base types or valids
+    if (!complex.length) {
+        return { errors: error('alternatives.types', { types: [...valids] }) };
+    }
+    //Single complex error
+    if (complex.length === 1) {
+        return { errors: complex[0].report };
+    }
+    return unmatched(failures, error);
+}
+function unmatched(failures, error) {
+    const errors = [];
+    for (const failure of failures) {
+        errors.push(...failure.reports);
+    }
+    return { errors: error('alternatives.match', Errors.details(errors, { override: false })) };
+}

package/dist/esm/lib/validation/engine/schema/types/any.js

@@ -0,0 +1,160 @@
+/**
+ * Derived from the upstream lib/types/any.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+import { assert } from '../assert.js';
+import base from '../base.js';
+import * as Common from '../common.js';
+import * as Messages from '../messages.js';
+function callBuild(obj, method, value) {
+    return (obj[method]).call(obj, value);
+}
+const Any = base.extend({
+    type: 'any',
+    flags: {
+        only: { default: false }
+    },
+    terms: {
+        alterations: { init: null },
+        examples: { init: null },
+        externals: { init: null },
+        metas: { init: [] },
+        notes: { init: [] },
+        shared: { init: null },
+        tags: { init: [] },
+        whens: { init: null }
+    },
+    rules: {
+        allOf: {
+            method(...schemas) {
+                //lakutata's own: the value must also match every schema (a description holds them as a list)
+                if (schemas.length === 1 && Array.isArray(schemas[0]))
+                    schemas = schemas[0];
+                assert(schemas.length > 0, 'Missing schemas');
+                const compiled = schemas.map((schema, i) => Common.tryWithPath(() => this.$_compile(schema), i, { append: true }));
+                const obj = this.$_addRule({ name: 'allOf', args: { schemas: compiled } });
+                for (const schema of compiled)
+                    obj.$_mutateRegister(schema);
+                return obj;
+            },
+            validate(value, { state, prefs, errorsArray }, { schemas }) {
+                for (let i = 0; i < schemas.length; ++i) {
+                    const schema = schemas[i];
+                    const result = schema.$_validate(value, state.nest(schema, `allOf.${i}`), prefs);
+                    if (result.errors) {
+                        //The errors of the schema (the value is kept)
+                        const errors = errorsArray();
+                        errors.push(...result.errors);
+                        return errors;
+                    }
+                }
+                return value;
+            },
+            args: ['schemas'],
+            multi: true
+        },
+        custom: {
+            method(method, description) {
+                assert(typeof method === 'function', 'Method must be a function');
+                assert(description === undefined || description && typeof description === 'string', 'Description must be a non-empty string');
+                return this.$_addRule({ name: 'custom', args: { method, description } });
+            },
+            validate(value, helpers, { method }) {
+                try {
+                    return method(value, helpers);
+                }
+                catch (err) {
+                    return helpers.error('any.custom', { error: err });
+                }
+            },
+            args: ['method', 'description'],
+            multi: true
+        },
+        messages: {
+            method(messages) {
+                return this.prefs({ messages });
+            }
+        },
+        shared: {
+            method(schema) {
+                assert(Common.isSchema(schema) && schema._flags.id, 'Schema must be a schema with an id');
+                const obj = this.clone();
+                obj.$_terms.shared = obj.$_terms.shared || [];
+                obj.$_terms.shared.push(schema);
+                obj.$_mutateRegister(schema);
+                return obj;
+            }
+        },
+        warning: {
+            method(code, local) {
+                assert(code && typeof code === 'string', 'Invalid warning code');
+                return this.$_addRule({ name: 'warning', args: { code, local }, warn: true });
+            },
+            validate(value, helpers, { code, local }) {
+                return helpers.error(code, local);
+            },
+            args: ['code', 'local'],
+            multi: true
+        }
+    },
+    modifiers: {
+        keep(rule, enabled = true) {
+            rule.keep = enabled;
+        },
+        message(rule, message) {
+            rule.message = Messages.compile(message);
+        },
+        warn(rule, enabled = true) {
+            rule.warn = enabled;
+        }
+    },
+    manifest: {
+        build(obj, desc) {
+            for (const key in desc) {
+                const values = desc[key];
+                if (['examples', 'externals', 'metas', 'notes', 'tags'].includes(key)) {
+                    for (const value of values)
+                        obj = callBuild(obj, key.slice(0, -1), value);
+                    continue;
+                }
+                if (key === 'alterations') {
+                    const alter = {};
+                    for (const { target, adjuster } of values)
+                        alter[target] = adjuster;
+                    obj = obj.alter(alter);
+                    continue;
+                }
+                if (key === 'whens') {
+                    for (const value of values) {
+                        const { ref, is, not, then, otherwise, concat } = value;
+                        if (concat) {
+                            obj = obj.concat(concat);
+                        }
+                        else if (ref) {
+                            obj = obj.when(ref, { is, not, then, otherwise, switch: value.switch, break: value.break });
+                        }
+                        else {
+                            obj = obj.when(is, { then, otherwise, break: value.break });
+                        }
+                    }
+                    continue;
+                }
+                if (key === 'shared') {
+                    for (const value of values)
+                        obj = obj.shared(value);
+                }
+            }
+            return obj;
+        }
+    },
+    messages: {
+        'any.custom': '{{#label}} failed custom validation because {{#error.message}}',
+        'any.default': '{{#label}} threw an error when running default method',
+        'any.failover': '{{#label}} threw an error when running failover method',
+        'any.invalid': '{{#label}} contains an invalid value',
+        'any.only': '{{#label}} must be {if(#valids.length == 1, "", "one of ")}{{#valids}}',
+        'any.ref': '{{#label}} {{#arg}} references {{:#ref}} which {{#reason}}',
+        'any.required': '{{#label}} is required',
+        'any.unknown': '{{#label}} is not allowed'
+    }
+});
+export default Any;