wok-server 0.4.13 → 0.6.0

package/documentation/en/validate.md

@@ -0,0 +1,130 @@
+# Validation
+
+The validation component provides a validate function to validate objects with many built-in validation rules. The component supports internationalization, and error messages depend on the current language. See the internationalization section for details.
+
+Here is a simple usage example:
+
+```ts
+validate(
+  // Object to validate
+  { name: 'tom' },
+  // Validation rules, multiple rules per property
+  {
+    name: [notNull(), length({ min: 2, max: 16 })]
+  }
+)
+```
+
+Built-in validation rule functions:
+
+| Function      | Description                                                              |
+| :------------ | :----------------------------------------------------------------------- |
+| notNull       | Not null validation, cannot be null or undefined                         |
+| notBlank      | Not blank validation, cannot be null, undefined, or blank string         |
+| min           | Validate minimum number value                                             |
+| max           | Validate maximum number value                                             |
+| length        | Validate length, applicable to strings and arrays                         |
+| maxLength     | Check maximum length, applicable to strings and arrays                   |
+| minLength     | Check minimum length, applicable to strings and arrays                   |
+| regexp        | Regular expression validation                                             |
+| enumerate     | Enumeration validation, value must be one of the specified list          |
+| array         | Array validation, set element validation rules to validate each element  |
+| plainObject   | Object validation, validate nested object properties                      |
+
+Here is an example of nested object and array validation:
+
+```ts
+interface Tag {
+  id: string
+  name: string
+  permissinos: { edit?: boolean; read?: boolean }
+}
+interface User {
+  profile: {
+    theme: string
+  }
+  tags: Tag[]
+}
+validate<User>(
+  {
+    profile: {
+      theme: 'light'
+    },
+    tags: [
+      { id: '001', name: 'basketball', permissinos: { edit: true, read: true } },
+      { id: '002', name: 'soccer', permissinos: { edit: true } }
+    ]
+  },
+  {
+    profile: [
+      notNull(),
+      plainObject({
+        theme: [notBlank()]
+      })
+    ],
+    tags: [
+      // Maximum 5 tags
+      maxLength(5),
+      // Tags list cannot be null
+      notNull(),
+      // Validate tag array elements
+      array([
+        // Element cannot be null
+        notNull(),
+        // Element property validation
+        plainObject({
+          id: [notBlank()],
+          name: [notBlank()],
+          permissinos: [
+            notNull(),
+            plainObject({
+              edit: [notNull()],
+              read: [notNull()]
+            })
+          ]
+        })
+      ])
+    ]
+  }
+)
+```
+
+In actual development, it's recommended to keep validation at most one level deep, without nesting, otherwise the program will be difficult to maintain.
+
+## Custom Validation Rules
+
+If the built-in validation rules cannot meet your needs, you can write custom validation rules.
+
+```ts
+/**
+ * Custom validation
+ * @returns Property validator
+ */
+function customValidate(): PropValidator {
+  // Validator name for tracking
+  const validator = 'custom'
+  const message = 'Cannot start with t'
+  return val => {
+    // Skip null validation
+    if (!val) {
+      return { ok: true }
+    }
+    if (typeof val !== 'string') {
+      return { ok: false, validator, message: 'Value is not a string' }
+    }
+    if (val.startsWith('t')) {
+      return { ok: false, validator, message }
+    }
+    return { ok: true }
+  }
+}
+
+validate(
+  { name: 'tim' },
+  {
+    name: [customValidate()]
+  }
+)
+```
+
+Built-in validation rules have internationalization support. If you need internationalization for custom validation rules, you need to handle it yourself. See the internationalization chapter for details.

package/documentation/zh-cn/engineering.md

