@lakutata/entrypoint 3.0.0-beta.0

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

@@ -0,0 +1,146 @@
+import { Container, Provider, type IBaseObjectConstructor } from '@lakutata/core';
+import type { CLIContext } from '../context/CLIContext.js';
+import type { HTTPContext } from '../context/HTTPContext.js';
+import type { ServiceContext } from '../context/ServiceContext.js';
+import type { CLIActionInfo, HTTPActionInfo, ServiceActionInfo } from '../Entrypoint.js';
+import type { BaseContext } from '../context/BaseContext.js';
+import type { ChannelActionInfo } from '../channel/EntrypointAdapter.js';
+/**
+ * A request to a controller action, as the middlewares receive it.
+ */
+export interface ActionInvocation {
+    /**
+     * The request's context; its `data` is the action's input before validation (a middleware may change it).
+     */
+    readonly context: CLIContext | HTTPContext | ServiceContext | BaseContext;
+    /**
+     * The requested action's description.
+     */
+    readonly action: HTTPActionInfo | CLIActionInfo | ServiceActionInfo | ChannelActionInfo;
+    /**
+     * The parameters taken from the request's address (such as route parameters), merged over the data into the
+     * input.
+     */
+    readonly params?: Record<string, unknown>;
+    /**
+     * The request's container, destroyed when the request ends: the controller and the middleware classes are
+     * created in it.
+     */
+    readonly container: Container;
+    /**
+     * Aborts when the request is aborted (its client gone, the entrypoint stopping).
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Run the rest of the pipeline: the next middlewares, then the input validation, the access control and the action.
+ * It may be called once per middleware; a second call rejects with a `MiddlewareNextCalledException`.
+ * @returns The action's result, as the next middlewares return it.
+ */
+export type Next = () => Promise<unknown>;
+/**
+ * A middleware function: it runs around the rest of the pipeline (see {@link Middleware.handle}).
+ * @param invocation The request.
+ * @param next Runs the rest of the pipeline.
+ * @returns The result given to the previous middleware (finally, to the adapter).
+ */
+export type MiddlewareHandler = (invocation: ActionInvocation, next: Next) => Promise<unknown>;
+/**
+ * A middleware class: it runs around the actions, created in each request's container (its dependencies are
+ * injected). Give it, or a {@link MiddlewareHandler} function, to the entrypoint's `middlewares` option (every
+ * action), an adapter's `middlewares` option (its requests), `@UseMiddlewares` (a controller class or a method) or an
+ * action's `middlewares` option. They run in that order: the entrypoint's, the adapter's, the controller parents'
+ * then the controller's, the action option's, then the method's.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller, Middleware, type ActionInvocation, type Next} from 'lakutata/com/entrypoint'
+ * import {GET, UseMiddlewares} from 'lakutata/decorator/ctrl'
+ *
+ * //Log the duration of each request
+ * class Timing extends Middleware {
+ *     public async handle(invocation: ActionInvocation, next: Next): Promise<unknown> {
+ *         const start: number = Date.now()
+ *         try {
+ *             return await next()
+ *         } finally {
+ *             console.log(`${invocation.action.name}: ${Date.now() - start}ms`)
+ *         }
+ *     }
+ * }
+ *
+ * @UseMiddlewares(async (invocation: ActionInvocation, next: Next): Promise<unknown> => {
+ *     //Short-circuit: the action does not run
+ *     if (invocation.context.data.maintenance) return {error: 'maintenance'}
+ *     return next()
+ * })
+ * class StatusController extends Controller {
+ *     @GET('/status')
+ *     public async status(): Promise<string> {
+ *         return 'ok'
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'status.app',
+ *     name: 'Status',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [StatusController],
+ *             middlewares: [Timing]
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+export declare abstract class Middleware extends Provider {
+    /**
+     * Handle a request: call `next()` to continue the pipeline and return its result (changed or not), or return
+     * without calling it to answer instead of the action. A thrown error fails the request.
+     * @param invocation The request.
+     * @param next Runs the rest of the pipeline; once at most.
+     * @returns The result given to the previous middleware (finally, to the adapter).
+     */
+    abstract handle(invocation: ActionInvocation, next: Next): Promise<unknown>;
+}
+/**
+ * A middleware: a {@link Middleware} subclass, created in each request's container, or a {@link MiddlewareHandler}
+ * function. Any other value (a class not extending `Middleware` included) fails with an `InvalidMiddlewareException`.
+ */
+export type MiddlewareDefinition = IBaseObjectConstructor<Middleware> | MiddlewareHandler;
+export type InvocationRunner = (invocation: ActionInvocation) => Promise<unknown>;
+/**
+ * Whether a middleware is a middleware class
+ * @param middleware
+ */
+export declare function isMiddlewareClass(middleware: MiddlewareDefinition): middleware is IBaseObjectConstructor<Middleware>;
+/**
+ * Check middleware definitions: middleware classes or functions
+ * @param middlewares
+ */
+export declare function validateMiddlewares(middlewares: unknown[]): MiddlewareDefinition[];
+/**
+ * Add middlewares to a controller class or an action method, the middlewares of each decorator run in their order,
+ * the decorators from top to bottom
+ * @param target
+ * @param propertyKey
+ * @param middlewares
+ */
+export declare function addMiddlewares(target: object, propertyKey: string | symbol | undefined, middlewares: MiddlewareDefinition[]): void;
+/**
+ * The middlewares of a controller class, the ones of its parent classes first
+ * @param controller
+ */
+export declare function getClassMiddlewares(controller: Function): MiddlewareDefinition[];
+/**
+ * The middlewares of an action method, declared on the method in the class hierarchy
+ * @param controller
+ * @param method
+ */
+export declare function getMethodMiddlewares(controller: Function, method: string | symbol): MiddlewareDefinition[];
+/**
+ * Compose middlewares around the innermost runner
+ * @param middlewares
+ * @param innermost
+ */
+export declare function composeMiddlewares(middlewares: MiddlewareDefinition[], innermost: InvocationRunner): InvocationRunner;

