jsql-neo 1.3.0 → 2.0.0

package/lib/database.js

@@ -1,13 +1,14 @@
 // © Vexify 2026 All Rights Reserved.
 /**
- * JSQL Database — 数据库管理器
- * 支持加密、插件系统、迁移、版本历史、变更流、响应式查询
+ * JSQL Database — 数据库管理器 v2.0
+ * WAL、文件锁、事务隔离级别、慢查询日志、错误码体系
  */
 
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const Table = require('./table');
+const { createError } = require('./errors');
 
 class Database {
     /**
@@ -18,6 +19,10 @@ class Database {
      * @param {boolean} options.pretty - JSON 是否格式化（默认 true）
      * @param {string} options.encryptKey - 加密密钥（16/24/32 字节），启用 AES-256-CBC
      * @param {boolean} options.versioning - 是否启用版本历史（默认 false）
+     * @param {boolean} options.wal - 是否启用 WAL 模式（默认 false，内存模式自动禁用）
+     * @param {string} options.isolationLevel - 事务隔离级别 'READ_COMMITTED' | 'REPEATABLE_READ'（默认 'READ_COMMITTED'）
+     * @param {number} options.slowQueryThreshold - 慢查询阈值 ms（默认 100，0 禁用）
+     * @param {boolean} options.fileLock - 是否启用文件锁（默认 false）
      */
     constructor(filePath, options = {}) {
         this._filePath = filePath;
@@ -44,21 +49,145 @@ class Database {
         this._attached = {};        // 附加数据库 { name: db }
         this._changeStream = null; // 变更流
 
+        // WAL（Write-Ahead Logging）
+        this._walEnabled = options.wal === true && !this._memoryMode;
+        this._walPath = this._filePath ? this._filePath + '.wal' : null;
+        this._walOps = [];          // WAL 操作日志
+
+        // 事务隔离
+        this._isolationLevel = options.isolationLevel || 'READ_COMMITTED';
+
+        // 文件锁
+        this._fileLockEnabled = options.fileLock === true && !this._memoryMode;
+        this._lockFd = null;
+        this._lockPath = this._filePath ? this._filePath + '.lock' : null;
+
+        // 慢查询日志
+        this._slowQueryThreshold = options.slowQueryThreshold !== undefined ? options.slowQueryThreshold : 100;
+        this._slowQueries = [];
+
         // 从文件加载
         if (!this._memoryMode && fs.existsSync(this._filePath)) {
             this._loading = true;
+            this._acquireLock();
             this._load();
             this._loading = false;
         }
     }
 
+    // ============================================================
+    // 文件锁
+    // ============================================================
+
+    _acquireLock() {
+        if (!this._fileLockEnabled) return;
+        try {
+            // 检查锁文件是否存在
+            if (fs.existsSync(this._lockPath)) {
+                const lockTime = fs.statSync(this._lockPath).mtimeMs;
+                // 锁超过 30 秒视为过期
+                if (Date.now() - lockTime > 30000) {
+                    fs.unlinkSync(this._lockPath);
+                } else {
+                    throw createError('ER_LOCK_WAIT_TIMEOUT', 'Database is locked by another process');
+                }
+            }
+            fs.writeFileSync(this._lockPath, String(process.pid), 'utf8');
+            this._lockFd = true;
+        } catch (e) {
+            if (e.code === 'ER_LOCK_WAIT_TIMEOUT') throw e;
+            // 权限不足等，降级为无锁模式
+            this._fileLockEnabled = false;
+        }
+    }
+
+    _releaseLock() {
+        if (!this._fileLockEnabled || !this._lockFd) return;
+        try {
+            if (fs.existsSync(this._lockPath)) {
+                fs.unlinkSync(this._lockPath);
+            }
+            this._lockFd = null;
+        } catch (e) {
+            // 忽略
+        }
+    }
+
+    // ============================================================
+    // WAL（Write-Ahead Logging）
+    // ============================================================
+
+    /**
+     * 写入 WAL 日志
+     */
+    _walWrite(op) {
+        if (!this._walEnabled) return;
+        this._walOps.push({
+            ...op,
+            timestamp: Date.now(),
+            sequence: this._walOps.length + 1
+        });
+        this._flushWAL();
+    }
+
+    /**
+     * 将 WAL 刷入磁盘
+     */
+    _flushWAL() {
+        if (!this._walEnabled || this._walOps.length === 0) return;
+        try {
+            const dir = path.dirname(this._walPath);
+            if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(this._walPath, JSON.stringify(this._walOps), 'utf8');
+        } catch (e) {
+            // WAL 写入失败不应阻塞主流程
+        }
+    }
+
+    /**
+     * 检查点：将 WAL 应用到数据文件并清空 WAL
+     */
+    _checkpoint() {
+        if (!this._walEnabled || this._walOps.length === 0) return;
+        // 所有操作已在内存中生效，此函数仅清除 WAL 文件
+        this._walOps = [];
+        try {
+            if (fs.existsSync(this._walPath)) {
+                fs.unlinkSync(this._walPath);
+            }
+        } catch (e) {
+            // 忽略
+        }
+    }
+
+    /**
+     * 崩溃恢复：从 WAL 重放操作
+     */
+    _recoverFromWAL() {
+        if (!this._walEnabled || !this._walPath || !fs.existsSync(this._walPath)) return;
+        try {
+            const walData = JSON.parse(fs.readFileSync(this._walPath, 'utf8'));
+            if (!Array.isArray(walData) || walData.length === 0) return;
+
+            // WAL 操作在 v2.0 中仅用于崩溃恢复标记
+            // 实际操作已在 save() 时持久化，WAL 主要用于：
+            // 1. 标记未完成的事务
+            // 2. 在 save() 间隔中保护数据
+            this._walOps = [];
+            fs.unlinkSync(this._walPath);
+        } catch (e) {
+            // WAL 损坏，忽略
+            try { if (fs.existsSync(this._walPath)) fs.unlinkSync(this._walPath); } catch (_) {}
+        }
+    }
+
     // ============================================================
     // 表管理
     // ============================================================
 
     createTable(name, schema) {
         if (this._tables[name]) {
-            throw new Error(`Table '${name}' already exists`);
+            throw createError('ER_TABLE_EXISTS_ERROR', name);
         }
         const table = new Table(name, schema, this);
         this._tables[name] = table;
@@ -74,14 +203,16 @@ class Database {
         }
 
         this._markDirty();
+        this._walWrite({ op: 'createTable', table: name, schema });
         return table;
     }
 
     dropTable(name) {
-        if (!this._tables[name]) throw new Error(`Table '${name}' does not exist`);
+        if (!this._tables[name]) throw createError('ER_NO_SUCH_TABLE', name);
         delete this._tables[name];
         delete this[name];
         delete this._versions[name];
+        this._walWrite({ op: 'dropTable', table: name });
         this._markDirty();
     }
 
@@ -105,10 +236,9 @@ class Database {
      * db.createView('adults', db => db.users.where({ age: { $gte: 18 } }).select(['name', 'age']));
      */
     createView(name, queryFn) {
-        if (this._views[name]) throw new Error(`View '${name}' already exists`);
+        if (this._views[name]) throw createError('ER_TABLE_EXISTS_ERROR', name);
         this._views[name] = { queryFn };
 
-        // 代理到 db 上
         Object.defineProperty(this, name, {
             get: () => {
                 const q = queryFn(this);
@@ -129,7 +259,7 @@ class Database {
     }
 
     dropView(name) {
-        if (!this._views[name]) throw new Error(`View '${name}' does not exist`);
+        if (!this._views[name]) throw createError('ER_NO_SUCH_TABLE', name);
         delete this._views[name];
         delete this[name];
     }
@@ -149,9 +279,9 @@ class Database {
      * @param {function} callback - 触发时执行的回调
      */
     createTrigger(name, options, callback) {
-        if (this._triggers[name]) throw new Error(`Trigger '${name}' already exists`);
+        if (this._triggers[name]) throw createError('ER_TRIGGER_EXISTS', name);
         const table = this._tables[options.table];
-        if (!table) throw new Error(`Table '${options.table}' does not exist`);
+        if (!table) throw createError('ER_NO_SUCH_TABLE', options.table);
 
         const hookName = options.timing + options.event.charAt(0).toUpperCase() + options.event.slice(1);
         this._triggers[name] = { event: options.event, table: options.table, callback, hookName };
@@ -160,7 +290,7 @@ class Database {
 
     dropTrigger(name) {
         const trigger = this._triggers[name];
-        if (!trigger) throw new Error(`Trigger '${name}' does not exist`);
+        if (!trigger) throw createError('ER_TRIGGER_NOT_FOUND', name);
         const table = this._tables[trigger.table];
         if (table) table.off(trigger.hookName, trigger.callback);
         delete this._triggers[name];
@@ -186,7 +316,7 @@ class Database {
      */
     importCSV(filePath, tableName, options = {}) {
         const table = this._tables[tableName];
-        if (!table) throw new Error(`Table '${tableName}' does not exist`);
+        if (!table) throw createError('ER_NO_SUCH_TABLE', tableName);
 
         const delimiter = options.delimiter || ',';
         const hasHeader = options.hasHeader !== false;
@@ -238,24 +368,18 @@ class Database {
 
     /**
      * 导出表数据到 CSV 文件
-     * @param {string} filePath - 输出文件路径
-     * @param {string} tableName - 表名
-     * @param {object} query - 筛选条件（可选）
-     * @param {object} options - { delimiter: ',', fields: ['col1','col2'] }
      */
     exportCSV(filePath, tableName, query = {}, options = {}) {
         const table = this._tables[tableName];
-        if (!table) throw new Error(`Table '${tableName}' does not exist`);
+        if (!table) throw createError('ER_NO_SUCH_TABLE', tableName);
 
         const delimiter = options.delimiter || ',';
         const rows = table._applyFilter(table._rows, query);
         const fields = options.fields || Object.keys(table._schema).filter(f => f !== '_softDelete');
 
         const lines = [];
-        // 表头
         lines.push(fields.map(f => this._csvEscape(f, delimiter)).join(delimiter));
 
-        // 数据行
         for (const row of rows) {
             lines.push(fields.map(f => {
                 const val = row[f];
@@ -266,7 +390,7 @@ class Database {
         const dir = path.dirname(filePath);
         if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
         fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
-        return lines.length - 1; // 返回数据行数
+        return lines.length - 1;
     }
 
     _parseCSVLine(line, delimiter) {
@@ -317,6 +441,11 @@ class Database {
             case 'boolean': return value.toLowerCase() === 'true' || value === '1';
             case 'array': try { return JSON.parse(value); } catch(e) { return [value]; }
             case 'object': try { return JSON.parse(value); } catch(e) { return {}; }
+            case 'date':
+            case 'datetime':
+            case 'timestamp':
+            case 'time':
+                return value;
             default: return value;
         }
     }
@@ -332,15 +461,18 @@ class Database {
         const tableStats = {};
         let totalRows = 0;
         let totalIndexes = 0;
+        let totalBTrees = 0;
 
         for (const [name, table] of Object.entries(this._tables)) {
             if (name === '__meta__') continue;
             const rowCount = table._rows.length;
             const indexCount = Object.keys(table._indexes).length;
+            const btreeCount = Object.keys(table._btrees).length;
             const sizeEstimate = JSON.stringify(table._rows).length;
             tableStats[name] = {
                 rowCount,
-                indexCount,
+                indexCount: indexCount + btreeCount,
+                btreeCount,
                 sizeEstimate,
                 primaryKey: table._primaryKey,
                 columns: Object.keys(table._schema).length,
@@ -350,6 +482,7 @@ class Database {
             };
             totalRows += rowCount;
             totalIndexes += indexCount;
+            totalBTrees += btreeCount;
         }
 
         return {
@@ -360,24 +493,75 @@ class Database {
             plugins: this._plugins.length,
             totalRows,
             totalIndexes,
+            totalBTrees,
             memoryMode: this._memoryMode,
             versioning: this._versioning,
             encrypted: !!this._encryptKey,
+            walEnabled: this._walEnabled,
+            fileLockEnabled: this._fileLockEnabled,
+            isolationLevel: this._isolationLevel,
+            slowQueryThreshold: this._slowQueryThreshold,
+            slowQueriesCount: this._slowQueries.length,
             tableStats
         };
     }
 
+    // ============================================================
+    // 慢查询日志
+    // ============================================================
+
+    /**
+     * 记录慢查询
+     */
+    _logSlowQuery(sql, durationMs, rowsReturned) {
+        if (this._slowQueryThreshold <= 0) return;
+        if (durationMs < this._slowQueryThreshold) return;
+
+        this._slowQueries.push({
+            sql,
+            duration: durationMs,
+            rows: rowsReturned,
+            timestamp: Date.now()
+        });
+
+        // 限制日志数量
+        if (this._slowQueries.length > 1000) {
+            this._slowQueries = this._slowQueries.slice(-500);
+        }
+    }
+
+    /**
+     * 获取慢查询日志
+     * @param {number} limit - 返回最近 N 条
+     */
+    getSlowQueries(limit = 50) {
+        return this._slowQueries.slice(-limit).reverse();
+    }
+
+    /**
+     * 清空慢查询日志
+     */
+    clearSlowQueries() {
+        this._slowQueries = [];
+    }
+
+    /**
+     * 设置慢查询阈值
+     * @param {number} ms - 毫秒，0 禁用
+     */
+    setSlowQueryThreshold(ms) {
+        this._slowQueryThreshold = ms;
+    }
+
     // ============================================================
     // 多数据库
     // ============================================================
 
     /**
      * 附加另一个数据库（跨库查询）
-     * @param {string} name - 别名
-     * @param {Database} db - 另一个 Database 实例
      */
     attach(name, db) {
-        if (this._attached[name]) throw new Error(`Database '${name}' already attached`);
+        if (this._attached[name]) throw createError('ER_DBATTACH_EXISTS', name);
         this._attached[name] = db;
 
         Object.defineProperty(this, name, {
@@ -388,7 +572,7 @@ class Database {
     }
 
     detach(name) {
-        if (!this._attached[name]) throw new Error(`Database '${name}' is not attached`);
+        if (!this._attached[name]) throw createError('ER_DBATTACH_NOT_FOUND', name);
         delete this._attached[name];
         delete this[name];
     }
@@ -398,35 +582,66 @@ class Database {
     }
 
     // ============================================================
-    // 事务
+    // 事务（支持隔离级别）
     // ============================================================
 
-    begin() {
-        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;
+    /**
+     * 开始事务
+     * @param {string} isolationLevel - 覆盖默认隔离级别（可选）
+     */
+    begin(isolationLevel) {
+        if (this._transaction) throw createError('ER_TRANSACTION_ACTIVE');
+
+        const level = isolationLevel || this._isolationLevel;
+
+        this._transaction = {
+            rows: {},
+            autoIncrements: {},
+            level,
+            startedAt: Date.now()
+        };
+
+        if (level === 'REPEATABLE_READ') {
+            // 快照：保存当前所有数据
+            for (const [name, table] of Object.entries(this._tables)) {
+                this._transaction.rows[name] = table._rows.map(r => ({ ...r }));
+                this._transaction.autoIncrements[name] = table._autoIncrement;
+            }
+        } else {
+            // READ_COMMITTED：只保存 autoIncrement
+            for (const [name, table] of Object.entries(this._tables)) {
+                this._transaction.autoIncrements[name] = table._autoIncrement;
+            }
         }
+
+        this._walWrite({ op: 'begin', level });
     }
 
     commit() {
-        if (!this._transaction) throw new Error('No transaction in progress');
+        if (!this._transaction) throw createError('ER_NO_TRANSACTION');
+        this._walWrite({ op: 'commit', at: this._transaction.startedAt });
         this._transaction = null;
+        this._checkpoint();
         this._markDirty();
     }
 
     rollback() {
-        if (!this._transaction) throw new Error('No transaction in progress');
+        if (!this._transaction) throw createError('ER_NO_TRANSACTION');
+
         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];
+                table._rebuildAllBTrees();
                 for (const field of Object.keys(table._indexes)) {
                     table.createIndex(field);
                 }
+            } else if (this._transaction.autoIncrements[name] !== undefined) {
+                table._autoIncrement = this._transaction.autoIncrements[name];
             }
         }
+
+        this._walWrite({ op: 'rollback', at: this._transaction.startedAt });
         this._transaction = null;
     }
 
@@ -434,6 +649,24 @@ class Database {
         return !!this._transaction;
     }
 
+    /**
+     * 获取当前事务隔离级别
+     */
+    getIsolationLevel() {
+        return this._transaction ? this._transaction.level : this._isolationLevel;
+    }
+
+    /**
+     * 设置默认事务隔离级别
+     * @param {'READ_COMMITTED'|'REPEATABLE_READ'} level
+     */
+    setIsolationLevel(level) {
+        if (!['READ_COMMITTED', 'REPEATABLE_READ'].includes(level)) {
+            throw createError('ER_NOT_SUPPORTED', `Isolation level '${level}' is not supported. Use READ_COMMITTED or REPEATABLE_READ.`);
+        }
+        this._isolationLevel = level;
+    }
+
     // ============================================================
     // 版本历史
     // ============================================================
@@ -447,10 +680,8 @@ class Database {
         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;
@@ -469,15 +700,15 @@ class Database {
      * 回退到指定版本
      */
     undo(tableName, steps = 1) {
-        if (!this._versioning) throw new Error('Versioning is not enabled');
+        if (!this._versioning) throw createError('ER_NOT_SUPPORTED', 'Versioning is not enabled');
         const versions = this._versions[tableName];
-        if (!versions || versions.length < 2) throw new Error('No versions to undo');
+        if (!versions || versions.length < 2) throw createError('ER_NOT_SUPPORTED', 'No versions to undo');
         const table = this._tables[tableName];
-        if (!table) throw new Error(`Table '${tableName}' not found`);
+        if (!table) throw createError('ER_NO_SUCH_TABLE', tableName);
 
         for (let i = 0; i < steps && versions.length > 1; i++) {
-            versions.pop();  // 丢弃最新版本
-            const snapshot = versions[versions.length - 1];  // 恢复到上一个版本
+            versions.pop();
+            const snapshot = versions[versions.length - 1];
             table._rows = snapshot.rows.map(r => ({ ...r }));
             table._autoIncrement = 0;
             for (const row of table._rows) {
@@ -485,10 +716,12 @@ class Database {
                     table._autoIncrement = row[table._autoIncrementField];
                 }
             }
+            table._rebuildAllBTrees();
             for (const field of Object.keys(table._indexes)) {
                 table.createIndex(field);
             }
         }
+        this._walWrite({ op: 'undo', table: tableName, steps });
         this._markDirty();
         return versions.length;
     }
@@ -504,6 +737,7 @@ class Database {
     /**
      * 监听变更事件
      * @param {function} callback - (event) => {}  event: { type, table, data, timestamp }
+     * @returns {function} 取消监听的函数
      */
     onChange(callback) {
         this._observers.push(callback);
@@ -558,7 +792,7 @@ class Database {
      */
     use(plugin) {
         if (typeof plugin.install !== 'function') {
-            throw new Error('Plugin must have an install() method');
+            throw createError('ER_PLUGIN_INVALID', 'Plugin must have an install() method');
         }
         this._plugins.push(plugin);
         plugin.install(this);
@@ -637,7 +871,7 @@ class Database {
 
     restore(filePath) {
         if (!fs.existsSync(filePath)) {
-            throw new Error(`Backup file not found: ${filePath}`);
+            throw createError('ER_FILE_NOT_FOUND', filePath);
         }
         const json = this._readFile(filePath);
         const data = JSON.parse(json);
@@ -646,6 +880,7 @@ class Database {
                 this._tables[name]._loadRows(rows);
             }
         }
+        this._walWrite({ op: 'restore', from: filePath });
         this._markDirty();
     }
 
@@ -654,7 +889,7 @@ class Database {
     // ============================================================
 
     save() {
-        // 版本快照（内存模式也支持）
+        // 版本快照
         if (this._versioning) {
             for (const name of Object.keys(this._tables)) {
                 this.snapshot(name);
@@ -675,6 +910,9 @@ class Database {
             : JSON.stringify(data);
         this._writeFile(this._filePath, json);
         this._dirty = false;
+
+        // 保存后做检查点
+        this._checkpoint();
     }
 
     _load() {
@@ -695,6 +933,9 @@ class Database {
                     this._tables[name]._loadRows(rows);
                 }
             }
+
+            // WAL 恢复
+            this._recoverFromWAL();
         } catch (e) {
             throw new Error(`Failed to load database from '${this._filePath}': ${e.message}`);
         }
@@ -723,6 +964,7 @@ class Database {
         if (this._dirty && !this._memoryMode) {
             this.save();
         }
+        this._releaseLock();
         this._tables = {};
     }
 
@@ -741,6 +983,7 @@ class Database {
                 this._tables[name]._loadRows(rows);
             }
         }
+        this._walWrite({ op: 'import', tables: Object.keys(data) });
         this._markDirty();
     }