@@ -204,7 +204,7 @@ user/create-user.ts 示例：
 
 ```ts
 import { createJsonHandler, getMysqlManager, notBlank, length } from 'wok-server'
-import { User, tableUser } from './user.ts'
+import { User, tableUser } from './user'
 
 /**
  * 请求发送的表单信息

package/documentation/zh-cn/log.md

@@ -4,12 +4,15 @@
 
 ## 环境变量
 
-| 环境变量名称      | 默认值 | 说明                                                                     |
-| :---------------- | :----- | :----------------------------------------------------------------------- |
-| LOG_LEVEL         | info   | 日志级别，低于设定级别的日志将不会输出，取值：DEBUG，INFO，WARN,ERROR    |
-| LOG_FILE          | false  | 取值 true 或 false ，表示是否开启文件                                    |
-| LOG_FILE_MAX_DAYS | 30     | 数文件的保留天数                                                         |
-| LOG_FILE_DIR      | logs   | 日志文件存储路径，支持相对路径和绝对路径，相对路径是相对于进程执行目录的 |
+| 环境变量名称      | 默认值 | 说明                                                                              |
+| :---------------- | :----- | :-------------------------------------------------------------------------------- |
+| LOG_LEVEL         | info   | 日志级别，低于设定级别的日志将不会输出，取值：DEBUG，INFO，WARN,ERROR             |
+| LOG_FILE          | false  | 取值 true 或 false ，表示是否开启文件                                             |
+| LOG_FILE_MAX_DAYS | 30     | 数文件的保留天数                                                                  |
+| LOG_FILE_DIR      | logs   | 日志文件存储路径，支持相对路径和绝对路径，相对路径是相对于进程执行目录的          |
+| LOG_CONSOLE       | true   | 是否输出日志到控制台,0.5 版本新增加                                               |
+| LOG_FORMAT        | text   | 输出日志的格式，可设置为 json 或 text, 0.5 版本新增加，注意控制台是强制输出文本的 |
+
 
 ## 使用
 
@@ -24,17 +27,87 @@ const err = new Error('错误信息测试')
 logger.error('错误日志输出信息', err)
 
 if (logger.isDebugEnabled()) {
-  logger.debug('调试日志输出', JSON.stringify(args))
+  logger.debug(`调试日志输出, args: ${JSON.stringify(args)}`)
+}
+```
+
+## 判定是否支持某个日志级别
+
+日志对象提供了 isDebugEnabled、isInfoEnabled、isWarnEnabled、isErrorEnabled 方法来判定是否支持某个日志级别。
+
+```ts
+if (logger.isDebugEnabled()) {
+  logger.debug('调试日志输出')
 }
 ```
 
+这些方法的作用是判断当前是否支持某个级别，然后再做处理，如果不支持就不构建日志内容。
+一些情况下，可以避免构建日志信息所带来的不必要的开销。
+
+## 给日志增加前缀
+
+0.5 版本开始，getLogger 函数支持增加前缀，比如：
+
+```ts
+const logger = getLogger('my-module')
+```
+
+这样输出的日志会增加前缀 `[my-module]`，方便区分不同模块的日志。
+
+例如，默认无前缀的日志是这样的：
+
+```
+[2024/08/19 16:27:18.214][INFO]Mysql migration
+```
+
+增加前缀后是这样的：
+
+```
+[2024/08/19 16:27:18.214][INFO][my-module]Mysql migration
+```
+
+
 ## 自定义日志存储
 
 通过函数 setLogStore 可以自定义日志的存储，一旦设置，将会覆盖掉文件存储，即使设置了开启文件，日志也不会输出到文件中。
 
+从 0.5 版本开始，日志做了结构化，存储函数的参数是日志对象和配置信息，而不是一个字符串了。
+
+
 ```ts
-setLogStore(log => {
+setLogStore((log: Log, config: LogConfig) => {
+  // log 的类型是 Log
+  // config 的类型是 LogConfig
   // 可以根据需要将日志内容放入消息队列或独立的文件存储系统中
   messageQueue.push(log)
 })
 ```
+
+Log 的定义如下：
+
+```ts
+export interface Log {
+  /**
+   * 日志的时间
+   */
+  time: Date
+  /**
+   * 日志的等级
+   */
+  level: LogLevel
+  /**
+   * 日志的内容
+   */
+  content: string
+  /**
+   * 异常信息
+   */
+  error?: any
+  /**
+   * 前缀信息
+   */
+  prefix?: string
+}
+```
+
+LogConfig 类型则是包含了前面的环境变量配置信息，用于获取配置信息来决定如何处理日志。

package/documentation/zh-cn/mvc.md

