@lakutata/entrypoint 3.0.0-beta.0

package/dist/types/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/types/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/types/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/types/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/types/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/types/lib/Result.d.ts

@@ -0,0 +1,173 @@
+import type { Readable } from 'node:stream';
+import { ActionResult } from './ActionResult.js';
+/**
+ * A result with a status and headers: the HTTP adapters set them on the response and send the data with their
+ * responder; the CLI adapter outputs the data. Build it with `Result.status()`.
+ * @example
+ * ```typescript
+ * import {Controller, Result, type StatusResult} from 'lakutata/com/entrypoint'
+ * import {POST} from 'lakutata/decorator/ctrl'
+ *
+ * class OrderController extends Controller {
+ *     //201 Created, with the location of the order
+ *     @POST('/orders')
+ *     public async create(): Promise<StatusResult> {
+ *         return Result.status(201, {id: 42}, {Location: '/orders/42'})
+ *     }
+ * }
+ * ```
+ */
+export declare class StatusResult extends ActionResult {
+    readonly status: number;
+    protected readonly payload?: unknown | undefined;
+    readonly headers: Record<string, string>;
+    /**
+     * Create a result with a status and headers.
+     * @param status The HTTP status.
+     * @param payload The data sent.
+     * @param headers The response headers.
+     */
+    constructor(status: number, payload?: unknown | undefined, headers?: Record<string, string>);
+    /**
+     * The data sent with the status.
+     */
+    get data(): unknown;
+}
+/**
+ * How a {@link FileResult} is sent.
+ */
+export type FileResultOptions = {
+    /**
+     * The content type, inferred from the file's or the attachment's name when omitted.
+     */
+    contentType?: string;
+    /**
+     * The name to send the file under, as an attachment (`Content-Disposition: attachment`); it is displayed inline
+     * when omitted.
+     */
+    filename?: string;
+    /**
+     * The content's entity tag, sent quoted in `ETag`: a request whose `If-None-Match` matches it gets a 304 response
+     * without content.
+     */
+    etag?: string;
+    /**
+     * Other response headers.
+     */
+    headers?: Record<string, string>;
+};
+/**
+ * A file: a path, a buffer or a stream. The HTTP adapters send it with its options; the CLI adapter writes its
+ * content to stdout. Build it with `Result.file()`.
+ * @example
+ * ```typescript
+ * import {Readable} from 'node:stream'
+ * import {Controller, Result, type FileResult} from 'lakutata/com/entrypoint'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ *
+ * class ReportController extends Controller {
+ *     //A file on disk, downloaded as report.pdf
+ *     @GET('/report')
+ *     public async report(): Promise<FileResult> {
+ *         return Result.file('./reports/latest.pdf', {filename: 'report.pdf', etag: 'v1'})
+ *     }
+ *
+ *     //A stream, with its content type
+ *     @GET('/export')
+ *     public async export(): Promise<FileResult> {
+ *         return Result.file(Readable.from(['id,name\n', '1,Ada\n']), {contentType: 'text/csv'})
+ *     }
+ * }
+ * ```
+ */
+export declare class FileResult extends ActionResult {
+    readonly source: string | Buffer | Readable;
+    readonly options: FileResultOptions;
+    /**
+     * Create a file result.
+     * @param source The file's path (resolved from the working directory), its content, or a stream of its content.
+     * @param options How the file is sent.
+     */
+    constructor(source: string | Buffer | Readable, options?: FileResultOptions);
+    /**
+     * The file's source.
+     */
+    get data(): unknown;
+}
+/**
+ * Send an event of a stream; nothing is sent once the client has left.
+ * @param data The event's data, serialized to JSON unless it is a string.
+ * @param event The event's name; the clients' default event (`message`) when omitted.
+ * @param id The event's id, which the client sends back as `Last-Event-ID` when it reconnects.
+ */
+export type SendEvent = (data: unknown, event?: string, id?: string) => void;
+/**
+ * Produce the events of a stream. The stream ends when the producer settles (an error ends it too, without other
+ * notice); when the client leaves, the signal aborts and the producer should return.
+ * @param send Sends an event.
+ * @param signal Aborts when the client leaves or the adapter stops.
+ */
+export type EventsProducer = (send: SendEvent, signal: AbortSignal) => Promise<void> | void;
+/**
+ * A stream of events: Server-Sent Events for the HTTP adapters, each event's data written as a line by the CLI
+ * adapter. Build it with `Result.events()`.
+ *
+ * The producer runs after the action returned, once the request's container is destroyed: it must only use objects
+ * living longer than the request (the components), not the controller's request-scoped dependencies.
+ * @example
+ * ```typescript
+ * import {Controller, Result, type EventsResult} from 'lakutata/com/entrypoint'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ *
+ * class ClockController extends Controller {
+ *     //The time every second until the client leaves
+ *     @GET('/clock')
+ *     public async clock(): Promise<EventsResult> {
+ *         return Result.events(async (send, signal): Promise<void> => {
+ *             while (!signal.aborted) {
+ *                 send({now: new Date().toISOString()}, 'tick')
+ *                 await new Promise((resolve): unknown => setTimeout(resolve, 1000))
+ *             }
+ *         })
+ *     }
+ * }
+ * ```
+ */
+export declare class EventsResult extends ActionResult {
+    readonly producer: EventsProducer;
+    /**
+     * Create an event stream result.
+     * @param producer Produces the events.
+     */
+    constructor(producer: EventsProducer);
+    /**
+     * Always `undefined`: an event stream has no data of its own.
+     */
+    get data(): unknown;
+}
+/**
+ * Build the results an action returns to describe its output beyond its data.
+ */
+export declare const Result: {
+    /**
+     * Build a result with a status and headers.
+     * @param status The HTTP status.
+     * @param data The data sent.
+     * @param headers The response headers.
+     * @returns The {@link StatusResult}.
+     */
+    status: (status: number, data?: unknown, headers?: Record<string, string>) => StatusResult;
+    /**
+     * Build a file result.
+     * @param source The file's path (resolved from the working directory), its content, or a stream of its content.
+     * @param options How the file is sent.
+     * @returns The {@link FileResult}.
+     */
+    file: (source: string | Buffer | Readable, options?: FileResultOptions) => FileResult;
+    /**
+     * Build an event stream result (Server-Sent Events for HTTP).
+     * @param producer Produces the events, after the action returned.
+     * @returns The {@link EventsResult}.
+     */
+    events: (producer: EventsProducer) => EventsResult;
+};