@lakutata/entrypoint 3.0.0-beta.0

package/dist/types/decorators/CLIAction.d.ts

@@ -0,0 +1,120 @@
+import { Controller, type ControllerProperty } from '../lib/Controller.js';
+import { MethodDecorator, DTO } from '@lakutata/core';
+import { ActionOptions } from '../lib/ActionOptions.js';
+import { CLIContext } from '../context/CLIContext.js';
+/**
+ * Expose the controller method as a CLI command, run by the CLI adapters of the entrypoint (`commanderCLIEntrypoint`).
+ * Without a DTO, the command has no options and its input is accepted as it is.
+ * On a command, the CLI adapter (`commanderCLIEntrypoint`) assembles the input from the positional arguments and the
+ * options, each value parsed by the type of its property; the middlewares run, the input is validated against the DTO
+ * (the defaults applied), the access control runs when `acl` is set, then the method receives the validated input as a
+ * plain object.
+ * The value returned is written to stdout: a string as it is, a `Uint8Array` as its bytes, `undefined` and `null` as
+ * nothing, another value as indented JSON; `Result.file()` and `Result.events()` stream a file or events. An error is
+ * written to stderr as `error: <errMsg or message>` and the command ends with the code 1.
+ * @param command The command line: its name, optionally followed by positional arguments (`copy <source> [target]`,
+ * `<files...>` for several values) given to the input properties of the same names; the words before the name are
+ * groups (`package exe <file>`: the command `exe` of the group `package`). The controller's `@Prefix({command})` is
+ * prepended to it, joined by ":" (`user` and `get` give `user:get`).
+ * @returns The method decorator.
+ * @example
+ * ```typescript
+ * import {Application, DTO} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {CLIAction} from 'lakutata/decorator/ctrl'
+ * import {Expect} from 'lakutata/decorator/dto'
+ * import {commanderCLIEntrypoint} from 'lakutata/adapter/commander'
+ *
+ * class GreetDTO extends DTO {
+ *     //The positional argument <name>
+ *     @Expect(DTO.String().required().description('Who to greet'))
+ *     public name!: string
+ *
+ *     //The option --times <value>, parsed as a number
+ *     @Expect(DTO.Number().integer().min(1).optional().default(1).description('How many times'))
+ *     public times!: number
+ *
+ *     //The flag --shout
+ *     @Expect(DTO.Boolean().optional().default(false).description('Greet loudly'))
+ *     public shout!: boolean
+ * }
+ *
+ * class GreetController extends Controller {
+ *     //"app greet Ada --times 2 --shout" prints ["HELLO, ADA", "HELLO, ADA"] as JSON; "app greet Ada --times 0" prints
+ *     //"error: …" to stderr and ends with the code 1
+ *     @CLIAction('greet <name>', GreetDTO, {description: 'Greet someone'})
+ *     public async greet(input: GreetDTO): Promise<string[]> {
+ *         const text: string = `Hello, ${input.name}`
+ *         return Array(input.times).fill(input.shout ? text.toUpperCase() : text)
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'greet.app',
+ *     name: 'Greet',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [GreetController],
+ *             cli: commanderCLIEntrypoint()
+ *         })
+ *     },
+ *     bootstrap: ['entrypoint']
+ * }))
+ * ```
+ */
+export declare function CLIAction<ClassPrototype extends Controller, Method>(command: string): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;
+/**
+ * Expose the controller method as a CLI command whose options are the properties of a DTO. The CLI adapter assembles
+ * the input from the positional arguments and the options; the method receives it validated, as a plain object. The
+ * value returned is written to stdout (a string as it is, another value as JSON), an error to stderr as `error:
+ * <message>` with the exit code 1.
+ * @param command The command line: its name, optionally followed by positional arguments (`copy <source> [target]`,
+ * `<files...>` for several values) given to the input properties of the same names; the words before the name are
+ * groups (`package exe <file>`: the command `exe` of the group `package`). The controller's `@Prefix({command})` is
+ * prepended to it, joined by ":" (`user` and `get` give `user:get`).
+ * @param dtoConstructor The DTO class of the input: each of its properties not given by a positional argument is an
+ * option `--kebab-case-name` (a flag for a boolean, a repeatable option for an array, JSON for an object), mandatory
+ * when it is required without a default; its schema `.description()` is the option's help.
+ * @returns The method decorator.
+ */
+export declare function CLIAction<ClassPrototype extends Controller, Method, DTOConstructor extends typeof DTO = typeof DTO>(command: string, dtoConstructor: DTOConstructor): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;
+/**
+ * Expose the controller method as a CLI command, with action options; the command has no options and its input is
+ * accepted as it is. The value returned is written to stdout (a string as it is, another value as JSON), an error to
+ * stderr as `error: <message>` with the exit code 1.
+ * @param command The command line: its name, optionally followed by positional arguments (`copy <source> [target]`,
+ * `<files...>` for several values) given to the input properties of the same names; the words before the name are
+ * groups (`package exe <file>`: the command `exe` of the group `package`). The controller's `@Prefix({command})` is
+ * prepended to it, joined by ":" (`user` and `get` give `user:get`).
+ * @param actionOptions The action options: `description` is the command's help; `acl` runs the access control rules
+ * (false by default); `name` (unique in the CLI actions, `ClassName:method` by default) and `groups` describe the
+ * action; `rule` is an access rule of the action; `middlewares` run before the ones `@UseMiddlewares` adds to the
+ * method.
+ * @returns The method decorator.
+ * @throws {InvalidValueException} When the class is declared, if the action options are invalid.
+ * @throws {InvalidMiddlewareException} When the class is declared, if a middleware of the options is neither a function
+ * nor a class extending `Middleware`.
+ */
+export declare function CLIAction<ClassPrototype extends Controller, Method>(command: string, actionOptions: ActionOptions<CLIContext>): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;
+/**
+ * Expose the controller method as a CLI command whose options are the properties of a DTO, with action options. The CLI
+ * adapter assembles the input from the positional arguments and the options; the method receives it validated, as a
+ * plain object. The value returned is written to stdout (a string as it is, another value as JSON), an error to stderr
+ * as `error: <message>` with the exit code 1.
+ * @param command The command line: its name, optionally followed by positional arguments (`copy <source> [target]`,
+ * `<files...>` for several values) given to the input properties of the same names; the words before the name are
+ * groups (`package exe <file>`: the command `exe` of the group `package`). The controller's `@Prefix({command})` is
+ * prepended to it, joined by ":" (`user` and `get` give `user:get`).
+ * @param dtoConstructor The DTO class of the input: each of its properties not given by a positional argument is an
+ * option `--kebab-case-name` (a flag for a boolean, a repeatable option for an array, JSON for an object), mandatory
+ * when it is required without a default; its schema `.description()` is the option's help.
+ * @param actionOptions The action options: `description` is the command's help; `acl` runs the access control rules
+ * (false by default); `name` (unique in the CLI actions, `ClassName:method` by default) and `groups` describe the
+ * action; `rule` is an access rule of the action; `middlewares` run before the ones `@UseMiddlewares` adds to the
+ * method.
+ * @returns The method decorator.
+ * @throws {InvalidValueException} When the class is declared, if the action options are invalid.
+ * @throws {InvalidMiddlewareException} When the class is declared, if a middleware of the options is neither a function
+ * nor a class extending `Middleware`.
+ */
+export declare function CLIAction<ClassPrototype extends Controller, Method, DTOConstructor extends typeof DTO = typeof DTO>(command: string, dtoConstructor: DTOConstructor, actionOptions: ActionOptions<CLIContext>): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;

