mm_mysql 2.2.5 → 2.2.6

package/README.md

@@ -1,9 +1,8 @@
 # mm_mysql
-一个简洁、高效的Node.js MySQL操作库，支持async/await语法，提供直观的API和强大的功能扩展。
 
-[![npm version](https://badge.fury.io/js/mm_mysql.svg)](https://www.npmjs.com/package/mm_mysql)
-[![GitHub issues](https://img.shields.io/github/issues/qiuwenwu91/mm_mysql.svg)](https://gitee.com/qiuwenwu91/mm_mysql/issues)
-[![GitHub license](https://img.shields.io/github/license/qiuwenwu91/mm_mysql.svg)](https://github.com/qiuwenwu91/mm_mysql/blob/main/LICENSE)
+[中文](./README.md) | [English](./README_EN.md)
+
+一个简洁、高效的Node.js MySQL操作库，支持async/await语法，提供直观的API和强大的功能扩展。
 
 ## 安装
 

package/README_EN.md

@@ -0,0 +1,478 @@
+# mm_mysql
+
+[中文](./README.md) | [English](./README_EN.md)
+
+A concise and efficient Node.js MySQL operation library with async/await support, providing intuitive API and powerful feature extensions.
+
+## Installation
+
+```bash
+npm install mm_mysql
+```
+
+## Basic Usage
+
+```javascript
+const { Mysql } = require('mm_mysql');
+
+// Create mysql instance
+const mysql = new Mysql({
+  host: "localhost",
+  port: 3306,
+  user: "root",
+  password: "your_password",
+  database: "your_database"
+});
+
+// Open connection (no need to call init() method)
+await mysql.open();
+
+// Get database manager and set table name
+const db = mysql.db().new('users', 'id');
+
+// Perform operations...
+
+// Close connection when done
+await mysql.close();
+```
+
+## Key Features
+
+- Support for async/await syntax, avoiding callback hell
+- Clean and intuitive API interface
+- Built-in transaction support
+- Automatic type inference for table creation (supports int, float, varchar, text, datetime, date, time, boolean, and more)
+- Flexible query condition support
+- Connection pool management support
+- Debug mode support
+
+## API Documentation
+
+### Mysql Class
+
+#### Constructor
+
+```javascript
+new Mysql(config)
+```
+
+Parameter description:
+- `config` {Object} Database configuration object
+
+#### Configuration Parameters
+
+```javascript
+const config = {
+  host: "127.0.0.1",          // Server address
+  port: 3306,                 // Port number
+  user: "root",              // Connection username
+  password: "password",       // Connection password
+  database: "dbname",        // Database name
+  charset: "utf8mb4",         // Character set
+  timezone: "+08:00",         // Timezone
+  connect_timeout: 20000,      // Connection timeout (milliseconds)
+  connection_limit: 10,        // Connection pool size
+  acquire_timeout: 20000,      // Connection acquisition timeout (milliseconds)
+  wait_for_connections: true   // Whether to wait for connections
+};
+```
+
+#### Main Methods
+
+##### open()
+Open database connection
+- Returns: {Promise<boolean>} Connection result
+
+##### close()
+Close database connection
+- Returns: {Promise<boolean>} Close result
+
+##### run(sql, params)
+Execute query SQL statement
+- `sql` {String} SQL statement
+- `params` {Array} Parameter array (optional)
+- Returns: {Promise<Array>} Query result array
+
+##### exec(sql, params)
+Execute non-query SQL statement (insert, update, delete)
+- `sql` {String} SQL statement
+- `params` {Array} Parameter array (optional)
+- Returns: {Promise<number>} Number of affected rows
+
+##### db()
+Get database manager instance
+- Returns: {Object} DB class instance
+
+### DB Class
+
+#### Constructor
+
+```javascript
+new DB(mysql, table, key)
+```
+
+Parameter description:
+- `mysql` {Object} Mysql instance
+- `table` {String} Table name
+- `key` {String} Primary key field name
+
+#### Main Methods
+
+##### new(table, key)
+Create new DB instance with specified table and key
+- `table` {String} Table name
+- `key` {String} Primary key field name
+- Returns: {Object} New DB instance
+
+##### table(table)
+Set table name
+- `table` {String} Table name
+- Returns: {Object} Current DB instance
+
+##### key(key)
+Set primary key
+- `key` {String} Primary key field name
+- Returns: {Object} Current DB instance
+
+##### add(data, timeout)
+Insert data
+- `data` {Object} Data to insert
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<Object>} Insert result
+
+##### set(where, data, timeout)
+Update data
+- `where` {Object} Where conditions
+- `data` {Object} Data to update
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<number>} Number of affected rows
+
+##### del(where, timeout)
+Delete data
+- `where` {Object} Where conditions
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<number>} Number of affected rows
+
+##### get(where, options, timeout)
+Query data
+- `where` {Object} Where conditions (optional)
+- `options` {Object} Query options (optional)
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<Array>} Query result array
+
+##### count(where, timeout)
+Count records
+- `where` {Object} Where conditions (optional)
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<number>} Record count
+
+##### sum(field, where, timeout)
+Sum field values
+- `field` {String} Field name
+- `where` {Object} Where conditions (optional)
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<number>} Sum result
+
+##### max(field, where, timeout)
+Get maximum value
+- `field` {String} Field name
+- `where` {Object} Where conditions (optional)
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<number>} Maximum value
+
+##### min(field, where, timeout)
+Get minimum value
+- `field` {String} Field name
+- `where` {Object} Where conditions (optional)
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<number>} Minimum value
+
+#### Table Operations
+
+##### addTable(table, field, type, auto, commit, timeout)
+Create table
+- `table` {String} Table name
+- `field` {String} Field name
+- `type` {String} Field type
+- `auto` {Boolean} Auto increment (optional)
+- `commit` {Boolean} Commit transaction (optional)
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<boolean>} Create result
+
+##### dropTable(table, timeout)
+Drop table
+- `table` {String} Table name
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<boolean>} Drop result
+
+##### renameTable(table, new_table, timeout)
+Rename table
+- `table` {String} Original table name
+- `new_table` {String} New table name
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<boolean>} Rename result
+
+##### emptyTable(table, timeout)
+Empty table
+- `table` {String} Table name
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<boolean>} Empty result
+
+##### hasTable(table, timeout)
+Check if table exists
+- `table` {String} Table name
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<boolean>} Existence result
+
+#### Field Operations
+
+##### addField(table, field, type, len, def, not_null, auto, comment, timeout)
+Add field
+- `table` {String} Table name
+- `field` {String} Field name
+- `type` {String} Field type
+- `len` {Number} Field length (optional)
+- `def` {String} Default value (optional)
+- `not_null` {Boolean} Not null constraint (optional)
+- `auto` {Boolean} Auto increment (optional)
+- `comment` {String} Field comment (optional)
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<boolean>} Add result
+
+##### dropField(table, field, timeout)
+Drop field
+- `table` {String} Table name
+- `field` {String} Field name
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<boolean>} Drop result
+
+##### renameField(table, field, new_field, type, timeout)
+Rename field
+- `table` {String} Table name
+- `field` {String} Original field name
+- `new_field` {String} New field name
+- `type` {String} Field type
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<boolean>} Rename result
+
+##### fields(table, field_name, timeout)
+Get table fields
+- `table` {String} Table name
+- `field_name` {String} Specific field name (optional)
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<Array>} Field information array
+
+##### hasField(table, field, timeout)
+Check if field exists
+- `table` {String} Table name
+- `field` {String} Field name
+- `timeout` {Number} Timeout in milliseconds (optional, default: 15000)
+- Returns: {Promise<boolean>} Existence result
+
+#### Transaction Operations
+
+##### start()
+Start transaction
+- Returns: {Promise<Object>} Transaction object
+
+##### commit(transaction)
+Commit transaction
+- `transaction` {Object} Transaction object
+- Returns: {Promise<void>}
+
+##### rollback(transaction)
+Rollback transaction
+- `transaction` {Object} Transaction object
+- Returns: {Promise<void>}
+
+#### Utility Methods
+
+##### size(size)
+Set batch size
+- `size` {Number} Batch size
+- Returns: {Object} Current DB instance
+
+##### getTableData(table, batchSize, timeout)
+Get table data in batches
+- `table` {String} Table name
+- `batchSize` {Number} Batch size (optional, default: 100)
+- `timeout` {Number} Timeout in milliseconds (optional, default: 60000)
+- Returns: {Promise<Array>} Table data array
+
+## 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
+
+## Advanced Usage Examples
+
+### Complex Queries
+
+```javascript
+// Complex conditional query with sorting and pagination
+const users = await db.get({
+  status: 'active',
+  age: { _gte: 18, _lte: 65 },
+  email: { _like: '%@example.com' }
+}, {
+  order: 'created_at desc',
+  limit: 10,
+  offset: 0,
+  field: 'id,username,email'
+});
+
+// Count with conditions
+const activeUserCount = await db.count({
+  status: 'active',
+  created_at: { _gte: new Date('2023-01-01') }
+});
+
+// Aggregate functions
+const totalAge = await db.sum('age', { status: 'active' });
+const oldestAge = await db.max('age', { status: 'active' });
+```
+
+### Transaction Management
+
+```javascript
+// Transaction example
+const transaction = await db.start();
+try {
+  // Insert multiple records
+  await db.add({ username: 'Alice', email: 'alice@example.com' });
+  await db.add({ username: 'Bob', email: 'bob@example.com' });
+  
+  // Update record
+  await db.set({ username: 'Alice' }, { status: 'verified' });
+  
+  // Commit transaction
+  await db.commit(transaction);
+  console.log('Transaction completed successfully');
+} catch (error) {
+  // Rollback on error
+  await db.rollback(transaction);
+  console.error('Transaction failed:', error.message);
+}
+```
+
+### Table and Field Operations
+
+```javascript
+// Create table
+await db.addTable('users', 'id', 'int', true);
+
+// Add fields
+await db.addField('users', 'username', 'varchar', 50, '', true);
+await db.addField('users', 'email', 'varchar', 100, '', true);
+await db.addField('users', 'age', 'int', null, '0', false);
+
+// Check if table exists
+const tableExists = await db.hasTable('users');
+
+// Get table fields
+const fields = await db.fields('users');
+
+// Check if field exists
+const fieldExists = await db.hasField('users', 'email');
+```
+
+## Error Handling
+
+All methods include comprehensive error handling:
+
+```javascript
+try {
+  const result = await db.get({ id: 1 });
+  console.log('Query result:', result);
+} catch (error) {
+  console.error('Query failed:', error.message);
+  // Handle specific error types
+  if (error.code === 'ER_NO_SUCH_TABLE') {
+    console.error('Table does not exist');
+  }
+}
+```
+
+## Performance Tips
+
+1. **Use Connection Pooling**: Set `connection_limit` > 1 for better concurrent performance
+2. **Batch Operations**: Use transactions for multiple related operations
+3. **Query Optimization**: Use appropriate indexes and limit result sets
+4. **Connection Management**: Close connections when not in use
+
+## 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.