@aetherframework/database 1.1.1 → 1.1.2

package/src/plugins/ShardingPlugin.js

@@ -0,0 +1,227 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/database/plugin/ShardingPlugin
+ */
+import { BasePlugin } from './BasePlugin.js';
+import crypto from 'crypto';
+
+/**
+ * Sharding Plugin - Provides horizontal and vertical data sharding/partitioning support.
+ * Dynamically routes queries to the correct physical table based on shard/partition keys.
+ */
+export class ShardingPlugin extends BasePlugin {
+  constructor(queryBuilder) {
+    super(queryBuilder);
+    this.shardKey = null;
+    this.partitionKey = null;
+    this.shardStrategy = 'hash'; // 'hash', 'range', 'list'
+    this.partitionStrategy = 'time'; // 'time', 'hash', 'range'
+    this.totalShards = 10;
+    this.partitionFormat = 'pYYYYMM'; // Format for time-based partitions
+  }
+
+  _registerMethods() {
+    // Register sharding methods to QueryBuilder
+    this.queryBuilder.shard = this.shard.bind(this);
+    this.queryBuilder.partition = this.partition.bind(this);
+    this.queryBuilder.getActualTableName = this.getActualTableName.bind(this);
+    this.queryBuilder.calculateShardKey = this.calculateShardKey.bind(this);
+    this.queryBuilder.shardRoute = this.shardRoute.bind(this);
+    this.queryBuilder.setShardingConfig = this.setShardingConfig.bind(this);
+  }
+
+  /**
+   * Set the shard key for horizontal partitioning.
+   * @param {string} shardKey - The value used to determine the shard.
+   * @returns {QueryBuilder} The QueryBuilder instance for chaining.
+   */
+  shard(shardKey) {
+    this.shardKey = shardKey;
+    return this.queryBuilder;
+  }
+
+  /**
+   * Set the partition key for vertical partitioning (e.g., time-based).
+   * @param {string|Date} partitionKey - The value used to determine the partition.
+   * @returns {QueryBuilder} The QueryBuilder instance for chaining.
+   */
+  partition(partitionKey) {
+    this.partitionKey = partitionKey;
+    return this.queryBuilder;
+  }
+
+  /**
+   * Configures the sharding/partitioning strategy.
+   * @param {Object} config - Configuration options.
+   * @returns {QueryBuilder} The QueryBuilder instance.
+   */
+  setShardingConfig(config = {}) {
+    Object.assign(this, config);
+    return this.queryBuilder;
+  }
+
+  /**
+   * Calculates the actual physical table name based on shard/partition keys.
+   * @returns {string} The actual table name to use in the query.
+   */
+  getActualTableName() {
+    let tableName = this.queryBuilder.tableName;
+
+    // Apply sharding (horizontal)
+    if (this.shardKey) {
+      let shardSuffix;
+      switch (this.shardStrategy) {
+        case 'hash':
+          shardSuffix = this._hashShard(this.shardKey);
+          break;
+        case 'range':
+          shardSuffix = this._rangeShard(this.shardKey);
+          break;
+        case 'list':
+          shardSuffix = this._listShard(this.shardKey);
+          break;
+        default:
+          shardSuffix = this._hashShard(this.shardKey);
+      }
+      tableName = `${tableName}_${shardSuffix}`;
+    }
+
+    // Apply partitioning (vertical, e.g., by time)
+    if (this.partitionKey) {
+      let partitionSuffix;
+      switch (this.partitionStrategy) {
+        case 'time':
+          partitionSuffix = this._timePartition(this.partitionKey);
+          break;
+        case 'hash':
+          partitionSuffix = this._hashPartition(this.partitionKey);
+          break;
+        case 'range':
+          partitionSuffix = this._rangePartition(this.partitionKey);
+          break;
+        default:
+          partitionSuffix = this._timePartition(this.partitionKey);
+      }
+      tableName = `${tableName}_${partitionSuffix}`;
+    }
+
+    return tableName;
+  }
+
+  /**
+   * Calculates a shard key using consistent hashing.
+   * @param {*} value - The value to hash (e.g., user ID).
+   * @param {number} totalShards - Total number of shards.
+   * @returns {string} The calculated shard identifier.
+   */
+  calculateShardKey(value, totalShards = this.totalShards) {
+    const hash = crypto.createHash('md5').update(String(value)).digest('hex');
+    const shardNum = parseInt(hash.substring(0, 8), 16) % totalShards;
+    return `shard${shardNum}`;
+  }
+
+  /**
+   * Routes an insert operation to the appropriate shard based on data.
+   * @param {Object} data - The data to insert.
+   * @param {string} keyField - The field used for shard calculation (default: 'id').
+   * @returns {Promise<Object>} The result of the insert operation.
+   */
+  async shardRoute(data, keyField = 'id') {
+    const shardValue = data[keyField];
+    if (!shardValue) {
+      throw new Error(`Shard key field '${keyField}' not found in data.`);
+    }
+    const shardKey = this.calculateShardKey(shardValue);
+    return this.queryBuilder.clone().shard(shardKey).insert(data).execute();
+  }
+
+  /**
+   * Hash-based sharding strategy.
+   * @private
+   */
+  _hashShard(value) {
+    return this.calculateShardKey(value);
+  }
+
+  /**
+   * Range-based sharding strategy (example: by numeric ranges).
+   * @private
+   */
+  _rangeShard(value) {
+    // Example: shard by user_id ranges (0-999 -> shard0, 1000-1999 -> shard1, etc.)
+    const num = Number(value);
+    if (isNaN(num)) {
+      throw new Error('Range sharding requires a numeric value.');
+    }
+    const shardNum = Math.floor(num / 1000) % this.totalShards;
+    return `shard${shardNum}`;
+  }
+
+  /**
+   * List-based sharding strategy (example: by region).
+   * @private
+   */
+  _listShard(value) {
+    // Example: map specific values to specific shards
+    const shardMap = {
+      'us': 'shard0',
+      'eu': 'shard1',
+      'asia': 'shard2'
+      // ... extend as needed
+    };
+    return shardMap[value] || this._hashShard(value);
+  }
+
+  /**
+   * Time-based partitioning strategy.
+   * @private
+   */
+  _timePartition(value) {
+    const date = new Date(value);
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    // Supports formats like pYYYYMM, pYYYYMMDD, etc.
+    return this.partitionFormat
+      .replace('YYYY', year)
+      .replace('MM', month)
+      .replace('DD', String(date.getDate()).padStart(2, '0'));
+  }
+
+  /**
+   * Hash-based partitioning strategy.
+   * @private
+   */
+  _hashPartition(value) {
+    const hash = crypto.createHash('md5').update(String(value)).digest('hex');
+    const partitionNum = parseInt(hash.substring(0, 4), 16) % 100; // Example: 100 partitions
+    return `part${String(partitionNum).padStart(3, '0')}`;
+  }
+
+  /**
+   * Range-based partitioning strategy (example: by date ranges).
+   * @private
+   */
+  _rangePartition(value) {
+    const date = new Date(value);
+    const year = date.getFullYear();
+    const quarter = Math.floor(date.getMonth() / 3) + 1;
+    return `y${year}q${quarter}`;
+  }
+
+  /**
+   * Override the internal method that builds the final SQL to use the actual table name.
+   * This method should be called by the plugin after the main QueryBuilder registers it.
+   */
+  applyTableNameOverride() {
+    const originalGetActualTableName = this.queryBuilder.getActualTableName;
+    this.queryBuilder.getActualTableName = () => {
+      // Use the plugin's logic if sharding/partitioning is active, otherwise fall back
+      if (this.shardKey || this.partitionKey) {
+        return this.getActualTableName();
+      }
+      return originalGetActualTableName ? originalGetActualTableName.call(this.queryBuilder) : this.queryBuilder.tableName;
+    };
+  }
+}

