@yarkivaev/scada 2.3.90 → 2.3.112

package/src/application/deploy/expandNamespace.js

@@ -0,0 +1,193 @@
+/**
+ * Rejects a patch that names one id twice.
+ *
+ * @param {object[]} patch - patch entries
+ * @returns {void}
+ * @example
+ *   repeated([{ id: 'voltage' }]);
+ */
+function repeated(patch) {
+    const ids = patch.map((entry) => {
+        return entry.id;
+    });
+    ids.forEach((id, index) => {
+        if (ids.indexOf(id) !== index) {
+            throw new Error(`system document patch repeats ${id}`);
+        }
+    });
+}
+
+/**
+ * Copies patch fields onto one staying node.
+ *
+ * @param {object} node - template node
+ * @param {object} entry - patch entry
+ * @param {object} templates - reusable node lists
+ * @param {Function} apply - patch function
+ * @param {Function} expand - node function
+ * @returns {object} patched node
+ * @example
+ *   revise({ id: 'electrical' }, { id: 'electrical' }, {}, () => { return []; }, () => { return {}; });
+ */
+function revise(node, entry, templates, apply, expand) {
+    const extra = {};
+    Object.keys(entry).forEach((key) => {
+        if (key !== 'enabled' && key !== 'id' && key !== 'nodes' && key !== 'template') {
+            extra[key] = entry[key];
+        }
+    });
+    const merged = { ...node, ...extra, id: node.id };
+    if (entry.nodes) {
+        merged.nodes = apply(node.nodes || [], entry.nodes, templates, expand);
+    }
+    if (!merged.nodes || merged.nodes.length === 0) {
+        delete merged.nodes;
+    }
+    return merged;
+}
+
+/**
+ * Applies one patch entry to an expanded child list.
+ *
+ * @param {object[]} current - children so far
+ * @param {object} entry - one patch entry
+ * @param {object} templates - reusable node lists
+ * @param {Function} apply - patch function
+ * @param {Function} expand - node function
+ * @returns {object[]} next children
+ * @example
+ *   mergeOne([{ id: 'step' }], { enabled: false, id: 'step' }, {}, () => { return []; }, () => { return {}; });
+ */
+function mergeOne(current, entry, templates, apply, expand) {
+    const index = current.findIndex((node) => {
+        return node.id === entry.id;
+    });
+    if (index < 0) {
+        if (entry.enabled === false) {
+            return current;
+        }
+        return current.concat([expand(entry, templates)]);
+    }
+    if (entry.enabled === false) {
+        return current.filter((node) => {
+            return node.id !== entry.id;
+        });
+    }
+    const next = current.slice();
+    next[index] = revise(current[index], entry, templates, apply, expand);
+    return next;
+}
+
+/**
+ * Patches a template child list.
+ *
+ * An id the template lacks is added. An id the patch disables is removed.
+ * A staying entry may patch those children the same way.
+ *
+ * @param {object[]} seeded - template children
+ * @param {object[]} patch - node patch
+ * @param {object} templates - reusable node lists
+ * @param {Function} expand - node function
+ * @returns {object[]} patched children
+ * @example
+ *   applyPatch([{ id: 'step' }], [{ enabled: false, id: 'step' }], {}, () => { return {}; });
+ */
+function applyPatch(seeded, patch, templates, expand) {
+    repeated(patch);
+    return patch.reduce((current, entry) => {
+        return mergeOne(current, entry, templates, applyPatch, expand);
+    }, seeded);
+}
+
+/**
+ * Expands the children of one namespace node.
+ *
+ * @param {object} node - namespace node
+ * @param {object} templates - reusable node lists
+ * @param {Function} expand - node function
+ * @returns {object[]} expanded children
+ * @example
+ *   childrenOf({ id: 'unit', template: 'unit' }, { unit: [] }, () => { return {}; });
+ */
+function childrenOf(node, templates, expand) {
+    if (!node.template) {
+        return (node.nodes || []).map((child) => {
+            return expand(child, templates);
+        });
+    }
+    const base = templates[node.template];
+    if (!Array.isArray(base)) {
+        throw new Error(`system document has no template ${node.template}`);
+    }
+    const seeded = base.map((child) => {
+        return expand(child, templates);
+    });
+    return applyPatch(seeded, node.nodes || [], templates, expand);
+}
+
+/**
+ * Expands one namespace node, applying its template and patch.
+ *
+ * @param {object} node - namespace node
+ * @param {object} templates - reusable node lists
+ * @returns {object} expanded node
+ * @example
+ *   expandNode({ id: 'mill' }, {});
+ */
+function expandNode(node, templates) {
+    if (!node || typeof node.id !== 'string' || node.id.length === 0) {
+        throw new Error('system document namespace id is empty');
+    }
+    const nodes = childrenOf(node, templates, expandNode);
+    const copy = { id: node.id };
+    Object.keys(node).forEach((key) => {
+        if (key !== 'enabled' && key !== 'id' && key !== 'nodes' && key !== 'template') {
+            copy[key] = node[key];
+        }
+    });
+    if (nodes.length > 0) {
+        copy.nodes = nodes;
+    }
+    return copy;
+}
+
+/**
+ * Expands a namespace tree.
+ *
+ * @param {object[]|undefined} nodes - root nodes
+ * @param {object} templates - reusable node lists
+ * @returns {object[]} expanded roots
+ * @example
+ *   expandTree([{ id: 'mill' }], {});
+ */
+export function expandTree(nodes, templates) {
+    return (nodes || []).map((node) => {
+        return expandNode(node, templates);
+    });
+}
+
+/**
+ * Lists every node path from the root.
+ *
+ * @param {object[]|undefined} nodes - sibling nodes
+ * @param {string} [prefix] - parent path
+ * @returns {string[]} paths
+ * @example
+ *   treePaths([{ id: 'mill', nodes: [{ id: 'hall' }] }]);
+ */
+export function treePaths(nodes, prefix = '') {
+    const found = [];
+    (nodes || []).forEach((node) => {
+        const path = prefix.length > 0 ? `${prefix}/${node.id}` : node.id;
+        if (path.split('/').some((part) => {
+            return part.length === 0;
+        })) {
+            throw new Error(`system document path ${path} has an empty segment`);
+        }
+        found.push(path);
+        treePaths(node.nodes, path).forEach((child) => {
+            found.push(child);
+        });
+    });
+    return found;
+}

