mm_session 1.5.1 → 1.5.3

package/README.md

@@ -0,0 +1,298 @@
+# mm_session
+
+[中文](./README.md) | [English](./README_EN.md)
+
+## 概述
+
+`mm_session` 是一个专为 Koa.js 框架设计的轻量级 session 管理中间件。它提供了简单易用的 session 管理功能，支持自定义存储后端，适用于各种规模的 Web 应用。
+
+这是超级美眉session函数模块，用于web服务端session缓存。
+
+## 特性
+
+- ✅ **Koa 中间件标准** - 符合 `app.use(session({ key: 'test_session', max_age: 3600 }))` 使用方式
+- ✅ **存储抽象层** - 支持自定义存储后端
+- ✅ **自动 session 管理** - 自动创建、保存、销毁 session
+- ✅ **Cookie 自动处理** - 自动设置和读取 session cookie
+- ✅ **安全 session ID** - 基于 IP + 时间戳 + AES 加密生成
+- ✅ **异步支持** - 完整的 async/await 支持
+- ✅ **轻量级** - 无冗余依赖，代码简洁
+- ✅ **生产就绪** - 经过充分测试，稳定可靠
+
+## 安装
+
+```bash
+npm install mm_session
+```
+
+## 快速开始
+
+### 基本用法
+
+```javascript
+const Koa = require('koa');
+const { session } = require('mm_session');
+
+const app = new Koa();
+
+// 注册中间件
+app.use(session({
+  key: 'my_session',      // cookie 名称
+  max_age: 3600          // session 过期时间（秒）
+}));
+
+// 业务路由
+app.use(async (ctx) => {
+  // 设置 session 数据
+  if (!ctx.session.user_id) {
+    ctx.session.user_id = 123;
+    ctx.session.username = 'test_user';
+  }
+  
+  // 读取 session 数据
+  ctx.body = {
+    user_id: ctx.session.user_id,
+    username: ctx.session.username
+  };
+});
+
+app.listen(3000);
+```
+
+### 高级配置
+
+```javascript
+const { Session, Store } = require('mm_session');
+
+// 自定义配置
+const session = new Session({
+  key: 'app_session',           // cookie 键名
+  max_age: 7200,               // 过期时间：2小时
+  http_only: true,             // 仅 HTTP 访问
+  secure: process.env.NODE_ENV === 'production', // 生产环境 HTTPS
+  same_site: 'strict'          // 同站策略
+});
+
+// 自定义存储（可选）
+const customStore = new Store('custom_prefix');
+session.init(customStore);
+```
+
+## API 文档
+
+### Session 类
+
+#### 构造函数
+
+```javascript
+new Session(config)
+```
+
+**参数:**
+- `config` (Object) - 配置对象
+  - `key` (String) - session cookie 名称，默认: 'mm:uuid'
+  - `max_age` (Number) - session 过期时间（秒）
+  - 其他 cookie 配置选项
+
+#### 方法
+
+##### middleware()
+返回 Koa 中间件函数。
+
+```javascript
+app.use(session.middleware());
+```
+
+##### init(store)
+初始化自定义存储后端。
+
+```javascript
+session.init(new CustomStore());
+```
+
+### Store 类
+
+存储抽象类，支持自定义存储实现。
+
+```javascript
+const { Store } = require('mm_session');
+const store = new Store('prefix_');
+```
+
+## 配置选项
+
+### Session 配置
+
+| 选项 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| key | String | 'mm:uuid' | session cookie 名称 |
+| max_age | Number | - | session 过期时间（秒） |
+| http_only | Boolean | true | 仅 HTTP 访问 |
+| secure | Boolean | false | 仅 HTTPS 传输 |
+| same_site | String | 'lax' | 同站策略 |
+
+### Cookie 配置
+
+支持所有 [cookie](https://github.com/jshttp/cookie) 库的配置选项。
+
+## 存储后端
+
+### 默认存储
+默认使用 `mm_cachebase` 作为存储后端，支持内存和文件持久化。
+
+### 自定义存储
+可以实现自定义存储类，只需实现以下接口：
+
+```javascript
+class CustomStore {
+  async get(sessionId) {}
+  async set(sessionData, options, ctx) {}
+  async destroy(sessionId, ctx) {}
+  async getID(ctx) {}
+}
+```
+
+## 示例应用
+
+### 用户登录系统
+
+```javascript
+const session = new Session({
+  key: 'user_session',
+  max_age: 86400 // 24小时
+});
+
+app.use(session.middleware());
+
+// 登录路由
+app.use(async (ctx, next) => {
+  if (ctx.path === '/login' && ctx.method === 'POST') {
+    const { username, password } = ctx.request.body;
+    
+    // 验证用户（示例）
+    if (username === 'admin' && password === 'password') {
+      ctx.session.user = {
+        id: 1,
+        username: 'admin',
+        role: 'administrator'
+      };
+      ctx.body = { success: true };
+    } else {
+      ctx.body = { success: false, error: '认证失败' };
+    }
+  } else {
+    await next();
+  }
+});
+
+// 需要认证的路由
+app.use(async (ctx, next) => {
+  if (!ctx.session.user) {
+    ctx.status = 401;
+    ctx.body = { error: '请先登录' };
+    return;
+  }
+  await next();
+});
+```
+
+## 测试
+
+```bash
+# 运行测试
+npm test
+
+# 或直接运行
+node test.js
+```
+
+## 开发
+
+### 代码规范
+
+项目使用 ESLint 进行代码规范检查：
+
+```bash
+# 检查代码规范
+npx eslint lib/session.js
+
+# 自动修复
+npx eslint lib/session.js --fix
+```
+
+### 项目结构
+
+```
+mm_session/
+├── lib/
+│   ├── session.js     # Session 类实现
+│   └── store.js       # Store 类实现
+├── index.js           # 模块入口
+├── test.js            # 测试文件
+├── eslint.config.js   # ESLint 配置
+└── package.json       # 项目配置
+```
+
+## 贡献
+
+欢迎贡献！请随时提交 Issue 和 Pull Request。
+
+### 开发环境设置
+
+1. 克隆仓库：
+```bash
+git clone https://gitee.com/qiuwenwu91/mm_session.git
+cd mm_session
+```
+
+2. 安装依赖：
+```bash
+npm install
+```
+
+3. 运行测试：
+```bash
+npm test
+```
+
+## 许可证
+
+ISC License
+
+版权所有 (c) 2024 邱文武
+
+特此免费授予任何获得本软件副本和相关文档文件（以下简称"软件"）的人不受限制地处理本软件的权限，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售本软件的副本，以及允许提供本软件的人员这样做，但须符合以下条件：
+
+上述版权声明和本许可声明应包含在本软件的所有副本或重要部分中。
+
+## 作者
+
+邱文武
+
+## 更新日志
+
+### v1.5.3
+- 当前稳定版本
+
+### v1.5.1
+- 修复 session 保存逻辑
+- 优化 cookie 设置机制
+- 改进测试用例
+
+### v1.5.0
+- 重构为类+原型函数模式
+- 符合 Koa 中间件标准使用方式
+- 增强代码可维护性
+
+## 错误报告
+
+如果您遇到任何错误或有功能请求，请在 [Git 仓库](https://gitee.com/qiuwenwu91/mm_session/issues) 上提交 Issue。
+
+## 相关项目
+
+- [mm_cache](https://www.npmjs.com/package/mm_cache) - 缓存库（依赖项）
+- [mm_eslint](https://www.npmjs.com/package/mm_eslint) - ESLint 配置（开发依赖项）
+
+## 支持
+
+如需支持和问题解答，请查阅文档或在项目仓库中创建 Issue。

package/README_EN.md

@@ -0,0 +1,296 @@
+# mm_session
+
+[中文](README.md) | [English](README_EN.md)
+
+## Overview
+
+`mm_session` is a lightweight session management middleware designed specifically for the Koa.js framework. It provides simple and easy-to-use session management functionality with support for custom storage backends, suitable for web applications of all sizes.
+
+This is a super session function module for web server-side session caching.
+
+## Features
+
+- ✅ **Koa Middleware Standard** - Compatible with `app.use(session({ key: 'test_session', max_age: 3600 }))` usage
+- ✅ **Storage Abstraction Layer** - Supports custom storage backends
+- ✅ **Automatic Session Management** - Automatic session creation, saving, and destruction
+- ✅ **Cookie Auto-handling** - Automatic session cookie setting and reading
+- ✅ **Secure Session ID** - Generated based on IP + timestamp + AES encryption
+- ✅ **Async Support** - Full async/await support
+- ✅ **Lightweight** - No redundant dependencies, clean codebase
+- ✅ **Production Ready** - Well-tested and stable for production use
+
+## Installation
+
+```bash
+npm install mm_session
+```
+
+## Quick Start
+
+### Basic Usage
+
+```javascript
+const Koa = require('koa');
+const { session } = require('mm_session');
+
+const app = new Koa();
+
+// Register middleware
+app.use(session({
+  key: 'my_session',      // cookie name
+  max_age: 3600          // session expiration time (seconds)
+}));
+
+// Business routes
+app.use(async (ctx) => {
+  // Set session data
+  if (!ctx.session.user_id) {
+    ctx.session.user_id = 123;
+    ctx.session.username = 'test_user';
+  }
+  
+  // Read session data
+  ctx.body = {
+    user_id: ctx.session.user_id,
+    username: ctx.session.username
+  };
+});
+
+app.listen(3000);
+```
+
+### Advanced Configuration
+
+```javascript
+const { Session, Store } = require('mm_session');
+
+// Custom configuration
+const session = new Session({
+  key: 'app_session',           // cookie key name
+  max_age: 7200,               // expiration time: 2 hours
+  http_only: true,             // HTTP-only access
+  secure: process.env.NODE_ENV === 'production', // HTTPS in production
+  same_site: 'strict'          // same-site policy
+});
+
+// Custom storage (optional)
+const customStore = new Store('custom_prefix');
+session.init(customStore);
+```
+
+## API Documentation
+
+### Session Class
+
+#### Constructor
+
+```javascript
+new Session(config)
+```
+
+**Parameters:**
+- `config` (Object) - Configuration object
+  - `key` (String) - Session cookie name, default: 'mm:uuid'
+  - `max_age` (Number) - Session expiration time (seconds)
+  - Other cookie configuration options
+
+#### Methods
+
+##### middleware()
+Returns Koa middleware function.
+
+```javascript
+app.use(session.middleware());
+```
+
+##### init(store)
+Initialize custom storage backend.
+
+```javascript
+session.init(new CustomStore());
+```
+
+### Store Class
+
+Storage abstraction class supporting custom storage implementations.
+
+```javascript
+const { Store } = require('mm_session');
+const store = new Store('prefix_');
+```
+
+## Configuration Options
+
+### Session Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| key | String | 'mm:uuid' | Session cookie name |
+| max_age | Number | - | Session expiration time (seconds) |
+| http_only | Boolean | true | HTTP-only access |
+| secure | Boolean | false | HTTPS-only transmission |
+| same_site | String | 'lax' | Same-site policy |
+
+### Cookie Configuration
+
+Supports all [cookie](https://github.com/jshttp/cookie) library configuration options.
+
+## Storage Backends
+
+### Default Storage
+Uses `mm_cachebase` as the default storage backend, supporting both memory and file persistence.
+
+### Custom Storage
+You can implement custom storage classes by implementing the following interface:
+
+```javascript
+class CustomStore {
+  async get(sessionId) {}
+  async set(sessionData, options, ctx) {}
+  async destroy(sessionId, ctx) {}
+  async getID(ctx) {}
+}
+```
+
+## Example Applications
+
+### User Login System
+
+```javascript
+const session = new Session({
+  key: 'user_session',
+  max_age: 86400 // 24 hours
+});
+
+app.use(session.middleware());
+
+// Login route
+app.use(async (ctx, next) => {
+  if (ctx.path === '/login' && ctx.method === 'POST') {
+    const { username, password } = ctx.request.body;
+    
+    // User authentication (example)
+    if (username === 'admin' && password === 'password') {
+      ctx.session.user = {
+        id: 1,
+        username: 'admin',
+        role: 'administrator'
+      };
+      ctx.body = { success: true };
+    } else {
+      ctx.body = { success: false, error: 'Authentication failed' };
+    }
+  } else {
+    await next();
+  }
+});
+
+// Routes requiring authentication
+app.use(async (ctx, next) => {
+  if (!ctx.session.user) {
+    ctx.status = 401;
+    ctx.body = { error: 'Please login first' };
+    return;
+  }
+  await next();
+});
+```
+
+## Testing
+
+```bash
+# Run tests
+npm test
+
+# Or run directly
+node test.js
+```
+
+## Development
+
+### Code Style
+
+The project uses ESLint for code style checking:
+
+```bash
+# Check code style
+npx eslint lib/session.js
+
+# Auto-fix issues
+npx eslint lib/session.js --fix
+```
+
+### Project Structure
+
+```
+mm_session/
+├── lib/
+│   ├── session.js     # Session class implementation
+│   └── store.js       # Store class implementation
+├── index.js           # Module entry point
+├── test.js            # Test file
+├── eslint.config.js   # ESLint configuration
+└── package.json       # Project configuration
+```
+
+## Contributing
+
+We welcome contributions! Please feel free to submit issues and pull requests.
+
+### Development Setup
+
+1. Clone the repository:
+```bash
+git clone https://gitee.com/qiuwenwu91/mm_session.git
+cd mm_session
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Run tests:
+```bash
+npm test
+```
+
+## License
+
+ISC License
+
+Copyright (c) 2024 Qiu Wenwu
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+## Author
+
+Qiu Wenwu
+
+## Changelog
+
+### v1.5.3
+- Current stable version
+
+### v1.5.1
+- Fixed session saving logic
+- Optimized cookie setting mechanism
+- Improved test cases
+
+### v1.5.0
+- Refactored to class + prototype function pattern
+- Compatible with Koa middleware standard usage
+- Enhanced code maintainability
+
+## Bug Reports
+
+If you encounter any bugs or have feature requests, please file an issue on the [Git repository](https://gitee.com/qiuwenwu91/mm_session/issues).
+
+## Related Projects
+
+- [mm_cache](https://www.npmjs.com/package/mm_cache) - Cache library (dependency)
+- [mm_eslint](https://www.npmjs.com/package/mm_eslint) - ESLint configuration (dev dependency)
+
+## Support
+
+For support and questions, please check the documentation or create an issue on the project repository.

package/eslint.config.js

@@ -27,13 +27,13 @@ module.exports = [
     rules: {
       // 自定义命名规范插件规则（优先使用）
       'naming-convention/class-name': 'error',
-      'naming-convention/function-name': 'off', // 禁用函数命名规则，私有方法以下划线开头
+      'naming-convention/function-name': 'error', // 启用函数命名规则
       'naming-convention/method-name': 'error',
       'naming-convention/variable-name': 'warn',
       'naming-convention/constant-name': 'error',
       'naming-convention/private-method-naming': 'warn',
       'naming-convention/private-variable-naming': 'warn',
-      'naming-convention/param-name': 'off', // 禁用入参名规则，私有方法入参以下划线开头
+      'naming-convention/param-name': 'error', // 启用入参名规则
       'naming-convention/property-name': 'warn',
       'naming-convention/instance-property': 'warn',
       
@@ -102,8 +102,7 @@ module.exports = [
     rules: {
       // 必须进行参数校验
       'no-unused-vars': ['error', {
-        args: 'all',
-        argsIgnorePattern: '^_',
+        args: 'none', // 不检查未使用的参数
         caughtErrors: 'all',
         caughtErrorsIgnorePattern: '^_',
         destructuredArrayIgnorePattern: '^_',

package/index.js

@@ -1,10 +1,11 @@
 const { Store } = require('./lib/store.js');
 const { Session } = require('./lib/session.js');
 
-let session = new Session();
-
 module.exports = {
   Session,
   Store,
-  session
+  session: function(config) {
+    let session = new Session(config);
+    return session.middleware();
+  }
 };