@lakutata/entrypoint 3.0.0-beta.0

package/dist/cjs/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/cjs/context/BaseContext.js

@@ -0,0 +1,90 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseContext = exports.ContextType = void 0;
+const core_1 = require("@lakutata/core");
+const dto_1 = require("@lakutata/core/decorator/dto");
+/**
+ * The kinds of the request contexts of the built-in channels, held by `BaseContext.type`.
+ */
+var ContextType;
+(function (ContextType) {
+    /**
+     * A command of a CLI adapter (`CLIContext`).
+     */
+    ContextType["CLI"] = "CLI";
+    /**
+     * A request of an HTTP adapter (`HTTPContext`).
+     */
+    ContextType["HTTP"] = "HTTP";
+    /**
+     * A message of a service adapter: Socket.IO, JSON-RPC, Electron IPC, HTTP service (`ServiceContext`).
+     */
+    ContextType["SERVICE"] = "SERVICE";
+    /**
+     * A run of a scheduled action (`ScheduleContext`).
+     */
+    ContextType["SCHEDULE"] = "SCHEDULE";
+})(ContextType || (exports.ContextType = ContextType = {}));
+/**
+ * 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}
+ *     }
+ * }
+ * ```
+ */
+let BaseContext = class BaseContext extends core_1.DTO {
+    /**
+     * 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) {
+        super(params);
+    }
+};
+exports.BaseContext = BaseContext;
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().required()),
+    __metadata("design:type", String)
+], BaseContext.prototype, "type", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Object().pattern(core_1.DTO.String(), core_1.DTO.Any()).required()),
+    __metadata("design:type", Object)
+], BaseContext.prototype, "data", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], BaseContext.prototype, "locale", void 0);
+exports.BaseContext = BaseContext = __decorate([
+    (0, dto_1.IndexSignature)(core_1.DTO.Any()),
+    __metadata("design:paramtypes", [Object])
+], BaseContext);

package/dist/cjs/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/cjs/context/CLIContext.js

@@ -0,0 +1,53 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLIContext = void 0;
+const BaseContext_js_1 = require("./BaseContext.js");
+const dto_1 = require("@lakutata/core/decorator/dto");
+const core_1 = require("@lakutata/core");
+/**
+ * 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`
+ *     }
+ * }
+ * ```
+ */
+class CLIContext extends BaseContext_js_1.BaseContext {
+    /**
+     * 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) {
+        super(params);
+    }
+}
+exports.CLIContext = CLIContext;
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().valid(BaseContext_js_1.ContextType.CLI).default(BaseContext_js_1.ContextType.CLI)),
+    __metadata("design:type", String)
+], CLIContext.prototype, "type", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().required()),
+    __metadata("design:type", String)
+], CLIContext.prototype, "command", void 0);

package/dist/cjs/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/cjs/context/HTTPContext.js

@@ -0,0 +1,78 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTTPContext = void 0;
+const core_1 = require("@lakutata/core");
+const dto_1 = require("@lakutata/core/decorator/dto");
+const BaseContext_js_1 = require("./BaseContext.js");
+const node_http_1 = require("node:http");
+/**
+ * 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}
+ *     }
+ * }
+ * ```
+ */
+class HTTPContext extends BaseContext_js_1.BaseContext {
+    /**
+     * 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) {
+        super(params);
+    }
+}
+exports.HTTPContext = HTTPContext;
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().valid(BaseContext_js_1.ContextType.HTTP).default(BaseContext_js_1.ContextType.HTTP)),
+    __metadata("design:type", String)
+], HTTPContext.prototype, "type", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().required()),
+    __metadata("design:type", String)
+], HTTPContext.prototype, "route", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().required()),
+    __metadata("design:type", String)
+], HTTPContext.prototype, "method", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.InstanceOf(node_http_1.IncomingMessage)),
+    __metadata("design:type", node_http_1.IncomingMessage
+    /**
+     * The Node.js response (the raw reply of Fastify, the Express response).
+     */
+    )
+], HTTPContext.prototype, "request", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.InstanceOf(node_http_1.ServerResponse)),
+    __metadata("design:type", node_http_1.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.
+     */
+    )
+], HTTPContext.prototype, "response", void 0);

package/dist/cjs/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/cjs/context/ScheduleContext.js

@@ -0,0 +1,65 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScheduleContext = void 0;
+const BaseContext_js_1 = require("./BaseContext.js");
+const dto_1 = require("@lakutata/core/decorator/dto");
+const core_1 = require("@lakutata/core");
+/**
+ * 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)`)
+ *     }
+ * }
+ * ```
+ */
+class ScheduleContext extends BaseContext_js_1.BaseContext {
+    /**
+     * 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) {
+        super(params);
+    }
+}
+exports.ScheduleContext = ScheduleContext;
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().valid(BaseContext_js_1.ContextType.SCHEDULE).default(BaseContext_js_1.ContextType.SCHEDULE)),
+    __metadata("design:type", String)
+], ScheduleContext.prototype, "type", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().required()),
+    __metadata("design:type", String)
+], ScheduleContext.prototype, "schedule", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Date().required()),
+    __metadata("design:type", Date
+    /**
+     * The number of the run in this process, from 1, counting the runs started (not the skipped ones).
+     */
+    )
+], ScheduleContext.prototype, "scheduledAt", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Number().integer().min(1).required()),
+    __metadata("design:type", Number)
+], ScheduleContext.prototype, "run", void 0);

package/dist/cjs/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>);
+}

package/dist/cjs/context/ServiceContext.js

@@ -0,0 +1,62 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceContext = void 0;
+const utils_1 = require("@lakutata/utils");
+const core_1 = require("@lakutata/core");
+const dto_1 = require("@lakutata/core/decorator/dto");
+const BaseContext_js_1 = require("./BaseContext.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}
+ *     }
+ * }
+ * ```
+ */
+class ServiceContext extends BaseContext_js_1.BaseContext {
+    /**
+     * 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) {
+        //A deep copy: the pattern keys removed from the data once matched, nested ones included, stay in the input
+        params = { ...params, input: (0, utils_1.cloneDeep)(params.data ?? {}) };
+        super(params);
+    }
+}
+exports.ServiceContext = ServiceContext;
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().valid(BaseContext_js_1.ContextType.SERVICE).default(BaseContext_js_1.ContextType.SERVICE)),
+    __metadata("design:type", String)
+], ServiceContext.prototype, "type", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Object().pattern(core_1.DTO.String(), core_1.DTO.Any()).required()),
+    __metadata("design:type", Object)
+], ServiceContext.prototype, "input", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], ServiceContext.prototype, "clientId", void 0);