@peter.prib/renderengine 0.2.5 → 0.2.6

package/src/charting/datamodel/DataModel.js

@@ -0,0 +1,299 @@
+import { DataModelPerspective } from './DataModelPerspective.js';
+import { DataModelContext } from './DataModelContext.js';
+import { LevelSchema } from './LevelSchema.js';
+import { LevelMapping } from './LevelMapping.js';
+import { NodeGeometry } from '../diagrams/NodeGeometry.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.
+ */
+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 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>} [spec.entities] - The older, one-entity form (levelsFromCombined)
+     * @param {Array<Object>} [spec.relationships]
+     */
+    constructor(spec = {}) {
+        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 : new DataModelPerspective(p)));
+        this.contexts = (spec.contexts ?? []).map(c => (c instanceof DataModelContext ? c : new DataModelContext(c)));
+    }
+
+    /**
+     * 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')] };
+    }
+
+    /** 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];
+    }
+
+    /** 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' } = {}) {
+        if (level === DataModel.MAPPING) return this.mappingView({ 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);
+        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 details = {
+                ...entity.details,
+                ...(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;
+            return {
+                ...rest,
+                name,
+                description: meanings.length ? meanings.join(' ') : entity.description,
+                ...(level !== 'conceptual' && { [level]: { attributes: attributes ?? [], ...(level === 'physical' && { tableName: entity.name }) } }),
+                ...(Object.keys(details).length && { details }),
+            };
+        });
+        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) };
+            })
+            .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 =====
+
+    /** Add a perspective (DataModelPerspective spec; an id is made from its name when it has none). */
+    addPerspective(spec) {
+        const perspective = new DataModelPerspective({ ...spec, id: spec.id ?? this._freshId(spec.name, this.perspectives) });
+        this.perspectives.push(perspective);
+        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;
+        return (this.perspectives[i] = new DataModelPerspective({ ...spec, id }));
+    }
+
+    removePerspective(id) {
+        this.perspectives = this.perspectives.filter(p => p.id !== id);
+    }
+
+    /** 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);
+        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;
+        return (this.contexts[i] = new DataModelContext({ ...spec, id }));
+    }
+
+    /** 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;
+    }
+
+    /** 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 {
+            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()),
+        };
+    }
+}

package/src/charting/datamodel/DataModelContext.js

@@ -0,0 +1,108 @@
+/**
+ * DataModelContext — the semantic environment a data model is read in: what
+ * its entities mean here (`meanings`, by entity id: "Account" in banking is
+ * not "Account" in a CRM), the rules that hold here (`constraints`, each on
+ * some entities), and where and when that applies (`jurisdiction`,
+ * `validFrom`, `validTo`). The schema stays as it is; a context gives it
+ * meaning, scope and constraints.
+ */
+export class DataModelContext {
+    /**
+     * @param {Object} spec
+     * @param {string} spec.id
+     * @param {string} [spec.name]
+     * @param {string} [spec.description]
+     * @param {Object<string, string>} [spec.meanings] - What an entity means here, by entity id
+     * @param {Array<{id?: string, text: string, applies?: string[], x?: number, y?: number}>} [spec.constraints]
+     *   Rules that hold here, each on the entities it `applies` to (drawn as notes attached to them)
+     * @param {string} [spec.jurisdiction]
+     * @param {string} [spec.validFrom] - ISO date
+     * @param {string} [spec.validTo] - ISO date
+     */
+    constructor({ id, name = id, description = '', meanings = {}, constraints = [], jurisdiction = '', validFrom = '', validTo = '' } = {}) {
+        if (!id) throw new TypeError('DataModelContext must have an id');
+        this.id = id;
+        this.name = name;
+        this.description = description;
+        this.meanings = { ...meanings };
+        this.constraints = constraints.map((c, i) => ({ ...c, id: c.id ?? `${id}-rule-${i + 1}`, applies: [...(c.applies ?? [])] }));
+        this.jurisdiction = jurisdiction;
+        this.validFrom = validFrom;
+        this.validTo = validTo;
+    }
+
+    /** What an entity means here, or null (then its schema description holds). */
+    meaningOf(entityId) {
+        return this.meanings[entityId] ?? null;
+    }
+
+    /** The rules that hold here on an entity. */
+    constraintsOn(entityId) {
+        return this.constraints.filter(c => c.applies.includes(entityId));
+    }
+
+    /** Where and when this context applies, in a few words ('AU · from 2024-07-01'), or ''. */
+    get scope() {
+        const when = this.validFrom && this.validTo ? `${this.validFrom} – ${this.validTo}`
+            : this.validFrom ? `from ${this.validFrom}`
+                : this.validTo ? `until ${this.validTo}` : '';
+        return [this.jurisdiction, when].filter(Boolean).join(' · ');
+    }
+
+    /**
+     * The fields of a dialog making or changing a context of `model`
+     * (FormDialog fields): its name, description, jurisdiction and dates, what
+     * each concept means in it, and its rules, one a line: the rule, then
+     * after '|' the concepts it applies to.
+     * @param {DataModel} model
+     * @param {DataModelContext|null} [context] - The one changed; none for a new one
+     */
+    static fields(model, context = null) {
+        const concepts = model.concepts;
+        const nameOf = (id) => model.level('conceptual').entity(id)?.name ?? id;
+        return [
+            { key: 'name', label: 'Name', type: 'text', value: context?.name ?? '' },
+            { key: 'description', label: 'Description', type: 'textarea', rows: 2, value: context?.description ?? '' },
+            { key: 'jurisdiction', label: 'Jurisdiction', type: 'text', value: context?.jurisdiction ?? '' },
+            { key: 'validFrom', label: 'Valid from', type: 'date', value: context?.validFrom ?? '' },
+            { key: 'validTo', label: 'Valid to', type: 'date', value: context?.validTo ?? '' },
+            { type: 'heading', label: 'Means here' },
+            ...concepts.map(c => ({ key: `meaning:${c.id}`, label: c.name, type: 'textarea', rows: 2, value: context?.meanings[c.id] ?? '', placeholder: 'as the schema describes it' })),
+            { type: 'heading', label: 'Rules' },
+            {
+                key: 'rules', label: '', type: 'textarea', rows: 5,
+                value: (context?.constraints ?? []).map(c => `${c.text} | ${c.applies.map(nameOf).join(', ')}`).join('\n'),
+                hint: 'One a line: the rule | the concepts it applies to (by name)',
+            },
+        ];
+    }
+
+    /**
+     * A context's spec from those fields' values. A rule kept from `context`
+     * (the same text) keeps its id and place; a concept is named by name or id.
+     */
+    static specFrom(values, model, context = null) {
+        const concepts = model.concepts;
+        const conceptOf = (word) => concepts.find(c => c.id === word || c.name.toLowerCase() === word.toLowerCase())?.id ?? null;
+        const meanings = Object.fromEntries(concepts.map(c => [c.id, (values[`meaning:${c.id}`] ?? '').trim()]).filter(([, text]) => text));
+        const constraints = String(values.rules ?? '').split('\n').map(line => line.trim()).filter(Boolean).map(line => {
+            const [text, on = ''] = line.split('|').map(part => part.trim());
+            const applies = on.split(',').map(w => w.trim()).filter(Boolean).map(conceptOf).filter(Boolean);
+            const kept = context?.constraints.find(c => c.text === text);
+            return { text, applies, ...(kept && { id: kept.id, ...(Number.isFinite(kept.x) && { x: kept.x, y: kept.y }) }) };
+        });
+        return {
+            name: (values.name ?? '').trim(), description: (values.description ?? '').trim(),
+            jurisdiction: (values.jurisdiction ?? '').trim(), validFrom: values.validFrom ?? '', validTo: values.validTo ?? '',
+            meanings, constraints,
+        };
+    }
+
+    toJSON() {
+        return {
+            id: this.id, name: this.name, description: this.description, meanings: { ...this.meanings },
+            constraints: this.constraints.map(c => ({ ...c, applies: [...c.applies] })),
+            jurisdiction: this.jurisdiction, validFrom: this.validFrom, validTo: this.validTo,
+        };
+    }
+}

