ts-prorm-orm 1.1.0

package/dist/replica-manager.js

@@ -0,0 +1,507 @@
+"use strict";
+/**
+ * Replica Manager for handling read replicas with lag detection
+ * Supports multiple database dialects with dialect-specific lag detection queries
+ */
+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.ReplicaManager = exports.ReplicaRoutingStrategy = void 0;
+const events_1 = require("events");
+/**
+ * Routing strategy for selecting a replica.
+ *
+ * Companion enum to the `RoutingStrategy` string-literal union below.
+ * Use either `ReplicaRoutingStrategy.RoundRobin` or the raw string
+ * `'round-robin'` (and so on) — both are accepted wherever a
+ * `RoutingStrategy` is expected.
+ */
+var ReplicaRoutingStrategy;
+(function (ReplicaRoutingStrategy) {
+    ReplicaRoutingStrategy["RoundRobin"] = "round-robin";
+    ReplicaRoutingStrategy["LeastConnections"] = "least-connections";
+    ReplicaRoutingStrategy["LowestLag"] = "lowest-lag";
+})(ReplicaRoutingStrategy || (exports.ReplicaRoutingStrategy = ReplicaRoutingStrategy = {}));
+/**
+ * Replica connection pool wrapper
+ */
+class ReplicaPool {
+    constructor(config) {
+        this.name = config.name;
+        this.config = config;
+    }
+    async initialize(dialectModule) {
+        this.dialectModule = dialectModule;
+        // Create dialect and pool based on the replica's configured dialect
+        // (not the replica's *name*, which is an arbitrary label a caller could
+        // set to anything - e.g. a Postgres replica named "read-1" was previously
+        // silently treated as an unsupported dialect).
+        const dialectName = this.config.dialect.toLowerCase();
+        if (dialectName.includes('mysql') || dialectName.includes('mariadb')) {
+            const mysql = await Promise.resolve().then(() => __importStar(require('mysql2/promise')));
+            this.pool = mysql.createPool({
+                host: this.config.host,
+                port: this.config.port,
+                user: this.config.username,
+                password: this.config.password,
+                database: this.config.database,
+                waitForConnections: true,
+                connectionLimit: this.config.pool?.max || 10,
+                queueLimit: 0,
+            });
+        }
+        else if (dialectName.includes('postgres')) {
+            const { Pool } = await Promise.resolve().then(() => __importStar(require('pg')));
+            this.pool = new Pool({
+                host: this.config.host,
+                port: this.config.port,
+                user: this.config.username,
+                password: this.config.password,
+                database: this.config.database,
+                max: this.config.pool?.max || 10,
+            });
+        }
+    }
+    getPool() {
+        return this.pool;
+    }
+    getName() {
+        return this.name;
+    }
+    getDialect() {
+        return this.config.dialect;
+    }
+    async getConnection() {
+        if (!this.pool) {
+            throw new Error(`Pool not initialized for replica ${this.name}`);
+        }
+        if (this.config.dialect.toLowerCase().includes('mysql') || this.config.dialect.toLowerCase().includes('mariadb')) {
+            return this.pool.getConnection();
+        }
+        else if (this.config.dialect.toLowerCase().includes('postgres')) {
+            return this.pool.connect();
+        }
+        throw new Error(`Unsupported dialect for replica ${this.name}`);
+    }
+    async releaseConnection(connection) {
+        if (!this.pool)
+            return;
+        if (this.config.dialect.toLowerCase().includes('mysql') || this.config.dialect.toLowerCase().includes('mariadb')) {
+            connection.release();
+        }
+        else if (this.config.dialect.toLowerCase().includes('postgres')) {
+            connection.release();
+        }
+    }
+    async close() {
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = null;
+        }
+    }
+    async query(sql, options) {
+        const connection = await this.getConnection();
+        try {
+            if (this.config.dialect.toLowerCase().includes('mysql') || this.config.dialect.toLowerCase().includes('mariadb')) {
+                const [rows] = await connection.query(sql);
+                return { rows };
+            }
+            else if (this.config.dialect.toLowerCase().includes('postgres')) {
+                const result = await connection.query(sql);
+                return { rows: result.rows };
+            }
+            throw new Error(`Unsupported dialect for replica ${this.name}`);
+        }
+        finally {
+            this.releaseConnection(connection);
+        }
+    }
+}
+/**
+ * ReplicaManager class for managing read replicas with lag detection
+ */
+class ReplicaManager extends events_1.EventEmitter {
+    /**
+     * Create a new ReplicaManager
+     */
+    constructor(options) {
+        super();
+        this.replicas = new Map();
+        this.replicaStats = new Map();
+        this.roundRobinIndex = 0;
+        this.monitorInterval = null;
+        this.masterConfig = null;
+        this.lagDetectionConfig = {
+            enabled: options?.lagDetection?.enabled ?? true,
+            interval: options?.lagDetection?.interval ?? 5000,
+            timeout: options?.lagDetection?.timeout ?? 5000,
+            maxAcceptableLag: options?.lagDetection?.maxAcceptableLag ?? 2000,
+            maxFailures: options?.lagDetection?.maxFailures ?? 3,
+        };
+        this.routingStrategy = options?.defaultRoutingStrategy ?? 'round-robin';
+        this.masterConfig = options?.master ?? null;
+    }
+    /**
+     * Add a replica to the manager
+     */
+    async addReplica(config) {
+        if (this.replicas.has(config.name)) {
+            throw new Error(`Replica with name ${config.name} already exists`);
+        }
+        const pool = new ReplicaPool(config);
+        pool.initialize({});
+        this.replicas.set(config.name, pool);
+        // Initialize status
+        this.replicaStats.set(config.name, {
+            name: config.name,
+            healthy: false,
+            lag: null,
+            activeConnections: 0,
+            lastCheck: new Date(),
+        });
+        this.emit('replica:added', config.name);
+    }
+    /**
+     * Remove a replica from the manager
+     */
+    async removeReplica(name) {
+        const pool = this.replicas.get(name);
+        if (!pool) {
+            throw new Error(`Replica ${name} not found`);
+        }
+        await pool.close();
+        this.replicas.delete(name);
+        this.replicaStats.delete(name);
+        this.emit('replica:removed', name);
+    }
+    /**
+     * Get a replica by name
+     */
+    getReplica(name) {
+        return this.replicas.get(name);
+    }
+    /**
+     * Get all replica names
+     */
+    getReplicaNames() {
+        return Array.from(this.replicas.keys());
+    }
+    /**
+     * Check replication lag for a specific replica
+     * Uses dialect-specific queries for lag detection
+     */
+    async checkLag(name) {
+        const pool = this.replicas.get(name);
+        if (!pool) {
+            throw new Error(`Replica ${name} not found`);
+        }
+        const replicaDialect = pool.getDialect().toLowerCase();
+        let lagQuery;
+        let lag = null;
+        try {
+            // Determine the lag detection query based on the replica's configured
+            // dialect (not its arbitrary display name - see the ReplicaPool fix
+            // above for why name-based dialect guessing is unreliable).
+            if (replicaDialect.includes('mysql') || replicaDialect.includes('mariadb')) {
+                // MySQL/MariaDB: Use SHOW SLAVE STATUS to get Seconds_Behind_Master
+                lagQuery = 'SHOW SLAVE STATUS';
+                const result = await pool.query(lagQuery);
+                if (result.rows && result.rows.length > 0) {
+                    const slaveStatus = result.rows[0];
+                    const secondsBehind = slaveStatus.Seconds_Behind_Master;
+                    lag = secondsBehind !== null && secondsBehind !== undefined
+                        ? Number(secondsBehind) * 1000 // Convert seconds to milliseconds
+                        : null;
+                }
+            }
+            else if (replicaDialect.includes('postgres')) {
+                // PostgreSQL: Use pg_last_xact_replay_timestamp()
+                lagQuery = "SELECT EXTRACT(EPOCH FROM (now() - pg_last_xact_replay_timestamp())) * 1000 AS lag";
+                const result = await pool.query(lagQuery);
+                if (result.rows && result.rows.length > 0) {
+                    lag = result.rows[0]?.lag ? Math.round(Number(result.rows[0].lag)) : null;
+                }
+            }
+            else {
+                // For other dialects, return null (not supported)
+                console.warn(`Lag detection not supported for dialect: ${replicaDialect}`);
+                return null;
+            }
+            // Update stats
+            const stats = this.replicaStats.get(name);
+            if (stats) {
+                stats.lag = lag;
+                stats.lastCheck = new Date();
+                stats.error = undefined;
+            }
+            if (lag !== null) {
+                this.emit('replica:lag-detected', name, lag);
+            }
+            return lag;
+        }
+        catch (error) {
+            // Update stats with error
+            const stats = this.replicaStats.get(name);
+            if (stats) {
+                stats.lag = null;
+                stats.lastCheck = new Date();
+                stats.error = error instanceof Error ? error.message : 'Unknown error';
+            }
+            throw error;
+        }
+    }
+    /**
+     * Start the lag monitoring loop
+     */
+    startLagMonitor() {
+        if (this.monitorInterval) {
+            console.warn('Lag monitor already running');
+            return;
+        }
+        const checkAllLags = async () => {
+            for (const name of Array.from(this.replicas.keys())) {
+                try {
+                    const lag = await this.checkLag(name);
+                    const stats = this.replicaStats.get(name);
+                    if (stats) {
+                        const wasHealthy = stats.healthy;
+                        stats.healthy = lag !== null && lag <= this.lagDetectionConfig.maxAcceptableLag;
+                        if (!wasHealthy && stats.healthy) {
+                            this.emit('replica:healthy', name, stats);
+                        }
+                        else if (wasHealthy && !stats.healthy) {
+                            this.emit('replica:unhealthy', name, stats);
+                        }
+                    }
+                    // Check if all replicas are unhealthy
+                    const allStats = Array.from(this.replicaStats.values());
+                    const allUnhealthy = allStats.every(s => !s.healthy);
+                    if (allUnhealthy && this.replicas.size > 0) {
+                        this.emit('all-replicas-unhealthy');
+                    }
+                }
+                catch (error) {
+                    console.error(`Error checking lag for replica ${name}:`, error);
+                    // A failed lag check means we can't confirm this replica is caught
+                    // up - and if the connection itself is down, it can't serve reads
+                    // either. Mark it unhealthy rather than silently leaving stale
+                    // (possibly "healthy") stats in place, which would keep routing
+                    // reads to a replica that's actually unreachable.
+                    const stats = this.replicaStats.get(name);
+                    if (stats) {
+                        const wasHealthy = stats.healthy;
+                        stats.healthy = false;
+                        stats.lastCheck = new Date();
+                        stats.error = error instanceof Error ? error.message : 'Unknown error';
+                        if (wasHealthy) {
+                            this.emit('replica:unhealthy', name, stats);
+                        }
+                    }
+                    const allStats = Array.from(this.replicaStats.values());
+                    if (allStats.length > 0 && allStats.every((s) => !s.healthy) && this.replicas.size > 0) {
+                        this.emit('all-replicas-unhealthy');
+                    }
+                }
+            }
+        };
+        // Run initial check
+        checkAllLags();
+        // Set up interval
+        this.monitorInterval = setInterval(checkAllLags, this.lagDetectionConfig.interval);
+        this.emit('monitor:started');
+    }
+    /**
+     * Stop the lag monitoring loop
+     */
+    stopLagMonitor() {
+        if (this.monitorInterval) {
+            clearInterval(this.monitorInterval);
+            this.monitorInterval = null;
+            this.emit('monitor:stopped');
+        }
+    }
+    /**
+     * Get statistics for all replicas
+     */
+    getReplicaStats() {
+        return new Map(this.replicaStats);
+    }
+    /**
+     * Get statistics for a specific replica
+     */
+    getReplicaStat(name) {
+        return this.replicaStats.get(name);
+    }
+    /**
+     * Set the routing strategy
+     */
+    setRoutingStrategy(strategy) {
+        this.routingStrategy = strategy;
+    }
+    /**
+     * Get the current routing strategy
+     */
+    getRoutingStrategy() {
+        return this.routingStrategy;
+    }
+    /**
+     * Select a replica based on the current routing strategy
+     */
+    async selectReplica() {
+        if (this.replicas.size === 0) {
+            throw new Error('No replicas available');
+        }
+        const names = Array.from(this.replicas.keys());
+        let selectedName;
+        // Round-robin should still skip known-unhealthy replicas where possible -
+        // previously it cycled through every name unconditionally, so an
+        // unhealthy replica still received its turn in rotation. Fall back to
+        // the full name list only if there are no healthy replicas at all (e.g.
+        // before the first lag-check cycle has run), so selection never throws.
+        const healthyNames = names.filter((name) => this.replicaStats.get(name)?.healthy !== false);
+        const roundRobinPool = healthyNames.length > 0 ? healthyNames : names;
+        switch (this.routingStrategy) {
+            case 'round-robin':
+                selectedName = roundRobinPool[this.roundRobinIndex % roundRobinPool.length];
+                this.roundRobinIndex++;
+                break;
+            case 'least-connections':
+                let minConnections = Infinity;
+                for (const name of names) {
+                    const stats = this.replicaStats.get(name);
+                    if (stats && stats.healthy && stats.activeConnections < minConnections) {
+                        minConnections = stats.activeConnections;
+                        selectedName = name;
+                    }
+                }
+                if (!selectedName) {
+                    // Fallback to round-robin if all have same connections or none are healthy
+                    selectedName = roundRobinPool[this.roundRobinIndex % roundRobinPool.length];
+                    this.roundRobinIndex++;
+                }
+                break;
+            case 'lowest-lag':
+                let minLag = Infinity;
+                for (const name of names) {
+                    const stats = this.replicaStats.get(name);
+                    if (stats && stats.healthy && stats.lag !== null && stats.lag < minLag) {
+                        minLag = stats.lag;
+                        selectedName = name;
+                    }
+                }
+                if (!selectedName) {
+                    // Fallback to round-robin if all have same lag or none are healthy
+                    selectedName = roundRobinPool[this.roundRobinIndex % roundRobinPool.length];
+                    this.roundRobinIndex++;
+                }
+                break;
+            default:
+                selectedName = roundRobinPool[this.roundRobinIndex % roundRobinPool.length];
+                this.roundRobinIndex++;
+        }
+        const pool = this.replicas.get(selectedName);
+        // Update active connections
+        const stats = this.replicaStats.get(selectedName);
+        if (stats) {
+            stats.activeConnections++;
+        }
+        this.emit('replica:selected', selectedName);
+        return { name: selectedName, pool };
+    }
+    /**
+     * Execute a query on a replica (auto-selects replica based on routing strategy)
+     */
+    async queryReplica(sql, options) {
+        const { name, pool } = await this.selectReplica();
+        const result = await pool.query(sql, options);
+        // Decrease active connections after query completes
+        const stats = this.replicaStats.get(name);
+        if (stats && stats.activeConnections > 0) {
+            stats.activeConnections--;
+        }
+        return result;
+    }
+    /**
+     * Get healthy replicas
+     */
+    getHealthyReplicas() {
+        const healthy = [];
+        for (const [name, stats] of Array.from(this.replicaStats.entries())) {
+            if (stats.healthy) {
+                healthy.push(name);
+            }
+        }
+        return healthy;
+    }
+    /**
+     * Get replica count
+     */
+    getReplicaCount() {
+        return this.replicas.size;
+    }
+    /**
+     * Check if replication is enabled
+     */
+    isReplicationEnabled() {
+        return this.replicas.size > 0;
+    }
+    /**
+     * Set lag detection configuration
+     */
+    setLagDetectionConfig(config) {
+        this.lagDetectionConfig = {
+            ...this.lagDetectionConfig,
+            ...config,
+        };
+    }
+    /**
+     * Get lag detection configuration
+     */
+    getLagDetectionConfig() {
+        return { ...this.lagDetectionConfig };
+    }
+    /**
+     * Close all replica connections
+     */
+    async close() {
+        this.stopLagMonitor();
+        for (const pool of Array.from(this.replicas.values())) {
+            await pool.close();
+        }
+        this.replicas.clear();
+        this.replicaStats.clear();
+    }
+}
+exports.ReplicaManager = ReplicaManager;
+exports.default = ReplicaManager;

package/dist/schema/index.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Schema Module - Automated schema diffing and migration generation
+ * Exports classes and functions for comparing model definitions against database schema
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMigrationGenerator = exports.MigrationGenerator = exports.createSchemaDiffer = exports.SchemaDiffer = void 0;
+// Re-export SchemaDiffer
+var schema_differ_1 = require("./schema-differ");
+Object.defineProperty(exports, "SchemaDiffer", { enumerable: true, get: function () { return schema_differ_1.SchemaDiffer; } });
+Object.defineProperty(exports, "createSchemaDiffer", { enumerable: true, get: function () { return schema_differ_1.createSchemaDiffer; } });
+// Re-export MigrationGenerator
+var migration_generator_1 = require("./migration-generator");
+Object.defineProperty(exports, "MigrationGenerator", { enumerable: true, get: function () { return migration_generator_1.MigrationGenerator; } });
+Object.defineProperty(exports, "createMigrationGenerator", { enumerable: true, get: function () { return migration_generator_1.createMigrationGenerator; } });