@lakutata/entrypoint 3.0.0-beta.0

package/dist/types/channel/Channel.d.ts

@@ -0,0 +1,196 @@
+import type { ActionPattern } from '@lakutata/core';
+import type { BaseContext } from '../context/BaseContext.js';
+import type { ActionDetails } from '../lib/ControllerEntrypoint.js';
+import type { PrefixOptions } from '../lib/Prefix.js';
+import type { BaseActionInfo } from '../Entrypoint.js';
+/**
+ * How the requests of a channel arrive:
+ * - `request`: a caller waits for the result (HTTP, CLI, service, MCP, D-Bus).
+ * - `delivery`: no caller waits, the adapter acknowledges the outcome (message queues).
+ * - `trigger`: no external caller, the adapter runs the actions on its own (schedules).
+ */
+export type ChannelKind = 'request' | 'delivery' | 'trigger';
+/**
+ * An action of a channel, as given to {@link ChannelDefinition.createMatcher}: one per address.
+ */
+export interface ChannelEntry {
+    /**
+     * The action's details: its address (`details.pattern`), controller, method, DTO and options.
+     */
+    readonly details: ActionDetails;
+    /**
+     * The action's description, with the fields of {@link ChannelDefinition.describe}.
+     */
+    readonly info: BaseActionInfo & Record<string, unknown>;
+}
+/**
+ * The action matching a request, with the parameters taken from its address.
+ */
+export interface ChannelMatch {
+    /**
+     * The matching action: one of the entries given to {@link ChannelDefinition.createMatcher}.
+     */
+    readonly entry: ChannelEntry;
+    /**
+     * The parameters taken from the request's address (such as route parameters); they are merged into the action's
+     * input and take precedence over the request's data.
+     */
+    readonly params?: Record<string, unknown>;
+}
+/**
+ * The lookup of a channel's actions, created by {@link ChannelDefinition.createMatcher}.
+ */
+export interface ChannelMatcher {
+    /**
+     * Find the action of a request.
+     * @param context The request's context.
+     * @returns The matching action, `undefined` when none matches (the request then fails with
+     * {@link ChannelDefinition.notFound}).
+     */
+    match(context: BaseContext): ChannelMatch | undefined;
+}
+/**
+ * A channel: how the actions declare their addresses and how a request finds its action. The entrypoint package
+ * defines `http`, `cli`, `service` and `schedule`; a package providing another transport defines its channel with
+ * {@link defineChannel} and registers the actions of its decorators with `registerControllerAction`.
+ */
+export interface ChannelDefinition {
+    /**
+     * The channel's name, which is also the key of its adapters in the entrypoint options.
+     */
+    readonly name: string;
+    /**
+     * How the channel's requests arrive.
+     */
+    readonly kind: ChannelKind;
+    /**
+     * The `type` of the channel's request contexts; the access control rules are selected by it.
+     */
+    readonly contextType: string;
+    /**
+     * Check, and possibly normalize, an address when an action is declared and when a controller prefix is applied to
+     * it; throw to reject it.
+     * @param address The address given to the action decorator.
+     * @returns The address to register.
+     */
+    validate?(address: ActionPattern): ActionPattern;
+    /**
+     * The text identifying an address, from which the action's id is derived: two addresses with the same text are
+     * the same action.
+     * @param address The action's address.
+     * @returns The identifying text.
+     */
+    identify(address: ActionPattern): string;
+    /**
+     * The fields describing an address in the action's description (such as `{route}` for HTTP).
+     * @param address The action's address.
+     * @returns The fields added to the action's description.
+     */
+    describe(address: ActionPattern): Record<string, unknown>;
+    /**
+     * Apply a controller's prefixes to an address; without this method the channel's addresses are not prefixed.
+     * @param prefix The controller's prefixes (set with `@Prefix`).
+     * @param address The action's address.
+     * @returns The prefixed address, `undefined` when the prefixes do not concern the channel.
+     */
+    prefix?(prefix: PrefixOptions, address: ActionPattern): ActionPattern | undefined;
+    /**
+     * Create the lookup of the channel's actions, once when the entrypoint starts.
+     * @param entries The channel's actions, one per address.
+     * @returns The lookup.
+     */
+    createMatcher(entries: ChannelEntry[]): ChannelMatcher;
+    /**
+     * Prepare a matched request's context before its dispatch (the service channel removes the pattern keys from the
+     * data). Not called for the requests dispatched to an action directly (`ChannelRuntime.dispatchTo`).
+     * @param entry The matched action.
+     * @param context The request's context, changed in place.
+     */
+    prepare?(entry: ChannelEntry, context: BaseContext): void;
+    /**
+     * The error a request matching no action fails with.
+     * @param context The request's context.
+     * @returns The error to throw.
+     */
+    notFound(context: BaseContext): Error;
+}
+/**
+ * Define a channel. A package providing a channel defines it when it is loaded; defining the same definition object
+ * again does nothing.
+ * @param definition The channel's definition.
+ * @returns The same definition.
+ * @throws {InvalidChannelException} When another definition already has the name.
+ * @example
+ * ```typescript
+ * import {Controller, ControllerActionNotFoundException, type BaseContext, type ControllerProperty} from 'lakutata/com/entrypoint'
+ * import {defineChannel, registerControllerAction, type ChannelEntry} from '@lakutata/entrypoint/channel'
+ * import {FlexibleDTO} from 'lakutata/dtos'
+ *
+ * //A channel of the messages of a queue, addressed by their topic
+ * export const QueueChannel = defineChannel({
+ *     name: 'queue',
+ *     kind: 'delivery',
+ *     contextType: 'QUEUE',
+ *     identify: (address): string => address.topic,
+ *     describe: (address): Record<string, unknown> => ({topic: address.topic}),
+ *     createMatcher: (entries: ChannelEntry[]) => ({
+ *         match: (context: BaseContext) => {
+ *             const entry: ChannelEntry | undefined = entries.find(candidate => candidate.details.pattern.topic === context.topic)
+ *             return entry ? {entry: entry} : undefined
+ *         }
+ *     }),
+ *     notFound: (context: BaseContext): Error => new ControllerActionNotFoundException('No action handles the topic {topic}', {topic: context.topic})
+ * })
+ *
+ * //The decorator declaring the actions of the channel
+ * export function OnMessage(topic: string) {
+ *     return <ClassPrototype extends Controller>(target: ClassPrototype, propertyKey: ControllerProperty<ClassPrototype>): void => {
+ *         registerControllerAction(QueueChannel, target, propertyKey, {topic: topic}, FlexibleDTO, {})
+ *     }
+ * }
+ * ```
+ */
+export declare function defineChannel<Definition extends ChannelDefinition>(definition: Definition): Definition;
+/**
+ * Get a defined channel.
+ * @param name The channel's name.
+ * @returns The channel's definition.
+ * @throws {InvalidChannelException} When no channel has the name.
+ * @example
+ * ```typescript
+ * import {getChannel, type ChannelDefinition} from '@lakutata/entrypoint/channel'
+ *
+ * const http: ChannelDefinition = getChannel('http')
+ * console.log(http.kind, http.contextType) //request HTTP
+ * ```
+ */
+export declare function getChannel(name: string): ChannelDefinition;
+/**
+ * Whether a channel is defined.
+ * @param name The channel's name.
+ * @returns `true` when a channel has the name.
+ * @example
+ * ```typescript
+ * import {hasChannel} from '@lakutata/entrypoint/channel'
+ *
+ * console.log(hasChannel('schedule')) //true
+ * console.log(hasChannel('queue')) //false until a package defines it
+ * ```
+ */
+export declare function hasChannel(name: string): boolean;
+/**
+ * Find the channel whose requests have a context type.
+ * @param contextType The `type` of a request context (`HTTP`, `CLI`…).
+ * @returns The first channel defined with the context type, `undefined` when there is none.
+ * @example
+ * ```typescript
+ * import {ContextType, type BaseContext} from 'lakutata/com/entrypoint'
+ * import {getChannelByContextType} from '@lakutata/entrypoint/channel'
+ *
+ * declare const context: BaseContext
+ *
+ * console.log(getChannelByContextType(ContextType.SERVICE)?.name) //service
+ * console.log(getChannelByContextType(context.type)?.name)
+ * ```
+ */
+export declare function getChannelByContextType(contextType: string): ChannelDefinition | undefined;