package/src/charting/datamodel/DataModelPerspective.js

@@ -0,0 +1,84 @@
+/**
+ * DataModelPerspective — how one stakeholder sees a data model: a lens on the
+ * schema, not another schema. It shows some of the entities (`entities`; all
+ * when unset) under the names that stakeholder uses (`names`: Party is the
+ * Customer, Ledger the Billing), with relationships renamed too
+ * (`relationshipNames`, by relationship id), and names the context it is
+ * usually read in (`context`, a DataModelContext id).
+ */
+export class DataModelPerspective {
+    /**
+     * @param {Object} spec
+     * @param {string} spec.id
+     * @param {string} [spec.name]
+     * @param {string} [spec.description]
+     * @param {string[]|null} [spec.entities] - The entity ids it shows; null: every one
+     * @param {Object<string, string>} [spec.names] - An entity's name here, by entity id
+     * @param {Object<string, string>} [spec.relationshipNames] - A relationship's name here, by relationship id
+     * @param {string|null} [spec.context] - The context it is read in by default
+     */
+    constructor({ id, name = id, description = '', entities = null, names = {}, relationshipNames = {}, context = null } = {}) {
+        if (!id) throw new TypeError('DataModelPerspective must have an id');
+        this.id = id;
+        this.name = name;
+        this.description = description;
+        this.entities = entities ? [...entities] : null;
+        this.names = { ...names };
+        this.relationshipNames = { ...relationshipNames };
+        this.context = context;
+    }
+
+    /** Whether it shows an entity. */
+    shows(entityId) {
+        return !this.entities || this.entities.includes(entityId);
+    }
+
+    /** What an entity is called here: its name in this perspective, else the schema's. */
+    nameOf(entity) {
+        return this.names[entity.id] ?? entity.name;
+    }
+
+    /** What a relationship is called here. */
+    relationshipNameOf(relationship) {
+        return (relationship.id && this.relationshipNames[relationship.id]) ?? relationship.name;
+    }
+
+    /**
+     * The fields of a dialog making or changing a perspective of `model`
+     * (FormDialog fields): its name, description, the context it is read in,
+     * the concepts it shows, and what it calls each.
+     * @param {DataModel} model
+     * @param {DataModelPerspective|null} [perspective] - The one changed; none for a new one
+     */
+    static fields(model, perspective = null) {
+        const concepts = model.concepts;
+        return [
+            { key: 'name', label: 'Name', type: 'text', value: perspective?.name ?? '' },
+            { key: 'description', label: 'Whose view', type: 'textarea', rows: 2, value: perspective?.description ?? '' },
+            { key: 'context', label: 'Read in', type: 'select', value: perspective?.context ?? '', choices: [['', 'No context'], ...model.contexts.map(c => [c.id, c.name])] },
+            { type: 'heading', label: 'Shows' },
+            { key: 'entities', label: '', type: 'checklist', value: perspective?.entities ?? concepts.map(c => c.id), choices: concepts.map(c => [c.id, c.name]) },
+            { type: 'heading', label: 'Called here' },
+            ...concepts.map(c => ({ key: `name:${c.id}`, label: c.name, type: 'text', value: perspective?.names[c.id] ?? '', placeholder: 'as in the schema' })),
+        ];
+    }
+
+    /** A perspective's spec from those fields' values (all shown: `entities` null; names left blank: none). */
+    static specFrom(values, model) {
+        const ids = model.concepts.map(c => c.id);
+        const shown = values.entities ?? ids;
+        const names = Object.fromEntries(ids.map(id => [id, (values[`name:${id}`] ?? '').trim()]).filter(([, name]) => name));
+        return {
+            name: (values.name ?? '').trim(), description: (values.description ?? '').trim(), context: values.context || null,
+            entities: shown.length === ids.length ? null : [...shown], names,
+        };
+    }
+
+    toJSON() {
+        return {
+            id: this.id, name: this.name, description: this.description,
+            entities: this.entities ? [...this.entities] : null,
+            names: { ...this.names }, relationshipNames: { ...this.relationshipNames }, context: this.context,
+        };
+    }
+}

