@lakutata/core 3.0.0 → 3.1.1

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2023-present Lakutata
+
+All rights reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,13 +1,16 @@
 # @lakutata/core
 
+English | [中文](README.zh-CN.md)
+
 The core of the lakutata framework: the IoC container and dependency injection, the object model (`BaseObject`,
-`Component`, `Provider`, `Module`, `Application`) with its asynchronous construction and destruction, and the schema
-validation (`DTO`, built on joi) used by the decorators `@Configurable`, `@Expect`, `@Accept` and `@Return`.
+`Component`, `Provider`, `Application`) with its asynchronous construction and destruction, and schema validation
+(`DTO`, a validation engine with the API of joi), which the `@Configurable`, `@Expect`, `@Accept` and `@Return`
+decorators use.
 
 Most applications install the umbrella package `lakutata`, which re-exports this package (`lakutata`,
-`lakutata/decorator/di`, `lakutata/decorator/dto`, `lakutata/decorator/asst`, `lakutata/dtos`) and presets a pino `log`
-component and the `entrypoint` component. `@lakutata/core` alone is enough for a library or an application without
-them (it logs to the console then).
+`lakutata/decorator/di`, `lakutata/decorator/dto`, `lakutata/decorator/asst`, `lakutata/dtos`) and presets the `log`
+and `entrypoint` components. `@lakutata/core` alone is enough for a library, or for an application that needs neither
+(it then logs to the console).
 
 ## Installation
 
@@ -16,7 +19,8 @@ npm install lakutata          # the framework
 npm install @lakutata/core    # or the core only
 ```
 
-Node.js 22 or later, ESM (`"type": "module"`). The TypeScript options the decorators need:
+The package needs Node.js `^22.13.0 || >=24.11.0`. Projects use ES modules (`"type": "module"`); the package also ships
+CommonJS builds. The decorators need these TypeScript options:
 
 ```json
 {
@@ -33,8 +37,8 @@ Node.js 22 or later, ESM (`"type": "module"`). The TypeScript options the decora
 
 ### An application
 
-An application is a tree of objects created by its container. `Application.run()` validates its options, registers its
-components and providers, creates the objects listed in `bootstrap`, then calls `onLaunched`.
+An application is a tree of objects that its container creates. `Application.run()` validates the application's
+options, registers its components and providers, creates the objects listed in `bootstrap`, then calls `onLaunched`.
 
 ```typescript
 import {Application, Component, DTO, type ILogger} from 'lakutata'
@@ -42,7 +46,7 @@ import {Configurable, Inject} from 'lakutata/decorator/di'
 
 //A component: a singleton of the application, created when it is first needed (or by bootstrap)
 class Mailer extends Component {
-    //Its option, validated when it is created: given by the application options below
+    //An option, validated when the component is created; its value comes from the application options below
     @Configurable(DTO.String().required())
     protected readonly host: string
 
@@ -90,14 +94,14 @@ Application
 
 ### Dependency injection
 
-`@Inject()` injects the object registered under the property name, `@Inject('name')` under another name,
-`@Inject(SomeClass)` an instance of a class (registered automatically when the class is marked `@Autoload()`). The
-injected objects are set before `init()` runs.
+`@Inject()` injects the object registered under the property's name, `@Inject('name')` the one registered under
+another name, and `@Inject(SomeClass)` an instance of a class (registered automatically when the class is marked
+`@Autoload()`). Injected objects are set before `init()` runs.
 
 ### Validation
 
-A `DTO` subclass declares its fields with `@Expect(schema)`. The schemas are built by the static methods of `DTO`
-(`DTO.String()`, `DTO.Number()`, `DTO.Object()`, `DTO.Array()`, `DTO.Alternatives()`…, the joi API):
+A `DTO` subclass declares its fields with `@Expect(schema)`. Schemas are built with the static methods of `DTO`
+(`DTO.String()`, `DTO.Number()`, `DTO.Object()`, `DTO.Array()`, `DTO.Alternatives()`…), which follow the joi API:
 
 ```typescript
 import {DTO} from 'lakutata'
@@ -118,8 +122,8 @@ class Users {
     }
 }
 