package/dist/types/channel/EntrypointAdapter.d.ts

@@ -0,0 +1,195 @@
+import type { ActionPattern, BaseObject, DTO, IBaseObjectConstructor, JSONSchema, Module, Schema } from '@lakutata/core';
+import type { Controller } from '../lib/Controller.js';
+import type { BaseContext } from '../context/BaseContext.js';
+import type { BaseActionInfo } from '../Entrypoint.js';
+import type { MiddlewareDefinition } from '../lib/Middleware.js';
+import type { ChannelDefinition } from './Channel.js';
+/**
+ * The options of a request dispatched by an adapter ({@link ChannelRuntime.dispatch}).
+ */
+export interface DispatchOptions {
+    /**
+     * Aborts the request (its client went away, its deadline passed): the controller's `signal` aborts, the request's
+     * container is destroyed and the dispatch resolves to `undefined` at once. A request whose signal is already
+     * aborted is not run.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * The parameters the transport took from the request's address (such as route parameters); they are merged into
+     * the action's input and take precedence over the request's data and the matcher's parameters.
+     */
+    readonly params?: Record<string, unknown>;
+}
+/**
+ * The description of an action given to the adapters ({@link ChannelRuntime.actions}): one per address (an HTTP route
+ * declared for two methods has two), with the fields of its channel (`route`, `command`, `pattern`…).
+ */
+export type ChannelActionInfo = BaseActionInfo & Record<string, unknown> & {
+    /**
+     * The action's address in its channel (`{route, method}` for HTTP, `{command}` for CLI, the pattern for service),
+     * with its controller prefix.
+     */
+    readonly address: ActionPattern;
+    /**
+     * The DTO validating the action's input (`FlexibleDTO`, accepting any input, when the action declares none).
+     */
+    readonly dto: typeof DTO;
+    /**
+     * The schema of the action's result, declared with `@Return`; `undefined` without it.
+     */
+    readonly returnSchema: Schema | undefined;
+};
+/**
+ * What the entrypoint gives an adapter when it starts it ({@link EntrypointAdapter.start}): the channel's actions and
+ * the functions dispatching the requests to them.
+ */
+export interface ChannelRuntime<Context extends BaseContext = BaseContext> {
+    /**
+     * The adapter's channel.
+     */
+    readonly channel: ChannelDefinition;
+    /**
+     * The module owning the entrypoint (the application).
+     */
+    readonly module: Module;
+    /**
+     * The channel's actions, one per address.
+     */
+    readonly actions: ReadonlyArray<ChannelActionInfo>;
+    /**
+     * The entrypoint's controller classes, for the channels serving what the controllers declare besides their actions
+     * (their prefixes, their metadata).
+     */
+    readonly controllers: ReadonlyArray<IBaseObjectConstructor<Controller>>;
+    /**
+     * Get an object from the entrypoint's container, such as a component the adapter uses (an autoloaded class is
+     * registered on first use).
+     * @param target The object's registration name or symbol, or its class.
+     * @returns The object, once created and initialized.
+     * @throws {Error} When the object is not registered or fails to be created.
+     */
+    getObject<T extends BaseObject>(target: string | symbol | IBaseObjectConstructor<T>): Promise<T>;
+    /**
+     * Resolves once every adapter of the entrypoint started and the application launched (its objects and its
+     * bootstrap are ready), for the adapters acting on their own rather than on requests (running a command,
+     * triggering the schedules). Without an application (a bare container) it never resolves unless the entrypoint's
+     * `launched()` is called.
+     */
+    readonly ready: Promise<void>;
+    /**
+     * Dispatch a request to the action it matches: the request runs in a container of its own, through the
+     * middlewares, the input validation, the access control and the action. It is tracked as in progress until it
+     * ends, so the entrypoint waits for it when it stops.
+     * @param context The request's context, of the channel's context class.
+     * @param options The request's abort signal and address parameters.
+     * @returns The action's result; `undefined` when the request is aborted by its signal.
+     * @throws {Error} The channel's not-found error when no action matches (`ControllerActionNotFoundException` for
+     * the built-in channels), the input validation error, the access control's denial (`AccessDeniedException`), the
+     * error of a middleware or of the action, or `EntrypointStoppedException` when the entrypoint stopped before the
+     * request completed.
+     */
+    dispatch(context: Context, options?: DispatchOptions): Promise<unknown>;
+    /**
+     * Dispatch a request to a given action without matching it, for the channels binding a trigger to each action
+     * (schedules, subscriptions); the request runs as with {@link ChannelRuntime.dispatch}.
+     * @param action One of the objects of {@link ChannelRuntime.actions} (compared by identity, not a copy).
+     * @param context The request's context, of the channel's context class.
+     * @param options The request's abort signal and address parameters.
+     * @returns The action's result; `undefined` when the request is aborted by its signal.
+     * @throws {Error} The channel's not-found error when the action is not one of the runtime's, and the errors of
+     * {@link ChannelRuntime.dispatch}.
+     */
+    dispatchTo(action: ChannelActionInfo, context: Context, options?: DispatchOptions): Promise<unknown>;
+}
+/**
+ * An adapter: a transport receiving a channel's requests (an HTTP server, a CLI parser, a socket server, the
+ * scheduler). It is given to the entrypoint options under its channel's key; the entrypoint starts it when it
+ * initializes and stops it, then closes it, when it is destroyed. The adapter packages export functions creating them
+ * (`expressHTTPEntrypoint()`, `scheduleEntrypoint()`…).
+ */
+export interface EntrypointAdapter<Context extends BaseContext = BaseContext> {
+    /**
+     * The adapter's channel, which is also its key in the entrypoint options.
+     */
+    readonly channel: string;
+    /**
+     * The channel's definition, defined by the entrypoint before it starts the adapter (for the packages defining their
+     * channel with their adapter).
+     */
+    readonly definition?: ChannelDefinition;
+    /**
+     * The adapter's name, to tell apart the adapters of a channel.
+     */
+    readonly name?: string;
+    /**
+     * The middlewares run around the requests of this adapter, after the entrypoint's and before the controller's and
+     * the action's.
+     */
+    readonly middlewares?: MiddlewareDefinition[];
+    /**
+     * Start receiving requests. The entrypoint starts its adapters one after the other and awaits each; a rejection
+     * fails the entrypoint's initialization.
+     * @param runtime The channel's actions and the functions dispatching the requests.
+     */
+    start(runtime: ChannelRuntime<Context>): void | Promise<void>;
+    /**
+     * Stop receiving requests; the entrypoint then waits for the requests in progress (aborting them after its
+     * `shutdownTimeout`) before it calls {@link EntrypointAdapter.close}.
+     */
+    stop?(): void | Promise<void>;
+    /**
+     * Release the resources (connections, servers) once the requests in progress ended or were aborted.
+     */
+    close?(): void | Promise<void>;
+    /**
+     * Push an event to a client of the adapter (a window's renderer, a socket); its listeners receive the arguments.
+     * Called by {@link Entrypoint.notify}.
+     * @param clientId The client's id, as set in its requests' contexts (`ServiceContext.clientId`).
+     * @param event The event's name.
+     * @param args The arguments given to the client's listeners.
+     * @returns Whether the adapter has the client.
+     */
+    notify?(clientId: string, event: string, args: unknown[]): boolean;
+    /**
+     * Push an event to every client of the adapter. Called by {@link Entrypoint.broadcast}.
+     * @param event The event's name.
+     * @param args The arguments given to the clients' listeners.
+     * @returns The number of clients the event was pushed to.
+     */
+    broadcast?(event: string, args: unknown[]): number;
+}
+/**
+ * Whether a value is an adapter: an object with a string `channel` and a `start` function.
+ * @param value The value to check.
+ * @returns `true` when the value is an adapter.
+ * @example
+ * ```typescript
+ * import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+ * import {isEntrypointAdapter} from '@lakutata/entrypoint/channel'
+ *
+ * console.log(isEntrypointAdapter(expressHTTPEntrypoint())) //true
+ * console.log(isEntrypointAdapter({channel: 'http'})) //false: no start function
+ * ```
+ */
+export declare function isEntrypointAdapter(value: unknown): value is EntrypointAdapter;
+/**
+ * Map the commands of CLI actions to the JSON schemas of their input, as a CLI adapter builds its commands from.
+ * @param actions The CLI channel's actions ({@link ChannelRuntime.actions} of a CLI adapter).
+ * @returns Each command mapped to its input's JSON schema; an action without command is mapped under `undefined`.
+ * @example
+ * ```typescript
+ * import {type CLIContext, type EntrypointAdapter} from 'lakutata/com/entrypoint'
+ * import {commandMap} from '@lakutata/entrypoint/channel'
+ *
+ * //A CLI adapter printing the commands and their options
+ * export const HelpCLIEntrypoint: EntrypointAdapter<CLIContext> = {
+ *     channel: 'cli',
+ *     start: (runtime): void => {
+ *         for (const [command, schema] of commandMap(runtime.actions)) {
+ *             console.log(command, Object.keys(schema.properties ?? {}).join(' '))
+ *         }
+ *     }
+ * }
+ * ```
+ */
+export declare function commandMap(actions: ReadonlyArray<ChannelActionInfo>): Map<string, JSONSchema>;

