@lakutata/entrypoint 3.0.0-beta.0

package/dist/cjs/channel/BuiltinChannels.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScheduleChannel = exports.ServiceChannel = exports.CLIChannel = exports.HTTPChannel = void 0;
+const utils_1 = require("@lakutata/utils");
+const Channel_js_1 = require("./Channel.js");
+const PatternManager_js_1 = require("../lib/pattern/PatternManager.js");
+const StringifyPattern_js_1 = require("../lib/StringifyPattern.js");
+const Prefix_js_1 = require("../lib/Prefix.js");
+const BaseContext_js_1 = require("../context/BaseContext.js");
+const ControllerActionNotFoundException_js_1 = require("../exceptions/ControllerActionNotFoundException.js");
+const UnsetValue_js_1 = require("../lib/UnsetValue.js");
+/**
+ * A lookup by exact key, falling back to the glob patterns
+ * @param entries
+ * @param key
+ * @param subject
+ */
+function exactMatcher(entries, key, subject) {
+    const exact = new Map();
+    const patterns = new PatternManager_js_1.PatternManager();
+    for (const entry of entries) {
+        exact.set(key(entry.details.pattern), entry);
+        patterns.add(entry.details.pattern, entry);
+    }
+    return {
+        match: (context) => {
+            const pattern = subject(context);
+            const entry = exact.get(key(pattern)) ?? patterns.find(pattern);
+            return entry ? { entry: entry } : undefined;
+        }
+    };
+}
+/**
+ * The key of an HTTP action
+ * @param pattern
+ */
+function httpKey(pattern) {
+    return `${pattern.method}\u0000${pattern.route}`;
+}
+/**
+ * The HTTP channel, addressed by route and method
+ */
+exports.HTTPChannel = (0, Channel_js_1.defineChannel)({
+    name: 'http',
+    kind: 'request',
+    contextType: BaseContext_js_1.ContextType.HTTP,
+    identify: (pattern) => pattern.route,
+    describe: (pattern) => ({ route: pattern.route }),
+    prefix: (prefix, pattern) => prefix.route === undefined ? undefined : { ...pattern, route: (0, Prefix_js_1.prefixRoute)(prefix.route, pattern.route) },
+    createMatcher: (entries) => exactMatcher(entries, httpKey, (context) => ({
+        route: context.route,
+        method: context.method
+    })),
+    notFound: (context) => new ControllerActionNotFoundException_js_1.ControllerActionNotFoundException('Route \'{route}\' not found', context)
+});
+/**
+ * The CLI channel, addressed by command
+ */
+exports.CLIChannel = (0, Channel_js_1.defineChannel)({
+    name: 'cli',
+    kind: 'request',
+    contextType: BaseContext_js_1.ContextType.CLI,
+    identify: (pattern) => pattern.command,
+    describe: (pattern) => ({ command: pattern.command }),
+    prefix: (prefix, pattern) => prefix.command === undefined ? undefined : { command: (0, Prefix_js_1.prefixCommand)(prefix.command, pattern.command) },
+    createMatcher: (entries) => exactMatcher(entries, (pattern) => pattern.command, (context) => ({ command: context.command })),
+    notFound: () => new ControllerActionNotFoundException_js_1.ControllerActionNotFoundException('Command not found')
+});
+/**
+ * The service channel, addressed by pattern
+ */
+exports.ServiceChannel = (0, Channel_js_1.defineChannel)({
+    name: 'service',
+    kind: 'request',
+    contextType: BaseContext_js_1.ContextType.SERVICE,
+    identify: (pattern) => (0, StringifyPattern_js_1.stringifyPattern)(pattern),
+    describe: (pattern) => ({ pattern: pattern }),
+    prefix: (prefix, pattern) => prefix.pattern === undefined ? undefined : (0, Prefix_js_1.prefixPattern)(prefix.pattern, pattern),
+    createMatcher: (entries) => {
+        const patterns = new PatternManager_js_1.PatternManager();
+        for (const entry of entries)
+            patterns.add(entry.details.pattern, entry);
+        return {
+            match: (context) => {
+                const entry = patterns.find(context.input);
+                return entry ? { entry: entry } : undefined;
+            }
+        };
+    },
+    //The keys of the pattern are not a part of the action input
+    prepare: (entry, context) => {
+        const patternPaths = (0, utils_1.getObjectPropertyPaths)(entry.details.pattern);
+        patternPaths.forEach((path) => (0, UnsetValue_js_1.unsetValue)(context.data, path));
+        const checkPatternPaths = (0, utils_1.uniqueArray)(patternPaths
+            .map((path) => path.substring(0, path.lastIndexOf('.')))
+            .filter((path) => !!path));
+        checkPatternPaths.forEach((path) => {
+            let target = context.data;
+            path.split('.').forEach((key) => target = target[key] ? target[key] : undefined);
+            if (target && !Object.keys(target).length)
+                (0, UnsetValue_js_1.unsetValue)(context.data, path);
+        });
+    },
+    notFound: () => new ControllerActionNotFoundException_js_1.ControllerActionNotFoundException('Controller action not found')
+});
+/**
+ * The schedule channel: no external caller, each action is run by the timers of the schedule adapter.
+ * The address of an action is its schedule, with the key telling apart the actions of a same schedule
+ */
+exports.ScheduleChannel = (0, Channel_js_1.defineChannel)({
+    name: 'schedule',
+    kind: 'trigger',
+    contextType: BaseContext_js_1.ContextType.SCHEDULE,
+    identify: (pattern) => `${pattern.schedule}#${pattern.key}`,
+    describe: (pattern) => {
+        const { key, ...schedule } = pattern;
+        void key;
+        return schedule;
+    },
+    createMatcher: (entries) => ({
+        //The runs are dispatched to their action: a context is matched by its schedule
+        match: (context) => {
+            const entry = entries.find((candidate) => candidate.details.pattern.schedule === context.schedule);
+            return entry ? { entry: entry } : undefined;
+        }
+    }),
+    notFound: (context) => new ControllerActionNotFoundException_js_1.ControllerActionNotFoundException('No action is scheduled {schedule}', { schedule: context.schedule })
+});

