ts-prorm-orm 1.1.0

package/dist/diagrams/schemadoc-diagram.js

@@ -0,0 +1,309 @@
+"use strict";
+/**
+ * SchemaDocDiagram — generates a print-friendly "data dictionary" / schema
+ * documentation sheet as SVG.
+ *
+ * Where ERDiagram / ModelDiagram render the *visual* shape of a schema, this
+ * generator renders the *reference* counterpart: for every table a titled
+ * section followed by a tabular grid with one row per column, listing
+ * Column · Type · Nullable · Key · Default · Description. Rows are
+ * zebra-striped and each grid's header row is painted in the accent color.
+ * A document title banner and a summary line ("N tables, M columns") top the
+ * sheet.
+ *
+ * All markup is built against a real DOM document (see ./svg-dom) — never by
+ * concatenating strings — and both `--theme` and `--color` genuinely change
+ * fill/stroke values in the output.
+ *
+ * Usage:
+ *   const doc = new SchemaDocDiagram({ tables: [...], title: 'My Schema' });
+ *   doc.save('./diagrams/schema.svg');
+ *   // or:
+ *   const svgString = doc.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.SchemaDocDiagram = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const palette_1 = require("./palette");
+const svg_dom_1 = require("./svg-dom");
+// ─── Layout constants (px) ──────────────────────────────────────────────────
+const W = 820; // content width
+const PAD = 28; // outer canvas padding
+const BANNER_H = 78; // title banner height
+const SUMMARY_H = 34; // summary line strip
+const SECTION_TITLE_H = 40; // per-table section title bar
+const COL_HDR_H = 30; // grid header row
+const ROW_H = 28; // grid data row
+const SECTION_GAP = 22; // space between tables
+const R = 12; // border radius
+// Column layout: [label, x offset, width]
+const COLS = [
+    { label: 'Column', x: 0, w: 170 },
+    { label: 'Type', x: 170, w: 140 },
+    { label: 'Nullable', x: 310, w: 80 },
+    { label: 'Key', x: 390, w: 60 },
+    { label: 'Default', x: 450, w: 130 },
+    { label: 'Description', x: 580, w: 240 },
+];
+const FONT_SANS = 'system-ui,-apple-system,sans-serif';
+const FONT_MONO = "'SF Mono','Fira Code',monospace";
+// ─── Helpers ────────────────────────────────────────────────────────────────
+/** Truncate text to roughly fit `width` px at the given font size. */
+function truncate(text, width, fontSize) {
+    const maxChars = Math.max(1, Math.floor(width / (fontSize * 0.6)));
+    if (text.length <= maxChars)
+        return text;
+    if (maxChars <= 1)
+        return '…';
+    return text.slice(0, maxChars - 1) + '…';
+}
+// ─── Main class ────────────────────────────────────────────────────────────
+class SchemaDocDiagram {
+    constructor(options) {
+        this.opts = {
+            tables: options.tables ?? [],
+            title: options.title ?? 'Schema Documentation',
+            theme: options.theme ?? 'light',
+            color: options.color ?? '',
+        };
+    }
+    /** Total column count across all tables. */
+    totalColumns() {
+        return this.opts.tables.reduce((n, t) => n + (t.columns?.length ?? 0), 0);
+    }
+    /** Height of one table's rendered section. */
+    sectionHeight(table) {
+        return SECTION_TITLE_H + COL_HDR_H + (table.columns?.length ?? 0) * ROW_H;
+    }
+    generate() {
+        const { tables, title, theme, color } = this.opts;
+        const accent = (0, palette_1.resolveAccent)(color);
+        const t = (0, palette_1.resolveTheme)(theme);
+        // ── Compute total height (auto-size viewBox) ────────────────────────
+        let contentH = BANNER_H + SUMMARY_H + 16;
+        tables.forEach((tbl, i) => {
+            contentH += this.sectionHeight(tbl);
+            if (i < tables.length - 1)
+                contentH += SECTION_GAP;
+        });
+        const svgW = W + 2 * PAD;
+        const svgH = contentH + 2 * PAD;
+        const cx = PAD;
+        const doc = new svg_dom_1.SvgDocument(svgW, svgH);
+        const svg = doc.root;
+        // ── Canvas background (theme) ───────────────────────────────────────
+        svg.child('rect', { width: svgW, height: svgH, fill: t.canvasBg });
+        // ── Title banner (accent) ───────────────────────────────────────────
+        const uid = 'sd';
+        doc.linearGradient(`bg${uid}`, [
+            [0, accent.from],
+            [100, accent.mid],
+        ]);
+        svg.child('rect', {
+            x: cx,
+            y: PAD,
+            width: W,
+            height: BANNER_H,
+            rx: R,
+            fill: `url(#bg${uid})`,
+        });
+        svg
+            .child('text', {
+            x: cx + 22,
+            y: PAD + 34,
+            'font-family': FONT_SANS,
+            'font-size': 24,
+            'font-weight': 800,
+            fill: '#FFFFFF',
+        })
+            .text(truncate(title, W - 44, 24));
+        svg
+            .child('text', {
+            x: cx + 22,
+            y: PAD + 58,
+            'font-family': FONT_SANS,
+            'font-size': 12,
+            'font-weight': 600,
+            fill: 'rgba(255,255,255,0.85)',
+            'letter-spacing': 1,
+        })
+            .text('DATA DICTIONARY');
+        // ── Summary line ────────────────────────────────────────────────────
+        const summaryY = PAD + BANNER_H + 8;
+        const tableCount = tables.length;
+        const colCount = this.totalColumns();
+        svg
+            .child('text', {
+            x: cx + 4,
+            y: summaryY + 22,
+            'font-family': FONT_SANS,
+            'font-size': 13,
+            'font-weight': 600,
+            fill: t.textSecondary,
+        })
+            .text(`${tableCount} table${tableCount !== 1 ? 's' : ''}, ${colCount} column${colCount !== 1 ? 's' : ''}`);
+        // ── Table sections ──────────────────────────────────────────────────
+        let y = summaryY + SUMMARY_H + 8;
+        tables.forEach((table) => {
+            y = this.drawTable(doc, svg, table, cx, y, accent, t);
+            y += SECTION_GAP;
+        });
+        return doc.toString('Generated by ts-prorm-orm SchemaDocDiagram');
+    }
+    /** Draw one table section starting at `y`; returns the y after the section. */
+    drawTable(doc, svg, table, cx, y, accent, t) {
+        const columns = table.columns ?? [];
+        // ── Section title bar ─────────────────────────────────────────────
+        svg.child('rect', {
+            x: cx,
+            y,
+            width: W,
+            height: SECTION_TITLE_H,
+            rx: 8,
+            fill: t.colHeaderBg,
+        });
+        svg.child('rect', { x: cx, y, width: 5, height: SECTION_TITLE_H, fill: accent.mid });
+        svg
+            .child('text', {
+            x: cx + 18,
+            y: y + 26,
+            'font-family': FONT_MONO,
+            'font-size': 16,
+            'font-weight': 700,
+            fill: t.textPrimary,
+        })
+            .text(truncate(table.name, 420, 16));
+        if (table.comment) {
+            svg
+                .child('text', {
+                x: cx + W - 14,
+                y: y + 26,
+                'font-family': FONT_SANS,
+                'font-size': 11,
+                fill: t.textSecondary,
+                'text-anchor': 'end',
+            })
+                .text(truncate(table.comment, 340, 11));
+        }
+        // ── Grid header row (accent) ──────────────────────────────────────
+        const gridX = cx;
+        let rowY = y + SECTION_TITLE_H;
+        svg.child('rect', {
+            x: gridX,
+            y: rowY,
+            width: W,
+            height: COL_HDR_H,
+            fill: accent.from,
+        });
+        COLS.forEach((c) => {
+            svg
+                .child('text', {
+                x: gridX + c.x + 10,
+                y: rowY + 20,
+                'font-family': FONT_SANS,
+                'font-size': 11,
+                'font-weight': 700,
+                fill: '#FFFFFF',
+                'letter-spacing': 0.4,
+            })
+                .text(c.label);
+        });
+        // ── Data rows (zebra) ─────────────────────────────────────────────
+        rowY += COL_HDR_H;
+        columns.forEach((col, i) => {
+            const rowBg = i % 2 === 0 ? t.cardBg : t.rowAlt;
+            svg.child('rect', { x: gridX, y: rowY, width: W, height: ROW_H, fill: rowBg });
+            const baseY = rowY + 18;
+            const cell = (idx, value, opts) => {
+                const c = COLS[idx];
+                const fs = 12;
+                svg
+                    .child('text', {
+                    x: gridX + c.x + 10,
+                    y: baseY,
+                    'font-family': opts?.mono ? FONT_MONO : FONT_SANS,
+                    'font-size': fs,
+                    fill: opts?.fill ?? t.textPrimary,
+                })
+                    .text(truncate(value, c.w - 16, fs));
+            };
+            cell(0, col.name, { mono: true, fill: t.textPrimary });
+            cell(1, col.type, { mono: true, fill: t.textSecondary });
+            cell(2, col.nullable === false ? 'NO' : 'YES', {
+                fill: col.nullable === false ? accent.mid : t.textSecondary,
+            });
+            cell(3, col.key ?? '', { mono: true, fill: accent.text });
+            cell(4, col.default != null ? String(col.default) : '', {
+                mono: true,
+                fill: t.textSecondary,
+            });
+            cell(5, col.description ?? '', { fill: t.textSecondary });
+            svg.child('line', {
+                x1: gridX,
+                y1: rowY + ROW_H,
+                x2: gridX + W,
+                y2: rowY + ROW_H,
+                stroke: t.border,
+                'stroke-width': 1,
+            });
+            rowY += ROW_H;
+        });
+        // ── Grid outline ──────────────────────────────────────────────────
+        svg.child('rect', {
+            x: gridX,
+            y: y + SECTION_TITLE_H,
+            width: W,
+            height: COL_HDR_H + columns.length * ROW_H,
+            fill: 'none',
+            stroke: t.border,
+            'stroke-width': 1,
+        });
+        return y + this.sectionHeight(table);
+    }
+    /**
+     * Write the SVG to a file. Creates parent directories if needed.
+     */
+    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.SchemaDocDiagram = SchemaDocDiagram;

package/dist/diagrams/sequence-diagram.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * SequenceDiagram — generates a UML sequence diagram as an SVG.
+ *
+ * Renders participants (actors / objects / databases) as header boxes across
+ * the top, each dropping a vertical dashed lifeline. Messages are drawn as
+ * numbered horizontal arrows between lifelines in order: a solid arrow is a
+ * synchronous call, a dashed arrow is a return / async message. Activation
+ * bars (thin rectangles) are drawn on a lifeline while it is active.
+ *
+ * The accent color (via resolveAccent) drives participant header boxes and
+ * arrowheads; the theme (via resolveTheme) drives the canvas, lifelines and
+ * text. Both `theme` and `color` genuinely change fill/stroke values in the
+ * generated SVG. The viewBox is auto-sized to fit all content.
+ *
+ * Usage:
+ *   const diag = new SequenceDiagram({ participants: […], messages: […] });
+ *   diag.save('./diagrams/flow.svg');
+ *   // or:
+ *   const svgString = diag.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.SequenceDiagram = 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 SequenceDiagram {
+    constructor(options) {
+        this.opts = {
+            participants: options.participants ?? [],
+            messages: options.messages ?? [],
+            title: options.title ?? '',
+            theme: options.theme ?? 'light',
+            color: options.color ?? '',
+        };
+    }
+    /** Kind glyph drawn inside a participant header. */
+    kindGlyph(kind) {
+        if (kind === 'actor')
+            return '☺';
+        if (kind === 'database')
+            return '⛁';
+        return '▭';
+    }
+    generate() {
+        const { participants, messages, title, theme, color } = this.opts;
+        const accent = (0, palette_1.resolveAccent)(color);
+        const t = (0, palette_1.resolveTheme)(theme);
+        const PAD = SequenceDiagram.PAD;
+        const LANE = SequenceDiagram.LANE;
+        const HDR_W = SequenceDiagram.HDR_W;
+        const HDR_H = SequenceDiagram.HDR_H;
+        const TITLE_H = title ? SequenceDiagram.TITLE_H : 0;
+        const MSG_GAP = SequenceDiagram.MSG_GAP;
+        const TOP_GAP = SequenceDiagram.TOP_GAP;
+        const BOT_GAP = SequenceDiagram.BOT_GAP;
+        const ACT_W = SequenceDiagram.ACT_W;
+        const n = Math.max(participants.length, 1);
+        const m = messages.length;
+        // Lifeline x-centers.
+        const laneX = (i) => PAD + HDR_W / 2 + i * LANE;
+        const indexOf = (name) => {
+            const idx = participants.findIndex((p) => p.name === name);
+            return idx < 0 ? 0 : idx;
+        };
+        // Vertical geometry.
+        const headerTop = PAD + TITLE_H;
+        const headerBottom = headerTop + HDR_H;
+        const firstMsgY = headerBottom + TOP_GAP;
+        const lifelineBottom = firstMsgY + m * MSG_GAP + BOT_GAP;
+        const svgW = PAD * 2 + HDR_W + (n - 1) * LANE;
+        const svgH = lifelineBottom + PAD;
+        const doc = new svg_dom_1.SvgDocument(svgW, svgH);
+        const svg = doc.root;
+        // ── Canvas background (theme-driven) ────────────────────────────────
+        svg.child('rect', { width: svgW, height: svgH, fill: t.canvasBg });
+        // ── Arrowhead marker (accent-colored) ───────────────────────────────
+        const headId = `seqhead${accent.name.replace(/\W/g, '')}`;
+        const marker = doc.defs().child('marker', {
+            id: headId,
+            markerWidth: 10,
+            markerHeight: 10,
+            refX: 8,
+            refY: 4,
+            orient: 'auto',
+            markerUnits: 'userSpaceOnUse',
+        });
+        marker.child('path', { d: 'M0,0 L8,4 L0,8 Z', fill: accent.mid });
+        // ── Title ───────────────────────────────────────────────────────────
+        if (title) {
+            svg
+                .child('text', {
+                x: svgW / 2,
+                y: PAD + 24,
+                'font-family': 'system-ui,-apple-system,sans-serif',
+                'font-size': 20,
+                'font-weight': 800,
+                fill: t.textPrimary,
+                'text-anchor': 'middle',
+            })
+                .text(title);
+        }
+        // ── Lifelines (dashed, theme-colored) ───────────────────────────────
+        participants.forEach((_p, i) => {
+            const x = laneX(i);
+            svg.child('line', {
+                x1: x,
+                y1: headerBottom,
+                x2: x,
+                y2: lifelineBottom,
+                stroke: t.border,
+                'stroke-width': 1.5,
+                'stroke-dasharray': '6 5',
+                class: 'lifeline',
+            });
+        });
+        // ── Activation bars (drawn under arrows so arrows sit on top edge) ──
+        messages.forEach((msg, i) => {
+            if (!msg.activate)
+                return;
+            const y = firstMsgY + i * MSG_GAP;
+            const x = laneX(indexOf(msg.to));
+            // Extend the bar to the next message (or to the lifeline end).
+            const endY = i + 1 < m ? firstMsgY + (i + 1) * MSG_GAP : y + MSG_GAP;
+            svg.child('rect', {
+                x: x - ACT_W / 2,
+                y,
+                width: ACT_W,
+                height: Math.max(endY - y, MSG_GAP / 2),
+                fill: accent.light,
+                stroke: accent.mid,
+                'stroke-width': 1,
+                class: 'activation',
+            });
+        });
+        // ── Participant header boxes (accent-colored) ───────────────────────
+        participants.forEach((p, i) => {
+            const cxLine = laneX(i);
+            const boxX = cxLine - HDR_W / 2;
+            svg.child('rect', {
+                x: boxX,
+                y: headerTop,
+                width: HDR_W,
+                height: HDR_H,
+                rx: 8,
+                fill: accent.from,
+                stroke: accent.mid,
+                'stroke-width': 1.5,
+                class: 'participant',
+            });
+            svg
+                .child('text', {
+                x: cxLine,
+                y: headerTop + 20,
+                'font-family': 'system-ui,-apple-system,sans-serif',
+                'font-size': 13,
+                fill: '#FFFFFF',
+                'text-anchor': 'middle',
+            })
+                .text(this.kindGlyph(p.kind));
+            svg
+                .child('text', {
+                x: cxLine,
+                y: headerTop + 38,
+                'font-family': "'SF Mono','Fira Code',monospace",
+                'font-size': 13,
+                'font-weight': 700,
+                fill: '#FFFFFF',
+                'text-anchor': 'middle',
+            })
+                .text(p.name.length > 16 ? p.name.slice(0, 15) + '…' : p.name);
+        });
+        // ── Messages (numbered arrows) ──────────────────────────────────────
+        messages.forEach((msg, i) => {
+            const y = firstMsgY + i * MSG_GAP;
+            const fromI = indexOf(msg.from);
+            const toI = indexOf(msg.to);
+            let x1 = laneX(fromI);
+            let x2 = laneX(toI);
+            const isReturn = !!msg.return;
+            const rightward = x2 >= x1;
+            // Nudge endpoints off activation bars so arrowheads stay visible.
+            if (x1 !== x2) {
+                x1 += rightward ? ACT_W / 2 : -ACT_W / 2;
+                x2 += rightward ? -ACT_W / 2 : ACT_W / 2;
+            }
+            if (fromI === toI) {
+                // Self-message: a small loop back to the same lifeline.
+                const w = 60;
+                const yb = y + 22;
+                svg.child('path', {
+                    d: `M${x1},${y} h${w} v${yb - y} h-${w}`,
+                    fill: 'none',
+                    stroke: accent.mid,
+                    'stroke-width': 1.6,
+                    'stroke-dasharray': isReturn ? '5 4' : undefined,
+                    'marker-end': `url(#${headId})`,
+                    class: isReturn ? 'message message-return' : 'message message-call',
+                });
+            }
+            else {
+                svg.child('line', {
+                    x1,
+                    y1: y,
+                    x2,
+                    y2: y,
+                    stroke: accent.mid,
+                    'stroke-width': 1.6,
+                    'stroke-dasharray': isReturn ? '5 4' : undefined,
+                    'marker-end': `url(#${headId})`,
+                    class: isReturn ? 'message message-return' : 'message message-call',
+                });
+            }
+            // Sequence number badge on the source side.
+            const badgeX = rightward ? Math.min(x1, x2) + 11 : Math.max(x1, x2) - 11;
+            svg.child('circle', {
+                cx: badgeX,
+                cy: y - 12,
+                r: 9,
+                fill: accent.mid,
+                class: 'seq-num',
+            });
+            svg
+                .child('text', {
+                x: badgeX,
+                y: y - 8,
+                'font-family': "'SF Mono',monospace",
+                'font-size': 10,
+                'font-weight': 700,
+                fill: '#FFFFFF',
+                'text-anchor': 'middle',
+            })
+                .text(i + 1);
+            // Message label above the arrow.
+            const midX = (x1 + x2) / 2;
+            svg
+                .child('text', {
+                x: fromI === toI ? x1 + 66 : midX,
+                y: y - 8,
+                'font-family': 'system-ui,-apple-system,sans-serif',
+                'font-size': 12,
+                'font-weight': 600,
+                fill: t.textPrimary,
+                'text-anchor': fromI === toI ? 'start' : 'middle',
+            })
+                .text(msg.label);
+        });
+        return doc.toString('Generated by ts-prorm-orm SequenceDiagram');
+    }
+    /**
+     * Write the SVG to a file. Creates parent directories if needed.
+     */
+    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.SequenceDiagram = SequenceDiagram;
+// Layout constants (px)
+SequenceDiagram.PAD = 30;
+SequenceDiagram.LANE = 170; // horizontal spacing between lifelines
+SequenceDiagram.HDR_W = 140; // participant header box width
+SequenceDiagram.HDR_H = 46; // participant header box height
+SequenceDiagram.TITLE_H = 40;
+SequenceDiagram.MSG_GAP = 54; // vertical spacing between messages
+SequenceDiagram.TOP_GAP = 40; // gap below headers before first message
+SequenceDiagram.BOT_GAP = 40; // gap below last message before lifelines end
+SequenceDiagram.ACT_W = 12; // activation bar width