package/dist/types/decorators/HTTPAction.d.ts

@@ -0,0 +1,178 @@
+import { Controller, type ControllerProperty } from '../lib/Controller.js';
+import { MethodDecorator, DTO } from '@lakutata/core';
+import { ActionOptions } from '../lib/ActionOptions.js';
+import { HTTPContext } from '../context/HTTPContext.js';
+/**
+ * Expose the controller method as an HTTP action answering a route for an HTTP method, served by the HTTP adapters of
+ * the entrypoint (`expressHTTPEntrypoint`, `fastifyHTTPEntrypoint`). Without a DTO, the input is accepted as it is.
+ *
+ * On a request, 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), the access control runs when `acl` is set, then the method receives the
+ * validated input as a plain object, not a DTO instance. The query values and the route parameters are strings and the
+ * DTO schemas are strict: convert them with `.strict(false)` (`DTO.Number().strict(false)`).
+ *
+ * The value returned is answered by the adapter's responder: as JSON by default, with the status 204 for `undefined`;
+ * return `Result.status()`, `Result.file()` or `Result.events()` for a status and headers, a file or server-sent
+ * events. 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 route The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is
+ * prepended to it.
+ * @param method The HTTP method (`'get'`, `'post'`, `'put'`, `'patch'`, `'delete'`, `'head'`, `'options'`), in any
+ * case; a method the adapter does not support fails its start.
+ * @returns The method decorator.
+ * @example
+ * ```typescript
+ * import {Application, DTO} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {HTTPAction} from 'lakutata/decorator/ctrl'
+ * import {Expect} from 'lakutata/decorator/dto'
+ * import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+ *
+ * class SearchDTO extends DTO {
+ *     @Expect(DTO.String().required())
+ *     public keyword!: string
+ *
+ *     //A query value is a string: converted to a number
+ *     @Expect(DTO.Number().integer().min(1).strict(false).optional().default(1))
+ *     public page!: number
+ * }
+ *
+ * class SearchController extends Controller {
+ *     //GET /search?keyword=lamp&page=2, or POST /search with the body {"keyword": "lamp"}: answered with the JSON
+ *     //{"keyword": "lamp", "page": 2}; without a keyword, the status 400 and {"errno": "E_INVALID_VALUE", "errMsg": …}
+ *     @HTTPAction('/search', ['get', 'post'], SearchDTO)
+ *     public async search(input: SearchDTO): Promise<{ keyword: string, page: number }> {
+ *         return {keyword: input.keyword, page: input.page}
+ *     }
+ *
+ *     //PURGE /cache, an access-controlled action: answered with the status 204 (no content)
+ *     @HTTPAction('/cache', 'purge', {acl: true, name: 'Purge the cache'})
+ *     public async purge(): Promise<void> {
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'search.app',
+ *     name: 'Search',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [SearchController],
+ *             http: expressHTTPEntrypoint({port: 8080})
+ *         })
+ *     },
+ *     bootstrap: ['entrypoint']
+ * }))
+ * ```
+ */
+export declare function HTTPAction<ClassPrototype extends Controller, Method>(route: string, method: string): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;
+/**
+ * Expose the controller method as an HTTP action answering a route for an HTTP method, its input validated against a
+ * DTO. The input is the query string merged with the parsed body, 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).
+ * @param route The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is
+ * prepended to it.
+ * @param method The HTTP method (`'get'`, `'post'`…), in any case.
+ * @param dtoConstructor The DTO class validating the input; the query values and the route parameters are strings,
+ * convert them with `.strict(false)`.
+ * @returns The method decorator.
+ */
+export declare function HTTPAction<ClassPrototype extends Controller, Method, DTOConstructor extends typeof DTO = typeof DTO>(route: string, method: string, dtoConstructor: DTOConstructor): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;
+/**
+ * Expose the controller method as an HTTP action answering a route for an HTTP method, with action options; the input
+ * is 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).
+ * @param route The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is
+ * prepended to it.
+ * @param method The HTTP method (`'get'`, `'post'`…), in any case.
+ * @param actionOptions The action options: `acl` runs the access control rules (false by default); `name` (unique in the
+ * HTTP actions, `ClassName:method` by default), `description` and `groups` describe the action; `rule` is an access
+ * rule of the action; `middlewares` run before the ones `@UseMiddlewares` adds to the method.
+ * @returns The method decorator.
+ * @throws {InvalidValueException} When the class is declared, if the action options are invalid.
+ * @throws {InvalidMiddlewareException} When the class is declared, if a middleware of the options is neither a function
+ * nor a class extending `Middleware`.
+ */
+export declare function HTTPAction<ClassPrototype extends Controller, Method>(route: string, method: string, actionOptions: ActionOptions<HTTPContext>): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;
+/**
+ * Expose the controller method as an HTTP action answering a route for an HTTP method, its input validated against a
+ * DTO, with action options. The input is the query string merged with the parsed body, 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).
+ * @param route The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is
+ * prepended to it.
+ * @param method The HTTP method (`'get'`, `'post'`…), in any case.
+ * @param dtoConstructor The DTO class validating the input; the query values and the route parameters are strings,
+ * convert them with `.strict(false)`.
+ * @param actionOptions The action options: `acl` runs the access control rules (false by default); `name` (unique in the
+ * HTTP actions, `ClassName:method` by default), `description` and `groups` describe the action; `rule` is an access
+ * rule of the action; `middlewares` run before the ones `@UseMiddlewares` adds to the method.
+ * @returns The method decorator.
+ * @throws {InvalidValueException} When the class is declared, if the action options are invalid.
+ * @throws {InvalidMiddlewareException} When the class is declared, if a middleware of the options is neither a function
+ * nor a class extending `Middleware`.
+ */
+export declare function HTTPAction<ClassPrototype extends Controller, Method, DTOConstructor extends typeof DTO = typeof DTO>(route: string, method: string, dtoConstructor: DTOConstructor, actionOptions: ActionOptions<HTTPContext>): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;
+/**
+ * Expose the controller method as an HTTP action answering a route for several HTTP methods; the input is accepted as
+ * it is. The input is the query string merged with the parsed body, then the route parameters over them (the default
+ * of the adapters). The value returned is answered as JSON (204 for `undefined`), an error as `{errno, errMsg}` with
+ * its status (500 by default).
+ * @param route The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is
+ * prepended to it.
+ * @param methods The HTTP methods (`['get', 'post']`), in any case; the action answers each of them.
+ * @returns The method decorator.
+ */
+export declare function HTTPAction<ClassPrototype extends Controller, Method>(route: string, methods: string[]): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;
+/**
+ * Expose the controller method as an HTTP action answering a route for several HTTP methods, its input validated
+ * against a DTO. The input is the query string merged with the parsed body, 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).
+ * @param route The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is
+ * prepended to it.
+ * @param methods The HTTP methods (`['get', 'post']`), in any case; the action answers each of them.
+ * @param dtoConstructor The DTO class validating the input; the query values and the route parameters are strings,
+ * convert them with `.strict(false)`.
+ * @returns The method decorator.
+ */
+export declare function HTTPAction<ClassPrototype extends Controller, Method, DTOConstructor extends typeof DTO = typeof DTO>(route: string, methods: string[], dtoConstructor: DTOConstructor): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;
+/**
+ * Expose the controller method as an HTTP action answering a route for several HTTP methods, with action options; the
+ * input is 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).
+ * @param route The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is
+ * prepended to it.
+ * @param methods The HTTP methods (`['get', 'post']`), in any case; the action answers each of them.
+ * @param actionOptions The action options: `acl` runs the access control rules (false by default); `name` (unique in the
+ * HTTP actions, `ClassName:method` by default), `description` and `groups` describe the action; `rule` is an access
+ * rule of the action; `middlewares` run before the ones `@UseMiddlewares` adds to the method.
+ * @returns The method decorator.
+ * @throws {InvalidValueException} When the class is declared, if the action options are invalid.
+ * @throws {InvalidMiddlewareException} When the class is declared, if a middleware of the options is neither a function
+ * nor a class extending `Middleware`.
+ */
+export declare function HTTPAction<ClassPrototype extends Controller, Method>(route: string, methods: string[], actionOptions: ActionOptions<HTTPContext>): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;
+/**
+ * Expose the controller method as an HTTP action answering a route for several HTTP methods, its input validated
+ * against a DTO, with action options. The input is the query string merged with the parsed body, 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).
+ * @param route The route, in the syntax of the HTTP adapter (`/users/:id`); the controller's `@Prefix({route})` is
+ * prepended to it.
+ * @param methods The HTTP methods (`['get', 'post']`), in any case; the action answers each of them.
+ * @param dtoConstructor The DTO class validating the input; the query values and the route parameters are strings,
+ * convert them with `.strict(false)`.
+ * @param actionOptions The action options: `acl` runs the access control rules (false by default); `name` (unique in the
+ * HTTP actions, `ClassName:method` by default), `description` and `groups` describe the action; `rule` is an access
+ * rule of the action; `middlewares` run before the ones `@UseMiddlewares` adds to the method.
+ * @returns The method decorator.
+ * @throws {InvalidValueException} When the class is declared, if the action options are invalid.
+ * @throws {InvalidMiddlewareException} When the class is declared, if a middleware of the options is neither a function
+ * nor a class extending `Middleware`.
+ */
+export declare function HTTPAction<ClassPrototype extends Controller, Method, DTOConstructor extends typeof DTO = typeof DTO>(route: string, methods: string[], dtoConstructor: DTOConstructor, actionOptions: ActionOptions<HTTPContext>): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;

