jsql-neo 2.0.0 → 2.1.0

package/README.md

@@ -1,33 +1,514 @@
-```
-                                                                                                                                                                     
-                                                                                                                                                                     
-          JJJJJJJJJJJ   SSSSSSSSSSSSSSS      QQQQQQQQQ     LLLLLLLLLLL                                                                                               
-          J:::::::::J SS:::::::::::::::S   QQ:::::::::QQ   L:::::::::L                                                                                               
-          J:::::::::JS:::::SSSSSS::::::S QQ:::::::::::::QQ L:::::::::L                                                                                               
-          JJ:::::::JJS:::::S     SSSSSSSQ:::::::QQQ:::::::QLL:::::::LL                                                                                               
-            J:::::J  S:::::S            Q::::::O   Q::::::Q  L:::::L                                          nnnn  nnnnnnnn        eeeeeeeeeeee       ooooooooooo   
-            J:::::J  S:::::S            Q:::::O     Q:::::Q  L:::::L                                          n:::nn::::::::nn    ee::::::::::::ee   oo:::::::::::oo 
-            J:::::J   S::::SSSS         Q:::::O     Q:::::Q  L:::::L                                          n::::::::::::::nn  e::::::eeeee:::::eeo:::::::::::::::o
-            J:::::j    SS::::::SSSSS    Q:::::O     Q:::::Q  L:::::L                     ---------------      nn:::::::::::::::ne::::::e     e:::::eo:::::ooooo:::::o
-            J:::::J      SSS::::::::SS  Q:::::O     Q:::::Q  L:::::L                     -:::::::::::::-        n:::::nnnn:::::ne:::::::eeeee::::::eo::::o     o::::o
-JJJJJJJ     J:::::J         SSSSSS::::S Q:::::O     Q:::::Q  L:::::L                     ---------------        n::::n    n::::ne:::::::::::::::::e o::::o     o::::o
-J:::::J     J:::::J              S:::::SQ:::::O  QQQQ:::::Q  L:::::L                                            n::::n    n::::ne::::::eeeeeeeeeee  o::::o     o::::o
-J::::::J   J::::::J              S:::::SQ::::::O Q::::::::Q  L:::::L         LLLLLL                             n::::n    n::::ne:::::::e           o::::o     o::::o
-J:::::::JJJ:::::::J  SSSSSSS     S:::::SQ:::::::QQ::::::::QLL:::::::LLLLLLLLL:::::L                             n::::n    n::::ne::::::::e          o:::::ooooo:::::o
- JJ:::::::::::::JJ   S::::::SSSSSS:::::S QQ::::::::::::::Q L::::::::::::::::::::::L                             n::::n    n::::n e::::::::eeeeeeee  o:::::::::::::::o
-   JJ:::::::::JJ     S:::::::::::::::SS    QQ:::::::::::Q  L::::::::::::::::::::::L                             n::::n    n::::n  ee:::::::::::::e   oo:::::::::::oo 
-     JJJJJJJJJ        SSSSSSSSSSSSSSS        QQQQQQQQ::::QQLLLLLLLLLLLLLLLLLLLLLLLL                             nnnnnn    nnnnnn    eeeeeeeeeeeeee     ooooooooooo   
-                                                     Q:::::Q                                                                                                         
-                                                      QQQQQQ                                                                                                         
-                                                                                                                                                                     
-                                                                                                                                                                     
-                                                                                                                                                                     
-                                                                                                                                                                     
-                                                                                                                                                                     
-```
-```
-.----.  .----. .-. . .-..----..----.    .----..-.  .-.   .-. .-..----..-.  .-..-..----..-.  .-.
-| {}  }/  {}  \| |/ \| || {_  | {}  }   | {}  }\ \/ /    | | | || {_   \ \/ / | || {_   \ \/ / 
-| .--' \      /|  .'.  || {__ | .-. \   | {}  } }  {     \ \_/ /| {__  / /\ \ | || |     }  {  
-`-'     `----' `-'   `-'`----'`-' `-'   `----'  `--'      `---' `----'`-'  `-'`-'`-'     `--'  
-```
+```
+                                                                                                                                                                     
+                                                                                                                                                                     
+          JJJJJJJJJJJ   SSSSSSSSSSSSSSS      QQQQQQQQQ     LLLLLLLLLLL                                                                                               
+          J:::::::::J SS:::::::::::::::S   QQ:::::::::QQ   L:::::::::L                                                                                               
+          J:::::::::JS:::::SSSSSS::::::S QQ:::::::::::::QQ L:::::::::L                                                                                               
+          JJ:::::::JJS:::::S     SSSSSSSQ:::::::QQQ:::::::QLL:::::::LL                                                                                               
+            J:::::J  S:::::S            Q::::::O   Q::::::Q  L:::::L                                          nnnn  nnnnnnnn        eeeeeeeeeeee       ooooooooooo   
+            J:::::J  S:::::S            Q:::::O     Q:::::Q  L:::::L                                          n:::nn::::::::nn    ee::::::::::::ee   oo:::::::::::oo 
+            J:::::J   S::::SSSS         Q:::::O     Q:::::Q  L:::::L                                          n::::::::::::::nn  e::::::eeeee:::::eeo:::::::::::::::o
+            J:::::j    SS::::::SSSSS    Q:::::O     Q:::::Q  L:::::L                     ---------------      nn:::::::::::::::ne::::::e     e:::::eo:::::ooooo:::::o
+            J:::::J      SSS::::::::SS  Q:::::O     Q:::::Q  L:::::L                     -:::::::::::::-        n:::::nnnn:::::ne:::::::eeeee::::::eo::::o     o::::o
+JJJJJJJ     J:::::J         SSSSSS::::S Q:::::O     Q:::::Q  L:::::L                     ---------------        n::::n    n::::ne:::::::::::::::::e o::::o     o::::o
+J:::::J     J:::::J              S:::::SQ:::::O  QQQQ:::::Q  L:::::L                                            n::::n    n::::ne::::::eeeeeeeeeee  o::::o     o::::o
+J::::::J   J::::::J              S:::::SQ::::::O Q::::::::Q  L:::::L         LLLLLL                             n::::n    n::::ne:::::::e           o::::o     o::::o
+J:::::::JJJ:::::::J  SSSSSSS     S:::::SQ:::::::QQ::::::::QLL:::::::LLLLLLLLL:::::L                             n::::n    n::::ne::::::::e          o:::::ooooo:::::o
+ JJ:::::::::::::JJ   S::::::SSSSSS:::::S QQ::::::::::::::Q L::::::::::::::::::::::L                             n::::n    n::::n e::::::::eeeeeeee  o:::::::::::::::o
+   JJ:::::::::JJ     S:::::::::::::::SS    QQ:::::::::::Q  L::::::::::::::::::::::L                             n::::n    n::::n  ee:::::::::::::e   oo:::::::::::oo 
+     JJJJJJJJJ        SSSSSSSSSSSSSSS        QQQQQQQQ::::QQLLLLLLLLLLLLLLLLLLLLLLLL                             nnnnnn    nnnnnn    eeeeeeeeeeeeee     ooooooooooo   
+                                                     Q:::::Q                                                                                                         
+                                                      QQQQQQ                                                                                                         
+```
+
+# JSQL-NEO
+
+**Pure JavaScript Embedded Database — SQL 风格 API，零原生依赖，JSON 文件存储**
+
+[![npm version](https://img.shields.io/npm/v/jsql-neo.svg)](https://www.npmjs.com/package/jsql-neo)
+[![license](https://img.shields.io/npm/l/jsql-neo.svg)](https://github.com/vexify-org/jsql-neo/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/jsql-neo.svg)](https://nodejs.org/)
+
+> **v2.0.0** — B-Tree 索引、哈希 JOIN、WAL 日志、事务隔离、MySQL 风格错误码
+
+---
+
+## 快速开始
+
+```bash
+npm install jsql-neo
+```
+
+```javascript
+const jsql = require('jsql-neo');
+
+// 内存模式
+const db = new jsql.Database(':memory:');
+
+// 文件模式（带 WAL + 文件锁）
+const db = new jsql.Database('mydb.json', {
+  wal: true,
+  fileLock: true,
+  isolationLevel: 'REPEATABLE_READ',
+  slowQueryThreshold: 100
+});
+
+// 创建表（自动为 primaryKey 和 unique 字段建 B-Tree 索引）
+db.createTable('users', {
+  id: { type: 'integer', primaryKey: true, autoIncrement: true },
+  name: { type: 'string', required: true, length: 50 },
+  email: { type: 'string', unique: true },
+  age: { type: 'integer', min: 0, max: 150 },
+  createdAt: { type: 'datetime', default: 'CURRENT_TIMESTAMP' }
+});
+
+// 插入
+db.users.insert({ name: 'Alice', email: 'alice@example.com', age: 25 });
+
+// 主键查询（B-Tree 加速，O(log n)）
+db.users.findById(1);
+
+// 链式查询
+db.users.where({ age: { $gte: 18 } })
+  .orderBy('name')
+  .limit(10)
+  .get();
+```
+
+---
+
+## v2.0.0 核心特性
+
+### 🔴 B-Tree 索引引擎
+
+自动为 `primaryKey` 和 `unique` 字段创建 B-Tree 索引，查询复杂度从 O(n) 降至 O(log n)。
+
+```javascript
+// 自动 B-Tree（无需手动创建）
+db.createTable('users', {
+  id: { type: 'integer', primaryKey: true, autoIncrement: true },
+  email: { type: 'string', unique: true }
+});
+// → 自动为 id 和 email 字段建 B-Tree
+
+// 手动创建 B-Tree 索引
+db.users.createBTreeIndex('name');
+
+// 范围查询（B-Tree 加速）
+db.users.where({ age: { $gte: 18, $lte: 60 } }).get();
+```
+
+### 🔴 事务隔离
+
+支持 `READ_COMMITTED` 和 `REPEATABLE_READ` 两级隔离。
+
+```javascript
+// REPEATABLE_READ：快照隔离
+db.begin('REPEATABLE_READ');
+db.users.insert({ name: 'Tx', email: 'tx@test.com' });
+// ... 其他操作看到的是事务开始时的快照
+db.rollback(); // 回滚所有变更
+
+// READ_COMMITTED（默认）
+db.begin();
+db.users.insert({ name: 'Tx2', email: 'tx2@test.com' });
+db.commit();
+
+// 动态切换隔离级别
+db.setIsolationLevel('REPEATABLE_READ');
+```
+
+### 🔴 文件锁 + WAL
+
+```javascript
+const db = new jsql.Database('mydb.json', {
+  wal: true,       // Write-Ahead Logging，崩溃恢复
+  fileLock: true   // 防止多进程同时写入
+});
+```
+
+### 🟡 哈希 JOIN 优化
+
+数据量 > 100 行时自动使用哈希 JOIN（O(n+m)），小数据量自动退化为嵌套循环。
+
+```javascript
+// JOIN 支持字符串表名（v2.0 新增）
+db.posts.where({})
+  .join('users', 'userId', 'id', 'author')
+  .get();
+
+// LEFT JOIN
+db.posts.where({})
+  .leftJoin('users', 'userId', 'id', 'author')
+  .get();
+
+// 手动指定 JOIN 策略
+db.posts.where({})
+  .useHashJoin()    // 强制哈希 JOIN
+  .join('users', 'userId', 'id', 'author')
+  .get();
+```
+
+### 🟡 外键约束
+
+```javascript
+db.createTable('posts', {
+  id: { type: 'integer', primaryKey: true, autoIncrement: true },
+  title: { type: 'string' },
+  userId: { type: 'integer', foreignKey: {
+    table: 'users',
+    field: 'id',
+    onDelete: 'cascade'   // cascade | set null | restrict
+  } }
+});
+
+// 删除用户时自动级联删除其帖子
+db.users.remove({ id: 1 });
+```
+
+### 🟡 MySQL 风格错误码
+
+```javascript
+try {
+  db.users.insert({ email: 'alice@example.com' }); // 重复
+} catch (e) {
+  e.code;    // 1062 (ER_DUP_ENTRY)
+  e.message; // "Duplicate entry 'alice@example.com' for key 'email'"
+  e.toJSON(); // { error: true, code: 1062, message: '...', details: {...} }
+}
+```
+
+错误码速查：
+
+| 错误码 | 名称 | 含义 |
+|--------|------|------|
+| 1048 | ER_BAD_NULL_ERROR | 列不能为 NULL |
+| 1062 | ER_DUP_ENTRY | 唯一键冲突 |
+| 1216 | ER_NO_REFERENCED_ROW | 外键约束失败 |
+| 1292 | ER_TRUNCATED_WRONG_VALUE | 数据类型错误 |
+| 1406 | ER_DATA_TOO_LONG | 数据超长 |
+| 3819 | ER_CHECK_CONSTRAINT | CHECK 约束违反 |
+| 1568 | ER_TRANSACTION_ACTIVE | 事务已在进行中 |
+| 1569 | ER_NO_TRANSACTION | 无活跃事务 |
+
+### 🟡 日期类型
+
+```javascript
+db.createTable('events', {
+  id: { type: 'integer', primaryKey: true, autoIncrement: true },
+  eventDate: { type: 'date' },         // YYYY-MM-DD
+  eventTime: { type: 'datetime' },     // YYYY-MM-DD HH:MM:SS
+  timestamp: { type: 'timestamp' },    // Unix 时间戳
+  duration: { type: 'time' }           // HH:MM:SS
+});
+```
+
+### 🟢 慢查询日志
+
+```javascript
+const db = new jsql.Database('mydb.json', { slowQueryThreshold: 50 });
+// 所有 > 50ms 的查询自动记录
+
+// 查看慢查询
+db.getSlowQueries(20);  // 最近 20 条
+
+// 清空日志
+db.clearSlowQueries();
+
+// 动态调整阈值
+db.setSlowQueryThreshold(200);
+```
+
+---
+
+## 完整 API
+
+### Database
+
+```javascript
+const db = new jsql.Database(filePath, options);
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `autoSave` | boolean | true | 自动保存 |
+| `autoSaveInterval` | number | 0 | 自动保存间隔（ms） |
+| `pretty` | boolean | true | JSON 格式化 |
+| `encryptKey` | string | null | AES-256-CBC 加密密钥 |
+| `versioning` | boolean | false | 版本历史 |
+| `wal` | boolean | false | WAL 模式 |
+| `fileLock` | boolean | false | 文件锁 |
+| `isolationLevel` | string | 'READ_COMMITTED' | 事务隔离级别 |
+| `slowQueryThreshold` | number | 100 | 慢查询阈值（ms），0 禁用 |
+
+#### 表管理
+
+```javascript
+db.createTable(name, schema)     // 创建表
+db.dropTable(name)               // 删除表
+db.hasTable(name)                // 是否存在
+db.getTables()                   // 获取所有表名
+```
+
+#### 事务
+
+```javascript
+db.begin(isolationLevel?)        // 开始事务
+db.commit()                      // 提交
+db.rollback()                    // 回滚
+db.inTransaction()               // 是否在事务中
+db.getIsolationLevel()           // 获取隔离级别
+db.setIsolationLevel(level)      // 设置隔离级别
+```
+
+#### 视图
+
+```javascript
+db.createView('adults', db => db.users.where({ age: { $gte: 18 } }));
+db.dropView('adults');
+db.getViews();
+```
+
+#### 触发器
+
+```javascript
+db.createTrigger('log_insert', {
+  event: 'insert',
+  table: 'users',
+  timing: 'after'
+}, (data) => { console.log('New user:', data); });
+
+db.dropTrigger('log_insert');
+db.getTriggers();
+```
+
+#### 备份 / 恢复
+
+```javascript
+db.backup('backup.json')         // 备份到文件
+db.restore('backup.json')        // 从文件恢复
+db.export()                      // 导出为 JSON 对象
+db.import(data)                  // 导入 JSON 对象
+```
+
+#### 统计 & 监控
+
+```javascript
+db.stats()                       // 数据库统计
+db.getSlowQueries()              // 慢查询日志
+db.clearSlowQueries()            // 清空慢查询日志
+db.setSlowQueryThreshold(ms)     // 设置慢查询阈值
+```
+
+#### 插件 & 迁移
+
+```javascript
+db.use(plugin)                   // 注册插件
+db.addMigration({ version, name, up, down })  // 注册迁移
+db.migrate(version)              // 执行迁移
+```
+
+#### 变更监听
+
+```javascript
+const unsubscribe = db.onChange(event => {
+  console.log(event.type, event.table, event.data);
+});
+
+// 变更流（异步迭代器）
+const stream = db.createChangeStream();
+for await (const event of stream) { /* ... */ }
+stream.close();
+```
+
+#### 多数据库
+
+```javascript
+db.attach('other', otherDb)      // 附加数据库
+db.detach('other')               // 分离
+db.getAttached()                 // 查看已附加的数据库
+```
+
+### Table
+
+```javascript
+// 插入
+table.insert(data)               // 插入单行
+table.insertMany([data, ...])    // 批量插入
+table.upsert(data)               // 存在则更新，否则插入
+
+// 查询
+table.find(query)                // 条件查询
+table.findOne(query)             // 查单条
+table.findById(id)               // 主键查询（B-Tree 加速）
+table.findAll()                  // 全表查询
+table.count(query)               // 计数
+table.where(conditions)          // 返回 Query 链式构建器
+
+// 更新
+table.update(query, updates)     // 条件更新
+table.updateById(id, updates)    // 主键更新
+
+// 删除
+table.remove(query)              // 条件删除
+
+// 索引
+table.createBTreeIndex(field)    // 创建 B-Tree 索引
+table.createIndex(field)         // 创建 Hash 索引
+table.dropIndex(field)           // 删除索引
+
+// Schema
+table.addColumn(name, def)       // 添加列
+table.dropColumn(name)           // 删除列
+table.renameColumn(old, new)     // 重命名列
+
+// 钩子
+table.on('beforeInsert', fn)     // 注册钩子
+table.off('beforeInsert', fn)    // 移除钩子
+```
+
+### Query
+
+```javascript
+db.users.where({ age: { $gte: 18 } })  // 条件
+  .select(['name', 'age'])              // 字段选择
+  .orderBy('name')                      // 排序
+  .orderByDesc('age')                   // 降序
+  .limit(10)                            // 限制行数
+  .offset(20)                           // 偏移
+  .distinct('age')                      // 去重
+  .groupBy('city')                      // 分组
+  .having({ count: { $gt: 5 } })        // 分组过滤
+  .join('posts', 'id', 'userId')        // INNER JOIN
+  .leftJoin('posts', 'id', 'userId')    // LEFT JOIN
+  .rightJoin('posts', 'id', 'userId')   // RIGHT JOIN
+  .union(otherQuery)                    // UNION
+  .window('rowNumber', 'name')          // 窗口函数
+  .case([{ when: { age: { $lt: 18 } }, then: 'minor' }], 'adult')
+    .as('ageGroup')                     // CASE WHEN
+  .cache(30000)                          // 查询缓存
+  .explain()                            // 执行计划
+  .toSQL()                              // 导出 SQL 字符串
+  .useHashJoin()                        // 强制哈希 JOIN
+  .useNestedLoop()                      // 强制嵌套循环
+
+  // 执行
+  .get()                                // 获取结果
+  .first()                              // 第一条
+  .count()                              // 计数
+  .sum('age')                           // 求和
+  .avg('age')                           // 平均
+  .min('age')                           // 最小
+  .max('age')                           // 最大
+  .groupStats('age')                    // 分组统计
+  .paginate(1, 20)                      // 分页
+  .update({ name: 'New' })              // 条件更新
+  .remove()                             // 条件删除
+  .invalidateCache()                    // 清除缓存
+```
+
+### Schema 定义
+
+```javascript
+{
+  fieldName: {
+    type: 'integer' | 'string' | 'number' | 'boolean' | 'array' | 'object' |
+          'date' | 'datetime' | 'timestamp' | 'time' | 'any',
+    primaryKey: true,
+    autoIncrement: true,
+    required: true,
+    unique: true,
+    default: '默认值',
+    length: 50,              // 字符串最大长度
+    min: 0,                  // 数值最小值
+    max: 150,                // 数值最大值
+    check: v => v >= 18,     // 自定义校验函数
+    foreignKey: {
+      table: 'users',
+      field: 'id',
+      onDelete: 'cascade',   // cascade | set null | restrict
+      onUpdate: 'restrict'
+    },
+    computed: row => `prefix_${row.id}`  // 计算字段
+  }
+}
+```
+
+### 操作符
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$eq` | 等于 | `{ age: { $eq: 25 } }` |
+| `$ne` | 不等于 | `{ age: { $ne: 25 } }` |
+| `$gt` | 大于 | `{ age: { $gt: 18 } }` |
+| `$gte` | 大于等于 | `{ age: { $gte: 18 } }` |
+| `$lt` | 小于 | `{ age: { $lt: 60 } }` |
+| `$lte` | 小于等于 | `{ age: { $lte: 60 } }` |
+| `$in` | 在列表中 | `{ status: { $in: ['a', 'b'] } }` |
+| `$nin` | 不在列表中 | `{ status: { $nin: ['x', 'y'] } }` |
+| `$like` | 模糊匹配 | `{ name: { $like: 'Ali' } }` |
+| `$regex` | 正则匹配 | `{ email: { $regex: /@gmail\.com$/ } }` |
+| `$between` | 区间 | `{ age: { $between: [18, 60] } }` |
+| `$null` | 是否为 null | `{ deletedAt: { $null: true } }` |
+| `$notNull` | 是否非 null | `{ name: { $notNull: true } }` |
+| `$or` | 或 | `{ $or: [{age: 18}, {age: 21}] }` |
+| `$and` | 且 | `{ $and: [{age: {$gte: 18}}, {age: {$lte: 60}}] }` |
+| `$inSub` | 子查询 IN | `{ $inSub: { query: q, field: 'id' } }` |
+| `$notInSub` | 子查询 NOT IN | `{ $notInSub: { query: q, field: 'id' } }` |
+| `$expr` | 表达式 | `{ $expr: row => row.a > row.b }` |
+
+### EXPLAIN 输出示例
+
+```javascript
+db.users.where({ id: 3 }).explain().get();
+// {
+//   table: 'users',
+//   totalRows: 5000,
+//   filteredRows: 1,
+//   selectivity: '0.02%',
+//   hasBTree: true,
+//   indexUsed: 'id',
+//   btreeIndexes: ['id', 'email'],
+//   estimatedCost: 0.05,
+//   joins: []
+// }
+```
+
+---
+
+## 内存模式 vs 文件模式
+
+| 特性 | 内存模式 | 文件模式 |
+|------|----------|----------|
+| 初始化 | `new Database(':memory:')` | `new Database('db.json')` |
+| 持久化 | 无 | 自动保存 |
+| B-Tree 索引 | ✅ | ✅ |
+| 事务隔离 | ✅ | ✅ |
+| WAL | ❌（自动禁用） | ✅ |
+| 文件锁 | ❌（自动禁用） | ✅ |
+| 加密存储 | ❌ | ✅ |
+| 慢查询日志 | ✅ | ✅ |
+
+---
+
+## 与 MySQL 对比
+
+| 特性 | JSQL-NEO v2.0 | MySQL 8.0 |
+|------|---------------|-----------|
+| 索引 | B-Tree（O(log n)） | B-Tree（O(log n)） |
+| 事务隔离 | READ_COMMITTED / REPEATABLE_READ | 4 级 |
+| 并发控制 | 文件锁 | MVCC + 锁 |
+| 外键 | CASCADE / SET NULL / RESTRICT | ✅ |
+| 错误码 | 25+ MySQL 兼容 | 完整 |
+| JOIN | 哈希 / 嵌套循环 | 基于代价 |
+| 子查询 | ✅ | ✅ |
+| 窗口函数 | ROW_NUMBER / RANK / DENSE_RANK | 完整 |
+| 存储引擎 | JSON 文件 | InnoDB / MyISAM |
+| 零依赖 | ✅ | ❌ |
+| 嵌入 Node.js | ✅ | ❌（需驱动） |
+
+---
+
+## 许可
+
+Apache License 2.0 — © Vexify 2026

package/index.js

@@ -1,7 +1,7 @@
 // © Vexify 2026 All Rights Reserved.
 /**
  * JSQL-NEO — Pure JavaScript Embedded Database
- * v2.0.0 — B-Tree 索引、WAL、哈希 JOIN、错误码体系、事务隔离
+ * v2.1.0 — B-Tree 索引、WAL、哈希 JOIN、Redis 兼容 Cache、事务隔离
  *
  * @example
  * const jsql = require('jsql-neo');
@@ -13,6 +13,7 @@ module.exports = {
     Table: require('./lib/table'),
     Query: require('./lib/query'),
     BTree: require('./lib/btree'),
+    Cache: require('./lib/cache'),
     JSQL_Error: require('./lib/errors').JSQL_Error,
     ErrorCodes: require('./lib/errors').ErrorCodes
 };

package/lib/btree.js

@@ -241,8 +241,9 @@ class BTree {
             return true;
         }
 
+        const origKey = node.keys[index];
         this._mergeChildren(node, index);
-        return this._removeFromNode(node.children[index], node.keys[index], rowIndex);
+        return this._removeFromNode(node.children[index], origKey, rowIndex);
     }
 
     _getMax(node) {

package/lib/cache.js

@@ -0,0 +1,328 @@
+const fs = require('fs');
+const path = require('path');
+
+class Cache {
+  constructor(options = {}) {
+    this._data = new Map();
+    this._expires = new Map();
+    this._ttlTimer = null;
+    this._db = 0;
+    this._dbs = [this._data];
+    this._dbsExpires = [this._expires];
+    this._persistPath = options.path || null;
+    this._saveInterval = options.saveInterval || 0;
+    this._dirty = false;
+    if (this._persistPath) this._load();
+    if (this._saveInterval > 0) this._startAutoSave();
+    this._startTTLCleaner();
+  }
+
+  set(key, value) { this._getData().set(String(key), String(value)); this._dirty = true; return 'OK'; }
+  get(key) {
+    const k = String(key);
+    if (this._isExpired(k)) return null;
+    const val = this._getData().get(k);
+    return val !== undefined ? val : null;
+  }
+  del(...keys) {
+    let count = 0;
+    for (const key of keys) { const k = String(key); if (this._getData().delete(k)) count++; this._getExpires().delete(k); }
+    if (count > 0) this._dirty = true;
+    return count;
+  }
+  exists(...keys) {
+    let count = 0;
+    for (const key of keys) { const k = String(key); if (!this._isExpired(k) && this._getData().has(k)) count++; }
+    return count;
+  }
+  keys(pattern = '*') {
+    const regex = new RegExp('^' + pattern.replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
+    const result = [];
+    for (const key of this._getData().keys()) { if (!this._isExpired(key) && regex.test(key)) result.push(key); }
+    return result;
+  }
+  type(key) {
+    const k = String(key);
+    if (this._isExpired(k)) return 'none';
+    const val = this._getData().get(k);
+    if (val === undefined) return 'none';
+    if (typeof val === 'string') return 'string';
+    if (Array.isArray(val)) return val._type === 'hash' ? 'hash' : 'list';
+    if (val instanceof Set) return 'set';
+    return 'string';
+  }
+  expire(key, seconds) {
+    const k = String(key);
+    if (!this._getData().has(k)) return 0;
+    this._getExpires().set(k, Date.now() + seconds * 1000);
+    return 1;
+  }
+  ttl(key) {
+    const k = String(key);
+    if (!this._getData().has(k)) return -2;
+    const expiry = this._getExpires().get(k);
+    if (expiry === undefined) return -1;
+    const remaining = Math.ceil((expiry - Date.now()) / 1000);
+    return remaining > 0 ? remaining : -2;
+  }
+  persist(key) { return this._getExpires().delete(String(key)) ? 1 : 0; }
+  incr(key) { return this._incrby(key, 1); }
+  decr(key) { return this._incrby(key, -1); }
+  incrby(key, increment) { return this._incrby(key, increment); }
+  decrby(key, decrement) { return this._incrby(key, -decrement); }
+  _incrby(key, delta) {
+    const k = String(key);
+    const cur = this._getData().get(k);
+    const val = (cur !== undefined ? Number(cur) : 0) + delta;
+    if (!Number.isFinite(val)) throw new Error('value is not an integer or out of range');
+    this._getData().set(k, String(val));
+    this._dirty = true;
+    return val;
+  }
+
+  hset(key, field, value) {
+    const k = String(key);
+    let hash = this._getData().get(k);
+    if (!hash || hash._type !== 'hash') { hash = { _type: 'hash' }; this._getData().set(k, hash); }
+    const existed = hash[field] !== undefined;
+    hash[field] = String(value);
+    this._dirty = true;
+    return existed ? 0 : 1;
+  }
+  hget(key, field) {
+    const k = String(key);
+    if (this._isExpired(k)) return null;
+    const hash = this._getData().get(k);
+    if (!hash || typeof hash !== 'object' || hash._type !== 'hash') return null;
+    return hash[field] !== undefined ? hash[field] : null;
+  }
+  hgetall(key) {
+    const k = String(key);
+    if (this._isExpired(k)) return null;
+    const hash = this._getData().get(k);
+    if (!hash || typeof hash !== 'object' || hash._type !== 'hash') return null;
+    const result = {};
+    for (const [f, v] of Object.entries(hash)) { if (f !== '_type') result[f] = v; }
+    return result;
+  }
+  hdel(key, ...fields) {
+    const k = String(key);
+    const hash = this._getData().get(k);
+    if (!hash || typeof hash !== 'object' || hash._type !== 'hash') return 0;
+    let count = 0;
+    for (const field of fields) { if (delete hash[field]) count++; }
+    if (count > 0) this._dirty = true;
+    return count;
+  }
+  hkeys(key) {
+    const k = String(key);
+    if (this._isExpired(k)) return [];
+    const hash = this._getData().get(k);
+    if (!hash || typeof hash !== 'object' || hash._type !== 'hash') return [];
+    return Object.keys(hash).filter(f => f !== '_type');
+  }
+  hlen(key) {
+    const k = String(key);
+    if (this._isExpired(k)) return 0;
+    const hash = this._getData().get(k);
+    if (!hash || typeof hash !== 'object' || hash._type !== 'hash') return 0;
+    return Object.keys(hash).filter(f => f !== '_type').length;
+  }
+
+  lpush(key, ...values) {
+    const k = String(key);
+    let list = this._getData().get(k);
+    if (!list || !Array.isArray(list) || list._type === 'hash') { list = []; this._getData().set(k, list); }
+    list.unshift(...values.map(String).reverse());
+    this._dirty = true;
+    return list.length;
+  }
+  rpush(key, ...values) {
+    const k = String(key);
+    let list = this._getData().get(k);
+    if (!list || !Array.isArray(list) || list._type === 'hash') { list = []; this._getData().set(k, list); }
+    list.push(...values.map(String));
+    this._dirty = true;
+    return list.length;
+  }
+  lpop(key) {
+    const k = String(key);
+    const list = this._getData().get(k);
+    if (!list || !Array.isArray(list) || list._type === 'hash') return null;
+    if (list.length === 0) return null;
+    this._dirty = true;
+    return list.shift();
+  }
+  rpop(key) {
+    const k = String(key);
+    const list = this._getData().get(k);
+    if (!list || !Array.isArray(list) || list._type === 'hash') return null;
+    if (list.length === 0) return null;
+    this._dirty = true;
+    return list.pop();
+  }
+  llen(key) {
+    const k = String(key);
+    if (this._isExpired(k)) return 0;
+    const list = this._getData().get(k);
+    if (!list || !Array.isArray(list) || list._type === 'hash') return 0;
+    return list.length;
+  }
+  lrange(key, start, stop) {
+    const k = String(key);
+    if (this._isExpired(k)) return [];
+    const list = this._getData().get(k);
+    if (!list || !Array.isArray(list) || list._type === 'hash') return [];
+    if (start < 0) start = Math.max(list.length + start, 0);
+    if (stop < 0) stop = list.length + stop;
+    return list.slice(start, stop + 1);
+  }
+
+  sadd(key, ...members) {
+    const k = String(key);
+    let set = this._getData().get(k);
+    if (!set || !(set instanceof Set)) { set = new Set(); this._getData().set(k, set); }
+    let count = 0;
+    for (const m of members) { if (!set.has(String(m))) { set.add(String(m)); count++; } }
+    if (count > 0) this._dirty = true;
+    return count;
+  }
+  srem(key, ...members) {
+    const k = String(key);
+    const set = this._getData().get(k);
+    if (!set || !(set instanceof Set)) return 0;
+    let count = 0;
+    for (const m of members) { if (set.delete(String(m))) count++; }
+    if (count > 0) this._dirty = true;
+    return count;
+  }
+  smembers(key) {
+    const k = String(key);
+    if (this._isExpired(k)) return [];
+    const set = this._getData().get(k);
+    if (!set || !(set instanceof Set)) return [];
+    return [...set];
+  }
+  sismember(key, member) {
+    const k = String(key);
+    if (this._isExpired(k)) return 0;
+    const set = this._getData().get(k);
+    if (!set || !(set instanceof Set)) return 0;
+    return set.has(String(member)) ? 1 : 0;
+  }
+  scard(key) {
+    const k = String(key);
+    if (this._isExpired(k)) return 0;
+    const set = this._getData().get(k);
+    if (!set || !(set instanceof Set)) return 0;
+    return set.size;
+  }
+
+  flushall() {
+    for (let i = 0; i < this._dbs.length; i++) { if (this._dbs[i]) this._dbs[i].clear(); if (this._dbsExpires[i]) this._dbsExpires[i].clear(); }
+    this._data = this._dbs[0] = new Map();
+    this._expires = this._dbsExpires[0] = new Map();
+    this._db = 0;
+    this._dirty = true;
+    return 'OK';
+  }
+  flushdb() { this._getData().clear(); this._getExpires().clear(); this._dirty = true; return 'OK'; }
+  dbsize() {
+    let count = 0;
+    for (const key of this._getData().keys()) { if (!this._isExpired(key)) count++; }
+    return count;
+  }
+  select(index) {
+    const idx = Number(index);
+    if (idx < 0 || idx > 15) throw new Error('DB index out of range');
+    this._db = idx;
+    if (!this._dbs[idx]) { this._dbs[idx] = new Map(); this._dbsExpires[idx] = new Map(); }
+    this._data = this._dbs[idx];
+    this._expires = this._dbsExpires[idx];
+    return 'OK';
+  }
+
+  save() {
+    if (!this._persistPath) return;
+    const dump = { version: 1, databases: [] };
+    for (let i = 0; i < this._dbs.length; i++) {
+      const db = this._dbs[i];
+      if (!db || db.size === 0) continue;
+      const data = {};
+      for (const [key, val] of db) {
+        const exp = this._dbsExpires[i];
+        if (exp && exp.has(key) && exp.get(key) <= Date.now()) continue;
+        if (val instanceof Set) data[key] = { _t: 'set', _v: [...val] };
+        else if (Array.isArray(val)) data[key] = { _t: 'list', _v: val };
+        else if (typeof val === 'object' && val._type === 'hash') {
+          const clean = {}; for (const [f, v] of Object.entries(val)) { if (f !== '_type') clean[f] = v; }
+          data[key] = { _t: 'hash', _v: clean };
+        } else data[key] = { _t: 'string', _v: val };
+      }
+      const expires = {};
+      const expMap = this._dbsExpires[i];
+      if (expMap) { for (const [key, ttl] of expMap) { if (ttl > Date.now()) expires[key] = ttl; } }
+      if (Object.keys(data).length > 0 || Object.keys(expires).length > 0) dump.databases.push({ index: i, data, expires });
+    }
+    const dir = path.dirname(this._persistPath);
+    if (dir) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(this._persistPath + '.tmp', JSON.stringify(dump), 'utf8');
+    fs.renameSync(this._persistPath + '.tmp', this._persistPath);
+    this._dirty = false;
+    return 'OK';
+  }
+
+  _load() {
+    try {
+      if (!fs.existsSync(this._persistPath)) return;
+      const dump = JSON.parse(fs.readFileSync(this._persistPath, 'utf8'));
+      if (dump.version !== 1) return;
+      for (const db of dump.databases || []) {
+        const idx = db.index;
+        if (!this._dbs[idx]) { this._dbs[idx] = new Map(); this._dbsExpires[idx] = new Map(); }
+        const data = this._dbs[idx], expires = this._dbsExpires[idx];
+        for (const [key, entry] of Object.entries(db.data || {})) {
+          if (entry._t === 'set') data.set(key, new Set(entry._v));
+          else if (entry._t === 'list') data.set(key, entry._v);
+          else if (entry._t === 'hash') data.set(key, { _type: 'hash', ...entry._v });
+          else data.set(key, entry._v);
+        }
+        for (const [key, ttl] of Object.entries(db.expires || {})) { if (ttl > Date.now()) expires.set(key, ttl); }
+      }
+      this._data = this._dbs[this._db] || new Map();
+      this._expires = this._dbsExpires[this._db] || new Map();
+    } catch (_) { /* ignore */ }
+  }
+
+  _startAutoSave() { this._saveTimer = setInterval(() => { if (this._dirty) this.save(); }, this._saveInterval); }
+  _startTTLCleaner() {
+    this._ttlTimer = setInterval(() => {
+      for (let i = 0; i < this._dbs.length; i++) {
+        const exp = this._dbsExpires[i]; if (!exp) continue;
+        const now = Date.now();
+        for (const [key, ttl] of exp) { if (ttl <= now) { if (this._dbs[i]) this._dbs[i].delete(key); exp.delete(key); } }
+      }
+    }, 1000);
+  }
+
+  close() { if (this._persistPath && this._dirty) this.save(); if (this._saveTimer) clearInterval(this._saveTimer); if (this._ttlTimer) clearInterval(this._ttlTimer); }
+  _isExpired(key) {
+    const expiry = this._getExpires().get(key);
+    if (expiry !== undefined && expiry <= Date.now()) { this._getData().delete(key); this._getExpires().delete(key); return true; }
+    return false;
+  }
+  _getData() { return this._data; }
+  _getExpires() { return this._expires; }
+
+  static redisPlugin(db, options = {}) {
+    const cache = new Cache(options);
+    db._cache = cache;
+    const redisMethods = ['set','get','del','exists','keys','type','expire','ttl','persist','incr','decr','incrby','decrby','hset','hget','hgetall','hdel','hkeys','hlen','lpush','rpush','lpop','rpop','llen','lrange','sadd','srem','smembers','sismember','scard','flushall','flushdb','dbsize','select'];
+    for (const m of redisMethods) {
+      db[m] = cache[m].bind(cache);
+    }
+    return cache;
+  }
+}
+
+module.exports = Cache;

package/lib/database.js

@@ -21,7 +21,7 @@ class Database {
      * @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 {number} options.slowQueryThreshold - 慢查询阈值 ms（默认 100，0 记录全部，<0 禁用）
      * @param {boolean} options.fileLock - 是否启用文件锁（默认 false）
      */
     constructor(filePath, options = {}) {
@@ -514,8 +514,8 @@ class Database {
      * 记录慢查询
      */
     _logSlowQuery(sql, durationMs, rowsReturned) {
-        if (this._slowQueryThreshold <= 0) return;
-        if (durationMs < this._slowQueryThreshold) return;
+        if (this._slowQueryThreshold < 0) return;
+        if (this._slowQueryThreshold > 0 && durationMs < this._slowQueryThreshold) return;
 
         this._slowQueries.push({
             sql,

package/lib/query.js

@@ -223,6 +223,7 @@ class Query {
     // ============================================================
 
     get() {
+        const startTime = Date.now();
         if (this._explain) return this._getExplain();
 
         // 缓存命中
@@ -319,6 +320,7 @@ class Query {
             this._cache.timestamp = Date.now();
         }
 
+        this._table._db._logSlowQuery(`get ${this._table._name}`, Date.now() - startTime, rows.length);
         return rows;
     }
 

package/lib/table.js

@@ -117,7 +117,37 @@ class Table {
     }
 
     insertMany(items) {
-        return items.map(item => this.insert(item));
+        if (items.length === 0) return [];
+        for (const hook of this._hooks.beforeInsert) {
+            items = items.map(data => hook({ ...data }) || data);
+        }
+        const uniqueTracker = {};
+        for (const [field, def] of Object.entries(this._schema)) {
+            if (def.unique) uniqueTracker[field] = new Set();
+        }
+        const results = [];
+        for (const item of items) {
+            let data = this._applyDefaults(item);
+            data = this._applyComputed(data);
+            data = this._validateDataTypes(data);
+            this._validateConstraints(data, -1, uniqueTracker);
+            if (this._autoIncrementField && data[this._autoIncrementField] === undefined) {
+                this._autoIncrement++;
+                data[this._autoIncrementField] = this._autoIncrement;
+            } else if (this._autoIncrementField && data[this._autoIncrementField] > this._autoIncrement) {
+                this._autoIncrement = data[this._autoIncrementField];
+            }
+            this._rows.push({ ...data });
+            results.push(data);
+        }
+        this._rebuildAllBTrees();
+        this._dirty = true;
+        this._db._markDirty();
+        for (const hook of this._hooks.afterInsert) {
+            for (const data of results) hook(data);
+        }
+        for (const data of results) this._db._emitChange('insert', this._name, data);
+        return results;
     }
 
     upsert(data) {
@@ -676,7 +706,7 @@ class Table {
     // 内部: 约束校验
     // ============================================================
 
-    _validateConstraints(data, excludeIndex) {
+    _validateConstraints(data, excludeIndex, uniqueTracker) {
         for (const [field, def] of Object.entries(this._schema)) {
             if (field === '_softDelete') continue;
 
@@ -687,11 +717,18 @@ class Table {
 
             // UNIQUE
             if (def.unique && data[field] !== undefined) {
-                for (let i = 0; i < this._rows.length; i++) {
-                    if (i === excludeIndex) continue;
-                    if (this._rows[i][field] === data[field]) {
+                if (uniqueTracker && uniqueTracker[field]) {
+                    if (uniqueTracker[field].has(data[field])) {
                         throw createError('ER_DUP_ENTRY', String(data[field]), field);
                     }
+                    uniqueTracker[field].add(data[field]);
+                } else {
+                    for (let i = 0; i < this._rows.length; i++) {
+                        if (i === excludeIndex) continue;
+                        if (this._rows[i][field] === data[field]) {
+                            throw createError('ER_DUP_ENTRY', String(data[field]), field);
+                        }
+                    }
                 }
             }
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "jsql-neo",
-    "version": "2.0.0",
-    "description": "JSQL-NEO — Pure JavaScript embedded database with B-Tree indexes, WAL, hash JOIN, and MySQL-style error codes",
+    "version": "2.1.0",
+    "description": "JSQL-NEO — Pure JavaScript embedded database with B-Tree indexes, WAL, hash JOIN, Redis-compatible Cache, and MySQL-style error codes",
     "main": "index.js",
     "files": [
         "index.js",