package/dist/types/context/BaseContext.d.ts

@@ -0,0 +1,75 @@
+import { DTO, type ActionPattern } from '@lakutata/core';
+/**
+ * The kinds of the request contexts of the built-in channels, held by `BaseContext.type`.
+ */
+export declare enum ContextType {
+    /**
+     * A command of a CLI adapter (`CLIContext`).
+     */
+    CLI = "CLI",
+    /**
+     * A request of an HTTP adapter (`HTTPContext`).
+     */
+    HTTP = "HTTP",
+    /**
+     * A message of a service adapter: Socket.IO, JSON-RPC, Electron IPC, HTTP service (`ServiceContext`).
+     */
+    SERVICE = "SERVICE",
+    /**
+     * A run of a scheduled action (`ScheduleContext`).
+     */
+    SCHEDULE = "SCHEDULE"
+}
+export type ContextParams<T extends {} = {}> = T & Record<string, any>;
+/**
+ * The context of a request: what an adapter knows about it, given to the controller (`this.context`), the middlewares
+ * (`invocation.context`) and the access control rules. Each channel has its subclass (`HTTPContext`, `CLIContext`,
+ * `ServiceContext`, `ScheduleContext`); test it with `instanceof` in an action serving several channels. A context is
+ * a DTO: its properties are validated when it is created and when they change; it also holds the extra properties
+ * given by its adapter (the Socket.IO socket, the JSON-RPC request), read by the adapters' helpers
+ * (`socketOfContext`…). The adapters create the contexts: an application only reads them.
+ * @example
+ * ```typescript
+ * import {Controller, CLIContext, HTTPContext, ServiceContext} from 'lakutata/com/entrypoint'
+ * import {CLIAction, GET, ServiceAction} from 'lakutata/decorator/ctrl'
+ *
+ * class VersionController extends Controller {
+ *     //One action for the three channels: the context tells them apart
+ *     @GET('/version')
+ *     @CLIAction('version')
+ *     @ServiceAction({act: 'version'})
+ *     public async version(): Promise<{ version: string, via: string }> {
+ *         let via: string = this.context.type
+ *         if (this.context instanceof HTTPContext) via = `${this.context.method.toUpperCase()} ${this.context.route}`
+ *         if (this.context instanceof CLIContext) via = `the command ${this.context.command}`
+ *         if (this.context instanceof ServiceContext) via = `the client ${this.context.clientId ?? 'unknown'}`
+ *         return {version: '1.0.0', via: via}
+ *     }
+ * }
+ * ```
+ */
+export declare class BaseContext<T extends Record<string, any> = {}> extends DTO {
+    /**
+     * The kind of the context: a `ContextType` for the built-in channels, the context type declared by its channel for
+     * the channels of other packages.
+     */
+    readonly type: ContextType | string;
+    /**
+     * The input of the action before its validation: for HTTP the query string merged with the parsed body (the route
+     * parameters are merged over it when the action runs, not into it), for CLI the arguments and the options of the
+     * command, for a service the message without the keys of the action's pattern, for a scheduled run an empty
+     * object. A middleware may change it before the validation.
+     */
+    data: ActionPattern<T>;
+    /**
+     * The language of the request (a BCP 47 tag such as `'zh-CN'`), set by the i18n middleware (`I18nMiddleware` of
+     * `lakutata/com/i18n`): the validation errors of an invalid input are then written in it. Undefined without it.
+     */
+    locale?: string;
+    /**
+     * Create a context, validating its properties.
+     * @param params The properties of the context: its `type`, its `data`, and those of its channel.
+     * @throws {InvalidValueException} When a property is invalid or a required one is missing.
+     */
+    constructor(params: ContextParams);
+}

