turbine-orm 0.3.1 → 0.5.0

package/dist/cjs/cli/migrate.js

@@ -0,0 +1,421 @@
+"use strict";
+/**
+ * turbine-orm CLI — Migration system
+ *
+ * SQL-first migrations with UP/DOWN sections, tracked in _turbine_migrations.
+ * Migration files are timestamp-prefixed .sql files.
+ *
+ * File format:
+ *   -- UP
+ *   CREATE TABLE users (...);
+ *
+ *   -- DOWN
+ *   DROP TABLE users;
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMigrationFilename = parseMigrationFilename;
+exports.sanitizeName = sanitizeName;
+exports.formatTimestamp = formatTimestamp;
+exports.getPendingMigrations = getPendingMigrations;
+exports.listMigrationFiles = listMigrationFiles;
+exports.parseMigrationContent = parseMigrationContent;
+exports.parseMigrationSQL = parseMigrationSQL;
+exports.createMigration = createMigration;
+exports.migrateUp = migrateUp;
+exports.migrateDown = migrateDown;
+exports.migrateStatus = migrateStatus;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const pg_1 = __importDefault(require("pg"));
+// ---------------------------------------------------------------------------
+// Tracking table management
+// ---------------------------------------------------------------------------
+const TRACKING_TABLE = '_turbine_migrations';
+const CREATE_TRACKING_TABLE = `
+  CREATE TABLE IF NOT EXISTS ${TRACKING_TABLE} (
+    id SERIAL PRIMARY KEY,
+    name TEXT NOT NULL UNIQUE,
+    checksum TEXT NOT NULL,
+    applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  );
+`;
+async function ensureTrackingTable(client) {
+    await client.query(CREATE_TRACKING_TABLE);
+}
+async function getAppliedMigrations(client) {
+    await ensureTrackingTable(client);
+    const result = await client.query(`SELECT id, name, applied_at, checksum FROM ${TRACKING_TABLE} ORDER BY id ASC`);
+    return result.rows;
+}
+// ---------------------------------------------------------------------------
+// File operations
+// ---------------------------------------------------------------------------
+/**
+ * Parse a migration filename into its components.
+ * Expected format: YYYYMMDDHHMMSS_description.sql
+ */
+function parseMigrationFilename(filename) {
+    const match = filename.match(/^(\d{14})_(.+)\.sql$/);
+    if (!match)
+        return null;
+    return {
+        filename,
+        path: '', // Set by caller
+        name: filename.replace(/\.sql$/, ''),
+        timestamp: match[1],
+    };
+}
+/**
+ * Sanitize a migration name: lowercase, replace non-alnum with _, collapse duplicates, trim.
+ */
+function sanitizeName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9_]/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_|_$/g, '');
+}
+/**
+ * Generate a YYYYMMDDHHMMSS timestamp string from a Date.
+ */
+function formatTimestamp(date) {
+    return [
+        date.getFullYear(),
+        String(date.getMonth() + 1).padStart(2, '0'),
+        String(date.getDate()).padStart(2, '0'),
+        String(date.getHours()).padStart(2, '0'),
+        String(date.getMinutes()).padStart(2, '0'),
+        String(date.getSeconds()).padStart(2, '0'),
+    ].join('');
+}
+/**
+ * Get pending migration files — those not yet applied.
+ * Returns files sorted by timestamp (ascending).
+ */
+function getPendingMigrations(migrationsDir, applied) {
+    const appliedSet = new Set(applied);
+    return listMigrationFiles(migrationsDir).filter((f) => !appliedSet.has(f.name));
+}
+/**
+ * List all migration files in the migrations directory, sorted by name.
+ */
+function listMigrationFiles(migrationsDir) {
+    if (!(0, node_fs_1.existsSync)(migrationsDir))
+        return [];
+    const entries = (0, node_fs_1.readdirSync)(migrationsDir)
+        .filter((f) => f.endsWith('.sql'))
+        .sort();
+    const files = [];
+    for (const entry of entries) {
+        const parsed = parseMigrationFilename(entry);
+        if (parsed) {
+            parsed.path = (0, node_path_1.join)(migrationsDir, entry);
+            files.push(parsed);
+        }
+    }
+    return files;
+}
+/**
+ * Parse migration content string into UP and DOWN sections.
+ * Exported for unit testing.
+ */
+function parseMigrationContent(content) {
+    const lines = content.split('\n');
+    let section = 'none';
+    const upLines = [];
+    const downLines = [];
+    for (const line of lines) {
+        const trimmed = line.trim().toUpperCase();
+        if (trimmed === '-- UP') {
+            section = 'up';
+            continue;
+        }
+        if (trimmed === '-- DOWN') {
+            section = 'down';
+            continue;
+        }
+        if (section === 'up')
+            upLines.push(line);
+        else if (section === 'down')
+            downLines.push(line);
+    }
+    return {
+        up: upLines.join('\n').trim(),
+        down: downLines.join('\n').trim(),
+    };
+}
+/**
+ * Parse a migration file into UP and DOWN sections.
+ */
+function parseMigrationSQL(filePath) {
+    const content = (0, node_fs_1.readFileSync)(filePath, 'utf-8');
+    return parseMigrationContent(content);
+}
+/**
+ * Simple checksum for a migration file (for drift detection).
+ */
+function checksum(content) {
+    let hash = 0;
+    for (let i = 0; i < content.length; i++) {
+        const chr = content.charCodeAt(i);
+        hash = ((hash << 5) - hash + chr) | 0;
+    }
+    return Math.abs(hash).toString(36);
+}
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+/**
+ * Create a new migration file.
+ */
+function createMigration(migrationsDir, name) {
+    (0, node_fs_1.mkdirSync)(migrationsDir, { recursive: true });
+    const now = new Date();
+    const ts = formatTimestamp(now);
+    const safeName = sanitizeName(name);
+    const filename = `${ts}_${safeName}.sql`;
+    const filePath = (0, node_path_1.join)(migrationsDir, filename);
+    const template = `-- Migration: ${name}
+-- Created: ${now.toISOString()}
+
+-- UP
+-- Write your migration SQL here
+
+-- DOWN
+-- Write your rollback SQL here
+`;
+    (0, node_fs_1.writeFileSync)(filePath, template, 'utf-8');
+    return {
+        filename,
+        path: filePath,
+        name: filename.replace(/\.sql$/, ''),
+        timestamp: ts,
+    };
+}
+// ---------------------------------------------------------------------------
+// Advisory lock for concurrent migration safety
+// ---------------------------------------------------------------------------
+/** Fixed lock ID for Turbine migrations — prevents concurrent migrate runs */
+const MIGRATION_LOCK_ID = 8_347_291; // arbitrary but stable
+async function acquireLock(client) {
+    const result = await client.query(`SELECT pg_try_advisory_lock($1)`, [MIGRATION_LOCK_ID]);
+    return result.rows[0]?.pg_try_advisory_lock ?? false;
+}
+async function releaseLock(client) {
+    await client.query(`SELECT pg_advisory_unlock($1)`, [MIGRATION_LOCK_ID]);
+}
+// ---------------------------------------------------------------------------
+// Checksum validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate that applied migration files have not been modified since they were run.
+ * Returns an array of mismatched migrations (empty if all are clean).
+ */
+async function validateChecksums(client, migrationsDir) {
+    const applied = await getAppliedMigrations(client);
+    const allFiles = listMigrationFiles(migrationsDir);
+    const fileMap = new Map(allFiles.map((f) => [f.name, f]));
+    const mismatches = [];
+    for (const migration of applied) {
+        const file = fileMap.get(migration.name);
+        if (!file)
+            continue; // file deleted — not a checksum issue
+        const content = (0, node_fs_1.readFileSync)(file.path, 'utf-8');
+        const currentHash = checksum(content);
+        if (currentHash !== migration.checksum) {
+            mismatches.push({
+                name: migration.name,
+                expected: migration.checksum,
+                actual: currentHash,
+            });
+        }
+    }
+    return mismatches;
+}
+/**
+ * Apply all pending migrations (UP).
+ *
+ * Features:
+ * - Idempotent: running twice is safe (already-applied migrations are skipped)
+ * - Advisory lock: prevents concurrent migration runs
+ * - Checksum validation: detects modified migration files
+ * - Each migration runs in its own transaction
+ */
+async function migrateUp(connectionString, migrationsDir, options) {
+    const client = new pg_1.default.Client({ connectionString });
+    await client.connect();
+    try {
+        // Acquire advisory lock to prevent concurrent migrations
+        const gotLock = await acquireLock(client);
+        if (!gotLock) {
+            return {
+                applied: [],
+                errors: [{
+                        file: { filename: '', path: '', name: '', timestamp: '' },
+                        error: 'Could not acquire migration lock — another migration is already running',
+                    }],
+            };
+        }
+        try {
+            await ensureTrackingTable(client);
+            // Validate checksums of already-applied migrations
+            const mismatches = await validateChecksums(client, migrationsDir);
+            if (mismatches.length > 0) {
+                const names = mismatches.map((m) => m.name).join(', ');
+                return {
+                    applied: [],
+                    errors: [{
+                            file: { filename: '', path: '', name: '', timestamp: '' },
+                            error: `Checksum mismatch: migration file(s) modified after application: ${names}. This is dangerous — applied migrations should be immutable. Use --force to skip this check.`,
+                        }],
+                };
+            }
+            const applied = await getAppliedMigrations(client);
+            const appliedNames = new Set(applied.map((m) => m.name));
+            const allFiles = listMigrationFiles(migrationsDir);
+            let pending = allFiles.filter((f) => !appliedNames.has(f.name));
+            if (options?.step != null && options.step > 0) {
+                pending = pending.slice(0, options.step);
+            }
+            const results = [];
+            const errors = [];
+            for (const file of pending) {
+                const { up } = parseMigrationSQL(file.path);
+                if (!up) {
+                    errors.push({ file, error: 'No UP section found in migration file' });
+                    continue;
+                }
+                const content = (0, node_fs_1.readFileSync)(file.path, 'utf-8');
+                const hash = checksum(content);
+                try {
+                    await client.query('BEGIN');
+                    await client.query(up);
+                    await client.query(`INSERT INTO ${TRACKING_TABLE} (name, checksum) VALUES ($1, $2) ON CONFLICT (name) DO NOTHING`, [file.name, hash]);
+                    await client.query('COMMIT');
+                    results.push(file);
+                }
+                catch (err) {
+                    await client.query('ROLLBACK');
+                    const msg = err instanceof Error ? err.message : String(err);
+                    errors.push({ file, error: msg });
+                    // Stop on first error
+                    break;
+                }
+            }
+            return { applied: results, errors };
+        }
+        finally {
+            await releaseLock(client);
+        }
+    }
+    finally {
+        await client.end();
+    }
+}
+/**
+ * Rollback the last N migrations (DOWN).
+ *
+ * Features:
+ * - Advisory lock: prevents concurrent rollback runs
+ * - Each rollback runs in its own transaction
+ * - Properly reverses changes in reverse application order
+ */
+async function migrateDown(connectionString, migrationsDir, options) {
+    const client = new pg_1.default.Client({ connectionString });
+    await client.connect();
+    try {
+        const gotLock = await acquireLock(client);
+        if (!gotLock) {
+            return {
+                rolledBack: [],
+                errors: [{
+                        file: { filename: '', path: '', name: '', timestamp: '' },
+                        error: 'Could not acquire migration lock — another migration is already running',
+                    }],
+            };
+        }
+        try {
+            await ensureTrackingTable(client);
+            const applied = await getAppliedMigrations(client);
+            if (applied.length === 0) {
+                return { rolledBack: [], errors: [] };
+            }
+            const allFiles = listMigrationFiles(migrationsDir);
+            const fileMap = new Map(allFiles.map((f) => [f.name, f]));
+            // Reverse order — rollback most recent first
+            const toRollback = applied.reverse().slice(0, options?.step ?? 1);
+            const results = [];
+            const errors = [];
+            for (const migration of toRollback) {
+                const file = fileMap.get(migration.name);
+                if (!file) {
+                    errors.push({
+                        file: { filename: migration.name + '.sql', path: '', name: migration.name, timestamp: '' },
+                        error: `Migration file not found for "${migration.name}"`,
+                    });
+                    continue;
+                }
+                const { down } = parseMigrationSQL(file.path);
+                if (!down) {
+                    errors.push({ file, error: 'No DOWN section found in migration file' });
+                    continue;
+                }
+                try {
+                    await client.query('BEGIN');
+                    await client.query(down);
+                    await client.query(`DELETE FROM ${TRACKING_TABLE} WHERE name = $1`, [migration.name]);
+                    await client.query('COMMIT');
+                    results.push(file);
+                }
+                catch (err) {
+                    await client.query('ROLLBACK');
+                    const msg = err instanceof Error ? err.message : String(err);
+                    errors.push({ file, error: msg });
+                    break;
+                }
+            }
+            return { rolledBack: results, errors };
+        }
+        finally {
+            await releaseLock(client);
+        }
+    }
+    finally {
+        await client.end();
+    }
+}
+/**
+ * Get the status of all migrations (applied vs pending).
+ * Includes checksum validation for applied migrations.
+ */
+async function migrateStatus(connectionString, migrationsDir) {
+    const client = new pg_1.default.Client({ connectionString });
+    await client.connect();
+    try {
+        await ensureTrackingTable(client);
+        const applied = await getAppliedMigrations(client);
+        const appliedMap = new Map(applied.map((m) => [m.name, m]));
+        const allFiles = listMigrationFiles(migrationsDir);
+        return allFiles.map((file) => {
+            const record = appliedMap.get(file.name);
+            let checksumValid;
+            if (record) {
+                const content = (0, node_fs_1.readFileSync)(file.path, 'utf-8');
+                const currentHash = checksum(content);
+                checksumValid = currentHash === record.checksum;
+            }
+            return {
+                file,
+                applied: !!record,
+                appliedAt: record?.applied_at,
+                checksumValid,
+            };
+        });
+    }
+    finally {
+        await client.end();
+    }
+}

