@aetherframework/database 1.1.0 → 1.1.2

package/src/plugins/EncryptionPlugin.js

@@ -0,0 +1,211 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/database/plugin/EncryptionPlugin
+ */
+import crypto from 'crypto';
+import { BasePlugin } from './BasePlugin.js';
+
+/**
+ * Encryption Plugin - Provides data encryption/decryption functionality
+ * Supports AES-256-GCM encryption for sensitive fields
+ */
+export class EncryptionPlugin extends BasePlugin {
+  constructor(queryBuilder) {
+    super(queryBuilder);
+    this.encryptionKey = null;
+    this.encryptedFields = new Set();
+    this.encryptionAlgorithm = 'aes-256-gcm';
+  }
+
+  _registerMethods() {
+    // Register encryption methods to QueryBuilder
+    this.queryBuilder.setEncryptionKey = this.setEncryptionKey.bind(this);
+    this.queryBuilder.encryptField = this.encryptField.bind(this);
+    this.queryBuilder.encryptData = this.encryptData.bind(this);
+    this.queryBuilder.decryptData = this.decryptData.bind(this);
+    this.queryBuilder.isEncryptionEnabled = this.isEncryptionEnabled.bind(this);
+  }
+
+  /**
+   * Set encryption key
+   * @param {string|Buffer} key - Encryption key (32 bytes for AES-256)
+   * @returns {QueryBuilder} Query builder instance
+   */
+  setEncryptionKey(key) {
+    if (typeof key === 'string') {
+      // Ensure key is 32 bytes for AES-256
+      const keyBuffer = Buffer.from(key, 'utf8');
+      if (keyBuffer.length !== 32) {
+        throw new Error('Encryption key must be 32 bytes for AES-256');
+      }
+      this.encryptionKey = keyBuffer;
+    } else if (Buffer.isBuffer(key)) {
+      if (key.length !== 32) {
+        throw new Error('Encryption key must be 32 bytes for AES-256');
+      }
+      this.encryptionKey = key;
+    } else {
+      throw new Error('Encryption key must be a string or Buffer');
+    }
+    
+    // Add encryption hooks
+    this._addEncryptionHooks();
+    return this.queryBuilder;
+  }
+
+  /**
+   * Mark field for encryption
+   * @param {string} fieldName - Field name to encrypt
+   * @returns {QueryBuilder} Query builder instance
+   */
+  encryptField(fieldName) {
+    this.encryptedFields.add(fieldName);
+    return this.queryBuilder;
+  }
+
+  /**
+   * Encrypt data before insertion/update
+   * @param {Object} data - Data to encrypt
+   * @returns {Object} Encrypted data
+   */
+  encryptData(data) {
+    if (!this.encryptionKey || this.encryptedFields.size === 0) {
+      return data;
+    }
+
+    const encrypted = { ...data };
+
+    for (const field of this.encryptedFields) {
+      if (encrypted[field] !== undefined && encrypted[field] !== null) {
+        try {
+          const iv = crypto.randomBytes(16);
+          const cipher = crypto.createCipheriv(
+            this.encryptionAlgorithm,
+            this.encryptionKey,
+            iv
+          );
+
+          let encryptedText = cipher.update(
+            String(encrypted[field]),
+            'utf8',
+            'hex'
+          );
+          encryptedText += cipher.final('hex');
+          const authTag = cipher.getAuthTag();
+
+          // Store format: iv:authTag:encryptedText
+          encrypted[field] = 
+            `${iv.toString('hex')}:${authTag.toString('hex')}:${encryptedText}`;
+        } catch (error) {
+          console.error(`Failed to encrypt field ${field}:`, error.message);
+          throw new Error(`Encryption failed for field ${field}`);
+        }
+      }
+    }
+
+    return encrypted;
+  }
+
+  /**
+   * Decrypt data after retrieval
+   * @param {Object} data - Data to decrypt
+   * @returns {Object} Decrypted data
+   */
+  decryptData(data) {
+    if (!this.encryptionKey || this.encryptedFields.size === 0) {
+      return data;
+    }
+
+    const decrypted = { ...data };
+
+    for (const field of this.encryptedFields) {
+      if (decrypted[field] && decrypted[field].includes(':')) {
+        try {
+          const [ivHex, authTagHex, encryptedText] = decrypted[field].split(':');
+          const iv = Buffer.from(ivHex, 'hex');
+          const authTag = Buffer.from(authTagHex, 'hex');
+          
+          const decipher = crypto.createDecipheriv(
+            this.encryptionAlgorithm,
+            this.encryptionKey,
+            iv
+          );
+          decipher.setAuthTag(authTag);
+
+          let decryptedText = decipher.update(encryptedText, 'hex', 'utf8');
+          decryptedText += decipher.final('utf8');
+
+          decrypted[field] = decryptedText;
+        } catch (error) {
+          console.warn(`Failed to decrypt field ${field}:`, error.message);
+          decrypted[field] = null;
+        }
+      }
+    }
+
+    return decrypted;
+  }
+
+  /**
+   * Check if encryption is enabled
+   * @returns {boolean} True if encryption is enabled
+   */
+  isEncryptionEnabled() {
+    return this.encryptionKey !== null && this.encryptedFields.size > 0;
+  }
+
+  /**
+   * Add encryption hooks to QueryBuilder
+   * @private
+   */
+  _addEncryptionHooks() {
+    // Hook for encrypting data before insert/update
+    this.queryBuilder.addHook('beforeInsert', async (data) => {
+      return this.encryptData(data);
+    });
+
+    this.queryBuilder.addHook('beforeUpdate', async (data) => {
+      return this.encryptData(data);
+    });
+
+    // Hook for decrypting data after select
+    this.queryBuilder.addHook('afterSelect', async (result) => {
+      if (Array.isArray(result)) {
+        return result.map(row => this.decryptData(row));
+      } else if (result && typeof result === 'object') {
+        return this.decryptData(result);
+      }
+      return result;
+    });
+  }
+
+  /**
+   * Generate encryption key
+   * @param {number} length - Key length in bytes (default: 32)
+   * @returns {Buffer} Generated key
+   */
+  static generateKey(length = 32) {
+    return crypto.randomBytes(length);
+  }
+
+  /**
+   * Get plugin metadata
+   * @returns {Object} Plugin metadata
+   */
+  getMetadata() {
+    return {
+      name: 'EncryptionPlugin',
+      version: '1.0.0',
+      description: 'Provides AES-256-GCM encryption for sensitive data fields',
+      dependencies: ['crypto'],
+      features: [
+        'Field-level encryption',
+        'AES-256-GCM algorithm',
+        'Automatic encryption/decryption hooks',
+        'Key management'
+      ]
+    };
+  }
+}