package/dist/types/decorators/Prefix.d.ts

@@ -0,0 +1,44 @@
+import { Controller } from '../lib/Controller.js';
+import { PrefixOptions } from '../lib/Prefix.js';
+/**
+ * Prefix the addresses of a controller's actions, and of the controllers extending it unless they declare their own
+ * prefixes (a subclass's `@Prefix` replaces its parent's, it does not add to it):
+ * - `route` is prepended to the routes of the HTTP actions (`'/users'` and `'/:id'` give `'/users/:id'`);
+ * - `command` is prepended to the commands of the CLI actions, joined by ":" (`'user'` and `'get'` give `'user:get'`);
+ * - `pattern` is merged into the patterns of the service actions (`{resource: 'user'}` and `{act: 'get'}` give
+ *   `{resource: 'user', act: 'get'}`).
+ *
+ * A channel without its prefix keeps the addresses as declared; the scheduled actions have none. The prefixes apply when
+ * the entrypoint registers the controller, and the prefixed actions are named after the registered controller, so that
+ * the controllers sharing a parent have distinct actions. Several `@Prefix` on a class merge their options.
+ * @param options The prefixes: `route`, `command` and `pattern`, each optional; the packages of other channels add
+ * their own.
+ * @returns The class decorator.
+ * @throws {InvalidValueException} When the class is declared, if the options are invalid.
+ * @throws {InvalidPrefixException} When the entrypoint initializes, if the pattern prefix sets a key that the pattern
+ * of an action sets to another value.
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {Controller} from 'lakutata/com/entrypoint'
+ * import {CLIAction, GET, Prefix, ServiceAction} from 'lakutata/decorator/ctrl'
+ * import {Expect} from 'lakutata/decorator/dto'
+ *
+ * class UserIdDTO extends DTO {
+ *     @Expect(DTO.String().required())
+ *     public id!: string
+ * }
+ *
+ * @Prefix({route: '/users', command: 'user', pattern: {resource: 'user'}})
+ * class UserController extends Controller {
+ *     //GET /users/:id, the command "user:get <id>" and the message {resource: 'user', act: 'get', id: …}
+ *     @GET('/:id', UserIdDTO)
+ *     @CLIAction('get <id>', UserIdDTO)
+ *     @ServiceAction({act: 'get'}, UserIdDTO)
+ *     public async get(input: UserIdDTO): Promise<{ id: string }> {
+ *         return {id: input.id}
+ *     }
+ * }
+ * ```
+ */
+export declare function Prefix<ClassConstructor extends typeof Controller>(options: PrefixOptions): (target: ClassConstructor) => void;

