@lakutata/core 1.0.60 → 3.0.0-beta.0

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

@@ -0,0 +1,280 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Store = exports.Tracer = void 0;
+exports.setup = setup;
+exports.location = location;
+/**
+ * Derived from the upstream lib/trace.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+const index_js_1 = require("../utils/index.js");
+const index_js_2 = require("../location/index.js");
+const Errors = __importStar(require("./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
+ */
+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
+ */
+function location(schema) {
+    //base.tracer(), caller
+    return schema.$_setFlag('_tracerLocation', (0, index_js_2.location)(2));
+}
+/**
+ * Collects the coverage of the traced schemas
+ */
+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 || (0, index_js_2.location)(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;
+    }
+}
+exports.Tracer = Tracer;
+/**
+ * The coverage store of a registered schema, recording the validations of its sub schemas
+ */
+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 || (0, index_js_1.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);
+    }
+}
+exports.Store = Store;
+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 ((0, index_js_1.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/cjs/lib/validation/engine/schema/types/alternatives.d.ts

@@ -0,0 +1,36 @@
+import type { Base, SchemaTerms } from '../base.js';
+import * as Compile from '../compile.js';
+import * as Ref from '../ref.js';
+import { type AnySchema, type AnyTerms } from './any.js';
+/**
+ * The match modes of an alternatives schema
+ */
+export type AlternativesMatchMode = 'any' | 'one' | 'all' | 'none';
+/**
+ * An item of the matches term: an alternative schema, a condition, or a switch statement
+ */
+export interface AlternativesMatch {
+    schema?: Base;
+    ref?: Ref.Ref;
+    is?: Base;
+    then?: Base;
+    otherwise?: Base;
+    switch?: Compile.WhenCase[];
+}
+/**
+ * The terms of an alternatives schema
+ */
+export interface AlternativesTerms {
+    matches: AlternativesMatch[];
+}
+/**
+ * The alternatives schema: matches any (or one, or all) of the alternative schemas, or the conditions
+ */
+export interface AlternativesSchema extends AnySchema {
+    $_terms: SchemaTerms & AnyTerms & AlternativesTerms;
+    conditional(condition: unknown, options: Compile.WhenOptions | Compile.WhenSwitchCase[]): this;
+    match(mode: AlternativesMatchMode): this;
+    try(...schemas: unknown[]): this;
+}
+declare const Alternatives: AlternativesSchema;
+export default Alternatives;

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

@@ -0,0 +1,332 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Derived from the upstream lib/types/alternatives.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+const index_js_1 = require("../../utils/index.js");
+const assert_js_1 = require("../assert.js");
+const Common = __importStar(require("../common.js"));
+const Compile = __importStar(require("../compile.js"));
+const Errors = __importStar(require("../errors.js"));
+const Ref = __importStar(require("../ref.js"));
+const any_js_1 = __importDefault(require("./any.js"));
+const Alternatives = any_js_1.default.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) => (0, index_js_1.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) {
+                (0, assert_js_1.assert)(!this._flags._endedSwitch, 'Unreachable condition');
+                (0, assert_js_1.assert)(!this._flags.match, 'Cannot combine match mode', this._flags.match, 'with conditional rule');
+                (0, assert_js_1.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) {
+                (0, assert_js_1.assert)(['any', 'one', 'all', 'none'].includes(mode), 'Invalid alternatives match mode', mode);
+                if (mode !== 'any') {
+                    for (const match of this.$_terms.matches) {
+                        (0, assert_js_1.assert)(match.schema, 'Cannot combine match mode', mode, 'with conditional rules');
+                    }
+                }
+                return this.$_setFlag('match', mode);
+            }
+        },
+        try: {
+            method(...schemas) {
+                (0, assert_js_1.assert)(schemas.length, 'Missing alternative schemas');
+                Common.verifyFlat(schemas, 'try');
+                (0, assert_js_1.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}}'
+    }
+});
+exports.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/cjs/lib/validation/engine/schema/types/any.d.ts

@@ -0,0 +1,37 @@
+import { type AlterationTerm, type Base, type SchemaTerms, type WhenTerm } from '../base.js';
+import type { ReportLocal } from '../errors.js';
+import * as Messages from '../messages.js';
+import type { ValidationHelpers } from '../model.js';
+/**
+ * A custom rule method: the validated (or converted) value, or an error
+ */
+export type CustomMethod = (value: unknown, helpers: ValidationHelpers) => unknown;
+/**
+ * The terms of any schema
+ */
+export interface AnyTerms {
+    alterations: AlterationTerm[] | null;
+    examples: unknown[] | null;
+    externals: unknown[] | null;
+    metas: unknown[];
+    notes: string[];
+    shared: Base[] | null;
+    tags: string[];
+    whens: WhenTerm[] | null;
+}
+/**
+ * The any schema: Base with the rules and modifiers shared by all the types
+ */
+export interface AnySchema extends Base {
+    $_terms: SchemaTerms & AnyTerms;
+    allOf(...schemas: unknown[]): this;
+    custom(method: CustomMethod, description?: string): this;
+    messages(messages: Messages.MessagesInput): this;
+    shared(schema: Base): this;
+    warning(code: string, local?: ReportLocal): this;
+    keep(enabled?: boolean): this;
+    message(message: Messages.MessagesInput): this;
+    warn(enabled?: boolean): this;
+}
+declare const Any: AnySchema;
+export default Any;