package/src/plugins/FullTextSearchPlugin.js

@@ -0,0 +1,164 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/database/plugin/FullTextSearchPlugin
+ */
+import { BasePlugin } from "./BasePlugin.js";
+
+/**
+ * 全文搜索插件 - 封装不同数据库的全文搜索语法
+ */
+export class FullTextSearchPlugin extends BasePlugin {
+  constructor(queryBuilder) {
+    super(queryBuilder);
+    this.pluginName = "FullTextSearchPlugin";
+  }
+
+  _registerMethods() {
+    // 注册全文搜索方法到 QueryBuilder
+    this.queryBuilder.fullTextSearch = this.fullTextSearch.bind(this);
+    this.queryBuilder.orderByRelevance = this.orderByRelevance.bind(this);
+    this.queryBuilder.matchAgainst = this.matchAgainst.bind(this);
+    this.queryBuilder.fullTextBoolean = this.fullTextBoolean.bind(this);
+    this.queryBuilder.fullTextQueryExpansion = this.fullTextQueryExpansion.bind(this);
+  }
+
+  /**
+   * 全文搜索
+   * @param {string|Array} columns - 要搜索的列
+   * @param {string} searchTerm - 搜索词
+   * @param {string} mode - 搜索模式 (natural, boolean)
+   * @returns {QueryBuilder} QueryBuilder 实例
+   */
+  fullTextSearch(columns, searchTerm, mode = "natural") {
+    this.queryBuilder.query.fullTextSearch = {
+      columns: Array.isArray(columns) ? columns : [columns],
+      searchTerm,
+      mode: mode.toLowerCase(),
+    };
+    return this.queryBuilder;
+  }
+
+  /**
+   * 按相关性排序（全文搜索）
+   * @param {string|Array} columns - 用于相关性的列
+   * @param {string} searchTerm - 搜索词
+   * @returns {QueryBuilder} QueryBuilder 实例
+   */
+  orderByRelevance(columns, searchTerm) {
+    this.queryBuilder.query.orderByRelevance = { columns, searchTerm };
+    return this.queryBuilder;
+  }
+
+  /**
+   * 使用 MATCH AGAINST 进行全文搜索
+   * @param {string|Array} columns - 要搜索的列
+   * @param {string} searchTerm - 搜索词
+   * @param {string} mode - 搜索模式 (natural, boolean, query expansion)
+   * @param {boolean} withQueryExpansion - 是否使用查询扩展
+   * @returns {QueryBuilder} QueryBuilder 实例
+   */
+  matchAgainst(columns, searchTerm, mode = "natural", withQueryExpansion = false) {
+    const columnList = Array.isArray(columns)
+      ? columns.map((col) => this.queryBuilder.wrapColumn(col)).join(", ")
+      : this.queryBuilder.wrapColumn(columns);
+
+    let modeClause = "";
+    if (mode === "boolean") {
+      modeClause = "IN BOOLEAN MODE";
+    } else if (mode === "query expansion" || withQueryExpansion) {
+      modeClause = "WITH QUERY EXPANSION";
+    }
+
+    this.queryBuilder.query.where.push({
+      type: "fulltext",
+      raw: `MATCH(${columnList}) AGAINST(? ${modeClause})`,
+      boolean: "and",
+    });
+
+    this.queryBuilder.bindings.push(searchTerm);
+    return this.queryBuilder;
+  }
+
+  /**
+   * 布尔模式全文搜索
+   * @param {string|Array} columns - 要搜索的列
+   * @param {string} searchTerm - 带有布尔运算符的搜索词
+   * @returns {QueryBuilder} QueryBuilder 实例
+   */
+  fullTextBoolean(columns, searchTerm) {
+    return this.matchAgainst(columns, searchTerm, "boolean");
+  }
+
+  /**
+   * 查询扩展全文搜索
+   * @param {string|Array} columns - 要搜索的列
+   * @param {string} searchTerm - 搜索词
+   * @returns {QueryBuilder} QueryBuilder 实例
+   */
+  fullTextQueryExpansion(columns, searchTerm) {
+    return this.matchAgainst(columns, searchTerm, "query expansion", true);
+  }
+
+  /**
+   * 构建全文搜索 SQL
+   * @param {Object} fullTextSearch - 全文搜索配置
+   * @returns {string} SQL 片段
+   */
+  buildFullTextSearchSQL(fullTextSearch) {
+    const { columns, searchTerm, mode } = fullTextSearch;
+    const columnList = Array.isArray(columns)
+      ? columns.map((col) => this.queryBuilder.wrapColumn(col)).join(", ")
+      : this.queryBuilder.wrapColumn(columns);
+
+    if (["mysql", "mariadb"].includes(this.queryBuilder.dialect)) {
+      let modeClause = "";
+      if (mode === "boolean") {
+        modeClause = "IN BOOLEAN MODE";
+      } else if (mode === "query expansion") {
+        modeClause = "WITH QUERY EXPANSION";
+      }
+
+      return `MATCH(${columnList}) AGAINST(? ${modeClause})`;
+    } else if (["postgresql", "postgres", "pg"].includes(this.queryBuilder.dialect)) {
+      const searchVector = Array.isArray(columns)
+        ? columns.map((col) => `to_tsvector(${col})`).join(" || ")
+        : `to_tsvector(${this.queryBuilder.wrapColumn(columns)})`;
+
+      return `${searchVector} @@ plainto_tsquery(?)`;
+    } else {
+      // 对于不支持全文搜索的数据库，使用 LIKE 模式
+      const columnArray = Array.isArray(columns) ? columns : [columns];
+      const likeConditions = columnArray.map((col) => {
+        return `${this.queryBuilder.wrapColumn(col)} LIKE ?`;
+      });
+
+      return `(${likeConditions.join(" OR ")})`;
+    }
+  }
+
+  /**
+   * 构建相关性排序 SQL
+   * @param {Object} orderByRelevance - 相关性排序配置
+   * @returns {string} SQL 片段
+   */
+  buildOrderByRelevanceSQL(orderByRelevance) {
+    const { columns, searchTerm } = orderByRelevance;
+    const columnList = Array.isArray(columns)
+      ? columns.map((col) => this.queryBuilder.wrapColumn(col)).join(", ")
+      : this.queryBuilder.wrapColumn(columns);
+
+    if (["mysql", "mariadb"].includes(this.queryBuilder.dialect)) {
+      return `MATCH(${columnList}) AGAINST(?) DESC`;
+    } else if (["postgresql", "postgres", "pg"].includes(this.queryBuilder.dialect)) {
+      const searchVector = Array.isArray(columns)
+        ? columns.map((col) => `to_tsvector(${col})`).join(" || ")
+        : `to_tsvector(${this.queryBuilder.wrapColumn(columns)})`;
+
+      return `ts_rank(${searchVector}, plainto_tsquery(?)) DESC`;
+    } else {
+      return null; // 不支持相关性排序
+    }
+  }
+}

