@lakutata/entrypoint 3.0.0-beta.6 → 3.1.0

package/README.md

@@ -1,13 +1,15 @@
 # @lakutata/entrypoint
 
-The entrypoint of the lakutata framework: the controllers and their actions, served by transports. One controller
-method can be an HTTP route, a CLI command, a service action (invoked over HTTP, Socket.IO, JSON-RPC, gRPC, NATS or
-Electron IPC) and a scheduled job at the same time; its input is validated by its DTO, checked by the access control and
-passed through the middlewares the same way whatever the transport.
+English | [中文](README.zh-CN.md)
 
-The umbrella package `lakutata` re-exports it: `lakutata/com/entrypoint` (the component, the controllers, the
-contexts, the results), `lakutata/decorator/ctrl` (the action decorators) and `lakutata/adapter/*` (the transports),
-and presets the `entrypoint` component of the applications.
+The entrypoint of the lakutata framework: controllers and their actions, served by transports. One controller method
+can be an HTTP route, a CLI command, a service action (called over HTTP, Socket.IO, JSON-RPC, gRPC, NATS or Electron
+IPC) and a scheduled job at the same time. Whatever the transport, a request goes through the same middlewares, its
+input is validated by the same DTO, and the same access control applies.
+
+The umbrella package `lakutata` re-exports it as `lakutata/com/entrypoint` (the component, controllers, contexts and
+results), `lakutata/decorator/ctrl` (the action decorators) and `lakutata/adapter/*` (the transports), and presets the
+`entrypoint` component in every application.
 
 ## Installation
 
@@ -15,7 +17,7 @@ and presets the `entrypoint` component of the applications.
 npm install lakutata
 ```
 
-The transports use optional peer dependencies, installed when used:
+The transports rely on optional peer dependencies, which you install only when you use them:
 
 | Transport | Subpath | Install |
 |---|---|---|
@@ -71,7 +73,7 @@ class OrderController extends Controller {
         return input
     }
 
-    //Every 5 minutes (with {every: '5m', exclusive: true} and a mutex component: in one instance at a time)
+    //Every 5 minutes (with {every: '5m', exclusive: true} and a mutex component, in one instance at a time)
     @Schedule('5m')
     public async report(): Promise<void> {
     }
@@ -93,15 +95,18 @@ Application.run(() => ({
 }))
 ```
 
-### The request of an action
+### Inside an action
 
-- `this.context` is the context of the request: `HTTPContext` (its `request`, `response`, `route`, `method`),
-  `CLIContext` (its `command`), `ServiceContext` (its `clientId`) or `ScheduleContext`.
-- `this.signal` is aborted when the request is: its client gone, its deadline exceeded, the entrypoint stopping.
-- A controller is created for each request (`@Scoped`): its injected objects of the request are shared by the request.
-- The value returned is the response. `Result.status(201, data, headers)`, `Result.file(path)` and `Result.events()`
+- `this.context` is the request's context: `HTTPContext` (with `request`, `response`, `route`, `method`),
+  `CLIContext` (with `command`), `ServiceContext` (with `clientId`) or `ScheduleContext`.
+- `this.signal` is aborted when the request is aborted: the client goes away, the deadline passes or the entrypoint
+  stops.
+- A controller is created for each request (`@Scoped`), and the request-scoped objects it injects are shared within
+  that request.
+- The returned value is the response. `Result.status(201, data, headers)`, `Result.file(path)` and `Result.events()`
   (Server-Sent Events) control the HTTP response.
-- An exception is answered with its `statusCode` (HTTP) and its `errno`, `message` (JSON); an invalid input with 400.
+- Over HTTP (Express, Fastify), an exception is answered with its `statusCode` and the JSON `{errno, errMsg}`, and
+  invalid input with 400.
 
 ### Middlewares and access control
 