package/dist/types/decorators/Schedule.d.ts

@@ -0,0 +1,120 @@
+import { Controller, type ControllerProperty } from '../lib/Controller.js';
+import { MethodDecorator } from '@lakutata/core';
+import { ActionOptions } from '../lib/ActionOptions.js';
+import { ScheduleContext } from '../context/ScheduleContext.js';
+/**
+ * When a scheduled action runs (`@Schedule`): every interval (`every`) or at the times of a cron expression (`cron`),
+ * with how its runs overlap, start and are shared between the instances of the application.
+ */
+export type ScheduleOptions = ({
+    /**
+     * The interval between the runs: milliseconds, or a duration text such as `'500ms'`, `'30s'`, `'5m'`, `'1h30m'` or
+     * `'1d'`. The first run comes one interval after the application launched; the runs missed while the process was
+     * suspended are skipped.
+     */
+    every: number | string;
+    cron?: never;
+    timezone?: never;
+} | {
+    /**
+     * The times of the runs: a cron expression `'second minute hour day-of-month month day-of-week'` (the second is
+     * optional: 5 fields run at second 0), or a macro (`'@hourly'`, `'@daily'`…).
+     */
+    cron: string;
+    /**
+     * The IANA time zone the expression is read in (`'Asia/Shanghai'`).
+     * @default the local time zone of the process
+     */
+    timezone?: string;
+    every?: never;
+}) & {
+    /**
+     * Start a run while the previous run of the action is still in progress; otherwise the run is skipped.
+     * @default false
+     */
+    overlap?: boolean;
+    /**
+     * Also run the action once as soon as the application launched, besides its schedule.
+     * @default false
+     */
+    immediate?: boolean;
+    /**
+     * Run the action in one instance of the application at a time, with the locks of a mutex component
+     * (`lakutata/com/mutex`): each run is made by the instance acquiring its lock, the others skip it, and the intervals
+     * are aligned on their multiples so that every instance plans the same times. `true` uses the component named
+     * `'mutex'`; `{mutex, key}` names the component and the lock (the action name by default). Without the component,
+     * the action does not run and the error is logged.
+     * @default false
+     */
+    exclusive?: boolean | {
+        mutex?: string;
+        key?: string;
+    };
+};
+/**
+ * Run the controller method on a schedule, when the entrypoint has a schedule adapter (`schedule: scheduleEntrypoint()`
+ * of `lakutata/com/entrypoint`). The runs start once the application launched and the runs in progress end before it
+ * stops. Each run has its own request scope and goes through the middlewares and the access control like a request; the
+ * method receives an empty input, and `this.context` is a `ScheduleContext` (its schedule, its planned time and its run
+ * number). The value returned is ignored; an error thrown is given to the adapter's `onError`, or logged by the
+ * application's `log` component (to the console without it), and the next runs go on.
+ * @param schedule A duration text (`'30s'`, `'1h30m'`) for an interval, any other text for a cron expression
+ * (`'0 *\/5 * * * *'`, `'@daily'`), or the schedule options.
+ * @returns The method decorator.
+ * @throws {SyntaxError} When the class is declared, if the interval or the cron expression is invalid.
+ * @throws {RangeError} When the class is declared, if the time zone is unknown.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller, ScheduleContext, scheduleEntrypoint} from 'lakutata/com/entrypoint'
+ * import {Schedule} from 'lakutata/decorator/ctrl'
+ *
+ * class JobController extends Controller {
+ *     //Every 30 seconds, and once as soon as the application launched
+ *     @Schedule({every: '30s', immediate: true})
+ *     public async heartbeat(): Promise<void> {
+ *         if (this.context instanceof ScheduleContext) console.log(`run ${this.context.run} of ${this.context.schedule}`)
+ *     }
+ *
+ *     //Every 5 minutes, at second 0
+ *     @Schedule('0 *\/5 * * * *')
+ *     public async report(): Promise<void> {
+ *     }
+ *
+ *     //At 03:00 every day in Shanghai, by one instance of the application at a time (a mutex component named "mutex")
+ *     @Schedule({cron: '0 3 * * *', timezone: 'Asia/Shanghai', exclusive: true}, {name: 'Purge the expired sessions'})
+ *     public async purge(): Promise<void> {
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'jobs.app',
+ *     name: 'Jobs',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [JobController],
+ *             schedule: scheduleEntrypoint({onError: (error: unknown): void => console.error(error)})
+ *         })
+ *     },
+ *     bootstrap: ['entrypoint']
+ * }))
+ * ```
+ */
+export declare function Schedule<ClassPrototype extends Controller, Method>(schedule: string | ScheduleOptions): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;
+/**
+ * Run the controller method on a schedule, with action options, when the entrypoint has a schedule adapter
+ * (`schedule: scheduleEntrypoint()`). Each run has its own request scope and goes through the middlewares and the access
+ * control like a request; the method receives an empty input and `this.context` is a `ScheduleContext`. An error thrown
+ * is given to the adapter's `onError`, or logged, and the next runs go on.
+ * @param schedule A duration text (`'30s'`, `'1h30m'`) for an interval, any other text for a cron expression
+ * (`'0 *\/5 * * * *'`, `'@daily'`), or the schedule options.
+ * @param actionOptions The action options: `name` (`ClassName:method` by default) names the action in the logs and is the
+ * default lock key of an exclusive schedule; `description` and `groups` describe it; `acl` runs the access control
+ * rules (false by default); `rule` is an access rule of the action; `middlewares` run before the ones `@UseMiddlewares`
+ * adds to the method.
+ * @returns The method decorator.
+ * @throws {SyntaxError} When the class is declared, if the interval or the cron expression is invalid.
+ * @throws {RangeError} When the class is declared, if the time zone is unknown.
+ * @throws {InvalidValueException} When the class is declared, if the action options are invalid.
+ */
+export declare function Schedule<ClassPrototype extends Controller, Method>(schedule: string | ScheduleOptions, actionOptions: ActionOptions<ScheduleContext>): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;

