mm_sqlite 1.2.2 → 1.2.4

package/README.md

@@ -1,12 +1,8 @@
 # mm_sqlite
+[中文](./README.md) | [English](./README_EN.md)
 
 高性能SQLite数据库操作模块，提供与mm_mysql完全兼容的API接口。适用于Node.js应用的轻量级数据存储解决方案。
 
-[![npm version](https://img.shields.io/npm/v/mm_sqlite.svg?style=flat-square)](https://www.npmjs.com/package/mm_sqlite)
-[![npm downloads](https://img.shields.io/npm/dm/mm_sqlite.svg?style=flat-square)](https://www.npmjs.com/package/mm_sqlite)
-[![node version](https://img.shields.io/node/v/mm_sqlite.svg?style=flat-square)](https://nodejs.org/en/)
-[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
-
 ## 安装
 
 ```bash
@@ -16,12 +12,13 @@ npm install mm_sqlite --save
 ## 特性
 
 - 🚀 **高性能优化**：经过深度优化的SQL构建器和连接管理
-- 🔄 **完全兼容**：与mm_mysql模块API完全兼容
+- 🔄 **完全兼容**：与mm_mysql模块API完全兼容，可无缝切换
 - 📊 **内存优化**：优化的内存使用，减少GC压力
 - 🔧 **链式调用**：流畅的SQL构建器链式调用
 - 🛡️ **错误处理**：完善的错误处理机制
 - 📈 **连接池支持**：支持连接池模式，提高并发性能
 - 🔒 **事务支持**：完整的事务处理机制
+- 🔍 **类型安全**：完善的JSDoc类型注释
 
 ## 依赖要求
 
@@ -32,7 +29,7 @@ npm install mm_sqlite --save
 
 ### 基本使用
 
-### 初始化和连接
+#### 初始化和连接
 
 ```javascript
 const { Sqlite } = require('mm_sqlite');
@@ -62,369 +59,136 @@ const sqlite = new Sqlite({
 
 // 打开数据库连接
 await sqlite.open();
-
-// 注意：SQLite会自动创建不存在的数据库文件和目录
 ```
 
-### 表操作
+#### 基础操作
 
 ```javascript
-// 创建表
-await sqlite.exec(`
-    CREATE TABLE IF NOT EXISTS users (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        username TEXT NOT NULL,
-        email TEXT UNIQUE,
-        age INTEGER,
-        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-    );
-`);
-
-// 删除表
-await sqlite.exec('DROP TABLE IF EXISTS users');
-```
+// 获取数据库管理器
+const db = sqlite.db();
 
-### 数据操作
+// 设置表名
+const userDb = db.new('users', 'id');
 
-```javascript
-// 插入单条数据
-const insertResult = await sqlite.table('users').add({
+// 插入数据
+const result = await userDb.add({
     username: '张三',
     email: 'zhangsan@example.com',
-    age: 28
+    age: 28,
+    created_at: new Date()
 });
-console.log('插入结果:', insertResult);
-
-// 查询多条数据
-const users = await sqlite.table('users').get();
-console.log('所有用户:', users);
 
-// 根据条件查询
-const user = await sqlite.table('users').getObj({ username: '张三' });
-console.log('查询用户:', user);
-
-// 使用SQL构建器
-const activeUsers = await sqlite
-    .table('users')
-    .select(['id', 'username', 'email'])
-    .where({ age: { '>=': 18 } })
-    .orderBy('created_at', 'DESC')
-    .limit(10)
-    .get();
+// 查询数据
+const users = await userDb.get();
 
 // 更新数据
-const updateResult = await sqlite.table('users').set(
-    { id: 1 },               // 更新条件
-    { age: 29, email: 'newname@example.com' }  // 更新数据
-);
-console.log('更新结果:', updateResult);
+await userDb.set({ id: 1 }, { age: 29 });
 
 // 删除数据
-const deleteResult = await sqlite.table('users').del({ id: 1 });
-console.log('删除结果:', deleteResult);
+await userDb.del({ id: 1 });
 ```
 
-### 批量操作
+#### 高级查询
 
 ```javascript
-// 批量插入数据
-const batchInsertResult = await sqlite.table('users').addList([
-    { username: '李四', email: 'lisi@example.com', age: 30 },
-    { username: '王五', email: 'wangwu@example.com', age: 25 },
-    { username: '赵六', email: 'zhaoliu@example.com', age: 32 }
-], true, 100, 60000);  // lock=true, batchSize=100, timeout=60000
-console.log('批量插入结果:', batchInsertResult);
-
-// 批量删除数据
-const batchDeleteResult = await sqlite.table('users').delList([
-    { id: 2 },
-    { id: 3 }
-], false, 100, 60000);  // like=false, batchSize=100, timeout=60000
-console.log('批量删除结果:', batchDeleteResult);
-```
-
-### 统计操作
-
-```javascript
-// 统计总记录数
-const totalCount = await sqlite.table('users').count();
-console.log('总记录数:', totalCount);
-
-// 条件统计
-const adultCount = await sqlite.table('users').count({ age: { '>=': 18 } });
-console.log('成年人数量:', adultCount);
-
-// 分组统计
-const ageGroupCount = await sqlite.table('users').groupCount(
-    {},              // 查询条件
-    'age',           // 分组字段
-    'age, COUNT(*) as count',  // 查询字段
-    'age DESC'       // 排序规则
-);
-console.log('年龄分组统计:', ageGroupCount);
-
-// 关闭连接
-await sqlite.close();
-```
-
-### 高级功能
-
-#### 事务处理
-
-```javascript
-// 开始事务
-const transaction = await sqlite.beginTransaction();
-
-try {
-    // 在事务中执行操作
-    await transaction.exec('INSERT INTO users (username, email) VALUES (?, ?)', ['张三', 'zhangsan@example.com']);
-    await transaction.exec('INSERT INTO profiles (user_id, bio) VALUES (?, ?)', [1, '这是一个测试用户']);
-
-    // 提交事务
-    await transaction.commit();
-} catch (error) {
-    // 回滚事务
-    await transaction.rollback();
-    console.error('事务执行失败:', error);
-}
-```
-
-#### 使用事务包装器
-
-```javascript
-// 使用事务包装器简化事务处理
-const result = await sqlite.transaction(async (transaction) => {
-    // 在事务中执行操作
-    await transaction.exec('INSERT INTO users (username, email) VALUES (?, ?)', ['李四', 'lisi@example.com']);
-    await transaction.exec('INSERT INTO profiles (user_id, bio) VALUES (?, ?)', [2, '这是另一个测试用户']);
-    
-    return { success: true };
+// 条件查询
+const adultUsers = await userDb.get({
+    age: { _gte: 18 }
 });
 
-console.log('事务执行结果:', result);
-```
+// 分页查询
+const pageUsers = await userDb.get({
+    _page: 1,
+    _size: 10,
+    _sort: 'created_at desc'
+});
 
-#### 复杂查询
-// 多表连接查询
-const results = await sqlite
-    .table('users')
-    .select(['users.name', 'profiles.bio', 'posts.title'])
-    .join('profiles', 'users.id = profiles.user_id')
-    .join('posts', 'users.id = posts.author_id')
-    .where({ 'users.status': 'active' })
-    .like('posts.title', '教程')
-    .groupBy('users.id')
-    .having('COUNT(posts.id) > 0')
-    .get();
-
-// IN查询
-const ids = [1, 2, 3, 4, 5];
-const users = await sqlite
-    .table('users')
-    .where('id', 'IN', ids)
-    .get();
-
-// OR条件查询
-const users = await sqlite
-    .table('users')
-    .where({ status: 'active' })
-    .orWhere({ role: 'admin' })
-    .get();
+// 聚合查询
+const stats = await userDb.aggr({
+    _count: 'id',
+    _avg: 'age',
+    _max: 'age',
+    _min: 'age'
+});
 ```
 
-## 性能优化特性
-
-### 内存优化
-
-- **DB实例缓存**：数据库实例缓存机制，避免重复创建
-- **SQL构建器优化**：优化的字符串拼接和参数处理
-- **连接管理**：智能连接池和重连机制
-
-### 性能测试结果
-
-经过优化后，模块性能显著提升：
-
-- **SQL构建器操作**：1,250,000+ 操作/秒
-- **内存使用**：平均每次迭代减少27.36字节
-- **连接管理**：连接实例创建内存使用减少2.1MB
-
 ## API参考
 
 ### Sqlite类
 
 #### 构造函数
-
 ```javascript
 new Sqlite(config)
 ```
 
-**配置参数：**
-- `config.dir` - 数据库文件存储目录，默认为`'./db/'`
-- `config.database` - 数据库文件名，默认为`'mm'`
-- `config.charset` - 字符集，默认为`'utf8mb4'`
-- `config.timezone` - 时区，默认为`'+08:00'`
-- `config.connect_timeout` - 连接超时时间，默认`20000ms`
-- `config.acquire_timeout` - 获取连接超时时间，默认`20000ms`
-- `config.query_timeout` - 查询超时时间，默认`20000ms`
-- `config.connection_limit` - 连接限制（>1启用连接池），默认`1`
-- `config.enable_keep_alive` - 启用保活，默认`true`
-- `config.keep_alive_initial_delay` - 保活初始延迟，默认`10000ms`
-- `config.enable_reconnect` - 启用重连，默认`true`
-- `config.reconnect_interval` - 重连间隔，默认`1000ms`
-- `config.max_reconnect_attempts` - 最大重连尝试次数，默认`5`
-- `config.wait_for_connections` - 等待连接，默认`true`
-- `config.pool_min` - 连接池最小连接数，默认`1`
-- `config.pool_max` - 连接池最大连接数，默认`5`
-- `config.pool_acquire_timeout` - 连接池获取超时，默认`30000ms`
-- `config.pool_idle_timeout` - 连接池空闲超时，默认`60000ms`
-- `config.pool_reap_interval` - 连接池清理间隔，默认`1000ms`
-
 #### 主要方法
 
-- `open(timeout)` - 打开数据库连接，返回`Promise<Boolean>`
-- `close()` - 关闭数据库连接，返回`Promise<Boolean>`
-- `getConn(timeout)` - 获取数据库连接，返回`Promise<Connection>`
-- `run(sql, params, timeout)` - 执行SQL查询语句，返回`Promise<Array>`
-- `exec(sql, params, timeout)` - 执行SQL语句（非查询操作），返回`Promise<Object>`
-- `read(table, condition, options)` - 读取整张表的数据，返回`Promise<Array>`
-- `db(database)` - 获取数据库操作实例，返回`DB`实例
-- `beginTransaction()` - 开始事务，返回`Promise<Object>`（事务对象）
-- `transaction(callback)` - 在事务中执行多个操作，返回`Promise<*>`
-
-#### 事务对象方法
-
-- `commit()` - 提交事务
-- `rollback()` - 回滚事务
-- `exec(sql, params)` - 在事务中执行SQL语句
+- `open()` - 打开数据库连接
+- `close()` - 关闭数据库连接
+- `db()` - 获取数据库管理器实例
+- `run(sql, params)` - 执行查询SQL
+- `exec(sql, params)` - 执行非查询SQL
 
 ### DB类
 
-DB类继承自Sql类，提供SQL构建器功能。
-
-#### 主要方法
-
-- `table(tableName)` - 设置表名，返回当前实例
-- `add(body)` - 添加单条数据，返回`Promise<Object>`
-- `del(query, like)` - 删除数据，返回`Promise<Object>`
-- `set(query, body, like)` - 更新数据，返回`Promise<Object>`
-- `get(query, sort, view, like, timeout)` - 查询多条数据，返回`Promise<Array>`
-- `getObj(query, sort, view, like, timeout)` - 获取单条记录，返回`Promise<Object|null>`
-- `addList(list, lock, batchSize, timeout)` - 批量添加数据，返回`Promise<Object>`
-- `delList(list, like, batchSize, timeout)` - 批量删除数据，返回`Promise<Object>`
-- `count(query, like, timeout)` - 统计记录数，返回`Promise<Number>`
-- `groupCount(query, groupby, view, sort)` - 分组统计，返回`Promise<Array>`
-- `groupSum(query, groupby, view, sort)` - 分组求和，返回`Promise<Array>`
-- `groupAvg(query, groupby, view, sort)` - 分组平均值，返回`Promise<Array>`
-
-#### SQL构建器方法
-
-- `select(fields)` - 设置查询字段
-- `where(condition)` - 设置查询条件
-- `orWhere(condition)` - 设置OR查询条件
-- `like(field, value)` - 设置LIKE查询条件
-- `orderBy(field, direction)` - 设置排序
-- `groupBy(field)` - 设置分组
-- `having(condition)` - 设置HAVING条件
-- `limit(count)` - 设置限制数量
-- `offset(count)` - 设置偏移量
-- `join(table, condition)` - 设置表连接
-
-## 错误处理
-
-模块提供完善的错误处理机制：
-
-1. **参数验证**：所有公开方法都会验证输入参数，参数不符合要求时会抛出`TypeError`
-2. **SQL错误捕获**：SQL执行错误会被捕获并记录到日志中
-3. **连接错误处理**：连接失败时会自动重连，超过最大重试次数后抛出错误
-4. **事务错误处理**：事务执行失败时会自动回滚，确保数据一致性
-
-错误处理示例：
-
-```javascript
-// 参数验证错误
-try {
-    await db.add(null); // 抛出TypeError
-} catch (err) {
-    console.error('参数错误:', err.message);
-}
-
-// SQL执行错误
-try {
-    await db.exec('SELECT * FROM non_existent_table');
-} catch (err) {
-    console.error('SQL错误:', err.message);
-}
-
-// 事务错误处理
-try {
-    await sqlite.transaction(async (tx) => {
-        await tx.exec('INSERT INTO users (name) VALUES (?)', ['Alice']);
-        await tx.exec('INSERT INTO users (name) VALUES (?)', [null]); // 触发错误
-    });
-} catch (err) {
-    console.error('事务执行失败:', err.message);
-}
-```
-
-## 性能监控
-
-模块内置连接池和性能优化功能：
-
-1. **连接池管理**：自动管理数据库连接，提高并发性能
-2. **连接复用**：连接使用完毕后自动归还到连接池
-3. **连接保活**：定期检查连接状态，自动重连失效连接
-4. **超时控制**：支持连接超时、查询超时等配置
-
-连接池配置示例：
-
-```javascript
-const sqlite = new Sqlite({
-    connection_limit: 5, // 启用连接池，最大5个连接
-    pool_min: 1,        // 最小连接数
-    pool_max: 5,        // 最大连接数
-    pool_idle_timeout: 60000, // 空闲超时60秒
-    enable_keep_alive: true,  // 启用保活
-    enable_reconnect: true    // 启用自动重连
-});
-```
-
-对于大规模应用，建议在生产环境前进行压力测试，确保数据库操作满足性能要求。
-
-## 兼容性
-
-- **Node.js版本**：支持 Node.js 12.0 及以上版本
-- **SQLite版本**：支持 SQLite 3.0 及以上版本
-- **操作系统**：支持 Windows、Linux、macOS
-
-## FAQ
-
-### Q: 如何处理数据库文件不存在的情况？
-A: 模块会自动创建数据库文件，无需手动创建。
-
-### Q: 如何优化查询性能？
-A: 建议使用索引、合理设计表结构、避免全表扫描。
-
-### Q: 如何处理并发访问？
-A: 模块内置连接池机制，支持并发访问。当连接数超过1时自动启用连接池。
-
-### Q: 如何备份数据库？
-A: 可以直接复制数据库文件进行备份。
-
-### Q: 如何查看SQL执行日志？
-A: 启用调试模式即可查看详细的SQL执行日志。
-
-### Q: 连接池如何工作？
-A: 当`connection_limit`大于1时启用连接池，连接池会自动管理连接的获取和释放。
-
-### Q: 事务处理是否安全？
-A: 是的，事务处理包含完整的错误处理机制，失败时会自动回滚。
-
-### Q: 支持哪些SQL操作？
-A: 支持标准的CRUD操作、复杂查询、事务处理、批量操作等。
-
-## 贡献
-
-欢迎提交 Issue 和 Pull Request 来改进这个模块。
+#### 表操作
+- `addTable(table, field, type, auto, commit, timeout)` - 创建表
+- `dropTable(table, timeout)` - 删除表
+- `renameTable(table, new_table, timeout)` - 重命名表
+- `emptyTable(table, timeout)` - 清空表
+- `hasTable(table, timeout)` - 检查表是否存在
+
+#### 字段操作
+- `addField(field, type, value, not_null, auto, comment, timeout)` - 添加字段
+- `delField(table, field, timeout)` - 删除字段
+- `renameField(table, field, new_field, type, timeout)` - 重命名字段
+- `editField(table, field, type, timeout)` - 修改字段
+- `fields(table, field_name, timeout)` - 获取字段信息
+
+#### 数据操作
+- `add(data, timeout)` - 插入数据
+- `set(where, data, timeout)` - 更新数据
+- `del(where, timeout)` - 删除数据
+- `get(where, timeout)` - 查询数据
+- `getTableData(table, batchSize, timeout)` - 获取表数据
+
+#### 事务操作
+- `start()` - 开始事务
+- `commit(transaction)` - 提交事务
+- `back(transaction)` - 回滚事务
+- `transaction(callback)` - 事务中执行操作
+
+## 配置参数
+
+| 参数 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| dir | string | './db/' | 数据库文件存储目录 |
+| database | string | 'mm' | 数据库文件名 |
+| charset | string | 'utf8mb4' | 字符集 |
+| timezone | string | '+08:00' | 时区 |
+| connect_timeout | number | 20000 | 连接超时时间(ms) |
+| acquire_timeout | number | 20000 | 获取连接超时时间(ms) |
+| query_timeout | number | 20000 | 查询超时时间(ms) |
+| connection_limit | number | 1 | 连接限制 |
+| enable_keep_alive | boolean | true | 启用保活 |
+| keep_alive_initial_delay | number | 10000 | 保活初始延迟(ms) |
+| enable_reconnect | boolean | true | 启用重连 |
+| reconnect_interval | number | 1000 | 重连间隔(ms) |
+| max_reconnect_attempts | number | 5 | 最大重连尝试次数 |
+| wait_for_connections | boolean | true | 等待连接 |
+| pool_min | number | 1 | 连接池最小连接数 |
+| pool_max | number | 5 | 连接池最大连接数 |
+| pool_acquire_timeout | number | 30000 | 连接池获取超时(ms) |
+| pool_idle_timeout | number | 60000 | 连接池空闲超时(ms) |
+| pool_reap_interval | number | 1000 | 连接池清理间隔(ms) |
+
+## 开发规范
+
+- 使用JavaScript开发，禁止使用TypeScript
+- 使用JSDoc注释进行类型定义
+- 遵循统一的命名规范和方法签名
+- 完善的错误处理机制
+- 支持异步/等待语法
 
 ## 许可证
 
@@ -432,18 +196,4 @@ MIT License
 
 ## 贡献
 
-欢迎提交Issue和Pull Request来改进这个模块。提交代码前请确保：
-
-1. 运行测试确保功能正常
-2. 添加适当的注释和文档
-3. 遵循项目的代码风格
-4. 确保代码符合ES6+标准
-5. 提交前请先拉取最新代码，解决冲突
-
-### 开发流程
-
-1. Fork 仓库
-2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
-3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
-4. 推送到分支 (`git push origin feature/AmazingFeature`)
-5. 打开 Pull Request
+欢迎提交Issue和Pull Request来改进这个项目。