ts-prorm-orm 1.1.0

package/dist/connection-manager.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * Connection Manager for managing multiple named database connections
+ * Supports cross-database queries and SQLite ATTACH DATABASE
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionManager = void 0;
+exports.createConnectionManager = createConnectionManager;
+const prorm_1 = require("./prorm");
+/**
+ * Connection Manager class for managing multiple database connections
+ * Allows switching between different databases in the same application
+ */
+class ConnectionManager {
+    /**
+     * Create a new ConnectionManager instance
+     */
+    constructor() {
+        this.connections = new Map();
+        this._defaultConnection = null;
+    }
+    /**
+     * Add a new named database connection
+     * @param name - Unique name to identify this connection
+     * @param options - Prorm options for the connection
+     * @returns The Prorm instance for the new connection
+     * @example
+     * // Add a secondary SQLite database
+     * const manager = new ConnectionManager();
+     * await manager.addConnection('analytics', {
+     *   dialect: 'sqlite',
+     *   storage: './analytics.db'
+     * });
+     */
+    async addConnection(name, options) {
+        if (this.connections.has(name)) {
+            throw new Error(`Connection with name '${name}' already exists`);
+        }
+        const prorm = new prorm_1.Prorm(options);
+        this.connections.set(name, prorm);
+        // Set as default if it's the first connection
+        if (this._defaultConnection === null) {
+            this._defaultConnection = name;
+        }
+        return prorm;
+    }
+    /**
+     * Get a connection by name
+     * @param name - The connection name
+     * @returns The Prorm instance or undefined if not found
+     * @example
+     * const analyticsDb = manager.getConnection('analytics');
+     */
+    getConnection(name) {
+        return this.connections.get(name);
+    }
+    /**
+     * Check if a connection exists
+     * @param name - The connection name to check
+     * @returns True if the connection exists
+     * @example
+     * if (manager.hasConnection('analytics')) {
+     *   // Use analytics connection
+     * }
+     */
+    hasConnection(name) {
+        return this.connections.has(name);
+    }
+    /**
+     * Remove a connection by name
+     * @param name - The connection name to remove
+     * @returns True if the connection was removed
+     * @example
+     * await manager.removeConnection('analytics');
+     */
+    async removeConnection(name) {
+        const prorm = this.connections.get(name);
+        if (!prorm) {
+            return false;
+        }
+        // Close the connection
+        await prorm.close();
+        this.connections.delete(name);
+        // Update default if needed
+        if (this._defaultConnection === name) {
+            const remaining = Array.from(this.connections.keys());
+            this._defaultConnection = remaining.length > 0 ? remaining[0] : null;
+        }
+        return true;
+    }
+    /**
+     * Get all connection names
+     * @returns Array of connection names
+     * @example
+     * const names = manager.getConnectionNames();
+     * // ['main', 'analytics', 'logs']
+     */
+    getConnectionNames() {
+        return Array.from(this.connections.keys());
+    }
+    /**
+     * Get or set the default connection name
+     */
+    get defaultConnection() {
+        return this._defaultConnection;
+    }
+    set defaultConnection(name) {
+        if (name !== null && !this.connections.has(name)) {
+            throw new Error(`Connection with name '${name}' does not exist`);
+        }
+        this._defaultConnection = name;
+    }
+    /**
+     * Get all connections
+     * @returns Map of connection names to Prorm instances
+     */
+    get connectionsMap() {
+        return new Map(this.connections);
+    }
+    /**
+     * Attach a SQLite database using ATTACH DATABASE
+     * This allows querying across multiple SQLite files
+     * @param mainConnectionName - The name of the main connection to attach to
+     * @param alias - The alias to use for the attached database
+     * @param path - Path to the SQLite file to attach
+     * @example
+     * // Attach analytics database to main connection
+     * await manager.attachDatabase('main', 'analytics', './analytics.db');
+     * // Now you can query: SELECT * FROM analytics.users
+     */
+    async attachDatabase(mainConnectionName, alias, path) {
+        const prorm = this.connections.get(mainConnectionName);
+        if (!prorm) {
+            throw new Error(`Connection with name '${mainConnectionName}' not found`);
+        }
+        if (!alias || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(alias)) {
+            throw new Error(`Invalid database alias: ${alias}`);
+        }
+        // Execute ATTACH DATABASE query. `path` is bound as a parameter (not
+        // string-interpolated) since a raw path containing a single quote would
+        // otherwise break out of the literal; `alias` is validated above since
+        // it appears in an identifier position that can't be parameterized.
+        await prorm.query(`ATTACH DATABASE ? AS ${alias}`, { replacements: [path] });
+    }
+    /**
+     * Detach a SQLite database
+     * @param mainConnectionName - The name of the main connection
+     * @param alias - The alias of the database to detach
+     * @example
+     * await manager.detachDatabase('main', 'analytics');
+     */
+    async detachDatabase(mainConnectionName, alias) {
+        const prorm = this.connections.get(mainConnectionName);
+        if (!prorm) {
+            throw new Error(`Connection with name '${mainConnectionName}' not found`);
+        }
+        if (!alias || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(alias)) {
+            throw new Error(`Invalid database alias: ${alias}`);
+        }
+        await prorm.query(`DETACH DATABASE ${alias}`);
+    }
+    /**
+     * Close all connections
+     * @example
+     * await manager.closeAll();
+     */
+    async closeAll() {
+        const closePromises = Array.from(this.connections.values()).map((seq) => seq.close());
+        await Promise.all(closePromises);
+        this.connections.clear();
+        this._defaultConnection = null;
+    }
+    /**
+     * Execute a raw query on a specific connection
+     * @param connectionName - The name of the connection to use
+     * @param sql - The SQL query to execute
+     * @param options - Optional query options
+     * @returns Query results
+     * @example
+     * const results = await manager.query('main', 'SELECT * FROM users');
+     */
+    async query(connectionName, sql, options) {
+        const prorm = this.connections.get(connectionName);
+        if (!prorm) {
+            throw new Error(`Connection with name '${connectionName}' not found`);
+        }
+        return prorm.query(sql, options);
+    }
+}
+exports.ConnectionManager = ConnectionManager;
+/**
+ * Create a new ConnectionManager instance
+ * @example
+ * const manager = createConnectionManager();
+ */
+function createConnectionManager() {
+    return new ConnectionManager();
+}

