wok-server 0.5.0 → 0.7.0

package/documentation/en/task.md

@@ -0,0 +1,45 @@
+# Task Scheduling
+
+Task scheduling provides functionality to initiate periodic tasks, meeting basic needs.
+
+## Environment Variables
+
+| Function Name            | Description                                                                 |
+| :----------------------- | :-------------------------------------------------------------------------- |
+| scheduleWithFixedRate    | Execute task at fixed rate                                                  |
+| scheduleWithFixedDelay   | Execute task with fixed delay, i.e., wait for specified interval after each task completion |
+| scheduleDailyTask        | Execute task at fixed time daily                                            |
+
+## Usage Examples
+
+```ts
+// Start a fixed delay task, first execution after 10 seconds, then every minute
+const controller = scheduleWithFixedDelay(10, 60, {
+  name: 'Record online users',
+  async run() {
+    const count = await countAuth()
+    await createPcu({
+      count,
+      time: new Date()
+    })
+  }
+})
+// Stop the task when necessary through the returned controller
+controller.stop()
+```
+
+The scheduleWithFixedRate function has the same parameters as scheduleWithFixedDelay. The difference is that scheduleWithFixedRate uses the task start time as the cycle, and the interval between each task's start time is consistent. If the task execution time exceeds the cycle, the next task will execute immediately. scheduleWithFixedDelay waits for the specified interval after each task completes before executing the next one.
+
+```ts
+// Start a task that runs daily at 1:30
+const controller = scheduleDailyTask(1, 30, {
+  name: 'Study report',
+  async run() {
+    // Logic omitted
+  }
+})
+```
+
+## Difference from Built-in Timers
+
+If requirements are not high, you can also use Node.js's built-in setTimeout and setInterval for periodic tasks. The task component is more convenient to use, with commonly used functions already encapsulated, and the run method is an async function. It automatically records task start time and exception information, and logs execution time for long-running tasks.

package/documentation/en/test.md

@@ -0,0 +1,56 @@
+# Unit Testing
+
+To run the project's unit tests, you need to start the database services first, then run the tests.
+
+## Start Database Services
+
+The project source code provides scripts to start local database services for testing. The services need to run in Docker, so you must install docker-desktop locally first. Docker installation is not covered here; you can visit the official website for documentation.
+
+First, start the MySQL service. This is simple - run docker-mysql.bat or docker-mysql.sh in the script directory.
+
+```
+./script/docker-mysql.sh
+```
+
+Then start the MongoDB service for testing. Run docker-mongo.bat or docker-mongo.sh in the script directory.
+
+```
+./script/docker-mongo.sh
+```
+
+Starting MongoDB alone is not sufficient. The service must be configured as a replica set to support transactions.
+
+Run mongosh in the MongoDB container:
+
+```
+docker exec -it mongo_test mongosh
+```
+
+In mongosh, execute the following script to initialize as a replica set:
+
+```js
+rs.initiate({
+  _id: 'rs0',
+  members: [{ _id: 0, host: '127.0.0.1:27017' }]
+})
+```
+
+Create a test user:
+
+```js
+db.createUser({
+  user: 'test',
+  pwd: 'abc123',
+  roles: [{ role: 'readWrite', db: 'test' }]
+})
+```
+
+After completing the above steps, the MongoDB service is ready for testing.
+
+## Run Tests
+
+Run the following script in the project root directory:
+
+```
+npm run test
+```

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/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

@@ -228,12 +228,32 @@ await manager.insert(tableUser, {
   nickname: '小明',
   balance: 1
 })
+// 插入时使用表达式
+await manager.insert(tableUser, {
+  id: 'in002',
+  nickname: '小红',
+  balance: ['expr', '?? * ?', ['score', 2]],
+  createAt: ['now']
+})
 // 批量插入
 await manager.insertMany(tableUser, [
   { id: 'im001', nickname: '张飞', balance: 0 },
   { id: 'im002', nickname: '关羽', balance: 2 },
   { id: 'im003', nickname: '刘备', balance: 5 }
 ])
