lakutata 3.0.0 → 3.1.1

package/doc/en/examples/WebApp.md

@@ -0,0 +1,568 @@
+# A web application with a user interface
+
+This example builds a shared shopping list: a web page that everyone in a household opens on a phone or a computer,
+where they all see the same list, add what is missing and remove what they have bought. It starts from the `web-react`
+template, a workspace of two packages: the application, which serves an HTTP API under `/api`, and a React page, built
+by Vite, which calls it. The example shows how the page reaches the API: through the Vite dev server during
+development, and directly once built, when the application serves the page itself. It also shows how a bundle carries
+the page among its resources, and how to test the API.
+
+| Method | Route | What it does |
+|---|---|---|
+| `GET` | `/api/items` | Lists the items |
+| `POST` | `/api/items` | Adds an item, `{"name": "Milk"}`, and answers with the list |
+| `DELETE` | `/api/items/:id` | Removes an item, and answers with the list |
+| `GET` | `/`, and any other page | The list page: the built `ui` package |
+
+## 1. Create the project
+
+```bash
+npx @lakutata/cli create --name shopping --template web-react --yes
+cd shopping
+rm packages/app/src/controllers/ExampleController.ts packages/app/src/dtos/GreetDTO.ts
+rm packages/app/src/middlewares/Authenticate.ts
+```
+
+The project is a workspace ([ProjectStructure](../ProjectStructure.md)): `packages/app` is the application, and
+`packages/ui` the React page. The example controller of the template is removed, and so is its middleware
+`Authenticate.ts`, which asks for a token that a page in a browser cannot keep secret. Anyone who can reach the
+application can use the list, which is fine on a home network; section 11 says what to do elsewhere.
+
+## 2. The list
+
+**`packages/app/src/components/ShoppingList.ts`**
+
+```typescript
+import {Component} from 'lakutata'
+
+/**
+ * An item of the list
+ */
+export interface Item {
+    id: number
+    name: string
+}
+
+/**
+ * The shopping list, kept in memory: one instance, shared by all the requests
+ */
+export class ShoppingList extends Component {
+
+    protected readonly items: Map<number, Item> = new Map()
+
+    protected lastId: number = 0
+
+    /**
+     * The items, in the order they were added
+     */
+    public all(): Item[] {
+        return [...this.items.values()]
+    }
+
+    /**
+     * Add an item
+     * @param name
+     */
+    public add(name: string): void {
+        const item: Item = {id: ++this.lastId, name: name}
+        this.items.set(item.id, item)
+    }
+
+    /**
+     * Remove an item; nothing happens when it was already removed
+     * @param id
+     */
+    public remove(id: number): void {
+        this.items.delete(id)
+    }
+}
+```
+
+A controller lives for one request only ([Controllers](../Controllers.md)), so it cannot keep the list. A component
+keeps it instead: it is created once and shared by the whole application ([Objects](../Objects.md)). The list is held
+in memory, so it is lost when the application stops (section 11).
+
+## 3. The input
+
+**`packages/app/src/dtos/ItemDTO.ts`**
+
+```typescript
+import {DTO} from 'lakutata'
+import {Expect} from 'lakutata/decorator/dto'
+
+/**
+ * A new item, its name trimmed (strict(false) lets trim() remove the spaces around it)
+ */
+export class NewItemDTO extends DTO {
+    @Expect(DTO.String().trim().strict(false).min(1).max(100).required())
+    public name: string
+}
+
+/**
+ * An item by its id (the :id of the route: text, converted by strict(false))
+ */
+export class ItemIdDTO extends DTO {
+    @Expect(DTO.Number().integer().positive().strict(false).required())
+    public id: number
+}
+```
+
+Each action validates its input with a DTO, and refuses invalid input ([DTOValidation](../DTOValidation.md)):
+
+- the schemas are strict: `.trim()` alone would refuse `'  Bread  '`. With `.strict(false)`, it removes the spaces, and
+  a name made of spaces only is refused as empty;
+- the `:id` of the route is text: `.strict(false)` converts `'1'` to the number 1.
+
+## 4. The controller
+
+**`packages/app/src/controllers/ItemController.ts`**
+
+```typescript
+import {Controller} from 'lakutata/com/entrypoint'
+import {DELETE, GET, POST, Prefix} from 'lakutata/decorator/ctrl'
+import {Inject} from 'lakutata/decorator/di'
+import {type Item, ShoppingList} from '../components/ShoppingList.js'
+import {ItemIdDTO, NewItemDTO} from '../dtos/ItemDTO.js'
+
+@Prefix({route: '/api/items'})
+export class ItemController extends Controller {
+
+    /**
+     * The list (the component "list" of the options)
+     */
+    @Inject('list')
+    protected readonly list: ShoppingList
+
+    /**
+     * GET /api/items
+     */
+    @GET('/')
+    public async all(): Promise<Item[]> {
+        return this.list.all()
+    }
+
+    /**
+     * POST /api/items {"name": "Milk"}: the list with the new item
+     * @param input
+     */
+    @POST('/', NewItemDTO)
+    public async add(input: NewItemDTO): Promise<Item[]> {
+        this.list.add(input.name)
+        return this.list.all()
+    }
+
+    /**
+     * DELETE /api/items/1: the list without the item
+     * @param input
+     */
+    @DELETE('/:id', ItemIdDTO)
+    public async remove(input: ItemIdDTO): Promise<Item[]> {
+        this.list.remove(input.id)
+        return this.list.all()
+    }
+}
+```
+
+- `@Prefix({route: '/api/items'})` puts the actions under `/api/items` ([HTTP](../HTTP.md)). Keeping the API under
+  `/api` leaves the other paths to the pages of the application (section 5).
+- `@Inject('list')` gives the controller the `list` component of the options.
+- `POST` and `DELETE` answer with the whole list, so the page can show it at once, including the changes made by
+  others.
+- Removing an item that is already removed is not an error: two people may remove the same item at the same time.
+
+## 5. The options of the application
+
+**`packages/app/src/config/Config.ts`**
+
+```typescript
+import {resourcesPath, type ApplicationOptions} from 'lakutata'
+import {buildEntrypoints} from 'lakutata/com/entrypoint'
+import {expressHTTPEntrypoint, jsonEnvelope, staticUI} from 'lakutata/adapter/express'
+import compression from 'compression'
+import {existsSync} from 'node:fs'
+import {createRequire} from 'node:module'
+import path from 'node:path'
+import {ShoppingList} from '../components/ShoppingList.js'
+import {HealthController} from '../controllers/HealthController.js'
+import {ItemController} from '../controllers/ItemController.js'
+
+/**
+ * The directory of the built ui package, undefined before it is built (in development, Vite serves the page): among the
+ * resources of a packed application (lakutata package bundle or lakutata package exe, from "lakutata.resources" in its
+ * package.json), otherwise in the ui package
+ */
+function uiDirectory(): string | undefined {
+    const resources: string | undefined = resourcesPath()
+    try {
+        const directory: string = resources ? path.join(resources, 'ui') : path.join(path.dirname(createRequire(import.meta.url).resolve('ui/package.json')), 'dist')
+        return existsSync(path.join(directory, 'index.html')) ? directory : undefined
+    } catch {
+        return undefined
+    }
+}
+
+/**
+ * The options of the service
+ * @param port the port of the HTTP server, the PORT environment variable or 8080 by default
+ */
+export function config(port: number = Number(process.env.PORT ?? 8080)): ApplicationOptions {
+    return {
+        id: 'shopping',
+        name: 'shopping',
+        mode: process.env.NODE_ENV === 'production' ? 'production' : 'development',
+        components: {
+            //The shopping list, created when a request first needs it
+            list: {class: ShoppingList},
+            entrypoint: buildEntrypoints({
+                controllers: [HealthController, ItemController],
+                http: expressHTTPEntrypoint({
+                    port: port,
+                    //The results and the errors are {errno, errMsg, data}, with the status 200
+                    respond: jsonEnvelope({errorStatus: 200}),
+                    body: {limit: '100mb'},
+                    server: {keepAliveTimeout: 60000, headersTimeout: 65000},
+                    before: (app): void => void app.use(compression()),
+                    //The paths that no action handles are the pages of the application
+                    fallback: ((directory: string | undefined) => directory ? staticUI(directory) : undefined)(uiDirectory())
+                })
+            })
+        },
+        bootstrap: ['entrypoint']
+    }
+}
+```
+
+This is the `Config.ts` of the template, with the `list` component, the `ItemController` instead of the example
+controller, and without the `authenticate` middleware. The code that serves the page comes from the template:
+
+- `fallback` answers the requests that match no action route (`/api/…` and `/health`). `staticUI()` sends the files of
+  the built page, and its `index.html` for any page path, which the page's own router then handles
+  ([HTTP](../HTTP.md)).
+- `uiDirectory()` finds the built page: among the resources of a packed application (`resourcesPath()`, section 11),
+  otherwise in the `dist` directory of the `ui` package. Before the page is built, there is no fallback: in
+  development, Vite serves the page.
+- `jsonEnvelope({errorStatus: 200})` sends both the results and the errors as `{errno, errMsg, data}` with the status
+  200: the page tells them apart by their `errno`.
+
+## 6. The calls to the API
+
+**`packages/ui/src/api.ts`**
+
+```typescript
+/**
+ * An item of the list
+ */
+export type Item = {
+    id: number
+    name: string
+}
+
+/**
+ * A request to the API of the application, on the page's own origin: returns the data of its {errno, errMsg, data}, or
+ * throws its error
+ * @param method
+ * @param route
+ * @param body
+ */
+async function request<T>(method: string, route: string, body?: unknown): Promise<T> {
+    const response: Response = await fetch(`/api${route}`, {
+        method: method,
+        headers: {'Content-Type': 'application/json'},
+        body: body === undefined ? undefined : JSON.stringify(body)
+    })
+    const result = await response.json() as { errno: string | null, errMsg: string | null, data: T }
+    if (result.errno) throw new Error(result.errMsg ?? result.errno)
+    return result.data
+}
+
+export const listItems = (): Promise<Item[]> => request('GET', '/items')
+
+export const addItem = (name: string): Promise<Item[]> => request('POST', '/items', {name: name})
+
+export const removeItem = (id: number): Promise<Item[]> => request('DELETE', `/items/${id}`)
+```
+
+The page calls the API by its path only (`/api/items`), so the requests go to the origin the page came from: the Vite
+dev server during development, the application once built. The address of the API is configured nowhere, and the
+browser makes no cross-origin request, which would need CORS. `request()` returns the `data` of the envelope, or throws
+its error, whose message the page shows, such as `"name" is not allowed to be empty`.
+
+## 7. The page
+
+**`packages/ui/src/App.tsx`**
+
+```tsx
+import {type FormEvent, useEffect, useState} from 'react'
+import {addItem, type Item, listItems, removeItem} from './api'
+
+export function App() {
+    const [items, setItems] = useState<Item[]>([])
+    const [name, setName] = useState<string>('')
+    const [error, setError] = useState<string>('')
+
+    /**
+     * Show the list that the API returns, or its error
+     * @param answer
+     */
+    async function show(answer: Promise<Item[]>): Promise<boolean> {
+        try {
+            setItems(await answer)
+            setError('')
+            return true
+        } catch (failure) {
+            setError((failure as Error).message)
+            return false
+        }
+    }
+
+    //Load the list now, then every 5 seconds, so that the changes made by others appear
+    useEffect((): (() => void) => {
+        void show(listItems())
+        const timer: number = window.setInterval((): void => void show(listItems()), 5000)
+        return (): void => window.clearInterval(timer)
+    }, [])
+
+    async function add(event: FormEvent<HTMLFormElement>): Promise<void> {
+        event.preventDefault()
+        if (await show(addItem(name))) setName('')
+    }
+
+    return (
+        <main>
+            <h1>Shopping list</h1>
+            <form onSubmit={add}>
+                <input value={name} onChange={(event): void => setName(event.target.value)} placeholder="Milk, bread…" aria-label="Item"/>
+                <button>Add</button>
+            </form>
+            {error && <p role="alert">{error}</p>}
+            {items.length === 0 && <p>The list is empty.</p>}
+            <ul>
+                {items.map((item: Item) => (
+                    <li key={item.id}>
+                        {item.name} <button onClick={(): void => void show(removeItem(item.id))}>Remove</button>
+                    </li>
+                ))}
+            </ul>
+        </main>
+    )
+}
+```
+
+- `show()` shows the list that the API returns, or its error.
+- The list is loaded when the page opens, then every 5 seconds, so the items added or removed on other phones appear.
+- The `main.tsx` of the template, which renders `App`, does not change.
+
+## 8. Run it
+
+```bash
+npm run dev
+```
+
+This runs the `dev` scripts of both packages at once ([Workspaces](../Workspaces.md)): the application is built and
+listens on port 8080, and Vite serves the page from its sources on http://localhost:5173, reloading it in the browser
+when they change. Open http://localhost:5173. The `vite.config.ts` of the template forwards the requests under `/api`
+to the application:
+
+```typescript
+server: {
+    proxy: {
+        '/api': `http://127.0.0.1:${process.env.PORT ?? 8080}`
+    }
+}
+```
+
+So the API can also be called through Vite, the way the page calls it:
+
+```bash
+curl -X POST localhost:5173/api/items -H 'Content-Type: application/json' -d '{"name": "Milk"}'
+# {"errno":null,"errMsg":null,"data":[{"id":1,"name":"Milk"}]}
+
+curl -X POST localhost:5173/api/items -H 'Content-Type: application/json' -d '{"name": "  Bread  "}'
+# {"errno":null,"errMsg":null,"data":[{"id":1,"name":"Milk"},{"id":2,"name":"Bread"}]}
+
+curl -X DELETE localhost:5173/api/items/1
+# {"errno":null,"errMsg":null,"data":[{"id":2,"name":"Bread"}]}
+
+curl -i -X POST localhost:5173/api/items -H 'Content-Type: application/json' -d '{"name": ""}'
+# HTTP/1.1 200 OK
+# {"errno":"E_INVALID_VALUE","errMsg":"\"name\" is not allowed to be empty","data":null}
+```
+
+Changes to the page show at once. Changes to the application need `npm run dev` again, as its `dev` script builds it,
+then starts it. If `npm run build` has run before, the application also serves the page of that build on port 8080;
+during development, use the page from Vite, which is up to date.
+
+## 9. Test it
+
+The test of the template is replaced by a test of the list. It starts the application on its own port, calls the API,
+then requests the page:
+
+**`packages/app/src/tests/App.spec.ts`**
+
+```typescript
+import {after, before, describe, it} from 'node:test'
+import assert from 'node:assert'
+import {Application} from 'lakutata'
+import {config} from '../config/Config.js'
+
+const PORT: number = Number(process.env.TEST_PORT ?? 18083)
+
+/**
+ * A request to the API: its {errno, errMsg, data}
+ * @param method
+ * @param route
+ * @param body
+ */
+async function request(method: string, route: string, body?: unknown): Promise<{ errno: string | null, errMsg: string | null, data: any }> {
+    const response: Response = await fetch(`http://127.0.0.1:${PORT}${route}`, {
+        method: method,
+        headers: {'Content-Type': 'application/json'},
+        body: body === undefined ? undefined : JSON.stringify(body)
+    })
+    return await response.json() as { errno: string | null, errMsg: string | null, data: any }
+}
+
+describe('shopping', (): void => {
+
+    let app: Application
+
+    before(async (): Promise<void> => {
+        app = await new Promise<Application>((resolve: (app: Application) => void): void => {
+            Application.run(config(PORT)).onLaunched((launched: Application): void => resolve(launched))
+        })
+    })
+
+    after(async (): Promise<void> => {
+        await app?.dispose()
+    })
+
+    it('adds, lists and removes the items', async (): Promise<void> => {
+        assert.deepStrictEqual((await request('GET', '/api/items')).data, [])
+        await request('POST', '/api/items', {name: 'Milk'})
+        const added = await request('POST', '/api/items', {name: '  Bread  '})
+        assert.deepStrictEqual(added.data, [{id: 1, name: 'Milk'}, {id: 2, name: 'Bread'}])
+        assert.deepStrictEqual((await request('DELETE', '/api/items/1')).data, [{id: 2, name: 'Bread'}])
+        //Removing it again changes nothing: someone else may have removed it first
+        assert.deepStrictEqual((await request('DELETE', '/api/items/1')).data, [{id: 2, name: 'Bread'}])
+        assert.deepStrictEqual((await request('GET', '/api/items')).data, [{id: 2, name: 'Bread'}])
+    })
+
+    it('refuses an item without a name', async (): Promise<void> => {
+        assert.deepStrictEqual(await request('POST', '/api/items', {name: ' '}), {errno: 'E_INVALID_VALUE', errMsg: '"name" is not allowed to be empty', data: null})
+    })
+
+    it('serves the page of the list', async (): Promise<void> => {
+        const response: Response = await fetch(`http://127.0.0.1:${PORT}/`, {headers: {Accept: 'text/html'}})
+        assert.strictEqual(response.status, 200)
+        assert.match(await response.text(), /<div id="root"><\/div>/)
+    })
+})
+```
+
+```bash
+npm test
+```
+
+```
+app │   ✔ adds, lists and removes the items
+app │   ✔ refuses an item without a name
+app │   ✔ serves the page of the list
+app │ ℹ pass 3
+✔ test ran in app
+```
+
+`npm test` builds the packages first, so the built page is there for the last test. The tests cover the API, not the
+React code; `npm run typecheck -w ui` checks the types of the page, which the Vite build does not.
+
+## 10. Build it
+
+```bash
+npm run build
+```
+
+```
+ui  │ dist/index.html                  0.31 kB │ gzip:  0.22 kB
+ui  │ dist/assets/index-D0SES_81.js  220.75 kB │ gzip: 69.11 kB
+ui  │ ✓ built in 49ms
+app │ > tsc
+✔ rebuild ran in ui, app
+```
+
+The `ui` package is built first, as the application depends on it (`"ui": "^0.0.1"` in its `package.json`): Vite
+writes the page into `packages/ui/dist`, then `tsc` compiles the application into `packages/app/build`.
+
+```bash
+npm start
+```
+
+The application now serves both the API and the page, from one process and one port: http://localhost:8080. It
+listens on all interfaces, so the phones on the network open the page at the computer's address, on port 8080.
+
+```bash
+curl -i localhost:8080/ -H 'Accept: text/html'
+# HTTP/1.1 200 OK
+# Cache-Control: no-cache
+# Content-Type: text/html; charset=utf-8
+#
+# <!doctype html>
+# ...
+#     <script type="module" crossorigin src="/assets/index-D0SES_81.js"></script>
+# ...
+
+curl -I localhost:8080/assets/index-D0SES_81.js
+# HTTP/1.1 200 OK
+# Cache-Control: public, max-age=31536000, immutable
+# Content-Type: text/javascript; charset=utf-8
+```
+
+Browsers check `index.html` again on each request, and keep the scripts for a year, as their names hold a hash of
+their content: a new build shows up at once.
+
+## 11. Package it
+
+The `package.json` of the application, from the template, declares the built page as a resource:
+
+```json
+"lakutata": {
+  "resources": [
+    {
+      "from": "../ui/dist",
+      "to": "ui"
+    }
+  ]
+}
+```
+
+A packed application carries its resources, and `resourcesPath()` gives their directory, where `uiDirectory()`
+(section 5) finds the page ([Packaging](../Packaging.md)). A bundle, for example:
+
+```bash
+npm install --save-dev @lakutata/builder
+npm run build
+cd packages/app
+npx lakutata package bundle
+```
+
+```
+✔ dist/app.cjs (1.7 MB): node dist/app.cjs
+✔ dist/app.resources: the resources (ui), distributed with the bundle
+```
+
+`dist/app.cjs` and `dist/app.resources` are the whole application: copy them together to a machine with Node.js, and
+`node app.cjs` serves the API and the page, without `node_modules`.
+
+- `npm run docker:build` builds the image of the application with the `Dockerfile` of the template, page included.
+- The list is lost when the application stops: keep it in a database, as in
+  [A REST API with a database](RestAPI.md).
+- Anyone who can reach the application can change the list. Outside a home network, put it behind a reverse proxy
+  that asks for a login, or authenticate the users in a middleware ([Middlewares](../Middlewares.md)).
+
+<!--
+check:
+  create: shopping web-react
+  remove: packages/app/src/controllers/ExampleController.ts packages/app/src/dtos/GreetDTO.ts
+  remove: packages/app/src/middlewares/Authenticate.ts
+  run: npm test
+  run: npm run typecheck -w ui
+  run: cd packages/app && npx lakutata package bundle && test -f dist/app.resources/ui/index.html
+-->

package/doc/zh/Application.md

@@ -0,0 +1,75 @@
+# Lakutata 应用
+
+**应用**是 Lakutata 程序的根对象。`Application.run()` 在一个新的根容器中创建它，注册它声明的对象，依次执行 bootstrap 步骤，并在收到退出信号时优雅地结束。本页介绍应用的选项、链式 API、生命周期、运行模式和打包后的应用。应用创建的对象见 [Objects](Objects.md)，对象之间如何获取彼此见 [Injection](Injection.md)。
+
+## 1. 选项
+
+`Application.run(options)`（或 `run(() => options)`，在启动时调用该函数，可以是异步的）接受以下选项：
+
+| 选项 | 含义 |
+|---|---|
+| `id`、`name` | 必填。应用的 ID（同时作为 `process.title`）和名称（`app.appId`、`app.appName`） |
+| `timezone` | IANA 时区名，或 `'auto'`（默认）表示使用系统时区；写入 `TZ` |
+| `mode` | `'development'` 或 `'production'`，在环境变量未指定时生效（见第 4 节） |
+| `shutdownSignals` | 使应用优雅退出的信号（默认 `['SIGTERM', 'SIGINT']`），或 `false` |
+| `components`、`providers` | 按名称声明的组件和提供者：`{class, ...options}` |
+| `objects` | 其他对象：`{named: {...}, anonymous: [...]}` |
+| `bootstrap` | 启动时依次执行的步骤：名称、symbol 或类（创建该对象），或以应用为参数调用的异步函数 |
+| `checkOptions` | 启动时检查所声明对象的选项（默认 `true`） |
+
+不带 `class` 的声明会补充框架预置的同名对象的选项：`lakutata` 包预置了 `log`（`Logger`）和 `entrypoint`（`Entrypoint`），因此 `log: {level: 'debug'}` 会设置预置日志组件的级别。`Application.preset(options)` 为进程中的所有应用预置对象。
+
+## 2. 链式 API
+
+```typescript
+import {Application, type ApplicationExitReason, type ILogger} from 'lakutata'
+
+Application
+    //环境变量，在启动时、调用选项函数之前设置
+    .env({TZ_NAME: 'Asia/Shanghai'})
+    //路径别名：传给 path.resolve() 或 app.alias.resolve() 的路径中的 '@data'；目录不存在时创建
+    .alias({'@data': './data'}, true)
+    .run(() => ({
+        id: 'com.example.app',
+        name: 'Example',
+        components: {}
+    }))
+    //bootstrap 完成后调用（不会被等待）
+    .onLaunched((app: Application, log: ILogger): void => log.info('%s launched in %s mode', app.appName, app.mode()))
+    //应用退出时、对象销毁之前调用，会被等待
+    .onDone(async (app: Application, log: ILogger, reason: ApplicationExitReason): Promise<void> => {
+        log.info('%s done (exit code %d%s)', app.appName, reason.code, reason.signal ? `, ${reason.signal}` : '')
+    })
+    //进程中未捕获的异常，应用继续运行
+    .onUncaughtException((error: Error, log: ILogger): void => log.warn(error.message))
+    //启动失败：返回的数字作为退出码（未返回时为 1）
+    .onFatalException((error: Error, log: ILogger): number => {
+        log.error('Launch failed: %s', error.message)
+        return 100
+    })
+```
+
+`app.exit(code)` 以指定退出码优雅地结束应用；`app.exit(true)` 立即以退出码 2 结束进程，不执行 `onDone` 处理函数，也不销毁对象。
+
+## 3. 生命周期
+
+1. 设置环境变量，注册路径别名（`@runtime` 为当前工作目录）。
+2. 读取并校验选项；应用 ID、时区和运行模式。
+3. 在新的根容器中创建应用：注册它的对象，并依次执行 `bootstrap`。
+4. 执行各对象的 `launched()` 钩子和 `onLaunched` 处理函数。
+
+- **启动失败**：应用无法启动时（选项不合法、对象初始化失败、bootstrap 步骤失败），由 `onFatalException` 的处理函数决定退出码（没有返回时为 1）。没有注册处理函数时，框架记录错误后以退出码 1 退出，和 Node.js 处理未捕获异常的方式一致，这样运行它的工具（Docker 的重启策略、Kubernetes、systemd、CI）都能知道启动失败了；已经创建的对象（正在监听的服务、数据库连接等）也不会让进程继续挂着。
+- **退出信号**：收到 `SIGTERM`（`docker stop`、Kubernetes 滚动更新、systemd 停止服务）或 `SIGINT`（Ctrl+C）时，应用会优雅退出：先执行 `onDone` 处理函数，此时应用仍然完全可用（第三个参数说明退出原因：收到信号时是 `{code: 0, signal: 'SIGTERM'}`，调用 `app.exit(code)` 时是 `{code}`）；然后各入口停止接收新请求并等待正在处理的请求完成，各对象被销毁，最后以退出码 0 退出。如果再次收到信号（比如退出过程卡住了），或者信号是在应用启动期间收到的，进程会立即以 128 + 信号编号退出（`SIGTERM` 为 143，`SIGINT` 为 130）。选项 `shutdownSignals` 可以指定其他信号（如 `['SIGTERM', 'SIGINT', 'SIGHUP']`），设为 `false` 则交由 Node.js 处理。
+- **没有事情可做时**：当没有任何东西让进程继续运行时（没有服务、连接或定时器），应用会像调用 `app.exit(0)` 一样优雅退出：执行 `onDone` 处理函数，销毁对象，然后以进程当前的退出码（`process.exitCode`，默认 0）退出。所以脚本做完工作直接结束即可。已经被销毁的应用（例如测试中调用了 `app.dispose()`）则把进程何时结束交给运行它的程序。
+
+## 4. 运行模式
+
+`app.mode()` 返回 `'development'` 或 `'production'`。环境变量会覆盖代码里的配置，同一份构建产物可以在不同模式下运行：依次看环境变量 `MODE`、`NODE_ENV`，然后是选项 `mode`，都没有时为 `'development'`。不是这两个值的 `MODE` 会发出警告并被忽略，不是这两个值的 `NODE_ENV`（如 `test`）会被跳过。确定的模式会写回 `MODE` 和 `NODE_ENV`，第三方库读到的也是同一个模式。环境变量可以来自系统、`Application.env({MODE: 'production'})`，或者 Bun 读取的 `.env` 文件（指 `bun App.js` 这种运行方式；Bun 构建的可执行文件不会读取它）。
+
+## 5. 打包后的应用
+
+`lakutata package bundle`、`package exe` 和 `package installer` 把编译好的应用打包成单文件包、可执行文件或安装包。以打包形式运行时，`isPackaged()`（来自 `lakutata`）返回 `true`，`resourcesPath()` 返回资源所在的目录，资源就是 `package.json` 的 `lakutata.resources` 中声明的文件；未打包时，它返回 `undefined`，应用从这些文件的构建位置读取它们。详见 [Packaging](Packaging.md)。
+
+## 6. 入口
+
+`entrypoint` 组件（`lakutata/com/entrypoint`）通过 HTTP、CLI、服务传输、定时任务和消息队列对外提供控制器。用 `buildEntrypoints({controllers, http, cli, service, schedule, queue})` 配置它，并把它列入 `bootstrap`；详见 [Entrypoint](Entrypoint.md)。