mm_redis 2.0.7 → 2.0.9

package/README.md

@@ -1,23 +1,28 @@
 # mm_redis
 
-mm_redis是一个高效的Redis客户端封装库，提供了全面的Redis功能支持，包括连接池管理、数据类型操作、错误处理和批量操作优化。
-
-[![npm version](https://badge.fury.io/js/mm_redis.svg)](https://badge.fury.io/js/mm_redis)
+[![npm version](https://badge.fury.io/js/mm_redis.svg)](https://www.npmjs.com/package/mm_redis)
 [![npm downloads](https://img.shields.io/npm/dm/mm_redis.svg)](https://www.npmjs.com/package/mm_redis)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+> 一个高效的Redis客户端封装库，提供完整的连接池管理、数据类型操作和批量操作优化
 
 ## 版本信息
 
-- **当前版本**: 2.0.5
+- **最新版本**: 2.0.0
 - **更新日期**: 2025-10-20
 - **作者**: qww
 - **NPM**: [https://www.npmjs.com/package/mm_redis](https://www.npmjs.com/package/mm_redis)
 - **GitHub**: [https://gitee.com/qiuwenwu91/mm_redis](https://gitee.com/qiuwenwu91/mm_redis)
+- **Node.js**: >= 14.0.0
 
 ## 功能特性
 
+### 🚀 核心功能
 - **完整的连接池管理**：优化并发性能，支持连接复用和自动回收
 - **Pipeline批量操作**：支持Redis Pipeline机制，大幅提升批量操作效率
 - **全面的数据类型支持**：覆盖String、List、Hash、Set、Sorted Set等所有主要Redis数据类型
+
+### 🔧 高级特性
 - **智能连接管理**：自动重连机制，使用指数退避策略，确保连接稳定可靠
 - **健壮的错误处理**：全面的错误处理机制和详细的日志记录，便于问题排查
 - **便捷的数据序列化**：自动JSON序列化/反序列化，无需手动转换数据格式
@@ -27,55 +32,113 @@ mm_redis是一个高效的Redis客户端封装库，提供了全面的Redis功
 
 ## 安装
 
+### npm
+```bash
+npm install mm_redis
+```
+
+### yarn
+```bash
+yarn add mm_redis
+```
+
+### pnpm
 ```bash
-npm install mm_redis --save
+pnpm add mm_redis
 ```
 
-## Node.js版本要求
+## 快速开始
+
+```javascript
+const { Redis } = require('mm_redis');
+
+// 创建Redis实例
+const redis = new Redis({
+    host: 'localhost',
+    port: 6379,
+    password: 'your_password',
+    db: 0
+});
+
+// 连接Redis
+await redis.connect();
+
+// 设置缓存
+await redis.set('user:1', { name: '张三', age: 25 });
+
+// 获取缓存
+const user = await redis.get('user:1');
+console.log(user); // { name: '张三', age: 25 }
 
-- **最低支持版本**：Node.js 14.0.0
-- **推荐版本**：Node.js 16.0.0及以上
+// 错误处理
+try {
+    await redis.set('key', 'value');
+} catch (err) {
+    console.error('Redis操作失败:', err);
+}
+```
 
 ## 配置引入方式
 
-mm_redis支持多种配置引入方式：
+mm_redis支持多种配置引入方式，满足不同场景的需求：
 
-1. **对象配置（推荐）**：直接传入配置对象
+### 1. 对象配置（推荐）
 ```javascript
-const Redis = require('mm_redis');
-const redis = new Redis('default');
-redis.setConfig({
-    // 服务器地址
-    host: "localhost",
-    // 端口号
+const { Redis } = require('mm_redis');
+
+// 直接传入配置对象
+const redis = new Redis({
+    host: 'localhost',
     port: 6379,
-    // 密码
-    password: "",
-    // 数据库
-    database: 0,
-    // 前缀
-    prefix: "app:",
-    // 连接超时时间(ms)
-    connect_timeout: 10000,
-    // 重试次数
-    retry_count: 3,
-    // 重试间隔(ms)
-    retry_delay: 1000,
-    // 连接池配置
-    pool: {
-        max_clients: 10,      // 最大连接数
-        min_idle: 2,          // 最小空闲连接数
-        max_idle: 5,          // 最大空闲连接数
-        idle_timeout: 30000   // 空闲超时时间(ms)
-    }
+    password: 'your_password',
+    db: 0,
+    key_prefix: 'app:',
+    max_clients: 10,
+    connect_timeout: 5000
 });
 ```
 
-2. **文件配置**：传入配置文件路径
+### 2. 文件配置
+```javascript
+// config/redis.json
+{
+    "host": "localhost",
+    "port": 6379,
+    "password": "your_password",
+    "db": 0,
+    "key_prefix": "app:",
+    "max_clients": 10,
+    "connect_timeout": 5000
+}
+
+// 使用配置
+const { Redis } = require('mm_redis');
+const config = require('./config/redis.json');
+const redis = new Redis(config);
+```
+
+### 3. 环境变量配置
 ```javascript
-const Redis = require('mm_redis');
-const redis = new Redis('default');
-redis.setConfig('./config.json');
+// 环境变量
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=your_password
+REDIS_DB=0
+REDIS_KEY_PREFIX=app:
+REDIS_MAX_CLIENTS=10
+REDIS_CONNECT_TIMEOUT=5000
+
+// 使用环境变量
+const { Redis } = require('mm_redis');
+const redis = new Redis({
+    host: process.env.REDIS_HOST,
+    port: parseInt(process.env.REDIS_PORT),
+    password: process.env.REDIS_PASSWORD,
+    db: parseInt(process.env.REDIS_DB),
+    key_prefix: process.env.REDIS_KEY_PREFIX,
+    max_clients: parseInt(process.env.REDIS_MAX_CLIENTS),
+    connect_timeout: parseInt(process.env.REDIS_CONNECT_TIMEOUT)
+});
 ```
 ## 变更日志
 

package/README_EN.md

@@ -0,0 +1,433 @@
+# mm_redis
+
+[![npm version](https://badge.fury.io/js/mm_redis.svg)](https://www.npmjs.com/package/mm_redis)
+[![npm downloads](https://img.shields.io/npm/dm/mm_redis.svg)](https://www.npmjs.com/package/mm_redis)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+A high-performance Redis client wrapper library that provides comprehensive Redis functionality support, including connection pool management, data type operations, error handling, and batch operation optimization.
+
+## Version Information
+
+- **Latest Version**: 2.0.0
+- **Update Date**: 2025-10-20
+- **Author**: qww
+- **NPM**: [https://www.npmjs.com/package/mm_redis](https://www.npmjs.com/package/mm_redis)
+- **GitHub**: [https://gitee.com/qiuwenwu91/mm_redis](https://gitee.com/qiuwenwu91/mm_redis)
+- **Node.js**: >= 14.0.0
+
+## Features
+
+### 🚀 Core Features
+- **Complete Connection Pool Management**: Optimized concurrent performance with connection reuse and automatic recycling
+- **Pipeline Batch Operations**: Support for Redis Pipeline mechanism, significantly improving batch operation efficiency
+- **Comprehensive Data Type Support**: Covers all major Redis data types including String, List, Hash, Set, Sorted Set
+
+### 🔧 Advanced Features
+- **Smart Connection Management**: Automatic reconnection with exponential backoff strategy for reliable connections
+- **Robust Error Handling**: Comprehensive error handling mechanism with detailed logging
+- **Automatic Data Serialization**: Automatic JSON serialization/deserialization without manual conversion
+- **Key Space Isolation**: Support for key prefix management for multi-business scenario data isolation
+- **Flexible Event System**: Unified event mechanism supporting pre/post operation event listening and interception
+- **Rich Numeric Operations**: Support for atomic increment/decrement operations, suitable for counter scenarios
+
+## Installation
+
+### Using npm
+```bash
+npm install mm_redis --save
+```
+
+### Using yarn
+```bash
+yarn add mm_redis
+```
+
+### Using pnpm
+```bash
+pnpm add mm_redis
+```
+
+## Node.js Version Requirements
+
+- **Minimum Supported Version**: Node.js 14.0.0
+- **Recommended Version**: Node.js 16.0.0 and above
+
+## Quick Start
+
+### Basic Usage
+```javascript
+const Redis = require('mm_redis');
+
+// Create Redis instance
+const redis = new Redis('default');
+
+async function example() {
+    try {
+        // Connect to Redis
+        await redis.open();
+        
+        // Set cache with expiration
+        await redis.set('user:1', { name: 'John', age: 25 }, 3600);
+        
+        // Get cache
+        const user = await redis.get('user:1');
+        console.log('User info:', user);
+        
+        // Close connection
+        await redis.close();
+    } catch (error) {
+        console.error('Operation failed:', error);
+    }
+}
+
+example();
+```
+
+## Configuration
+
+mm_redis supports multiple configuration loading methods:
+
+### Object Configuration (Recommended)
+```javascript
+const Redis = require('mm_redis');
+const redis = new Redis('default');
+
+redis.setConfig({
+    host: "localhost",
+    port: 6379,
+    password: "",
+    database: 0,
+    prefix: "app:",
+    connect_timeout: 10000,
+    retry_count: 3,
+    retry_delay: 1000,
+    pool: {
+        max_clients: 10,
+        min_idle: 2,
+        max_idle: 5,
+        idle_timeout: 30000
+    }
+});
+```
+
+### File Configuration
+```javascript
+const Redis = require('mm_redis');
+const redis = new Redis('default');
+
+redis.setConfig('./config.json');
+```
+
+Configuration file example (`config.json`):
+```json
+{
+    "host": "localhost",
+    "port": 6379,
+    "password": "",
+    "database": 0,
+    "prefix": "app:",
+    "connect_timeout": 10000,
+    "retry_count": 3,
+    "retry_delay": 1000,
+    "pool": {
+        "max_clients": 10,
+        "min_idle": 2,
+        "max_idle": 5,
+        "idle_timeout": 30000
+    }
+}
+```
+
+### Environment Variables
+```javascript
+const Redis = require('mm_redis');
+const redis = new Redis('default');
+
+redis.setConfig({
+    host: process.env.REDIS_HOST || 'localhost',
+    port: parseInt(process.env.REDIS_PORT) || 6379,
+    password: process.env.REDIS_PASSWORD || '',
+    database: parseInt(process.env.REDIS_DB) || 0
+});
+```
+
+## Change Log
+
+### v2.0.0 (2025-10-14)
+- Removed list_push method, unified to use addForList method for list operations
+- Updated documentation, replaced all list_push references with addForList
+- Updated API list and usage examples in documentation
+- Optimized connection pool configuration management, unified configuration to this.config.pool
+- Added connection pool configuration parameters: min_idle, max_idle, idle_timeout
+
+### v1.9.8 (2024-12-22)
+- Updated documentation, improved content required for npm publishing
+- Added GitHub repository link to documentation
+- Optimized feature description, enhanced document readability
+- Added Node.js version requirement description
+
+### v1.9.5 (2024-12-21)
+- Fixed compatibility issues with hmset and hgetall methods to ensure compatibility with Redis client v5
+- Removed deprecated hexists, hkeys and hvals methods, optimized API design
+- Optimized implementation of mget and mset methods to ensure full compatibility with Redis v5 API
+- Updated test scripts, removed calls to deprecated methods
+- Updated compatibility table to ensure documentation matches actual API
+- Fixed errors in native Redis API calls, improved code stability
+- Optimized connection pool management, fixed potential memory leak issues
+
+### v1.9.4 (2024-12-20)
+- Optimized configuration loading methods, supporting both object configuration and file path configuration
+- Improved implementation of setConfig method, using Object.assign instead of original merge method
+- Fixed warning messages related to connection pool
+- Enhanced error handling mechanism
+
+### v1.9.0 (2024-11-20)
+- Initial version release
+- Support for complete connection pool management
+- Implementation of Pipeline batch operations
+- Support for all major Redis data type operations
+
+## Usage Examples
+
+### Basic Operations
+```javascript
+// Connect to Redis
+await redis.open();
+
+// Set cache
+await redis.set('user:1', { name: 'John', age: 25 }, 3600);
+
+// Get cache
+const user = await redis.get('user:1');
+console.log('User info:', user);
+
+// Check if key exists
+const exists = await redis.has('user:1');
+
+// Delete cache
+await redis.del('user:1');
+
+// Close connection
+await redis.close();
+```
+
+### List Operations
+```javascript
+// Set list
+await redis.setForList('users', ['user1', 'user2', 'user3']);
+
+// Add element to list
+await redis.addForList('users', 'user4');
+
+// Get list
+const users = await redis.getForList('users');
+console.log('User list:', users);
+
+// Get partial list elements
+const partialUsers = await redis.getForList('users', 0, 2);
+
+// Clear list
+await redis.clearForList('users');
+```
+
+### Hash Operations
+```javascript
+// Set hash field
+await redis.hset('user:profile:1', 'name', 'John');
+await redis.hset('user:profile:1', 'age', 25);
+
+// Batch set hash fields
+await redis.hmset('user:profile:1', {
+    'email': 'john@example.com',
+    'phone': '1234567890'
+});
+
+// Get hash field
+const name = await redis.hget('user:profile:1', 'name');
+
+// Get all hash fields and values
+const profile = await redis.hgetall('user:profile:1');
+console.log('User profile:', profile);
+
+// Get hash field count
+const fieldCount = await redis.hlen('user:profile:1');
+
+// Delete hash fields
+await redis.hdel('user:profile:1', ['email', 'phone']);
+```
+
+### Batch Operations
+```javascript
+// Batch get
+const data = await redis.mget(['user:1', 'user:2', 'user:3']);
+console.log('Batch get result:', data);
+
+// Batch set
+await redis.mset({
+    'user:4': { name: 'Jane', age: 30 },
+    'user:5': { name: 'Bob', age: 35 }
+}, 3600);
+```
+
+### Pipeline Optimization
+```javascript
+// Create Pipeline
+const pipeline = redis.pipeline();
+
+// Add multiple commands
+pipeline.set('counter:1', 100);
+pipeline.ttl('counter:1', 3600);
+pipeline.hset('stats:today', 'visits', 500);
+pipeline.hset('stats:today', 'users', 100);
+
+// Execute all commands
+const results = await pipeline.exec();
+console.log('Pipeline execution result:', results);
+```
+
+### Publish/Subscribe
+```javascript
+// Subscribe to channel
+await redis.subscribe('notifications', async (message) => {
+    console.log('Received notification:', message);
+    // Process received message
+});
+
+// Publish message
+const receivedCount = await redis.publish('notifications', JSON.stringify({ 
+    type: 'info', 
+    content: 'System update successful' 
+}));
+
+console.log(`Message published, ${receivedCount} clients received`);
+
+// Unsubscribe
+await redis.unsubscribe('notifications');
+```
+
+## API Documentation
+
+### Connection Management
+- `setConfig(config)`: Set Redis configuration
+- `open()`: Connect to Redis
+- `close()`: Close connection
+- `isConnected()`: Check connection status
+
+### String Operations
+- `set(key, value, seconds)`: Set cache
+- `get(key)`: Get cache
+- `has(key)`: Check if key exists
+- `del(key)`: Delete cache
+- `add(key, value, seconds)`: Set cache only if key doesn't exist
+- `ttl(key, seconds)`: Set or get expiration time
+- `addInt(key, num)`: Increment integer value
+- `addFloat(key, num)`: Increment float value
+- `addStr(key, str)`: Append string
+- `getrange(key, start, end)`: Get substring
+- `setrange(key, index, value)`: Set substring
+
+### List Operations
+- `setForList(key, value, seconds)`: Set list
+- `addForList(key, value)`: Add element to list
+- `getForList(key, start, end)`: Get list
+- `hasForList(key, value)`: Check if element exists in list
+- `clearForList(key, value)`: Clear list or reset list
+
+### Hash Operations
+- `hset(key, field, value)`: Set hash field
+- `hmset(key, obj)`: Batch set hash fields
+- `hget(key, field)`: Get hash field value
+- `hgetall(key)`: Get all hash fields and values
+- `hdel(key, fields)`: Delete hash fields
+- `hlen(key)`: Get hash field count
+
+### Batch Operations
+- `mget(keys)`: Batch get cache
+- `mset(obj, seconds)`: Batch set cache
+- `pipeline()`: Create Pipeline object for batch operation optimization
+
+### Set Operations
+- `sadd(key, members)`: Add members to set
+- `srem(key, members)`: Remove members from set
+- `sismember(key, member)`: Check if member is in set
+- `smembers(key)`: Get all members in set
+- `scard(key)`: Get member count in set
+- `sinter(keys)`: Get intersection of multiple sets
+- `sunion(keys)`: Get union of multiple sets
+- `sdiff(keys)`: Get difference of multiple sets
+
+### Sorted Set Operations
+- `zadd(key, score, member)`: Add member to sorted set
+- `zrem(key, members)`: Remove members from sorted set
+- `zscore(key, member)`: Get member score in sorted set
+- `zrank(key, member)`: Get member rank in sorted set
+- `zrange(key, start, stop, withScores)`: Get members in specified range
+- `zcard(key)`: Get member count in sorted set
+- `zincrby(key, increment, member)`: Increment member score in sorted set
+
+### Numeric Operations
+- `incr(key)`: Increment key value by 1
+- `decr(key)`: Decrement key value by 1
+- `incrby(key, increment)`: Increment key value by specified integer
+- `decrby(key, decrement)`: Decrement key value by specified integer
+- `expire(key, seconds)`: Set key expiration time
+
+## Connection Pool Management
+
+This module has built-in efficient connection pool management that automatically handles connection creation, recycling, and reuse. Connection pool configuration can be set during initialization:
+
+```javascript
+{
+    "pool": {
+        "max_clients": 10,      // Maximum connections
+        "min_idle": 2,          // Minimum idle connections
+        "max_idle": 5,          // Maximum idle connections
+        "idle_timeout": 30000   // Idle timeout (ms)
+    }
+}
+```
+
+## Error Handling
+
+All methods include comprehensive error handling mechanisms and provide detailed log output. When errors occur, error information is automatically recorded and fallback solutions are provided when possible.
+
+## Best Practices
+
+1. **Use Connection Pool**: For high-concurrency applications, connection pool configuration is crucial. Reasonably set maximum connections and idle connections.
+2. **Use Pipeline**: For batch operations, using Pipeline can significantly improve performance.
+3. **Set Expiration Time Reasonably**: Avoid unlimited growth of data in Redis.
+4. **Use Key Prefix**: Isolate business through key prefix to avoid key conflicts.
+5. **Close Connections Timely**: Call close() method to close all connections when application ends.
+6. **Leverage Event System**: Use event system for logging, data validation, and operation interception.
+
+## Contributing
+
+We welcome community contributions! If you're interested in contributing to the mm_redis project, please follow these steps:
+
+1. Fork this 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
+
+Please ensure your code follows the project's coding standards and passes all tests.
+
+## License
+
+This project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.
+
+## Issue Reporting
+
+If you encounter any problems or have any suggestions during use, please provide feedback through the following methods:
+
+- **GitHub Issues**: [https://gitee.com/qiuwenwu91/mm_redis/issues](https://gitee.com/qiuwenwu91/mm_redis/issues)
+- **NPM**: [https://www.npmjs.com/package/mm_redis](https://www.npmjs.com/package/mm_redis)
+
+## Acknowledgments
+
+Thanks to all developers and users who have contributed to this project!
+
+## Related Links
+
+- **Redis Official Documentation**: [https://redis.io/documentation](https://redis.io/documentation)
+- **Node Redis Client**: [https://github.com/redis/node-redis](https://github.com/redis/node-redis)