@aetherframework/database 1.0.9 → 1.1.1

package/src/plugins/SyncPlugin.js

@@ -1,373 +0,0 @@
-/**
- * @license MIT
- * Copyright (c) 2026-present AetherFramework Contributors.
- * SPDX-License-Identifier: MIT
- * @module @aetherframework/database/plugin/SyncPlugin
- */
-import { BasePlugin } from './BasePlugin.js';
-
-/**
- * Sync Plugin - Provides cross-database data synchronization functionality
- * Supports bidirectional sync, conflict resolution, and batch processing
- */
-export class SyncPlugin extends BasePlugin {
-  constructor(queryBuilder) {
-    super(queryBuilder);
-    this.syncConfig = {
-      conflictStrategy: 'update',
-      batchSize: 1000,
-      keyField: 'id',
-      timestampField: 'updated_at',
-      onConflict: null,
-      onProgress: null
-    };
-  }
-
-  _registerMethods() {
-    // Register sync methods to QueryBuilder
-    this.queryBuilder.syncTo = this.syncTo.bind(this);
-    this.queryBuilder.syncBidirectional = this.syncBidirectional.bind(this);
-    this.queryBuilder.setSyncConfig = this.setSyncConfig.bind(this);
-    this.queryBuilder.migrateData = this.migrateData.bind(this);
-  }
-
-  /**
-   * Set synchronization configuration
-   * @param {Object} config - Sync configuration
-   * @returns {QueryBuilder} Query builder instance
-   */
-  setSyncConfig(config = {}) {
-    this.syncConfig = {
-      ...this.syncConfig,
-      ...config
-    };
-    return this.queryBuilder;
-  }
-
-  /**
-   * Sync data to another database
-   * @param {Object} targetDb - Target database connection
-   * @param {string} targetTable - Target table name
-   * @param {Object} options - Sync options
-   * @returns {Promise<number>} Number of synced records
-   */
-  async syncTo(targetDb, targetTable, options = {}) {
-    const config = {
-      ...this.syncConfig,
-      ...options
-    };
-
-    let offset = 0;
-    let totalSynced = 0;
-    let totalRecords = 0;
-
-    // Get total record count
-    const countResult = await this.queryBuilder.clone()
-      .selectRaw("COUNT(*) as total")
-      .first();
-    totalRecords = parseInt(countResult.total);
-    while (true) {
-      // Get batch of data
-      const sourceData = await this.queryBuilder.clone()
-        .limit(config.batchSize)
-        .offset(offset)
-        .get();
-
-      if (!sourceData || sourceData.length === 0) {
-        break;
-      }
-
-      // Sync each record
-      for (const row of sourceData) {
-        try {
-          const targetQuery = new this.queryBuilder.constructor(
-            targetTable,
-            targetDb,
-            this.queryBuilder.dialect
-          );
-
-          // Build conflict resolution
-          if (config.conflictStrategy === 'update') {
-            const updateData = { ...row };
-            delete updateData[config.keyField];
-
-            await targetQuery
-              .where(config.keyField, '=', row[config.keyField])
-              .update(updateData)
-              .execute();
-          } else if (config.conflictStrategy === 'ignore') {
-            try {
-              await targetQuery.insert(row).execute();
-            } catch (error) {
-              // Ignore duplicate errors
-              if (
-                !error.message.includes('duplicate') &&
-                !error.message.includes('unique')
-              ) {
-                throw error;
-              }
-            }
-          } else {
-            // error strategy - just insert, will throw on conflict
-            await targetQuery.insert(row).execute();
-          }
-
-          totalSynced++;
-        } catch (error) {
-          if (config.onConflict) {
-            await config.onConflict(row, error);
-          } else {
-            throw error;
-          }
-        }
-      }
-
-      offset += config.batchSize;
-
-      // Progress callback
-      if (config.onProgress) {
-        config.onProgress({
-          totalRecords,
-          synced: totalSynced,
-          percentage: Math.round((offset / totalRecords) * 100)
-        });
-      }
-
-    }
-
-    return totalSynced;
-  }
-
-  /**
-   * Two-way sync between databases
-   * @param {Object} targetDb - Target database connection
-   * @param {string} targetTable - Target table name
-   * @param {Object} options - Sync options
-   * @returns {Promise<Object>} Sync results
-   */
-  async syncBidirectional(targetDb, targetTable, options = {}) {
-    const config = {
-      ...this.syncConfig,
-      ...options
-    };
-
-    const results = {
-      sourceToTarget: 0,
-      targetToSource: 0,
-      conflicts: 0,
-      errors: []
-    };
-
-    // Sync from source to target
-    try {
-      results.sourceToTarget = await this.syncTo(targetDb, targetTable, {
-        conflictStrategy: config.conflictStrategy,
-        keyField: config.keyField,
-        batchSize: config.batchSize,
-        onConflict: async (row, error) => {
-          if (config.conflictStrategy === 'newer_wins') {
-            try {
-              // Compare timestamps
-              const targetQuery = new this.queryBuilder.constructor(
-                targetTable,
-                targetDb,
-                this.queryBuilder.dialect
-              );
-              const targetRow = await targetQuery
-                .where(config.keyField, '=', row[config.keyField])
-                .first();
-
-              if (
-                targetRow &&
-                row[config.timestampField] > targetRow[config.timestampField]
-              ) {
-                // Source is newer, update target
-                const updateData = { ...row };
-                delete updateData[config.keyField];
-
-                await targetQuery
-                  .where(config.keyField, '=', row[config.keyField])
-                  .update(updateData)
-                  .execute();
-                results.conflicts++;
-              }
-            } catch (compareError) {
-              results.errors.push(
-                `Conflict resolution failed: ${compareError.message}`
-              );
-            }
-          }
-        }
-      });
-    } catch (error) {
-      results.errors.push(`Source to target sync failed: ${error.message}`);
-    }
-
-    // Sync from target to source
-    try {
-      const targetQuery = new this.queryBuilder.constructor(targetTable, targetDb, this.queryBuilder.dialect);
-      results.targetToSource = await targetQuery.syncTo(
-        this.queryBuilder.connection,
-        this.queryBuilder.tableName,
-        {
-          conflictStrategy: config.conflictStrategy,
-          keyField: config.keyField,
-          batchSize: config.batchSize,
-          onConflict: async (row, error) => {
-            if (config.conflictStrategy === 'newer_wins') {
-              try {
-                // Compare timestamps
-                const sourceRow = await this.queryBuilder.clone()
-                  .where(config.keyField, '=', row[config.keyField])
-                  .first();
-
-                if (
-                  sourceRow &&
-                  row[config.timestampField] > sourceRow[config.timestampField]
-                ) {
-                  // Target is newer, update source
-                  const updateData = { ...row };
-                  delete updateData[config.keyField];
-
-                  await this.queryBuilder.clone()
-                    .where(config.keyField, '=', row[config.keyField])
-                    .update(updateData)
-                    .execute();
-                  results.conflicts++;
-                }
-              } catch (compareError) {
-                results.errors.push(
-                  `Conflict resolution failed: ${compareError.message}`
-                );
-              }
-            }
-          }
-        }
-      );
-    } catch (error) {
-      results.errors.push(`Target to source sync failed: ${error.message}`);
-    }
-
-    return results;
-  }
-
-  /**
-   * Migrate data from source to target
-   * @param {string} sourceTable - Source table name
-   * @param {Object} mapping - Field mapping
-   * @param {Object} options - Migration options
-   * @returns {Promise<number>} Number of migrated records
-   */
-  async migrateData(sourceTable, mapping, options = {}) {
-    const {
-      batchSize = 1000,
-      transform = null,
-      validate = null,
-      onProgress = null
-    } = options;
-
-    let offset = 0;
-    let totalMigrated = 0;
-    let totalProcessed = 0;
-
-    // Get total record count
-    const countResult = await this.queryBuilder.connection.query(
-      `SELECT COUNT(*) as total FROM ${sourceTable}`
-    );
-    const totalRecords = parseInt(countResult.rows.total);
-
-
-
-    while (true) {
-      // Get batch of data
-      const sourceData = await this.queryBuilder.connection.query(
-        `SELECT * FROM ${sourceTable} LIMIT ? OFFSET ?`,
-        [batchSize, offset]
-      );
-
-      if (!sourceData.rows || sourceData.rows.length === 0) {
-        break;
-      }
-
-      // Transform data
-      const transformedData = sourceData.rows.map((row) => {
-        let newRow = {};
-
-        // Apply field mapping
-        Object.entries(mapping).forEach(([sourceField, targetField]) => {
-          if (typeof targetField === 'function') {
-            newRow[sourceField] = targetField(row);
-          } else {
-            newRow[targetField] = row[sourceField];
-          }
-        });
-
-        // Apply transformation if provided
-        if (transform) {
-          newRow = transform(newRow, row);
-        }
-
-        return newRow;
-      });
-
-      // Validate data if validator provided
-      if (validate) {
-        const validationErrors = [];
-        transformedData.forEach((row, index) => {
-          const error = validate(row);
-          if (error) {
-            validationErrors.push({ index, error, row });
-          }
-        });
-
-        if (validationErrors.length > 0) {
-          throw new Error(
-            `Validation failed for ${validationErrors.length} records`
-          );
-        }
-      }
-
-      // Insert batch
-      const result = await this.queryBuilder.clone().insert(transformedData).execute();
-
-      totalMigrated += transformedData.length;
-      totalProcessed += sourceData.rows.length;
-      offset += batchSize;
-
-      // Progress callback
-      if (onProgress) {
-        onProgress({
-          totalRecords,
-          processed: totalProcessed,
-          migrated: totalMigrated,
-          batchSize: transformedData.length,
-          percentage: Math.round((totalProcessed / totalRecords) * 100)
-        });
-      }
-
-    }
-
-
-    return totalMigrated;
-  }
-
-  /**
-   * Get plugin metadata
-   * @returns {Object} Plugin metadata
-   */
-  getMetadata() {
-    return {
-      name: 'SyncPlugin',
-      version: '1.0.0',
-      description: 'Cross-database data synchronization and migration',
-      features: [
-        'Bidirectional synchronization',
-        'Conflict resolution strategies',
-        'Batch processing',
-        'Data migration',
-        'Progress tracking'
-      ],
-      strategies: ['update', 'ignore', 'error', 'newer_wins']
-    };
-  }
-}

