jsql-neo 1.1.0 → 1.2.0

package/index.js

@@ -21,5 +21,6 @@
 
 module.exports = {
     Database: require('./lib/database'),
-    Table: require('./lib/table')
+    Table: require('./lib/table'),
+    Query: require('./lib/query')
 };

package/lib/database.js

@@ -1,11 +1,12 @@
 // © Vexify 2026 All Rights Reserved.
 /**
  * JSQL Database — 数据库管理器
- * 管理表集合、文件持久化、自动保存
+ * 支持加密、插件系统、迁移、版本历史、变更流、响应式查询
  */
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const Table = require('./table');
 
 class Database {
@@ -13,8 +14,10 @@ class Database {
      * @param {string} filePath - 数据库文件路径，传 null 或 ':memory:' 使用内存模式
      * @param {object} options
      * @param {boolean} options.autoSave - 是否自动保存（默认 true）
-     * @param {number} options.autoSaveInterval - 自动保存间隔 ms（默认 0，即每次操作后保存）
+     * @param {number} options.autoSaveInterval - 自动保存间隔 ms（默认 0）
      * @param {boolean} options.pretty - JSON 是否格式化（默认 true）
+     * @param {string} options.encryptKey - 加密密钥（16/24/32 字节），启用 AES-256-CBC
+     * @param {boolean} options.versioning - 是否启用版本历史（默认 false）
      */
     constructor(filePath, options = {}) {
         this._filePath = filePath;
@@ -24,11 +27,19 @@ class Database {
             autoSaveInterval: options.autoSaveInterval || 0,
             pretty: options.pretty !== false
         };
-        this._tables = {};       // 表名 -> Table 实例
+        this._tables = {};
         this._dirty = false;
         this._autoSaveTimer = null;
-        this._loading = false;     // 加载中，不触发自动保存
-        this._transaction = null;   // 事务快照 { tables, autoIncrements }
+        this._loading = false;
+        this._transaction = null;
+        this._encryptKey = options.encryptKey || null;
+        this._versioning = options.versioning || false;
+        this._versions = {};       // tableName -> [{ rows, timestamp }]
+        this._maxVersions = options.maxVersions || 50;
+        this._plugins = [];
+        this._migrations = [];
+        this._observers = [];      // 响应式观察者
+        this._changeStream = null; // 变更流
 
         // 从文件加载
         if (!this._memoryMode && fs.existsSync(this._filePath)) {
@@ -42,17 +53,6 @@ class Database {
     // 表管理
     // ============================================================
 
-    /**
-     * 创建表
-     * @param {string} name - 表名
-     * @param {object} schema - 表结构定义
-     * @example
-     * db.createTable('users', {
-     *   id: { type: 'integer', primaryKey: true, autoIncrement: true },
-     *   name: { type: 'string', required: true },
-     *   email: { type: 'string', unique: true }
-     * })
-     */
     createTable(name, schema) {
         if (this._tables[name]) {
             throw new Error(`Table '${name}' already exists`);
@@ -60,39 +60,32 @@ class Database {
         const table = new Table(name, schema, this);
         this._tables[name] = table;
 
-        // 动态代理到 Database 实例上，方便 db.users.insert() 调用
         Object.defineProperty(this, name, {
             get: () => this._tables[name],
             enumerable: true,
             configurable: true
         });
 
+        if (this._versioning) {
+            this._versions[name] = [];
+        }
+
         this._markDirty();
         return table;
     }
 
-    /**
-     * 删除表
-     */
     dropTable(name) {
-        if (!this._tables[name]) {
-            throw new Error(`Table '${name}' does not exist`);
-        }
+        if (!this._tables[name]) throw new Error(`Table '${name}' does not exist`);
         delete this._tables[name];
         delete this[name];
+        delete this._versions[name];
         this._markDirty();
     }
 
-    /**
-     * 判断表是否存在
-     */
     hasTable(name) {
         return !!this._tables[name];
     }
 
-    /**
-     * 获取所有表名
-     */
     getTables() {
         return Object.keys(this._tables);
     }
@@ -101,47 +94,27 @@ class Database {
     // 事务
     // ============================================================
 
-    /**
-     * 开始事务
-     * 保存当前数据快照，后续操作可回滚
-     */
     begin() {
-        if (this._transaction) {
-            throw new Error('Transaction already in progress');
-        }
-        this._transaction = {
-            rows: {},
-            autoIncrements: {}
-        };
+        if (this._transaction) throw new Error('Transaction already in progress');
+        this._transaction = { rows: {}, autoIncrements: {} };
         for (const [name, table] of Object.entries(this._tables)) {
             this._transaction.rows[name] = table._rows.map(r => ({ ...r }));
             this._transaction.autoIncrements[name] = table._autoIncrement;
         }
     }
 
-    /**
-     * 提交事务
-     */
     commit() {
-        if (!this._transaction) {
-            throw new Error('No transaction in progress');
-        }
+        if (!this._transaction) throw new Error('No transaction in progress');
         this._transaction = null;
         this._markDirty();
     }
 
-    /**
-     * 回滚事务
-     */
     rollback() {
-        if (!this._transaction) {
-            throw new Error('No transaction in progress');
-        }
+        if (!this._transaction) throw new Error('No transaction in progress');
         for (const [name, table] of Object.entries(this._tables)) {
             if (this._transaction.rows[name]) {
                 table._rows = this._transaction.rows[name];
                 table._autoIncrement = this._transaction.autoIncrements[name];
-                // 重建索引
                 for (const field of Object.keys(table._indexes)) {
                     table.createIndex(field);
                 }
@@ -150,41 +123,216 @@ class Database {
         this._transaction = null;
     }
 
-    /**
-     * 是否在事务中
-     */
     inTransaction() {
         return !!this._transaction;
     }
 
     // ============================================================
-    // 备份与恢复
+    // 版本历史
     // ============================================================
 
     /**
-     * 备份到文件
+     * 保存当前快照
      */
+    snapshot(tableName) {
+        if (!this._versioning) return;
+        const table = this._tables[tableName];
+        if (!table) return;
+        if (!this._versions[tableName]) this._versions[tableName] = [];
+
+        // 空表跳过
+        if (table._rows.length === 0) return;
+
+        // 去重：如果当前状态与上次快照相同，跳过
+        const currentHash = JSON.stringify(table._rows);
+        const versions = this._versions[tableName];
+        if (versions.length > 0 && versions[versions.length - 1]._hash === currentHash) return;
+
+        versions.push({
+            rows: table._rows.map(r => ({ ...r })),
+            timestamp: Date.now(),
+            _hash: currentHash
+        });
+        if (versions.length > this._maxVersions) {
+            versions.shift();
+        }
+    }
+
+    /**
+     * 回退到指定版本
+     */
+    undo(tableName, steps = 1) {
+        if (!this._versioning) throw new Error('Versioning is not enabled');
+        const versions = this._versions[tableName];
+        if (!versions || versions.length < 2) throw new Error('No versions to undo');
+        const table = this._tables[tableName];
+        if (!table) throw new Error(`Table '${tableName}' not found`);
+
+        for (let i = 0; i < steps && versions.length > 1; i++) {
+            versions.pop();  // 丢弃最新版本
+            const snapshot = versions[versions.length - 1];  // 恢复到上一个版本
+            table._rows = snapshot.rows.map(r => ({ ...r }));
+            table._autoIncrement = 0;
+            for (const row of table._rows) {
+                if (table._autoIncrementField && row[table._autoIncrementField] > table._autoIncrement) {
+                    table._autoIncrement = row[table._autoIncrementField];
+                }
+            }
+            for (const field of Object.keys(table._indexes)) {
+                table.createIndex(field);
+            }
+        }
+        this._markDirty();
+        return versions.length;
+    }
+
+    getVersions(tableName) {
+        return this._versions[tableName] || [];
+    }
+
+    // ============================================================
+    // 变更流 & 响应式
+    // ============================================================
+
+    /**
+     * 监听变更事件
+     * @param {function} callback - (event) => {}  event: { type, table, data, timestamp }
+     */
+    onChange(callback) {
+        this._observers.push(callback);
+        return () => {
+            this._observers = this._observers.filter(cb => cb !== callback);
+        };
+    }
+
+    _emitChange(type, table, data) {
+        const event = { type, table, data, timestamp: Date.now() };
+        for (const cb of this._observers) {
+            try { cb(event); } catch (e) { /* ignore */ }
+        }
+    }
+
+    /**
+     * 创建变更流（返回异步迭代器）
+     */
+    createChangeStream() {
+        const events = [];
+        let resolve = null;
+        const unsubscribe = this.onChange(event => {
+            events.push(event);
+            if (resolve) {
+                resolve();
+                resolve = null;
+            }
+        });
+
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    next: async () => {
+                        while (events.length === 0) {
+                            await new Promise(r => resolve = r);
+                        }
+                        return { value: events.shift(), done: false };
+                    }
+                };
+            },
+            close: unsubscribe
+        };
+    }
+
+    // ============================================================
+    // 插件系统
+    // ============================================================
+
+    /**
+     * 注册插件
+     * @param {object} plugin - { name, install(db) }
+     */
+    use(plugin) {
+        if (typeof plugin.install !== 'function') {
+            throw new Error('Plugin must have an install() method');
+        }
+        this._plugins.push(plugin);
+        plugin.install(this);
+        return this;
+    }
+
+    // ============================================================
+    // 迁移
+    // ============================================================
+
+    /**
+     * 注册迁移
+     * @param {object} migration - { version, name, up(db), down(db) }
+     */
+    addMigration(migration) {
+        this._migrations.push(migration);
+        this._migrations.sort((a, b) => a.version - b.version);
+    }
+
+    /**
+     * 执行迁移到指定版本
+     */
+    migrate(targetVersion) {
+        const current = this._getCurrentVersion();
+        if (targetVersion === undefined) {
+            targetVersion = this._migrations.length > 0
+                ? this._migrations[this._migrations.length - 1].version
+                : 0;
+        }
+
+        if (targetVersion > current) {
+            for (const m of this._migrations) {
+                if (m.version > current && m.version <= targetVersion) {
+                    m.up(this);
+                    this._setCurrentVersion(m.version);
+                }
+            }
+        } else if (targetVersion < current) {
+            for (const m of this._migrations.reverse()) {
+                if (m.version <= current && m.version > targetVersion) {
+                    m.down(this);
+                    this._setCurrentVersion(m.version - 1);
+                }
+            }
+        }
+    }
+
+    _getCurrentVersion() {
+        return this._tables['__meta__']
+            ? (this._tables['__meta__'].findOne({ key: 'version' })?.value || 0)
+            : 0;
+    }
+
+    _setCurrentVersion(version) {
+        if (!this._tables['__meta__']) {
+            this.createTable('__meta__', {
+                key: { type: 'string', primaryKey: true },
+                value: { type: 'any' }
+            });
+        }
+        this._tables['__meta__'].upsert({ key: 'version', value: version });
+    }
+
+    // ============================================================
+    // 备份与恢复
+    // ============================================================
+
     backup(filePath) {
         const data = this.export();
         const json = this._options.pretty
             ? JSON.stringify(data, null, 2)
             : JSON.stringify(data);
-        const dir = path.dirname(filePath);
-        if (!fs.existsSync(dir)) {
-            fs.mkdirSync(dir, { recursive: true });
-        }
-        fs.writeFileSync(filePath, json, 'utf8');
+        this._writeFile(filePath, json);
         return filePath;
     }
 
-    /**
-     * 从文件恢复（覆盖当前数据）
-     */
     restore(filePath) {
         if (!fs.existsSync(filePath)) {
             throw new Error(`Backup file not found: ${filePath}`);
         }
-        const json = fs.readFileSync(filePath, 'utf8');
+        const json = this._readFile(filePath);
         const data = JSON.parse(json);
         for (const [name, rows] of Object.entries(data)) {
             if (this._tables[name]) {
@@ -198,39 +346,35 @@ class Database {
     // 持久化
     // ============================================================
 
-    /**
-     * 手动保存到文件
-     */
     save() {
+        // 版本快照（内存模式也支持）
+        if (this._versioning) {
+            for (const name of Object.keys(this._tables)) {
+                this.snapshot(name);
+            }
+        }
+
         if (this._memoryMode) return;
 
-        const data = { __schema__: {} };
+        const data = { __schema__: {}, __meta__: { version: this._getCurrentVersion() } };
         for (const [name, table] of Object.entries(this._tables)) {
+            if (name === '__meta__') continue;
             data.__schema__[name] = table._schema;
             data[name] = table.toJSON();
         }
 
-        const dir = path.dirname(this._filePath);
-        if (!fs.existsSync(dir)) {
-            fs.mkdirSync(dir, { recursive: true });
-        }
-
         const json = this._options.pretty
             ? JSON.stringify(data, null, 2)
             : JSON.stringify(data);
-        fs.writeFileSync(this._filePath, json, 'utf8');
+        this._writeFile(this._filePath, json);
         this._dirty = false;
     }
 
-    /**
-     * 从文件加载
-     */
     _load() {
         try {
-            const json = fs.readFileSync(this._filePath, 'utf8');
+            const json = this._readFile(this._filePath);
             const data = JSON.parse(json);
 
-            // 先根据 schema 重建表
             if (data.__schema__) {
                 for (const [name, schema] of Object.entries(data.__schema__)) {
                     if (!this._tables[name]) {
@@ -239,9 +383,8 @@ class Database {
                 }
             }
 
-            // 加载数据
             for (const [name, rows] of Object.entries(data)) {
-                if (name !== '__schema__' && this._tables[name]) {
+                if (name !== '__schema__' && name !== '__meta__' && this._tables[name]) {
                     this._tables[name]._loadRows(rows);
                 }
             }
@@ -250,12 +393,9 @@ class Database {
         }
     }
 
-    /**
-     * 标记脏数据（触发自动保存）
-     */
     _markDirty() {
         this._dirty = true;
-        if (this._loading) return;  // 加载中不保存
+        if (this._loading) return;
         if (this._options.autoSave && !this._autoSaveTimer) {
             if (this._options.autoSaveInterval > 0) {
                 this._autoSaveTimer = setTimeout(() => {
@@ -263,15 +403,11 @@ class Database {
                     if (this._dirty) this.save();
                 }, this._options.autoSaveInterval);
             } else {
-                // 立即保存（同步）
                 this.save();
             }
         }
     }
 
-    /**
-     * 关闭数据库（保存并清理）
-     */
     close() {
         if (this._autoSaveTimer) {
             clearTimeout(this._autoSaveTimer);
@@ -283,20 +419,15 @@ class Database {
         this._tables = {};
     }
 
-    /**
-     * 导出数据库为 JSON 对象
-     */
     export() {
         const data = {};
         for (const [name, table] of Object.entries(this._tables)) {
+            if (name === '__meta__') continue;
             data[name] = table.toJSON();
         }
         return data;
     }
 
-    /**
-     * 从 JSON 对象导入数据
-     */
     import(data) {
         for (const [name, rows] of Object.entries(data)) {
             if (this._tables[name]) {
@@ -305,6 +436,35 @@ class Database {
         }
         this._markDirty();
     }
+
+    // ============================================================
+    // 加密（内部）
+    // ============================================================
+
+    _writeFile(filePath, content) {
+        if (this._encryptKey) {
+            const iv = crypto.randomBytes(16);
+            const cipher = crypto.createCipheriv('aes-256-cbc', Buffer.from(this._encryptKey.padEnd(32).slice(0, 32)), iv);
+            const encrypted = Buffer.concat([cipher.update(content, 'utf8'), cipher.final()]);
+            const data = Buffer.concat([iv, encrypted]);
+            fs.writeFileSync(filePath, data.toString('base64'), 'utf8');
+        } else {
+            const dir = path.dirname(filePath);
+            if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(filePath, content, 'utf8');
+        }
+    }
+
+    _readFile(filePath) {
+        if (this._encryptKey) {
+            const data = Buffer.from(fs.readFileSync(filePath, 'utf8'), 'base64');
+            const iv = data.slice(0, 16);
+            const encrypted = data.slice(16);
+            const decipher = crypto.createDecipheriv('aes-256-cbc', Buffer.from(this._encryptKey.padEnd(32).slice(0, 32)), iv);
+            return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString('utf8');
+        }
+        return fs.readFileSync(filePath, 'utf8');
+    }
 }
 
 module.exports = Database;