package/dist/types/context/CLIContext.d.ts

@@ -0,0 +1,38 @@
+import { BaseContext, type ContextParams, ContextType } from './BaseContext.js';
+import { type CLIContextParams } from '../types/CLIContextParams.js';
+/**
+ * The context of a command run by a CLI adapter (`commanderCLIEntrypoint`): `this.context` of a controller action
+ * declared with `@CLIAction`, when it runs as a command. Its `data` holds the positional arguments and the options of
+ * the command, before their validation.
+ * @example
+ * ```typescript
+ * import {Controller, CLIContext} from 'lakutata/com/entrypoint'
+ * import {CLIAction} from 'lakutata/decorator/ctrl'
+ *
+ * class CacheController extends Controller {
+ *     //"app cache clear" prints "cache clear: done"
+ *     @CLIAction('cache clear')
+ *     public async clear(): Promise<string> {
+ *         const command: string = this.context instanceof CLIContext ? this.context.command : 'unknown'
+ *         return `${command}: done`
+ *     }
+ * }
+ * ```
+ */
+export declare class CLIContext<T extends Record<string, any> = {}> extends BaseContext<T> {
+    /**
+     * Always `ContextType.CLI`.
+     */
+    readonly type: ContextType;
+    /**
+     * The command of the action as declared, its controller prefix included (`'user:get <id>'`), not the arguments
+     * typed by the user.
+     */
+    command: string;
+    /**
+     * Create the context of a command, validating its properties.
+     * @param params The command and its data.
+     * @throws {InvalidValueException} When a property is invalid or a required one is missing.
+     */
+    constructor(params: ContextParams<CLIContextParams>);
+}