-//Validated directly: the value with its defaults ({email: 'a@example.com', credit: 0}), InvalidValueException thrown
-//when it is invalid
+//Validated directly: resolves to the value with its defaults ({email: 'a@example.com', credit: 0}), or rejects with
+//InvalidValueException when the value is invalid
 const input = await CreateUserDTO.validateAsync({email: 'a@example.com'})
 ```
 
@@ -138,7 +142,7 @@ class Mailer extends Component {
     }
 }
 
-//Created with its options, its init() awaited
+//Created with its options; set() resolves once its init() has completed
 const container: Container = new Container()
 const mailer: Mailer = await container.set(Mailer, {host: 'localhost'})
 await mailer.send('someone@example.com', 'Hello')
@@ -151,7 +155,7 @@ await container.destroy()
 | Export | Subpath | What it is |
 |---|---|---|
 | `Application` | `lakutata` | The application: `run()`, `env()`, `alias()`, `onLaunched()`, `onDone()`, `onFatalException()`, `getObject()`, `exit()` |
-| `Module` | `lakutata` | A group of components, providers and objects with its own container |
+| `Module` | `lakutata` | The base class of `Application`: the container and the declared objects live here |
 | `Component` | `lakutata` | A singleton service with events (`emit`, `on`…) |
 | `Provider` | `lakutata` | A scoped object (one per scope) |
 | `BaseObject` | `lakutata` | The root class: asynchronous construction (`init`), destruction (`destroy`), `getObject` |
@@ -164,7 +168,7 @@ await container.destroy()
 | `Expect`, `Accept`, `Return`, `IndexSignature` | `lakutata/decorator/dto` | DTO fields, method argument and return validation |
 | `Before`, `After` | `lakutata/decorator/asst` | Functions run before and after a method |
 | `PaginationSearchDTO`, `PaginationResultDTO`, `paginator`, `FlexibleDTO`, `toJsonSchema`, `fromJsonSchema` | `lakutata/dtos` | Pagination, open DTOs and JSON Schema conversion |
-| `ConsoleLogger`, `ILogger` | `lakutata/com/logger` | The logger interface and its console implementation |
+| `ConsoleLogger`, `ILogger` | `@lakutata/core/com/logger` | The logger interface and its console implementation |
 
 The typings document each declaration with examples.
 
@@ -183,7 +187,10 @@ The typings document each declaration with examples.
 
 ## See also
 
-- The guides: `doc/en/Core.md`, `doc/en/DTOValidation.md`, `doc/en/Decorator.md` of the package `lakutata` (Chinese
-  in `doc/zh`).
+- The guides on the website: [Objects and Lifetimes](https://lakutata.com/guide/Objects),
+  [Dependency Injection](https://lakutata.com/guide/Injection) and
+  [DTO and Validation](https://lakutata.com/guide/DTOValidation).
+- The guides `doc/en/Application.md`, `doc/en/Objects.md`, `doc/en/Injection.md`, `doc/en/DTOValidation.md` and
+  `doc/en/Decorator.md` in the `lakutata` package (Chinese in `doc/zh`).
 - `@lakutata/entrypoint`: the controllers and their HTTP, CLI and service transports.
-- `@lakutata/logger`: the pino logger preset by `lakutata`.
+- `@lakutata/logger`: the logger that `lakutata` presets as `log` (pino-compatible JSON lines).

package/README.zh-CN.md

@@ -0,0 +1,182 @@
+# @lakutata/core
+
+[English](README.md) | 中文
+
+lakutata 框架的核心：IoC 容器和依赖注入，对象模型（`BaseObject`、`Component`、`Provider`、`Application`）及其异步的创建与销毁，以及 `@Configurable`、`@Expect`、`@Accept` 和 `@Return` 装饰器所用的数据校验（`DTO`，一个 API 和 joi 一样的校验引擎）。
+
+大多数应用安装的是 `lakutata` 包：它重新导出这个包（`lakutata`、`lakutata/decorator/di`、`lakutata/decorator/dto`、`lakutata/decorator/asst`、`lakutata/dtos`），并预置 `log` 和 `entrypoint` 组件。对于库，或者这两个组件都不需要的应用，只用 `@lakutata/core` 就够了（此时日志输出到控制台）。
+
+## 安装
+
+```shell
+npm install lakutata          # 框架
+npm install @lakutata/core    # 或者只安装核心
+```
+
+这个包需要 Node.js `^22.13.0 || >=24.11.0`。项目使用 ES 模块（`"type": "module"`）；包里也带有 CommonJS 构建。装饰器需要以下 TypeScript 选项：
+
+```json
+{
+  "compilerOptions": {
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+## 用法
+
+### 一个应用
+
+应用是一棵由它的容器创建的对象树。`Application.run()` 校验应用的选项，注册它的组件和提供者，创建 `bootstrap` 中列出的对象，然后调用 `onLaunched`。
+
+```typescript
+import {Application, Component, DTO, type ILogger} from 'lakutata'
+import {Configurable, Inject} from 'lakutata/decorator/di'
+
+//组件：应用中的单例，在第一次被需要时创建（或者由 bootstrap 创建）
+class Mailer extends Component {
+    //一个选项，在组件创建时校验；它的值来自下面的应用选项
+    @Configurable(DTO.String().required())
+    protected readonly host: string
+
+    @Inject('log')
+    protected readonly log: ILogger
+
+    //注入的对象和选项都设置好之后调用
+    protected async init(): Promise<void> {
+        this.log.info('Mailer connected to %s', this.host)
+    }
+
+    public async send(to: string, text: string): Promise<void> {
+        this.log.info('Mail to %s: %s', to, text)
+    }
+
+    //应用停止时调用
+    protected async destroy(): Promise<void> {
+    }
+}
+
+Application
+    .run(() => ({
+        id: 'com.example.app',
+        name: 'Example',
+        components: {
+            mailer: {class: Mailer, host: 'smtp.example.com'}
+        },
+        bootstrap: ['mailer']
+    }))
+    .onLaunched(async (app: Application, log: ILogger): Promise<void> => {
+        const mailer: Mailer = await app.getObject('mailer')
+        await mailer.send('someone@example.com', 'Hello')
+        log.info('%s started', app.appName)
+    })
+    .onFatalException((error: Error, log: ILogger): void => log.error(error.message))
+```
+
+### 生命周期
+
+| 装饰器 | 实例数量 | 默认用于 |
+|---|---|---|
+| `@Singleton()` | 每个容器一个 | `Component` |
+| `@Scoped()` | 每个作用域一个（`container.createScope()`，例如一次请求） | `Provider`（包括控制器） |
+| `@Transient()` | 每次解析一个 | `BaseObject` |
+
+### 依赖注入
+
+`@Inject()` 注入以属性名注册的对象，`@Inject('name')` 注入以另一个名称注册的对象，`@Inject(SomeClass)` 注入一个类的实例（类标记了 `@Autoload()` 时会自动注册）。注入的对象在 `init()` 执行之前就已设置好。
+
+### 校验
+
+`DTO` 的子类用 `@Expect(schema)` 声明它的字段。校验规则由 `DTO` 的静态方法构建（`DTO.String()`、`DTO.Number()`、`DTO.Object()`、`DTO.Array()`、`DTO.Alternatives()`……），API 与 joi 相同：
+
+```typescript
+import {DTO} from 'lakutata'
+import {Accept, Expect} from 'lakutata/decorator/dto'
+
+class CreateUserDTO extends DTO {
+    @Expect(DTO.String().email().required())
+    public email: string
+
+    @Expect(DTO.Number().integer().min(0).default(0))
+    public credit: number
+}
+
+class Users {
+    //方法执行之前校验参数（并填充默认值）
+    @Accept(CreateUserDTO.required())
+    public async create(input: CreateUserDTO): Promise<void> {
+    }
+}
+
+//直接校验：得到补上默认值后的对象（{email: 'a@example.com', credit: 0}）；值不合法时
+//以 InvalidValueException 拒绝
+const input = await CreateUserDTO.validateAsync({email: 'a@example.com'})
+```
+
+### 测试与库：不使用应用的容器
+
+```typescript
+import {Component, Container, DTO} from 'lakutata'
+import {Configurable} from 'lakutata/decorator/di'
+
+class Mailer extends Component {
+    @Configurable(DTO.String().required())
+    protected readonly host: string
+
+    public async send(to: string, text: string): Promise<string> {
+        return `${this.host} -> ${to}: ${text}`
+    }
+}
+
+//按选项创建；set() 会等到它的 init() 完成
+const container: Container = new Container()
+const mailer: Mailer = await container.set(Mailer, {host: 'localhost'})
+await mailer.send('someone@example.com', 'Hello')
+//销毁它创建的对象
+await container.destroy()
+```
+
+## API
+
+| 导出 | 子路径 | 说明 |
+|---|---|---|
+| `Application` | `lakutata` | 应用：`run()`、`env()`、`alias()`、`onLaunched()`、`onDone()`、`onFatalException()`、`getObject()`、`exit()` |
+| `Module` | `lakutata` | `Application` 的基类：容器和声明的对象都在这里 |
+| `Component` | `lakutata` | 带事件（`emit`、`on`……）的单例服务 |
+| `Provider` | `lakutata` | 作用域对象（每个作用域一个） |
+| `BaseObject` | `lakutata` | 根类：异步构造（`init`）、销毁（`destroy`）、`getObject` |
+| `Container` | `lakutata` | IoC 容器：`set`、`get`、`getShared`、`register`、`createScope`、`destroy` |
+| `DTO` | `lakutata` | 带校验的数据类，以及构建校验规则的方法 |
+| `Exception` | `lakutata` | 框架中各种异常的基类（`errno`、`statusCode`） |
+| `isPackaged`、`resourcesPath` | `lakutata` | 应用是否以打包形式运行，以及它的资源目录 |
+| `registerValidationMessages`、`runInValidationLanguage`…… | `lakutata` | 校验消息的语言 |
+| `Inject`、`Configurable`、`Autoload`、`Singleton`、`Scoped`、`Transient`、`Lifetime` | `lakutata/decorator/di` | 依赖注入与生命周期 |
+| `Expect`、`Accept`、`Return`、`IndexSignature` | `lakutata/decorator/dto` | DTO 字段，以及方法参数和返回值的校验 |
+| `Before`、`After` | `lakutata/decorator/asst` | 在方法之前和之后执行的函数 |
+| `PaginationSearchDTO`、`PaginationResultDTO`、`paginator`、`FlexibleDTO`、`toJsonSchema`、`fromJsonSchema` | `lakutata/dtos` | 分页、接受任意字段的 DTO、JSON Schema 转换 |
+| `ConsoleLogger`、`ILogger` | `@lakutata/core/com/logger` | 日志记录器接口及其控制台实现 |
+
+类型声明中的每一项都附有说明和示例。
+
+## 错误
+
+| 异常 | 什么时候抛出 |
+|---|---|
+| `InvalidValueException` | 值不符合它的校验规则（`DTO.validate`、`@Configurable`、`@Expect`） |
+| `InvalidMethodAcceptException`、`InvalidMethodReturnException` | 方法的参数（`@Accept`）或返回值（`@Return`）不合法 |
+| `DependencyInjectionException` | 要注入的对象无法解析 |
+| `InvalidObjectOptionsException`、`InvalidObjectTypeException` | 所声明对象的选项或类不合法 |
+| `LifetimeLockedException` | 类的生命周期锁定之后又被修改 |
+| `ObjectDestroyedException` | 使用了已销毁的对象 |
+| `AliasExistsException`、`AliasNotFoundException`、`InvalidAliasNameException` | 路径别名重复声明、不存在或不合法 |
+| `MethodNotFoundException` | 按名称调用的方法不存在 |
+
+## 另见
+
+- 网站上的指南：[对象与生命周期](https://lakutata.com/zh/guide/Objects)、[依赖注入](https://lakutata.com/zh/guide/Injection)、[DTO 与数据校验](https://lakutata.com/zh/guide/DTOValidation)。
+- `lakutata` 包中的指南 `doc/zh/Application.md`、`doc/zh/Objects.md`、`doc/zh/Injection.md`、`doc/zh/DTOValidation.md` 和 `doc/zh/Decorator.md`。
+- `@lakutata/entrypoint`：控制器，以及它们的 HTTP、命令行和服务调用传输方式。
+- `@lakutata/logger`：`lakutata` 预置为 `log` 的日志记录器（与 pino 兼容的 JSON 行）。

package/dist/cjs/decorators/dto/Expect.d.ts

@@ -5,7 +5,8 @@ import { Schema } from '../../lib/validation/types/Schema.js';
  * Declare the schema of a property of a DTO class. The DTO validates the property against it when it is constructed
  * (the whole object at once: defaults applied, the keys without schema removed unless the class has an
  * `@IndexSignature`), and each time the property, or a value nested in it, is changed afterwards (the change is undone
- * when invalid). The schema is also part of the class schema (`MyDTO.Schema()`) used by `@Accept`, `@Return` and the
+ * when invalid). With `DTO.Any()`, an object of another class the property holds is given as it is, not watched: no
+ * change of it can be invalid. The schema is also part of the class schema (`MyDTO.Schema()`) used by `@Accept`, `@Return` and the
  * actions' input validation. Subclasses inherit the property schemas, and may declare a property again to replace its
  * schema. Ignored on a symbol property or on a class which is not a DTO.
  * @param schema The schema of the property, built with the static methods of `DTO` (`DTO.String().required()`); a

package/dist/cjs/decorators/dto/Expect.js

@@ -6,7 +6,8 @@ const ObjectSchemaValidation_js_1 = require("../../lib/dto/ObjectSchemaValidatio
  * Declare the schema of a property of a DTO class. The DTO validates the property against it when it is constructed
  * (the whole object at once: defaults applied, the keys without schema removed unless the class has an
  * `@IndexSignature`), and each time the property, or a value nested in it, is changed afterwards (the change is undone
- * when invalid). The schema is also part of the class schema (`MyDTO.Schema()`) used by `@Accept`, `@Return` and the
+ * when invalid). With `DTO.Any()`, an object of another class the property holds is given as it is, not watched: no
+ * change of it can be invalid. The schema is also part of the class schema (`MyDTO.Schema()`) used by `@Accept`, `@Return` and the
  * actions' input validation. Subclasses inherit the property schemas, and may declare a property again to replace its
  * schema. Ignored on a symbol property or on a class which is not a DTO.
  * @param schema The schema of the property, built with the static methods of `DTO` (`DTO.String().required()`); a

package/dist/cjs/dto/PaginationSearchDTO.d.ts

@@ -1,7 +1,8 @@
 import { DTO } from '../lib/dto/DTO.js';
 /**
- * The input of a paginated search: how many items to return and how many to skip. Extend it with the search criteria,
- * and pass the validated input to `paginator()`.
+ * The input of a paginated search: how many items to return and how many to skip, numbers or their text (the query
+ * string of a request, `?limit=20&offset=40`). Extend it with the search criteria, and pass the validated input to
+ * `paginator()`.
  * @example
  * ```typescript
  * import {DTO} from 'lakutata'
@@ -21,12 +22,13 @@ import { DTO } from '../lib/dto/DTO.js';
  */
 export declare class PaginationSearchDTO extends DTO {
     /**
-     * The maximum number of items to return: an integer, 0 or more.
+     * The maximum number of items to return: an integer, 0 or more (its text too, as a query string gives it).
      * @default 10
      */
     limit?: number;
     /**
-     * The number of items to skip before the first one returned: an integer, 0 or more.
+     * The number of items to skip before the first one returned: an integer, 0 or more (its text too, as a query string
+     * gives it).
      * @default 0
      */
     offset?: number;

package/dist/cjs/dto/PaginationSearchDTO.js

@@ -13,8 +13,9 @@ exports.PaginationSearchDTO = void 0;
 const DTO_js_1 = require("../lib/dto/DTO.js");
 const Expect_js_1 = require("../decorators/dto/Expect.js");
 /**
- * The input of a paginated search: how many items to return and how many to skip. Extend it with the search criteria,
- * and pass the validated input to `paginator()`.
+ * The input of a paginated search: how many items to return and how many to skip, numbers or their text (the query
+ * string of a request, `?limit=20&offset=40`). Extend it with the search criteria, and pass the validated input to
+ * `paginator()`.
  * @example
  * ```typescript
  * import {DTO} from 'lakutata'
@@ -36,10 +37,10 @@ class PaginationSearchDTO extends DTO_js_1.DTO {
 }
 exports.PaginationSearchDTO = PaginationSearchDTO;
 __decorate([
-    (0, Expect_js_1.Expect)(DTO_js_1.DTO.Number().integer().positive().allow(0).optional().default(10)),
+    (0, Expect_js_1.Expect)(DTO_js_1.DTO.Number().integer().positive().allow(0).strict(false).optional().default(10)),
     __metadata("design:type", Number)
 ], PaginationSearchDTO.prototype, "limit", void 0);
 __decorate([
-    (0, Expect_js_1.Expect)(DTO_js_1.DTO.Number().integer().positive().allow(0).optional().default(0)),
+    (0, Expect_js_1.Expect)(DTO_js_1.DTO.Number().integer().positive().allow(0).strict(false).optional().default(0)),
     __metadata("design:type", Number)
 ], PaginationSearchDTO.prototype, "offset", void 0);

package/dist/cjs/exceptions/dto/InvalidValueException.d.ts

@@ -3,9 +3,11 @@ import { Exception } from '../../lib/foundation/Exception.js';
  * Thrown when a value does not match its schema: by `DTO.validate()` and `DTO.validateAsync()`, by the DTO constructor
  * and the assignments to a DTO property, and by the creation of an object whose `@Configurable` value is invalid. Its
  * message describes the first error; its causes lead to the `SchemaValidationException` holding the details (the path
- * and the rule of each error). Its `errno` is `E_INVALID_VALUE`; the HTTP entrypoints answer an invalid action input with the
- * status 400, JSON-RPC with the error "invalid params".
+ * and the rule of each error). Its `errno` is `E_INVALID_VALUE` and its `statusCode` 400, a value refused being an
+ * error of the caller: the HTTP entrypoints answer an invalid action input with the status 400, the service transports
+ * send the error with it, JSON-RPC answers with the error "invalid params".
  */
 export declare class InvalidValueException extends Exception {
     errno: string | number;
+    readonly statusCode: number;
 }

package/dist/cjs/exceptions/dto/InvalidValueException.js

@@ -6,13 +6,15 @@ const Exception_js_1 = require("../../lib/foundation/Exception.js");
  * Thrown when a value does not match its schema: by `DTO.validate()` and `DTO.validateAsync()`, by the DTO constructor
  * and the assignments to a DTO property, and by the creation of an object whose `@Configurable` value is invalid. Its
  * message describes the first error; its causes lead to the `SchemaValidationException` holding the details (the path
- * and the rule of each error). Its `errno` is `E_INVALID_VALUE`; the HTTP entrypoints answer an invalid action input with the
- * status 400, JSON-RPC with the error "invalid params".
+ * and the rule of each error). Its `errno` is `E_INVALID_VALUE` and its `statusCode` 400, a value refused being an
+ * error of the caller: the HTTP entrypoints answer an invalid action input with the status 400, the service transports
+ * send the error with it, JSON-RPC answers with the error "invalid params".
  */
 class InvalidValueException extends Exception_js_1.Exception {
     constructor() {
         super(...arguments);
         this.errno = 'E_INVALID_VALUE';
+        this.statusCode = 400;
     }
 }
 exports.InvalidValueException = InvalidValueException;

package/dist/cjs/lib/app/Application.d.ts

@@ -1,4 +1,5 @@
 import { Module } from '../core/Module.js';
+import { __destroy } from '../base/BaseObject.js';
 import { ApplicationConfigLoader } from './ApplicationConfigLoader.js';
 import { ApplicationOptions } from '../../options/ApplicationOptions.js';
 import { Alias } from '../core/Alias.js';
@@ -270,6 +271,20 @@ export declare class Application extends Module {
      * @protected
      */
     protected static listenShutdownSignals(signals: NodeJS.Signals[]): void;
+    /**
+     * End the launched application gracefully once nothing keeps the process busy (no server, connection or timer
+     * left): its exit, with the exit code the process has (`process.exitCode`, 0 by default), as with `exit()`. A
+     * process ending so does not wait for an exit, so the done handlers and the teardown would not run otherwise.
+     * @param app The launched application.
+     * @protected
+     */
+    protected static listenNaturalEnd(app: Application): void;
+    /**
+     * Stop ending the application with the process: it exits, or it is destroyed (disposed by a test, which leaves the
+     * end of the process to its runner)
+     * @protected
+     */
+    protected static stopListeningNaturalEnd(): void;
     /**
      * Launch the application: environment variables, aliases, options (or the database migration command given by the
      * `MIGRATION_*` environment variables), then the application created in a new root container.
@@ -328,6 +343,13 @@ export declare class Application extends Module {
      * variable.
      */
     get timezone(): string;
+    /**
+     * The framework's destroyer, see {@link Module}: a destroyed application no longer ends with the process.
+     * @param hooks The steps the framework's subclasses run before `destroy()`.
+     * @returns Resolves once the application and its objects are destroyed.
+     * @protected
+     */
+    protected [__destroy](...hooks: (() => Promise<void>)[]): Promise<void>;
     /**
      * The time the process has been running, in seconds (rounded down).
      */

package/dist/cjs/lib/app/Application.js

@@ -14,6 +14,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Application = exports.ApplicationState = void 0;
 const Module_js_1 = require("../core/Module.js");
+const BaseObject_js_1 = require("../base/BaseObject.js");
 const Container_js_1 = require("../core/Container.js");
 const ApplicationConfigLoader_js_1 = require("./ApplicationConfigLoader.js");
 const ApplicationOptions_js_1 = require("../../options/ApplicationOptions.js");
@@ -136,6 +137,16 @@ class Application extends Module_js_1.Module {
      * @private
      */
     static #consoleLogger;
+    /**
+     * Whether the application is exiting: a step of its bootstrap that exits it (a command of the migrations) ends its
+     * launch
+     */
+    static #exiting = false;
+    /**
+     * The listener of the end of the process once nothing keeps it busy (beforeExit): the launched application exits
+     * gracefully then, as with exit()
+     */
+    static #naturalEnd;
     /**
      * Preset the options of the applications, before they run: the packages assembling the framework preset their
      * components (the `lakutata` package presets its Logger as `log` and its Entrypoint as `entrypoint`). An object
@@ -374,6 +385,36 @@ class Application extends Module_js_1.Module {
             });
         }
     }
+    /**
+     * End the launched application gracefully once nothing keeps the process busy (no server, connection or timer
+     * left): its exit, with the exit code the process has (`process.exitCode`, 0 by default), as with `exit()`. A
+     * process ending so does not wait for an exit, so the done handlers and the teardown would not run otherwise.
+     * @param app The launched application.
+     * @protected
+     */
+    static listenNaturalEnd(app) {
+        Application.stopListeningNaturalEnd();
+        const listener = () => {
+            Application.stopListeningNaturalEnd();
+            //Exiting already (a signal, exit()): its teardown runs
+            if (Application.#exiting)
+                return;
+            const code = Number(process.exitCode ?? 0);
+            Application.eventEmitter.emit('exit', app, Number.isInteger(code) ? code : 1);
+        };
+        Application.#naturalEnd = listener;
+        process.once('beforeExit', listener);
+    }
+    /**
+     * Stop ending the application with the process: it exits, or it is destroyed (disposed by a test, which leaves the
+     * end of the process to its runner)
+     * @protected
+     */
+    static stopListeningNaturalEnd() {
+        if (Application.#naturalEnd)
+            process.removeListener('beforeExit', Application.#naturalEnd);
+        Application.#naturalEnd = undefined;
+    }
     /**
      * Launch the application: environment variables, aliases, options (or the database migration command given by the
      * `MIGRATION_*` environment variables), then the application created in a new root container.
@@ -382,6 +423,7 @@ class Application extends Module_js_1.Module {
      */
     static async launchApplication() {
         this.eventEmitter.once('exit', async (app, exitCode, signal) => {
+            this.#exiting = true;
             try {
                 //The done handler, told why the application exits
                 const reason = signal ? { code: exitCode ? exitCode : 0, signal: signal } : { code: exitCode ? exitCode : 0 };
@@ -497,6 +539,9 @@ class Application extends Module_js_1.Module {
                 if (applicationOptions.shutdownSignals)
                     this.listenShutdownSignals(applicationOptions.shutdownSignals);
                 applicationOptions.bootstrap?.push(async (target) => {
+                    //Exited by a step of the bootstrap: its container is being destroyed, it does not launch
+                    if (Application.#exiting)
+                        return;
                     const launchedCallbackRemover = function () {
                         this.options.bootstrap?.pop();
                         (0, As_1.As)(Reflect.getOwnMetadata('#bootstrap', this))?.pop();
@@ -508,6 +553,7 @@ class Application extends Module_js_1.Module {
                     (0, ApplicationLaunch_js_1.markApplicationLaunched)(target);
                     //The application launched is the one the signals end (its launched handlers may receive them)
                     Reflect.set(this, 'appInstance', target);
+                    Application.listenNaturalEnd((0, As_1.As)(target));
                     this.eventEmitter.emit(ApplicationState.Launched, (0, As_1.As)(target));
                 });
                 //Resolved once the application is initialized (its objects loaded, its bootstrap run), rejected with
@@ -582,6 +628,16 @@ class Application extends Module_js_1.Module {
     get timezone() {
         return (0, BasicInfo_js_1.getBasicInfo)().timezone;
     }
+    /**
+     * The framework's destroyer, see {@link Module}: a destroyed application no longer ends with the process.
+     * @param hooks The steps the framework's subclasses run before `destroy()`.
+     * @returns Resolves once the application and its objects are destroyed.
+     * @protected
+     */
+    async [BaseObject_js_1.__destroy](...hooks) {
+        Application.stopListeningNaturalEnd();
+        return await super[BaseObject_js_1.__destroy](...hooks);
+    }
     /**
      * The time the process has been running, in seconds (rounded down).
      */

package/dist/cjs/lib/base/BaseObject.js

@@ -559,7 +559,9 @@ let BaseObject = BaseObject_1 = class BaseObject extends AsyncConstructor_js_1.A
      */
     getMethod(name, throwExceptionIfNotFound = false) {
         if (this.hasMethod(name)) {
-            return (...args) => this[name](...args);
+            //Named: else V8 names it after the code below in the stack traces (MethodNotFoundException.methodName)
+            const callMethod = (...args) => this[name](...args);
+            return callMethod;
         }
         else if (throwExceptionIfNotFound) {
             throw new MethodNotFoundException_js_1.MethodNotFoundException('Method "{methodName}" not found in "{className}"', {

package/dist/cjs/lib/base/internal/ConfigurableRecordsInjection.d.ts

@@ -1,18 +1,18 @@
 import { BaseObject } from '../BaseObject.js';
+import { type Resolver } from '../../ioc/Resolvers.js';
 /**
- * Set configurable records to target constructor with its registration name
- * @param target
- * @param registrationName
+ * Set configurable records to a registration (the options it was declared with)
+ * @param registration
  * @param configurableRecords
  * @constructor
  */
-export declare function setConfigurableRecords<ClassConstructor extends typeof BaseObject>(target: ClassConstructor, registrationName: string | symbol, configurableRecords: Record<string, any>): void;
+export declare function setConfigurableRecords(registration: Resolver<any>, configurableRecords: Record<string, any>): void;
 /**
- * Get configurable records from target constructor by its registration name
- * @param target
+ * Get configurable records from a registration
+ * @param registration
  * @constructor
  */
-export declare function getConfigurableRecords<ClassConstructor extends typeof BaseObject>(target: ClassConstructor, registrationName: string | symbol): Record<string, any>;
+export declare function getConfigurableRecords(registration: Resolver<any> | null): Record<string, any>;
 /**
  * Set id to instance
  * @param target