@aetherframework/database 1.1.0 → 1.1.2

package/src/core/TransactionManager.js

@@ -0,0 +1,40 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/database/core/TransactionManager
+ */
+
+class TransactionManager {
+  constructor(driver) {
+    this.driver = driver;
+  }
+
+  async transaction(callback) {
+    const connection = await this.driver.pool.getConnection();
+    try {
+      await this.driver.beginTransaction(connection);
+ 
+      const trx = {
+        query: (sql, params) => this.driver.query(connection, sql, params),
+        rawQuery: (sql) => this.driver.rawQuery(connection, sql),   
+        execute: (sql, params) => this.driver.execute(connection, sql, params),
+      };
+
+      const result = await callback(trx);
+
+      await this.driver.commitTransaction(connection);
+
+      return result;
+
+    } catch (error) {
+
+      await this.driver.rollbackTransaction(connection).catch(() => {});
+      throw error;
+    } finally {
+      connection.release();
+    }
+  }
+}
+
+export default TransactionManager;

package/src/drivers/clickhouse-driver.js

@@ -0,0 +1,272 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/database/drivers/clickhouse-driver
+ */
+import { createClient } from '@clickhouse/client';
+
+/**
+ * ClickHouse Driver
+ * Implements ClickHouse database driver with environment variable control
+ */
+class ClickHouseDriver {
+  constructor(config) {
+    this.config = config;
+    this.client = null;
+    this.isConnected = false;
+  }
+
+  /**
+   * Initialize the ClickHouse client
+   * @returns {Promise<Object>} ClickHouse connection
+   */
+  async connect() {
+    // Check if ClickHouse is enabled via environment variable
+    if (process.env.ENABLE_CLICKHOUSE !== 'true') {
+      throw new Error('ClickHouse driver is disabled. Set ENABLE_CLICKHOUSE=true to enable.');
+    }
+
+    if (this.isConnected) return this.client;
+
+    try {
+      this.client = createClient({
+        host: this.config.host || 'http://localhost:8123',
+        username: this.config.user || 'default',
+        password: this.config.password || '',
+        database: this.config.database || 'default',
+        // ClickHouse specific options
+        clickhouse_settings: {
+          async_insert: 1, // Enable async insert for better performance
+          wait_for_async_insert: 0,
+        },
+        // Connection pool settings
+        max_open_connections: this.config.pool?.max || 10,
+        request_timeout: this.config.pool?.acquireTimeout || 10000,
+        compression: {
+          response: true,
+          request: true
+        }
+      });
+      
+      // Test connection
+      await this.client.ping();
+      this.isConnected = true;
+      return this.client;
+    } catch (error) {
+      console.error('❌ ClickHouse connection failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Create connection pool (ClickHouse doesn't have traditional connection pool)
+   * @returns {Promise<Object>} ClickHouse client
+   */
+  async createPool() {
+    // ClickHouse client handles connection pooling internally
+    return await this.connect();
+  }
+
+  /**
+   * Execute SELECT query
+   * @param {Object} connection - ClickHouse client
+   * @param {string} sql - SQL query
+   * @param {Array} params - Query parameters
+   * @returns {Promise<Object>} Query result
+   */
+  async query(connection, sql, params = []) {
+    await this.ensureConnected();
+    
+    try {
+      // ClickHouse uses parameterized queries differently
+      // We need to handle parameters manually
+      let finalSql = sql;
+      if (params && params.length > 0) {
+        // Replace ? placeholders with ClickHouse format
+        params.forEach((param, index) => {
+          const placeholder = `{param${index}:${this.getClickHouseType(param)}}`;
+          finalSql = finalSql.replace('?', placeholder);
+        });
+      }
+      
+      const resultSet = await connection.query({
+        query: finalSql,
+        format: 'JSONEachRow', // Return data as JSON array
+        clickhouse_settings: {
+          allow_experimental_object_type: 1
+        }
+      });
+      
+      const rows = await resultSet.json();
+      return {
+        rows,
+        rowCount: rows.length,
+        metaData: resultSet.meta || []
+      };
+    } catch (error) {
+      console.error('❌ ClickHouse query error:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Execute INSERT/UPDATE/DELETE operation
+   * Note: ClickHouse has limited UPDATE/DELETE support
+   * @param {Object} connection - ClickHouse client
+   * @param {string} sql - SQL statement
+   * @param {Array} params - Query parameters
+   * @returns {Promise<Object>} Execution result
+   */
+  async execute(connection, sql, params = []) {
+    await this.ensureConnected();
+
+    try {
+      let finalSql = sql;
+      if (params && params.length > 0) {
+        // Replace ? placeholders with ClickHouse format
+        params.forEach((param, index) => {
+          const placeholder = `{param${index}:${this.getClickHouseType(param)}}`;
+          finalSql = finalSql.replace('?', placeholder);
+        });
+      }
+
+      // For INSERT operations, ClickHouse has optimized methods
+      if (sql.toUpperCase().startsWith('INSERT')) {
+        // Extract table name from INSERT statement
+        const tableMatch = sql.match(/INSERT\s+INTO\s+(\w+)/i);
+        if (tableMatch && tableMatch) {
+          const tableName = tableMatch;
+          // If params is an array of objects, use insert method
+          if (params.length > 0 && typeof params === 'object') {
+            await connection.insert({
+              table: tableName,
+              values: params,
+              format: 'JSONEachRow'
+            });
+            return { affectedRows: params.length };
+          }
+        }
+      }
+
+      // For other operations, use command
+      await connection.command({ query: finalSql });
+      return { affectedRows: 1 };
+    } catch (error) {
+      console.error('❌ ClickHouse execute error:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Get ClickHouse type for parameter
+   * @param {*} value - Parameter value
+   * @returns {string} ClickHouse type string
+   */
+  getClickHouseType(value) {
+    if (value === null || value === undefined) return 'Nullable(Nothing)';
+    if (typeof value === 'number') {
+      return Number.isInteger(value) ? 'Int64' : 'Float64';
+    }
+    if (typeof value === 'boolean') return 'UInt8';
+    if (typeof value === 'string') return 'String';
+    if (value instanceof Date) return 'DateTime';
+    if (Array.isArray(value)) return 'Array(String)';
+    if (typeof value === 'object') return 'JSON';
+    return 'String';
+  }
+
+  /**
+   * Begin transaction (ClickHouse has limited transaction support)
+   * @param {Object} connection - ClickHouse client
+   * @returns {Promise<Object>} Transaction object
+   */
+  async beginTransaction(connection) {
+    console.warn('⚠️ ClickHouse has limited transaction support. Transactions may not work as expected.');
+    // ClickHouse doesn't support traditional transactions for all operations
+    return { sessionId: Date.now() };
+  }
+
+  /**
+   * Commit transaction
+   * @param {Object} transaction - Transaction object
+   */
+  async commitTransaction(transaction) {
+    // ClickHouse doesn't support traditional commit
+    console.warn('⚠️ ClickHouse transaction committed (no-op)');
+  }
+
+  /**
+   * Rollback transaction
+   * @param {Object} transaction - Transaction object
+   */
+  async rollbackTransaction(transaction) {
+    // ClickHouse doesn't support traditional rollback
+    console.warn('⚠️ ClickHouse transaction rolled back (no-op)');
+  }
+
+  /**
+   * Close connection
+   * @param {Object} connection - ClickHouse client
+   */
+  async close(connection) {
+    if (this.client) {
+      await this.client.close();
+      this.isConnected = false;
+    }
+  }
+
+  /**
+   * Close pool (ClickHouse doesn't have traditional connection pool)
+   * @param {Object} pool - Not used for ClickHouse
+   */
+  async closePool(pool) {
+    await this.close();
+  }
+
+  /**
+   * Get pool statistics
+   * @returns {Object} Pool statistics
+   */
+  getPoolStats() {
+    return {
+      isConnected: this.isConnected,
+      // ClickHouse doesn't expose connection pool stats
+      note: 'ClickHouse uses HTTP connection pooling internally'
+    };
+  }
+
+  /**
+   * Health check
+   * @param {Object} connection - ClickHouse client
+   * @returns {Promise<boolean>} Health status
+   */
+  async healthCheck(connection) {
+    try {
+      await connection.ping();
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Ensure connection is established
+   * @private
+   */
+  async ensureConnected() {
+    if (!this.isConnected) {
+      await this.connect();
+    }
+  }
+
+  /**
+   * Get dialect name
+   * @returns {string} Dialect name
+   */
+  getDialect() {
+    return 'clickhouse';
+  }
+}
+
+export default ClickHouseDriver;

package/src/drivers/index.js

@@ -0,0 +1,273 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/database/drivers/index
+ */
+// Driver registry mapping database types to driver classes
+const drivers = {};
+
+// Driver file path mapping
+const driverPaths = {
+  mysql: './mysql-driver.js',
+  mariadb: './mysql-driver.js',
+  postgresql: './postgres-driver.js',
+  postgres: './postgres-driver.js',
+  pg: './postgres-driver.js',
+  sqlite: './sqlite-driver.js',
+  sqlite3: './sqlite-driver.js',
+  mongodb: './mongodb-driver.js',
+  mongo: './mongodb-driver.js',
+  mssql: './mssql-driver.js',
+  sqlserver: './mssql-driver.js',
+  oracle: './oracle-driver.js',
+  // Add CockroachDB support (reuse PostgreSQL driver)
+  cockroachdb: './postgres-driver.js',
+  cockroach: './postgres-driver.js',
+  // Add ClickHouse support (requires separate driver)
+  clickhouse: './clickhouse-driver.js'
+};
+
+/**
+ * Get driver class by database type name using dynamic imports
+ * @param {string} name - Database type name (mysql, postgresql, sqlite, etc.)
+ * @returns {Promise<Class|null>} Driver class or null if not found
+ */
+export async function getDriver(name) {
+  const normalizedName = name.toLowerCase();
+  
+  // Return cached driver if already loaded
+  if (drivers[normalizedName]) {
+    return drivers[normalizedName];
+  }
+  
+  // Check if it's MySQL (your current database)
+  if (normalizedName === 'mysql' || normalizedName === 'mariadb') {
+    try {
+      // Only dynamically import MySQL driver
+      const { default: MySQLDriver } = await import('./mysql-driver.js');
+      drivers[normalizedName] = MySQLDriver;
+      return MySQLDriver;
+    } catch (error) {
+      console.error(`❌ Failed to load MySQL driver:`, error.message);
+      return null;
+    }
+  }
+
+  // Check if it's MongoDB
+  if (normalizedName === 'mongodb' || normalizedName === 'mongo') {
+    try {
+      // Dynamically import MongoDB driver
+      const { default: MongoDBDriver } = await import('./mongodb-driver.js');
+      drivers[normalizedName] = MongoDBDriver;
+      return MongoDBDriver;
+    } catch (error) {
+      console.error(`❌ Failed to load MongoDB driver:`, error.message);
+      return null;
+    }
+  }
+
+  // Check if it's CockroachDB (reuse PostgreSQL driver)
+  if (normalizedName === 'cockroachdb' || normalizedName === 'cockroach') {
+    // Check if CockroachDB support is enabled via environment variable
+    if (process.env.ENABLE_COCKROACHDB !== 'true') {
+      console.warn(`⚠️ CockroachDB driver is disabled. Set ENABLE_COCKROACHDB=true to enable.`);
+      return null;
+    }
+    
+    try {
+      // CockroachDB is PostgreSQL compatible, reuse PostgreSQL driver
+      const { default: PostgreSQLDriver } = await import('./postgres-driver.js');
+      drivers[normalizedName] = PostgreSQLDriver;
+
+      return PostgreSQLDriver;
+    } catch (error) {
+      console.error(`❌ Failed to load CockroachDB driver:`, error.message);
+      return null;
+    }
+  }
+
+  // Check if it's ClickHouse
+  if (normalizedName === 'clickhouse') {
+    // Check if ClickHouse support is enabled via environment variable
+    if (process.env.ENABLE_CLICKHOUSE !== 'true') {
+      console.warn(`⚠️ ClickHouse driver is disabled. Set ENABLE_CLICKHOUSE=true to enable.`);
+      return null;
+    }
+    
+    try {
+      // Dynamically import ClickHouse driver
+      const { default: ClickHouseDriver } = await import('./clickhouse-driver.js');
+      drivers[normalizedName] = ClickHouseDriver;
+
+      return ClickHouseDriver;
+    } catch (error) {
+      console.error(`❌ Failed to load ClickHouse driver:`, error.message);
+      return null;
+    }
+  }
+  
+  // For other drivers, return null and prompt for installation
+  console.warn(`⚠️ Driver "${name}" not loaded. To use this driver, install required package:`);
+  
+  const packageMap = {
+    postgresql: 'pg',
+    postgres: 'pg',
+    pg: 'pg',
+    sqlite: 'sqlite3',
+    sqlite3: 'sqlite3',
+    mongodb: 'mongodb',
+    mongo: 'mongodb',
+    redis: 'redis',
+    mssql: 'mssql',
+    sqlserver: 'mssql',
+    oracle: 'oracledb',
+    cockroachdb: 'pg',        // CockroachDB uses PostgreSQL driver
+    cockroach: 'pg',          // CockroachDB uses PostgreSQL driver
+    clickhouse: '@clickhouse/client'  // ClickHouse client package
+  };
+  
+  if (packageMap[normalizedName]) {
+    console.warn(`   npm install ${packageMap[normalizedName]}`);
+  }
+  
+  return null;
+}
+
+// Check if driver exists
+export function hasDriver(name) {
+  const normalizedName = name.toLowerCase();
+  return !!drivers[normalizedName];
+}
+
+// Get all available driver names
+export function getAvailableDrivers() {
+  return Object.keys(driverPaths);
+}
+
+// Register custom driver
+export function registerDriver(name, driverClass) {
+  const normalizedName = name.toLowerCase();
+  if (drivers[normalizedName]) {
+    console.warn(`⚠️ Driver "${name}" is already registered, overriding existing driver`);
+  }
+  drivers[normalizedName] = driverClass;
+}
+
+// Remove registered driver
+export function unregisterDriver(name) {
+  const normalizedName = name.toLowerCase();
+  if (drivers[normalizedName]) {
+    delete drivers[normalizedName];
+  } else {
+    console.warn(`⚠️ Driver "${name}" not found, nothing to unregister`);
+  }
+}
+
+// Preload all drivers
+export async function preloadDrivers() {
+  const driverNames = getAvailableDrivers();
+  const promises = driverNames.map(async (name) => {
+    try {
+      await getDriver(name);
+    } catch (error) {
+      console.error(`❌ Failed to preload driver "${name}":`, error.message);
+    }
+  });
+  await Promise.all(promises);
+}
+
+// Clear driver cache
+export function clearDriverCache() {
+  drivers.clear();
+}
+
+// On-demand export of individual drivers
+export async function getMySQLDriver() {
+  return await getDriver('mysql');
+}
+
+export async function getPostgreSQLDriver() {
+  return await getDriver('postgresql');
+}
+
+export async function getSQLiteDriver() {
+  return await getDriver('sqlite');
+}
+
+export async function getMongoDBDriver() {
+  return await getDriver('mongodb');
+}
+
+export async function getMSSQLDriver() {
+  return await getDriver('mssql');
+}
+
+export async function getOracleDriver() {
+  return await getDriver('oracle');
+}
+
+// New: Export CockroachDB driver (environment variable controlled)
+export async function getCockroachDBDriver() {
+  // Check if CockroachDB support is enabled
+  if (process.env.ENABLE_COCKROACHDB !== 'true') {
+    console.warn(`⚠️ CockroachDB driver is disabled. Set ENABLE_COCKROACHDB=true to enable.`);
+    return null;
+  }
+  return await getDriver('cockroachdb');
+}
+
+// New: Export ClickHouse driver (environment variable controlled)
+export async function getClickHouseDriver() {
+  // Check if ClickHouse support is enabled
+  if (process.env.ENABLE_CLICKHOUSE !== 'true') {
+    console.warn(`⚠️ ClickHouse driver is disabled. Set ENABLE_CLICKHOUSE=true to enable.`);
+    return null;
+  }
+  return await getDriver('clickhouse');
+}
+
+// New: Export Redis driver
+export async function getRedisDriver() {
+  return await getDriver('redis');
+}
+
+// New: Export all drivers as an object
+export async function getAllDrivers() {
+  const driverNames = getAvailableDrivers();
+  const driversObj = {};
+  
+  for (const name of driverNames) {
+    try {
+      const driver = await getDriver(name);
+      if (driver) {
+        driversObj[name] = driver;
+      }
+    } catch (error) {
+      console.warn(`⚠️ Failed to load driver "${name}":`, error.message);
+    }
+  }
+  
+  return driversObj;
+}
+
+// New: Check if specific driver is available
+export async function isDriverAvailable(name) {
+  try {
+    const driver = await getDriver(name);
+    return driver !== null;
+  } catch (error) {
+    return false;
+  }
+}
+
+// New: Get driver with fallback
+export async function getDriverWithFallback(name, fallbackName = 'mysql') {
+  const driver = await getDriver(name);
+  if (driver) {
+    return driver;
+  }
+  
+  console.warn(`⚠️ Driver "${name}" not available, falling back to "${fallbackName}"`);
+  return await getDriver(fallbackName);
+}

package/src/drivers/mongodb-driver.js

@@ -0,0 +1,87 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/database/drivers/mongodb-driver
+ */
+import { MongoClient } from 'mongodb';
+
+class MongoDBDriver {
+  constructor(config) {
+    this.config = config;
+    this.client = null;
+  }
+
+  async connect(config) {
+    const url = `mongodb://${config.user}:${config.password}@${config.host}:${config.port}/${config.database}?authSource=${config.authSource || 'admin'}`;
+    this.client = new MongoClient(url, {
+      useNewUrlParser: true,
+      useUnifiedTopology: true,
+      maxPoolSize: config.pool?.max || 10,
+      minPoolSize: config.pool?.min || 2,
+      maxIdleTimeMS: config.pool?.idleTimeout || 30000,
+      serverSelectionTimeoutMS: config.pool?.acquireTimeout || 10000
+    });
+    await this.client.connect();
+    return this.client.db(config.database);
+  }
+
+  async query(connection, collectionName, query = {}, options = {}) {
+    const collection = connection.collection(collectionName);
+    const cursor = collection.find(query, options);
+    const rows = await cursor.toArray();
+    return { rows, rowCount: rows.length };
+  }
+
+  async execute(connection, collectionName, operation, data, options = {}) {
+    const collection = connection.collection(collectionName);
+    let result;
+    
+    switch (operation) {
+      case 'insert':
+        result = await collection.insertOne(data, options);
+        return { insertedId: result.insertedId, insertedCount: result.insertedCount };
+      case 'update':
+        result = await collection.updateOne(data.filter, data.update, options);
+        return { matchedCount: result.matchedCount, modifiedCount: result.modifiedCount };
+      case 'delete':
+        result = await collection.deleteOne(data.filter, options);
+        return { deletedCount: result.deletedCount };
+      default:
+        throw new Error(`Unsupported MongoDB operation: ${operation}`);
+    }
+  }
+
+  async beginTransaction(connection) {
+    const session = this.client.startSession();
+    session.startTransaction();
+    return session;
+  }
+
+  async commitTransaction(session) {
+    await session.commitTransaction();
+    session.endSession();
+  }
+
+  async rollbackTransaction(session) {
+    await session.abortTransaction();
+    session.endSession();
+  }
+
+  async close() {
+    if (this.client) {
+      await this.client.close();
+    }
+  }
+
+  async healthCheck(connection) {
+    try {
+      await connection.command({ ping: 1 });
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+}
+
+export default MongoDBDriver;