@@ -632,36 +632,78 @@ await startWebServer({
 
 ### Server-Sent Events
 
-组件本身没有直接提供对 SSE（Server-Sent Events） 的支持，可以在路由的处理函数中适当的进行处理来实现。
+从 0.6.0 版本开始，MVC 组件内置了 `createSseHandler`，封装了 SSE 协议细节，大幅简化服务端推送实现。
 
 ```ts
-// 启动服务
+import { createSseHandler } from 'wok-server'
+
 await startWebServer({
-  // 路由配置
   routers: {
-    '/sse': async exchange => {
-      const { response } = exchange
-      // 设置消息头
-      response.setHeader('Content-Type', 'text/event-stream')
-      response.setHeader('Cache-Control', 'no-cache')
-      response.setHeader('Connection', 'keep-alive')
-      // 模拟异步操作更新多条消息
-      let counter = 0
-      for (let i = 0; i < 10; i++) {
-        // 沉睡一秒，模拟异步业务处理
-        await new Promise<void>((resolve, reject) => {
-          setTimeout(resolve, 1000)
-        })
-        counter++
-        // 写数据到响应信息中，前端在 EventSource 的 message 事件中处理
-        response.write(`data: ${JSON.stringify({ message: '实时更新', count: counter })}\n\n`)
-        if (counter >= 10) {
-          break
+    '/sse': createSseHandler({
+      async handle(ctx) {
+        let counter = 0
+        for (let i = 0; i < 10; i++) {
+          await new Promise<void>(resolve => setTimeout(resolve, 1000))
+          counter++
+          ctx.send({ message: '实时更新', count: counter })
+          if (counter >= 10) {
+            break
+          }
         }
+        ctx.close()
       }
-      // 最后结束响应
-      response.end()
-    }
+    })
+  }
+})
+```
+
+`handle` 函数接收一个 `SseContext` 对象，提供以下能力：
+
+| 方法/属性                                 | 说明                                                         |
+| :---------------------------------------- | :----------------------------------------------------------- |
+| `ctx.send(data, event?, id?)`            | 发送 SSE 事件，`data` 会被 JSON 序列化。`event` 指定事件名（前端用 `addEventListener` 监听），`id` 设置事件 ID（用于断线重连的 `Last-Event-ID`） |
+| `ctx.close()`                             | 显式结束 SSE 连接。`handle` 返回或抛异常时连接也会自动关闭   |
+| `ctx.request`                             | 原始 `IncomingMessage`，可读取请求头等信息                   |
+| `ctx.response`                            | 原始 `ServerResponse`，高级场景下使用                         |
+
+#### 命名事件
+
+通过 `event` 参数发送命名事件，前端可按事件类型分别处理：
+
+```ts
+createSseHandler({
+  async handle(ctx) {
+    ctx.send({ title: '新消息' }, 'notification')
+    ctx.send({ progress: 50 }, 'progress')
   }
 })
 ```
+
+前端：
+
+```ts
+const es = new EventSource('/sse')
+es.addEventListener('notification', e => {
+  const data = JSON.parse(e.data)
+  console.log('收到通知：', data.title)
+})
+```
+
+#### 断线重连
+
+通过 `id` 参数设置事件 ID，前端断线重连时浏览器会自动发送 `Last-Event-ID` 请求头：
+
+```ts
+createSseHandler({
+  async handle(ctx) {
+    const lastId = ctx.request.headers['last-event-id']
+    // 根据 lastId 确定从何处恢复推送
+  }
+})
+```
+
+#### 连接生命周期
+
+- `handle` 开始执行时，SSE 消息头已发送，连接已建立
+- 客户端断开连接时，`ctx.send()` 调用变为空操作（自动忽略）
+- `handle` 返回或抛异常时，连接自动关闭

package/documentation/zh-cn/mysql.md

@@ -29,7 +29,7 @@ mysql 组件基于 [mysql2](https://www.npmjs.com/package/mysql2) 封装，提
 | MYSQL_SLOW_SQL_MS             | 慢 sql 毫秒数，默认 200                               |
 | MYSQL_TRANSACTION_TIMEOUT     | 事务超时时间，单位毫秒，默认 5000                     |
 | MYSQL_TRANSACTION_STRICT      | 事务严格模式，默认 true，设置为 false 可关闭严格模式  |
-| MYSQL_MAX_OPS_IN_STRICT_TX    | 严格事务中可以执行的操作次数，默认 10  |
+| MYSQL_MAX_OPS_IN_STRICT_TX    | 严格事务中可以执行的操作次数，默认 10                 |
 
 ## 初始化
 
@@ -48,7 +48,7 @@ await enableMysql()
 await enableMysql('d2')
 ```
 
-上传的操作要激活 mysql 　时，会自动映射以 `D2_` 为前缀的环境变量。
+执行上面的操作后，会自动映射以 `D2_` 为前缀的环境变量。
 
 下面是多数据源的环境变量示例：
 
@@ -284,27 +284,28 @@ await manager.modify(`update user set nickname='无名' where nickname='佚名'`
 
 ### 所有操作方法
 
-| 方法          | 功能说明                                                                    |
-| :------------ | :-------------------------------------------------------------------------- |
-| findById      | 按 id 查询                                                                  |
-| findByIdIn    | 按 id 列表查询多条记录                                                      |
-| existsBy      | 判定指定的条件是否存在记录                                                  |
-| existsById    | 判定 id 是否存在                                                            |
-| deleteById    | 按 id 删除                                                                  |
-| deleteMany    | 按指定条件删除，危险操作，建议尽可能设置 limit 参数来限制数量               |
-| findAll       | 查询表下所有记录，危险操作，建议只对数据量非常小的表使用                    |
-| findFirst     | 查询符合条件的第一条记录                                                    |
-| insert        | 插入记录                                                                    |
-| insertMany    | 一次性插入多条记录                                                          |
-| update        | 更新记录，需要完整信息                                                      |
-| partialUpdate | 局部更新，只提供 id 和需要更新的字段信息                                    |
-| updateOne     | 只更新指定条件的第一条记录，必须是相等条件，不支持范围条件                  |
-| updateMany    | 更新所有符合条件的记录，危险操作，建议对条件严加限制，控制受影响的范围      |
-| find          | 按条件查询所有符合条件的记录，危险操作，建议尽可能设置 limit 参数来限制数量 |
-| count         | 统计符合条件的记录数量，危险操作，建议严格限制条件，注意索引的利用          |
-| paginate      | 分页查询 ，危险操作，基于 find 和 count                                     |
-| query         | 自定义 sql 查询，返回记录列表，支持预编译 sql                               |
-| modify        | 执行自定义 sql，返回操作记录数 ，支持预编译 sql                             |
+| 方法          | 功能说明                                                                            |
+| :------------ | :---------------------------------------------------------------------------------- |
+| findById      | 按 id 查询                                                                          |
+| findByIdIn    | 按 id 列表查询多条记录                                                              |
+| existsBy      | 判定指定的条件是否存在记录                                                          |
+| existsById    | 判定 id 是否存在                                                                    |
+| deleteById    | 按 id 删除                                                                          |
+| deleteMany    | 按指定条件删除，危险操作，建议尽可能设置 limit 参数来限制数量                       |
+| findAll       | 查询表下所有记录，危险操作，建议只对数据量非常小的表使用                            |
+| findFirst     | 查询符合条件的第一条记录                                                            |
+| insert        | 插入记录                                                                            |
+| insertMany    | 一次性插入多条记录                                                                  |
+| update        | 更新记录，需要完整信息                                                              |
+| partialUpdate | 局部更新，只提供 id 和需要更新的字段信息                                            |
+| updateOne     | 只更新指定条件的第一条记录，必须是相等条件，不支持范围条件                          |
+| updateMany    | 更新所有符合条件的记录，危险操作，建议对条件严加限制，控制受影响的范围              |
+| find          | 按条件查询所有符合条件的记录，危险操作，建议尽可能设置 limit 参数来限制数量         |
+| findSelect    | 指定字段进行条件查询,与 find 唯一的不同的是多一个参数 select 可以用来指定要返回的列 |
+| count         | 统计符合条件的记录数量，危险操作，建议严格限制条件，注意索引的利用                  |
+| paginate      | 分页查询 ，危险操作，基于 find 和 count                                             |
+| query         | 自定义 sql 查询，返回记录列表，支持预编译 sql                                       |
+| modify        | 执行自定义 sql，返回操作记录数 ，支持预编译 sql                                     |
 
 ### json 类型
 

package/documentation/zh-cn/validate.md

@@ -20,8 +20,8 @@ validate(
 
 | 函数        | 作用                                                 |
 | :---------- | :--------------------------------------------------- |
-| notNull     | 非空校验，不能是 null 或 undefinded                  |
-| notBlank    | 字符非空校验，不能是 null 或 undefinded 或空白字符串 |
+| notNull     | 非空校验，不能是 null 或 undefined                    |
+| notBlank    | 字符非空校验，不能是 null 或 undefined 或空白字符串 |
 | min         | 校验数字最小值                                       |
 | max         | 校验数字最大值                                       |
 | length      | 校验长度，适用于字符串和数组                         |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wok-server",
-  "version": "0.4.13",
+  "version": "0.6.0",
   "packageManager": "pnpm@8.9.0",
   "description": "一个基于 NodeJs 和 TypeScript 的后端框架，轻量级、克制、简洁。A lightweight, restrained, and concise backend framework based on Node.js and TypeScript.",
   "scripts": {
@@ -19,6 +19,8 @@
     "dist/",
     "docs/",
     "documentation/",
+    "skills/",
+    "src/",
     "README.md"
   ],
   "author": "peak",