lakutata 3.0.0-beta.1 → 3.0.0-beta.2

package/doc/en/ActionPattern.md

@@ -205,7 +205,7 @@ the `middlewares` action option.
 import {type ActionInvocation, Controller, type Next} from 'lakutata/com/entrypoint'
 import {GET, UseMiddlewares} from 'lakutata/decorator/ctrl'
 
-async function Timing(invocation: ActionInvocation, next: Next): Promise<unknown> {
+async function timing(invocation: ActionInvocation, next: Next): Promise<unknown> {
     const started: number = Date.now()
     try {
         return await next()
@@ -214,7 +214,7 @@ async function Timing(invocation: ActionInvocation, next: Next): Promise<unknown
     }
 }
 
-@UseMiddlewares(Timing)
+@UseMiddlewares(timing)
 class HealthController extends Controller {
     @GET('/health')
     public async health(): Promise<string> {
@@ -248,7 +248,7 @@ class UserController extends Controller {
     }
 }
 
-//BuildEntrypoints({controllers: [UserController], rules: [AdminRule], httpActionGroups: {admin: 'Administration'}})
+//buildEntrypoints({controllers: [UserController], rules: [AdminRule], httpActionGroups: {admin: 'Administration'}})
 ```
 
 The groups of an action must be declared in `httpActionGroups`, `cliActionGroups` or `serviceActionGroups` of
@@ -287,7 +287,11 @@ launches once its server listens. To move it to `expressHTTPEntrypoint`:
 - the `{errno, errMsg, data}` envelope is `jsonEnvelope()`. The applications of 2.x usually answered the errors of the
   actions with 200 and the errors of their express middlewares (`next(error)`: an authenticator's 401) with their
   status: `jsonEnvelope({actionErrorStatus: 200})` does the same — `errorStatus: 200` would answer the 401 with 200 too,
-  which the clients redirecting to the login page on a 401 would miss.
+  which the clients redirecting to the login page on a 401 would miss;
+- the other fields of the envelope of the application (`timestamp`, `nonce`, a request id) are given by its `extra`
+  option, called for each response, results and errors: `jsonEnvelope({actionErrorStatus: 200, extra: () =>
+  ({timestamp: Date.now()})})`. They are added after `errno`, `errMsg` and `data`, which they never replace — no
+  responder of its own is needed to keep them.
 
 ```typescript
 import {buildEntrypoints} from 'lakutata/com/entrypoint'
@@ -310,13 +314,13 @@ export const entrypoint = buildEntrypoints({
             //The authenticator of the requests: its errors keep their status (401)
             app.use((request: Request, _response: Response, next: NextFunction): void => request.headers.authorization ? next() : next(new Unauthorized('Not logged in')))
         },
-        //The errors of the actions answered with 200 in the envelope, as in 2.x
-        respond: jsonEnvelope({actionErrorStatus: 200})
+        //The errors of the actions answered with 200 in the envelope, as in 2.x, with its timestamp
+        respond: jsonEnvelope({actionErrorStatus: 200, extra: (): Record<string, unknown> => ({timestamp: Date.now()})})
     })
 })
 ```
 
-`fastifyHTTPEntrypoint` takes the same options (`fastifyJSONEnvelope({actionErrorStatus: 200})`, the authenticator
+`fastifyHTTPEntrypoint` takes the same options (`fastifyJSONEnvelope({actionErrorStatus: 200, extra})`, the authenticator
 being a hook of fastify). A responder of its own receives the origin of each error as the fourth argument of its
 `error` (`'action'` or `'request'`).
 

package/doc/zh/ActionPattern.md

@@ -171,7 +171,7 @@ class UserController extends Controller {
 import {type ActionInvocation, Controller, type Next} from 'lakutata/com/entrypoint'
 import {GET, UseMiddlewares} from 'lakutata/decorator/ctrl'
 
-async function Timing(invocation: ActionInvocation, next: Next): Promise<unknown> {
+async function timing(invocation: ActionInvocation, next: Next): Promise<unknown> {
     const started: number = Date.now()
     try {
         return await next()
@@ -180,7 +180,7 @@ async function Timing(invocation: ActionInvocation, next: Next): Promise<unknown
     }
 }
 
-@UseMiddlewares(Timing)
+@UseMiddlewares(timing)
 class HealthController extends Controller {
     @GET('/health')
     public async health(): Promise<string> {
@@ -212,7 +212,7 @@ class UserController extends Controller {
     }
 }
 
-//BuildEntrypoints({controllers: [UserController], rules: [AdminRule], httpActionGroups: {admin: 'Administration'}})
+//buildEntrypoints({controllers: [UserController], rules: [AdminRule], httpActionGroups: {admin: 'Administration'}})
 ```
 
 动作的分组必须在 `buildEntrypoints` 的 `httpActionGroups`、`cliActionGroups` 或 `serviceActionGroups` 中声明。`shutdownTimeout`（默认 30000 毫秒）是入口停止时留给正在处理的请求的时间。
