@lakutata/entrypoint 3.0.0-beta.0

package/dist/cjs/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/cjs/decorators/CLIAction.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLIAction = CLIAction;
+const ControllerEntrypoint_js_1 = require("../lib/ControllerEntrypoint.js");
+const ActionOptions_js_1 = require("../lib/ActionOptions.js");
+const GetActionDTOAndOptions_js_1 = require("../lib/GetActionDTOAndOptions.js");
+function CLIAction(command, dtoConstructorOrOptions, options) {
+    return (target, propertyKey, descriptor) => {
+        const [dtoConstructor, actionOptions] = (0, GetActionDTOAndOptions_js_1.getActionDTOAndOptions)(dtoConstructorOrOptions, options);
+        (0, ControllerEntrypoint_js_1.registerCLIAction)(command, target, propertyKey, dtoConstructor, ActionOptions_js_1.ActionOptions.validate(actionOptions));
+        return descriptor;
+    };
+}

package/dist/cjs/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/cjs/decorators/HTTPAction.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTTPAction = HTTPAction;
+const ControllerEntrypoint_js_1 = require("../lib/ControllerEntrypoint.js");
+const GetActionDTOAndOptions_js_1 = require("../lib/GetActionDTOAndOptions.js");
+function HTTPAction(r, m, dtoConstructorOrOptions, options) {
+    return (target, propertyKey, descriptor) => {
+        const route = r.toString();
+        const methods = Array.isArray(m) ? m : [m];
+        const [dtoConstructor, actionOptions] = (0, GetActionDTOAndOptions_js_1.getActionDTOAndOptions)(dtoConstructorOrOptions, options);
+        (0, ControllerEntrypoint_js_1.registerHTTPAction)(route, methods, target, propertyKey, dtoConstructor, actionOptions);
+        return descriptor;
+    };
+}

package/dist/cjs/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/cjs/decorators/Prefix.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Prefix = Prefix;
+const Prefix_js_1 = require("../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}
+ *     }
+ * }
+ * ```
+ */
+function Prefix(options) {
+    return (target) => (0, Prefix_js_1.setPrefix)(target, options);
+}

package/dist/cjs/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/cjs/decorators/Schedule.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Schedule = Schedule;
+const ControllerEntrypoint_js_1 = require("../lib/ControllerEntrypoint.js");
+const GetActionDTOAndOptions_js_1 = require("../lib/GetActionDTOAndOptions.js");
+const BuiltinChannels_js_1 = require("../channel/BuiltinChannels.js");
+const Cron_js_1 = require("../lib/schedule/Cron.js");
+/**
+ * A key for each scheduled action, telling apart the actions of a same schedule
+ */
+let keys = 0;
+/**
+ * The address of a schedule
+ * @param schedule
+ */
+function ScheduleAddress(schedule) {
+    let options;
+    if (typeof schedule === 'string') {
+        //A text is an interval ("30s") when it is one, a cron expression otherwise
+        let every;
+        try {
+            every = (0, Cron_js_1.parseDuration)(schedule);
+        }
+        catch {
+            every = undefined;
+        }
+        options = every === undefined ? { cron: schedule } : { every: schedule };
+    }
+    else {
+        options = schedule;
+    }
+    const address = {};
+    if (options.every !== undefined) {
+        address.every = (0, Cron_js_1.parseDuration)(options.every);
+        address.schedule = `every ${typeof options.every === 'number' ? `${options.every}ms` : options.every}`;
+    }
+    else if (options.cron !== undefined) {
+        //The expression is checked now, not at the first run
+        new Cron_js_1.Cron(options.cron, options.timezone);
+        address.cron = options.cron;
+        address.schedule = `cron ${options.cron}`;
+        if (options.timezone)
+            address.timezone = options.timezone;
+    }
+    else {
+        throw new SyntaxError('A schedule is an interval (every) or a cron expression (cron)');
+    }
+    address.overlap = options.overlap === true;
+    address.immediate = options.immediate === true;
+    if (options.exclusive) {
+        address.exclusive = (typeof options.exclusive === 'object' ? options.exclusive.mutex : undefined) ?? 'mutex';
+        if (typeof options.exclusive === 'object' && options.exclusive.key)
+            address.exclusiveKey = options.exclusive.key;
+    }
+    address.key = `s${++keys}`;
+    return address;
+}
+function Schedule(schedule, actionOptions) {
+    return (target, propertyKey, descriptor) => {
+        const [dtoConstructor, options] = (0, GetActionDTOAndOptions_js_1.getActionDTOAndOptions)(actionOptions ?? {});
+        (0, ControllerEntrypoint_js_1.registerControllerAction)(BuiltinChannels_js_1.ScheduleChannel, target, propertyKey, ScheduleAddress(schedule), dtoConstructor, options);
+        return descriptor;
+    };
+}