package/dist/types/context/HTTPContext.d.ts

@@ -0,0 +1,52 @@
+import { BaseContext, type ContextParams, ContextType } from './BaseContext.js';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { type HTTPContextParams } from '../types/HTTPContextParams.js';
+/**
+ * The context of a request served by an HTTP adapter (`expressHTTPEntrypoint`, `fastifyHTTPEntrypoint`):
+ * `this.context` of a controller action declared with `@HTTPAction` or `@GET`…, when it runs for an HTTP request. It
+ * gives the Node.js request and response, to read or set headers; once an action has sent the response itself (its
+ * headers sent), the adapter writes neither its value nor its error.
+ * @example
+ * ```typescript
+ * import {Controller, HTTPContext} from 'lakutata/com/entrypoint'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ *
+ * class AgentController extends Controller {
+ *     //GET /agent: answered with the header Cache-Control and the JSON {"agent": "curl/8.0", "route": "/agent"}
+ *     @GET('/agent')
+ *     public async agent(): Promise<{ agent: string, route: string }> {
+ *         if (!(this.context instanceof HTTPContext)) return {agent: '', route: ''}
+ *         this.context.response.setHeader('Cache-Control', 'no-store')
+ *         return {agent: this.context.request.headers['user-agent'] ?? '', route: this.context.route}
+ *     }
+ * }
+ * ```
+ */
+export declare class HTTPContext<T extends Record<string, any> = {}> extends BaseContext<T> {
+    /**
+     * Always `ContextType.HTTP`.
+     */
+    readonly type: ContextType;
+    /**
+     * The route of the action as declared, its controller prefix included (`'/users/:id'`), not the requested path.
+     */
+    readonly route: string;
+    /**
+     * The HTTP method of the action, as declared (`'get'` for `@GET`).
+     */
+    readonly method: string;
+    /**
+     * The Node.js request (the raw request of Fastify, the Express request).
+     */
+    readonly request: IncomingMessage;
+    /**
+     * The Node.js response (the raw reply of Fastify, the Express response).
+     */
+    readonly response: ServerResponse;
+    /**
+     * Create the context of an HTTP request, validating its properties.
+     * @param params The route, the method, the request, the response and the data of the request.
+     * @throws {InvalidValueException} When a property is invalid or a required one is missing.
+     */
+    constructor(params: ContextParams<HTTPContextParams>);
+}