@@ -240,7 +240,8 @@ class UserController extends Controller {
 
 - 应用自己的中间件和路由（CORS、压缩、健康检查、Authenticator、Web UI）放进 `before` 钩子，钩子里用 `module.getObject()` 获取对象；请求体解析用 `body` 选项（`{limit: '100mb'}`）；服务器的 `keepAliveTimeout`/`headersTimeout` 用 `server` 选项；
 - 从请求构造动作输入（查询参数、请求体、会话中的值）用 `input` 选项；
-- `{errno, errMsg, data}` 封套用 `jsonEnvelope()`。2.x 的应用通常对动作的错误返回 200，而对 Express 中间件的错误（`next(error)`，比如 Authenticator 的 401）使用错误自带的状态码：`jsonEnvelope({actionErrorStatus: 200})` 的行为与此相同。如果用 `errorStatus: 200`，401 也会变成 200，按 401 跳转登录页的前端就会失效。
+- `{errno, errMsg, data}` 封套用 `jsonEnvelope()`。2.x 的应用通常对动作的错误返回 200，而对 Express 中间件的错误（`next(error)`，比如 Authenticator 的 401）使用错误自带的状态码：`jsonEnvelope({actionErrorStatus: 200})` 的行为与此相同。如果用 `errorStatus: 200`，401 也会变成 200，按 401 跳转登录页的前端就会失效；
+- 应用封套里的其他字段（`timestamp`、`nonce`、请求 ID）用 `extra` 选项给出。它在每次响应时调用，成功和错误的响应都会带上这些字段：`jsonEnvelope({actionErrorStatus: 200, extra: () => ({timestamp: Date.now()})})`。这些字段排在 `errno`、`errMsg`、`data` 之后，不会覆盖这三个字段，因此不需要为了保留它们自己实现响应器。
 
 ```typescript
 import {buildEntrypoints} from 'lakutata/com/entrypoint'
@@ -263,13 +264,13 @@ export const entrypoint = buildEntrypoints({
             //请求的鉴权：它的错误保留自带的状态码（401）
             app.use((request: Request, _response: Response, next: NextFunction): void => request.headers.authorization ? next() : next(new Unauthorized('Not logged in')))
         },
-        //动作的错误在封套中以 200 返回，与 2.x 相同
-        respond: jsonEnvelope({actionErrorStatus: 200})
+        //动作的错误在封套中以 200 返回，与 2.x 相同，并带上时间戳
+        respond: jsonEnvelope({actionErrorStatus: 200, extra: (): Record<string, unknown> => ({timestamp: Date.now()})})
     })
 })
 ```
 
-`fastifyHTTPEntrypoint` 的选项相同（使用 `fastifyJSONEnvelope({actionErrorStatus: 200})`，Authenticator 写成 Fastify 的钩子）。自定义的响应器可以从 `error` 的第四个参数得到每个错误的来源（`'action'` 或 `'request'`）。
+`fastifyHTTPEntrypoint` 的选项相同（使用 `fastifyJSONEnvelope({actionErrorStatus: 200, extra})`，Authenticator 写成 Fastify 的钩子）。自定义的响应器可以从 `error` 的第四个参数得到每个错误的来源（`'action'` 或 `'request'`）。
 
 ### 服务动作的客户端与推送事件
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lakutata",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-beta.2",
   "description": "An IoC-based universal application framework.",
   "type": "module",
   "exports": {
@@ -326,18 +326,18 @@
     "typescript"
   ],
   "dependencies": {
-    "@lakutata/cache": "3.0.0-beta.1",
-    "@lakutata/containerd": "3.0.0-beta.1",
-    "@lakutata/core": "3.0.0-beta.1",
-    "@lakutata/docker": "3.0.0-beta.1",
-    "@lakutata/entrypoint": "3.0.0-beta.1",
-    "@lakutata/i18n": "3.0.0-beta.1",
-    "@lakutata/logger": "3.0.0-beta.1",
-    "@lakutata/monitor": "3.0.0-beta.1",
-    "@lakutata/mutex": "3.0.0-beta.1",
-    "@lakutata/orm": "3.0.0-beta.1",
-    "@lakutata/security": "3.0.0-beta.1",
-    "@lakutata/utils": "3.0.0-beta.1"
+    "@lakutata/cache": "3.0.0-beta.2",
+    "@lakutata/containerd": "3.0.0-beta.2",
+    "@lakutata/core": "3.0.0-beta.2",
+    "@lakutata/docker": "3.0.0-beta.2",
+    "@lakutata/entrypoint": "3.0.0-beta.2",
+    "@lakutata/i18n": "3.0.0-beta.2",
+    "@lakutata/logger": "3.0.0-beta.2",
+    "@lakutata/monitor": "3.0.0-beta.2",
+    "@lakutata/mutex": "3.0.0-beta.2",
+    "@lakutata/orm": "3.0.0-beta.2",
+    "@lakutata/security": "3.0.0-beta.2",
+    "@lakutata/utils": "3.0.0-beta.2"
   },
   "files": [
     "dist",