package/dist/types/decorators/ServiceAction.d.ts

@@ -0,0 +1,116 @@
+import { Controller, type ControllerProperty } from '../lib/Controller.js';
+import { MethodDecorator, ActionPattern, DTO } from '@lakutata/core';
+import { ActionOptions } from '../lib/ActionOptions.js';
+import { ServiceContext } from '../context/ServiceContext.js';
+/**
+ * Expose the controller method as a service action, addressed by a pattern that the messages of the service adapters
+ * must match. Without a DTO, the input is accepted as it is.
+ * A service adapter (`socketIOServiceEntrypoint`, `jsonRPCServiceEntrypoint`, `electronIPCServiceEntrypoint`,
+ * `httpServiceEntrypoint`) receives a message, an object, and dispatches it to the action whose pattern it matches. The
+ * input is the message without the keys of the pattern; the middlewares run, the input is validated against the DTO
+ * (the defaults applied, the unknown keys removed), the access control runs when `acl` is set, then the method receives
+ * the validated input as a plain object.
+ * The value returned is sent back to the caller: `{success: true, error: null, payload}` for the Socket.IO, Electron
+ * and HTTP service adapters, the `result` of the response for JSON-RPC. An error is sent as `{success: false, error,
+ * payload: null}`, `error` holding its properties (`errno`, `errMsg`, `statusCode`, `message`…); JSON-RPC answers it as
+ * an error response. A message no pattern matches fails with `ControllerActionNotFoundException`.
+ * @param pattern The pattern of the action: an object (nested 2 levels at most) whose keys the messages must hold with
+ * the same values; a string value may be a glob (`'user.*'`, `*` any characters, `?` one). The most specific pattern
+ * matching a message wins. The controller's `@Prefix({pattern})` is merged into it.
+ * @returns The method decorator.
+ * @throws {InvalidActionPatternDepthException} When the class is declared, if the pattern is nested more than 2 levels.
+ * @example
+ * ```typescript
+ * import {Application, DTO} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ * import {Expect} from 'lakutata/decorator/dto'
+ * import {socketIOServiceEntrypoint} from 'lakutata/adapter/socket.io'
+ *
+ * class TransferDTO extends DTO {
+ *     @Expect(DTO.String().required())
+ *     public to!: string
+ *
+ *     @Expect(DTO.Number().positive().required())
+ *     public amount!: number
+ * }
+ *
+ * class AccountController extends Controller {
+ *     //The message {resource: 'account', act: 'transfer', to: 'ada', amount: 5}: the input is {to: 'ada', amount: 5},
+ *     //the caller receives {success: true, error: null, payload: {to: 'ada', amount: 5, done: true}}; without an
+ *     //amount, {success: false, error: {errno: 'E_INVALID_VALUE', …}, payload: null}
+ *     @ServiceAction({resource: 'account', act: 'transfer'}, TransferDTO, {acl: true})
+ *     public async transfer(input: TransferDTO): Promise<{ to: string, amount: number, done: boolean }> {
+ *         return {to: input.to, amount: input.amount, done: true}
+ *     }
+ *
+ *     //Any message whose act starts with "audit.", its other keys accepted as they are
+ *     @ServiceAction({resource: 'account', act: 'audit.*'})
+ *     public async audit(input: Record<string, unknown>): Promise<void> {
+ *         console.log(input)
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'bank.app',
+ *     name: 'Bank',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [AccountController],
+ *             service: socketIOServiceEntrypoint({port: 3000})
+ *         })
+ *     },
+ *     bootstrap: ['entrypoint']
+ * }))
+ * ```
+ */
+export declare function ServiceAction<ClassPrototype extends Controller, Method>(pattern: ActionPattern): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;
+/**
+ * Expose the controller method as a service action addressed by a pattern, its input validated against a DTO. The input
+ * is the message without the keys of the pattern; the method receives it validated, as a plain object. The value
+ * returned is sent back as `{success: true, error: null, payload}`, an error as `{success: false, error, payload:
+ * null}` (a JSON-RPC result or error response).
+ * @param pattern The pattern of the action: an object (nested 2 levels at most) whose keys the messages must hold with
+ * the same values; a string value may be a glob (`'user.*'`, `*` any characters, `?` one). The most specific pattern
+ * matching a message wins. The controller's `@Prefix({pattern})` is merged into it.
+ * @param dtoConstructor The DTO class validating the input: the message without the keys of the pattern.
+ * @returns The method decorator.
+ * @throws {InvalidActionPatternDepthException} When the class is declared, if the pattern is nested more than 2 levels.
+ */
+export declare function ServiceAction<ClassPrototype extends Controller, Method, DTOConstructor extends typeof DTO = typeof DTO>(pattern: ActionPattern, dtoConstructor: DTOConstructor): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;
+/**
+ * Expose the controller method as a service action addressed by a pattern, with action options; the input, the message
+ * without the keys of the pattern, is accepted as it is. The value returned is sent back as `{success: true, error:
+ * null, payload}`, an error as `{success: false, error, payload: null}` (a JSON-RPC result or error response).
+ * @param pattern The pattern of the action: an object (nested 2 levels at most) whose keys the messages must hold with
+ * the same values; a string value may be a glob (`'user.*'`, `*` any characters, `?` one). The most specific pattern
+ * matching a message wins. The controller's `@Prefix({pattern})` is merged into it.
+ * @param actionOptions The action options: `acl` runs the access control rules (false by default); `name` (unique in
+ * the service actions, `ClassName:method` by default), `description` and `groups` describe the action; `rule` is an
+ * access rule of the action; `middlewares` run before the ones `@UseMiddlewares` adds to the method.
+ * @returns The method decorator.
+ * @throws {InvalidActionPatternDepthException} When the class is declared, if the pattern is nested more than 2 levels.
+ * @throws {InvalidValueException} When the class is declared, if the action options are invalid.
+ * @throws {InvalidMiddlewareException} When the class is declared, if a middleware of the options is neither a function
+ * nor a class extending `Middleware`.
+ */
+export declare function ServiceAction<ClassPrototype extends Controller, Method>(pattern: ActionPattern, actionOptions: ActionOptions<ServiceContext>): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;
+/**
+ * Expose the controller method as a service action addressed by a pattern, its input validated against a DTO, with
+ * action options. The input is the message without the keys of the pattern; the method receives it validated, as a
+ * plain object. The value returned is sent back as `{success: true, error: null, payload}`, an error as `{success:
+ * false, error, payload: null}` (a JSON-RPC result or error response).
+ * @param pattern The pattern of the action: an object (nested 2 levels at most) whose keys the messages must hold with
+ * the same values; a string value may be a glob (`'user.*'`, `*` any characters, `?` one). The most specific pattern
+ * matching a message wins. The controller's `@Prefix({pattern})` is merged into it.
+ * @param dtoConstructor The DTO class validating the input: the message without the keys of the pattern.
+ * @param actionOptions The action options: `acl` runs the access control rules (false by default); `name` (unique in
+ * the service actions, `ClassName:method` by default), `description` and `groups` describe the action; `rule` is an
+ * access rule of the action; `middlewares` run before the ones `@UseMiddlewares` adds to the method.
+ * @returns The method decorator.
+ * @throws {InvalidActionPatternDepthException} When the class is declared, if the pattern is nested more than 2 levels.
+ * @throws {InvalidValueException} When the class is declared, if the action options are invalid.
+ * @throws {InvalidMiddlewareException} When the class is declared, if a middleware of the options is neither a function
+ * nor a class extending `Middleware`.
+ */
+export declare function ServiceAction<ClassPrototype extends Controller, Method, DTOConstructor extends typeof DTO = typeof DTO>(pattern: ActionPattern, dtoConstructor: DTOConstructor, actionOptions: ActionOptions<ServiceContext>): MethodDecorator<ClassPrototype, Method, ControllerProperty<ClassPrototype>>;

