@peter.prib/renderengine 0.2.5 → 0.2.7

package/src/charting/datamodel/DataModel.js

@@ -0,0 +1,645 @@
+import { DataModelPerspective } from './DataModelPerspective.js';
+import { DataModelContext } from './DataModelContext.js';
+import { DataType } from './DataType.js';
+import './EnumerationType.js';
+import './StructuredType.js';
+import { LevelSchema } from './LevelSchema.js';
+import { LevelMapping } from './LevelMapping.js';
+import { NodeGeometry } from '../diagrams/NodeGeometry.js';
+import { ModelComparison } from '../diagramModel/ModelComparison.js';
+import { DataModelChecker } from './DataModelChecker.js';
+import { CommandHistory } from '../CommandHistory.js';
+import { MergeModelCommand } from '../diagramModel/MergeModelCommand.js';
+import { ServiceLandscape } from './ServiceLandscape.js';
+import {
+    LevelEntitiesCompared, LevelRelationshipsCompared, MappingsCompared, ContextsCompared, PerspectivesCompared, DataTypesCompared,
+} from './DataModelCompared.js';
+
+/** The levels, outermost first: each realised by the next. */
+const LEVELS = Object.freeze(['conceptual', 'logical', 'physical']);
+
+/**
+ * DataModel — a data model read many ways. Its structure is three levels, each
+ * its own schema (LevelSchema: conceptual concepts, logical entities, physical
+ * tables, with their relationships), joined by mappings (LevelMapping:
+ * conceptual → logical, logical → physical, any number either way). A
+ * perspective (DataModelPerspective) is a stakeholder's viewpoint on the
+ * concepts; a context (DataModelContext) their meaning, scope and constraints.
+ * Perspective → context → schema: `view({ perspective, context, level })`
+ * gives what to draw at a level, or ('mapping') how the levels map; the
+ * schema is left as it is.
+ *
+ * The older form, one entity per thing with each level's detail on it
+ * (`{ entities, relationships }`, as dataModelDiagram takes them), is read as
+ * three levels mapped one to one.
+ *
+ * It knows whether it changed since it was saved (`edited()`, `markSaved()`,
+ * `isDirty()`, `onEdit(fn)`), as a ViewSetModel does, so a part can show it,
+ * keep it and ask before it is lost.
+ */
+export class DataModel {
+    /** The levels, outermost first. */
+    static LEVELS = LEVELS;
+
+    /** The view of how the levels map (a `level` for view()). */
+    static MAPPING = 'mapping';
+
+    /** The view of its service domains in their business areas and domains (a `level` for view()). */
+    static LANDSCAPE = 'landscape';
+
+    /** The view of its data types (a `level` for view()). */
+    static DATA_TYPES = 'datatypes';
+
+    /** How many data type boxes side by side in the data types view, and how far apart. */
+    static DATA_TYPE_COLUMNS = 4;
+    static DATA_TYPE_SPACING = { x: 260, gap: 40 };
+
+    /**
+     * The views that are no level of the schema, each one way to read the
+     * whole model: its name (a `level` for view()), label and description,
+     * whether a model has it to show (`offered`), whether a box dragged in it
+     * keeps its place (`keepsPlaces`), and what it draws.
+     */
+    static OTHER_VIEWS = Object.freeze([
+        Object.freeze({
+            name: 'mapping', label: 'Mapping', description: 'The levels side by side, joined where one realises another',
+            offered: () => true, keepsPlaces: true,
+            view: (model, choice) => model.mappingView(choice),
+        }),
+        Object.freeze({
+            name: 'datatypes', label: 'Data types', description: 'Its data types: enumerations with their values, structures with their fields',
+            offered: (model) => model.dataTypes.length > 0, keepsPlaces: false,
+            view: (model) => model.dataTypesView(),
+        }),
+        Object.freeze({
+            name: 'landscape', label: 'Service landscape', description: 'The service domains in their business areas and business domains (BIAN)',
+            offered: (model) => model.serviceDomains().length > 0, keepsPlaces: false,
+            view: (model) => ServiceLandscape.view(model.serviceDomains()),
+        }),
+    ]);
+
+    /** One of OTHER_VIEWS by name, or null for a level of the schema. */
+    static otherView(name) {
+        return DataModel.OTHER_VIEWS.find(v => v.name === name) ?? null;
+    }
+
+    /** The room between the mapping view's columns, and between the boxes in one. */
+    static MAPPING_COLUMN = 380;
+    static MAPPING_GAP = 40;
+
+    /** How far below the lowest box notes with no place of their own sit, and how far apart. */
+    static NOTE_ROW = 200;
+    static NOTE_SPACING = 220;
+
+    /**
+     * @param {Object} spec
+     * @param {Object<string, {entities, relationships}>} [spec.levels] - Each level's schema
+     * @param {Array<Object|LevelMapping>} [spec.mappings] - Conceptual → logical, logical → physical
+     * @param {Object<string, {x, y}>} [spec.mappingLayout] - Where the mapping view's boxes are, by 'level:id'
+     * @param {Object<string, Object<string, {x, y}>>} [spec.noteLayout] - Where a rule's note is on a level, by level then rule id
+     *   (the conceptual level's is the rule's own x, y)
+     * @param {Array<Object|DataModelPerspective>} [spec.perspectives]
+     * @param {Array<Object|DataModelContext>} [spec.contexts]
+     * @param {Array<Object|DataType>} [spec.dataTypes] - Its data types (DataType and its kinds)
+     * @param {Array<Object>} [spec.entities] - The older, one-entity form (levelsFromCombined)
+     * @param {Array<Object>} [spec.relationships]
+     * @param {string} [spec.name] - What the model is called
+     */
+    constructor(spec = {}) {
+        /** What the model is called. */
+        this.name = spec.name ?? '';
+        this._version = 0;
+        this._saved = 0;
+        this._editListeners = [];
+        const { levels, mappings = [], mappingLayout = {}, noteLayout = {} } = spec.levels ? spec : DataModel.levelsFromCombined(spec);
+        this.levels = Object.fromEntries(LEVELS.map(level => [level, new LevelSchema(level, levels?.[level] ?? {})]));
+        this.mappings = LEVELS.slice(1).map((to, i) => {
+            const from = LEVELS[i];
+            const given = mappings.find(m => m.from === from && m.to === to);
+            return given instanceof LevelMapping ? given : new LevelMapping(given ?? { from, to });
+        });
+        this.mappingLayout = { ...mappingLayout };
+        this.noteLayout = Object.fromEntries(Object.entries(noteLayout).map(([level, at]) => [level, { ...at }]));
+        this.perspectives = (spec.perspectives ?? []).map(p => (p instanceof DataModelPerspective ? p : DataModelPerspective.from(p)));
+        this.contexts = (spec.contexts ?? []).map(c => (c instanceof DataModelContext ? c : new DataModelContext(c)));
+        /** Its data types: the types attributes name (`attribute.type`, a data type's id or name). */
+        this.dataTypes = (spec.dataTypes ?? []).map(t => (t instanceof DataType ? t : DataType.from(t)));
+    }
+
+    /**
+     * Levels from the older form: one entity per thing, each level's detail on
+     * it (`entity.logical.attributes`, `entity.physical.tableName`...). Every
+     * entity is a concept, and a logical entity and a table when it has their
+     * detail (or none of either), mapped one to one; every relationship is at
+     * each level between what is there.
+     */
+    static levelsFromCombined({ entities = [], relationships = [] } = {}) {
+        const common = (e) => {
+            const { conceptual, logical, physical, ...rest } = e;
+            return rest;
+        };
+        const at = {
+            conceptual: entities.map(e => common(e)),
+            logical: entities.map(e => ({ ...common(e), attributes: e.logical?.attributes ?? [] })),
+            physical: entities.map(e => ({ ...common(e), name: e.physical?.tableName ?? e.name, attributes: e.physical?.attributes ?? [] })),
+        };
+        const levels = Object.fromEntries(LEVELS.map(level => [level, { entities: at[level], relationships: relationships.map(r => ({ ...r })) }]));
+        const oneToOne = (from, to) => ({ from, to, pairs: entities.map(e => [e.id, e.id]) });
+        return { levels, mappings: [oneToOne('conceptual', 'logical'), oneToOne('logical', 'physical')] };
+    }
+
+    // ===== Compared and merged =====
+
+    /**
+     * What two data models are compared on and merged by, what is needed first:
+     * each level's entities, then each level's relationships, the mappings,
+     * contexts and perspectives.
+     */
+    comparedKinds() {
+        return [
+            ...LEVELS.map(level => new LevelEntitiesCompared(level)),
+            ...LEVELS.map(level => new LevelRelationshipsCompared(level)),
+            new MappingsCompared(),
+            new ContextsCompared(),
+            new DataTypesCompared(),
+            new PerspectivesCompared(),
+        ];
+    }
+
+    /** How this model differs from another (ModelComparison), which can merge the other's into it. */
+    compareWith(other) {
+        return new ModelComparison(this, other);
+    }
+
+    /** Its undo history: a merge is one step on it. */
+    get history() {
+        return (this._history ??= new CommandHistory());
+    }
+
+    // ===== Changed since saved =====
+
+    /** Something changed (a perspective or context, a box or note moved): listeners hear of it. */
+    edited() {
+        this._version++;
+        this._emitEdit();
+    }
+
+    /** This state is the saved one (a file opened or saved). */
+    markSaved() {
+        this._saved = this._version;
+        this._emitEdit();
+    }
+
+    /** Whether it changed since markSaved. */
+    isDirty() {
+        return this._version !== this._saved;
+    }
+
+    /** Call `fn(model)` after every change (and markSaved). Returns an unsubscribe function. */
+    onEdit(fn) {
+        this._editListeners.push(fn);
+        return () => { this._editListeners = this._editListeners.filter(l => l !== fn); };
+    }
+
+    /** @private */
+    _emitEdit() {
+        for (const fn of this._editListeners) fn(this);
+    }
+
+    /** A level's schema (LevelSchema). */
+    level(name) {
+        const schema = this.levels[name];
+        if (!schema) throw new Error(`Unknown level: "${name}"`);
+        return schema;
+    }
+
+    /** The mapping from one level to the next (LevelMapping). */
+    mapping(from, to) {
+        return this.mappings.find(m => m.from === from && m.to === to) ?? null;
+    }
+
+    /** The concepts' entities, for perspectives and contexts to name. */
+    get concepts() {
+        return this.level('conceptual').entities;
+    }
+
+    /** The entities at `level` that realise some of `conceptIds` (through the mappings); null for null (every one). */
+    realising(level, conceptIds) {
+        if (!conceptIds) return null;
+        let ids = new Set(conceptIds);
+        for (let i = 1; i <= LEVELS.indexOf(level); i++) {
+            const mapping = this.mapping(LEVELS[i - 1], LEVELS[i]);
+            ids = new Set([...ids].flatMap(id => mapping.targetsOf(id)));
+        }
+        return ids;
+    }
+
+    /** The concepts an entity at `level` realises (itself at the conceptual level). */
+    conceptsOf(level, id) {
+        let ids = new Set([id]);
+        for (let i = LEVELS.indexOf(level); i > 0; i--) {
+            const mapping = this.mapping(LEVELS[i - 1], LEVELS[i]);
+            ids = new Set([...ids].flatMap(x => mapping.sourcesOf(x)));
+        }
+        return [...ids];
+    }
+
+    /** The perspectives (service domains) that own a business object (a logical entity). */
+    ownersOf(entityId) {
+        return this.perspectives.filter(p => p.ownedEntities().includes(entityId));
+    }
+
+    /** The checks this model is held to (DataModelChecker): ownership, service domains, mappings. */
+    checker() {
+        return new DataModelChecker(this);
+    }
+
+    /** A perspective by id, or null (the whole schema). */
+    perspective(id) {
+        return this.perspectives.find(p => p.id === id) ?? null;
+    }
+
+    /** A context by id, or null (the schema's own descriptions). */
+    context(id) {
+        return this.contexts.find(c => c.id === id) ?? null;
+    }
+
+    /**
+     * What to draw for a perspective read in a context (either may be null) at
+     * a level ('conceptual', 'logical', 'physical'; 'mapping': mappingView).
+     * Entities: those realising the concepts the perspective shows (the
+     * concepts themselves under its names), each with its level's detail for
+     * dataModelDiagram (`entity[level]`), meaning what the context says of its
+     * concepts, and `details` (shown on hover): the schema entity behind a
+     * renamed concept, the concepts a logical entity or table realises, the
+     * context and the rules on them. Relationships: the level's, between shown
+     * entities. Annotations: the context's rules, each a note on what realises
+     * the concepts it applies to. Links: none (mappingView has them).
+     * @param {{perspective?: string|null, context?: string|null, level?: string}} [choice]
+     * @returns {{entities, relationships, annotations, links}}
+     */
+    view({ perspective = null, context = null, level = 'conceptual' } = {}) {
+        const other = DataModel.otherView(level);
+        if (other) return other.view(this, { perspective, context });
+        const lens = this.perspective(perspective);
+        const meaning = this.context(context);
+        const schema = this.level(level);
+        const allowed = this.realising(level, lens ? this.concepts.filter(c => lens.shows(c.id)).map(c => c.id) : null);
+        // A kind of perspective may show more at a level (a service domain: its control record and qualifiers).
+        for (const id of lens?.alsoShows(level) ?? []) allowed?.add(id);
+        const shown = schema.entities.filter(e => !allowed || allowed.has(e.id));
+        const ids = new Set(shown.map(e => e.id));
+        const conceptName = (id) => {
+            const concept = this.level('conceptual').entity(id);
+            return concept ? (lens ? lens.nameOf(concept) : concept.name) : id;
+        };
+        const entities = shown.map(entity => {
+            const concepts = this.conceptsOf(level, entity.id);
+            const name = level === 'conceptual' && lens ? lens.nameOf(entity) : entity.name;
+            const meanings = meaning ? concepts.map(c => meaning.meaningOf(c)).filter(Boolean) : [];
+            const rules = meaning ? [...new Set(concepts.flatMap(c => meaning.constraintsOn(c).map(r => r.text)))] : [];
+            const owners = level === 'logical' ? this.ownersOf(entity.id).map(o => o.name) : [];
+            const typed = this.typedAttributes(entity);
+            const iso = this.iso20022Of(entity);
+            const details = {
+                ...entity.details,
+                ...(owners.length && { 'owned by': owners.join(', ') }),
+                ...(typed.length && { 'data types': typed.map(({ attribute, type }) => `${attribute.name}: ${type.summary()}`) }),
+                ...(iso.length && { 'ISO 20022': iso }),
+                ...(name !== entity.name && { schema: entity.name }),
+                ...(level !== 'conceptual' && concepts.length && { concepts: concepts.map(conceptName).join(', ') }),
+                ...(meaning && { context: meaning.name }),
+                ...(rules.length && { rules }),
+            };
+            const { attributes, ...rest } = entity;
+            const mark = lens?.decorate(entity, level) ?? {};
+            const allDetails = { ...details, ...mark.details };
+            return {
+                ...rest,
+                name,
+                ...(mark.color && { color: mark.color }),
+                description: meanings.length ? meanings.join(' ') : entity.description,
+                ...(level !== 'conceptual' && { [level]: { attributes: attributes ?? [], ...(level === 'physical' && { tableName: entity.name }) } }),
+                ...(Object.keys(allDetails).length && { details: allDetails }),
+            };
+        });
+        const relationships = schema.relationships
+            .filter(r => ids.has(r.source) && ids.has(r.target))
+            .map(r => (lens && level === 'conceptual' ? { ...r, name: lens.relationshipNameOf(r) } : r));
+        const notes = [
+            ...(meaning?.constraints ?? []).map(c => {
+                const on = this.realising(level, c.applies) ?? new Set(c.applies);
+                return { id: c.id, text: c.text, attachTo: [...on].filter(id => ids.has(id)), ...this.notePlace(level, c) };
+            }),
+            ...(lens?.notes(level) ?? []).map(n => ({ ...n, attachTo: n.attachTo.filter(id => ids.has(id)), ...this.notePlace(level, n) })),
+        ].filter(a => a.attachTo.length);
+        // A note with no place on this level goes in a row below every box, so it covers none.
+        const below = Math.max(0, ...shown.map(e => (Number.isFinite(e.y) ? e.y : 0))) + DataModel.NOTE_ROW;
+        let free = 0;
+        const annotations = notes.map(a => (Number.isFinite(a.x) ? a : { ...a, x: 130 + DataModel.NOTE_SPACING * free++, y: below }));
+        return { entities, relationships, annotations, links: [] };
+    }
+
+    /**
+     * How the levels map: a column per level (conceptual, logical, physical),
+     * each entity the perspective shows drawn at its own level (`level` on it,
+     * its id 'level:id'), and a link for each mapping between shown ones.
+     * A box sits where it was left (`mappingLayout`), else down its column.
+     */
+    mappingView({ perspective = null, context = null } = {}) {
+        const columns = LEVELS.map(level => [level, this.view({ perspective, context, level })]);
+        const entities = columns.flatMap(([level, { entities: shown }], column) => {
+            let y = 60;
+            return shown.map(entity => {
+                const key = `${level}:${entity.id}`;
+                const height = DataModel.boxHeight(level, entity);
+                const place = this.mappingLayout[key] ?? { x: 120 + column * DataModel.MAPPING_COLUMN, y: y + height / 2 };
+                y += height + DataModel.MAPPING_GAP;
+                return { ...entity, id: key, level, x: place.x, y: place.y };
+            });
+        });
+        const shown = new Set(entities.map(e => e.id));
+        const links = this.mappings.flatMap(m => m.pairs
+            .map(([a, b]) => ({ id: `map:${m.from}:${a}->${m.to}:${b}`, source: `${m.from}:${a}`, target: `${m.to}:${b}` }))
+            .filter(l => shown.has(l.source) && shown.has(l.target)));
+        return { entities, relationships: [], annotations: [], links };
+    }
+
+    /** Where a rule's note is on a level: on the conceptual level the rule's own place, else the level's note layout; {} for none. */
+    notePlace(level, constraint) {
+        const at = level === 'conceptual' ? constraint : this.noteLayout[level]?.[constraint.id];
+        return Number.isFinite(at?.x) ? { x: at.x, y: at.y } : {};
+    }
+
+    /** Keep where a rule's note was left on a level (notePlace reads it back). */
+    placeNote(level, constraint, { x, y }) {
+        if (level === 'conceptual') Object.assign(constraint, { x, y });
+        else (this.noteLayout[level] ??= {})[constraint.id] = { x, y };
+    }
+
+    /** How tall an entity's box is at a level (a table grows with its columns), to stack a column. */
+    static boxHeight(level, entity) {
+        const attributes = entity[level]?.attributes ?? [];
+        return attributes.length ? NodeGeometry.tableNodeSize({ columns: attributes }).h : 56;
+    }
+
+    // ===== Perspectives and contexts of one's own =====
+
+    // ===== Data types =====
+
+    /** A data type by its id, else its name (any case), or null. */
+    dataType(ref) {
+        if (!ref) return null;
+        const name = String(ref).toLowerCase();
+        return this.dataTypes.find(t => t.id === ref) ?? this.dataTypes.find(t => t.name.toLowerCase() === name) ?? null;
+    }
+
+    /** An attribute's data type (its `type` naming one), or null for a plain type ('VARCHAR(20)'). */
+    typeOf(attribute) {
+        return this.dataType(attribute?.type);
+    }
+
+    /** An entity's attributes that have a data type: `[{ attribute, type }]`. */
+    typedAttributes(entity) {
+        return (entity.attributes ?? []).map(attribute => ({ attribute, type: this.typeOf(attribute) })).filter(a => a.type);
+    }
+
+    /**
+     * What an entity says of ISO 20022, a line each: its own type, then each
+     * attribute's (its own `iso20022`, else its data type's).
+     */
+    iso20022Of(entity) {
+        return [
+            ...(entity.iso20022 ? [`${entity.name}: ${entity.iso20022}`] : []),
+            ...(entity.attributes ?? []).map(a => [a.name, a.iso20022 || this.typeOf(a)?.iso20022]).filter(([, t]) => t).map(([n, t]) => `${n}: ${t}`),
+        ];
+    }
+
+    /** Where a data type is used: `{ attributes: [{ level, entity, attribute }], types: [DataType] }`. */
+    usesOf(id) {
+        const type = this.dataType(id);
+        if (!type) return { attributes: [], types: [] };
+        const names = (ref) => this.dataType(ref) === type;
+        return {
+            attributes: LEVELS.flatMap(level => this.level(level).entities.flatMap(entity => (entity.attributes ?? [])
+                .filter(a => names(a.type)).map(attribute => ({ level, entity, attribute })))),
+            types: this.dataTypes.filter(t => t !== type && t.uses().some(names)),
+        };
+    }
+
+    /** Add a data type (a DataType spec, its `kind` saying which; an id is made from its name when it has none). */
+    addDataType(spec) {
+        const type = DataType.from({ ...spec, id: spec.id ?? this._freshId(spec.name, this.dataTypes) });
+        this.dataTypes.push(type);
+        this.edited();
+        return type;
+    }
+
+    /** Change a data type (its id and kind stay). */
+    updateDataType(id, spec) {
+        const i = this.dataTypes.findIndex(t => t.id === id);
+        if (i < 0) return null;
+        this.dataTypes[i] = DataType.from({ ...spec, kind: this.dataTypes[i].constructor.kind, id });
+        this.edited();
+        return this.dataTypes[i];
+    }
+
+    removeDataType(id) {
+        this.dataTypes = this.dataTypes.filter(t => t.id !== id);
+        this.edited();
+    }
+
+    /**
+     * The data types view: each a box with a row per value or field (as a
+     * table), enumerations and structures coloured apart, in a grid; a link
+     * from a structure to each data type its fields are.
+     */
+    dataTypesView() {
+        const { x: across, gap } = DataModel.DATA_TYPE_SPACING;
+        const columns = DataModel.DATA_TYPE_COLUMNS;
+        const color = { enumeration: '#fef3c7', structure: '#e0f2fe', type: '#f3f4f6' };
+        const heights = this.dataTypes.map(t => DataModel.boxHeight('datatypes', { datatypes: { attributes: t.rows() } }));
+        const tops = [];
+        this.dataTypes.forEach((t, i) => {
+            const above = i - columns;
+            tops.push(above < 0 ? 60 : tops[above] + heights[above] + gap);
+        });
+        const entities = this.dataTypes.map((t, i) => ({
+            id: `type:${t.id}`, name: `${t.constructor === DataType ? '' : `«${t.constructor.kindLabel.toLowerCase()}» `}${t.name}`,
+            level: 'datatypes', datatypes: { attributes: t.rows().length ? t.rows() : [{ name: t.basedOn || '—' }] },
+            x: 140 + (i % columns) * across, y: tops[i] + heights[i] / 2,
+            color: color[t.constructor.kind] ?? color.type,
+            description: t.description,
+            details: { kind: t.constructor.kindLabel, ...(t.iso20022 && { 'ISO 20022': t.iso20022 }), used: this._usedSummary(t) },
+        }));
+        const links = this.dataTypes.flatMap(t => [...new Set(t.uses().map(ref => this.dataType(ref)).filter(u => u && u !== t))]
+            .map(u => ({ id: `uses:${t.id}->${u.id}`, source: `type:${t.id}`, target: `type:${u.id}` })));
+        return { entities, relationships: [], annotations: [], links, notation: 'crowsfoot' };
+    }
+
+    /** Where a data type is used, in a few words. @private */
+    _usedSummary(type) {
+        const { attributes, types } = this.usesOf(type.id);
+        const parts = [
+            ...(attributes.length ? [`${attributes.length} attribute${attributes.length === 1 ? '' : 's'}`] : []),
+            ...(types.length ? [`by ${types.map(t => t.name).join(', ')}`] : []),
+        ];
+        return parts.join('; ') || 'nowhere';
+    }
+
+    /** Its service domains (the perspectives that are ServiceDomains). */
+    serviceDomains() {
+        return this.perspectives.filter(p => p.constructor.kind === 'service-domain');
+    }
+
+    /**
+     * Service domains read from elsewhere (BianLandscapeReader), as one undo
+     * step (bringCommand). Null when there is nothing to bring.
+     * @param {Array<Object>} specs - ServiceDomain specs
+     * @param {string} [source] - Where they were read from, for the undo label
+     * @returns {MergeModelCommand|null}
+     */
+    serviceDomainsCommand(specs, source = 'a service landscape') {
+        return this.bringCommand({ serviceDomains: specs },
+            `Read ${specs.length} service domain${specs.length === 1 ? '' : 's'} from ${source}`);
+    }
+
+    /**
+     * Things read from elsewhere (a BIAN landscape, a BIAN semantic API)
+     * brought in as one undo step (a MergeModelCommand). A logical entity
+     * already here (by id, else by name) stays as it is, and what was read
+     * refers to it; so does a data type already here by name. Only the data
+     * types what is brought needs come (those its new entities' attributes
+     * are, and theirs in turn). A service domain already here (by id, else by
+     * name) keeps all it has, taking its business area and domain from what
+     * was read, its asset, pattern and control record where it has none, and
+     * the behaviour qualifiers it lacks (by name or entity); one that would
+     * come out the same is left alone. Null when there is nothing to bring.
+     * @param {Object} read
+     * @param {Array<Object>} [read.entities] - Logical entities
+     * @param {Array<Object>} [read.relationships] - Logical relationships between them
+     * @param {Array<Object>} [read.dataTypes] - DataType specs
+     * @param {Array<Object>} [read.serviceDomains] - ServiceDomain specs
+     * @param {string} label - The undo label
+     * @returns {MergeModelCommand|null}
+     */
+    bringCommand({ entities = [], relationships = [], dataTypes = [], serviceDomains = [] }, label) {
+        const logical = this.level('logical');
+        const sameName = (list, name) => list.find(x => String(x.name).toLowerCase() === String(name).toLowerCase());
+        // What was read refers to an entity already here by that one's id.
+        const idHere = new Map(entities.map(e => [e.id, (logical.entity(e.id) ?? sameName(logical.entities, e.name))?.id ?? null]));
+        const as = (id) => idHere.get(id) ?? id;
+        const newEntities = entities.filter(e => !idHere.get(e.id));
+        const newRelationships = relationships.map(r => ({ ...r, source: as(r.source), target: as(r.target) }))
+            .filter(r => !logical.relationships.some(h => h.source === r.source && h.target === r.target && (h.name ?? '') === (r.name ?? '')));
+        // The data types the new entities need, then the ones those need; none already here by id or name.
+        const readType = (ref) => dataTypes.find(t => t.id === ref) ?? sameName(dataTypes, ref);
+        const needed = new Set();
+        const need = (ref) => {
+            const t = readType(ref);
+            if (!t || needed.has(t) || this.dataType(t.id) || sameName(this.dataTypes, t.name)) return;
+            needed.add(t);
+            DataType.from(t).uses().forEach(need);
+        };
+        newEntities.flatMap(e => e.attributes ?? []).forEach(a => need(a.type));
+        const newTypes = dataTypes.filter(t => needed.has(t));
+        const domains = serviceDomains.map(spec => {
+            const read = { ...spec, controlRecord: spec.controlRecord ? as(spec.controlRecord) : spec.controlRecord, qualifiers: (spec.qualifiers ?? []).map(q => ({ ...q, ...(q.entity && { entity: as(q.entity) }) })) };
+            const here = this.perspective(read.id) ?? this.perspectives.find(p => p.name.toLowerCase() === String(read.name).toLowerCase());
+            if (!here) return read;
+            const kept = here.toJSON();
+            return {
+                ...kept, kind: read.kind,
+                businessArea: read.businessArea || kept.businessArea || '', businessDomain: read.businessDomain || kept.businessDomain || '',
+                asset: kept.asset || read.asset || '', pattern: here.functionalPattern ? kept.pattern : (read.pattern || kept.pattern || ''),
+                controlRecord: kept.controlRecord || read.controlRecord || null,
+                qualifiers: [...kept.qualifiers, ...read.qualifiers.filter(q => !kept.qualifiers.some(k =>
+                    k.name.toLowerCase() === String(q.name).toLowerCase() || (q.entity && k.entity === q.entity)))],
+            };
+        }).filter(spec => {
+            // One here that would come out the same is nothing to bring.
+            const here = this.perspective(spec.id);
+            return !here || JSON.stringify(DataModelPerspective.from(spec).toJSON()) !== JSON.stringify(here.toJSON());
+        });
+        if (!newEntities.length && !newRelationships.length && !newTypes.length && !domains.length) return null;
+        const from = new DataModel({
+            name: label,
+            levels: { logical: { entities: newEntities, relationships: newRelationships } },
+            dataTypes: newTypes, perspectives: domains,
+        });
+        const kinds = new Map(this.comparedKinds().map(k => [k.key, k]));
+        const steps = [
+            ...from.level('logical').entities.map(item => ({ kind: kinds.get('logical-entity'), item })),
+            ...from.level('logical').relationships.map(item => ({ kind: kinds.get('logical-relationship'), item })),
+            ...from.dataTypes.map(item => ({ kind: kinds.get('data-type'), item })),
+            ...from.perspectives.map(item => ({ kind: kinds.get('perspective'), item })),
+        ];
+        return new MergeModelCommand(this, from, steps, label);
+    }
+
+    /** Add a perspective (DataModelPerspective spec; an id is made from its name when it has none). */
+    addPerspective(spec) {
+        const perspective = DataModelPerspective.from({ ...spec, id: spec.id ?? this._freshId(spec.name, this.perspectives) });
+        this.perspectives.push(perspective);
+        this.edited();
+        return perspective;
+    }
+
+    /** Change a perspective (its id stays). */
+    updatePerspective(id, spec) {
+        const i = this.perspectives.findIndex(p => p.id === id);
+        if (i < 0) return null;
+        this.perspectives[i] = DataModelPerspective.from({ kind: this.perspectives[i].constructor.kind, ...spec, id });
+        this.edited();
+        return this.perspectives[i];
+    }
+
+    removePerspective(id) {
+        this.perspectives = this.perspectives.filter(p => p.id !== id);
+        this.edited();
+    }
+
+    /** Add a context (DataModelContext spec; an id is made from its name when it has none). */
+    addContext(spec) {
+        const context = new DataModelContext({ ...spec, id: spec.id ?? this._freshId(spec.name, this.contexts) });
+        this.contexts.push(context);
+        this.edited();
+        return context;
+    }
+
+    /** Change a context (its id stays). */
+    updateContext(id, spec) {
+        const i = this.contexts.findIndex(c => c.id === id);
+        if (i < 0) return null;
+        this.contexts[i] = new DataModelContext({ ...spec, id });
+        this.edited();
+        return this.contexts[i];
+    }
+
+    /** Remove a context; a perspective read in it is then read in none. */
+    removeContext(id) {
+        this.contexts = this.contexts.filter(c => c.id !== id);
+        for (const p of this.perspectives) if (p.context === id) p.context = null;
+        this.edited();
+    }
+
+    /** An id from a name, not yet among `taken`. @private */
+    _freshId(name, taken) {
+        const base = String(name ?? 'item').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'item';
+        let id = base;
+        for (let n = 2; taken.some(t => t.id === id); n++) id = `${base}-${n}`;
+        return id;
+    }
+
+    toJSON() {
+        return {
+            name: this.name,
+            levels: Object.fromEntries(LEVELS.map(level => [level, this.level(level).toJSON()])),
+            mappings: this.mappings.map(m => m.toJSON()),
+            mappingLayout: { ...this.mappingLayout },
+            noteLayout: Object.fromEntries(Object.entries(this.noteLayout).map(([level, at]) => [level, { ...at }])),
+            perspectives: this.perspectives.map(p => p.toJSON()), contexts: this.contexts.map(c => c.toJSON()),
+            ...(this.dataTypes.length && { dataTypes: this.dataTypes.map(t => t.toJSON()) }),
+        };
+    }
+}