@lakutata/entrypoint 3.0.0-beta.6 → 3.1.0

package/dist/types/decorators/http/DELETE.d.ts

@@ -5,11 +5,11 @@ import { HTTPContext } from '../../context/HTTPContext.js';
 /**
  * Expose the controller method as an HTTP DELETE action on a route, to delete a resource: the shorthand of
  * `@HTTPAction(route, 'delete', …)`. The adapter assembles the input: by default, the query string merged with the
- * parsed body (JSON or URL encoded), then the route parameters over them. The middlewares run, the input is validated
- * against the DTO (the defaults applied, the unknown keys removed; without a DTO, it is accepted as it is), the access
- * control runs when `acl` is set, then the method receives the validated input as a plain object. The query values and
- * the route parameters are strings and the DTO schemas are strict: convert them with `.strict(false)`. The value
- * returned is answered by the adapter's responder: as JSON by default, with the status 204 for `undefined`;
+ * parsed body (JSON; URL encoded with Express), then the route parameters over them. The middlewares run, the input is
+ * validated against the DTO (the defaults applied, the unknown keys removed; without a DTO, it is accepted as it is),
+ * the access control runs when `acl` is set, then the method receives the validated input as a plain object. The query
+ * values and the route parameters are strings and the DTO schemas are strict: convert them with `.strict(false)`. The
+ * value returned is answered by the adapter's responder: as JSON by default, with the status 204 for `undefined`;
  * `Result.status()` sets a status and headers. An error thrown is answered as `{errno, errMsg}` with the first 4xx
  * `statusCode` along its causes (400 for an invalid input), else its own `statusCode`, else 500.
  * @param r The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is

package/dist/types/decorators/http/GET.d.ts

@@ -5,13 +5,13 @@ import { HTTPContext } from '../../context/HTTPContext.js';
 /**
  * Expose the controller method as an HTTP GET action on a route, to read a resource: the shorthand of
  * `@HTTPAction(route, 'get', …)`. The adapter assembles the input: by default, the query string merged with the parsed
- * body (JSON or URL encoded), then the route parameters over them. The middlewares run, the input is validated against
- * the DTO (the defaults applied, the unknown keys removed; without a DTO, it is accepted as it is), the access control
- * runs when `acl` is set, then the method receives the validated input as a plain object. The query values and the
- * route parameters are strings and the DTO schemas are strict: convert them with `.strict(false)`. The value returned
- * is answered by the adapter's responder: as JSON by default, with the status 204 for `undefined`; `Result.status()`
- * sets a status and headers. An error thrown is answered as `{errno, errMsg}` with the first 4xx `statusCode` along its
- * causes (400 for an invalid input), else its own `statusCode`, else 500.
+ * body (JSON; URL encoded with Express), then the route parameters over them. The middlewares run, the input is
+ * validated against the DTO (the defaults applied, the unknown keys removed; without a DTO, it is accepted as it is),
+ * the access control runs when `acl` is set, then the method receives the validated input as a plain object. The query
+ * values and the route parameters are strings and the DTO schemas are strict: convert them with `.strict(false)`. The
+ * value returned is answered by the adapter's responder: as JSON by default, with the status 204 for `undefined`;
+ * `Result.status()` sets a status and headers. An error thrown is answered as `{errno, errMsg}` with the first 4xx
+ * `statusCode` along its causes (400 for an invalid input), else its own `statusCode`, else 500.
  * @param r The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is
  * prepended to it.
  * @returns The method decorator.

package/dist/types/decorators/http/HEAD.d.ts

@@ -5,14 +5,14 @@ import { HTTPContext } from '../../context/HTTPContext.js';
 /**
  * Expose the controller method as an HTTP HEAD action on a route, to answer the headers of a resource without its body:
  * the shorthand of `@HTTPAction(route, 'head', …)`. The adapter assembles the input: by default, the query string
- * merged with the parsed body (JSON or URL encoded), then the route parameters over them. The middlewares run, the
- * input is validated against the DTO (the defaults applied, the unknown keys removed; without a DTO, it is accepted as
- * it is), the access control runs when `acl` is set, then the method receives the validated input as a plain object.
- * The query values and the route parameters are strings and the DTO schemas are strict: convert them with
+ * merged with the parsed body (JSON; URL encoded with Express), then the route parameters over them. The middlewares
+ * run, the input is validated against the DTO (the defaults applied, the unknown keys removed; without a DTO, it is
+ * accepted as it is), the access control runs when `acl` is set, then the method receives the validated input as a
+ * plain object. The query values and the route parameters are strings and the DTO schemas are strict: convert them with
  * `.strict(false)`. The value returned is answered by the adapter's responder: as JSON by default, with the status 204
  * for `undefined`; `Result.status()` sets a status and headers. An error thrown is answered as `{errno, errMsg}` with
- * the first 4xx `statusCode` along its causes (400 for an invalid input), else its own `statusCode`, else 500.
- * With Fastify, a GET action also answers the HEAD requests of its route unless the route has a HEAD action.
+ * the first 4xx `statusCode` along its causes (400 for an invalid input), else its own `statusCode`, else 500. A GET
+ * action also answers the HEAD requests of its route, unless the route has a HEAD action.
  * @param r The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is
  * prepended to it.
  * @returns The method decorator.
@@ -37,7 +37,7 @@ export declare function HEAD<ClassPrototype extends Controller, Method>(r: strin
  * over them (the default of the adapters); the method receives it validated, as a plain object. The value returned is
  * answered as JSON (204 for `undefined`), an error as `{errno, errMsg}` with its status (400 for an invalid input, else
  * 500 by default).
- * With Fastify, a GET action also answers the HEAD requests of its route unless the route has a HEAD action.
+ * A GET action also answers the HEAD requests of its route, unless the route has a HEAD action.
  * @param r The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is
  * prepended to it.
  * @param dtoConstructor The DTO class validating the input; the query values and the route parameters are strings,
@@ -50,7 +50,7 @@ export declare function HEAD<ClassPrototype extends Controller, Method, DTOConst
  * `@HTTPAction(route, 'head', …)`. The input is the query string merged with the parsed body, then the route parameters
  * over them (the default of the adapters), accepted as it is. The value returned is answered as JSON (204 for
  * `undefined`), an error as `{errno, errMsg}` with its status (500 by default).
- * With Fastify, a GET action also answers the HEAD requests of its route unless the route has a HEAD action.
+ * A GET action also answers the HEAD requests of its route, unless the route has a HEAD action.
  * @param r The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is
  * prepended to it.
  * @param actionOptions The action options: `acl` runs the access control rules (false by default); `name` (unique in the
@@ -68,7 +68,7 @@ export declare function HEAD<ClassPrototype extends Controller, Method>(r: strin
  * then the route parameters over them (the default of the adapters); the method receives it validated, as a plain
  * object. The value returned is answered as JSON (204 for `undefined`), an error as `{errno, errMsg}` with its status
  * (400 for an invalid input, else 500 by default).
- * With Fastify, a GET action also answers the HEAD requests of its route unless the route has a HEAD action.
+ * A GET action also answers the HEAD requests of its route, unless the route has a HEAD action.
  * @param r The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is
  * prepended to it.
  * @param dtoConstructor The DTO class validating the input; the query values and the route parameters are strings,

package/dist/types/decorators/http/OPTIONS.d.ts

@@ -5,13 +5,14 @@ import { HTTPContext } from '../../context/HTTPContext.js';
 /**
  * Expose the controller method as an HTTP OPTIONS action on a route, to describe the communication options of a
  * resource: the shorthand of `@HTTPAction(route, 'options', …)`. The adapter assembles the input: by default, the query
- * string merged with the parsed body (JSON or URL encoded), then the route parameters over them. The middlewares run,
- * the input is validated against the DTO (the defaults applied, the unknown keys removed; without a DTO, it is accepted
- * as it is), the access control runs when `acl` is set, then the method receives the validated input as a plain object.
- * The query values and the route parameters are strings and the DTO schemas are strict: convert them with
- * `.strict(false)`. The value returned is answered by the adapter's responder: as JSON by default, with the status 204
- * for `undefined`; `Result.status()` sets a status and headers. An error thrown is answered as `{errno, errMsg}` with
- * the first 4xx `statusCode` along its causes (400 for an invalid input), else its own `statusCode`, else 500.
+ * string merged with the parsed body (JSON; URL encoded with Express), then the route parameters over them. The
+ * middlewares run, the input is validated against the DTO (the defaults applied, the unknown keys removed; without a
+ * DTO, it is accepted as it is), the access control runs when `acl` is set, then the method receives the validated
+ * input as a plain object. The query values and the route parameters are strings and the DTO schemas are strict:
+ * convert them with `.strict(false)`. The value returned is answered by the adapter's responder: as JSON by default,
+ * with the status 204 for `undefined`; `Result.status()` sets a status and headers. An error thrown is answered as
+ * `{errno, errMsg}` with the first 4xx `statusCode` along its causes (400 for an invalid input), else its own
+ * `statusCode`, else 500.
  * @param r The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is
  * prepended to it.
  * @returns The method decorator.

package/dist/types/decorators/http/PATCH.d.ts

@@ -5,11 +5,11 @@ import { HTTPContext } from '../../context/HTTPContext.js';
 /**
  * Expose the controller method as an HTTP PATCH action on a route, to update a part of a resource: the shorthand of
  * `@HTTPAction(route, 'patch', …)`. The adapter assembles the input: by default, the query string merged with the
- * parsed body (JSON or URL encoded), then the route parameters over them. The middlewares run, the input is validated
- * against the DTO (the defaults applied, the unknown keys removed; without a DTO, it is accepted as it is), the access
- * control runs when `acl` is set, then the method receives the validated input as a plain object. The query values and
- * the route parameters are strings and the DTO schemas are strict: convert them with `.strict(false)`. The value
- * returned is answered by the adapter's responder: as JSON by default, with the status 204 for `undefined`;
+ * parsed body (JSON; URL encoded with Express), then the route parameters over them. The middlewares run, the input is
+ * validated against the DTO (the defaults applied, the unknown keys removed; without a DTO, it is accepted as it is),
+ * the access control runs when `acl` is set, then the method receives the validated input as a plain object. The query
+ * values and the route parameters are strings and the DTO schemas are strict: convert them with `.strict(false)`. The
+ * value returned is answered by the adapter's responder: as JSON by default, with the status 204 for `undefined`;
  * `Result.status()` sets a status and headers. An error thrown is answered as `{errno, errMsg}` with the first 4xx
  * `statusCode` along its causes (400 for an invalid input), else its own `statusCode`, else 500.
  * @param r The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is

package/dist/types/decorators/http/POST.d.ts

@@ -5,11 +5,11 @@ import { HTTPContext } from '../../context/HTTPContext.js';
 /**
  * Expose the controller method as an HTTP POST action on a route, to create a resource or run a command: the shorthand
  * of `@HTTPAction(route, 'post', …)`. The adapter assembles the input: by default, the query string merged with the
- * parsed body (JSON or URL encoded), then the route parameters over them. The middlewares run, the input is validated
- * against the DTO (the defaults applied, the unknown keys removed; without a DTO, it is accepted as it is), the access
- * control runs when `acl` is set, then the method receives the validated input as a plain object. The query values and
- * the route parameters are strings and the DTO schemas are strict: convert them with `.strict(false)`. The value
- * returned is answered by the adapter's responder: as JSON by default, with the status 204 for `undefined`;
+ * parsed body (JSON; URL encoded with Express), then the route parameters over them. The middlewares run, the input is
+ * validated against the DTO (the defaults applied, the unknown keys removed; without a DTO, it is accepted as it is),
+ * the access control runs when `acl` is set, then the method receives the validated input as a plain object. The query
+ * values and the route parameters are strings and the DTO schemas are strict: convert them with `.strict(false)`. The
+ * value returned is answered by the adapter's responder: as JSON by default, with the status 204 for `undefined`;
  * `Result.status()` sets a status and headers. An error thrown is answered as `{errno, errMsg}` with the first 4xx
  * `statusCode` along its causes (400 for an invalid input), else its own `statusCode`, else 500.
  * @param r The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is

package/dist/types/decorators/http/PUT.d.ts

@@ -5,13 +5,13 @@ import { HTTPContext } from '../../context/HTTPContext.js';
 /**
  * Expose the controller method as an HTTP PUT action on a route, to replace a resource: the shorthand of
  * `@HTTPAction(route, 'put', …)`. The adapter assembles the input: by default, the query string merged with the parsed
- * body (JSON or URL encoded), then the route parameters over them. The middlewares run, the input is validated against
- * the DTO (the defaults applied, the unknown keys removed; without a DTO, it is accepted as it is), the access control
- * runs when `acl` is set, then the method receives the validated input as a plain object. The query values and the
- * route parameters are strings and the DTO schemas are strict: convert them with `.strict(false)`. The value returned
- * is answered by the adapter's responder: as JSON by default, with the status 204 for `undefined`; `Result.status()`
- * sets a status and headers. An error thrown is answered as `{errno, errMsg}` with the first 4xx `statusCode` along its
- * causes (400 for an invalid input), else its own `statusCode`, else 500.
+ * body (JSON; URL encoded with Express), then the route parameters over them. The middlewares run, the input is
+ * validated against the DTO (the defaults applied, the unknown keys removed; without a DTO, it is accepted as it is),
+ * the access control runs when `acl` is set, then the method receives the validated input as a plain object. The query
+ * values and the route parameters are strings and the DTO schemas are strict: convert them with `.strict(false)`. The
+ * value returned is answered by the adapter's responder: as JSON by default, with the status 204 for `undefined`;
+ * `Result.status()` sets a status and headers. An error thrown is answered as `{errno, errMsg}` with the first 4xx
+ * `statusCode` along its causes (400 for an invalid input), else its own `statusCode`, else 500.
  * @param r The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is
  * prepended to it.
  * @returns The method decorator.

package/dist/types/exceptions/AccessDeniedException.d.ts

@@ -5,6 +5,12 @@ import { Exception } from '@lakutata/core';
  */
 export declare class AccessDeniedException extends Exception {
     errno: string | number;
-    message: string;
     readonly statusCode: number;
+    /**
+     * Create the exception: its message is "Access denied" unless one is given.
+     * @param template The message, or a template filled from the parameters (see `Exception`), or an error whose
+     * message it takes; "Access denied" by default.
+     * @param params The parameters of the template.
+     */
+    constructor(template?: string | Error, ...params: any[]);
 }