package/dist/cjs/lib/Middleware.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Middleware = void 0;
+exports.isMiddlewareClass = isMiddlewareClass;
+exports.validateMiddlewares = validateMiddlewares;
+exports.addMiddlewares = addMiddlewares;
+exports.getClassMiddlewares = getClassMiddlewares;
+exports.getMethodMiddlewares = getMethodMiddlewares;
+exports.composeMiddlewares = composeMiddlewares;
+const core_1 = require("@lakutata/core");
+const utils_1 = require("@lakutata/utils");
+const InvalidMiddlewareException_js_1 = require("../exceptions/InvalidMiddlewareException.js");
+const MiddlewareNextCalledException_js_1 = require("../exceptions/MiddlewareNextCalledException.js");
+/**
+ * A middleware class: it runs around the actions, created in each request's container (its dependencies are
+ * injected). Give it, or a {@link MiddlewareHandler} function, to the entrypoint's `middlewares` option (every
+ * action), an adapter's `middlewares` option (its requests), `@UseMiddlewares` (a controller class or a method) or an
+ * action's `middlewares` option. They run in that order: the entrypoint's, the adapter's, the controller parents'
+ * then the controller's, the action option's, then the method's.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller, Middleware, type ActionInvocation, type Next} from 'lakutata/com/entrypoint'
+ * import {GET, UseMiddlewares} from 'lakutata/decorator/ctrl'
+ *
+ * //Log the duration of each request
+ * class Timing extends Middleware {
+ *     public async handle(invocation: ActionInvocation, next: Next): Promise<unknown> {
+ *         const start: number = Date.now()
+ *         try {
+ *             return await next()
+ *         } finally {
+ *             console.log(`${invocation.action.name}: ${Date.now() - start}ms`)
+ *         }
+ *     }
+ * }
+ *
+ * @UseMiddlewares(async (invocation: ActionInvocation, next: Next): Promise<unknown> => {
+ *     //Short-circuit: the action does not run
+ *     if (invocation.context.data.maintenance) return {error: 'maintenance'}
+ *     return next()
+ * })
+ * class StatusController extends Controller {
+ *     @GET('/status')
+ *     public async status(): Promise<string> {
+ *         return 'ok'
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'status.app',
+ *     name: 'Status',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [StatusController],
+ *             middlewares: [Timing]
+ *         })
+ *     }
+ * }))
+ * ```
+ */
+class Middleware extends core_1.Provider {
+}
+exports.Middleware = Middleware;
+const CLASS_MIDDLEWARES = Symbol('ENTRYPOINT.CLASS.MIDDLEWARES');
+const METHOD_MIDDLEWARES = Symbol('ENTRYPOINT.METHOD.MIDDLEWARES');
+/**
+ * Whether a middleware is a middleware class
+ * @param middleware
+ */
+function isMiddlewareClass(middleware) {
+    return (0, utils_1.isSubclassOf)(middleware, Middleware);
+}
+/**
+ * Check middleware definitions: middleware classes or functions
+ * @param middlewares
+ */
+function validateMiddlewares(middlewares) {
+    for (const middleware of middlewares) {
+        if (typeof middleware !== 'function')
+            throw new InvalidMiddlewareException_js_1.InvalidMiddlewareException('A middleware must be a function or a class extending Middleware');
+        if (!isMiddlewareClass(middleware) && /^class[\s{]/.test(Function.prototype.toString.call(middleware)))
+            throw new InvalidMiddlewareException_js_1.InvalidMiddlewareException('The middleware class "{0}" does not extend Middleware', [middleware.name]);
+    }
+    return middlewares;
+}
+/**
+ * Add middlewares to a controller class or an action method, the middlewares of each decorator run in their order,
+ * the decorators from top to bottom
+ * @param target
+ * @param propertyKey
+ * @param middlewares
+ */
+function addMiddlewares(target, propertyKey, middlewares) {
+    const key = propertyKey === undefined ? CLASS_MIDDLEWARES : METHOD_MIDDLEWARES;
+    const existing = (propertyKey === undefined ? Reflect.getOwnMetadata(key, target) : Reflect.getOwnMetadata(key, target, propertyKey)) || [];
+    //The decorators are applied from bottom to top
+    const merged = [...validateMiddlewares(middlewares), ...existing];
+    propertyKey === undefined ? Reflect.defineMetadata(key, merged, target) : Reflect.defineMetadata(key, merged, target, propertyKey);
+}
+/**
+ * The middlewares of a controller class, the ones of its parent classes first
+ * @param controller
+ */
+function getClassMiddlewares(controller) {
+    const chain = [];
+    for (let current = controller; current && current !== Function.prototype; current = Object.getPrototypeOf(current))
+        chain.unshift(current);
+    return chain.flatMap((constructor) => Reflect.getOwnMetadata(CLASS_MIDDLEWARES, constructor) || []);
+}
+/**
+ * The middlewares of an action method, declared on the method in the class hierarchy
+ * @param controller
+ * @param method
+ */
+function getMethodMiddlewares(controller, method) {
+    for (let prototype = controller.prototype; prototype; prototype = Object.getPrototypeOf(prototype)) {
+        const middlewares = Reflect.getOwnMetadata(METHOD_MIDDLEWARES, prototype, method);
+        if (middlewares)
+            return middlewares;
+    }
+    return [];
+}
+/**
+ * Compose middlewares around the innermost runner
+ * @param middlewares
+ * @param innermost
+ */
+function composeMiddlewares(middlewares, innermost) {
+    return middlewares.reduceRight((next, middleware) => {
+        const handle = isMiddlewareClass(middleware)
+            ? async (invocation, nextStep) => (await invocation.container.get(middleware)).handle(invocation, nextStep)
+            : middleware;
+        return (invocation) => {
+            let called = false;
+            return handle(invocation, () => {
+                if (called)
+                    return Promise.reject(new MiddlewareNextCalledException_js_1.MiddlewareNextCalledException('next() is called more than once'));
+                called = true;
+                return next(invocation);
+            });
+        };
+    }, innermost);
+}

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

@@ -0,0 +1,98 @@
+import { DTO, type ActionPattern } from '@lakutata/core';
+/**
+ * A controller's action prefixes, given to `@Prefix`. The packages of the other channels add their own prefix keys
+ * (declaration merging); the keys are kept even when not declared here.
+ * @example
+ * ```typescript
+ * import {Controller} from 'lakutata/com/entrypoint'
+ * import {CLIAction, GET, Prefix, ServiceAction} from 'lakutata/decorator/ctrl'
+ *
+ * //GET /users/:id, the command user:get, the pattern {resource: 'user', act: 'get'}
+ * @Prefix({route: '/users', command: 'user', pattern: {resource: 'user'}})
+ * class UserController extends Controller {
+ *     @GET('/:id')
+ *     @CLIAction('get')
+ *     @ServiceAction({act: 'get'})
+ *     public async get(input: {id: string}): Promise<{id: string}> {
+ *         return {id: input.id}
+ *     }
+ * }
+ * ```
+ */
+export declare class PrefixOptions extends DTO {
+    /**
+     * The path prepended to the HTTP actions' routes, the slashes between them normalized (`/users` + `/:id` =
+     * `/users/:id`).
+     */
+    route?: string;
+    /**
+     * The command prepended to the CLI actions' commands, joined by `:` (`user` + `get` = `user:get`; an empty
+     * command gives the prefix alone).
+     */
+    command?: string;
+    /**
+     * The pattern merged into the service actions' patterns, deeply (`{resource: 'user'}` + `{act: 'get'}` =
+     * `{resource: 'user', act: 'get'}`); a key the prefix and the pattern set to different values fails the
+     * entrypoint's initialization with an `InvalidPrefixException`.
+     */
+    pattern?: ActionPattern;
+}
+/**
+ * Set a controller class's prefixes, merged over the ones already set on the class (by the decorators of the other
+ * channels). Used by `@Prefix` and by the prefix decorators of the packages providing a channel.
+ * @param controller The controller class.
+ * @param options The prefixes to set.
+ * @throws {Error} When the merged prefixes are invalid (the validation error of {@link PrefixOptions}).
+ * @example
+ * ```typescript
+ * import {Controller} from 'lakutata/com/entrypoint'
+ * import {setPrefix} from '@lakutata/entrypoint/channel'
+ *
+ * //A decorator of a "queue" channel prefixing the topics of a controller
+ * export function TopicPrefix(topic: string) {
+ *     return (target: typeof Controller): void => setPrefix(target, {topic: topic})
+ * }
+ * ```
+ */
+export declare function setPrefix(controller: Function, options: PrefixOptions): void;
+/**
+ * Get a controller's prefixes: the ones of the class, or else of its nearest parent class declaring them (they are not
+ * merged across the hierarchy).
+ * @param controller The controller class.
+ * @returns The prefixes, `undefined` when neither the class nor its parents declare any.
+ * @example
+ * ```typescript
+ * import {Controller} from 'lakutata/com/entrypoint'
+ * import {Prefix} from 'lakutata/decorator/ctrl'
+ * import {getPrefix} from '@lakutata/entrypoint/channel'
+ *
+ * @Prefix({route: '/users'})
+ * class UserController extends Controller {
+ * }
+ *
+ * class AdminController extends UserController {
+ * }
+ *
+ * console.log(getPrefix(AdminController)?.route) //'/users'
+ * ```
+ */
+export declare function getPrefix(controller: Function): PrefixOptions | undefined;
+/**
+ * Join a route prefix and a route
+ * @param prefix
+ * @param route
+ */
+export declare function prefixRoute(prefix: string, route: string): string;
+/**
+ * Join a command prefix and a command
+ * @param prefix
+ * @param command
+ */
+export declare function prefixCommand(prefix: string, command: string): string;
+/**
+ * Merge a pattern prefix into a pattern, a key cannot have different values
+ * @param prefix
+ * @param pattern
+ * @param path
+ */
+export declare function prefixPattern(prefix: ActionPattern, pattern: ActionPattern, path?: string): ActionPattern;

package/dist/cjs/lib/Prefix.js

@@ -0,0 +1,151 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrefixOptions = void 0;
+exports.setPrefix = setPrefix;
+exports.getPrefix = getPrefix;
+exports.prefixRoute = prefixRoute;
+exports.prefixCommand = prefixCommand;
+exports.prefixPattern = prefixPattern;
+const core_1 = require("@lakutata/core");
+const dto_1 = require("@lakutata/core/decorator/dto");
+const InvalidPrefixException_js_1 = require("../exceptions/InvalidPrefixException.js");
+/**
+ * A controller's action prefixes, given to `@Prefix`. The packages of the other channels add their own prefix keys
+ * (declaration merging); the keys are kept even when not declared here.
+ * @example
+ * ```typescript
+ * import {Controller} from 'lakutata/com/entrypoint'
+ * import {CLIAction, GET, Prefix, ServiceAction} from 'lakutata/decorator/ctrl'
+ *
+ * //GET /users/:id, the command user:get, the pattern {resource: 'user', act: 'get'}
+ * @Prefix({route: '/users', command: 'user', pattern: {resource: 'user'}})
+ * class UserController extends Controller {
+ *     @GET('/:id')
+ *     @CLIAction('get')
+ *     @ServiceAction({act: 'get'})
+ *     public async get(input: {id: string}): Promise<{id: string}> {
+ *         return {id: input.id}
+ *     }
+ * }
+ * ```
+ */
+let PrefixOptions = class PrefixOptions extends core_1.DTO {
+};
+exports.PrefixOptions = PrefixOptions;
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], PrefixOptions.prototype, "route", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], PrefixOptions.prototype, "command", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Object().optional()),
+    __metadata("design:type", Object)
+], PrefixOptions.prototype, "pattern", void 0);
+exports.PrefixOptions = PrefixOptions = __decorate([
+    (0, dto_1.IndexSignature)(core_1.DTO.Any())
+], PrefixOptions);
+const CONTROLLER_PREFIX = Symbol('ENTRYPOINT.CONTROLLER.PREFIX');
+/**
+ * Set a controller class's prefixes, merged over the ones already set on the class (by the decorators of the other
+ * channels). Used by `@Prefix` and by the prefix decorators of the packages providing a channel.
+ * @param controller The controller class.
+ * @param options The prefixes to set.
+ * @throws {Error} When the merged prefixes are invalid (the validation error of {@link PrefixOptions}).
+ * @example
+ * ```typescript
+ * import {Controller} from 'lakutata/com/entrypoint'
+ * import {setPrefix} from '@lakutata/entrypoint/channel'
+ *
+ * //A decorator of a "queue" channel prefixing the topics of a controller
+ * export function TopicPrefix(topic: string) {
+ *     return (target: typeof Controller): void => setPrefix(target, {topic: topic})
+ * }
+ * ```
+ */
+function setPrefix(controller, options) {
+    const own = Reflect.getOwnMetadata(CONTROLLER_PREFIX, controller);
+    Reflect.defineMetadata(CONTROLLER_PREFIX, PrefixOptions.validate({ ...own, ...options }), controller);
+}
+/**
+ * Get a controller's prefixes: the ones of the class, or else of its nearest parent class declaring them (they are not
+ * merged across the hierarchy).
+ * @param controller The controller class.
+ * @returns The prefixes, `undefined` when neither the class nor its parents declare any.
+ * @example
+ * ```typescript
+ * import {Controller} from 'lakutata/com/entrypoint'
+ * import {Prefix} from 'lakutata/decorator/ctrl'
+ * import {getPrefix} from '@lakutata/entrypoint/channel'
+ *
+ * @Prefix({route: '/users'})
+ * class UserController extends Controller {
+ * }
+ *
+ * class AdminController extends UserController {
+ * }
+ *
+ * console.log(getPrefix(AdminController)?.route) //'/users'
+ * ```
+ */
+function getPrefix(controller) {
+    for (let current = controller; current && current !== Function.prototype; current = Object.getPrototypeOf(current)) {
+        const prefix = Reflect.getOwnMetadata(CONTROLLER_PREFIX, current);
+        if (prefix)
+            return prefix;
+    }
+    return undefined;
+}
+/**
+ * Join a route prefix and a route
+ * @param prefix
+ * @param route
+ */
+function prefixRoute(prefix, route) {
+    const segments = [prefix, route].map((part) => part.replace(/^\/+|\/+$/g, '')).filter(Boolean);
+    return `/${segments.join('/')}`;
+}
+/**
+ * Join a command prefix and a command
+ * @param prefix
+ * @param command
+ */
+function prefixCommand(prefix, command) {
+    return command ? `${prefix}:${command}` : prefix;
+}
+/**
+ * Merge a pattern prefix into a pattern, a key cannot have different values
+ * @param prefix
+ * @param pattern
+ * @param path
+ */
+function prefixPattern(prefix, pattern, path = '') {
+    const merged = { ...pattern };
+    for (const [key, value] of Object.entries(prefix)) {
+        if (!(key in merged)) {
+            merged[key] = value;
+        }
+        else if (value !== null && typeof value === 'object' && merged[key] !== null && typeof merged[key] === 'object') {
+            merged[key] = prefixPattern(value, merged[key], `${path}${key}.`);
+        }
+        else if (merged[key] !== value) {
+            throw new InvalidPrefixException_js_1.InvalidPrefixException('The pattern prefix sets "{key}" to {prefix}, the pattern sets it to {pattern}', {
+                key: `${path}${key}`,
+                prefix: JSON.stringify(value),
+                pattern: JSON.stringify(merged[key])
+            });
+        }
+    }
+    return merged;
+}