package/dist/types/decorators/UseMiddlewares.d.ts

@@ -0,0 +1,52 @@
+import { MiddlewareDefinition } from '../lib/Middleware.js';
+/**
+ * Add middlewares to all the actions of a controller (on the class) or to one action (on the method). A middleware is a
+ * function `(invocation, next) => Promise<unknown>` or a class extending `Middleware`, created in the container of each
+ * request (its dependencies injected). It receives the request's context, whose data is the input before validation,
+ * and returns the result of `next()` (the rest of the pipeline), or another value without calling it, which is then
+ * answered instead of the action's result; an error it throws is answered as the action's error.
+ *
+ * The order of a request: the entrypoint's `middlewares`, the adapter's `middlewares`, the ones of the controller classes
+ * (the parent classes first), of the action options, of the action method, then the input validation, the access
+ * control and the action. Several `@UseMiddlewares` on a target run from top to bottom, the middlewares of each in their
+ * order. The middlewares of a method are taken from the nearest class declaring them for it: an overriding method
+ * replaces them.
+ * @param middlewares The middleware functions and classes, in their running order.
+ * @returns The class or method decorator.
+ * @throws {InvalidMiddlewareException} When the decorator is called, if a middleware is neither a function nor a class
+ * extending `Middleware`.
+ * @example
+ * ```typescript
+ * import {Controller, Middleware, type ActionInvocation, type Next} from 'lakutata/com/entrypoint'
+ * import {GET, UseMiddlewares} from 'lakutata/decorator/ctrl'
+ *
+ * //A middleware function: logs the duration of each action of the controller
+ * async function Timing(invocation: ActionInvocation, next: Next): Promise<unknown> {
+ *     const started: number = Date.now()
+ *     try {
+ *         return await next()
+ *     } finally {
+ *         console.log(`${invocation.action.name}: ${Date.now() - started}ms`)
+ *     }
+ * }
+ *
+ * //A middleware class: answers without running the action during a maintenance
+ * class Maintenance extends Middleware {
+ *     public async handle(invocation: ActionInvocation, next: Next): Promise<unknown> {
+ *         if (process.env.MAINTENANCE) return {maintenance: true}
+ *         return await next()
+ *     }
+ * }
+ *
+ * @UseMiddlewares(Timing)
+ * class StatusController extends Controller {
+ *     //Timing, then Maintenance, then the action
+ *     @GET('/status')
+ *     @UseMiddlewares(Maintenance)
+ *     public async status(): Promise<{ ok: boolean }> {
+ *         return {ok: true}
+ *     }
+ * }
+ * ```
+ */
+export declare function UseMiddlewares(...middlewares: MiddlewareDefinition[]): (target: object, propertyKey?: string | symbol, descriptor?: PropertyDescriptor) => void;