package/src/application/deploy/expandPattern.js

@@ -0,0 +1,207 @@
+/**
+ * Reports whether a token is a device address.
+ *
+ * @param {string} value - flow source
+ * @returns {boolean} true when the token carries a scheme
+ * @example
+ *   isAddress('modbus://192.0.2.10:502');
+ */
+export function isAddress(value) {
+    return typeof value === 'string' && value.includes('://');
+}
+
+/**
+ * Rejects an empty path segment.
+ *
+ * @param {string} path - path or pattern
+ * @returns {void}
+ * @example
+ *   assertSegments('mill/hall');
+ */
+function assertSegments(path) {
+    if (path.split('/').some((part) => {
+        return part.length === 0;
+    })) {
+        throw new Error(`system document path ${path} has an empty segment`);
+    }
+}
+
+/**
+ * Lists brace groups in one path.
+ *
+ * @param {string} text - path text
+ * @returns {{body: string, end: number, start: number}[]} groups
+ * @example
+ *   groups('mill/{a,b}');
+ */
+function groups(text) {
+    return [...text.matchAll(/\{(?<body>[^{}]*)\}/gu)].map((match) => {
+        return {
+            body: match.groups.body,
+            end: match.index + match[0].length,
+            start: match.index
+        };
+    });
+}
+
+/**
+ * Splits one brace body into segment alternatives.
+ *
+ * @param {string} body - text inside braces
+ * @returns {string[]} alternatives
+ * @example
+ *   alternatives('east,west');
+ */
+function alternatives(body) {
+    const parts = body.split(',').map((part) => {
+        return part.trim();
+    });
+    if (parts.some((part) => {
+        return part.length === 0 || part.includes('/');
+    })) {
+        throw new Error(`system document brace ${body} is not one segment`);
+    }
+    return parts;
+}
+
+/**
+ * Substitutes the index-th alternative of every brace group.
+ *
+ * @param {string} text - original path
+ * @param {{end: number, start: number}[]} marks - brace groups
+ * @param {string[][]} choices - alternatives per group
+ * @param {number} index - shared alternative index
+ * @returns {string} one concrete path
+ * @example
+ *   fill('mill/{a,b}', [], [], 0);
+ */
+function fill(text, marks, choices, index) {
+    let built = '';
+    let cursor = 0;
+    marks.forEach((group, place) => {
+        built += text.slice(cursor, group.start);
+        built += choices[place][index];
+        cursor = group.end;
+    });
+    return built + text.slice(cursor);
+}
+
+/**
+ * Builds one zipped row per shared brace index.
+ *
+ * @param {string} text - original path
+ * @param {{body: string, end: number, start: number}[]} marks - brace groups
+ * @returns {string[]} concrete paths
+ * @example
+ *   rowsFrom('mill/{a,b}/{c,d}', []);
+ */
+function rowsFrom(text, marks) {
+    const choices = marks.map((group) => {
+        return alternatives(group.body);
+    });
+    const count = choices[0].length;
+    if (choices.some((choice) => {
+        return choice.length !== count;
+    })) {
+        throw new Error(`system document braces in ${text} differ in length`);
+    }
+    const rows = [];
+    for (let index = 0; index < count; index += 1) {
+        rows.push(fill(text, marks, choices, index));
+    }
+    return rows;
+}
+
+/**
+ * Expands `{a,b}` groups in one path together.
+ *
+ * A fixed string is returned as a single-element list. Brace groups share an
+ * index, so `{a,b}/{c,d}` becomes `a/c` and `b/d`.
+ *
+ * @param {string} text - path, server id, or address
+ * @returns {string[]} expanded texts
+ * @example
+ *   zipped('mill/{east,west}/{alpha,beta}');
+ */
+export function zipped(text) {
+    const marks = groups(text);
+    if (marks.length === 0) {
+        return [text];
+    }
+    return rowsFrom(text, marks);
+}
+
+/**
+ * Reports whether a value matches a star pattern.
+ *
+ * `*` matches any remainder, including `/`.
+ *
+ * @param {string} pattern - pattern that may contain `*`
+ * @param {string} value - concrete text
+ * @returns {boolean} true when the value fits
+ * @example
+ *   fits('mill/*', 'mill/hall/unit');
+ */
+export function fits(pattern, value) {
+    const body = pattern.split('*').map((part) => {
+        return part.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+    }).join('.*');
+    return new RegExp(`^${body}$`, 'u').test(value);
+}
+
+/**
+ * Collects pool entries that fit one concrete pattern.
+ *
+ * @param {string} item - pattern without braces
+ * @param {string[]} pool - existing values
+ * @param {string} noun - path or server
+ * @param {boolean} strict - whether a miss is an error
+ * @param {string[]} matched - accumulator
+ * @returns {void}
+ * @example
+ *   collect('mill/*', ['mill/hall'], 'path', true, []);
+ */
+function collect(item, pool, noun, strict, matched) {
+    if (item.includes('*')) {
+        pool.forEach((entry) => {
+            if (fits(item, entry) && !matched.includes(entry)) {
+                matched.push(entry);
+            }
+        });
+        return;
+    }
+    if (!pool.includes(item)) {
+        if (strict) {
+            throw new Error(`system document has no ${noun} ${item}`);
+        }
+        return;
+    }
+    if (!matched.includes(item)) {
+        matched.push(item);
+    }
+}
+
+/**
+ * Expands braces and `*` against values that already exist.
+ *
+ * @param {string} pattern - path or server pattern
+ * @param {string[]} pool - existing values
+ * @param {string} noun - path or server
+ * @param {boolean} strict - whether a miss is an error
+ * @returns {string[]} matches
+ * @example
+ *   picked('mill/*', ['mill/hall/unit'], 'path', true);
+ */
+export function picked(pattern, pool, noun, strict) {
+    assertSegments(pattern);
+    const concrete = zipped(pattern);
+    const matched = [];
+    concrete.forEach((item) => {
+        assertSegments(item);
+        collect(item, pool, noun, strict, matched);
+    });
+    if (matched.length === 0 && strict) {
+        throw new Error(`system document has no ${noun} ${pattern}`);
+    }
+    return matched;
+}

