@lakutata/entrypoint 3.0.0-beta.0

package/dist/cjs/lib/ControllerEntrypoint.d.ts

@@ -0,0 +1,168 @@
+import { Controller, type ControllerProperty } from './Controller.js';
+import { IBaseObjectConstructor, ActionPattern, JSONSchema, DTO, Component } from '@lakutata/core';
+import { ActionOptions } from './ActionOptions.js';
+import { CLIContext } from '../context/CLIContext.js';
+import { ServiceContext } from '../context/ServiceContext.js';
+import { HTTPContext } from '../context/HTTPContext.js';
+import type { AccessControlRuleHandler } from './AccessControlRule.js';
+import { MiddlewareDefinition } from './Middleware.js';
+import { ChannelDefinition } from '../channel/Channel.js';
+export type ActionPatternMap = Map<ActionPattern, ActionDetails>;
+/**
+ * A registered controller action: its address in its channel, its controller and method, its input DTO and its
+ * options. The channels read it from {@link ChannelEntry.details}.
+ */
+export type ActionDetails<ClassPrototype extends Controller = Controller, DTOConstructor extends typeof DTO = typeof DTO> = {
+    /**
+     * The action's address in its channel (`{route, method}`, `{command}`, a service pattern…), with its
+     * controller prefix once bound to an entrypoint.
+     */
+    pattern: ActionPattern;
+    /**
+     * The controller class serving the action: the registered controller, which may be a subclass of the class
+     * declaring the action.
+     */
+    constructor: IBaseObjectConstructor<ClassPrototype>;
+    /**
+     * The controller method running the action.
+     */
+    method: string | number | symbol;
+    /**
+     * The DTO validating the action's input.
+     */
+    dtoConstructor: DTOConstructor;
+    /**
+     * The JSON schema of the action's input (its DTO).
+     */
+    jsonSchema: JSONSchema;
+    /**
+     * The middlewares of the action's `middlewares` option.
+     */
+    middlewares: MiddlewareDefinition[];
+    /**
+     * Get the action's options and identity, as given to the access control rules (`targetAction`).
+     * @returns The action's identity and options.
+     */
+    getActionInfo: () => ActionInfo;
+} & ActionInfo;
+/**
+ * A controller action's identity and options.
+ */
+export type ActionInfo = {
+    /**
+     * The action's id: a UUID derived from the controller, the method and the address, stable across restarts.
+     */
+    id: string;
+    /**
+     * Whether the action is checked by the access control rules (its `acl` option).
+     */
+    acl: boolean;
+    /**
+     * The action's controller class and method, as `ControllerClass:method`.
+     */
+    action: string;
+    /**
+     * The action's name: its `name` option, `ControllerClass:method` by default.
+     */
+    name: string;
+    /**
+     * The action's description: its `description` option, empty by default.
+     */
+    description: string;
+    /**
+     * The ids of the action's groups (its `groups` option).
+     */
+    groups: string[];
+    /**
+     * The action's own access rule (its `rule` option).
+     */
+    rule?: AccessControlRuleHandler<any>;
+};
+/**
+ * The channels of the actions of a controller, its parent classes included
+ * @param target
+ */
+export declare function getControllerChannels(target: IBaseObjectConstructor<Controller>): string[];
+/**
+ * Register an action of a controller on a channel
+ * @param channel
+ * @param target
+ * @param actionPattern
+ * @param details
+ * @constructor
+ */
+export declare function registerChannelAction(channel: ChannelDefinition, target: IBaseObjectConstructor<Controller>, actionPattern: ActionPattern, details: ActionDetails): void;
+/**
+ * Register a controller method as an action of a channel, for the decorators of the packages providing a channel
+ * (the built-in `@HTTPAction`, `@CLIAction` and `@ServiceAction` call it). The action is served by the controller class
+ * and its subclasses registered in an entrypoint. Registering the same address again for the class replaces the
+ * previous action.
+ * @param channel The channel's definition (see {@link defineChannel}).
+ * @param controllerPrototype The prototype of the controller class (the decorator's target).
+ * @param propertyKey The name of the method running the action.
+ * @param actionPattern The action's address, checked by the channel's `validate`; at most 2 levels of nesting.
+ * @param dtoConstructor The DTO validating the action's input (`FlexibleDTO` to accept any input).
+ * @param actionOptions The action's options (name, description, groups, access control, middlewares); give them
+ * validated (as {@link getActionDTOAndOptions} returns them).
+ * @throws {InvalidActionPatternDepthException} When the address is nested more than 2 levels deep.
+ * @throws {InvalidMiddlewareException} When a middleware of the options is neither a function nor a `Middleware` subclass.
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {Controller, type ControllerProperty} from 'lakutata/com/entrypoint'
+ * import {getActionDTOAndOptions, getChannel, registerControllerAction, type ActionOptions} from '@lakutata/entrypoint/channel'
+ *
+ * //A decorator declaring the actions of a "queue" channel defined by its package
+ * export function OnMessage(topic: string, dtoOrOptions?: typeof DTO | ActionOptions<any>, options?: ActionOptions<any>) {
+ *     return <ClassPrototype extends Controller>(target: ClassPrototype, propertyKey: ControllerProperty<ClassPrototype>): void => {
+ *         const [dtoConstructor, actionOptions] = getActionDTOAndOptions(dtoOrOptions, options)
+ *         registerControllerAction(getChannel('queue'), target, propertyKey, {topic: topic}, dtoConstructor, actionOptions)
+ *     }
+ * }
+ * ```
+ */
+export declare function registerControllerAction<ClassPrototype extends Controller, DTOConstructor extends typeof DTO = typeof DTO>(channel: ChannelDefinition, controllerPrototype: ClassPrototype, propertyKey: ControllerProperty<ClassPrototype>, actionPattern: ActionPattern, dtoConstructor: DTOConstructor, actionOptions: ActionOptions<any>): void;
+/**
+ * Bind controller to component
+ * @param component
+ * @param controllerConstructor
+ * @constructor
+ */
+export declare function bindControllerToComponent(component: Component, controllerConstructor: IBaseObjectConstructor<Controller>): void;
+/**
+ * Get module controller action map
+ * @constructor
+ * @param component
+ */
+export declare function getComponentControllerActionMap(component: Component): Map<string, ActionPatternMap>;
+/**
+ * Register http action
+ * @param route
+ * @param methods
+ * @param controllerPrototype
+ * @param propertyKey
+ * @param dtoConstructor
+ * @param actionOptions
+ * @constructor
+ */
+export declare function registerHTTPAction<ClassPrototype extends Controller, DTOConstructor extends typeof DTO = typeof DTO>(route: string, methods: string[], controllerPrototype: ClassPrototype, propertyKey: ControllerProperty<ClassPrototype>, dtoConstructor: DTOConstructor, actionOptions: ActionOptions<HTTPContext>): void;
+/**
+ * Register cli action
+ * @param command
+ * @param controllerPrototype
+ * @param propertyKey
+ * @param dtoConstructor
+ * @param actionOptions
+ * @constructor
+ */
+export declare function registerCLIAction<ClassPrototype extends Controller, DTOConstructor extends typeof DTO = typeof DTO>(command: string, controllerPrototype: ClassPrototype, propertyKey: ControllerProperty<ClassPrototype>, dtoConstructor: DTOConstructor, actionOptions: ActionOptions<CLIContext>): void;
+/**
+ * Register service action
+ * @param pattern
+ * @param controllerPrototype
+ * @param propertyKey
+ * @param dtoConstructor
+ * @param actionOptions
+ * @constructor
+ */
+export declare function registerServiceAction<ClassPrototype extends Controller, DTOConstructor extends typeof DTO = typeof DTO>(pattern: ActionPattern, controllerPrototype: ClassPrototype, propertyKey: ControllerProperty<ClassPrototype>, dtoConstructor: DTOConstructor, actionOptions: ActionOptions<ServiceContext>): void;