+// Upsert 单条，id 冲突则更新
+await manager.upsert(tableUser, { id: 'us001', nickname: '赵云', balance: 10 })
+// Upsert 批量
+await manager.upsertMany(tableUser, [
+  { id: 'us002', nickname: '马超', balance: 20 },
+  { id: 'us003', nickname: '黄忠', balance: 30 }
+])
+// Upsert 单条，冲突时自定义更新（如递增余额）
+await manager.upsertWithUpdater(
+  tableUser,
+  { id: 'us001', nickname: '赵云', balance: 10 },
+  { balance: ['inc', 5], nickname: '赵云-updated' }
+)
 // 根据指定的条件查询第一条符合的记录
 const user = await manager.findFirst(tableUser, c =>
   c.like('nickname', 'ff0%').gt('balance', 75).lt('balance', 77)
@@ -254,6 +274,18 @@ await manager.find({
   limit: 10,
   orderBy: [['balance', 'asc']]
 })
+// 自定义排序表达式：按 balance * 2 降序
+await manager.find({
+  table: tableUser,
+  criteria: c => c.like('nickname', 'ff0%'),
+  orderBy: [['expr', '?? * ?', ['balance', 2], 'desc']]
+})
+// 自定义查询条件表达式：balance * 2 > 50
+await manager.find({
+  table: tableUser,
+  criteria: c => c.like('id', 'critex%').expr('?? * ? > ?', ['balance', 2, 50]),
+  orderBy: [['balance', 'asc']]
+})
 // 统计符合条件的记录数量
 const count = await manager.count(tableUser, c => c.like('id', 'c00%').like('nickname', '李%'))
 // 分页查询
@@ -294,18 +326,99 @@ await manager.modify(`update user set nickname='无名' where nickname='佚名'`
 | 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                                     |
+| insert          | 插入记录                                                                            |
+| insertMany      | 一次性插入多条记录                                                                  |
+| upsert          | 插入记录，主键冲突则更新                                                            |
+| upsertMany      | 批量 upsert                                                                         |
+| upsertWithUpdater | upsert 单条，主键冲突时使用自定义更新器（Updater）                                  |
+| update          | 更新记录，需要完整信息                                                              |
+| partialUpdate   | 局部更新，只提供 id 和需要更新的字段信息                                            |
+| updateOne       | 只更新指定条件的第一条记录，必须是相等条件，不支持范围条件                          |
+| updateMany      | 更新所有符合条件的记录，危险操作，建议对条件严加限制，控制受影响的范围              |
+| find            | 按条件查询所有符合条件的记录，危险操作，建议尽可能设置 limit 参数来限制数量         |
+| findSelect      | 指定字段进行条件查询,与 find 唯一的不同的是多一个参数 select 可以用来指定要返回的列 |
+| count           | 统计符合条件的记录数量，危险操作，建议严格限制条件，注意索引的利用                  |
+| paginate        | 分页查询 ，危险操作，基于 find 和 count                                             |
+| paginateSelect  | 指定字段进行分页查询，在 paginate 基础上增加了 select 参数                          |
+| query           | 自定义 sql 查询，返回记录列表，支持预编译 sql                                       |
+| modify          | 执行自定义 sql，返回操作记录数 ，支持预编译 sql                                     |
+
+### 插入表达式
+
+从 0.7.0 版本开始，`insert`、`insertMany`、`upsert` 等插入方法的 data 参数支持 `InsertValue` 类型，
+可以在 VALUES 子句中使用表达式：
+
+```ts
+await manager.insert(tableUser, {
+  id: 'in001',
+  nickname: '小明',
+  // 设置为 NOW()
+  createAt: ['now'],
+  // 解决冲突：将字段设置为 ['setNull'] 这个数组值（而非执行 setNull 操作）
+  extra: ['set', ['setNull']],
+  // 自定义表达式：balance = score * 2
+  balance: ['expr', '?? * ?', ['score', 2]],
+  // 无参数表达式
+  balance2: ['expr', 'RAND() * 100']
+})
+```
+
+### 排序表达式
+
+从 0.7.0 版本开始，`orderBy` 参数升级为 `OrderBy<T>` 类型，除了普通列排序外，还支持自定义表达式排序。
+该类型向后兼容，原有的列排序写法不受影响：
+
+```ts
+await manager.find({
+  table: tableUser,
+  criteria: c => c.like('nickname', 'ob%'),
+  // 普通列排序（与旧版兼容）
+  orderBy: [['balance', 'asc']]
+})
+
+// 自定义表达式排序：按 balance * 2 降序
+// SQL: ORDER BY `balance` * 2 desc
+await manager.find({
+  table: tableUser,
+  criteria: c => c.like('nickname', 'ob%'),
+  orderBy: [['expr', '?? * ?', ['balance', 2], 'desc']]
+})
+
+// 按名称长度排序：CHAR_LENGTH(name) desc
+// SQL: ORDER BY CHAR_LENGTH(`name`) desc
+await manager.find({
+  table: tableBook,
+  criteria: c => c.like('name', 'ob%'),
+  orderBy: [['expr', 'CHAR_LENGTH(??)', ['name'], 'desc']]
+})
+
+// 混合使用：普通列 + 表达式
+orderBy: [
+  ['active', 'asc'],
+  ['expr', '?? * ?', ['balance', 2], 'desc']
+]
+// SQL: ORDER BY `active` asc , `balance` * 2 desc
+```
+
+### 条件表达式
+
+从 0.7.0 版本开始，`MysqlCriteria` 新增 `expr()` 方法，可在 WHERE 子句中插入自定义 SQL 表达式：
+
+```ts
+// balance * 2 > 50
+// SQL: where ... and `balance` * 2 > 50
+await manager.find({
+  table: tableUser,
+  criteria: c => c.like('id', 'critex%').expr('?? * ? > ?', ['balance', 2, 50])
+})
+
+// 全文搜索
+// SQL: where ... and MATCH(`title`, `content`) AGAINST (? IN BOOLEAN MODE)
+await manager.find({
+  table: tableBook,
+  criteria: c => c.expr('MATCH(??, ??) AGAINST(? IN BOOLEAN MODE)', ['title', 'content', keyword])
+})
+```
 
 ### json 类型
 
@@ -431,24 +544,40 @@ partialUpdate 和 updateMany 方法支持局部修改一些字段，并且支持
 await manager.updateMany(tableUser, c => c.between('balance', 23, 24), {
   // 将 balance 增加 2
   balance: ['inc', 2],
+  // 将 balance 增加 1（省略第二个参数，默认 +1）
+  visits: ['inc'],
   // 将 consume_type 置空
-  consume_type:['setNull']
+  consume_type: ['setNull'],
+  // 设置为 NOW()
+  last_login_at: ['now'],
+  // NULL 安全的字符串追加：col = CONCAT(IFNULL(col, ''), ?)
+  nickname: ['concat', '-suffix'],
+  // 自定义表达式：score = score * 2
+  score: ['expr', '?? * ?', ['score', 2]]
 })
 ```
 
-如果将一个字段的值设置为 null 也可以置空，但是这要求设置 ts 类型支持。
+> **注意**：0.7.0 版本已移除 `['func']`，请使用 `['expr']` 替代。
+> 如 `['func', 'NOW()']` → `['expr', 'NOW()']`。
+
+从 **0.7.0 版本**开始，`null` 和 `undefined` 一样会被忽略更新。**如需将字段设置为 NULL，必须使用 `['setNull']`**。
 
 ```ts
 interface User {
   id: string
-  // 将 role 的类型设置包含 null
   role: string | null
 }
 
+// 正确：使用 ['setNull'] 将字段置空
+await manager.partialUpdate(tableUser, {
+  id: '001',
+  role: ['setNull']
+})
+
+// 错误：0.7.0 版本开始，null 会被忽略，不会更新字段
 await manager.partialUpdate(tableUser, {
   id: '001',
-  // 等同于 role:['setNull']
-  role: null
+  role: null  // 此操作不会生效
 })
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wok-server",
-  "version": "0.5.0",
+  "version": "0.7.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,9 @@
     "dist/",
     "docs/",
     "documentation/",
+    "skills/",
+    "src/",
+    "README.en.md",
     "README.md"
   ],
   "author": "peak",