package/dist/connection-pool.js

@@ -0,0 +1,519 @@
+"use strict";
+/**
+ * Connection Pool Management
+ * Manages a pool of database connections for efficient resource usage
+ * Includes health checks, connection validation, and comprehensive metrics
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseConnectionPool = exports.ConnectionPool = exports.PooledConnection = void 0;
+exports.createPool = createPool;
+const events_1 = require("events");
+/**
+ * Pooled connection wrapper with health tracking
+ */
+class PooledConnection {
+    constructor(connection, id) {
+        this.inUse = false;
+        this.metadata = {};
+        this.healthCheckFailures = 0;
+        this.lastHealthCheck = 0;
+        this.lastValidation = 0;
+        this.isHealthy = true;
+        this.id = id || `conn_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        this.connection = connection;
+        this.timestamp = Date.now();
+        this.connectTimestamp = Date.now();
+    }
+    /**
+     * Mark the connection as in use
+     */
+    markInUse() {
+        this.inUse = true;
+        this.timestamp = Date.now();
+    }
+    /**
+     * Release the connection back to the pool
+     */
+    release() {
+        this.inUse = false;
+        this.timestamp = Date.now();
+    }
+    /**
+     * Check if the connection is idle for too long
+     */
+    isIdle(timeout) {
+        return !this.inUse && Date.now() - this.timestamp > timeout;
+    }
+    /**
+     * Check if the connection has been idle longer than the given timeout
+     */
+    isIdleExceeding(timeout) {
+        return !this.inUse && Date.now() - this.timestamp > timeout;
+    }
+    /**
+     * Increment health check failure counter
+     */
+    recordHealthCheckFailure() {
+        this.healthCheckFailures++;
+        this.lastHealthCheck = Date.now();
+        if (this.healthCheckFailures > 3) {
+            this.isHealthy = false;
+        }
+    }
+    /**
+     * Reset health check failures on successful check
+     */
+    resetHealthCheckFailures() {
+        this.healthCheckFailures = 0;
+        this.isHealthy = true;
+        this.lastHealthCheck = Date.now();
+    }
+    /**
+     * Get connection age in milliseconds
+     */
+    getAge() {
+        return Date.now() - this.connectTimestamp;
+    }
+}
+exports.PooledConnection = PooledConnection;
+/**
+ * Connection Pool class
+ * Manages a pool of database connections with configurable limits
+ */
+class ConnectionPool extends events_1.EventEmitter {
+    /**
+     * Maximum number of connections in the pool
+     */
+    get max() {
+        return this.config.max ?? 10;
+    }
+    /**
+     * Minimum number of idle connections
+     */
+    get min() {
+        return this.config.min ?? 0;
+    }
+    /**
+     * Get the pending requests count
+     */
+    get pending() {
+        return this._pending;
+    }
+    /**
+     * Constructor
+     */
+    constructor(config) {
+        super();
+        this.connections = new Map();
+        this.waitingQueue = [];
+        this._isDestroyed = false;
+        // Statistics
+        this._size = 0;
+        this._available = 0;
+        this._inUse = 0;
+        this._acquired = 0;
+        this._released = 0;
+        this._destroyed = 0;
+        this._pending = 0;
+        this.config = {
+            max: 10,
+            min: 0,
+            acquire: 60000, // 60 seconds
+            idle: 30000, // 30 seconds
+            evict: 1000, // 1 second
+            ...config,
+        };
+        // Start eviction timer
+        this.startEvictor();
+    }
+    /**
+     * Initialize the pool with a factory function to create connections
+     */
+    async initialize() {
+        // Create minimum number of connections if specified
+        const createPromises = [];
+        const minConnections = this.config.min ?? 0;
+        for (let i = 0; i < minConnections; i++) {
+            createPromises.push(this.createConnection());
+        }
+        await Promise.allSettled(createPromises);
+    }
+    /**
+     * Get a connection from the pool
+     */
+    async getConnection() {
+        if (this.isDestroyed) {
+            throw new Error('Pool is destroyed');
+        }
+        // Try to find an available connection
+        const available = this.getAvailableConnection();
+        if (available) {
+            available.markInUse();
+            this._acquired++;
+            this._inUse++;
+            this._available--;
+            // Emit acquire event
+            this.emit('acquire', available.connection);
+            // Call onConnect callback if provided (Prorm-style)
+            if (this.config.onConnect) {
+                try {
+                    this.config.onConnect(available.connection);
+                }
+                catch (error) {
+                    this.emit('error', error);
+                }
+            }
+            // Legacy callback support
+            if (this.config.onAcquire) {
+                try {
+                    this.config.onAcquire(available.connection);
+                }
+                catch (error) {
+                    // Log but don't fail the connection acquisition
+                    console.error('onAcquire callback error:', error);
+                }
+            }
+            // Log pool operation if enabled
+            if (this.config.logPoolOperations) {
+                console.log(`[Pool] Connection acquired. Pool size: ${this.size}, available: ${this._available}, in use: ${this._inUse}`);
+            }
+            return available;
+        }
+        // If we can create more connections, do so
+        const maxConnections = this.config.max ?? 10;
+        if (this.connections.size < maxConnections) {
+            const connection = await this.createConnection();
+            connection.markInUse();
+            this._acquired++;
+            this._inUse++;
+            if (this.config.onAcquire) {
+                try {
+                    this.config.onAcquire(connection.connection);
+                }
+                catch (error) {
+                    console.error('onAcquire callback error:', error);
+                }
+            }
+            return connection;
+        }
+        // Wait for a connection to become available
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                // Remove from waiting queue
+                const index = this.waitingQueue.findIndex((w) => w.resolve === resolve);
+                if (index !== -1) {
+                    this.waitingQueue.splice(index, 1);
+                }
+                // Emit timeout event
+                this.emit('timeout', null);
+                reject(new Error(`Acquisition timeout after ${this.config.acquire}ms. Pool size: ${this.connections.size}, max: ${this.config.max}`));
+            }, this.config.acquire);
+            this.waitingQueue.push({ resolve, reject, timeoutId });
+        });
+    }
+    /**
+     * Release a connection back to the pool
+     */
+    releaseConnection(pooledConnection) {
+        if (this.isDestroyed) {
+            this.destroyConnection(pooledConnection);
+            return;
+        }
+        pooledConnection.release();
+        this._released++;
+        this._inUse--;
+        this._available++;
+        // Emit release event
+        this.emit('release', pooledConnection.connection);
+        // Call onDisconnect callback if provided (Prorm-style)
+        if (this.config.onDisconnect) {
+            try {
+                this.config.onDisconnect(pooledConnection.connection);
+            }
+            catch (error) {
+                this.emit('error', error);
+            }
+        }
+        // Legacy callback support
+        if (this.config.onRelease) {
+            try {
+                this.config.onRelease(pooledConnection.connection);
+            }
+            catch (error) {
+                console.error('onRelease callback error:', error);
+            }
+        }
+        // Log pool operations if enabled
+        if (this.config.logPoolOperations) {
+            console.log(`[Pool] Connection released. Pool size: ${this.size}, available: ${this._available}, in use: ${this._inUse}`);
+        }
+        // Process waiting queue
+        this.processWaitingQueue();
+    }
+    /**
+     * Destroy a connection
+     */
+    async destroyConnection(pooledConnection) {
+        const { connection } = pooledConnection;
+        // Remove from pool
+        this.connections.delete(pooledConnection.id);
+        this._size--;
+        this._destroyed++;
+        if (pooledConnection.inUse) {
+            this._inUse--;
+            this._available--;
+        }
+        // Emit remove event
+        this.emit('remove', connection);
+        if (this.config.onDestroy) {
+            try {
+                this.config.onDestroy(connection);
+            }
+            catch (error) {
+                this.emit('error', error);
+                console.error('onDestroy callback error:', error);
+            }
+        }
+        // Log pool operations if enabled
+        if (this.config.logPoolOperations) {
+            console.log(`[Pool] Connection removed. Pool size: ${this._size}, available: ${this._available}, in use: ${this._inUse}`);
+        }
+        // Close the actual connection if it has a close method
+        try {
+            if (typeof connection.close === 'function') {
+                await connection.close();
+            }
+            else if (typeof connection.end === 'function') {
+                await connection.end();
+            }
+            else if (typeof connection.disconnect === 'function') {
+                await connection.disconnect();
+            }
+        }
+        catch (error) {
+            console.error('Error closing connection:', error);
+        }
+    }
+    /**
+     * Destroy a specific connection or the entire pool
+     * @param connection - Optional connection to destroy. If not provided, destroys the entire pool
+     */
+    async destroy(connection) {
+        // If a connection is provided, destroy just that connection
+        if (connection) {
+            for (const [, pooledConnection] of this.connections) {
+                if (pooledConnection.connection === connection) {
+                    await this.destroyConnection(pooledConnection);
+                    return;
+                }
+            }
+            return;
+        }
+        // Otherwise destroy the entire pool
+        if (this._isDestroyed) {
+            return;
+        }
+        this._isDestroyed = true;
+        // Clear evict timer
+        if (this.evictTimer) {
+            clearInterval(this.evictTimer);
+            this.evictTimer = undefined;
+        }
+        // Reject waiting promises
+        for (const { reject, timeoutId } of this.waitingQueue) {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            reject(new Error('Pool is being destroyed'));
+        }
+        this.waitingQueue = [];
+        // Destroy all connections
+        const destroyPromises = [];
+        for (const [, pooledConnection] of this.connections) {
+            destroyPromises.push(this.destroyConnection(pooledConnection));
+        }
+        await Promise.all(destroyPromises);
+        this.connections.clear();
+        this._size = 0;
+        this._available = 0;
+        this._inUse = 0;
+    }
+    /**
+     * Get pool statistics
+     */
+    get stats() {
+        return {
+            size: this.connections.size,
+            available: this._available,
+            inUse: this._inUse,
+            acquired: this._acquired,
+            released: this._released,
+            destroyed: this._destroyed,
+            pending: this.waitingQueue.length,
+        };
+    }
+    /**
+     * Get the current pool size
+     */
+    get size() {
+        return this._size;
+    }
+    /**
+     * Get the number of available connections
+     */
+    get available() {
+        return this._available;
+    }
+    /**
+     * Get the number of connections in use
+     */
+    get inUse() {
+        return this._inUse;
+    }
+    /**
+     * Check if the pool is destroyed
+     */
+    get isDestroyed() {
+        return this._isDestroyed;
+    }
+    /**
+     * Get the number of connections in use (alias for inUse)
+     */
+    get used() {
+        return this._inUse;
+    }
+    /**
+     * Get an available connection from the pool
+     */
+    getAvailableConnection() {
+        for (const [, pooledConnection] of this.connections) {
+            if (!pooledConnection.inUse) {
+                return pooledConnection;
+            }
+        }
+        return null;
+    }
+    /**
+     * Create a new connection
+     */
+    async createConnection() {
+        if (this.isDestroyed) {
+            throw new Error('Pool is destroyed');
+        }
+        const maxConnections = this.config.max ?? 10;
+        if (this.connections.size >= maxConnections) {
+            throw new Error('Pool is at maximum capacity');
+        }
+        // This should be overridden by subclasses or set up via the factory
+        // For now, we'll throw an error if no factory is provided
+        throw new Error('Connection factory not set. Use setConnectionFactory()');
+    }
+    /**
+     * Process the waiting queue
+     */
+    processWaitingQueue() {
+        while (this.waitingQueue.length > 0 && this.getAvailableConnection()) {
+            const { resolve, timeoutId } = this.waitingQueue.shift();
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            const connection = this.getAvailableConnection();
+            if (connection) {
+                connection.markInUse();
+                this._acquired++;
+                this._inUse++;
+                this._available--;
+                if (this.config.onAcquire) {
+                    try {
+                        this.config.onAcquire(connection.connection);
+                    }
+                    catch (error) {
+                        console.error('onAcquire callback error:', error);
+                    }
+                }
+                resolve(connection);
+            }
+        }
+    }
+    /**
+     * Start the evictor to clean up idle connections
+     */
+    startEvictor() {
+        this.evictTimer = setInterval(async () => {
+            if (this.isDestroyed) {
+                return;
+            }
+            // Check for idle connections to evict
+            const toEvict = [];
+            for (const [, pooledConnection] of this.connections) {
+                // Don't evict if we're below minimum
+                const minConnections = this.config.min ?? 0;
+                if (this.connections.size - toEvict.length <= minConnections) {
+                    break;
+                }
+                const idleTimeout = this.config.idle ?? 30000;
+                if (pooledConnection.isIdle(idleTimeout)) {
+                    toEvict.push(pooledConnection);
+                }
+            }
+            // Destroy idle connections
+            for (const pooledConnection of toEvict) {
+                await this.destroyConnection(pooledConnection);
+            }
+        }, this.config.evict || 1000);
+    }
+}
+exports.ConnectionPool = ConnectionPool;
+/**
+ * Database-specific connection pool implementation
+ */
+class DatabaseConnectionPool extends ConnectionPool {
+    constructor(config) {
+        super(config);
+        this.connectionFactory = config.factory;
+    }
+    /**
+     * Create a new database connection
+     */
+    async createConnection() {
+        try {
+            const connection = await this.connectionFactory();
+            const pooledConnection = new PooledConnection(connection);
+            this.connections.set(pooledConnection.id, pooledConnection);
+            this._size++;
+            this._available++;
+            return pooledConnection;
+        }
+        catch (error) {
+            throw new Error(`Failed to create connection: ${error.message}`);
+        }
+    }
+    /**
+     * Get a connection using async/await
+     */
+    async acquire() {
+        const pooledConnection = await this.getConnection();
+        return pooledConnection.connection;
+    }
+    /**
+     * Release a connection
+     */
+    release(connection) {
+        for (const [, pooledConnection] of this.connections) {
+            if (pooledConnection.connection === connection) {
+                this.releaseConnection(pooledConnection);
+                return;
+            }
+        }
+    }
+}
+exports.DatabaseConnectionPool = DatabaseConnectionPool;
+/**
+ * Create a new connection pool
+ */
+function createPool(config) {
+    const pool = new DatabaseConnectionPool(config);
+    pool.initialize();
+    return pool;
+}
+exports.default = ConnectionPool;