package/src/plugins/VersioningPlugin.js

@@ -1,314 +0,0 @@
-/**
- * @license MIT
- * Copyright (c) 2026-present AetherFramework Contributors.
- * SPDX-License-Identifier: MIT
- * @module @aetherframework/database/plugin/VersioningPlugin
- */
-import { BasePlugin } from './BasePlugin.js';
-
-/**
- * Versioning Plugin - Provides optimistic locking and data versioning functionality.
- * Prevents concurrent update conflicts and optionally maintains a version history table.
- */
-export class VersioningPlugin extends BasePlugin {
-  constructor(queryBuilder) {
-    super(queryBuilder);
-    this.versionColumn = 'version';
-    this.versionHistoryEnabled = false;
-    this.versionHistoryTable = null;
-    this.keyField = 'id';
-  }
-
-  _registerMethods() {
-    // Register versioning methods to QueryBuilder
-    this.queryBuilder.withOptimisticLock = this.withOptimisticLock.bind(this);
-    this.queryBuilder.updateWithVersion = this.updateWithVersion.bind(this);
-    this.queryBuilder.createVersionHistory = this.createVersionHistory.bind(this);
-    this.queryBuilder.getVersionHistory = this.getVersionHistory.bind(this);
-    this.queryBuilder.restoreFromVersion = this.restoreFromVersion.bind(this);
-    this.queryBuilder.getCurrentVersion = this.getCurrentVersion.bind(this);
-    this.queryBuilder.checkVersion = this.checkVersion.bind(this);
-
-    // Override the update method to integrate version checking
-    this._wrapUpdateMethod();
-  }
-
-  /**
-   * Enable optimistic locking for the table.
-   * @param {string} column - The name of the version column (default: 'version').
-   * @returns {QueryBuilder} The QueryBuilder instance for chaining.
-   */
-  withOptimisticLock(column = 'version') {
-    this.versionColumn = column;
-    this.queryBuilder.query.optimisticLock = true;
-    return this.queryBuilder;
-  }
-
-  /**
-   * Perform an update with optimistic lock check.
-   * @param {Object} data - The data to update.
-   * @param {number} expectedVersion - The expected current version of the record.
-   * @param {Object} options - Additional options (e.g., changedBy, changeReason).
-   * @returns {Promise<Object>} The result of the update operation, including new version.
-   */
-  async updateWithVersion(data, expectedVersion, options = {}) {
-    if (!this.versionColumn) {
-      throw new Error('Optimistic lock is not enabled. Call withOptimisticLock() first.');
-    }
-
-    // Fetch the current record to check version and optionally log history
-    const originalData = await this.queryBuilder.clone().first();
-    if (!originalData) {
-      throw new Error('Record not found');
-    }
-
-    if (originalData[this.versionColumn] !== expectedVersion) {
-      throw new Error(
-        `Optimistic lock failed: Record was modified by another transaction. ` +
-        `Expected version: ${expectedVersion}, Actual version: ${originalData[this.versionColumn]}`
-      );
-    }
-
-    // Increment the version in the update data
-    const updateData = { ...data };
-    updateData[this.versionColumn] = expectedVersion + 1;
-
-    // Add version condition to WHERE clause
-    this.queryBuilder.where(this.versionColumn, '=', expectedVersion);
-
-    // Execute the update
-    const result = await this.queryBuilder.update(updateData).execute();
-
-    if (result.affectedRows === 0) {
-      throw new Error('Optimistic lock failed: Record was modified by another transaction during update.');
-    }
-
-    // Record version history if enabled
-    if (this.versionHistoryEnabled && this.versionHistoryTable) {
-      await this._recordVersionHistory(originalData, updateData, options);
-    }
-
-    return {
-      ...result,
-      newVersion: updateData[this.versionColumn],
-      previousVersion: expectedVersion
-    };
-  }
-
-  /**
-   * Create a version history table and enable history tracking.
-   * @param {string} historyTable - Name of the history table (defaults to `${mainTable}_history`).
-   * @param {string} keyField - The primary key field name (default: 'id').
-   * @returns {Promise<QueryBuilder>} The QueryBuilder instance.
-   */
-  async createVersionHistory(historyTable = null, keyField = 'id') {
-    const tableName = historyTable || `${this.queryBuilder.tableName}_history`;
-    this.versionHistoryEnabled = true;
-    this.versionHistoryTable = tableName;
-    this.keyField = keyField;
-
-    // SQL to create the history table (example for MySQL/PostgreSQL syntax)
-    const createTableSQL = `
-      CREATE TABLE IF NOT EXISTS ${tableName} (
-        history_id BIGINT AUTO_INCREMENT PRIMARY KEY,
-        ${keyField} BIGINT NOT NULL,
-        version INT NOT NULL,
-        data JSON NOT NULL,
-        changed_by VARCHAR(255),
-        changed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-        change_reason TEXT,
-        INDEX idx_${keyField}_version (${keyField}, version),
-        INDEX idx_changed_at (changed_at)
-      )
-    `;
-
-    try {
-      await this.queryBuilder.connection.query(createTableSQL);
-    } catch (error) {
-      console.error(`Failed to create version history table: ${error.message}`);
-      throw error;
-    }
-
-    // Attach a hook to automatically record history on updates
-    this.queryBuilder.addHook('beforeUpdate', async (data, builder) => {
-      if (builder.query.optimisticLock) {
-        await this._recordVersionHistoryOnUpdate(data, builder);
-      }
-    });
-
-    return this.queryBuilder;
-  }
-
-  /**
-   * Retrieve the version history for a specific record.
-   * @param {number|string} recordId - The ID of the record.
-   * @param {Object} options - Query options (limit, offset, order).
-   * @returns {Promise<Array>} Array of historical versions.
-   */
-  async getVersionHistory(recordId, options = {}) {
-    if (!this.versionHistoryEnabled || !this.versionHistoryTable) {
-      throw new Error('Version history is not enabled. Call createVersionHistory() first.');
-    }
-
-    const { limit = 100, offset = 0, orderBy = 'changed_at', orderDirection = 'DESC' } = options;
-
-    const historyQuery = new this.queryBuilder.constructor(
-      this.versionHistoryTable,
-      this.queryBuilder.connection,
-      this.queryBuilder.dialect
-    );
-
-    return historyQuery
-      .where(this.keyField, '=', recordId)
-      .orderBy(orderBy, orderDirection)
-      .limit(limit)
-      .offset(offset)
-      .get();
-  }
-
-  /**
-   * Restore a record to a specific historical version.
-   * @param {number} historyId - The ID of the history record to restore from.
-   * @param {Object} options - Restore options (restoredBy, restoreReason).
-   * @returns {Promise<Object>} The result of the restore operation.
-   */
-  async restoreFromVersion(historyId, options = {}) {
-    if (!this.versionHistoryEnabled || !this.versionHistoryTable) {
-      throw new Error('Version history is not enabled. Call createVersionHistory() first.');
-    }
-
-    // Fetch the historical record
-    const historyQuery = new this.queryBuilder.constructor(
-      this.versionHistoryTable,
-      this.queryBuilder.connection,
-      this.queryBuilder.dialect
-    );
-    const historyRecord = await historyQuery.where('history_id', '=', historyId).first();
-
-    if (!historyRecord) {
-      throw new Error(`Version history record with ID ${historyId} not found.`);
-    }
-
-    // Parse the historical data
-    const historicalData = typeof historyRecord.data === 'string'
-      ? JSON.parse(historyRecord.data)
-      : historyRecord.data;
-
-    // Prepare update data, restoring the version and adding audit info
-    const updateData = {
-      ...historicalData,
-      [this.versionColumn]: historyRecord.version,
-      restored_from_version: historyId,
-      restored_at: new Date(),
-      restored_by: options.restoredBy || null,
-      restore_reason: options.restoreReason || null
-    };
-
-    // Remove history-specific fields before update
-    delete updateData.history_id;
-    delete updateData.changed_at;
-    delete updateData.changed_by;
-
-    // Perform the restore update
-    return this.queryBuilder
-      .where(this.keyField, '=', historyRecord[this.keyField])
-      .update(updateData)
-      .execute();
-  }
-
-  /**
-   * Get the current version of a record.
-   * @param {number|string} recordId - The record ID.
-   * @returns {Promise<number|null>} The current version number, or null if not found.
-   */
-  async getCurrentVersion(recordId) {
-    const record = await this.queryBuilder
-      .clone()
-      .where(this.keyField, '=', recordId)
-      .select(this.versionColumn)
-      .first();
-    return record ? record[this.versionColumn] : null;
-  }
-
-  /**
-   * Check if a record's current version matches the expected version.
-   * @param {number|string} recordId - The record ID.
-   * @param {number} expectedVersion - The version to check against.
-   * @returns {Promise<boolean>} True if versions match.
-   */
-  async checkVersion(recordId, expectedVersion) {
-    const currentVersion = await this.getCurrentVersion(recordId);
-    return currentVersion === expectedVersion;
-  }
-
-  /**
-   * Wraps the original update method to inject version checking logic.
-   * @private
-   */
-  _wrapUpdateMethod() {
-    const originalUpdate = this.queryBuilder.update;
-    this.queryBuilder.update = function(data) {
-      // If optimistic locking is enabled and a version is provided in the data
-      if (this.query.optimisticLock && data && data[this.versionColumn] !== undefined) {
-        const expectedVersion = data[this.versionColumn];
-        // Remove version from update data as it will be incremented
-        delete data[this.versionColumn];
-        // Add version check to WHERE clause
-        this.where(this.versionColumn, '=', expectedVersion);
-        // Increment version for the update
-        data[this.versionColumn] = expectedVersion + 1;
-      }
-      return originalUpdate.call(this, data);
-    }.bind(this.queryBuilder);
-  }
-
-  /**
-   * Records a version history entry during an update operation.
-   * @private
-   */
-  async _recordVersionHistoryOnUpdate(data, builder) {
-    if (!this.versionHistoryEnabled || !this.versionHistoryTable) return;
-
-    const current = await builder.clone().first();
-    if (current && current[this.versionColumn] !== undefined) {
-      await this._recordVersionHistory(current, data, {
-        changed_by: data.changed_by,
-        change_reason: data.change_reason
-      });
-    }
-  }
-
-  /**
-   * Inserts a record into the version history table.
-   * @private
-   */
-  async _recordVersionHistory(originalData, newData, options = {}) {
-    const historyData = {
-      [this.keyField]: originalData[this.keyField],
-      version: originalData[this.versionColumn],
-      data: JSON.stringify(originalData),
-      changed_by: options.changed_by || null,
-      change_reason: options.change_reason || null
-    };
-
-    const historyQuery = new this.queryBuilder.constructor(
-      this.versionHistoryTable,
-      this.queryBuilder.connection,
-      this.queryBuilder.dialect
-    );
-    await historyQuery.insert(historyData);
-  }
-
-  /**
-   * Returns the plugin's configuration.
-   * @returns {Object} The configuration object.
-   */
-  getConfig() {
-    return {
-      versionColumn: this.versionColumn,
-      versionHistoryEnabled: this.versionHistoryEnabled,
-      versionHistoryTable: this.versionHistoryTable,
-      keyField: this.keyField
-    };
-  }
-}