package/dist/types/context/ScheduleContext.d.ts

@@ -0,0 +1,47 @@
+import { BaseContext, type ContextParams, ContextType } from './BaseContext.js';
+import { type ScheduleContextParams } from '../types/ScheduleContextParams.js';
+/**
+ * The context of a run of a scheduled action (`scheduleEntrypoint`): `this.context` of a controller action declared
+ * with `@Schedule`, when the schedule runs it. Its `data` is an empty object.
+ * @example
+ * ```typescript
+ * import {Controller, ScheduleContext} from 'lakutata/com/entrypoint'
+ * import {Schedule} from 'lakutata/decorator/ctrl'
+ *
+ * class ReportController extends Controller {
+ *     //Every hour: logs "run 1 of every 1h, planned at …", then "run 2…"
+ *     @Schedule('1h')
+ *     public async hourly(): Promise<void> {
+ *         if (!(this.context instanceof ScheduleContext)) return
+ *         const delay: number = Date.now() - this.context.scheduledAt.getTime()
+ *         console.log(`run ${this.context.run} of ${this.context.schedule}, planned at ${this.context.scheduledAt.toISOString()} (${delay}ms late)`)
+ *     }
+ * }
+ * ```
+ */
+export declare class ScheduleContext<T extends Record<string, any> = {}> extends BaseContext<T> {
+    /**
+     * Always `ContextType.SCHEDULE`.
+     */
+    readonly type: ContextType;
+    /**
+     * The schedule of the action, as a text: `'every '` and the interval as declared (`'every 30s'`, `'every 500ms'` for a
+     * number), or `'cron '` and the expression (`'cron 0 * * * *'`).
+     */
+    readonly schedule: string;
+    /**
+     * The time the run was planned for; the run starts at it or a little later (the time of the launch for the
+     * `immediate` run).
+     */
+    readonly scheduledAt: Date;
+    /**
+     * The number of the run in this process, from 1, counting the runs started (not the skipped ones).
+     */
+    readonly run: number;
+    /**
+     * Create the context of a scheduled run, validating its properties.
+     * @param params The schedule, the planned time, the run number and the data of the run.
+     * @throws {InvalidValueException} When a property is invalid or a required one is missing.
+     */
+    constructor(params: ContextParams<ScheduleContextParams>);
+}

