@thinkbun/middleware 1.0.3 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @thinkbun/middleware
 
+## 1.0.4
+
+### Patch Changes
+
+- docs
+- Updated dependencies
+  - @thinkbun/core@1.0.7
+
 ## 1.0.3
 
 ### Patch Changes

package/README.md

@@ -78,81 +78,7 @@ app.use(logger({
 | `logger`      | `(message: string) => void` | `console.log` | Custom logger function                 |
 | `ignorePaths` | `string[]`                  | `[]`          | Array of paths to exclude from logging |
 
-### 3. Validator
-
-Request parameter validation middleware that validates request body, query parameters, and route parameters using Ajv schema validation.
-
-#### Usage
-
-```typescript
-import { validator } from '@thinkbun/middleware';
-
-app.use(validator({
-  rules: [
-    {
-      path: '/api/users',
-      method: 'POST',
-      schema: {
-        body: {
-          type: 'object',
-          properties: {
-            name: { type: 'string' },
-            email: { type: 'string', format: 'email' },
-            age: { type: 'number', minimum: 18 }
-          },
-          required: ['name', 'email']
-        },
-        query: {
-          type: 'object',
-          properties: {
-            active: { type: 'boolean' }
-          }
-        }
-      }
-    },
-    {
-      path: '/api/users/:id',
-      method: 'GET',
-      schema: {
-        params: {
-          type: 'object',
-          properties: {
-            id: { type: 'string', pattern: '^\\d+$' }
-          },
-          required: ['id']
-        }
-      }
-    }
-  ],
-  errorHandler: (errors, ctx) => {
-    // Custom validation error handling
-    ctx.throw(400, `Validation error: ${errors[0].message}`);
-  }
-}));
-```
-
-#### Options
-
-| Option         | Type                                    | Default | Description                               |
-| -------------- | --------------------------------------- | ------- | ----------------------------------------- |
-| `rules`        | `ValidationRule[]`                      | -       | Array of validation rules                 |
-| `errorHandler` | `(errors: any[], ctx: Context) => void` | -       | Custom validation error handling function |
-
-#### ValidationRule Interface
-
-```typescript
-interface ValidationRule {
-  path: string;           // Request path pattern to match
-  method: string;         // HTTP method to match (GET, POST, etc.)
-  schema: {
-    body?: any;          // Request body schema
-    query?: any;         // Query parameters schema
-    params?: any;        // Route parameters schema
-  };
-}
-```
-
-### 4. CORS
+### 3. CORS
 
 CORS configuration middleware that handles Cross-Origin Resource Sharing, supporting flexible configuration options.
 
@@ -188,9 +114,9 @@ app.use(cors({
 | `maxAge`            | `number`                                              | `86400` (24 hours)                                  | Preflight request cache time (seconds)                                     |
 | `preflightContinue` | `boolean`                                             | `true`                                              | Whether to continue processing preflight requests                          |
 
-### 5. Static Serve
+### 4. Static Serve
 
-Static file serving middleware that serves static files from the specified directory, with support for request path prefixes, cache control, and more.
+Static file serving middleware that serves static files from specified directory, with support for request path prefixes, cache control, and more.
 
 #### Usage
 
@@ -215,10 +141,10 @@ app.use(staticServe({
 #### Options
 
 | Option         | Type      | Default        | Description                      |
-| -------------- | --------- | -------------- | -------------------------------- |
-| `root`         | `string`  | -              | Static file directory (required) |
-| `prefix`       | `string`  | `''`           | Request path prefix              |
-| `index`        | `string`  | `'index.html'` | Default index file               |
+| -------------- | --------- | -------------- | ------------------------- |
+| `root`        | `string`  | -              | Static file directory (required) |
+| `prefix`      | `string`  | `''`           | Request path prefix              |
+| `index`       | `string`  | `'index.html'` | Default index file               |
 | `maxAge`       | `number`  | `3600`         | Cache control max-age (seconds)  |
 | `gzip`         | `boolean` | `true`         | Enable gzip compression          |
 | `brotli`       | `boolean` | `true`         | Enable Brotli compression        |
@@ -240,7 +166,7 @@ app.use(middlewares.staticServe({ root: './public' }));
 
 ## Middleware Execution Flow
 
-The middleware follows the Koa onion model, where each middleware can execute code before and after subsequent middleware:
+The middleware follows Koa onion model, where each middleware can execute code before and after subsequent middleware:
 
 ```typescript
 app.use(async (ctx, next) => {
@@ -275,11 +201,11 @@ app.use(async (ctx, next) => {
 
 ## Best Practices
 
-1. **Order Matters**: Middleware execution follows the order in which they are added with `app.use()`. Place global middleware (like error handler, logger, CORS) before route-specific middleware.
+1. **Order Matters**: Middleware execution follows order in which they are added with `app.use()`. Place global middleware (like error handler, logger, CORS) before route-specific middleware.
 
 2. **Error Handler Placement**: Always place the error handler middleware first to ensure it can capture errors from all subsequent middleware.
 
-3. **Static Files**: Place the static file serving middleware before route handlers to improve performance (static files are served directly without going through route processing).
+3. **Static Files**: Place static file serving middleware before route handlers to improve performance (static files are served directly without going through route processing).
 
 4. **Validation Scope**: Use the validator middleware with specific paths and methods to avoid unnecessary validation overhead.
 

package/README_CN.md

@@ -0,0 +1,290 @@
+# ThinkBun 中间件集合
+
+为 ThinkBun 框架提供的全面中间件集合，遵循 Koa 中间件规范，支持 async/await 语法和洋葱模型执行流程。
+
+## 安装
+
+```bash
+bun add @thinkbun/middleware
+```
+
+## 可用中间件
+
+### 1. 错误处理器
+
+全局错误处理中间件，捕获并处理后续中间件抛出的错误，支持在开发和生产环境中显示不同的错误信息。
+
+#### 使用方法
+
+```typescript
+import { errorHandler } from '@thinkbun/middleware';
+
+// 基本使用
+app.use(errorHandler());
+
+// 使用自定义选项
+app.use(errorHandler({
+  exposeStackTrace: true, // 在错误响应中显示堆栈跟踪（仅建议在开发环境使用）
+  customHandler: (error, ctx) => {
+    // 自定义错误处理逻辑
+    return new Response(JSON.stringify({ error: error.message }), {
+      status: (error as any).status || 500,
+      headers: { 'Content-Type': 'application/json' }
+    });
+  },
+  logger: (error) => {
+    // 自定义错误日志记录
+    console.error('Error occurred:', error);
+  }
+}));
+```
+
+#### 选项
+
+| 选项              | 类型                                       | 默认值  | 描述                                   |
+| ----------------- | ------------------------------------------ | ------- | -------------------------------------- |
+| `exposeStackTrace` | `boolean`                                  | `false` | 是否在错误响应中暴露堆栈跟踪         |
+| `customHandler`    | `(error: Error, ctx: Context) => Response` | -       | 自定义错误处理函数                      |
+| `logger`           | `(error: Error, ctx: Context) => void`     | -       | 自定义错误日志记录函数                  |
+
+### 2. 日志记录器
+
+请求日志记录中间件，记录请求和响应信息，支持自定义日志格式、路径过滤和日志记录器。
+
+#### 使用方法
+
+```typescript
+import { logger } from '@thinkbun/middleware';
+
+// 基本使用
+app.use(logger());
+
+// 使用自定义选项
+app.use(logger({
+  format: (ctx) => `${ctx.method} ${ctx.path} ${ctx.header('user-agent')}`,
+  logger: (message) => {
+    // 自定义日志记录
+    console.log('[LOG]', message);
+  },
+  ignorePaths: ['/health', '/metrics'] // 从日志中排除的路径
+}));
+```
+
+#### 选项
+
+| 选项         | 类型                        | 默认值       | 描述                      |
+| ------------ | --------------------------- | ------------- | ------------------------- |
+| `format`     | `(ctx: Context) => string`  | -             | 自定义日志格式函数         |
+| `logger`     | `(message: string) => void` | `console.log` | 自定义日志记录函数         |
+| `ignorePaths`| `string[]`                  | `[]`          | 从日志中排除的路径数组    |
+
+### 3. 验证器
+
+请求参数验证中间件，使用 Ajv 模式验证验证请求体、查询参数和路由参数。
+
+#### 使用方法
+
+```typescript
+import { validator } from '@thinkbun/middleware';
+
+app.use(validator({
+  rules: [
+    {
+      path: '/api/users',
+      method: 'POST',
+      schema: {
+        body: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            email: { type: 'string', format: 'email' },
+            age: { type: 'number', minimum: 18 }
+          },
+          required: ['name', 'email']
+        },
+        query: {
+          type: 'object',
+          properties: {
+            active: { type: 'boolean' }
+          }
+        }
+      }
+    },
+    {
+      path: '/api/users/:id',
+      method: 'GET',
+      schema: {
+        params: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', pattern: '^\\d+$' }
+          },
+          required: ['id']
+        }
+      }
+    }
+  ],
+  errorHandler: (errors, ctx) => {
+    // 自定义验证错误处理
+    ctx.throw(400, `Validation error: ${errors[0].message}`);
+  }
+}));
+```
+
+#### 选项
+
+| 选项           | 类型                                    | 默认值 | 描述                               |
+| -------------- | --------------------------------------- | ------- | ----------------------------------- |
+| `rules`        | `ValidationRule[]`                      | -       | 验证规则数组                         |
+| `errorHandler` | `(errors: any[], ctx: Context) => void` | -       | 自定义验证错误处理函数                |
+
+#### ValidationRule 接口
+
+```typescript
+interface ValidationRule {
+  path: string;           // 要匹配的请求路径模式
+  method: string;         // 要匹配的 HTTP 方法（GET、POST 等）
+  schema: {
+    body?: any;          // 请求体模式
+    query?: any;         // 查询参数模式
+    params?: any;        // 路由参数模式
+  };
+}
+```
+
+### 4. CORS
+
+CORS 配置中间件，处理跨源资源共享，支持灵活的配置选项。
+
+#### 使用方法
+
+```typescript
+import { cors } from '@thinkbun/middleware';
+
+// 基本使用（默认允许所有源）
+app.use(cors());
+
+// 使用自定义选项
+app.use(cors({
+  origin: ['https://example.com', 'https://sub.example.com'], // 允许特定源
+  methods: ['GET', 'POST', 'PUT', 'DELETE'],                // 允许的 HTTP 方法
+  allowedHeaders: ['Content-Type', 'Authorization'],        // 允许的请求头
+  exposedHeaders: ['X-Custom-Header'],                      // 暴露给客户端的响应头
+  credentials: true,                                        // 允许凭据
+  maxAge: 86400,                                            // 预检请求缓存时间（秒）
+  preflightContinue: true                                  // 继续处理预检请求
+}));
+```
+
+#### 选项
+
+| 选项              | 类型                                                  | 默认值                                                 | 描述                                                                |
+| ----------------- | ----------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------- |
+| `origin`          | `string \| string[] \| ((origin: string) => boolean)` | `'*'`                                                   | 允许的源                                                          |
+| `methods`         | `string[]`                                            | `['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH']` | 允许的 HTTP 方法                                                     |
+| `allowedHeaders`  | `string[]`                                            | -                                                        | 允许的请求头（默认为 Access-Control-Request-Headers 的值）           |
+| `exposedHeaders`  | `string[]`                                            | -                                                        | 暴露给客户端的响应头                                              |
+| `credentials`     | `boolean`                                             | `false`                                                  | 是否允许凭据                                                       |
+| `maxAge`          | `number`                                              | `86400` (24 小时)                                        | 预检请求缓存时间（秒）                                               |
+| `preflightContinue` | `boolean`                                             | `true`                                                   | 是否继续处理预检请求                                              |
+
+### 5. 静态文件服务
+
+静态文件服务中间件，从指定目录服务静态文件，支持请求路径前缀、缓存控制等功能。
+
+#### 使用方法
+
+```typescript
+import { staticServe } from '@thinkbun/middleware';
+
+// 基本使用
+app.use(staticServe({ root: './public' }));
+
+// 使用自定义选项
+app.use(staticServe({
+  root: './public',        // 静态文件目录
+  prefix: '/static',       // 请求路径前缀（例如 /static/css/style.css）
+  index: 'index.html',     // 默认索引文件
+  maxAge: 3600,            // 缓存控制 max-age（秒）
+  gzip: true,              // 启用 gzip 压缩
+  brotli: true,            // 启用 Brotli 压缩
+  cacheControl: true       // 启用缓存控制头
+}));
+```
+
+#### 选项
+
+| 选项          | 类型      | 默认值        | 描述                      |
+| ------------- | --------- | -------------- | ------------------------- |
+| `root`        | `string`  | -              | 静态文件目录（必需）      |
+| `prefix`      | `string`  | `''`           | 请求路径前缀              |
+| `index`       | `string`  | `'index.html'` | 默认索引文件              |
+| `maxAge`      | `number`  | `3600`         | 缓存控制 max-age（秒）     |
+| `gzip`        | `boolean` | `true`         | 启用 gzip 压缩          |
+| `brotli`      | `boolean` | `true`         | 启用 Brotli 压缩        |
+| `cacheControl` | `boolean` | `true`         | 启用缓存控制头         |
+
+## 使用所有中间件
+
+您也可以一次性导入所有中间件：
+
+```typescript
+import { middlewares } from '@thinkbun/middleware';
+
+// 使用所有中间件
+app.use(middlewares.errorHandler());
+app.use(middlewares.logger());
+app.use(middlewares.cors());
+app.use(middlewares.staticServe({ root: './public' }));
+```
+
+## 中间件执行流程
+
+中间件遵循 Koa 洋葱模型，每个中间件可以在后续中间件之前和之后执行代码：
+
+```typescript
+app.use(async (ctx, next) => {
+  // 在下一个中间件之前执行的代码
+  console.log('中间件 1: 之前');
+
+  const response = await next();
+
+  // 在下一个中间件之后执行的代码
+  console.log('中间件 1: 之后');
+
+  return response;
+});
+
+app.use(async (ctx, next) => {
+  console.log('中间件 2: 之前');
+
+  const response = await next();
+
+  console.log('中间件 2: 之后');
+
+  return response;
+});
+
+// 处理请求时的输出：
+// 中间件 1: 之前
+// 中间件 2: 之前
+// (请求处理)
+// 中间件 2: 之后
+// 中间件 1: 之后
+```
+
+## 最佳实践
+
+1. **顺序很重要**：中间件执行遵循使用 `app.use()` 添加时的顺序。将全局中间件（如错误处理器、日志、CORS）放在特定于路由的中间件之前。
+
+2. **错误处理器位置**：始终将错误处理中间件放在第一位，以确保它可以捕获所有后续中间件的错误。
+
+3. **静态文件**：将静态文件服务中间件放在路由处理器之前，以提高性能（静态文件直接提供服务，无需经过路由处理）。
+
+4. **验证范围**：将验证器中间件与特定路径和方法一起使用，以避免不必要的验证开销。
+
+5. **环境特定配置**：为开发和生产环境配置不同的中间件（例如，仅在开发环境中暴露堆栈跟踪）。
+
+## 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkbun/middleware",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "module": "src/index.ts",
   "type": "module",
   "devDependencies": {
@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "picocolors": "^1.1.1",
-    "@thinkbun/core": "1.0.4"
+    "@thinkbun/core": "1.0.6"
   },
   "publishConfig": {
     "access": "public"