package/src/plugins/GeospatialPlugin.js

@@ -0,0 +1,219 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/database/plugin/GeospatialPlugin
+ */
+import { BasePlugin } from "./BasePlugin.js";
+
+
+export class GeospatialPlugin extends BasePlugin {
+  constructor(queryBuilder) {
+    super(queryBuilder);
+    this.pluginName = "GeospatialPlugin";
+  }
+
+  _registerMethods() {
+    // 注册地理空间查询方法到 QueryBuilder
+    this.queryBuilder.whereDistance = this.whereDistance.bind(this);
+    this.queryBuilder.whereWithin = this.whereWithin.bind(this);
+    this.queryBuilder.whereIntersects = this.whereIntersects.bind(this);
+    this.queryBuilder.orderByDistance = this.orderByDistance.bind(this);
+    this.queryBuilder.selectDistance = this.selectDistance.bind(this);
+  }
+
+  /**
+   * WHERE 距离条件（适用于 MySQL/PostgreSQL）
+   * @param {string} column - 几何列名
+   * @param {Object} point - 点坐标 {latitude, longitude} 或 {x, y}
+   * @param {number} distance - 距离（米）
+   * @param {string} operator - 比较运算符 (<, <=, >, >=, =)
+   * @returns {QueryBuilder} QueryBuilder 实例
+   */
+  whereDistance(column, point, distance, operator = "<") {
+    const { latitude, longitude, x, y } = point;
+    const lat = latitude !== undefined ? latitude : y;
+    const lng = longitude !== undefined ? longitude : x;
+
+    if (["mysql", "mariadb"].includes(this.queryBuilder.dialect)) {
+      // MySQL 空间扩展
+      this.queryBuilder.whereRaw(
+        `ST_Distance_Sphere(${this.queryBuilder.wrapColumn(column)}, ST_GeomFromText(?)) ${operator} ?`,
+        [`POINT(${lng} ${lat})`, distance]
+      );
+    } else if (["postgresql", "postgres", "pg"].includes(this.queryBuilder.dialect)) {
+      // PostgreSQL PostGIS
+      this.queryBuilder.whereRaw(
+        `ST_Distance(${this.queryBuilder.wrapColumn(column)}::geography, ST_MakePoint(?, ?)::geography) ${operator} ?`,
+        [lng, lat, distance]
+      );
+    }
+
+    return this.queryBuilder;
+  }
+
+  /**
+   * WHERE 在多边形内条件
+   * @param {string} column - 几何列名
+   * @param {Array} polygon - 点数组 [{latitude, longitude}, ...]
+   * @returns {QueryBuilder} QueryBuilder 实例
+   */
+  whereWithin(column, polygon) {
+    const points = polygon
+      .map((p) => {
+        const { latitude, longitude, x, y } = p;
+        const lat = latitude !== undefined ? latitude : y;
+        const lng = longitude !== undefined ? longitude : x;
+        return `${lng} ${lat}`;
+      })
+      .join(", ");
+
+    const polygonWkt = `POLYGON((${points}))`;
+
+    if (["mysql", "mariadb"].includes(this.queryBuilder.dialect)) {
+      this.queryBuilder.whereRaw(
+        `ST_Within(${this.queryBuilder.wrapColumn(column)}, ST_GeomFromText(?))`,
+        [polygonWkt]
+      );
+    } else if (["postgresql", "postgres", "pg"].includes(this.queryBuilder.dialect)) {
+      this.queryBuilder.whereRaw(
+        `ST_Within(${this.queryBuilder.wrapColumn(column)}, ST_GeomFromText(?, 4326))`,
+        [polygonWkt]
+      );
+    }
+
+    return this.queryBuilder;
+  }
+
+  /**
+   * WHERE 与几何图形相交条件
+   * @param {string} column - 几何列名
+   * @param {Object} geometry - 几何对象
+   * @returns {QueryBuilder} QueryBuilder 实例
+   */
+  whereIntersects(column, geometry) {
+    let geometryWkt;
+
+    if (geometry.type === "point") {
+      const { latitude, longitude, x, y } = geometry;
+      const lat = latitude !== undefined ? latitude : y;
+      const lng = longitude !== undefined ? longitude : x;
+      geometryWkt = `POINT(${lng} ${lat})`;
+    } else if (geometry.type === "polygon") {
+      const points = geometry.coordinates
+        .map((p) => {
+          const { latitude, longitude, x, y } = p;
+          const lat = latitude !== undefined ? latitude : y;
+          const lng = longitude !== undefined ? longitude : x;
+          return `${lng} ${lat}`;
+        })
+        .join(", ");
+      geometryWkt = `POLYGON((${points}))`;
+    } else if (geometry.type === "linestring") {
+      const points = geometry.coordinates
+        .map((p) => {
+          const { latitude, longitude, x, y } = p;
+          const lat = latitude !== undefined ? latitude : y;
+          const lng = longitude !== undefined ? longitude : x;
+          return `${lng} ${lat}`;
+        })
+        .join(", ");
+      geometryWkt = `LINESTRING(${points})`;
+    }
+
+    if (geometryWkt) {
+      if (["mysql", "mariadb"].includes(this.queryBuilder.dialect)) {
+        this.queryBuilder.whereRaw(
+          `ST_Intersects(${this.queryBuilder.wrapColumn(column)}, ST_GeomFromText(?))`,
+          [geometryWkt]
+        );
+      } else if (["postgresql", "postgres", "pg"].includes(this.queryBuilder.dialect)) {
+        this.queryBuilder.whereRaw(
+          `ST_Intersects(${this.queryBuilder.wrapColumn(column)}, ST_GeomFromText(?, 4326))`,
+          [geometryWkt]
+        );
+      }
+    }
+
+    return this.queryBuilder;
+  }
+
+  /**
+   * 按距离排序
+   * @param {string} column - 几何列名
+   * @param {Object} point - 点坐标
+   * @param {string} direction - 排序方向 (asc, desc)
+   * @returns {QueryBuilder} QueryBuilder 实例
+   */
+  orderByDistance(column, point, direction = "asc") {
+    const { latitude, longitude, x, y } = point;
+    const lat = latitude !== undefined ? latitude : y;
+    const lng = longitude !== undefined ? longitude : x;
+
+    if (["mysql", "mariadb"].includes(this.queryBuilder.dialect)) {
+      this.queryBuilder.orderByRaw(
+        `ST_Distance_Sphere(${this.queryBuilder.wrapColumn(column)}, ST_GeomFromText(?)) ${direction.toUpperCase()}`,
+        [`POINT(${lng} ${lat})`]
+      );
+    } else if (["postgresql", "postgres", "pg"].includes(this.queryBuilder.dialect)) {
+      this.queryBuilder.orderByRaw(
+        `ST_Distance(${this.queryBuilder.wrapColumn(column)}::geography, ST_MakePoint(?, ?)::geography) ${direction.toUpperCase()}`,
+        [lng, lat]
+      );
+    }
+
+    return this.queryBuilder;
+  }
+
+  /**
+   * 在 SELECT 中计算距离
+   * @param {string} column - 几何列名
+   * @param {Object} point - 点坐标
+   * @param {string} alias - 列别名
+   * @returns {QueryBuilder} QueryBuilder 实例
+   */
+  selectDistance(column, point, alias = "distance") {
+    const { latitude, longitude, x, y } = point;
+    const lat = latitude !== undefined ? latitude : y;
+    const lng = longitude !== undefined ? longitude : x;
+
+    if (["mysql", "mariadb"].includes(this.queryBuilder.dialect)) {
+      this.queryBuilder.selectRaw(
+        `ST_Distance_Sphere(${this.queryBuilder.wrapColumn(column)}, ST_GeomFromText(?)) as ${alias}`,
+        [`POINT(${lng} ${lat})`]
+      );
+    } else if (["postgresql", "postgres", "pg"].includes(this.queryBuilder.dialect)) {
+      this.queryBuilder.selectRaw(
+        `ST_Distance(${this.queryBuilder.wrapColumn(column)}::geography, ST_MakePoint(?, ?)::geography) as ${alias}`,
+        [lng, lat]
+      );
+    }
+
+    return this.queryBuilder;
+  }
+
+  /**
+   * 获取支持的地理空间函数
+   * @returns {Array} 支持的函数列表
+   */
+  getSupportedFunctions() {
+    const functions = {
+      mysql: ["ST_Distance_Sphere", "ST_Within", "ST_Intersects", "ST_GeomFromText"],
+      mariadb: ["ST_Distance_Sphere", "ST_Within", "ST_Intersects", "ST_GeomFromText"],
+      postgresql: ["ST_Distance", "ST_Within", "ST_Intersects", "ST_MakePoint", "ST_GeomFromText"],
+      postgres: ["ST_Distance", "ST_Within", "ST_Intersects", "ST_MakePoint", "ST_GeomFromText"],
+      pg: ["ST_Distance", "ST_Within", "ST_Intersects", "ST_MakePoint", "ST_GeomFromText"],
+    };
+
+    return functions[this.queryBuilder.dialect] || [];
+  }
+
+  /**
+   * 检查数据库是否支持地理空间查询
+   * @returns {boolean} 是否支持
+   */
+  isGeospatialSupported() {
+    const supportedDialects = ["mysql", "mariadb", "postgresql", "postgres", "pg"];
+    return supportedDialects.includes(this.queryBuilder.dialect);
+  }
+}