package/dist/cjs/lib/ControllerEntrypoint.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getControllerChannels = getControllerChannels;
+exports.registerChannelAction = registerChannelAction;
+exports.registerControllerAction = registerControllerAction;
+exports.bindControllerToComponent = bindControllerToComponent;
+exports.getComponentControllerActionMap = getComponentControllerActionMap;
+exports.registerHTTPAction = registerHTTPAction;
+exports.registerCLIAction = registerCLIAction;
+exports.registerServiceAction = registerServiceAction;
+const utils_1 = require("@lakutata/utils");
+const core_1 = require("@lakutata/core");
+const Middleware_js_1 = require("./Middleware.js");
+const Prefix_js_1 = require("./Prefix.js");
+const Channel_js_1 = require("../channel/Channel.js");
+const BuiltinChannels_js_1 = require("../channel/BuiltinChannels.js");
+//The channels of the actions declared by a controller class
+const CONTROLLER_CHANNELS = Symbol('CONTROLLER.CHANNELS');
+//The actions of the controllers bound to an entrypoint, by channel
+const COMPONENT_CTRL_MAP = Symbol('COMPONENT.CTRL.MAP');
+/**
+ * The metadata key of the actions of a channel
+ * @param channel
+ */
+function channelActionsKey(channel) {
+    return `ENTRYPOINT.CHANNEL.ACTIONS.${channel}`;
+}
+/**
+ * Get action info
+ * @param controllerPrototype
+ * @param propertyKey
+ * @param actionOptions
+ * @param extra
+ */
+function getActionInfo(controllerPrototype, propertyKey, actionOptions, extra) {
+    const action = `${(0, utils_1.As)((0, utils_1.objectConstructor)(controllerPrototype)).className}:${String(propertyKey)}`;
+    const id = utils_1.UUID.v5(`${action}:${extra}`, utils_1.UUID.NIL);
+    const name = actionOptions.name ? actionOptions.name : action;
+    const description = actionOptions.description ? actionOptions.description : '';
+    return {
+        id: id,
+        acl: !!actionOptions.acl,
+        action: action,
+        name: name,
+        description: description,
+        groups: actionOptions.groups ? actionOptions.groups : [],
+        rule: actionOptions.rule
+    };
+}
+/**
+ * Validate action pattern definition
+ * @param actionPattern
+ */
+function validateActionPatternDefinition(actionPattern) {
+    const depth = (0, utils_1.getObjectNestingDepth)(actionPattern);
+    if (depth > 2)
+        throw new core_1.InvalidActionPatternDepthException('The maximum nesting depth of ActionPattern objects cannot be greater than 2 levels. The current nesting depth of the object is {0} levels', [depth]);
+    return actionPattern;
+}
+/**
+ * Get controller's internal action pattern map of a channel
+ * @param channel
+ * @param target
+ * @constructor
+ */
+function getInternalControllerActionPatternMap(channel, target) {
+    const key = channelActionsKey(channel);
+    const internalActionPatternMap = new Map();
+    //From the farthest parent: the closest declaration of an action wins
+    (0, utils_1.objectParentConstructors)(target).reverse().forEach(parentConstructor => {
+        const parentActionPatternMap = Reflect.getOwnMetadata(key, parentConstructor) || new Map();
+        parentActionPatternMap.forEach((value, hash) => internalActionPatternMap.set(hash, value));
+    });
+    (0, utils_1.As)(Reflect.getOwnMetadata(key, target) || new Map()).forEach((value, hash) => internalActionPatternMap.set(hash, value));
+    return internalActionPatternMap;
+}
+/**
+ * The channels of the actions of a controller, its parent classes included
+ * @param target
+ */
+function getControllerChannels(target) {
+    const names = new Set();
+    for (const constructor of [target, ...(0, utils_1.objectParentConstructors)(target)]) {
+        const own = Reflect.getOwnMetadata(CONTROLLER_CHANNELS, constructor);
+        own?.forEach((name) => names.add(name));
+    }
+    return [...names];
+}
+/**
+ * Register an action of a controller on a channel
+ * @param channel
+ * @param target
+ * @param actionPattern
+ * @param details
+ * @constructor
+ */
+function registerChannelAction(channel, target, actionPattern, details) {
+    actionPattern = validateActionPatternDefinition(channel.validate ? channel.validate(actionPattern) : actionPattern);
+    const internalActionPatternMap = getInternalControllerActionPatternMap(channel.name, target);
+    internalActionPatternMap.set((0, utils_1.objectHash)(actionPattern), {
+        pattern: actionPattern,
+        details: { ...details, pattern: actionPattern }
+    });
+    Reflect.defineMetadata(channelActionsKey(channel.name), internalActionPatternMap, target);
+    const own = Reflect.getOwnMetadata(CONTROLLER_CHANNELS, target) || new Set();
+    Reflect.defineMetadata(CONTROLLER_CHANNELS, own.add(channel.name), target);
+}
+/**
+ * Register a controller method as an action of a channel, for the decorators of the packages providing a channel
+ * (the built-in `@HTTPAction`, `@CLIAction` and `@ServiceAction` call it). The action is served by the controller class
+ * and its subclasses registered in an entrypoint. Registering the same address again for the class replaces the
+ * previous action.
+ * @param channel The channel's definition (see {@link defineChannel}).
+ * @param controllerPrototype The prototype of the controller class (the decorator's target).
+ * @param propertyKey The name of the method running the action.
+ * @param actionPattern The action's address, checked by the channel's `validate`; at most 2 levels of nesting.
+ * @param dtoConstructor The DTO validating the action's input (`FlexibleDTO` to accept any input).
+ * @param actionOptions The action's options (name, description, groups, access control, middlewares); give them
+ * validated (as {@link getActionDTOAndOptions} returns them).
+ * @throws {InvalidActionPatternDepthException} When the address is nested more than 2 levels deep.
+ * @throws {InvalidMiddlewareException} When a middleware of the options is neither a function nor a `Middleware` subclass.
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {Controller, type ControllerProperty} from 'lakutata/com/entrypoint'
+ * import {getActionDTOAndOptions, getChannel, registerControllerAction, type ActionOptions} from '@lakutata/entrypoint/channel'
+ *
+ * //A decorator declaring the actions of a "queue" channel defined by its package
+ * export function OnMessage(topic: string, dtoOrOptions?: typeof DTO | ActionOptions<any>, options?: ActionOptions<any>) {
+ *     return <ClassPrototype extends Controller>(target: ClassPrototype, propertyKey: ControllerProperty<ClassPrototype>): void => {
+ *         const [dtoConstructor, actionOptions] = getActionDTOAndOptions(dtoOrOptions, options)
+ *         registerControllerAction(getChannel('queue'), target, propertyKey, {topic: topic}, dtoConstructor, actionOptions)
+ *     }
+ * }
+ * ```
+ */
+function registerControllerAction(channel, controllerPrototype, propertyKey, actionPattern, dtoConstructor, actionOptions) {
+    const constructor = (0, utils_1.As)((0, utils_1.objectConstructor)(controllerPrototype));
+    const actionInfo = getActionInfo(controllerPrototype, propertyKey, actionOptions, channel.identify(actionPattern));
+    registerChannelAction(channel, constructor, actionPattern, {
+        ...actionInfo,
+        pattern: actionPattern,
+        constructor: constructor,
+        method: propertyKey,
+        dtoConstructor: dtoConstructor,
+        jsonSchema: dtoConstructor.toJsonSchema(),
+        middlewares: (0, Middleware_js_1.validateMiddlewares)(actionOptions.middlewares ?? []),
+        getActionInfo: () => actionInfo
+    });
+}
+/**
+ * Bind controller to component
+ * @param component
+ * @param controllerConstructor
+ * @constructor
+ */
+function bindControllerToComponent(component, controllerConstructor) {
+    const totalInternalActionPatternMap = Reflect.getOwnMetadata(COMPONENT_CTRL_MAP, component) || new Map();
+    const prefix = (0, Prefix_js_1.getPrefix)(controllerConstructor);
+    //The actions inherited from a parent controller are run by the registered controller
+    const bind = (channel, value) => {
+        const details = { ...value.details, constructor: controllerConstructor };
+        const prefixed = prefix && channel.prefix ? channel.prefix(prefix, value.pattern) : undefined;
+        if (prefixed === undefined)
+            return ['', { pattern: value.pattern, details: details }];
+        const pattern = validateActionPatternDefinition(channel.validate ? channel.validate(prefixed) : prefixed);
+        //A prefixed action is named after the registered controller, so the controllers sharing a parent have distinct actions
+        const action = `${controllerConstructor.className}:${String(details.method)}`;
+        details.name = details.name === details.action ? action : details.name;
+        details.action = action;
+        details.id = utils_1.UUID.v5(`${action}:${channel.identify(pattern)}`, utils_1.UUID.NIL);
+        details.pattern = pattern;
+        const actionInfo = { id: details.id, acl: details.acl, action: action, name: details.name, description: details.description, groups: details.groups, rule: details.rule };
+        details.getActionInfo = () => actionInfo;
+        return [(0, utils_1.objectHash)(pattern), { pattern: pattern, details: details }];
+    };
+    for (const name of getControllerChannels(controllerConstructor)) {
+        const channel = (0, Channel_js_1.getChannel)(name);
+        const map = totalInternalActionPatternMap.get(name) ?? new Map();
+        getInternalControllerActionPatternMap(name, controllerConstructor).forEach((value, hash) => {
+            const [prefixedHash, bound] = bind(channel, value);
+            map.set(prefixedHash || hash, bound);
+        });
+        totalInternalActionPatternMap.set(name, map);
+    }
+    Reflect.defineMetadata(COMPONENT_CTRL_MAP, totalInternalActionPatternMap, component);
+}
+/**
+ * Get module controller action map
+ * @constructor
+ * @param component
+ */
+function getComponentControllerActionMap(component) {
+    const totalInternalActionPatternMap = Reflect.getOwnMetadata(COMPONENT_CTRL_MAP, component) || new Map();
+    const totalActionPatternMap = new Map();
+    totalInternalActionPatternMap.forEach((map, channel) => {
+        const actions = new Map();
+        map.forEach((value) => actions.set(value.pattern, value.details));
+        totalActionPatternMap.set(channel, actions);
+    });
+    return totalActionPatternMap;
+}
+/**
+ * Register http action
+ * @param route
+ * @param methods
+ * @param controllerPrototype
+ * @param propertyKey
+ * @param dtoConstructor
+ * @param actionOptions
+ * @constructor
+ */
+function registerHTTPAction(route, methods, controllerPrototype, propertyKey, dtoConstructor, actionOptions) {
+    methods.forEach((method) => registerControllerAction(BuiltinChannels_js_1.HTTPChannel, controllerPrototype, propertyKey, { route: route, method: method }, dtoConstructor, actionOptions));
+}
+/**
+ * Register cli action
+ * @param command
+ * @param controllerPrototype
+ * @param propertyKey
+ * @param dtoConstructor
+ * @param actionOptions
+ * @constructor
+ */
+function registerCLIAction(command, controllerPrototype, propertyKey, dtoConstructor, actionOptions) {
+    registerControllerAction(BuiltinChannels_js_1.CLIChannel, controllerPrototype, propertyKey, { command: command }, dtoConstructor, actionOptions);
+}
+/**
+ * Register service action
+ * @param pattern
+ * @param controllerPrototype
+ * @param propertyKey
+ * @param dtoConstructor
+ * @param actionOptions
+ * @constructor
+ */
+function registerServiceAction(pattern, controllerPrototype, propertyKey, dtoConstructor, actionOptions) {
+    registerControllerAction(BuiltinChannels_js_1.ServiceChannel, controllerPrototype, propertyKey, pattern, dtoConstructor, actionOptions);
+}