package/src/plugins/SoftDeletePlugin.js

@@ -0,0 +1,258 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/database/plugin/SoftDeletePlugin
+ */
+import { BasePlugin } from './BasePlugin.js';
+
+/**
+ * Soft Delete Plugin - Provides soft delete functionality
+ * Automatically adds deleted_at IS NULL condition to queries
+ */
+export class SoftDeletePlugin extends BasePlugin {
+  constructor(queryBuilder) {
+    super(queryBuilder);
+    this.softDeleteEnabled = false;
+    this.softDeleteColumn = 'deleted_at';
+    this.deletedByColumn = 'deleted_by';
+    this.deletedReasonColumn = 'deleted_reason';
+    this.restoredAtColumn = 'restored_at';
+    this.restoredByColumn = 'restored_by';
+  }
+
+  /**
+   * Initialize the plugin
+   * @returns {Promise<void>}
+   */
+  async init() {
+    if (this.initialized) return;
+    this.initialized = true;
+    this._registerMethods();
+  }
+
+  /**
+   * Register plugin methods to QueryBuilder
+   * @protected
+   */
+  _registerMethods() {
+    this.queryBuilder.enableSoftDelete = this.enableSoftDelete.bind(this);
+    this.queryBuilder.softDelete = this.softDelete.bind(this);
+    this.queryBuilder.restore = this.restore.bind(this);
+    this.queryBuilder.withTrashed = this.withTrashed.bind(this);
+    this.queryBuilder.onlyTrashed = this.onlyTrashed.bind(this);
+    this.queryBuilder.forceDelete = this.forceDelete.bind(this);
+    
+    // Override the execute method to add soft delete filtering
+    const originalExecute = this.queryBuilder.execute;
+    this.queryBuilder.execute = async function() {
+      // Add soft delete filter for SELECT queries
+      if (this.query.type === 'select' && this.softDeleteEnabled && !this.query.includeDeleted) {
+        this.whereNull(this.softDeleteColumn);
+      }
+      return originalExecute.call(this);
+    }.bind(this.queryBuilder);
+
+    return this;
+  }
+
+  /**
+   * Cleanup plugin resources
+   * @returns {Promise<void>}
+   */
+  async cleanup() {
+    delete this.queryBuilder.enableSoftDelete;
+    delete this.queryBuilder.softDelete;
+    delete this.queryBuilder.restore;
+    delete this.queryBuilder.withTrashed;
+    delete this.queryBuilder.onlyTrashed;
+    delete this.queryBuilder.forceDelete;
+    
+    // Restore original execute method
+    // Note: This requires storing the original method reference
+    
+    this.initialized = false;
+  }
+
+  /**
+   * Enable soft delete functionality
+   * @param {Object} options - Configuration options
+   * @param {string} options.column - Soft delete column name (default: 'deleted_at')
+   * @param {string} options.deletedByColumn - Deleted by column name (default: 'deleted_by')
+   * @param {string} options.deletedReasonColumn - Deleted reason column name (default: 'deleted_reason')
+   * @param {string} options.restoredAtColumn - Restored at column name (default: 'restored_at')
+   * @param {string} options.restoredByColumn - Restored by column name (default: 'restored_by')
+   * @returns {QueryBuilder} Query builder instance
+   */
+  enableSoftDelete(options = {}) {
+    this.softDeleteEnabled = true;
+    this.softDeleteColumn = options.column || 'deleted_at';
+    this.deletedByColumn = options.deletedByColumn || 'deleted_by';
+    this.deletedReasonColumn = options.deletedReasonColumn || 'deleted_reason';
+    this.restoredAtColumn = options.restoredAtColumn || 'restored_at';
+    this.restoredByColumn = options.restoredByColumn || 'restored_by';
+    
+    return this.queryBuilder;
+  }
+
+  /**
+   * Perform soft delete (mark as deleted instead of physical delete)
+   * @param {Object} options - Soft delete options
+   * @param {string|number} options.deletedBy - User ID or name who performed deletion
+   * @param {string} options.reason - Reason for deletion
+   * @returns {Promise<Object>} Delete result
+   */
+  async softDelete(options = {}) {
+    if (!this.softDeleteEnabled) {
+      throw new Error('Soft delete is not enabled. Call enableSoftDelete() first.');
+    }
+
+    const updateData = {
+      [this.softDeleteColumn]: new Date()
+    };
+
+    // Add deleted_by if provided
+    if (options.deletedBy !== undefined) {
+      updateData[this.deletedByColumn] = options.deletedBy;
+    }
+
+    // Add deleted_reason if provided
+    if (options.reason !== undefined) {
+      updateData[this.deletedReasonColumn] = options.reason;
+    }
+
+    // Ensure we only update non-deleted records
+    if (!this.queryBuilder.query.where.some(
+      w => w.column === this.softDeleteColumn && w.type === 'null'
+    )) {
+      this.queryBuilder.whereNull(this.softDeleteColumn);
+    }
+
+    return this.queryBuilder
+      .update(updateData)
+      .execute();
+  }
+
+  /**
+   * Restore soft deleted records
+   * @param {Object} options - Restore options
+   * @param {string|number} options.restoredBy - User ID or name who performed restoration
+   * @returns {Promise<Object>} Update result
+   */
+  async restore(options = {}) {
+    if (!this.softDeleteEnabled) {
+      throw new Error('Soft delete is not enabled. Call enableSoftDelete() first.');
+    }
+
+    const updateData = {
+      [this.softDeleteColumn]: null,
+      [this.restoredAtColumn]: new Date()
+    };
+
+    // Add restored_by if provided
+    if (options.restoredBy !== undefined) {
+      updateData[this.restoredByColumn] = options.restoredBy;
+    }
+
+    // Only restore deleted records
+    this.queryBuilder.whereNotNull(this.softDeleteColumn);
+
+    return this.queryBuilder
+      .update(updateData)
+      .execute();
+  }
+
+  /**
+   * Include soft deleted records in query
+   * @returns {QueryBuilder} Query builder instance
+   */
+  withTrashed() {
+    this.queryBuilder.query.includeDeleted = true;
+    
+    // Remove soft delete filter if present
+    this.queryBuilder.query.where = this.queryBuilder.query.where.filter(
+      w => !(w.column === this.softDeleteColumn && w.type === 'null')
+    );
+    
+    return this.queryBuilder;
+  }
+
+  /**
+   * Query only soft deleted records
+   * @returns {QueryBuilder} Query builder instance
+   */
+  onlyTrashed() {
+    if (!this.softDeleteEnabled) {
+      throw new Error('Soft delete is not enabled. Call enableSoftDelete() first.');
+    }
+
+    this.queryBuilder.whereNotNull(this.softDeleteColumn);
+    return this.queryBuilder;
+  }
+
+  /**
+   * Force delete (permanent delete)
+   * @returns {Promise<Object>} Delete result
+   */
+  async forceDelete() {
+    // Remove soft delete filter
+    this.queryBuilder.query.where = this.queryBuilder.query.where.filter(
+      w => !(w.column === this.softDeleteColumn && w.type === 'null')
+    );
+
+    return this.queryBuilder.delete().execute();
+  }
+
+  /**
+   * Get soft delete configuration
+   * @returns {Object} Configuration object
+   */
+  getConfig() {
+    return {
+      enabled: this.softDeleteEnabled,
+      column: this.softDeleteColumn,
+      deletedByColumn: this.deletedByColumn,
+      deletedReasonColumn: this.deletedReasonColumn,
+      restoredAtColumn: this.restoredAtColumn,
+      restoredByColumn: this.restoredByColumn
+    };
+  }
+
+  /**
+   * Check if record is soft deleted
+   * @param {Object} record - Database record
+   * @returns {boolean} True if record is soft deleted
+   */
+  isSoftDeleted(record) {
+    if (!this.softDeleteEnabled) return false;
+    return record[this.softDeleteColumn] !== null && record[this.softDeleteColumn] !== undefined;
+  }
+
+  /**
+   * Get soft delete status
+   * @param {Object} record - Database record
+   * @returns {Object} Soft delete status information
+   */
+  getSoftDeleteStatus(record) {
+    if (!this.softDeleteEnabled) {
+      return { enabled: false, deleted: false };
+    }
+
+    const deleted = this.isSoftDeleted(record);
+    const status = {
+      enabled: true,
+      deleted,
+      deletedAt: record[this.softDeleteColumn],
+      deletedBy: record[this.deletedByColumn],
+      deletedReason: record[this.deletedReasonColumn]
+    };
+
+    if (!deleted && record[this.restoredAtColumn]) {
+      status.restored = true;
+      status.restoredAt = record[this.restoredAtColumn];
+      status.restoredBy = record[this.restoredByColumn];
+    }
+
+    return status;
+  }
+}