package/dist/cjs/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/cjs/channel/Channel.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineChannel = defineChannel;
+exports.getChannel = getChannel;
+exports.hasChannel = hasChannel;
+exports.getChannelByContextType = getChannelByContextType;
+const InvalidChannelException_js_1 = require("../exceptions/InvalidChannelException.js");
+const channels = new Map();
+/**
+ * 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, {})
+ *     }
+ * }
+ * ```
+ */
+function defineChannel(definition) {
+    const defined = channels.get(definition.name);
+    if (defined && defined !== definition)
+        throw new InvalidChannelException_js_1.InvalidChannelException('The channel "{0}" is already defined', [definition.name]);
+    channels.set(definition.name, definition);
+    return 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
+ * ```
+ */
+function getChannel(name) {
+    const definition = channels.get(name);
+    if (!definition)
+        throw new InvalidChannelException_js_1.InvalidChannelException('The channel "{0}" is not defined', [name]);
+    return definition;
+}
+/**
+ * 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
+ * ```
+ */
+function hasChannel(name) {
+    return channels.has(name);
+}
+/**
+ * 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)
+ * ```
+ */
+function getChannelByContextType(contextType) {
+    for (const definition of channels.values())
+        if (definition.contextType === contextType)
+            return definition;
+    return undefined;
+}

package/dist/cjs/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/cjs/channel/EntrypointAdapter.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEntrypointAdapter = isEntrypointAdapter;
+exports.commandMap = commandMap;
+/**
+ * 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
+ * ```
+ */
+function isEntrypointAdapter(value) {
+    return !!value && typeof value === 'object' && typeof value.channel === 'string' && typeof value.start === 'function';
+}
+/**
+ * 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(' '))
+ *         }
+ *     }
+ * }
+ * ```
+ */
+function commandMap(actions) {
+    return new Map(actions.map((action) => [action.command, action.jsonSchema]));
+}