ts-prorm-orm 1.1.0

package/dist/diagrams/relational-diagram.js

@@ -0,0 +1,455 @@
+"use strict";
+/**
+ * RelationalDiagram — renders a relational schema as entity boxes with their
+ * columns and draws connectors between related tables using proper crow's-foot
+ * cardinality notation.
+ *
+ * Each entity is a box listing its columns; primary-key columns are marked and
+ * underlined, foreign-key columns are marked. Relationship connectors terminate
+ * with crow's-foot endpoints:
+ *   - "one"       → a small perpendicular tick (single bar)
+ *   - "many"      → the three-pronged crow's foot
+ *   - "optional"  → a small circle just outside the endpoint (zero cardinality)
+ *
+ * Supported relationship types: one-to-one, one-to-many, many-to-one,
+ * many-to-many. Entities are laid out on a grid and connectors are routed
+ * between the nearest entity edges.
+ *
+ * Everything is built against a real DOM document via the shared `SvgDocument`
+ * / `El` builder — never by concatenating markup strings — and the viewBox is
+ * auto-sized to the content. Both `theme` and `color` change real fill/stroke
+ * values in the output (via `resolveTheme` / `resolveAccent`).
+ *
+ * Usage:
+ *   const rel = new RelationalDiagram({
+ *     title: 'Shop Schema',
+ *     entities: [ …RelEntity ],
+ *     relationships: [ …RelRelationship ],
+ *   });
+ *   rel.save('./diagrams/schema.svg');
+ *   // or: const svg = rel.generate();
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelationalDiagram = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const palette_1 = require("./palette");
+const svg_dom_1 = require("./svg-dom");
+// ─── Main class ──────────────────────────────────────────────────────────────
+class RelationalDiagram {
+    constructor(options) {
+        this.opts = {
+            entities: options.entities,
+            relationships: options.relationships ?? [],
+            title: options.title ?? 'Relational Schema',
+            theme: options.theme ?? 'light',
+            color: options.color ?? '',
+            columns: options.columns ?? 3,
+        };
+    }
+    // ── Box height for an entity ─────────────────────────────────────────────
+    boxHeight(entity) {
+        const h = RelationalDiagram.HDR_H + entity.columns.length * RelationalDiagram.ROW_H + 8;
+        return Math.max(h, RelationalDiagram.BOX_MIN_H);
+    }
+    // ── Grid layout ──────────────────────────────────────────────────────────
+    computeLayout() {
+        const { entities, columns } = this.opts;
+        const W = RelationalDiagram.BOX_W;
+        const MARGIN = RelationalDiagram.MARGIN;
+        const BANNER = RelationalDiagram.BANNER_H;
+        const H_GAP = RelationalDiagram.H_GAP;
+        const V_GAP = RelationalDiagram.V_GAP;
+        // Precompute per-row max height so rows never overlap.
+        const rowHeights = [];
+        let curRowMax = 0;
+        entities.forEach((e, i) => {
+            curRowMax = Math.max(curRowMax, this.boxHeight(e));
+            if ((i + 1) % columns === 0 || i === entities.length - 1) {
+                rowHeights.push(curRowMax);
+                curRowMax = 0;
+            }
+        });
+        const layout = [];
+        let col = 0;
+        let row = 0;
+        let rowTop = BANNER + MARGIN;
+        entities.forEach((entity) => {
+            const h = this.boxHeight(entity);
+            const x = MARGIN + col * (W + H_GAP);
+            const y = rowTop + (rowHeights[row] - h) / 2;
+            layout.push({ entity, x, y, w: W, h });
+            col++;
+            if (col >= columns) {
+                col = 0;
+                rowTop += rowHeights[row] + V_GAP;
+                row++;
+            }
+        });
+        return layout;
+    }
+    // ── Render a single entity box ───────────────────────────────────────────
+    renderBox(doc, svg, box, idx) {
+        const { entity, x, y, w, h } = box;
+        const t = (0, palette_1.resolveTheme)(this.opts.theme);
+        const palettes = (0, palette_1.rotatedPalettes)(this.opts.color);
+        const accent = palettes[idx % palettes.length];
+        const HDR = RelationalDiagram.HDR_H;
+        const ROW = RelationalDiagram.ROW_H;
+        const R = 8;
+        const uid = entity.name.replace(/\W/g, '') + idx;
+        // Header gradient (accent-driven → responds to `color`).
+        const gradId = doc.linearGradient(`relhg${uid}`, [
+            [0, accent.from],
+            [100, accent.mid],
+        ]);
+        // Shell / shadow.
+        svg.child('rect', {
+            x: x - 1,
+            y: y - 1,
+            width: w + 2,
+            height: h + 2,
+            rx: R + 1,
+            fill: t.border,
+        });
+        // Surface.
+        svg.child('rect', { x, y, width: w, height: h, rx: R, fill: t.cardBg });
+        // Header band (rounded top, flattened bottom).
+        svg.child('rect', { x, y, width: w, height: HDR, rx: R, fill: `url(#${gradId})` });
+        svg.child('rect', { x, y: y + HDR - R, width: w, height: R, fill: `url(#${gradId})` });
+        svg
+            .child('text', {
+            x: x + w / 2,
+            y: y + 26,
+            'font-family': 'system-ui,-apple-system,sans-serif',
+            'font-size': 16,
+            'font-weight': 800,
+            fill: '#FFFFFF',
+            'text-anchor': 'middle',
+        })
+            .text(entity.name);
+        // Column rows.
+        entity.columns.forEach((colDef, ci) => {
+            const ry = y + HDR + ci * ROW;
+            const midY = ry + ROW / 2;
+            const textY = midY + 4;
+            const isPK = !!colDef.primaryKey;
+            const isFK = !!colDef.foreignKey;
+            const rowBg = ci % 2 === 0 ? t.cardBg : t.rowAlt;
+            svg.child('rect', { x, y: ry, width: w, height: ROW, fill: rowBg });
+            // Key marker.
+            const markX = x + 14;
+            if (isPK) {
+                svg.child('circle', { cx: markX, cy: midY, r: 4, fill: '#F59E0B' });
+            }
+            else if (isFK) {
+                svg.child('circle', {
+                    cx: markX,
+                    cy: midY,
+                    r: 4,
+                    fill: 'none',
+                    stroke: '#3B82F6',
+                    'stroke-width': 1.6,
+                });
+            }
+            else {
+                svg.child('circle', { cx: markX, cy: midY, r: 2.5, fill: t.textSecondary });
+            }
+            // Column name (PK underlined, PK/FK colored+bold).
+            const nameColor = isPK ? '#B45309' : isFK ? '#2563EB' : t.textPrimary;
+            const nameWeight = isPK ? 700 : isFK ? 600 : 400;
+            const nameX = x + 28;
+            svg
+                .child('text', {
+                x: nameX,
+                y: textY,
+                'font-family': "'SF Mono','Fira Code',monospace",
+                'font-size': 11,
+                'font-weight': nameWeight,
+                'text-decoration': isPK ? 'underline' : undefined,
+                fill: nameColor,
+            })
+                .text(colDef.name);
+            // Type (right-aligned).
+            if (colDef.type) {
+                svg
+                    .child('text', {
+                    x: x + w - 10,
+                    y: textY,
+                    'font-family': "'SF Mono',monospace",
+                    'font-size': 10,
+                    'font-weight': 500,
+                    fill: t.textSecondary,
+                    'text-anchor': 'end',
+                })
+                    .text(colDef.type);
+            }
+            // PK/FK tag near the name.
+            if (isPK || isFK) {
+                svg
+                    .child('text', {
+                    x: nameX,
+                    y: ry + ROW - 4,
+                    'font-family': 'monospace',
+                    'font-size': 7,
+                    'font-weight': 700,
+                    fill: isPK ? '#B45309' : '#2563EB',
+                })
+                    .text(isPK ? 'PK' : 'FK');
+            }
+            // Row separator.
+            svg.child('line', {
+                x1: x,
+                y1: ry + ROW,
+                x2: x + w,
+                y2: ry + ROW,
+                stroke: t.border,
+                'stroke-width': 0.5,
+            });
+        });
+    }
+    // ── Pick the connection point on the nearest edges of two boxes ──────────
+    edgePoint(box, side) {
+        switch (side) {
+            case 'left':
+                return { x: box.x, y: box.y + box.h / 2 };
+            case 'right':
+                return { x: box.x + box.w, y: box.y + box.h / 2 };
+            case 'top':
+                return { x: box.x + box.w / 2, y: box.y };
+            case 'bottom':
+                return { x: box.x + box.w / 2, y: box.y + box.h };
+        }
+    }
+    chooseSides(a, b) {
+        const aMidX = a.x + a.w / 2;
+        const bMidX = b.x + b.w / 2;
+        const aMidY = a.y + a.h / 2;
+        const bMidY = b.y + b.h / 2;
+        // If mostly stacked vertically, exit top/bottom.
+        if (Math.abs(aMidX - bMidX) < a.w / 2 && Math.abs(aMidY - bMidY) > a.h) {
+            return b.y >= a.y ? ['bottom', 'top'] : ['top', 'bottom'];
+        }
+        return bMidX >= aMidX ? ['right', 'left'] : ['left', 'right'];
+    }
+    // ── Crow's-foot "many" endpoint (three prongs + arc bar) ────────────────
+    crowFoot(parent, x, y, side, color) {
+        // Symbol points AWAY from the box, back along the connector.
+        const reach = 13;
+        const spread = 7;
+        let ex, ey, perp;
+        if (side === 'left' || side === 'right') {
+            const sign = side === 'right' ? 1 : -1;
+            ex = x + sign * reach;
+            ey = y;
+            perp = [
+                [ex, y - spread],
+                [ex, y + spread],
+            ];
+        }
+        else {
+            const sign = side === 'bottom' ? 1 : -1;
+            ex = x;
+            ey = y + sign * reach;
+            perp = [
+                [x - spread, ey],
+                [x + spread, ey],
+            ];
+        }
+        // Three prongs converging at the box edge.
+        parent.child('line', { x1: x, y1: y, x2: perp[0][0], y2: perp[0][1], stroke: color, 'stroke-width': 1.6 });
+        parent.child('line', { x1: x, y1: y, x2: ex, y2: ey, stroke: color, 'stroke-width': 1.6 });
+        parent.child('line', { x1: x, y1: y, x2: perp[1][0], y2: perp[1][1], stroke: color, 'stroke-width': 1.6 });
+        // Connecting bar across the prongs.
+        parent.child('line', {
+            x1: perp[0][0],
+            y1: perp[0][1],
+            x2: perp[1][0],
+            y2: perp[1][1],
+            stroke: color,
+            'stroke-width': 1.4,
+        });
+    }
+    // ── "One" endpoint (single perpendicular tick) ───────────────────────────
+    oneBar(parent, x, y, side, color) {
+        const gap = 11;
+        const ht = 7;
+        if (side === 'left' || side === 'right') {
+            const bx = side === 'right' ? x + gap : x - gap;
+            parent.child('line', { x1: bx, y1: y - ht, x2: bx, y2: y + ht, stroke: color, 'stroke-width': 1.8 });
+        }
+        else {
+            const by = side === 'bottom' ? y + gap : y - gap;
+            parent.child('line', { x1: x - ht, y1: by, x2: x + ht, y2: by, stroke: color, 'stroke-width': 1.8 });
+        }
+    }
+    // ── Draw one relationship connector with crow's-foot ends ────────────────
+    renderRelationship(svg, rel, byName, color) {
+        const a = byName.get(rel.from);
+        const b = byName.get(rel.to);
+        if (!a || !b)
+            return;
+        const [sideA, sideB] = this.chooseSides(a, b);
+        const p = this.edgePoint(a, sideA);
+        const q = this.edgePoint(b, sideB);
+        const group = svg.child('g', { 'data-rel': `${rel.from}-${rel.to}` });
+        // Connector path (bezier for horizontal exits, gentle curve for vertical).
+        const horizontal = sideA === 'left' || sideA === 'right';
+        let d;
+        if (horizontal) {
+            const off = Math.max(Math.abs(q.x - p.x) * 0.5, 50);
+            const c1x = sideA === 'right' ? p.x + off : p.x - off;
+            const c2x = sideB === 'left' ? q.x - off : q.x + off;
+            d = `M ${p.x} ${p.y} C ${c1x} ${p.y}, ${c2x} ${q.y}, ${q.x} ${q.y}`;
+        }
+        else {
+            const off = Math.max(Math.abs(q.y - p.y) * 0.5, 50);
+            const c1y = sideA === 'bottom' ? p.y + off : p.y - off;
+            const c2y = sideB === 'top' ? q.y - off : q.y + off;
+            d = `M ${p.x} ${p.y} C ${p.x} ${c1y}, ${q.x} ${c2y}, ${q.x} ${q.y}`;
+        }
+        group.child('path', {
+            d,
+            fill: 'none',
+            stroke: color,
+            'stroke-width': 1.8,
+            opacity: 0.85,
+        });
+        // Cardinality endpoints.
+        const manyAtFrom = rel.type === 'many-to-one' || rel.type === 'many-to-many';
+        const manyAtTo = rel.type === 'one-to-many' || rel.type === 'many-to-many';
+        if (manyAtFrom)
+            this.crowFoot(group, p.x, p.y, sideA, color);
+        else
+            this.oneBar(group, p.x, p.y, sideA, color);
+        if (manyAtTo)
+            this.crowFoot(group, q.x, q.y, sideB, color);
+        else
+            this.oneBar(group, q.x, q.y, sideB, color);
+        // Midpoint label.
+        const label = rel.label ?? rel.type;
+        const mx = (p.x + q.x) / 2;
+        const my = (p.y + q.y) / 2;
+        const lw = label.length * 6.5 + 14;
+        group.child('rect', {
+            x: mx - lw / 2,
+            y: my - 10,
+            width: lw,
+            height: 18,
+            rx: 5,
+            fill: (0, palette_1.resolveTheme)(this.opts.theme).cardBg,
+            stroke: color,
+            'stroke-width': 1,
+            opacity: 0.95,
+        });
+        group
+            .child('text', {
+            x: mx,
+            y: my + 3,
+            'font-family': 'system-ui,sans-serif',
+            'font-size': 9,
+            'font-weight': 600,
+            fill: color,
+            'text-anchor': 'middle',
+        })
+            .text(label);
+    }
+    // ── Generate full SVG ────────────────────────────────────────────────────
+    generate() {
+        const { title, relationships } = this.opts;
+        const t = (0, palette_1.resolveTheme)(this.opts.theme);
+        const accent = (0, palette_1.resolveAccent)(this.opts.color);
+        const MARGIN = RelationalDiagram.MARGIN;
+        const BANNER = RelationalDiagram.BANNER_H;
+        const layout = this.computeLayout();
+        const byName = new Map();
+        layout.forEach((b) => byName.set(b.entity.name, b));
+        // Auto-size canvas.
+        const maxX = layout.length ? Math.max(...layout.map((b) => b.x + b.w)) : MARGIN;
+        const maxY = layout.length ? Math.max(...layout.map((b) => b.y + b.h)) : BANNER;
+        const totalW = maxX + MARGIN;
+        const totalH = maxY + MARGIN;
+        const doc = new svg_dom_1.SvgDocument(totalW, totalH);
+        const svg = doc.root;
+        // Canvas background (theme-driven → responds to `theme`).
+        svg.child('rect', { width: totalW, height: totalH, fill: t.canvasBg });
+        // Banner (accent-driven fill so `color` shows here too).
+        const bannerGrad = doc.linearGradient('relBanner', [
+            [0, accent.from],
+            [100, accent.mid],
+        ], { x2: 1, y2: 0 });
+        svg.child('rect', { width: totalW, height: BANNER, fill: `url(#${bannerGrad})` });
+        svg
+            .child('text', {
+            x: 24,
+            y: 38,
+            'font-family': 'system-ui,-apple-system,sans-serif',
+            'font-size': 22,
+            'font-weight': 800,
+            fill: '#FFFFFF',
+        })
+            .text(title);
+        // Relationship connectors (drawn under the boxes).
+        const relColor = accent.mid;
+        relationships.forEach((rel) => this.renderRelationship(svg, rel, byName, relColor));
+        // Entity boxes on top.
+        layout.forEach((box, i) => this.renderBox(doc, svg, box, i));
+        return doc.toString('Generated by ts-prorm-orm RelationalDiagram');
+    }
+    /**
+     * Write the SVG to a file, creating parent directories as needed.
+     * Returns the resolved absolute path.
+     */
+    save(outputPath) {
+        const resolved = path.resolve(outputPath);
+        const dir = path.dirname(resolved);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(resolved, this.generate(), 'utf-8');
+        return resolved;
+    }
+}
+exports.RelationalDiagram = RelationalDiagram;
+// Entity box geometry (px)
+RelationalDiagram.BOX_W = 240;
+RelationalDiagram.HDR_H = 40;
+RelationalDiagram.ROW_H = 26;
+RelationalDiagram.BOX_MIN_H = 80;
+// Chrome
+RelationalDiagram.BANNER_H = 60;
+RelationalDiagram.MARGIN = 56;
+RelationalDiagram.H_GAP = 130;
+RelationalDiagram.V_GAP = 90;