package/dist/cjs/lib/GetActionDTOAndOptions.d.ts

@@ -0,0 +1,29 @@
+import { DTO } from '@lakutata/core';
+import { ActionOptions } from './ActionOptions.js';
+import { FlexibleDTO } from '@lakutata/core/dtos';
+/**
+ * Sort out the optional arguments of an action decorator (`(dto?)`, `(options?)` or `(dto, options)`): a function is
+ * the DTO, an object the options. The options are validated, their defaults applied.
+ * @param dtoConstructorOrOptions The DTO validating the action's input, or the action's options.
+ * @param options The action's options, when the first argument is the DTO.
+ * @returns The DTO (`FlexibleDTO`, accepting any input, when none is given) and the validated options.
+ * @throws {Error} When the options are invalid (the validation error of {@link ActionOptions}).
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {FlexibleDTO} from 'lakutata/dtos'
+ * import {Expect} from 'lakutata/decorator/dto'
+ * import {getActionDTOAndOptions} from '@lakutata/entrypoint/channel'
+ *
+ * class SendDTO extends DTO {
+ *     @Expect(DTO.String().required())
+ *     public text: string
+ * }
+ *
+ * const [dto, options] = getActionDTOAndOptions(SendDTO, {name: 'send'})
+ * console.log(dto === SendDTO, options.groups) //true []
+ * const [anyInput] = getActionDTOAndOptions({acl: true})
+ * console.log(anyInput === FlexibleDTO) //true
+ * ```
+ */
+export declare function getActionDTOAndOptions<DTOConstructor extends typeof DTO = typeof DTO>(dtoConstructorOrOptions?: DTOConstructor | ActionOptions<any>, options?: ActionOptions<any>): [DTOConstructor | typeof FlexibleDTO, ActionOptions<any>];