package/dist/cjs/cli/ui.js

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * turbine-orm CLI — UI utilities
+ *
+ * ANSI colors, spinners, box-drawing, and formatting helpers.
+ * Zero dependencies — raw escape codes only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Spinner = exports.symbols = exports.bgCyan = exports.bgYellow = exports.bgRed = exports.bgGreen = exports.redBright = exports.yellowBright = exports.cyanBright = exports.greenBright = exports.gray = exports.white = exports.cyan = exports.magenta = exports.blue = exports.yellow = exports.green = exports.red = exports.underline = exports.italic = exports.dim = exports.bold = void 0;
+exports.box = box;
+exports.table = table;
+exports.header = header;
+exports.success = success;
+exports.error = error;
+exports.warn = warn;
+exports.info = info;
+exports.label = label;
+exports.newline = newline;
+exports.divider = divider;
+exports.banner = banner;
+exports.elapsed = elapsed;
+exports.stripAnsi = stripAnsi;
+exports.redactUrl = redactUrl;
+// ---------------------------------------------------------------------------
+// ANSI escape codes
+// ---------------------------------------------------------------------------
+const isColorSupported = process.env['NO_COLOR'] == null &&
+    process.env['TERM'] !== 'dumb' &&
+    (process.stdout.isTTY ?? false);
+function code(open, close) {
+    if (!isColorSupported)
+        return (s) => s;
+    return (s) => `\x1b[${open}m${s}\x1b[${close}m`;
+}
+exports.bold = code('1', '22');
+exports.dim = code('2', '22');
+exports.italic = code('3', '23');
+exports.underline = code('4', '24');
+exports.red = code('31', '39');
+exports.green = code('32', '39');
+exports.yellow = code('33', '39');
+exports.blue = code('34', '39');
+exports.magenta = code('35', '39');
+exports.cyan = code('36', '39');
+exports.white = code('37', '39');
+exports.gray = code('90', '39');
+// Bright variants
+exports.greenBright = code('92', '39');
+exports.cyanBright = code('96', '39');
+exports.yellowBright = code('93', '39');
+exports.redBright = code('91', '39');
+// Background
+exports.bgGreen = code('42', '49');
+exports.bgRed = code('41', '49');
+exports.bgYellow = code('43', '49');
+exports.bgCyan = code('46', '49');
+// ---------------------------------------------------------------------------
+// Symbols
+// ---------------------------------------------------------------------------
+exports.symbols = {
+    check: isColorSupported ? '\u2713' : 'v',
+    cross: isColorSupported ? '\u2717' : 'x',
+    bullet: isColorSupported ? '\u2022' : '*',
+    arrow: isColorSupported ? '\u2192' : '->',
+    arrowRight: isColorSupported ? '\u25B8' : '>',
+    info: isColorSupported ? '\u2139' : 'i',
+    warning: isColorSupported ? '\u26A0' : '!',
+    dot: isColorSupported ? '\u2219' : '.',
+    line: isColorSupported ? '\u2500' : '-',
+    vertLine: isColorSupported ? '\u2502' : '|',
+    topLeft: isColorSupported ? '\u256D' : '+',
+    topRight: isColorSupported ? '\u256E' : '+',
+    bottomLeft: isColorSupported ? '\u2570' : '+',
+    bottomRight: isColorSupported ? '\u256F' : '+',
+    tee: isColorSupported ? '\u251C' : '|',
+    teeEnd: isColorSupported ? '\u2514' : '\\',
+};
+// ---------------------------------------------------------------------------
+// Box drawing
+// ---------------------------------------------------------------------------
+function box(content, options) {
+    const padding = options?.padding ?? 1;
+    const lines = content.split('\n');
+    const pad = ' '.repeat(padding);
+    // Calculate max width (strip ANSI for measurement)
+    const maxWidth = Math.max(...lines.map((l) => stripAnsi(l).length), options?.title ? stripAnsi(options.title).length + 2 : 0);
+    const innerWidth = maxWidth + padding * 2;
+    const top = options?.title
+        ? `${exports.symbols.topLeft}${exports.symbols.line} ${options.title} ${exports.symbols.line.repeat(Math.max(0, innerWidth - stripAnsi(options.title).length - 3))}${exports.symbols.topRight}`
+        : `${exports.symbols.topLeft}${exports.symbols.line.repeat(innerWidth)}${exports.symbols.topRight}`;
+    const bottom = `${exports.symbols.bottomLeft}${exports.symbols.line.repeat(innerWidth)}${exports.symbols.bottomRight}`;
+    const body = lines.map((line) => {
+        const stripped = stripAnsi(line);
+        const rightPad = ' '.repeat(Math.max(0, maxWidth - stripped.length));
+        return `${exports.symbols.vertLine}${pad}${line}${rightPad}${pad}${exports.symbols.vertLine}`;
+    });
+    return [top, ...body, bottom].join('\n');
+}
+// ---------------------------------------------------------------------------
+// Table formatting
+// ---------------------------------------------------------------------------
+function table(headers, rows) {
+    const colWidths = headers.map((h, i) => {
+        const dataMax = rows.reduce((max, row) => {
+            const cell = row[i] ?? '';
+            return Math.max(max, stripAnsi(cell).length);
+        }, 0);
+        return Math.max(stripAnsi(h).length, dataMax);
+    });
+    const headerLine = headers
+        .map((h, i) => {
+        const w = colWidths[i];
+        return ` ${(0, exports.bold)(h)}${' '.repeat(Math.max(0, w - stripAnsi(h).length))} `;
+    })
+        .join((0, exports.dim)(exports.symbols.vertLine));
+    const separator = colWidths
+        .map((w) => exports.symbols.line.repeat(w + 2))
+        .join((0, exports.dim)(exports.symbols.line));
+    const bodyLines = rows.map((row) => row
+        .map((cell, i) => {
+        const w = colWidths[i];
+        return ` ${cell}${' '.repeat(Math.max(0, w - stripAnsi(cell).length))} `;
+    })
+        .join((0, exports.dim)(exports.symbols.vertLine)));
+    return [headerLine, (0, exports.dim)(separator), ...bodyLines].join('\n');
+}
+// ---------------------------------------------------------------------------
+// Spinner (simple dots animation)
+// ---------------------------------------------------------------------------
+class Spinner {
+    frames = ['   ', '.  ', '.. ', '...', ' ..', '  .'];
+    frameIndex = 0;
+    interval = null;
+    message;
+    constructor(message) {
+        this.message = message;
+    }
+    start() {
+        if (!isColorSupported || !process.stdout.isTTY) {
+            process.stdout.write(`  ${this.message}...\n`);
+            return this;
+        }
+        this.interval = setInterval(() => {
+            const frame = this.frames[this.frameIndex % this.frames.length];
+            process.stdout.write(`\r  ${(0, exports.cyan)(frame)} ${this.message}`);
+            this.frameIndex++;
+        }, 120);
+        return this;
+    }
+    succeed(msg) {
+        this.stop();
+        const text = msg ?? this.message;
+        process.stdout.write(`\r  ${(0, exports.green)(exports.symbols.check)} ${text}\n`);
+    }
+    fail(msg) {
+        this.stop();
+        const text = msg ?? this.message;
+        process.stdout.write(`\r  ${(0, exports.red)(exports.symbols.cross)} ${text}\n`);
+    }
+    info(msg) {
+        this.stop();
+        const text = msg ?? this.message;
+        process.stdout.write(`\r  ${(0, exports.blue)(exports.symbols.info)} ${text}\n`);
+    }
+    stop() {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+            // Clear the line
+            if (isColorSupported && process.stdout.isTTY) {
+                process.stdout.write('\r\x1b[K');
+            }
+        }
+    }
+}
+exports.Spinner = Spinner;
+// ---------------------------------------------------------------------------
+// Logging helpers
+// ---------------------------------------------------------------------------
+function header(text) {
+    console.log('');
+    console.log(`  ${(0, exports.bold)((0, exports.cyan)(text))}`);
+    console.log('');
+}
+function success(msg) {
+    console.log(`  ${(0, exports.green)(exports.symbols.check)} ${msg}`);
+}
+function error(msg) {
+    console.log(`  ${(0, exports.red)(exports.symbols.cross)} ${msg}`);
+}
+function warn(msg) {
+    console.log(`  ${(0, exports.yellow)(exports.symbols.warning)} ${msg}`);
+}
+function info(msg) {
+    console.log(`  ${(0, exports.blue)(exports.symbols.info)} ${msg}`);
+}
+function label(key, value) {
+    console.log(`  ${(0, exports.dim)(key + ':')} ${value}`);
+}
+function newline() {
+    console.log('');
+}
+function divider() {
+    const width = Math.min(process.stdout.columns ?? 60, 60);
+    console.log(`  ${(0, exports.dim)(exports.symbols.line.repeat(width - 4))}`);
+}
+// ---------------------------------------------------------------------------
+// Banner
+// ---------------------------------------------------------------------------
+function banner() {
+    console.log('');
+    console.log(`  ${(0, exports.bold)((0, exports.cyan)('turbine'))} ${(0, exports.dim)('by')} ${(0, exports.bold)('BataData')}`);
+    console.log(`  ${(0, exports.dim)('TypeScript ORM with json_agg nested queries')}`);
+    console.log('');
+}
+// ---------------------------------------------------------------------------
+// Elapsed time formatting
+// ---------------------------------------------------------------------------
+function elapsed(startMs) {
+    const ms = performance.now() - startMs;
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    return `${(ms / 1000).toFixed(2)}s`;
+}
+// ---------------------------------------------------------------------------
+// Strip ANSI codes (for width calculation)
+// ---------------------------------------------------------------------------
+function stripAnsi(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\x1b\[[0-9;]*m/g, '');
+}
+// ---------------------------------------------------------------------------
+// Redact password from connection URL
+// ---------------------------------------------------------------------------
+function redactUrl(url) {
+    return url.replace(/:([^@/:]+)@/, ':***@');
+}