mm_sqlite 1.3.2 → 1.3.3

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 邱文武
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# mm_sqlite
+[中文](./README.md) | [English](./README_EN.md)
+
+高性能SQLite数据库操作模块，提供与mm_mysql完全兼容的API接口。适用于Node.js应用的轻量级数据存储解决方案。
+
+## 安装
+
+```bash
+npm install mm_sqlite --save
+```
+
+## 特性
+
+- 🚀 **高性能优化**：经过深度优化的SQL构建器和连接管理
+- 🔄 **完全兼容**：与mm_mysql模块API完全兼容，可无缝切换
+- 📊 **内存优化**：优化的内存使用，减少GC压力
+- 🔧 **链式调用**：流畅的SQL构建器链式调用
+- 🛡️ **错误处理**：完善的错误处理机制
+- 📈 **连接池支持**：支持连接池模式，提高并发性能
+- 🔒 **事务支持**：完整的事务处理机制
+- 🔍 **类型安全**：完善的JSDoc类型注释
+
+## 依赖要求
+
+- Node.js 14.0+
+- SQLite3 3.0+
+
+## 快速开始
+
+### 基本使用
+
+#### 初始化和连接
+
+```javascript
+const { Sqlite } = require('mm_sqlite');
+
+// 创建数据库实例
+const sqlite = new Sqlite({
+    dir: './db/',                  // 数据库文件存储目录
+    database: 'test',              // 数据库文件名（不包含扩展名）
+    charset: 'utf8mb4',            // 字符集
+    timezone: '+08:00',            // 时区
+    connect_timeout: 20000,        // 连接超时时间（毫秒）
+    acquire_timeout: 20000,        // 获取连接超时时间（毫秒）
+    query_timeout: 20000,          // 查询超时时间（毫秒）
+    connection_limit: 1,           // 连接限制（>1启用连接池）
+    enable_keep_alive: true,       // 启用保活
+    keep_alive_initial_delay: 10000, // 保活初始延迟
+    enable_reconnect: true,        // 启用重连
+    reconnect_interval: 1000,      // 重连间隔
+    max_reconnect_attempts: 5,     // 最大重连尝试次数
+    wait_for_connections: true,    // 等待连接
+    pool_min: 1,                   // 连接池最小连接数
+    pool_max: 5,                   // 连接池最大连接数
+    pool_acquire_timeout: 30000,   // 连接池获取超时
+    pool_idle_timeout: 60000,      // 连接池空闲超时
+    pool_reap_interval: 1000       // 连接池清理间隔
+});
+
+// 打开数据库连接
+await sqlite.open();
+```
+
+#### 基础操作
+
+```javascript
+// 获取数据库管理器
+const db = sqlite.db();
+
+// 设置表名
+const userDb = db.new('users', 'id');
+
+// 插入数据
+const result = await userDb.add({
+    username: '张三',
+    email: 'zhangsan@example.com',
+    age: 28,
+    created_at: new Date()
+});
+
+// 查询数据
+const users = await userDb.get();
+
+// 更新数据
+await userDb.set({ id: 1 }, { age: 29 });
+
+// 删除数据
+await userDb.del({ id: 1 });
+```
+
+#### 高级查询
+
+```javascript
+// 条件查询
+const adultUsers = await userDb.get({
+    age: { _gte: 18 }
+});
+
+// 分页查询
+const pageUsers = await userDb.get({
+    _page: 1,
+    _size: 10,
+    _sort: 'created_at desc'
+});
+
+// 聚合查询
+const stats = await userDb.aggr({
+    _count: 'id',
+    _avg: 'age',
+    _max: 'age',
+    _min: 'age'
+});
+```
+
+## API参考
+
+### Sqlite类
+
+#### 构造函数
+```javascript
+new Sqlite(config)
+```
+
+#### 主要方法
+
+- `open()` - 打开数据库连接
+- `close()` - 关闭数据库连接
+- `db()` - 获取数据库管理器实例
+- `run(sql, params)` - 执行查询SQL
+- `exec(sql, params)` - 执行非查询SQL
+
+### DB类
+
+#### 表操作
+- `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注释进行类型定义
+- 遵循统一的命名规范和方法签名
+- 完善的错误处理机制
+- 支持异步/等待语法
+
+## 许可证
+
+MIT License
+
+## 贡献
+
+欢迎提交Issue和Pull Request来改进这个项目。

package/README_EN.md

@@ -0,0 +1,293 @@
+# mm_sqlite
+
+[中文](./README.md) | [English](./README_EN.md)
+
+High-performance SQLite database operation module with API fully compatible with mm_mysql. A lightweight data storage solution for Node.js applications.
+
+## Installation
+
+```bash
+npm install mm_sqlite --save
+```
+
+## Features
+
+- 🚀 **High Performance**: Deeply optimized SQL builder and connection management
+- 🔄 **Fully Compatible**: API fully compatible with mm_mysql module, seamless switching
+- 📊 **Memory Optimized**: Optimized memory usage, reduced GC pressure
+- 🔧 **Chainable API**: Fluent SQL builder with chainable calls
+- 🛡️ **Error Handling**: Comprehensive error handling mechanism
+- 📈 **Connection Pool Support**: Connection pool mode for better concurrency
+- 🔒 **Transaction Support**: Complete transaction handling mechanism
+- 🔍 **Type Safety**: Comprehensive JSDoc type annotations
+
+## Requirements
+
+- Node.js 14.0+
+- SQLite3 3.0+
+
+## Quick Start
+
+### Basic Usage
+
+#### Initialization and Connection
+
+```javascript
+const { Sqlite } = require('mm_sqlite');
+
+// Create database instance
+const sqlite = new Sqlite({
+    dir: './db/',                  // Database file storage directory
+    database: 'test',              // Database filename (without extension)
+    charset: 'utf8mb4',            // Character set
+    timezone: '+08:00',            // Timezone
+    connect_timeout: 20000,        // Connection timeout (ms)
+    acquire_timeout: 20000,        // Connection acquisition timeout (ms)
+    query_timeout: 20000,          // Query timeout (ms)
+    connection_limit: 1,           // Connection limit (>1 enables connection pool)
+    enable_keep_alive: true,       // Enable keep-alive
+    keep_alive_initial_delay: 10000, // Keep-alive initial delay
+    enable_reconnect: true,        // Enable reconnection
+    reconnect_interval: 1000,      // Reconnection interval
+    max_reconnect_attempts: 5,     // Maximum reconnection attempts
+    wait_for_connections: true,    // Wait for connections
+    pool_min: 1,                   // Connection pool minimum connections
+    pool_max: 5,                   // Connection pool maximum connections
+    pool_acquire_timeout: 30000,   // Connection pool acquisition timeout
+    pool_idle_timeout: 60000,      // Connection pool idle timeout
+    pool_reap_interval: 1000       // Connection pool cleanup interval
+});
+
+// Open database connection
+await sqlite.open();
+```
+
+#### Basic Operations
+
+```javascript
+// Get database manager
+const db = sqlite.db();
+
+// Set table name
+const userDb = db.new('users', 'id');
+
+// Insert data
+const result = await userDb.add({
+    username: 'John',
+    email: 'john@example.com',
+    age: 28,
+    created_at: new Date()
+});
+
+// Query data
+const users = await userDb.get();
+
+// Update data
+await userDb.set({ id: 1 }, { age: 29 });
+
+// Delete data
+await userDb.del({ id: 1 });
+```
+
+#### Advanced Queries
+
+```javascript
+// Conditional queries
+const adultUsers = await userDb.get({
+    age: { _gte: 18 }
+});
+
+// Complex queries with sorting and pagination
+const users = await userDb.get({
+    status: 'active',
+    age: { _gte: 18, _lte: 65 }
+}, {
+    order: 'created_at desc',
+    limit: 10,
+    offset: 0
+});
+
+// Transaction operations
+const transaction = await db.start();
+try {
+    await userDb.add({ username: 'Alice', email: 'alice@example.com' });
+    await userDb.add({ username: 'Bob', email: 'bob@example.com' });
+    await db.commit(transaction);
+} catch (error) {
+    await db.rollback(transaction);
+    throw error;
+}
+```
+
+## API Reference
+
+### Sqlite Class
+
+#### Constructor
+```javascript
+new Sqlite(config)
+```
+
+#### Configuration Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| dir | string | './db/' | Database file storage directory |
+| database | string | 'test' | Database filename (without .sqlite extension) |
+| charset | string | 'utf8mb4' | Character set |
+| timezone | string | '+08:00' | Timezone offset |
+| connect_timeout | number | 20000 | Connection timeout in milliseconds |
+| acquire_timeout | number | 20000 | Connection acquisition timeout |
+| query_timeout | number | 20000 | Query timeout |
+| connection_limit | number | 1 | Connection limit (>1 enables connection pool) |
+| enable_keep_alive | boolean | true | Enable keep-alive mechanism |
+| keep_alive_initial_delay | number | 10000 | Keep-alive initial delay |
+| enable_reconnect | boolean | true | Enable automatic reconnection |
+| reconnect_interval | number | 1000 | Reconnection interval |
+| max_reconnect_attempts | number | 5 | Maximum reconnection attempts |
+| wait_for_connections | boolean | true | Wait for available connections |
+| pool_min | number | 1 | Connection pool minimum connections |
+| pool_max | number | 5 | Connection pool maximum connections |
+| pool_acquire_timeout | number | 30000 | Connection pool acquisition timeout |
+| pool_idle_timeout | number | 60000 | Connection pool idle timeout |
+| pool_reap_interval | number | 1000 | Connection pool cleanup interval |
+
+#### Main Methods
+
+- `open()` - Open database connection
+- `close()` - Close database connection
+- `db()` - Get database manager instance
+- `run(sql, params)` - Execute query SQL
+- `exec(sql, params)` - Execute non-query SQL
+
+### DB Class
+
+#### Table Operations
+- `addTable(table, field, type, auto, commit, timeout)` - Create table
+- `dropTable(table, timeout)` - Drop table
+- `renameTable(table, new_table, timeout)` - Rename table
+- `emptyTable(table, timeout)` - Empty table
+- `hasTable(table, timeout)` - Check if table exists
+
+#### Field Operations
+- `addField(table, field, type, len, def, not_null, auto, comment, timeout)` - Add field
+- `dropField(table, field, timeout)` - Drop field
+- `renameField(table, field, new_field, type, timeout)` - Rename field
+- `fields(table, field_name, timeout)` - Get table fields
+- `hasField(table, field, timeout)` - Check if field exists
+
+#### Data Operations
+- `add(data, timeout)` - Insert data
+- `set(where, data, timeout)` - Update data
+- `del(where, timeout)` - Delete data
+- `get(where, options, timeout)` - Query data
+- `count(where, timeout)` - Count records
+- `sum(field, where, timeout)` - Sum field values
+- `max(field, where, timeout)` - Get maximum value
+- `min(field, where, timeout)` - Get minimum value
+
+#### Transaction Operations
+- `start()` - Start transaction
+- `commit(transaction)` - Commit transaction
+- `rollback(transaction)` - Rollback transaction
+
+#### Utility Methods
+- `new(table, key)` - Create new DB instance with table and key
+- `table(table)` - Set table name
+- `key(key)` - Set primary key
+- `size(size)` - Set batch size
+- `getTableData(table, batchSize, timeout)` - Get table data in batches
+
+## Query Conditions
+
+### Comparison Operators
+- `_eq` - Equal to
+- `_neq` - Not equal to
+- `_gt` - Greater than
+- `_gte` - Greater than or equal to
+- `_lt` - Less than
+- `_lte` - Less than or equal to
+
+### Logical Operators
+- `_and` - Logical AND
+- `_or` - Logical OR
+- `_not` - Logical NOT
+
+### Array Operators
+- `_in` - In array
+- `_nin` - Not in array
+
+### String Operators
+- `_like` - Like pattern
+- `_nlike` - Not like pattern
+
+### Null Operators
+- `_null` - Is null
+- `_nnull` - Is not null
+
+## Query Options
+
+### Pagination
+- `limit` - Number of records to return
+- `offset` - Number of records to skip
+
+### Sorting
+- `order` - Sort order (e.g., 'name asc', 'created_at desc')
+
+### Field Selection
+- `field` - Specific fields to return
+- `group` - Group by fields
+
+## Error Handling
+
+All methods include comprehensive error handling:
+
+```javascript
+try {
+    const result = await db.get({ id: 1 });
+} catch (error) {
+    console.error('Query failed:', error.message);
+}
+```
+
+## Development Specifications
+
+### Code Style
+- Use 2-space indentation
+- Single quotes for strings
+- One class per file or multiple functions
+
+### Naming Conventions
+- Class names: PascalCase
+- Function/method names: camelCase
+- Parameters/variables: snake_case
+- Constants: UPPER_SNAKE_CASE
+- Maximum name length: 20 characters
+- Prefer single-word names
+
+### Error Handling
+- Parameter validation using `throw new TypeError()`
+- Use try...catch for calling other class methods
+- Chinese error messages (for Chinese version)
+
+### Performance
+- Method length ≤ 40 lines
+- Single line ≤ 100 characters
+- Each class focuses on single responsibility
+- Each method does one thing only
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Support
+
+For issues and questions, please open an issue on the GitHub repository.