package/dist/cjs/lib/GetActionDTOAndOptions.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getActionDTOAndOptions = getActionDTOAndOptions;
+const ActionOptions_js_1 = require("./ActionOptions.js");
+const dtos_1 = require("@lakutata/core/dtos");
+/**
+ * Sort out the optional arguments of an action decorator (`(dto?)`, `(options?)` or `(dto, options)`): a function is
+ * the DTO, an object the options. The options are validated, their defaults applied.
+ * @param dtoConstructorOrOptions The DTO validating the action's input, or the action's options.
+ * @param options The action's options, when the first argument is the DTO.
+ * @returns The DTO (`FlexibleDTO`, accepting any input, when none is given) and the validated options.
+ * @throws {Error} When the options are invalid (the validation error of {@link ActionOptions}).
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {FlexibleDTO} from 'lakutata/dtos'
+ * import {Expect} from 'lakutata/decorator/dto'
+ * import {getActionDTOAndOptions} from '@lakutata/entrypoint/channel'
+ *
+ * class SendDTO extends DTO {
+ *     @Expect(DTO.String().required())
+ *     public text: string
+ * }
+ *
+ * const [dto, options] = getActionDTOAndOptions(SendDTO, {name: 'send'})
+ * console.log(dto === SendDTO, options.groups) //true []
+ * const [anyInput] = getActionDTOAndOptions({acl: true})
+ * console.log(anyInput === FlexibleDTO) //true
+ * ```
+ */
+function getActionDTOAndOptions(dtoConstructorOrOptions, options) {
+    let dtoConstructor = dtos_1.FlexibleDTO;
+    let actionOptions = {};
+    if (options) {
+        //The DTO may be omitted (undefined) before the options
+        if (dtoConstructorOrOptions)
+            dtoConstructor = dtoConstructorOrOptions;
+        actionOptions = options;
+    }
+    else if (dtoConstructorOrOptions) {
+        if (dtoConstructorOrOptions.constructor.name.toUpperCase() === 'FUNCTION') {
+            dtoConstructor = dtoConstructorOrOptions;
+        }
+        else {
+            actionOptions = dtoConstructorOrOptions;
+        }
+    }
+    return [dtoConstructor, ActionOptions_js_1.ActionOptions.validate(actionOptions)];
+}

