@lakutata/core 3.1.1 → 3.1.5

package/README.md

@@ -19,8 +19,8 @@ npm install lakutata          # the framework
 npm install @lakutata/core    # or the core only
 ```
 
-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:
+The package needs Node.js 18.10 or later (`>=18.10.0`). Projects use ES modules (`"type": "module"`); the package also
+ships CommonJS builds. The decorators need these TypeScript options:
 
 ```json
 {
@@ -169,6 +169,7 @@ await container.destroy()
 | `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/core/com/logger` | The logger interface and its console implementation |
+| `IInterfaceListening`, `IInterfaceListener`, `IInterfaceListenOptions`, `IListeningAddress`, `NetworkInterfaceSelector` | `lakutata` | The contract of the listening on network interfaces, which the entrypoints use for their `interface` option and `@lakutata/netif` implements (types only) |
 
 The typings document each declaration with examples.
 

package/README.zh-CN.md

@@ -13,7 +13,7 @@ npm install lakutata          # 框架
 npm install @lakutata/core    # 或者只安装核心
 ```
 
-这个包需要 Node.js `^22.13.0 || >=24.11.0`。项目使用 ES 模块（`"type": "module"`）；包里也带有 CommonJS 构建。装饰器需要以下 TypeScript 选项：
+这个包需要 Node.js 18.10 或更高版本（`>=18.10.0`）。项目使用 ES 模块（`"type": "module"`）；包里也带有 CommonJS 构建。装饰器需要以下 TypeScript 选项：
 
 ```json
 {
@@ -158,6 +158,7 @@ await container.destroy()
 | `Before`、`After` | `lakutata/decorator/asst` | 在方法之前和之后执行的函数 |
 | `PaginationSearchDTO`、`PaginationResultDTO`、`paginator`、`FlexibleDTO`、`toJsonSchema`、`fromJsonSchema` | `lakutata/dtos` | 分页、接受任意字段的 DTO、JSON Schema 转换 |
 | `ConsoleLogger`、`ILogger` | `@lakutata/core/com/logger` | 日志记录器接口及其控制台实现 |
+| `IInterfaceListening`、`IInterfaceListener`、`IInterfaceListenOptions`、`IListeningAddress`、`NetworkInterfaceSelector` | `lakutata` | 按网口监听的接口：入口的 `interface` 选项通过它监听，`@lakutata/netif` 实现了它（只有类型） |
 
 类型声明中的每一项都附有说明和示例。
 

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

@@ -90,4 +90,5 @@ export * from '../types/ModuleOptions.js';
  */
 export * from '../interfaces/IBaseObjectConstructor.js';
 export * from '../interfaces/ILogger.js';
+export * from '../interfaces/IInterfaceListening.js';
 export * from '../interfaces/IConstructor.js';

package/dist/cjs/exports/Core.js

@@ -121,6 +121,7 @@ __exportStar(require("../types/ModuleOptions.js"), exports);
  */
 __exportStar(require("../interfaces/IBaseObjectConstructor.js"), exports);
 __exportStar(require("../interfaces/ILogger.js"), exports);
+__exportStar(require("../interfaces/IInterfaceListening.js"), exports);
 __exportStar(require("../interfaces/IConstructor.js"), exports);
 
 //The default of the entry: the entry itself (scripts/package-build/cjs-package.mjs)

package/dist/cjs/interfaces/IInterfaceListening.d.ts

@@ -0,0 +1,159 @@
+import type { Server } from 'node:net';
+/**
+ * A network interface, as an implementation of {@link IInterfaceListening} takes it: its name (`'eth1'`; on Windows the
+ * name of the network connection), its hardware address (`{mac: '52:54:00:12:34:56'}`) or its index (`{index: 3}`).
+ */
+export type NetworkInterfaceSelector = string | {
+    /**
+     * The hardware address of the interface.
+     */
+    mac: string;
+} | {
+    /**
+     * The index of the interface.
+     */
+    index: number;
+};
+/**
+ * An address a listener of a network interface can be reached at.
+ */
+export interface IListeningAddress {
+    /**
+     * The address (an IPv6 address without its scope).
+     */
+    address: string;
+    /**
+     * `'IPv4'` or `'IPv6'`.
+     */
+    family: 'IPv4' | 'IPv6';
+    /**
+     * The port.
+     */
+    port: number;
+    /**
+     * IPv6 only: the scope of the address (the index of the interface for a link-local one), 0 for a global one.
+     */
+    scopeid?: number;
+}
+/**
+ * The options of {@link IInterfaceListening.listenOnAll}.
+ */
+export interface IInterfaceListenOptions {
+    /**
+     * The port; 0 lets the system choose one (for one interface only).
+     */
+    port: number;
+    /**
+     * The families listened on.
+     * @default 'both'
+     */
+    family?: 'IPv4' | 'IPv6' | 'both';
+    /**
+     * Refuse to listen where the connections reaching the addresses of the interface through another interface cannot
+     * be refused, and stop listening while they cannot. An implementation that never refuses them throws.
+     * @default false
+     */
+    strict?: boolean;
+}
+/**
+ * The listener of a network interface for a server: it accepts the connections of the interface and gives them to the
+ * server, whatever the addresses of the interface, again when they change and when the interface is unplugged and
+ * plugged back. The server itself does not listen. The `InterfaceListener` of `@lakutata/netif` implements it.
+ */
+export interface IInterfaceListener {
+    /**
+     * The interface listened on: its name (`undefined` while it does not exist), and whether it is the loopback one.
+     */
+    readonly networkInterface: {
+        readonly name: string | undefined;
+        readonly loopback: boolean;
+    };
+    /**
+     * The port, `undefined` until a port 0 is given one by the system.
+     */
+    readonly port: number | undefined;
+    /**
+     * The addresses it can be reached at now: none while the interface does not exist or has no address.
+     */
+    readonly addresses: IListeningAddress[];
+    /**
+     * Whether the interface is listened on now.
+     */
+    readonly listening: boolean;
+    /**
+     * Whether the system refuses the connections that reach the addresses of the interface through another interface.
+     */
+    readonly enforced: boolean;
+    /**
+     * Why `enforced` is `false`, when it is.
+     */
+    readonly reason: string | undefined;
+    /**
+     * Whether it was closed.
+     */
+    readonly closed: boolean;
+    /**
+     * Stop listening; the connections established are left to the server.
+     */
+    close(): Promise<void>;
+    /**
+     * The interface is listened on, again after a change.
+     * @param event `'listening'`.
+     * @param listener Called without argument.
+     */
+    on(event: 'listening', listener: () => void): this;
+    /**
+     * A failure of listening again, retried by the listener; with `strict`, the guarantee lost.
+     * @param event `'error'`.
+     * @param listener Called with the error.
+     */
+    on(event: 'error', listener: (error: Error) => void): this;
+    /**
+     * `enforced` changed.
+     * @param event `'enforced'`.
+     * @param listener Called with its new value.
+     */
+    on(event: 'enforced', listener: (enforced: boolean) => void): this;
+    /**
+     * The listener was closed.
+     * @param event `'close'`.
+     * @param listener Called without argument.
+     */
+    on(event: 'close', listener: () => void): this;
+    /**
+     * Remove a listener of an event.
+     * @param event The event.
+     * @param listener The listener given to `on()`.
+     */
+    off(event: 'listening' | 'error' | 'enforced' | 'close', listener: (...args: any[]) => void): this;
+}
+/**
+ * Listening on network interfaces instead of addresses: what the entrypoints use for their `interface` option. The
+ * package `@lakutata/netif` implements it, and is the one used by default; another implementation is given in the
+ * `interfaceListening` option of the entrypoints.
+ * @example
+ * ```typescript
+ * import type {IInterfaceListener, IInterfaceListening} from 'lakutata'
+ * import {listenOnAll} from '@lakutata/netif'
+ *
+ * //An implementation that writes each listener made before giving it to the entrypoint
+ * const logged: IInterfaceListening = {
+ *     listenOnAll: async (selectors, server, options): Promise<IInterfaceListener[]> => {
+ *         const listeners: IInterfaceListener[] = await listenOnAll(selectors, server, options)
+ *         for (const listener of listeners) console.log(listener.networkInterface.name, listener.addresses)
+ *         return listeners
+ *     }
+ * }
+ * ```
+ */
+export interface IInterfaceListening {
+    /**
+     * Listen on interfaces for a server, one listener by interface; when one cannot be listened on, the others are
+     * closed and the error is thrown. An interface that does not exist yet is listened on once it appears.
+     * @param selectors The interfaces; several need a port other than 0.
+     * @param server The server the connections are given to.
+     * @param options The port, the families, and whether the other interfaces must be refused.
+     * @returns The listeners, in the order of the interfaces.
+     */
+    listenOnAll(selectors: NetworkInterfaceSelector | NetworkInterfaceSelector[], server: Server, options: IInterfaceListenOptions): Promise<IInterfaceListener[]>;
+}

package/dist/cjs/interfaces/IInterfaceListening.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -49,7 +49,7 @@ export declare enum ApplicationState {
  * and `run()` have no effect then):
  * 1. the environment variables are set, the aliases registered (`@runtime` being the working directory);
  * 2. the options are read (from the getter given to `run()`, which may be async) and validated, the identity applied
- *    (`process.title` is the application ID, the time zone and the mode set);
+ *    (`process.title` is the application ID, except in NW.js; the time zone and the mode set);
  * 3. the application is created in a new root container: its objects are registered and its bootstrap runs in order;
  * 4. the `onLaunched()` handlers and the objects' `launched()` hooks run.
  *

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

@@ -51,7 +51,7 @@ var ApplicationState;
  * and `run()` have no effect then):
  * 1. the environment variables are set, the aliases registered (`@runtime` being the working directory);
  * 2. the options are read (from the getter given to `run()`, which may be async) and validated, the identity applied
- *    (`process.title` is the application ID, the time zone and the mode set);
+ *    (`process.title` is the application ID, except in NW.js; the time zone and the mode set);
  * 3. the application is created in a new root container: its objects are registered and its bootstrap runs in order;
  * 4. the `onLaunched()` handlers and the objects' `launched()` hooks run.
  *

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

@@ -16,13 +16,17 @@ class ApplicationConfigLoader extends ModuleConfigLoader_js_1.ModuleConfigLoader
      */
     constructor(app, applicationOptions, presetLoadOptions = []) {
         if (ApplicationOptions_js_1.ApplicationOptions.isValid(applicationOptions)) {
-            process.title = (0, BasicInfo_js_1.setBasicInfo)({
+            const appId = (0, BasicInfo_js_1.setBasicInfo)({
                 appId: applicationOptions.id,
                 appName: applicationOptions.name,
                 timezone: applicationOptions.timezone ? applicationOptions.timezone : 'auto',
                 //MODE, NODE_ENV, the options, development
                 mode: (0, BasicInfo_js_1.resolveMode)(applicationOptions.mode)
             }).appId;
+            //The process is named after the application, except in NW.js: its Node.js runs in a renderer process of
+            //Chromium, whose title would make it an application of its own (an icon in the Dock of macOS)
+            if (!process.versions.nw)
+                process.title = appId;
         }
         super(app, applicationOptions, presetLoadOptions);
     }

package/dist/cjs/options/ApplicationOptions.d.ts

@@ -27,8 +27,8 @@ import { ModuleOptions } from './ModuleOptions.js';
  */
 export declare class ApplicationOptions extends ModuleOptions {
     /**
-     * The ID of the application (`'shop.app'`): the `process.title`, read by `Application.appId` and stamped on the
-     * exceptions. Required.
+     * The ID of the application (`'shop.app'`), read by `Application.appId` and stamped on the exceptions; the
+     * `process.title` too, except in NW.js. Required.
      */
     readonly id: string;
     /**

package/dist/esm/exports/Core.js

@@ -61,4 +61,5 @@ export * from '../types/ModuleOptions.js';
  */
 export * from '../interfaces/IBaseObjectConstructor.js';
 export * from '../interfaces/ILogger.js';
+export * from '../interfaces/IInterfaceListening.js';
 export * from '../interfaces/IConstructor.js';

package/dist/esm/interfaces/IInterfaceListening.js

@@ -0,0 +1 @@
+export {};

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

@@ -45,7 +45,7 @@ export var ApplicationState;
  * and `run()` have no effect then):
  * 1. the environment variables are set, the aliases registered (`@runtime` being the working directory);
  * 2. the options are read (from the getter given to `run()`, which may be async) and validated, the identity applied
- *    (`process.title` is the application ID, the time zone and the mode set);
+ *    (`process.title` is the application ID, except in NW.js; the time zone and the mode set);
  * 3. the application is created in a new root container: its objects are registered and its bootstrap runs in order;
  * 4. the `onLaunched()` handlers and the objects' `launched()` hooks run.
  *

package/dist/esm/lib/app/ApplicationConfigLoader.js

@@ -13,13 +13,17 @@ export class ApplicationConfigLoader extends ModuleConfigLoader {
      */
     constructor(app, applicationOptions, presetLoadOptions = []) {
         if (ApplicationOptions.isValid(applicationOptions)) {
-            process.title = setBasicInfo({
+            const appId = setBasicInfo({
                 appId: applicationOptions.id,
                 appName: applicationOptions.name,
                 timezone: applicationOptions.timezone ? applicationOptions.timezone : 'auto',
                 //MODE, NODE_ENV, the options, development
                 mode: resolveMode(applicationOptions.mode)
             }).appId;
+            //The process is named after the application, except in NW.js: its Node.js runs in a renderer process of
+            //Chromium, whose title would make it an application of its own (an icon in the Dock of macOS)
+            if (!process.versions.nw)
+                process.title = appId;
         }
         super(app, applicationOptions, presetLoadOptions);
     }

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

@@ -90,4 +90,5 @@ export * from '../types/ModuleOptions.js';
  */
 export * from '../interfaces/IBaseObjectConstructor.js';
 export * from '../interfaces/ILogger.js';
+export * from '../interfaces/IInterfaceListening.js';
 export * from '../interfaces/IConstructor.js';

package/dist/types/interfaces/IInterfaceListening.d.ts

@@ -0,0 +1,159 @@
+import type { Server } from 'node:net';
+/**
+ * A network interface, as an implementation of {@link IInterfaceListening} takes it: its name (`'eth1'`; on Windows the
+ * name of the network connection), its hardware address (`{mac: '52:54:00:12:34:56'}`) or its index (`{index: 3}`).
+ */
+export type NetworkInterfaceSelector = string | {
+    /**
+     * The hardware address of the interface.
+     */
+    mac: string;
+} | {
+    /**
+     * The index of the interface.
+     */
+    index: number;
+};
+/**
+ * An address a listener of a network interface can be reached at.
+ */
+export interface IListeningAddress {
+    /**
+     * The address (an IPv6 address without its scope).
+     */
+    address: string;
+    /**
+     * `'IPv4'` or `'IPv6'`.
+     */
+    family: 'IPv4' | 'IPv6';
+    /**
+     * The port.
+     */
+    port: number;
+    /**
+     * IPv6 only: the scope of the address (the index of the interface for a link-local one), 0 for a global one.
+     */
+    scopeid?: number;
+}
+/**
+ * The options of {@link IInterfaceListening.listenOnAll}.
+ */
+export interface IInterfaceListenOptions {
+    /**
+     * The port; 0 lets the system choose one (for one interface only).
+     */
+    port: number;
+    /**
+     * The families listened on.
+     * @default 'both'
+     */
+    family?: 'IPv4' | 'IPv6' | 'both';
+    /**
+     * Refuse to listen where the connections reaching the addresses of the interface through another interface cannot
+     * be refused, and stop listening while they cannot. An implementation that never refuses them throws.
+     * @default false
+     */
+    strict?: boolean;
+}
+/**
+ * The listener of a network interface for a server: it accepts the connections of the interface and gives them to the
+ * server, whatever the addresses of the interface, again when they change and when the interface is unplugged and
+ * plugged back. The server itself does not listen. The `InterfaceListener` of `@lakutata/netif` implements it.
+ */
+export interface IInterfaceListener {
+    /**
+     * The interface listened on: its name (`undefined` while it does not exist), and whether it is the loopback one.
+     */
+    readonly networkInterface: {
+        readonly name: string | undefined;
+        readonly loopback: boolean;
+    };
+    /**
+     * The port, `undefined` until a port 0 is given one by the system.
+     */
+    readonly port: number | undefined;
+    /**
+     * The addresses it can be reached at now: none while the interface does not exist or has no address.
+     */
+    readonly addresses: IListeningAddress[];
+    /**
+     * Whether the interface is listened on now.
+     */
+    readonly listening: boolean;
+    /**
+     * Whether the system refuses the connections that reach the addresses of the interface through another interface.
+     */
+    readonly enforced: boolean;
+    /**
+     * Why `enforced` is `false`, when it is.
+     */
+    readonly reason: string | undefined;
+    /**
+     * Whether it was closed.
+     */
+    readonly closed: boolean;
+    /**
+     * Stop listening; the connections established are left to the server.
+     */
+    close(): Promise<void>;
+    /**
+     * The interface is listened on, again after a change.
+     * @param event `'listening'`.
+     * @param listener Called without argument.
+     */
+    on(event: 'listening', listener: () => void): this;
+    /**
+     * A failure of listening again, retried by the listener; with `strict`, the guarantee lost.
+     * @param event `'error'`.
+     * @param listener Called with the error.
+     */
+    on(event: 'error', listener: (error: Error) => void): this;
+    /**
+     * `enforced` changed.
+     * @param event `'enforced'`.
+     * @param listener Called with its new value.
+     */
+    on(event: 'enforced', listener: (enforced: boolean) => void): this;
+    /**
+     * The listener was closed.
+     * @param event `'close'`.
+     * @param listener Called without argument.
+     */
+    on(event: 'close', listener: () => void): this;
+    /**
+     * Remove a listener of an event.
+     * @param event The event.
+     * @param listener The listener given to `on()`.
+     */
+    off(event: 'listening' | 'error' | 'enforced' | 'close', listener: (...args: any[]) => void): this;
+}
+/**
+ * Listening on network interfaces instead of addresses: what the entrypoints use for their `interface` option. The
+ * package `@lakutata/netif` implements it, and is the one used by default; another implementation is given in the
+ * `interfaceListening` option of the entrypoints.
+ * @example
+ * ```typescript
+ * import type {IInterfaceListener, IInterfaceListening} from 'lakutata'
+ * import {listenOnAll} from '@lakutata/netif'
+ *
+ * //An implementation that writes each listener made before giving it to the entrypoint
+ * const logged: IInterfaceListening = {
+ *     listenOnAll: async (selectors, server, options): Promise<IInterfaceListener[]> => {
+ *         const listeners: IInterfaceListener[] = await listenOnAll(selectors, server, options)
+ *         for (const listener of listeners) console.log(listener.networkInterface.name, listener.addresses)
+ *         return listeners
+ *     }
+ * }
+ * ```
+ */
+export interface IInterfaceListening {
+    /**
+     * Listen on interfaces for a server, one listener by interface; when one cannot be listened on, the others are
+     * closed and the error is thrown. An interface that does not exist yet is listened on once it appears.
+     * @param selectors The interfaces; several need a port other than 0.
+     * @param server The server the connections are given to.
+     * @param options The port, the families, and whether the other interfaces must be refused.
+     * @returns The listeners, in the order of the interfaces.
+     */
+    listenOnAll(selectors: NetworkInterfaceSelector | NetworkInterfaceSelector[], server: Server, options: IInterfaceListenOptions): Promise<IInterfaceListener[]>;
+}

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

@@ -49,7 +49,7 @@ export declare enum ApplicationState {
  * and `run()` have no effect then):
  * 1. the environment variables are set, the aliases registered (`@runtime` being the working directory);
  * 2. the options are read (from the getter given to `run()`, which may be async) and validated, the identity applied
- *    (`process.title` is the application ID, the time zone and the mode set);
+ *    (`process.title` is the application ID, except in NW.js; the time zone and the mode set);
  * 3. the application is created in a new root container: its objects are registered and its bootstrap runs in order;
  * 4. the `onLaunched()` handlers and the objects' `launched()` hooks run.
  *

package/dist/types/options/ApplicationOptions.d.ts

@@ -27,8 +27,8 @@ import { ModuleOptions } from './ModuleOptions.js';
  */
 export declare class ApplicationOptions extends ModuleOptions {
     /**
-     * The ID of the application (`'shop.app'`): the `process.title`, read by `Application.appId` and stamped on the
-     * exceptions. Required.
+     * The ID of the application (`'shop.app'`), read by `Application.appId` and stamped on the exceptions; the
+     * `process.title` too, except in NW.js. Required.
      */
     readonly id: string;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lakutata/core",
-  "version": "3.1.1",
+  "version": "3.1.5",
   "description": "The core of the lakutata framework: the IoC container and dependency injection, the object model with asynchronous construction, and DTO schema validation with the API of joi.",
   "keywords": [
     "lakutata",
@@ -107,11 +107,11 @@
     "test:engine-types": "node scripts/check-engine-types.mjs"
   },
   "dependencies": {
-    "@lakutata/utils": "3.1.1",
+    "@lakutata/utils": "3.1.5",
     "reflect-metadata": "0.2.2"
   },
   "engines": {
-    "node": "^22.13.0 || >=24.11.0"
+    "node": ">=18.10.0"
   },
   "files": [
     "dist",