package/dist/types/exceptions/EntrypointStoppedException.d.ts

@@ -1,7 +1,8 @@
 import { Exception } from '@lakutata/core';
 /**
  * The request arrived while the entrypoint is stopping (the application exiting): it is refused, the requests in
- * progress being waited for. Its errno is `E_ENTRYPOINT_STOPPED`, its HTTP status 503.
+ * progress being waited for. A request still running when the entrypoint's `shutdownTimeout` runs out is aborted with
+ * it too. Its errno is `E_ENTRYPOINT_STOPPED`, its HTTP status 503.
  */
 export declare class EntrypointStoppedException extends Exception {
     errno: string | number;

package/dist/types/exceptions/InvalidActionGroupException.d.ts

@@ -1,4 +1,8 @@
 import { Exception } from '@lakutata/core';
+/**
+ * An action is in a group that the `*ActionGroups` option of its channel (`httpActionGroups`, `cliActionGroups`,
+ * `serviceActionGroups`) does not declare, when the entrypoint initializes. Its errno is `E_INVALID_ACTION_GROUP`.
+ */
 export declare class InvalidActionGroupException extends Exception {
     errno: string | number;
 }

package/dist/types/exceptions/ServiceUnavailableException.d.ts

@@ -0,0 +1,15 @@
+import { Exception } from '@lakutata/core';
+/**
+ * A service called by an `HTTPServiceProxy` gave no response: it could not be reached, it did not answer in time, or
+ * its answer was not a service response (the error page of a proxy in front of it…). Its `cause` is the error of the
+ * request when there is one, its `service` the address of the service. Its errno is `E_SERVICE_UNAVAILABLE`, its HTTP
+ * status 503. The failures of the actions themselves are thrown as `ServiceInvokeException`.
+ */
+export declare class ServiceUnavailableException extends Exception {
+    errno: string | number;
+    readonly statusCode: number;
+    /**
+     * The address of the service called.
+     */
+    service?: string;
+}

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

@@ -3,6 +3,7 @@ export * from '../lib/Controller.js';
 export * from '../lib/AccessControlRule.js';
 export * from '../exceptions/AccessDeniedException.js';
 export * from '../exceptions/DuplicateActionNameException.js';
+export * from '../exceptions/InvalidActionGroupException.js';
 export * from '../exceptions/ControllerActionNotFoundException.js';
 export { AccessControl } from '../lib/AccessControl.js';
 export { Middleware, type ActionInvocation, type Next, type MiddlewareHandler, type MiddlewareDefinition } from '../lib/Middleware.js';
@@ -21,4 +22,6 @@ export * from '../exceptions/EntrypointStoppedException.js';
 export * from '../exceptions/ServiceInvokeException.js';
 export { scheduleEntrypoint, type ScheduleEntrypointOptions } from '../adapter/schedule/ScheduleEntrypoint.js';
 export { httpServiceEntrypoint, httpRequestOfContext, type HTTPServiceEntrypointOptions } from '../adapter/http/HTTPServiceEntrypoint.js';
+export { buildHTTPServiceProxy, HTTPServiceProxy, type BuildHTTPServiceProxyOptions } from '../adapter/http/HTTPServiceProxy.js';
+export * from '../exceptions/ServiceUnavailableException.js';
 export { Cron, parseDuration } from '../lib/schedule/Cron.js';

package/dist/types/lib/AccessControl.d.ts

@@ -39,7 +39,8 @@ import { AccessControlRule, AccessControlRuleHandler } from './AccessControlRule
  *     name: 'Report',
  *     components: {
  *         entrypoint: {class: AuditedEntrypoint, controllers: [ReportController]}
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * }))
  * ```
  */

package/dist/types/lib/AccessControlRule.d.ts

@@ -49,7 +49,8 @@ export type AccessControlRuleHandler<T extends BaseContext<Record<string, any>>>
  *             rules: [AdminRule],
  *             httpActionGroups: {admin: 'Administration'}
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * }))
  * ```
  */