package/dist/cjs/lib/HTTPErrors.d.ts

@@ -0,0 +1,55 @@
+import { type ErrorDescription } from '../types/ErrorDescription.js';
+/**
+ * Where an error answered by an HTTP adapter comes from, given to the `error` of its responder: `'action'` when the
+ * request reached an action and its dispatch failed (the entrypoint's middlewares, the validation of the input, the
+ * access control, the action itself); `'request'` when it failed before (a middleware of the web framework such as an
+ * authenticator, a hook of fastify, a body too large) or matched no route.
+ * @example
+ * ```typescript
+ * import type {Request, Response} from 'express'
+ * import {describeError, type ExpressResponder, type HTTPErrorOrigin, statusOfError} from 'lakutata/adapter/express'
+ *
+ * //The errors of the actions answered with 200, the others with their status
+ * export const responder: ExpressResponder = {
+ *     success: (response: Response, data: unknown): void => void response.json({data: data}),
+ *     error: (response: Response, error: unknown, _request: Request, origin?: HTTPErrorOrigin): void => {
+ *         response.status(origin === 'action' ? 200 : statusOfError(error)).json(describeError(error))
+ *     }
+ * }
+ * ```
+ */
+export type HTTPErrorOrigin = 'action' | 'request';
+/**
+ * Find the HTTP status of an error, read from its `statusCode` or `status`: the first client error (4xx) found on the
+ * error or along its `cause` chain, else the error's own status when it is between 400 and 599, else 500. A validation
+ * failure, wrapped in an exception whose cause is the 400 validation error, thus gives 400.
+ * @param error The error, any value.
+ * @returns The HTTP status, from 400 to 599.
+ * @example
+ * ```typescript
+ * import {statusOfError} from 'lakutata/adapter/express'
+ *
+ * class NotFound extends Error {
+ *     public readonly statusCode: number = 404
+ * }
+ *
+ * console.log(statusOfError(new NotFound('No such order'))) //404
+ * console.log(statusOfError(new Error('Failed', {cause: new NotFound('No such order')}))) //404
+ * console.log(statusOfError(new Error('Boom'))) //500
+ * ```
+ */
+export declare function statusOfError(error: unknown): number;
+/**
+ * Describe an error as the JSON responders send it: its `errno` (or `code`, `E_UNKNOWN` without either) and its
+ * `errMsg` (or `message`, or the error converted to a string).
+ * @param error The error, any value.
+ * @returns The error's number and message.
+ * @example
+ * ```typescript
+ * import {describeError, type ErrorDescription} from 'lakutata/adapter/express'
+ *
+ * const description: ErrorDescription = describeError(new Error('Boom'))
+ * console.log(description) //{errno: 'E_UNKNOWN', errMsg: 'Boom'}
+ * ```
+ */
+export declare function describeError(error: unknown): ErrorDescription;