package/src/charting/datamodel/LevelMapping.js

@@ -0,0 +1,38 @@
+/**
+ * LevelMapping — which entities of one level realise which of another
+ * (conceptual → logical, logical → physical): pairs of ids, any number either
+ * way, so one concept may become several logical entities (Party → Person,
+ * Organisation), several one table (Person, Organisation → party), or many
+ * many.
+ */
+export class LevelMapping {
+    /**
+     * @param {{from: string, to: string, pairs?: Array<[string, string]>}} spec
+     *   `from`/`to` levels; each pair [id at `from`, id at `to`]
+     */
+    constructor({ from, to, pairs = [] } = {}) {
+        if (!from || !to) throw new TypeError('LevelMapping needs the levels it maps, from and to');
+        this.from = from;
+        this.to = to;
+        this.pairs = pairs.map(([a, b]) => [a, b]);
+    }
+
+    /** What realises an entity of `from` at `to`. */
+    targetsOf(id) {
+        return this.pairs.filter(([a]) => a === id).map(([, b]) => b);
+    }
+
+    /** What an entity of `to` realises at `from`. */
+    sourcesOf(id) {
+        return this.pairs.filter(([, b]) => b === id).map(([a]) => a);
+    }
+
+    /** Map one more pair (none twice). */
+    add(fromId, toId) {
+        if (!this.pairs.some(([a, b]) => a === fromId && b === toId)) this.pairs.push([fromId, toId]);
+    }
+
+    toJSON() {
+        return { from: this.from, to: this.to, pairs: this.pairs.map(p => [...p]) };
+    }
+}