package/src/application/deploy/expandProfiles.js

@@ -0,0 +1,70 @@
+/**
+ * Overlays a child profile on its parent.
+ *
+ * The child keeps the parent's modules, command, variables, and apps.
+ * A child app id replaces that one app. A child command replaces the command.
+ *
+ * @param {object} parent - resolved parent profile
+ * @param {object} child - extending profile
+ * @returns {object} merged profile
+ * @example
+ *   overlay({ command: ['node'] }, { extends: 'cell' });
+ */
+function overlay(parent, child) {
+    const merged = {
+        ...parent,
+        ...child,
+        apps: { ...(parent.apps || {}), ...(child.apps || {}) },
+        modules: { ...(parent.modules || {}), ...(child.modules || {}) },
+        variables: { ...(parent.variables || {}), ...(child.variables || {}) }
+    };
+    delete merged.extends;
+    return merged;
+}
+
+/**
+ * Resolves one profile, following `extends`.
+ *
+ * @param {string} name - profile id
+ * @param {object} profiles - declared profiles
+ * @param {object} done - profiles already resolved
+ * @param {string[]} stack - profiles on the current chain
+ * @returns {object} resolved profile
+ * @example
+ *   resolve('cell', { cell: {} }, {}, []);
+ */
+function resolve(name, profiles, done, stack) {
+    if (Object.hasOwn(done, name)) {
+        return done[name];
+    }
+    const profile = profiles[name];
+    if (!profile) {
+        throw new Error(`system document has no profile ${name}`);
+    }
+    if (stack.includes(name)) {
+        throw new Error(`system document profile ${name} extends itself`);
+    }
+    if (!profile.extends) {
+        done[name] = { ...profile };
+        return done[name];
+    }
+    const parent = resolve(profile.extends, profiles, done, stack.concat(name));
+    done[name] = overlay(parent, profile);
+    return done[name];
+}
+
+/**
+ * Merges every profile with the profile it extends.
+ *
+ * @param {object} profiles - declared profiles
+ * @returns {object} profiles with `extends` applied
+ * @example
+ *   expandProfiles({ cell: {}, external: { extends: 'cell' } });
+ */
+export function expandProfiles(profiles) {
+    const done = {};
+    Object.keys(profiles).forEach((name) => {
+        resolve(name, profiles, done, []);
+    });
+    return done;
+}