package/dist/types/context/ServiceContext.d.ts

@@ -0,0 +1,47 @@
+import { type ActionPattern } from '@lakutata/core';
+import { BaseContext, type ContextParams, ContextType } from './BaseContext.js';
+import { type ServiceContextParams } from '../types/ServiceContextParams.js';
+/**
+ * The context of a message received by a service adapter (`socketIOServiceEntrypoint`, `jsonRPCServiceEntrypoint`,
+ * `electronIPCServiceEntrypoint`, `httpServiceEntrypoint`): `this.context` of a controller action declared with
+ * `@ServiceAction`, when it runs for a message. Its `input` is the whole message, matched against the actions'
+ * patterns; its `data` is the message without the keys of the matched pattern. The adapters' helpers give the
+ * transport objects (`socketOfContext`, `httpRequestOfContext`, `ipcEventOfContext`, `jsonRPCRequestOfContext`).
+ * @example
+ * ```typescript
+ * import {Controller, ServiceContext} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ *
+ * class ChatController extends Controller {
+ *     //The message {act: 'join', room: 'lobby'}: answered with the payload {room: 'lobby', client: <the client id>}
+ *     @ServiceAction({act: 'join'})
+ *     public async join(input: { room: string }): Promise<{ room: string, client?: string }> {
+ *         const client: string | undefined = this.context instanceof ServiceContext ? this.context.clientId : undefined
+ *         return {room: input.room, client: client}
+ *     }
+ * }
+ * ```
+ */
+export declare class ServiceContext<T extends Record<string, any> = {}> extends BaseContext<T> {
+    /**
+     * Always `ContextType.SERVICE`.
+     */
+    readonly type: ContextType;
+    /**
+     * The message as received, matched against the actions' patterns: a copy of the data given at creation, which
+     * keeps the keys of the pattern (they are removed from `data` once the action is matched), the nested ones
+     * included.
+     */
+    input: ActionPattern<T>;
+    /**
+     * The id of the client of the request (the renderer of an Electron window, a Socket.IO socket, an HTTP service
+     * client): `Entrypoint.notify()` pushes events to it by this id. Undefined for the transports without clients.
+     */
+    readonly clientId?: string;
+    /**
+     * Create the context of a service message, validating its properties; `input` is set to a copy of `data`.
+     * @param params The message (`data`), its client id, and the adapter's extra properties.
+     * @throws {InvalidValueException} When a property is invalid or a required one is missing.
+     */
+    constructor(params: ContextParams<ServiceContextParams>);
+}