package/src/charting/datamodel/LevelSchema.js

@@ -0,0 +1,41 @@
+/**
+ * LevelSchema — one level of a data model (conceptual, logical, physical) as
+ * its own structure: its entities (a concept; a logical entity with its
+ * attributes and keys; a table with its columns and types) and the
+ * relationships between them. The levels are not one-to-one: a concept may be
+ * realised by several logical entities, several by one table (LevelMapping
+ * says which).
+ *
+ * An entity: `{ id, name, description?, attributes?, x?, y?, color?, shape?,
+ * labelPosition? }` — `attributes` `[{name, type?, isPK?, isFK?}]` (none at the
+ * conceptual level); a relationship as dataModelDiagram takes it.
+ */
+export class LevelSchema {
+    /**
+     * @param {string} level - 'conceptual', 'logical' or 'physical'
+     * @param {{entities?: Array<Object>, relationships?: Array<Object>}} [spec]
+     */
+    constructor(level, { entities = [], relationships = [] } = {}) {
+        if (!level) throw new TypeError('LevelSchema needs its level');
+        this.level = level;
+        this.entities = entities;
+        this.relationships = relationships;
+    }
+
+    /** An entity by id, or null. */
+    entity(id) {
+        return this.entities.find(e => e.id === id) ?? null;
+    }
+
+    /** Add an entity (its id unique at this level). */
+    addEntity(entity) {
+        if (!entity?.id) throw new TypeError('An entity needs an id');
+        if (this.entity(entity.id)) throw new TypeError(`The ${this.level} level already has "${entity.id}"`);
+        this.entities.push(entity);
+        return entity;
+    }
+
+    toJSON() {
+        return { entities: this.entities, relationships: this.relationships };
+    }
+}

package/src/charting/datamodel/index.js

@@ -0,0 +1,5 @@
+export { DataModel } from './DataModel.js';
+export { DataModelPerspective } from './DataModelPerspective.js';
+export { DataModelContext } from './DataModelContext.js';
+export { LevelSchema } from './LevelSchema.js';
+export { LevelMapping } from './LevelMapping.js';