package/dist/cjs/lib/HTTPErrors.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.statusOfError = statusOfError;
+exports.describeError = describeError;
+/**
+ * Find the HTTP status of an error, read from its `statusCode` or `status`: the first client error (4xx) found on the
+ * error or along its `cause` chain, else the error's own status when it is between 400 and 599, else 500. A validation
+ * failure, wrapped in an exception whose cause is the 400 validation error, thus gives 400.
+ * @param error The error, any value.
+ * @returns The HTTP status, from 400 to 599.
+ * @example
+ * ```typescript
+ * import {statusOfError} from 'lakutata/adapter/express'
+ *
+ * class NotFound extends Error {
+ *     public readonly statusCode: number = 404
+ * }
+ *
+ * console.log(statusOfError(new NotFound('No such order'))) //404
+ * console.log(statusOfError(new Error('Failed', {cause: new NotFound('No such order')}))) //404
+ * console.log(statusOfError(new Error('Boom'))) //500
+ * ```
+ */
+function statusOfError(error) {
+    for (let current = error; current && typeof current === 'object'; current = current.cause) {
+        const status = current.statusCode ?? current.status;
+        if (typeof status === 'number' && status >= 400 && status < 500)
+            return status;
+    }
+    const status = error?.statusCode ?? error?.status;
+    return typeof status === 'number' && status >= 400 && status < 600 ? status : 500;
+}
+/**
+ * Describe an error as the JSON responders send it: its `errno` (or `code`, `E_UNKNOWN` without either) and its
+ * `errMsg` (or `message`, or the error converted to a string).
+ * @param error The error, any value.
+ * @returns The error's number and message.
+ * @example
+ * ```typescript
+ * import {describeError, type ErrorDescription} from 'lakutata/adapter/express'
+ *
+ * const description: ErrorDescription = describeError(new Error('Boom'))
+ * console.log(description) //{errno: 'E_UNKNOWN', errMsg: 'Boom'}
+ * ```
+ */
+function describeError(error) {
+    const described = error ?? {};
+    return {
+        errno: described.errno ?? described.code ?? 'E_UNKNOWN',
+        errMsg: described.errMsg ?? described.message ?? String(error)
+    };
+}