@peter.prib/renderengine 0.2.7 → 0.2.11

package/src/datamodel.js

@@ -35,7 +35,19 @@
  * the same calibration archimateDiagram's own icons use.
  */
 
-/** One data-modelling abstraction level. See DataModelNotation.levels(). */
+/** Text from a dialog field, trimmed. */
+const text = (v) => String(v ?? '').trim();
+/** Categories as written ('PII, PCI') as a list. */
+const list = (v) => (Array.isArray(v) ? v : String(v ?? '').split(/[,;]/)).map(x => String(x).trim()).filter(Boolean);
+/** Who answers for an entity (DMBOK2's stewardship), in its dialog's order. */
+const STEWARDS = Object.freeze([['owner', 'Business owner'], ['steward', 'Data steward'], ['custodian', 'Technical custodian']]);
+
+/**
+ * One data-modelling abstraction level (see DataModelNotation.levels()): what
+ * it is, and what its entities and relationships hold, as the dialogs that
+ * edit them show it. A level's entity has a name and a definition; a level
+ * whose entities have attributes (AttributedLevel) adds them as a table.
+ */
 export class DataModelLevel {
     constructor(name, description) {
         this.name = name;
@@ -46,6 +58,195 @@ export class DataModelLevel {
     get label() {
         return this.name.charAt(0).toUpperCase() + this.name.slice(1);
     }
+
+    /** What an entity is called at this level ('Concept', 'Entity', 'Table'). */
+    get entityNoun() {
+        return 'Entity';
+    }
+
+    /**
+     * An entity's dialog fields (FormDialog): its name and definition, who
+     * answers for it (business owner, data steward, technical custodian), and
+     * how it is classified (a sensitivity of the model's scheme, categories).
+     * @param {Object|null} entity - null for a new one
+     * @param {Object} [context] - What the fields may offer: `typeNames` (the model's data types),
+     *   `sensitivities` and `categories` (its classification scheme's)
+     */
+    entityFields(entity, context = {}) {
+        const { sensitivities = [], categories = [] } = context;
+        return [
+            { key: 'name', label: 'Name', type: 'text', value: entity?.name ?? '' },
+            { key: 'description', label: 'Definition', type: 'textarea', rows: 3, value: entity?.description ?? '', placeholder: 'What it is, in the business\'s words' },
+            { type: 'heading', label: 'Stewardship' },
+            ...STEWARDS.map(([key, label]) => ({ key: `stewardship.${key}`, label, type: 'text', value: entity?.stewardship?.[key] ?? '' })),
+            { type: 'heading', label: 'Classification' },
+            { key: 'sensitivity', label: 'Sensitivity', type: 'select', value: entity?.sensitivity ?? '', choices: [['', 'Unclassified'], ...sensitivities.map(s => [s, s])] },
+            { key: 'categories', label: 'Categories', type: 'text', value: list(entity?.categories).join(', '), placeholder: categories.join(', ') },
+        ];
+    }
+
+    /** What those fields say, laid over the entity (what they do not show kept; an empty one taken away). */
+    entitySpecFrom(values, entity = null) {
+        const out = { ...(entity ?? {}), name: text(values.name) };
+        const keep = (key, value) => { if (value === '' || (Array.isArray(value) && !value.length)) delete out[key]; else out[key] = value; };
+        keep('description', text(values.description));
+        const stewardship = Object.fromEntries(STEWARDS.map(([key]) => [key, text(values[`stewardship.${key}`])]).filter(([, v]) => v));
+        keep('stewardship', Object.keys(stewardship).length ? stewardship : '');
+        keep('sensitivity', text(values.sensitivity));
+        keep('categories', list(values.categories));
+        return out;
+    }
+
+    /**
+     * A relationship's dialog fields: its two ends (entities at this level),
+     * its name, each end's cardinality, whether it is identifying, a definition.
+     * @param {Array<Object>} entities - The level's entities
+     * @param {Object|null} relationship - null for a new one
+     */
+    relationshipFields(entities, relationship = null) {
+        const ends = entities.map(e => [e.id, e.name]);
+        const cardinalities = DataModelNotation.cardinalities().map(c => [c, c]);
+        return [
+            {
+                key: 'kind', label: 'Kind', type: 'select', value: RelationshipKind.of(relationship).kind,
+                choices: RelationshipKind.all().map(k => [k.kind, k.label]),
+                hint: 'A generalization: From is a subtype of To; its cardinalities are not used',
+            },
+            { key: 'source', label: 'From', type: 'select', value: relationship?.source ?? ends[0]?.[0] ?? '', choices: ends },
+            { key: 'sourceCardinality', label: 'Its cardinality', type: 'select', value: relationship?.sourceCardinality ?? '1', choices: cardinalities },
+            { key: 'name', label: 'Name', type: 'text', value: relationship?.name ?? '', placeholder: 'has, places, is for…' },
+            { key: 'target', label: 'To', type: 'select', value: relationship?.target ?? ends[1]?.[0] ?? ends[0]?.[0] ?? '', choices: ends },
+            { key: 'targetCardinality', label: 'Its cardinality', type: 'select', value: relationship?.targetCardinality ?? '0..*', choices: cardinalities },
+            { key: 'identifying', label: 'Identifying', type: 'checkbox', value: relationship ? relationship.identifying !== false : true },
+            { key: 'complete', label: 'Complete (generalization)', type: 'checkbox', value: !!relationship?.complete },
+            { key: 'disjoint', label: 'Disjoint (generalization)', type: 'checkbox', value: relationship ? relationship.disjoint !== false : true },
+            { key: 'description', label: 'Definition', type: 'textarea', rows: 2, value: relationship?.description ?? '' },
+        ];
+    }
+
+    /** What those fields say, laid over the relationship. */
+    relationshipSpecFrom(values, relationship = null) {
+        const out = {
+            ...(relationship ?? {}),
+            source: values.source, target: values.target, name: text(values.name),
+            sourceCardinality: values.sourceCardinality, targetCardinality: values.targetCardinality,
+        };
+        if (values.identifying) delete out.identifying; else out.identifying = false;
+        if (text(values.description)) out.description = text(values.description); else delete out.description;
+        const kind = RelationshipKind.KINDS.get(values.kind) ?? RelationshipKind.of(relationship);
+        delete out.complete; delete out.disjoint; delete out.kind;
+        if (kind.kind !== AssociationKind.kind) out.kind = kind.kind;
+        if (!kind.hasCardinality) {
+            delete out.sourceCardinality; delete out.targetCardinality; delete out.identifying;
+            out.complete = !!values.complete;
+            out.disjoint = values.disjoint !== false;
+        }
+        return out;
+    }
+}
+
+/**
+ * A level whose entities have attributes (logical attributes, physical
+ * columns): its entity dialog adds them as a table (a FormDialog `rows`
+ * field), a row each: the attribute's name, type, keys, whether it is
+ * required, what a foreign key references, its definition.
+ */
+export class AttributedLevel extends DataModelLevel {
+    /** What its attributes are called ('Attributes', 'Columns'). */
+    get attributeNoun() {
+        return 'Attributes';
+    }
+
+    /** The types its type column suggests. @param {Object} context */
+    typeSuggestions(context) {
+        return [];
+    }
+
+    /** The attribute table's columns. */
+    attributeColumns(context = {}) {
+        return [
+            { key: 'name', label: 'Name' },
+            { key: 'type', label: 'Type', suggestions: this.typeSuggestions(context), width: '130px' },
+            { key: 'isPK', label: 'PK', type: 'checkbox' },
+            { key: 'isFK', label: 'FK', type: 'checkbox' },
+            { key: 'isUnique', label: 'Unique', type: 'checkbox' },
+            { key: 'required', label: 'Required', type: 'checkbox' },
+            { key: 'references', label: 'References', placeholder: 'entity.attribute', width: '140px' },
+            { key: 'description', label: 'Definition' },
+            { key: 'sensitivity', label: 'Sensitivity', type: 'select', choices: [['', '—'], ...(context.sensitivities ?? []).map(x => [x, x])] },
+            { key: 'categories', label: 'Categories', placeholder: (context.categories ?? []).slice(0, 2).join(', '), width: '90px' },
+            { key: 'measure', label: 'Measure', type: 'select', choices: [['', '—'], ...MEASURES.map(m => [m, m])] },
+        ];
+    }
+
+    entityFields(entity, context = {}) {
+        return [
+            ...super.entityFields(entity, context),
+            { type: 'heading', label: 'Dimensional' },
+            { key: 'role', label: 'Role', type: 'select', value: EntityRole.of(entity).role, choices: EntityRole.all().map(r => [r.role, r.label]) },
+            { key: 'grain', label: 'Grain (a fact)', type: 'text', value: entity?.grain ?? '', placeholder: 'One row per account per day' },
+            { key: 'scdType', label: 'History (a dimension)', type: 'select', value: entity?.scdType ?? '', choices: [['', '—'], ...DimensionRole.SCD_TYPES] },
+            { key: 'conformed', label: 'Conformed (a dimension)', type: 'checkbox', value: !!entity?.conformed },
+            {
+                key: 'attributes', label: this.attributeNoun, type: 'rows', columns: this.attributeColumns(context),
+                // Categories shown as written, a list read back (entitySpecFrom).
+                value: (entity?.attributes ?? []).map(a => (Array.isArray(a.categories) ? { ...a, categories: a.categories.join(', ') } : a)),
+                addLabel: this.attributeNoun.replace(/s$/, '').toLowerCase(),
+            },
+        ];
+    }
+
+    entitySpecFrom(values, entity = null) {
+        // An attribute's categories as a list, as an entity's are.
+        const attributes = (values.attributes ?? []).filter(a => text(a.name)).map(a => {
+            if (a.categories === undefined) return a;
+            const categories = list(a.categories);
+            const { categories: _, ...rest } = a;
+            return categories.length ? { ...rest, categories } : rest;
+        });
+        const out = { ...super.entitySpecFrom(values, entity), attributes };
+        // Its role, and only what that role has (a fact's grain, a dimension's history).
+        const role = EntityRole.ROLES.get(values.role ?? EntityRole.of(entity).role) ?? EntityRole.of(null);
+        for (const key of ['role', 'grain', 'scdType', 'conformed']) delete out[key];
+        if (role.role) out.role = role.role;
+        if (role.keys.includes('grain') && text(values.grain)) out.grain = text(values.grain);
+        if (role.keys.includes('scdType') && values.scdType !== '' && values.scdType != null) out.scdType = String(values.scdType);
+        if (role.keys.includes('conformed') && values.conformed) out.conformed = true;
+        return out;
+    }
+}
+
+/** The logical level: entities and their attributes, typed by the model's data types or plainly. */
+export class LogicalLevel extends AttributedLevel {
+    static PLAIN_TYPES = Object.freeze(['Text', 'Number', 'Decimal', 'Amount', 'Date', 'Date/Time', 'Boolean', 'Identifier', 'Code']);
+
+    typeSuggestions({ typeNames = [] } = {}) {
+        return [...typeNames, ...LogicalLevel.PLAIN_TYPES];
+    }
+}
+
+/** The physical level: tables and their columns, typed as a database types them. */
+export class PhysicalLevel extends AttributedLevel {
+    static SQL_TYPES = Object.freeze(['VARCHAR(40)', 'TEXT', 'INT', 'BIGINT', 'DECIMAL(18,2)', 'DATE', 'TIMESTAMP', 'BOOLEAN', 'CHAR(3)', 'JSONB']);
+
+    get entityNoun() {
+        return 'Table';
+    }
+
+    get attributeNoun() {
+        return 'Columns';
+    }
+
+    typeSuggestions() {
+        return PhysicalLevel.SQL_TYPES;
+    }
+}
+
+/** The conceptual level: concepts with a name and a definition, no attributes. */
+export class ConceptualLevel extends DataModelLevel {
+    get entityNoun() {
+        return 'Concept';
+    }
 }
 
 /** The canonical cardinality vocabulary every NotationStyle renders
@@ -91,9 +292,9 @@ export class NotationStyle {
 }
 
 const LEVELS = {
-    conceptual: new DataModelLevel('conceptual', 'Entities and their relationships only — no attributes, no keys, no types.'),
-    logical: new DataModelLevel('logical', 'Attributes and keys, still database-agnostic — no column types or engine specifics.'),
-    physical: new DataModelLevel('physical', 'Real column types, keys, and constraints as they exist in an actual database.'),
+    conceptual: new ConceptualLevel('conceptual', 'Entities and their relationships only — no attributes, no keys, no types.'),
+    logical: new LogicalLevel('logical', 'Attributes and keys, still database-agnostic — no column types or engine specifics.'),
+    physical: new PhysicalLevel('physical', 'Real column types, keys, and constraints as they exist in an actual database.'),
 };
 
 const NOTATIONS = {
@@ -120,6 +321,197 @@ const NOTATIONS = {
     }),
 };
 
+/**
+ * RelationshipKind — what a relationship between two entities is: an
+ * association (`AssociationKind`, a cardinality at each end, a Chen diamond)
+ * or a generalization (`GeneralizationKind`, the source a subtype of the
+ * target). A relationship's `kind` names one (none: an association); each
+ * draws its own edge in a notation, says whether a notation draws it as a node
+ * of its own, and whether it has cardinalities.
+ */
+export class RelationshipKind {
+    static kind = '';
+    static label = '';
+
+    /** Relationship kinds by their `kind`. */
+    static KINDS = new Map();
+
+    static register(KindClass) {
+        RelationshipKind.KINDS.set(KindClass.kind, new KindClass());
+    }
+
+    /** A relationship's kind (an association when it names none, or one not known). */
+    static of(relationship) {
+        return RelationshipKind.KINDS.get(relationship?.kind) ?? RelationshipKind.KINDS.get('association');
+    }
+
+    /** Every kind, in the order registered. */
+    static all() {
+        return [...RelationshipKind.KINDS.values()];
+    }
+
+    get kind() { return this.constructor.kind; }
+    get label() { return this.constructor.label; }
+
+    /** Whether it has a cardinality at each end. */
+    get hasCardinality() {
+        return true;
+    }
+
+    /** Whether a notation draws it as a node of its own (Chen's diamond). */
+    drawnAsNode(notation) {
+        return false;
+    }
+
+    /** The graphDiagram edge it is in a notation. @abstract */
+    edge(relationship, notation) {
+        throw new Error(`${this.constructor.name} must implement edge()`);
+    }
+}
+
+/** An association: a cardinality at each end, drawn as each notation draws one (a Chen diamond). */
+export class AssociationKind extends RelationshipKind {
+    static kind = 'association';
+    static label = 'Association';
+
+    drawnAsNode(notation) {
+        return !!notation.relationshipAsNode;
+    }
+
+    edge(relationship, notation) {
+        return {
+            ...relationship,
+            label: relationship.name,
+            lineStyle: relationship.identifying === false ? 'dashed' : 'solid',
+            arrowheadStart: notation.cardinalityArrowhead(relationship.sourceCardinality) || 'none',
+            arrowhead: notation.cardinalityArrowhead(relationship.targetCardinality) || 'none',
+            sourceLabel: notation.cardinalityLabel(relationship.sourceCardinality),
+            targetLabel: notation.cardinalityLabel(relationship.targetCardinality),
+        };
+    }
+}
+
+/**
+ * A generalization (DMBOK2's subtypes and supertypes): the source a subtype
+ * of the target. `complete` (every instance of the supertype is one of its
+ * subtypes) and `disjoint` (an instance is one subtype at most) are said on
+ * it. Drawn in every notation as a line to the supertype ending in a hollow
+ * triangle, its constraints its label (Chen's an ISA one); no cardinalities.
+ */
+export class GeneralizationKind extends RelationshipKind {
+    static kind = 'generalization';
+    static label = 'Generalization (subtype of)';
+
+    get hasCardinality() {
+        return false;
+    }
+
+    /** Its constraints in words: '{complete, disjoint}'. */
+    static constraints(relationship) {
+        return `{${relationship.complete ? 'complete' : 'incomplete'}, ${relationship.disjoint === false ? 'overlapping' : 'disjoint'}}`;
+    }
+
+    edge(relationship, notation) {
+        const { sourceCardinality, targetCardinality, ...rest } = relationship;
+        const words = GeneralizationKind.constraints(relationship);
+        return {
+            ...rest,
+            label: notation.relationshipAsNode ? `ISA ${words}` : words,
+            lineStyle: 'solid', arrowhead: 'triangle-hollow', arrowheadStart: 'none',
+        };
+    }
+}
+
+RelationshipKind.register(AssociationKind);
+RelationshipKind.register(GeneralizationKind);
+
+/**
+ * EntityRole — what an entity is in a dimensional scheme (DMBOK2's data
+ * warehousing and BI, after Kimball): a plain entity (`EntityRole`, none), a
+ * fact (`FactRole`: what is measured, at a stated `grain`, its attributes
+ * `measure`s) or a dimension (`DimensionRole`: what facts are looked at by,
+ * its `scdType` how it keeps history, `conformed` when facts share it). An
+ * entity's `role` names one; each says how it is drawn in the star view.
+ */
+export class EntityRole {
+    static role = '';
+    static label = 'None';
+    /** The colour its entities are drawn in, in the star view. */
+    static color = null;
+
+    /** Entity roles by their `role` ('' the plain one). */
+    static ROLES = new Map();
+
+    static register(RoleClass) {
+        EntityRole.ROLES.set(RoleClass.role, new RoleClass());
+    }
+
+    /** An entity's role (the plain one when it names none, or one not known). */
+    static of(entity) {
+        return EntityRole.ROLES.get(entity?.role ?? '') ?? EntityRole.ROLES.get('');
+    }
+
+    static all() {
+        return [...EntityRole.ROLES.values()];
+    }
+
+    get role() { return this.constructor.role; }
+    get label() { return this.constructor.label; }
+    get color() { return this.constructor.color; }
+
+    /** What is said of an entity in this role, for a hover: `{}` here. */
+    details(entity) {
+        return {};
+    }
+
+    /** The keys this role adds to an entity (FactRole's grain...): none here. */
+    get keys() {
+        return [];
+    }
+}
+
+/** A fact: measured, at a grain. */
+export class FactRole extends EntityRole {
+    static role = 'fact';
+    static label = 'Fact';
+    static color = '#fde68a';
+
+    details(entity) {
+        return { role: 'fact', ...(entity.grain && { grain: entity.grain }) };
+    }
+
+    get keys() {
+        return ['grain'];
+    }
+}
+
+/** A dimension: what facts are looked at by. */
+export class DimensionRole extends EntityRole {
+    static role = 'dimension';
+    static label = 'Dimension';
+    static color = '#bfdbfe';
+    /** Slowly changing dimension types: how a dimension keeps history. */
+    static SCD_TYPES = Object.freeze([['0', 'Type 0: never changes'], ['1', 'Type 1: overwritten'], ['2', 'Type 2: a row per version'], ['3', 'Type 3: the previous value kept']]);
+
+    details(entity) {
+        return {
+            role: entity.conformed ? 'conformed dimension' : 'dimension',
+            ...(entity.scdType !== undefined && entity.scdType !== '' && { history: DimensionRole.SCD_TYPES.find(([t]) => t === String(entity.scdType))?.[1] ?? `type ${entity.scdType}` }),
+        };
+    }
+
+    get keys() {
+        return ['scdType', 'conformed'];
+    }
+}
+
+EntityRole.register(EntityRole);
+EntityRole.register(FactRole);
+EntityRole.register(DimensionRole);
+
+/** How a fact's measure adds up across its dimensions. */
+const MEASURES = Object.freeze(['additive', 'semi-additive', 'non-additive']);
+
 export const DataModelNotation = {
     levels() { return Object.values(LEVELS); },
     levelNames() { return Object.keys(LEVELS); },
@@ -129,4 +521,10 @@ export const DataModelNotation = {
     notation(name) { return NOTATIONS[name] || NOTATIONS.crowsfoot; },
     isCardinality(value) { return CARDINALITIES.has(value); },
     cardinalities() { return [...CARDINALITIES]; },
+    /** A relationship's kind (RelationshipKind). */
+    relationshipKind(relationship) { return RelationshipKind.of(relationship); },
+    /** An entity's role in a dimensional scheme (EntityRole). */
+    entityRole(entity) { return EntityRole.of(entity); },
+    /** How a fact's measures add up: additive, semi-additive, non-additive. */
+    measures() { return [...MEASURES]; },
 };