lakutata 3.0.0 → 3.1.0

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-![lakutata](https://socialify.git.ci/lakutata/lakutata/image?description=1&descriptionEditable=An%20IoC-based%20universal%20application%20framework&font=Source%20Code%20Pro&forks=1&language=1&logo=https%3A%2F%2Fraw.githubusercontent.com%2Flakutata%2Flakutata%2Fmain%2Fassets%2Flogo.svg&name=1&pattern=Circuit%20Board&stargazers=1&theme=Auto)
+![lakutata](https://socialify.git.ci/lakutata/lakutata/image?description=1&descriptionEditable=An%20IoC%20application%20framework%20for%20Node.js%20and%20TypeScript&font=Source%20Code%20Pro&forks=1&language=1&logo=https%3A%2F%2Fraw.githubusercontent.com%2Flakutata%2Flakutata%2Fmain%2Fpackages%2Flakutata%2Fassets%2Flogo.svg&name=1&pattern=Circuit%20Board&stargazers=1&theme=Auto)
 
 </div>
 
@@ -14,18 +14,19 @@
 
 </div>
 
+English | [中文](README.zh-CN.md)
 
 # lakutata
 
-An IoC-based application framework for Node.js and TypeScript: one programming model for web services, CLI tools,
-desktop (Electron) applications and embedded devices. An application is a tree of objects created by a container
-(components, providers, controllers), validated by DTOs, and served by transports: HTTP (Express, Fastify), CLI
-(Commander), service RPC (HTTP, Socket.IO, JSON-RPC 2.0, gRPC, NATS, Electron IPC) and schedules — one controller method
-can be all of them at once.
+An IoC-based application framework for Node.js and TypeScript, with one programming model for web services, CLI tools,
+desktop (Electron) applications and embedded devices. An application is a tree of objects (components, providers,
+controllers) that a container creates. DTOs validate their options and inputs, and transports expose the controllers:
+HTTP (Express, Fastify), CLI (Commander), service RPC (HTTP, Socket.IO, JSON-RPC 2.0, gRPC, NATS, Electron IPC),
+schedules and message queues. One controller method can serve all of them at once.
 
-This package is the framework: it re-exports the `@lakutata/*` packages under the subpaths listed below, and presets
-the `log` (pino) and `entrypoint` components of the applications. Each subpath's typings document every declaration
-with examples; each `@lakutata/*` package has its own README.
+This package is the framework itself: it re-exports the `@lakutata/*` packages under the subpaths listed below and
+presets two components in every application, `log` and `entrypoint`. The typings of each subpath document every
+declaration with examples, and each `@lakutata/*` package has its own README.
 
 ## Installation
 
@@ -34,19 +35,27 @@ npx @lakutata/cli create --name my-app   # a new project from a template (web, s
 npm install lakutata                      # or the framework in an existing project
 ```
 
-Node.js 22 or later, ESM (`"type": "module"`). The TypeScript options the framework needs are published as
-`lakutata/tsconfig.json`:
+The framework needs Node.js `^22.13.0 || >=24.11.0`: 22.13 or a later 22.x, or 24.11 and later (not 23). Projects
+use ES modules (`"type": "module"`), as the templates do; the package also ships CommonJS builds. The TypeScript
+options that the framework needs are published as `lakutata/tsconfig.json`:
 
 ```json
 {
   "extends": "lakutata/tsconfig.json",
-  "compilerOptions": {"rootDir": "src", "outDir": "dist"}
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "build"
+  },
+  "include": ["src"]
 }
 ```
 
-The transports and the integrations use optional peer dependencies, installed when used: `express` or `fastify`,
-`commander`, `socket.io`, `ws`, the database drivers (`pg`, `mysql2`, `sqlite3`…), the cache stores (`redis`…), see each
-package's README.
+Keep `include`: the published options compile JavaScript files too (`allowJs`), so without it a configuration file at
+the root of the project (`eslint.config.js`, `vite.config.ts`) breaks the build.
+
+The transports and integrations rely on optional peer dependencies, which you install only when you use them: `express`
+or `fastify`, `commander`, `socket.io`, `ws`, the database drivers (`pg`, `mysql2`, `better-sqlite3`…) and the cache
+stores (`redis`…). Each package's README lists its own.
 
 ## Usage
 
@@ -90,45 +99,56 @@ Application
 
 | Subpath | Package | What it provides |
 |---|---|---|
-| `lakutata` | `@lakutata/core` | `Application`, `Module`, `Component`, `Provider`, `BaseObject`, `Container`, `DTO`, `Exception`, `Time`, the validation schemas and messages |
-| `lakutata/decorator/di` | `@lakutata/core` | `@Inject`, `@Configurable`, `@Autoload`, `@Singleton`, `@Scoped`, `@Transient` |
+| `lakutata` | `@lakutata/core` | `Application`, `Component`, `Provider`, `BaseObject`, `Container`, `DTO`, `Exception`, `Time`, `isPackaged`, `resourcesPath`, the validation schemas and messages |
+| `lakutata/decorator/di` | `@lakutata/core` | `@Inject`, `@Configurable`, `@Autoload`, `@Lifetime`, `@Singleton`, `@Scoped`, `@Transient` |
 | `lakutata/decorator/dto` | `@lakutata/core` | `@Expect`, `@Accept`, `@Return`, `@IndexSignature` |
 | `lakutata/decorator/asst` | `@lakutata/core` | `@Before`, `@After` |
 | `lakutata/dtos` | `@lakutata/core` | `PaginationSearchDTO`, `PaginationResultDTO`, `paginator`, `FlexibleDTO`, the JSON Schema conversion |
 | `lakutata/com/entrypoint` | `@lakutata/entrypoint` | `Entrypoint`, `buildEntrypoints`, `Controller`, the contexts, the results, the access control, the middlewares, `httpServiceEntrypoint`, `scheduleEntrypoint` |
 | `lakutata/decorator/ctrl` | `@lakutata/entrypoint` | `@HTTPAction`, `@GET`…`@OPTIONS`, `@CLIAction`, `@ServiceAction`, `@Schedule`, `@Prefix`, `@UseMiddlewares` |
-| `lakutata/adapter/express`, `lakutata/adapter/fastify` | `@lakutata/entrypoint` | The HTTP transports, `staticUI` |
+| `lakutata/adapter/express`, `lakutata/adapter/fastify` | `@lakutata/entrypoint` | The HTTP transports, `staticUI` (Express only) |
 | `lakutata/adapter/commander` | `@lakutata/entrypoint` | The CLI transport |
 | `lakutata/adapter/socket.io`, `lakutata/adapter/jsonrpc`, `lakutata/adapter/electron` | `@lakutata/entrypoint` | The service transports |
-| `lakutata/com/logger` | `@lakutata/logger` | The `Logger` component (pino) preset as `log` |
+| `lakutata/com/logger` | `@lakutata/logger` | The `Logger` component preset as `log` (pino-compatible JSON lines) |
 | `lakutata/orm`, `lakutata/decorator/orm` | `@lakutata/orm` | TypeORM, its decorators |
 | `lakutata/com/database`, `lakutata/provider/database` | `@lakutata/orm` | The `Database` component and provider, the migration commands |
 | `lakutata/com/cacher` | `@lakutata/cache` | The `Cacher` component: memory, file, Redis, Memcached, MongoDB, SQLite, PostgreSQL, MySQL stores |
 | `lakutata/com/mutex` | `@lakutata/mutex` | The `Mutex` component, `@Synchronized` |
+| `lakutata/com/queue` | `@lakutata/queue` | The `Queue` component, `@QueueAction`, `queueEntrypoint`: message queues in memory, Redis (BullMQ), NATS JetStream, RabbitMQ or Kafka |
 | `lakutata/com/i18n` | `@lakutata/i18n` | The `I18n` component, the `Translator`, the language middleware |
 | `lakutata/com/docker` | `@lakutata/docker` | The `Docker` component |
 | `lakutata/com/containerd` | `@lakutata/containerd` | The `Containerd` component (containerd without Docker, BuildKit builds) |
 | `lakutata/com/monitor` | `@lakutata/monitor` | The CPU, memory, event loop and HTTP monitors |
 | `lakutata/security`, `lakutata/provider/passwordHash` | `@lakutata/security` | Hashing, ciphers, signatures, the `PasswordHash` provider |
 | `lakutata/utils` | `@lakutata/utils` | The helpers (strings, objects, arrays, time, files, globs, encodings, guards) |
-| `lakutata/tsconfig.json` | | The compiler options of the applications |
+| `lakutata/tsconfig.json` | | The compiler options for applications |
 
-Outside this package: `@lakutata/cli` (the `lakutata` command: projects, bundles, executables, installers, migrations),
-`@lakutata/grpc` (gRPC client, server and service transport), `@lakutata/nats` (NATS component and service transport),
-`@lakutata/dbus` (D-Bus), `@lakutata/mcp` (the Model Context Protocol).
+Not part of this package: `@lakutata/cli` (the `lakutata` command for projects, bundles, executables, installers and
+migrations), `@lakutata/grpc` (a gRPC client, server and service transport), `@lakutata/nats` (a NATS component and
+service transport), `@lakutata/dbus` (D-Bus) and `@lakutata/mcp` (the Model Context Protocol).
 
 ## Errors
 
-The framework's exceptions extend `Exception` (from `lakutata`): an `errno` (`E_…`), a `message`, the application's id
-and name, and a `statusCode` the HTTP transports answer with (500 by default; 400 for an invalid input, 403 for a denied
-access, 404 for a missing route or action, 409 for a lock not acquired…). Each package's README lists its exceptions.
+The framework's exceptions extend `Exception` (from `lakutata`). Each one has an `errno` (`E_…`), a `message`, the
+application's id and name, and a `statusCode` that the HTTP transports use as the response status: 500 by default, 400
+for invalid input, 403 when access is denied, 404 for a missing route or action, 409 when a lock is not acquired, and so
+on. Each package's README lists its exceptions.
 
 ## See also
 
-- The guides, in this package: `doc/en` (English) and `doc/zh` (Chinese): `Overview.md`, `Core.md`, `DTOValidation.md`,
-  `Decorator.md`, `ActionPattern.md`, `ORMIntegration.md`, `I18n.md`, `Mutex.md`, `DockerIntegration.md`,
-  `ContainerdIntegration.md`, `Security.md`, `Time.md`, `HelperFunctions.md`.
-- `@lakutata/cli`: creating, building and packaging the applications.
+- The website, [lakutata.com](https://lakutata.com): the guides, the examples and the API reference, in English and in
+  Chinese.
+- The guides, in this package: `doc/en` (English) and `doc/zh` (Chinese): `Overview.md`, `GettingStarted.md`,
+  `ProjectStructure.md`, `UpgradingFrom2.md`, `UpgradingFrom1.md`, `Application.md`, `Objects.md`, `Injection.md`,
+  `DTOValidation.md`, `Exceptions.md`, `Logger.md`, `Decorator.md`, `Time.md`, `HelperFunctions.md`, `Controllers.md`,
+  `Entrypoint.md`, `Middlewares.md`, `HTTP.md`, `CLI.md`, `ServiceCalls.md`, `GRPC.md`, `NATS.md`, `Schedules.md`,
+  `Queue.md`, `Database.md`, `DatabaseDrivers.md`, `MongoEmbedded.md`, `Entities.md`, `Migrations.md`, `Cache.md`,
+  `Mutex.md`, `I18n.md`, `DockerIntegration.md`, `ContainerdIntegration.md`, `Monitor.md`, `Security.md`, `DBus.md`,
+  `MCP.md`, `Command.md`, `Workspaces.md`, `NativeAddons.md`, `Packaging.md`, `Installers.md`; and the examples, in
+  `doc/en/examples` and `doc/zh/examples`: whole applications built from the templates.
+- `@lakutata/cli`: creating, building and packaging applications.
+- The official Agent Skill for AI coding assistants that work on lakutata projects:
+  [lakutata.com/skill](https://lakutata.com/skill/).
 
 ## License
 

package/README.zh-CN.md

@@ -0,0 +1,130 @@
+<div align="center">
+
+![lakutata](https://socialify.git.ci/lakutata/lakutata/image?description=1&descriptionEditable=An%20IoC%20application%20framework%20for%20Node.js%20and%20TypeScript&font=Source%20Code%20Pro&forks=1&language=1&logo=https%3A%2F%2Fraw.githubusercontent.com%2Flakutata%2Flakutata%2Fmain%2Fpackages%2Flakutata%2Fassets%2Flogo.svg&name=1&pattern=Circuit%20Board&stargazers=1&theme=Auto)
+
+</div>
+
+<div align="center">
+
+![node-lts](https://img.shields.io/node/v-lts/lakutata?style=for-the-badge&logo=nodedotjs&color=rgb(128%2C189%2C65))
+![npm](https://img.shields.io/npm/v/lakutata?style=for-the-badge&logo=npm&color=rgb(128%2C189%2C65))
+![npm](https://img.shields.io/npm/dm/lakutata?style=for-the-badge&logo=npm&color=rgb(128%2C189%2C65))
+![NPM](https://img.shields.io/npm/l/lakutata?style=for-the-badge&logo=github&color=rgb(128%2C189%2C65))
+![Codacy grade](https://img.shields.io/codacy/grade/0f16d1c355494415ad7733f8f22f7d36?style=for-the-badge&logo=codacy)
+
+</div>
+
+[English](README.md) | 中文
+
+# lakutata
+
+一个基于 IoC 的 Node.js 和 TypeScript 应用框架，让 Web 服务、命令行工具、桌面（Electron）应用和嵌入式设备共用同一套编程模型。应用是一棵由容器创建的对象树（组件、提供者、控制器）。DTO 校验对象的选项和输入，各种传输方式把控制器暴露出去：HTTP（Express、Fastify）、CLI（Commander）、服务调用（HTTP、Socket.IO、JSON-RPC 2.0、gRPC、NATS、Electron IPC）、定时任务和消息队列。同一个控制器方法可以同时通过所有这些方式调用。
+
+这个包就是框架本身：它通过下面列出的子路径重新导出各个 `@lakutata/*` 包，并为每个应用预置两个组件：`log` 和 `entrypoint`。各子路径的类型声明中，每一项都附有说明和示例，每个 `@lakutata/*` 包也都有自己的 README。
+
+## 安装
+
+```shell
+npx @lakutata/cli create --name my-app   # 用模板创建新项目（Web、服务、CLI、Electron……）
+npm install lakutata                      # 或者在已有项目中安装框架
+```
+
+框架需要 Node.js `^22.13.0 || >=24.11.0`：22.13 或更高的 22.x 版本，或者 24.11 及以上（不支持 23）。项目使用 ES 模块（`"type": "module"`），模板也是如此；这个包也提供 CommonJS 版本。框架需要的 TypeScript 选项发布为 `lakutata/tsconfig.json`：
+
+```json
+{
+  "extends": "lakutata/tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "build"
+  },
+  "include": ["src"]
+}
+```
+
+请保留 `include`：发布的选项也会编译 JavaScript 文件（`allowJs`），没有它的话，项目根目录下的配置文件（`eslint.config.js`、`vite.config.ts`）会让构建失败。
+
+传输方式和各项集成所需的 peer 依赖都是可选的，用到时才需要安装：`express` 或 `fastify`、`commander`、`socket.io`、`ws`、数据库驱动（`pg`、`mysql2`、`better-sqlite3`……）以及缓存存储（`redis`……）。各个包的 README 列出了各自需要的依赖。
+
+## 用法
+
+```typescript
+import {Application, DTO, type ILogger} from 'lakutata'
+import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+import {GET, ServiceAction} from 'lakutata/decorator/ctrl'
+import {Expect} from 'lakutata/decorator/dto'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+
+class GreetDTO extends DTO {
+    @Expect(DTO.String().optional().default('world'))
+    public name: string
+}
+
+class GreetController extends Controller {
+    //GET /greet?name=you，以及服务动作 {cmd: 'greet', name: 'you'}
+    @GET('/greet', GreetDTO)
+    @ServiceAction({cmd: 'greet'}, GreetDTO)
+    public async greet(input: GreetDTO): Promise<{ message: string }> {
+        return {message: `Hello, ${input.name}!`}
+    }
+}
+
+Application
+    .run(() => ({
+        id: 'com.example.greeter',
+        name: 'Greeter',
+        components: {
+            entrypoint: buildEntrypoints({
+                controllers: [GreetController],
+                http: expressHTTPEntrypoint({port: 8080})
+            })
+        },
+        bootstrap: ['entrypoint']
+    }))
+    .onLaunched((app: Application, log: ILogger): void => log.info('%s started', app.appName))
+```
+
+## API
+
+| 子路径 | 包 | 提供什么 |
+|---|---|---|
+| `lakutata` | `@lakutata/core` | `Application`、`Component`、`Provider`、`BaseObject`、`Container`、`DTO`、`Exception`、`Time`、`isPackaged`、`resourcesPath`、校验规则和校验消息 |
+| `lakutata/decorator/di` | `@lakutata/core` | `@Inject`、`@Configurable`、`@Autoload`、`@Lifetime`、`@Singleton`、`@Scoped`、`@Transient` |
+| `lakutata/decorator/dto` | `@lakutata/core` | `@Expect`、`@Accept`、`@Return`、`@IndexSignature` |
+| `lakutata/decorator/asst` | `@lakutata/core` | `@Before`、`@After` |
+| `lakutata/dtos` | `@lakutata/core` | `PaginationSearchDTO`、`PaginationResultDTO`、`paginator`、`FlexibleDTO`、JSON Schema 转换 |
+| `lakutata/com/entrypoint` | `@lakutata/entrypoint` | `Entrypoint`、`buildEntrypoints`、`Controller`、各种上下文、各种结果、访问控制、中间件、`httpServiceEntrypoint`、`scheduleEntrypoint` |
+| `lakutata/decorator/ctrl` | `@lakutata/entrypoint` | `@HTTPAction`、`@GET`…`@OPTIONS`、`@CLIAction`、`@ServiceAction`、`@Schedule`、`@Prefix`、`@UseMiddlewares` |
+| `lakutata/adapter/express`、`lakutata/adapter/fastify` | `@lakutata/entrypoint` | HTTP 传输、`staticUI`（仅 Express） |
+| `lakutata/adapter/commander` | `@lakutata/entrypoint` | CLI 传输 |
+| `lakutata/adapter/socket.io`、`lakutata/adapter/jsonrpc`、`lakutata/adapter/electron` | `@lakutata/entrypoint` | 服务传输 |
+| `lakutata/com/logger` | `@lakutata/logger` | `Logger` 组件，预置为 `log`（输出与 pino 兼容的 JSON 行） |
+| `lakutata/orm`、`lakutata/decorator/orm` | `@lakutata/orm` | TypeORM 及其装饰器 |
+| `lakutata/com/database`、`lakutata/provider/database` | `@lakutata/orm` | `Database` 组件和提供者、迁移命令 |
+| `lakutata/com/cacher` | `@lakutata/cache` | `Cacher` 组件：存储可以是内存、文件、Redis、Memcached、MongoDB、SQLite、PostgreSQL、MySQL |
+| `lakutata/com/mutex` | `@lakutata/mutex` | `Mutex` 组件、`@Synchronized` |
+| `lakutata/com/queue` | `@lakutata/queue` | `Queue` 组件、`@QueueAction`、`queueEntrypoint`：基于内存、Redis（BullMQ）、NATS JetStream、RabbitMQ 或 Kafka 的消息队列 |
+| `lakutata/com/i18n` | `@lakutata/i18n` | `I18n` 组件、`Translator`、语言中间件 |
+| `lakutata/com/docker` | `@lakutata/docker` | `Docker` 组件 |
+| `lakutata/com/containerd` | `@lakutata/containerd` | `Containerd` 组件（不依赖 Docker 的 containerd，用 BuildKit 构建镜像） |
+| `lakutata/com/monitor` | `@lakutata/monitor` | CPU、内存、事件循环和 HTTP 监控器 |
+| `lakutata/security`、`lakutata/provider/passwordHash` | `@lakutata/security` | 哈希、加解密、签名、`PasswordHash` 提供者 |
+| `lakutata/utils` | `@lakutata/utils` | 辅助函数（字符串、对象、数组、时间、文件、glob、编码、类型守卫） |
+| `lakutata/tsconfig.json` | | 应用的编译选项 |
+
+不在本包中的：`@lakutata/cli`（`lakutata` 命令：创建项目，制作单文件包、可执行文件和安装包，执行迁移）、`@lakutata/grpc`（gRPC 客户端、服务端和服务传输）、`@lakutata/nats`（NATS 组件和服务传输）、`@lakutata/dbus`（D-Bus）和 `@lakutata/mcp`（模型上下文协议）。
+
+## 错误
+
+框架的异常都继承自 `Exception`（来自 `lakutata`）。每个异常都有 `errno`（`E_…`）、`message`、应用的 ID 和名称，以及 `statusCode`，HTTP 传输把它用作响应的状态码：默认是 500，输入无效时是 400，访问被拒绝时是 403，路由或动作不存在时是 404，没有拿到锁时是 409，等等。各个包的 README 列出了各自的异常。
+
+## 另见
+
+- 网站 <https://lakutata.com/zh/>：指南、示例和 API 参考，中英文都有。
+- 指南在这个包的 `doc/zh`（中文）和 `doc/en`（英文）中：`Overview.md`、`GettingStarted.md`、`ProjectStructure.md`、`UpgradingFrom2.md`、`UpgradingFrom1.md`、`Application.md`、`Objects.md`、`Injection.md`、`DTOValidation.md`、`Exceptions.md`、`Logger.md`、`Decorator.md`、`Time.md`、`HelperFunctions.md`、`Controllers.md`、`Entrypoint.md`、`Middlewares.md`、`HTTP.md`、`CLI.md`、`ServiceCalls.md`、`GRPC.md`、`NATS.md`、`Schedules.md`、`Queue.md`、`Database.md`、`DatabaseDrivers.md`、`MongoEmbedded.md`、`Entities.md`、`Migrations.md`、`Cache.md`、`Mutex.md`、`I18n.md`、`DockerIntegration.md`、`ContainerdIntegration.md`、`Monitor.md`、`Security.md`、`DBus.md`、`MCP.md`、`Command.md`、`Workspaces.md`、`NativeAddons.md`、`Packaging.md`、`Installers.md`；示例在 `doc/zh/examples` 和 `doc/en/examples` 中：从模板构建的完整应用。
+- `@lakutata/cli`：创建、构建和打包应用。
+- 官方 Agent Skill（智能体技能），供 AI 编程助手在 lakutata 项目中使用：<https://lakutata.com/zh/skill/>。
+
+## 许可证
+
+Lakutata 使用 [MIT 许可证](LICENSE)。

package/dist/cjs/exports/QueueComponent.d.ts

@@ -0,0 +1 @@
+export * from '@lakutata/queue';

package/dist/cjs/exports/QueueComponent.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("@lakutata/queue"), exports);
+
+//The default of the entry: the entry itself (scripts/package-build/cjs-package.mjs)
+if (!Object.prototype.hasOwnProperty.call(exports, 'default')) Object.defineProperty(exports, 'default', {value: exports})

package/dist/esm/exports/QueueComponent.js

@@ -0,0 +1 @@
+export * from '@lakutata/queue';

package/dist/types/exports/QueueComponent.d.ts

@@ -0,0 +1 @@
+export * from '@lakutata/queue';

package/doc/en/Application.md

@@ -0,0 +1,107 @@
+# Lakutata Application
+
+The **application** is the root object of a Lakutata program. `Application.run()` creates it in a new root container,
+registers the objects it declares, runs its bootstrap steps, and ends it gracefully on a shutdown signal. This page
+covers its options, the fluent API, the lifecycle, the mode and packed applications. The objects it creates are
+described in [Objects](Objects.md), and how they obtain one another in [Injection](Injection.md).
+
+## 1. Options
+
+`Application.run(options)` — or `run(() => options)`, a function called at launch that may be async — takes these
+options:
+
+| Option | Meaning |
+|---|---|
+| `id`, `name` | Required. The ID (also the `process.title`) and the name of the application (`app.appId`, `app.appName`) |
+| `timezone` | An IANA time zone, or `'auto'` (default) for the system's; written to `TZ` |
+| `mode` | `'development'` or `'production'`, when the environment gives none (see section 4) |
+| `shutdownSignals` | The signals that end the application gracefully (default `['SIGTERM', 'SIGINT']`), or `false` |
+| `components`, `providers` | The components and providers by name: `{class, ...options}` |
+| `objects` | Other objects: `{named: {...}, anonymous: [...]}` |
+| `bootstrap` | The steps run in order at launch: a name, a symbol or a class (the object is created), or an async function that receives the application |
+| `checkOptions` | Check the options of the declared objects at launch (default `true`) |
+
+A declaration without `class` adds options to an object of the same name that the framework presets: the `lakutata`
+package presets `log` (the `Logger`) and `entrypoint` (the `Entrypoint`), so `log: {level: 'debug'}` sets the level of
+the preset logger. `Application.preset(options)` presets objects for every application in the process.
+
+## 2. The fluent API
+
+```typescript
+import {Application, type ApplicationExitReason, type ILogger} from 'lakutata'
+
+Application
+    //Environment variables, set at launch before the options function runs
+    .env({TZ_NAME: 'Asia/Shanghai'})
+    //Path aliases: '@data' in a path passed to path.resolve() or app.alias.resolve(); the directory is created when missing
+    .alias({'@data': './data'}, true)
+    .run(() => ({
+        id: 'com.example.app',
+        name: 'Example',
+        components: {}
+    }))
+    //Called once the bootstrap has completed (not awaited)
+    .onLaunched((app: Application, log: ILogger): void => log.info('%s launched in %s mode', app.appName, app.mode()))
+    //Called and awaited when the application exits, before its objects are destroyed
+    .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}` : '')
+    })
+    //An uncaught exception in the process; the application keeps running
+    .onUncaughtException((error: Error, log: ILogger): void => log.warn(error.message))
+    //The launch failed: the returned number is the exit code (1 when none)
+    .onFatalException((error: Error, log: ILogger): number => {
+        log.error('Launch failed: %s', error.message)
+        return 100
+    })
+```
+
+`app.exit(code)` ends the application gracefully with that exit code; `app.exit(true)` ends the process immediately with
+exit code 2, skipping the done handlers and the teardown.
+
+## 3. The lifecycle
+
+1. The environment variables are set and the aliases registered (`@runtime` is the working directory).
+2. The options are read and validated; the ID, the time zone and the mode are applied.
+3. The application is created in a new root container: its objects are registered and its `bootstrap` runs in order.
+4. The `launched()` hooks of the objects and the `onLaunched` handlers run.
+
+- **Launch failure**: when the application cannot launch (invalid options, an object that fails to initialize, a
+  bootstrap step that fails), the `onFatalException` handler decides the exit code (1 when it returns none). Without a
+  handler, the error is logged and the process exits with code 1, as Node.js does on an uncaught exception, so whatever
+  runs it (Docker restart policies, Kubernetes, systemd, CI) knows it failed; objects already created (a listening
+  server, a connection) do not keep the process alive.
+- **Shutdown signals**: on `SIGTERM` (`docker stop`, Kubernetes rolling updates, systemd) and `SIGINT` (Ctrl+C), the
+  application ends gracefully. The `onDone` handlers run first, while the application is still fully working (their
+  third argument says why it is exiting: `{code: 0, signal: 'SIGTERM'}`, or `{code}` after `app.exit(code)`). Then the
+  entrypoints stop accepting requests and let the running ones finish, the objects are destroyed, and the process exits
+  with code 0. A second signal (if the shutdown hangs), or a signal received while the application is still launching,
+  ends the process at once with code 128 + the signal number (143 for `SIGTERM`, 130 for `SIGINT`). The
+  `shutdownSignals` option accepts other signals (`['SIGTERM', 'SIGINT', 'SIGHUP']`), or `false` to leave them to
+  Node.js.
+- **Nothing left to do**: when nothing keeps the process busy any more (no server, connection or timer), the application
+  ends gracefully, as with `app.exit(0)`: the `onDone` handlers run, the objects are destroyed, and the process exits
+  with the code it has (`process.exitCode`, 0 by default). A script can therefore just finish its work. An application
+  that has been disposed (`app.dispose()`, as in tests) leaves the end of the process to whatever runs it.
+
+## 4. The mode
+
+`app.mode()` returns `'development'` or `'production'`. The environment overrides the code, so the same build can run in
+either mode: the `MODE` environment variable wins, then `NODE_ENV`, then the `mode` option, and `'development'`
+otherwise. A `MODE` with an unknown value is ignored with a warning; a `NODE_ENV` with an unknown value (such as `test`)
+is skipped. The resolved mode is written back to `MODE` and `NODE_ENV`, so libraries see the same mode. The variables
+can come from the system, from `Application.env({MODE: 'production'})`, or from the `.env` file that Bun reads (when
+running `bun App.js`; executables built by Bun do not read it).
+
+## 5. The packed application
+
+`lakutata package bundle`, `package exe` and `package installer` pack the compiled application into a bundle, an
+executable or installers. When it runs packed, `isPackaged()` (from `lakutata`) returns `true`, and `resourcesPath()`
+returns the directory of its resources, the files declared in the `lakutata.resources` of its `package.json`; when not
+packed, it returns `undefined` and the application reads those files from where they are built. See
+[Packaging](Packaging.md).
+
+## 6. Entrypoints
+
+The `entrypoint` component (`lakutata/com/entrypoint`) serves the controllers over HTTP, the CLI, service transports,
+schedules and message queues. Configure it with `buildEntrypoints({controllers, http, cli, service, schedule, queue})`
+and list it in `bootstrap`; see [Entrypoint](Entrypoint.md).