@@ -109,8 +114,9 @@ Application.run(() => ({
 import {Application} from 'lakutata'
 import {buildEntrypoints, Controller, type ActionInvocation, type Next} from 'lakutata/com/entrypoint'
 import {GET, UseMiddlewares} from 'lakutata/decorator/ctrl'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
 
-//Runs around the action: before its input validation and its access control
+//Runs around the action, before input validation and access control
 async function timing(invocation: ActionInvocation, next: Next): Promise<unknown> {
     const started: number = Date.now()
     try {
@@ -120,6 +126,7 @@ async function timing(invocation: ActionInvocation, next: Next): Promise<unknown
     }
 }
 
+//For the actions of this controller (buildEntrypoints({middlewares: [timing]}) would run it for every action)
 @UseMiddlewares(timing)
 class HealthController extends Controller {
     @GET('/health')
@@ -132,13 +139,14 @@ Application.run(() => ({
     id: 'health.app',
     name: 'Health',
     components: {
-        entrypoint: buildEntrypoints({controllers: [HealthController], middlewares: [timing]})
-    }
+        entrypoint: buildEntrypoints({controllers: [HealthController], http: expressHTTPEntrypoint({port: 3000})})
+    },
+    bootstrap: ['entrypoint']
 }))
 ```
 
-The access control: an action declared with `{acl: true}` is checked by the rules given to `buildEntrypoints({rules})`
-(`AccessControlRule` subclasses, created for each request); a rule resolving `false` denies it with
+Access control: an action declared with `{acl: true}` is checked by the rules given to `buildEntrypoints({rules})`
+(`AccessControlRule` subclasses, created for each request). A rule that resolves to `false` denies the request with
 `AccessDeniedException` (HTTP 403).
 
 ## API
@@ -152,11 +160,12 @@ The access control: an action declared with `{acl: true}` is checked by the rule
 | `AccessControlRule`, `AccessControl` | `lakutata/com/entrypoint` | The access control |
 | `Middleware`, `ActionInvocation`, `Next` | `lakutata/com/entrypoint` | The middlewares |
 | `httpServiceEntrypoint`, `scheduleEntrypoint` | `lakutata/com/entrypoint` | The service over HTTP, the schedules |
+| `HTTPServiceProxy`, `buildHTTPServiceProxy` | `lakutata/com/entrypoint` | The client of a service over HTTP: its actions and its events |
 | `Cron`, `parseDuration` | `lakutata/com/entrypoint` | Cron expressions and durations |
 | `HTTPAction`, `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS` | `lakutata/decorator/ctrl` | HTTP routes |
 | `CLIAction`, `ServiceAction`, `Schedule` | `lakutata/decorator/ctrl` | Commands, service actions, scheduled jobs |
 | `Prefix`, `UseMiddlewares` | `lakutata/decorator/ctrl` | A prefix for the routes, commands and patterns of a controller; its middlewares |
-| `expressHTTPEntrypoint`, `fastifyHTTPEntrypoint` | `lakutata/adapter/express`, `lakutata/adapter/fastify` | HTTP transports (with static UIs) |
+| `expressHTTPEntrypoint`, `fastifyHTTPEntrypoint` | `lakutata/adapter/express`, `lakutata/adapter/fastify` | HTTP transports (`staticUI` with Express) |
 | `commanderCLIEntrypoint` | `lakutata/adapter/commander` | CLI transport |
 | `socketIOServiceEntrypoint`, `jsonRPCServiceEntrypoint`, `electronIPCServiceEntrypoint` | `lakutata/adapter/*` | Service transports |
 | `EntrypointAdapter`, `ChannelRuntime` | `@lakutata/entrypoint/channel` | Writing a transport or a channel |
@@ -172,12 +181,16 @@ The typings document each declaration with examples.
 | `ControllerActionNotFoundException`, `RouteNotFoundException` | No action matches the request (HTTP 404) |
 | `EntrypointStoppedException` | The entrypoint is stopping (HTTP 503) |
 | `DuplicateActionNameException` | Two actions of a channel have the same name |
-| `InvalidPrefixException`, `InvalidMiddlewareException`, `InvalidChannelException`, `InvalidEntrypointAdapterException` | The declarations of the controllers or the options are invalid |
+| `InvalidActionGroupException`, `InvalidPrefixException`, `InvalidMiddlewareException`, `InvalidChannelException`, `InvalidEntrypointAdapterException` | The declarations of the controllers or the options are invalid |
 | `ServiceInvokeException` | A remote service action failed (its error's properties copied) |
+| `ServiceUnavailableException` | A service called by an `HTTPServiceProxy` gave no response (HTTP 503) |
 
 ## See also
 
-- The guide: `doc/en/ActionPattern.md` of the package `lakutata` (Chinese in `doc/zh`).
-- `@lakutata/core`: the DTOs, the dependency injection and the application.
-- `@lakutata/mutex`: `@Synchronized` actions and the `exclusive` schedules.
+- The guides on the website: [Controllers and Actions](https://lakutata.com/guide/Controllers) and
+  [Entrypoint](https://lakutata.com/guide/Entrypoint).
+- The guides in the `lakutata` package (`doc/en`, Chinese in `doc/zh`): `Controllers.md`, `Entrypoint.md`,
+  `Middlewares.md`, `HTTP.md` (the HTTP adapters), `ServiceCalls.md` (the service transports), `CLI.md`, `Schedules.md`.
+- `@lakutata/core`: DTOs, dependency injection and the application.
+- `@lakutata/mutex`: `@Synchronized` actions and `exclusive` schedules.
 - `@lakutata/grpc`, `@lakutata/nats`: the service transports over gRPC and NATS.

package/README.zh-CN.md

@@ -0,0 +1,182 @@
+# @lakutata/entrypoint
+
+[English](README.md) | 中文
+
+lakutata 框架的入口：控制器及其动作，通过各种传输方式对外提供。一个控制器方法可以同时是 HTTP 路由、命令行命令、服务动作（通过 HTTP、Socket.IO、JSON-RPC、gRPC、NATS 或 Electron IPC 调用）和定时任务。无论通过哪种传输方式，请求都经过相同的中间件，输入由相同的 DTO 校验，适用的访问控制也相同。
+
+`lakutata` 包把它重新导出为 `lakutata/com/entrypoint`（组件、控制器、上下文和结果）、`lakutata/decorator/ctrl`（动作装饰器）和 `lakutata/adapter/*`（各种传输方式），并在每个应用中预置 `entrypoint` 组件。
+
+## 安装
+
+```shell
+npm install lakutata
+```
+
+各传输方式所需的包都是可选的 peer 依赖，用到时才需要安装：
+
+| 传输方式 | 子路径 | 需要安装 |
+|---|---|---|
+| 基于 Express 4/5 的 HTTP | `lakutata/adapter/express` | `express` |
+| 基于 Fastify 5 的 HTTP | `lakutata/adapter/fastify` | `fastify` |
+| 基于 Commander 的命令行 | `lakutata/adapter/commander` | `commander`（提示输入还需要 `@inquirer/prompts`） |
+| 基于 Socket.IO 的服务调用 | `lakutata/adapter/socket.io` | `socket.io` |
+| 基于 JSON-RPC 2.0 的服务调用（HTTP、WebSocket、stdio） | `lakutata/adapter/jsonrpc` | 使用 WebSocket 时需要 `ws` |
+| 基于 Electron IPC 的服务调用 | `lakutata/adapter/electron` | （Electron） |
+| 基于 HTTP 的服务调用（`POST /`，事件通过 SSE 推送） | `lakutata/com/entrypoint` | 无 |
+| 定时任务（`@Schedule`） | `lakutata/com/entrypoint` | 无 |
+| 基于 gRPC / NATS 的服务调用 | `@lakutata/grpc/service` / `@lakutata/nats` | 它们各自的包 |
+
+## 用法
+
+### 控制器与传输方式
+
+```typescript
+import {Application, DTO} from 'lakutata'
+import {buildEntrypoints, Controller, scheduleEntrypoint} from 'lakutata/com/entrypoint'
+import {CLIAction, GET, POST, Schedule, ServiceAction} from 'lakutata/decorator/ctrl'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+import {commanderCLIEntrypoint} from 'lakutata/adapter/commander'
+import {socketIOServiceEntrypoint} from 'lakutata/adapter/socket.io'
+import {Expect} from 'lakutata/decorator/dto'
+
+class GetOrderDTO extends DTO {
+    //路由参数和查询参数都是字符串：strict(false) 会转换它们
+    @Expect(DTO.Number().integer().strict(false).required())
+    public id: number
+}
+
+class CreateOrderDTO extends DTO {
+    @Expect(DTO.String().required())
+    public product: string
+
+    @Expect(DTO.Number().integer().min(1).default(1))
+    public quantity: number
+}
+
+class OrderController extends Controller {
+    //GET /orders/42、命令 "order --id 42"、服务请求 {cmd: 'order.get', id: 42}
+    @GET('/orders/:id', GetOrderDTO)
+    @CLIAction('order', GetOrderDTO)
+    @ServiceAction({cmd: 'order.get'}, GetOrderDTO)
+    public async get(input: GetOrderDTO): Promise<{id: number}> {
+        return {id: input.id}
+    }
+
+    //带 JSON 请求体的 POST /orders；返回值就是响应（JSON）
+    @POST('/orders', CreateOrderDTO)
+    public async create(input: CreateOrderDTO): Promise<{product: string, quantity: number}> {
+        return input
+    }
+
+    //每 5 分钟执行一次（使用 {every: '5m', exclusive: true} 并配置锁组件时，同一时间只在一个实例中执行）
+    @Schedule('5m')
+    public async report(): Promise<void> {
+    }
+}
+
+Application.run(() => ({
+    id: 'orders.app',
+    name: 'Orders',
+    components: {
+        entrypoint: buildEntrypoints({
+            controllers: [OrderController],
+            http: expressHTTPEntrypoint({port: 8080}),
+            cli: commanderCLIEntrypoint(),
+            service: socketIOServiceEntrypoint({port: 8081}),
+            schedule: scheduleEntrypoint()
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+### 在动作中
+
+- `this.context` 是请求的上下文：`HTTPContext`（带有 `request`、`response`、`route`、`method`）、`CLIContext`（带有 `command`）、`ServiceContext`（带有 `clientId`）或 `ScheduleContext`。
+- 请求被中止时，`this.signal` 也会被中止：客户端离开、截止时间已过，或者入口停止。
+- 每个请求都会创建一个控制器（`@Scoped`），它注入的请求作用域对象在这个请求内共享。
+- 返回值就是响应。`Result.status(201, data, headers)`、`Result.file(path)` 和 `Result.events()`（Server-Sent Events）用来控制 HTTP 响应。
+- 通过 HTTP（Express、Fastify）调用时，抛出的异常会以它的 `statusCode` 和 JSON `{errno, errMsg}` 返回，输入不合法时返回 400。
+
+### 中间件与访问控制
+
+```typescript
+import {Application} from 'lakutata'
+import {buildEntrypoints, Controller, type ActionInvocation, type Next} from 'lakutata/com/entrypoint'
+import {GET, UseMiddlewares} from 'lakutata/decorator/ctrl'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+
+//在动作前后运行，早于输入校验和访问控制
+async function timing(invocation: ActionInvocation, next: Next): Promise<unknown> {
+    const started: number = Date.now()
+    try {
+        return await next()
+    } finally {
+        console.log(`${invocation.context.type} took ${Date.now() - started} ms`)
+    }
+}
+
+//作用于这个控制器的动作（写在 buildEntrypoints({middlewares: [timing]}) 中则作用于所有动作）
+@UseMiddlewares(timing)
+class HealthController extends Controller {
+    @GET('/health')
+    public async health(): Promise<string> {
+        return 'ok'
+    }
+}
+
+Application.run(() => ({
+    id: 'health.app',
+    name: 'Health',
+    components: {
+        entrypoint: buildEntrypoints({controllers: [HealthController], http: expressHTTPEntrypoint({port: 3000})})
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+访问控制：以 `{acl: true}` 声明的动作，由传给 `buildEntrypoints({rules})` 的规则检查（`AccessControlRule` 的子类，每个请求创建一次）。某条规则的结果为 `false` 时，请求被拒绝，抛出 `AccessDeniedException`（HTTP 403）。
+
+## API
+
+| 导出 | 子路径 | 说明 |
+|---|---|---|
+| `Entrypoint`、`buildEntrypoints` | `lakutata/com/entrypoint` | 组件及其选项：控制器、传输方式、中间件、规则、分组 |
+| `Controller` | `lakutata/com/entrypoint` | 控制器的基类（`context`、`signal`） |
+| `HTTPContext`、`CLIContext`、`ServiceContext`、`ScheduleContext`、`BaseContext`、`ContextType` | `lakutata/com/entrypoint` | 请求的上下文 |
+| `Result`、`StatusResult`、`FileResult`、`EventsResult` | `lakutata/com/entrypoint` | 控制 HTTP 响应的结果 |
+| `AccessControlRule`、`AccessControl` | `lakutata/com/entrypoint` | 访问控制 |
+| `Middleware`、`ActionInvocation`、`Next` | `lakutata/com/entrypoint` | 中间件 |
+| `httpServiceEntrypoint`、`scheduleEntrypoint` | `lakutata/com/entrypoint` | 基于 HTTP 的服务调用；定时任务 |
+| `HTTPServiceProxy`、`buildHTTPServiceProxy` | `lakutata/com/entrypoint` | 基于 HTTP 的服务的客户端：调用它的动作，接收它推送的事件 |
+| `Cron`、`parseDuration` | `lakutata/com/entrypoint` | cron 表达式和时长 |
+| `HTTPAction`、`GET`、`POST`、`PUT`、`PATCH`、`DELETE`、`HEAD`、`OPTIONS` | `lakutata/decorator/ctrl` | HTTP 路由 |
+| `CLIAction`、`ServiceAction`、`Schedule` | `lakutata/decorator/ctrl` | 命令、服务动作、定时任务 |
+| `Prefix`、`UseMiddlewares` | `lakutata/decorator/ctrl` | 为控制器的路由、命令和模式加上前缀；控制器的中间件 |
+| `expressHTTPEntrypoint`、`fastifyHTTPEntrypoint` | `lakutata/adapter/express`、`lakutata/adapter/fastify` | HTTP 传输方式（Express 支持 `staticUI`） |
+| `commanderCLIEntrypoint` | `lakutata/adapter/commander` | 命令行传输方式 |
+| `socketIOServiceEntrypoint`、`jsonRPCServiceEntrypoint`、`electronIPCServiceEntrypoint` | `lakutata/adapter/*` | 服务调用的传输方式 |
+| `EntrypointAdapter`、`ChannelRuntime` | `@lakutata/entrypoint/channel` | 编写适配器或新的传输方式 |
+
+类型声明中的每一项都附有说明和示例。
+
+## 错误
+
+| 异常 | 什么时候抛出 |
+|---|---|
+| `InvalidValueException`（来自 `lakutata`） | 输入不符合动作的 DTO（HTTP 400） |
+| `AccessDeniedException` | 规则拒绝了请求（HTTP 403） |
+| `ControllerActionNotFoundException`、`RouteNotFoundException` | 没有与请求匹配的动作（HTTP 404） |
+| `EntrypointStoppedException` | 入口正在停止（HTTP 503） |
+| `DuplicateActionNameException` | 同一传输方式中有两个同名的动作 |
+| `InvalidActionGroupException`、`InvalidPrefixException`、`InvalidMiddlewareException`、`InvalidChannelException`、`InvalidEntrypointAdapterException` | 控制器的声明或选项不合法 |
+| `ServiceInvokeException` | 远程服务动作失败（带有原错误的各个属性） |
+| `ServiceUnavailableException` | `HTTPServiceProxy` 调用的服务没有给出响应（HTTP 503） |
+
+## 另见
+
+- 网站上的指南：[控制器与动作](https://lakutata.com/zh/guide/Controllers)、[Entrypoint](https://lakutata.com/zh/guide/Entrypoint)。
+- `lakutata` 包中的指南（`doc/zh`）：`Controllers.md`、`Entrypoint.md`、`Middlewares.md`、`HTTP.md`（HTTP 适配器）、`ServiceCalls.md`（服务调用的传输方式）、`CLI.md`、`Schedules.md`。
+- `@lakutata/core`：DTO、依赖注入和应用。
+- `@lakutata/mutex`：`@Synchronized` 动作和 `exclusive` 定时任务。
+- `@lakutata/grpc`、`@lakutata/nats`：基于 gRPC 和 NATS 的服务调用传输方式。

package/dist/cjs/Entrypoint.d.ts

@@ -60,7 +60,7 @@ export type ServiceEntrypoint = (module: Module, handler: ServiceEntrypointHandl
 export type CLIMap = Map<string, JSONSchema>;
 /**
  * The HTTP actions given to an {@link HTTPEntrypoint}: each route (with its controller prefix) mapped to the set of
- * its HTTP methods (`GET`, `POST`…).
+ * its HTTP methods, as declared (`get`, `post`… from `@GET`, `@POST`…; `@HTTPAction` keeps the case it is given).
  */
 export type HTTPRouteMap<HTTPMethods = string> = Map<string, Set<HTTPMethods>>;
 /**
@@ -303,7 +303,8 @@ export interface EntrypointActions<T extends BaseActionInfo> {
  *                 if (cliMap.has(command)) console.log(await handler(new CLIContext({command: command, data: {}})))
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * }))
  * ```
  */
@@ -335,8 +336,9 @@ export declare const buildCLIEntrypoint: (entrypoint: CLIEntrypoint) => CLIEntry
  *             controllers: [HealthController],
  *             http: buildHTTPEntrypoint((module, routeMap, handler, registerDestroy): void => {
  *                 const server: Server = createServer(async (request, response): Promise<void> => {
+ *                     //The route map holds the routes and the methods as declared: '/health', 'get'
  *                     const route: string = (request.url ?? '/').split('?')[0]
- *                     const method: string = request.method ?? 'GET'
+ *                     const method: string = (request.method ?? 'GET').toLowerCase()
  *                     if (!routeMap.get(route)?.has(method)) {
  *                         response.writeHead(404).end()
  *                         return
@@ -353,7 +355,8 @@ export declare const buildCLIEntrypoint: (entrypoint: CLIEntrypoint) => CLIEntry
  *                 registerDestroy((): Promise<void> => new Promise((resolve): void => void server.close((): void => resolve())))
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * }))
  * ```
  */
@@ -394,7 +397,8 @@ export declare const buildHTTPEntrypoint: (entrypoint: HTTPEntrypoint) => HTTPEn
  *                 registerDestroy((): void => void bus.off('request', listener))
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * }))
  * ```
  */
@@ -444,7 +448,8 @@ export declare const buildServiceEntrypoint: (entrypoint: ServiceEntrypoint) =>
  *             http: expressHTTPEntrypoint({port: 3000}),
  *             schedule: scheduleEntrypoint()
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * }))
  * ```
  */
@@ -531,7 +536,8 @@ type StartedAdapter = {
  *                 http: expressHTTPEntrypoint({port: 3000}),
  *                 service: socketIOServiceEntrypoint({port: 3001})
  *             })
- *         }
+ *         },
+ *         bootstrap: ['entrypoint']
  *     }))
  *     .onLaunched(async (app: Application): Promise<void> => {
  *         const entrypoint: Entrypoint = await app.getObject<Entrypoint>('entrypoint')

package/dist/cjs/Entrypoint.js

@@ -67,7 +67,8 @@ Object.defineProperty(exports, "ScheduleContext", { enumerable: true, get: funct
  *                 if (cliMap.has(command)) console.log(await handler(new CLIContext({command: command, data: {}})))
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * }))
  * ```
  */
@@ -100,8 +101,9 @@ exports.buildCLIEntrypoint = buildCLIEntrypoint;
  *             controllers: [HealthController],
  *             http: buildHTTPEntrypoint((module, routeMap, handler, registerDestroy): void => {
  *                 const server: Server = createServer(async (request, response): Promise<void> => {
+ *                     //The route map holds the routes and the methods as declared: '/health', 'get'
  *                     const route: string = (request.url ?? '/').split('?')[0]
- *                     const method: string = request.method ?? 'GET'
+ *                     const method: string = (request.method ?? 'GET').toLowerCase()
  *                     if (!routeMap.get(route)?.has(method)) {
  *                         response.writeHead(404).end()
  *                         return
@@ -118,7 +120,8 @@ exports.buildCLIEntrypoint = buildCLIEntrypoint;
  *                 registerDestroy((): Promise<void> => new Promise((resolve): void => void server.close((): void => resolve())))
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * }))
  * ```
  */
@@ -160,7 +163,8 @@ exports.buildHTTPEntrypoint = buildHTTPEntrypoint;
  *                 registerDestroy((): void => void bus.off('request', listener))
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * }))
  * ```
  */
@@ -211,7 +215,8 @@ exports.buildServiceEntrypoint = buildServiceEntrypoint;
  *             http: expressHTTPEntrypoint({port: 3000}),
  *             schedule: scheduleEntrypoint()
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * }))
  * ```
  */
@@ -282,7 +287,8 @@ const LEGACY_CHANNELS = new Set(['cli', 'http', 'service']);
  *                 http: expressHTTPEntrypoint({port: 3000}),
  *                 service: socketIOServiceEntrypoint({port: 3001})
  *             })
- *         }
+ *         },
+ *         bootstrap: ['entrypoint']
  *     }))
  *     .onLaunched(async (app: Application): Promise<void> => {
  *         const entrypoint: Entrypoint = await app.getObject<Entrypoint>('entrypoint')

package/dist/cjs/adapter/commander/CommanderCLIEntrypoint.d.ts

@@ -173,7 +173,7 @@ export type CommanderCLIEntrypointOptions = {
  *     @CLIAction('greet <name>', GreetDTO)
  *     public async greet(input: GreetDTO): Promise<string> {
  *         const text: string = `Hello, ${input.name}`
- *         return (input.loud ? text.toUpperCase() : text).repeat(input.times ?? 1)
+ *         return Array(input.times ?? 1).fill(input.loud ? text.toUpperCase() : text).join('\n')
  *     }
  * }
  *
@@ -185,7 +185,8 @@ export type CommanderCLIEntrypointOptions = {
  *             controllers: [GreetController],
  *             cli: commanderCLIEntrypoint({bin: 'tool', description: 'A greeting tool', version: '1.0.0'})
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  * ```
  */

package/dist/cjs/adapter/commander/CommanderCLIEntrypoint.js

@@ -196,7 +196,7 @@ function errorMessage(error) {
  *     @CLIAction('greet <name>', GreetDTO)
  *     public async greet(input: GreetDTO): Promise<string> {
  *         const text: string = `Hello, ${input.name}`
- *         return (input.loud ? text.toUpperCase() : text).repeat(input.times ?? 1)
+ *         return Array(input.times ?? 1).fill(input.loud ? text.toUpperCase() : text).join('\n')
  *     }
  * }
  *
@@ -208,7 +208,8 @@ function errorMessage(error) {
  *             controllers: [GreetController],
  *             cli: commanderCLIEntrypoint({bin: 'tool', description: 'A greeting tool', version: '1.0.0'})
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  * ```
  */

package/dist/cjs/adapter/electron/ElectronIPCServiceEntrypoint.d.ts

@@ -187,7 +187,8 @@ export declare function ipcEventOfContext<Event extends IPCInvokeEvent = IPCInvo
  *             controllers: [EchoController],
  *             service: electronIPCServiceEntrypoint()
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  *
  * //In the preload script of a window

package/dist/cjs/adapter/electron/ElectronIPCServiceEntrypoint.js

@@ -127,7 +127,8 @@ async function loadIPCMain() {
  *             controllers: [EchoController],
  *             service: electronIPCServiceEntrypoint()
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  *
  * //In the preload script of a window

package/dist/cjs/adapter/express/ExpressHTTPEntrypoint.d.ts

@@ -20,7 +20,7 @@ export type ExpressHookContext = {
      */
     readonly server: Server;
     /**
-     * Each action route mapped to its HTTP methods, in lower case as declared (`'/users/:id'` → `{'get', 'delete'}`).
+     * Each action route mapped to its HTTP methods, as declared (`'/users/:id'` → `{'get', 'delete'}`).
      */
     readonly routes: Map<string, Set<string>>;
     /**
@@ -166,7 +166,8 @@ export type ExpressHTTPEntrypointOptions = {
  *                 fallback: staticUI('./ui/dist')
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  * ```
  */

package/dist/cjs/adapter/express/ExpressHTTPEntrypoint.js

@@ -12,6 +12,7 @@ const BuiltinChannels_js_1 = require("../../channel/BuiltinChannels.js");
 const Result_js_1 = require("../../lib/Result.js");
 const RouteNotFoundException_js_1 = require("../../exceptions/RouteNotFoundException.js");
 const Connections_js_1 = require("../../lib/Connections.js");
+const ExplicitStatus_js_1 = require("../../lib/ExplicitStatus.js");
 const Responders_js_1 = require("./Responders.js");
 /**
  * The first segments of the routes
@@ -100,7 +101,8 @@ function eventFrame(data, event, id) {
  *                 fallback: staticUI('./ui/dist')
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  * ```
  */
@@ -199,6 +201,7 @@ function expressHTTPEntrypoint(options = {}) {
             return await sendFile(result, request, response);
         if (result instanceof Result_js_1.StatusResult) {
             response.status(result.status).set(result.headers);
+            (0, ExplicitStatus_js_1.markExplicitStatus)(response);
             return respond.success(response, result.data, request);
         }
         respond.success(response, result, request);
@@ -257,7 +260,10 @@ function expressHTTPEntrypoint(options = {}) {
             await options.before?.(app, { module: runtime.module, server: server, routes: routes, actionPrefixes: actionPrefixes, isActionPath: isActionPath });
             if (options.body !== false)
                 app.use(express_1.default.json({ limit: options.body?.limit ?? '1mb' }), express_1.default.urlencoded({ extended: true, limit: options.body?.limit ?? '1mb' }));
-            for (const action of runtime.actions) {
+            //The HEAD actions first: express answers a HEAD request with the first GET route of its path when no HEAD route
+            //comes before it
+            const isHead = (action) => String(action.address.method).toLowerCase() === 'head';
+            for (const action of [...runtime.actions.filter(isHead), ...runtime.actions.filter((action) => !isHead(action))]) {
                 const method = String(action.address.method).toLowerCase();
                 const register = app[method];
                 if (typeof register !== 'function')

package/dist/cjs/adapter/express/Responders.d.ts

@@ -100,7 +100,8 @@ export type JSONEnvelopeOptions = {
  *                 })
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  * ```
  */

package/dist/cjs/adapter/express/Responders.js

@@ -6,6 +6,7 @@ const HTTPErrors_js_1 = require("../../lib/HTTPErrors.js");
 Object.defineProperty(exports, "describeError", { enumerable: true, get: function () { return HTTPErrors_js_1.describeError; } });
 Object.defineProperty(exports, "statusOfError", { enumerable: true, get: function () { return HTTPErrors_js_1.statusOfError; } });
 const Envelope_js_1 = require("../../lib/Envelope.js");
+const ExplicitStatus_js_1 = require("../../lib/ExplicitStatus.js");
 /**
  * The default responder of {@link expressHTTPEntrypoint}: a result is sent as JSON, no result as an empty 204 (or the
  * status set by a `StatusResult`); an error is sent as `{errno, errMsg}` (see `describeError`) with its HTTP status
@@ -14,7 +15,7 @@ const Envelope_js_1 = require("../../lib/Envelope.js");
 exports.JSONResponder = {
     success: (response, data) => {
         if (data === undefined) {
-            response.status(response.statusCode === 200 ? 204 : response.statusCode).end();
+            response.status(response.statusCode === 200 && !(0, ExplicitStatus_js_1.hasExplicitStatus)(response) ? 204 : response.statusCode).end();
             return;
         }
         response.json(data);
@@ -63,7 +64,8 @@ exports.JSONResponder = {
  *                 })
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  * ```
  */

package/dist/cjs/adapter/express/StaticUI.d.ts

@@ -76,7 +76,8 @@ export declare function assetsMaxAge(value: string | number | undefined): number
  *                 fallback: staticUI('./ui/dist', {assetsMaxAge: 86400})
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  * ```
  */

package/dist/cjs/adapter/express/StaticUI.js

@@ -69,7 +69,8 @@ function assetsMaxAge(value) {
  *                 fallback: staticUI('./ui/dist', {assetsMaxAge: 86400})
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  * ```
  */

package/dist/cjs/adapter/fastify/FastifyHTTPEntrypoint.d.ts

@@ -150,7 +150,8 @@ export type FastifyHTTPEntrypointOptions = {
  *                 }
  *             })
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * })
  * ```
  */