package/dist/types/lib/ExplicitStatus.d.ts

@@ -0,0 +1,11 @@
+import type { ServerResponse } from 'node:http';
+/**
+ * Mark the status of a response as set by the action
+ * @param response
+ */
+export declare function markExplicitStatus(response: ServerResponse): void;
+/**
+ * Whether the status of a response was set by the action
+ * @param response
+ */
+export declare function hasExplicitStatus(response: ServerResponse): boolean;

package/dist/types/lib/Middleware.d.ts

@@ -89,7 +89,8 @@ export type MiddlewareHandler = (invocation: ActionInvocation, next: Next) => Pr
  *             controllers: [StatusController],
  *             middlewares: [Timing]
  *         })
- *     }
+ *     },
+ *     bootstrap: ['entrypoint']
  * }))
  * ```
  */

package/dist/types/lib/Preflight.d.ts

@@ -0,0 +1,8 @@
+import type { IncomingMessage, OutgoingHttpHeaders } from 'node:http';
+/**
+ * The headers of the answer to a preflight of a browser: the headers the request asks for are allowed (Authorization,
+ * the headers of the application…), the headers of the adapter when it asks for none
+ * @param request
+ * @param headers the CORS headers of the adapter
+ */
+export declare function preflightHeaders(request: IncomingMessage, headers: OutgoingHttpHeaders): OutgoingHttpHeaders;

package/dist/types/lib/ReadBody.d.ts

@@ -0,0 +1,9 @@
+import type { IncomingMessage } from 'node:http';
+/**
+ * Read the body of a request, up to a limit. Over the limit, it fails with a 413 error at once, and the rest of the body
+ * is read and dropped: the connection stays usable for the next request of the client (closing it while the client
+ * still sends would fail its request, keeping it unread would fail the next one)
+ * @param request
+ * @param limit bytes
+ */
+export declare function readBody(request: IncomingMessage, limit: number): Promise<string>;

package/dist/types/lib/pattern/FlattenPattern.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A pattern with the properties of its nested objects as keys joined by dots (`{res: {name: 'user'}}` gives
+ * `{'res.name': 'user'}`): their values are compared one by one, not as the text of their object. An empty nested
+ * object stays a value.
+ * @param pattern
+ * @param prefix
+ */
+export declare function flattenPattern(pattern: Record<string, any>, prefix?: string): Record<string, any>;
+/**
+ * A subject matched by the flattened patterns: its own properties, with the ones of its nested objects as keys joined
+ * by dots
+ * @param subject
+ */
+export declare function flattenSubject(subject: Record<string, any>): Record<string, any>;

package/package.json

@@ -1,7 +1,38 @@
 {
   "name": "@lakutata/entrypoint",
-  "version": "3.0.0-beta.6",
+  "version": "3.1.0",
   "description": "The entrypoint component of the lakutata framework: controllers and the dispatch of the CLI, HTTP and service actions.",
+  "keywords": [
+    "lakutata",
+    "controller",
+    "routing",
+    "http",
+    "express",
+    "fastify",
+    "commander",
+    "cli",
+    "socket.io",
+    "websocket",
+    "json-rpc",
+    "electron",
+    "ipc",
+    "schedule",
+    "cron",
+    "middleware",
+    "typescript"
+  ],
+  "homepage": "https://lakutata.com/packages/entrypoint",
+  "bugs": {
+    "url": "https://github.com/lakutata/lakutata/issues",
+    "email": "admin@lakutata.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lakutata/lakutata.git",
+    "directory": "packages/entrypoint"
+  },
+  "author": "alex.ma",
+  "license": "MIT",
   "type": "module",
   "main": "./dist/cjs/exports/Entrypoint.js",
   "types": "./dist/cjs/exports/Entrypoint.d.ts",
@@ -110,8 +141,8 @@
   },
   "peerDependencies": {
     "@inquirer/prompts": "^7.0.0 || ^8.0.0",
-    "@lakutata/core": "3.0.0-beta.6",
-    "@lakutata/utils": "3.0.0-beta.6",
+    "@lakutata/core": "3.1.0",
+    "@lakutata/utils": "3.1.0",
     "commander": "^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0",
     "express": "^4.21.0 || ^5.0.0",
     "fastify": "^5.0.0",
@@ -139,7 +170,7 @@
     }
   },
   "engines": {
-    "node": ">=22"
+    "node": "^22.13.0 || >=24.11.0"
   },
   "files": [
     "dist",