package/src/application/deploy/frozen.js

@@ -0,0 +1,23 @@
+/**
+ * Deep-freezes a document value.
+ *
+ * @param {unknown} value - any JSON-like value
+ * @returns {unknown} frozen value
+ * @example
+ *   frozen({ id: 'mill' });
+ */
+export default function frozen(value) {
+    if (value === null || typeof value !== 'object' || Object.isFrozen(value)) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return Object.freeze(value.map((item) => {
+            return frozen(item);
+        }));
+    }
+    const copy = {};
+    Object.keys(value).forEach((key) => {
+        copy[key] = frozen(value[key]);
+    });
+    return Object.freeze(copy);
+}

package/src/application/deploy/mergeDocuments.js

@@ -0,0 +1,98 @@
+/**
+ * Reports whether a value is a plain map.
+ *
+ * @param {*} value - candidate
+ * @returns {boolean} true for a non-null object that is not an array
+ * @example
+ *   isMap({ id: 'cell' });
+ */
+function isMap(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Deep-merges two maps. A null value removes that key.
+ *
+ * @param {object|undefined} left - base map
+ * @param {object|undefined} right - overlay
+ * @returns {object} merged map
+ * @example
+ *   mergeMaps({ secret: 'pg' }, { image: 'plant:1' });
+ */
+function mergeMaps(left, right) {
+    const value = { ...(left || {}) };
+    Object.keys(right || {}).forEach((key) => {
+        const next = right[key];
+        if (next === null) {
+            delete value[key];
+            return;
+        }
+        if (isMap(value[key]) && isMap(next)) {
+            value[key] = mergeMaps(value[key], next);
+            return;
+        }
+        value[key] = next;
+    });
+    return value;
+}
+
+/**
+ * Merges namespace trees by node id.
+ *
+ * @param {object[]|undefined} left - base nodes
+ * @param {object[]|undefined} right - overlay nodes
+ * @returns {object[]} merged nodes
+ * @example
+ *   mergeNodes([{ id: 'mill', nodes: [{ id: 'a' }] }], [{ id: 'mill', nodes: [{ id: 'b' }] }]);
+ */
+function mergeNodes(left, right) {
+    const value = new Map();
+    (left || []).forEach((node) => {
+        value.set(node.id, node);
+    });
+    (right || []).forEach((node) => {
+        const prior = value.get(node.id);
+        if (!prior) {
+            value.set(node.id, node);
+            return;
+        }
+        const next = { ...prior, ...node };
+        const nodes = mergeNodes(prior.nodes, node.nodes);
+        if (nodes.length > 0) {
+            next.nodes = nodes;
+        } else {
+            delete next.nodes;
+        }
+        value.set(node.id, next);
+    });
+    return Array.from(value.values());
+}
+
+/**
+ * Overlays one system document on another.
+ *
+ * Maps and namespace trees merge. Listed servers replace. A `null`
+ * app drops that app. Omitted keys stay from the catalog.
+ *
+ * @param {object} base - catalog document
+ * @param {object} extra - contour overlay
+ * @returns {object} combined document
+ * @example
+ *   mergeDocuments({ servers: [{ id: 'cell' }] }, { servers: [{ id: 'lab' }] });
+ */
+export default function mergeDocuments(base, extra) {
+    const document = { ...base, ...extra };
+    if (base.templates || extra.templates) {
+        document.templates = { ...(base.templates || {}), ...(extra.templates || {}) };
+    }
+    if (base.mappings || extra.mappings) {
+        document.mappings = mergeMaps(base.mappings, extra.mappings);
+    }
+    if (base.profiles || extra.profiles) {
+        document.profiles = mergeMaps(base.profiles, extra.profiles);
+    }
+    if (base.namespace || extra.namespace) {
+        document.namespace = mergeNodes(base.namespace, extra.namespace);
+    }
+    return document;
+}

package/src/application/deploy/paths.js

@@ -0,0 +1,86 @@
+/**
+ * Joins a child id onto a parent path.
+ *
+ * @param {string} prefix - parent path
+ * @param {string} id - child id
+ * @returns {string} path
+ * @example
+ *   joined('mill', 'unit');
+ */
+function joined(prefix, id) {
+    if (prefix.length === 0) {
+        return id;
+    }
+    return `${prefix}/${id}`;
+}
+
+/**
+ * Patch entries the template does not already name.
+ *
+ * @param {object[]} base - template children
+ * @param {object[]|undefined} patch - node patch
+ * @returns {object[]} added nodes
+ * @example
+ *   extras([{ id: 'voltage' }], [{ id: 'rotation_on' }]);
+ */
+function extras(base, patch) {
+    return (patch || []).filter((entry) => {
+        return base.every((child) => {
+            return child.id !== entry.id;
+        });
+    });
+}
+
+/**
+ * Children of one namespace node, expanding its template.
+ *
+ * @param {object} node - namespace node
+ * @param {object} templates - reusable node lists
+ * @returns {object[]} children
+ * @example
+ *   children({ id: 'unit', template: 'furnace' }, { furnace: [] });
+ */
+function children(node, templates) {
+    if (!node.template) {
+        return node.nodes || [];
+    }
+    const base = templates[node.template];
+    if (!Array.isArray(base)) {
+        throw new Error(`system document has no template ${node.template}`);
+    }
+    return base.concat(extras(base, node.nodes));
+}
+
+/**
+ * Walks a namespace and records every path.
+ *
+ * @param {object[]|undefined} nodes - sibling nodes
+ * @param {string} prefix - parent path
+ * @param {object} templates - reusable node lists
+ * @param {string[]} found - accumulator
+ * @returns {void}
+ * @example
+ *   walk([{ id: 'mill' }], '', {}, []);
+ */
+function walk(nodes, prefix, templates, found) {
+    (nodes || []).forEach((node) => {
+        const next = joined(prefix, node.id);
+        found.push(next);
+        walk(children(node, templates), next, templates, found);
+    });
+}
+
+/**
+ * Lists namespace paths, expanding templates and added patch ids.
+ *
+ * @example
+ *   paths({ namespace: [{ id: 'mill' }], templates: {} });
+ *
+ * @param {object} document - system document
+ * @returns {string[]} paths from the root
+ */
+export default function paths(document) {
+    const found = [];
+    walk(document.namespace, '', document.templates || {}, found);
+    return found;
+}

package/src/application/deploy/pointPaths.js

@@ -0,0 +1,20 @@
+/**
+ * Document path of each device point in a map.
+ *
+ * A point map key is the parameter. The published name is the flow path
+ * plus that parameter. The device point stays the map value.
+ *
+ * @example
+ *   pointPaths('mill/electrical', { voltage: 'holding:4000:cdab' });
+ *
+ * @param {string} name - flow path
+ * @param {object} mapping - parameter id to device point
+ * @returns {object} device point to document path
+ */
+export default function pointPaths(name, mapping) {
+    const paths = {};
+    Object.keys(mapping || {}).forEach((key) => {
+        paths[String(mapping[key])] = `${name}/${key}`;
+    });
+    return paths;
+}