@lakutata/entrypoint 3.0.0-beta.0

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

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

package/dist/cjs/lib/Result.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Result = exports.EventsResult = exports.FileResult = exports.StatusResult = void 0;
+const ActionResult_js_1 = require("./ActionResult.js");
+/**
+ * A result with a status and headers: the HTTP adapters set them on the response and send the data with their
+ * responder; the CLI adapter outputs the data. Build it with `Result.status()`.
+ * @example
+ * ```typescript
+ * import {Controller, Result, type StatusResult} from 'lakutata/com/entrypoint'
+ * import {POST} from 'lakutata/decorator/ctrl'
+ *
+ * class OrderController extends Controller {
+ *     //201 Created, with the location of the order
+ *     @POST('/orders')
+ *     public async create(): Promise<StatusResult> {
+ *         return Result.status(201, {id: 42}, {Location: '/orders/42'})
+ *     }
+ * }
+ * ```
+ */
+class StatusResult extends ActionResult_js_1.ActionResult {
+    /**
+     * Create a result with a status and headers.
+     * @param status The HTTP status.
+     * @param payload The data sent.
+     * @param headers The response headers.
+     */
+    constructor(status, payload, headers = {}) {
+        super();
+        this.status = status;
+        this.payload = payload;
+        this.headers = headers;
+    }
+    /**
+     * The data sent with the status.
+     */
+    get data() {
+        return this.payload;
+    }
+}
+exports.StatusResult = StatusResult;
+/**
+ * A file: a path, a buffer or a stream. The HTTP adapters send it with its options; the CLI adapter writes its
+ * content to stdout. Build it with `Result.file()`.
+ * @example
+ * ```typescript
+ * import {Readable} from 'node:stream'
+ * import {Controller, Result, type FileResult} from 'lakutata/com/entrypoint'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ *
+ * class ReportController extends Controller {
+ *     //A file on disk, downloaded as report.pdf
+ *     @GET('/report')
+ *     public async report(): Promise<FileResult> {
+ *         return Result.file('./reports/latest.pdf', {filename: 'report.pdf', etag: 'v1'})
+ *     }
+ *
+ *     //A stream, with its content type
+ *     @GET('/export')
+ *     public async export(): Promise<FileResult> {
+ *         return Result.file(Readable.from(['id,name\n', '1,Ada\n']), {contentType: 'text/csv'})
+ *     }
+ * }
+ * ```
+ */
+class FileResult extends ActionResult_js_1.ActionResult {
+    /**
+     * Create a file result.
+     * @param source The file's path (resolved from the working directory), its content, or a stream of its content.
+     * @param options How the file is sent.
+     */
+    constructor(source, options = {}) {
+        super();
+        this.source = source;
+        this.options = options;
+    }
+    /**
+     * The file's source.
+     */
+    get data() {
+        return this.source;
+    }
+}
+exports.FileResult = FileResult;
+/**
+ * A stream of events: Server-Sent Events for the HTTP adapters, each event's data written as a line by the CLI
+ * adapter. Build it with `Result.events()`.
+ *
+ * The producer runs after the action returned, once the request's container is destroyed: it must only use objects
+ * living longer than the request (the components), not the controller's request-scoped dependencies.
+ * @example
+ * ```typescript
+ * import {Controller, Result, type EventsResult} from 'lakutata/com/entrypoint'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ *
+ * class ClockController extends Controller {
+ *     //The time every second until the client leaves
+ *     @GET('/clock')
+ *     public async clock(): Promise<EventsResult> {
+ *         return Result.events(async (send, signal): Promise<void> => {
+ *             while (!signal.aborted) {
+ *                 send({now: new Date().toISOString()}, 'tick')
+ *                 await new Promise((resolve): unknown => setTimeout(resolve, 1000))
+ *             }
+ *         })
+ *     }
+ * }
+ * ```
+ */
+class EventsResult extends ActionResult_js_1.ActionResult {
+    /**
+     * Create an event stream result.
+     * @param producer Produces the events.
+     */
+    constructor(producer) {
+        super();
+        this.producer = producer;
+    }
+    /**
+     * Always `undefined`: an event stream has no data of its own.
+     */
+    get data() {
+        return undefined;
+    }
+}
+exports.EventsResult = EventsResult;
+/**
+ * Build the results an action returns to describe its output beyond its data.
+ */
+exports.Result = {
+    /**
+     * Build a result with a status and headers.
+     * @param status The HTTP status.
+     * @param data The data sent.
+     * @param headers The response headers.
+     * @returns The {@link StatusResult}.
+     */
+    status: (status, data, headers) => new StatusResult(status, data, headers),
+    /**
+     * Build a file result.
+     * @param source The file's path (resolved from the working directory), its content, or a stream of its content.
+     * @param options How the file is sent.
+     * @returns The {@link FileResult}.
+     */
+    file: (source, options) => new FileResult(source, options),
+    /**
+     * Build an event stream result (Server-Sent Events for HTTP).
+     * @param producer Produces the events, after the action returned.
+     * @returns The {@link EventsResult}.
+     */
+    events: (producer) => new EventsResult(producer)
+};

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

@@ -0,0 +1,82 @@
+import { Exception } from '@lakutata/core';
+/**
+ * The response of a service invocation, as the service transports (Socket.IO, Electron IPC, NATS…) send it.
+ */
+export interface ServiceResponse {
+    /**
+     * Whether the invocation succeeded.
+     */
+    readonly success: boolean;
+    /**
+     * The failure: a serializable copy of the error's own properties (see {@link ServiceResponseCodec.errorObject});
+     * `null` on success.
+     */
+    readonly error: Error | Exception | null;
+    /**
+     * The action's result; `null` on failure.
+     */
+    readonly payload: any | null;
+}
+/**
+ * Encode the results and failures of service invocations as {@link ServiceResponse}s, and decode them on the
+ * caller's side. Used by the service adapters and the service clients; all its methods are static.
+ * @example
+ * ```typescript
+ * import {ServiceResponseCodec, type ServiceResponse} from '@lakutata/entrypoint/channel'
+ *
+ * //On the service side
+ * const ok: ServiceResponse = ServiceResponseCodec.encode({id: 1}, false)
+ * const failed: ServiceResponse = ServiceResponseCodec.encodeError(new Error('Not found'))
+ *
+ * //On the caller side
+ * console.log(ServiceResponseCodec.decode(ok)) //{id: 1}
+ * try {
+ *     ServiceResponseCodec.decode(failed, 'order.service')
+ * } catch (error) {
+ *     console.log((error as Error).message) //Not found (a ServiceInvokeException whose service is order.service)
+ * }
+ * ```
+ */
+export declare class ServiceResponseCodec {
+    /**
+     * Copy an error into a serializable object: its own properties (message, stack, errno, errMsg, statusCode…). The
+     * values are copied as they are, not deeply.
+     * @param error The error; a value which is not an object gives `{message: String(error)}`.
+     * @returns The copy.
+     */
+    static errorObject(error: unknown): Record<string, unknown>;
+    /**
+     * Encode the failure of a service invocation.
+     * @param error The error, copied with {@link ServiceResponseCodec.errorObject}.
+     * @returns A failed response.
+     */
+    static encodeError(error: unknown): ServiceResponse;
+    /**
+     * The payload of an action's result for the service transports: the data of a `StatusResult` (its status and
+     * headers are HTTP's), the result itself otherwise.
+     * @param result The value the action returned.
+     * @returns The payload to send.
+     * @throws {TypeError} When it is a `FileResult` or an `EventsResult`, which only the HTTP adapters can send.
+     */
+    static payload(result: unknown): unknown;
+    /**
+     * Encode a service response.
+     * @param data The result (a `StatusResult` sent as its data, see {@link ServiceResponseCodec.payload}), or the
+     * error when `isError` is `true` (stored as it is: use {@link ServiceResponseCodec.encodeError} to make an error
+     * serializable).
+     * @param isError Whether `data` is an error.
+     * @returns The response.
+     * @throws {TypeError} When the result is a `FileResult` or an `EventsResult`.
+     */
+    static encode(data: any, isError: boolean): ServiceResponse;
+    /**
+     * Decode a service response: return its payload, or throw its error.
+     * @param response The response.
+     * @param serviceId The invoked service's id, set to the exception's `service`.
+     * @returns The payload of a successful response.
+     * @throws {ServiceInvokeException} When the response is a failure: its message is the remote error's message
+     * (`Unknown Error` without one), the remote error's enumerable properties (errno, statusCode…) are copied onto it,
+     * the read-only ones skipped.
+     */
+    static decode(response: ServiceResponse, serviceId?: string): any;
+}

package/dist/cjs/lib/ServiceResponseCodec.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceResponseCodec = void 0;
+const ServiceInvokeException_js_1 = require("../exceptions/ServiceInvokeException.js");
+const ActionResult_js_1 = require("./ActionResult.js");
+const Result_js_1 = require("./Result.js");
+/**
+ * Encode the results and failures of service invocations as {@link ServiceResponse}s, and decode them on the
+ * caller's side. Used by the service adapters and the service clients; all its methods are static.
+ * @example
+ * ```typescript
+ * import {ServiceResponseCodec, type ServiceResponse} from '@lakutata/entrypoint/channel'
+ *
+ * //On the service side
+ * const ok: ServiceResponse = ServiceResponseCodec.encode({id: 1}, false)
+ * const failed: ServiceResponse = ServiceResponseCodec.encodeError(new Error('Not found'))
+ *
+ * //On the caller side
+ * console.log(ServiceResponseCodec.decode(ok)) //{id: 1}
+ * try {
+ *     ServiceResponseCodec.decode(failed, 'order.service')
+ * } catch (error) {
+ *     console.log((error as Error).message) //Not found (a ServiceInvokeException whose service is order.service)
+ * }
+ * ```
+ */
+class ServiceResponseCodec {
+    /**
+     * Copy an error into a serializable object: its own properties (message, stack, errno, errMsg, statusCode…). The
+     * values are copied as they are, not deeply.
+     * @param error The error; a value which is not an object gives `{message: String(error)}`.
+     * @returns The copy.
+     */
+    static errorObject(error) {
+        if (!error || typeof error !== 'object')
+            return { message: String(error) };
+        const errorObject = {};
+        Object.getOwnPropertyNames(error).forEach((property) => errorObject[property] = error[property]);
+        return errorObject;
+    }
+    /**
+     * Encode the failure of a service invocation.
+     * @param error The error, copied with {@link ServiceResponseCodec.errorObject}.
+     * @returns A failed response.
+     */
+    static encodeError(error) {
+        return this.encode(this.errorObject(error), true);
+    }
+    /**
+     * The payload of an action's result for the service transports: the data of a `StatusResult` (its status and
+     * headers are HTTP's), the result itself otherwise.
+     * @param result The value the action returned.
+     * @returns The payload to send.
+     * @throws {TypeError} When it is a `FileResult` or an `EventsResult`, which only the HTTP adapters can send.
+     */
+    static payload(result) {
+        if (result instanceof Result_js_1.StatusResult)
+            return result.data;
+        if (result instanceof ActionResult_js_1.ActionResult)
+            throw new TypeError(`The service transports cannot send a ${result.constructor.name}: only the HTTP adapters send files and event streams`);
+        return result;
+    }
+    /**
+     * Encode a service response.
+     * @param data The result (a `StatusResult` sent as its data, see {@link ServiceResponseCodec.payload}), or the
+     * error when `isError` is `true` (stored as it is: use {@link ServiceResponseCodec.encodeError} to make an error
+     * serializable).
+     * @param isError Whether `data` is an error.
+     * @returns The response.
+     * @throws {TypeError} When the result is a `FileResult` or an `EventsResult`.
+     */
+    static encode(data, isError) {
+        if (!isError)
+            data = this.payload(data);
+        return isError ? {
+            success: false,
+            error: data,
+            payload: null
+        } : {
+            success: true,
+            error: null,
+            payload: data
+        };
+    }
+    /**
+     * Decode a service response: return its payload, or throw its error.
+     * @param response The response.
+     * @param serviceId The invoked service's id, set to the exception's `service`.
+     * @returns The payload of a successful response.
+     * @throws {ServiceInvokeException} When the response is a failure: its message is the remote error's message
+     * (`Unknown Error` without one), the remote error's enumerable properties (errno, statusCode…) are copied onto it,
+     * the read-only ones skipped.
+     */
+    static decode(response, serviceId) {
+        if (!response.success) {
+            const remoteError = response.error;
+            const serviceInvokeException = new ServiceInvokeException_js_1.ServiceInvokeException(remoteError?.message || 'Unknown Error');
+            //The properties of the remote error are copied one by one, the read-only ones (such as the name of a NatsError) are skipped
+            if (remoteError && typeof remoteError === 'object') {
+                for (const key of Object.keys(remoteError)) {
+                    try {
+                        serviceInvokeException[key] = remoteError[key];
+                    }
+                    catch {
+                        //A read-only property
+                    }
+                }
+            }
+            //The service invoked, whatever the remote error holds
+            if (serviceId)
+                serviceInvokeException.service = serviceId;
+            throw serviceInvokeException;
+        }
+        return response.payload;
+    }
+}
+exports.ServiceResponseCodec = ServiceResponseCodec;

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

@@ -0,0 +1,7 @@
+import { ActionPattern } from '@lakutata/core';
+/**
+ * Stringify pattern object
+ * @param pattern
+ * @constructor
+ */
+export declare function stringifyPattern(pattern: ActionPattern): string;

package/dist/cjs/lib/StringifyPattern.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stringifyPattern = stringifyPattern;
+const utils_1 = require("@lakutata/utils");
+function patternToArrayPair(pattern) {
+    switch (typeof pattern) {
+        case 'string':
+            return pattern;
+        case 'boolean':
+            return pattern ? 'true' : 'false';
+        case 'number':
+            return pattern.toString();
+        case 'bigint':
+            return undefined;
+        case 'symbol':
+            return undefined;
+        case 'function':
+            return undefined;
+        case 'undefined':
+            return undefined;
+        case 'object': {
+            if (Array.isArray(pattern)) {
+                const arrayData = [];
+                (0, utils_1.sortArray)(pattern, { order: 'asc' }).forEach((item) => {
+                    const newItem = patternToArrayPair(item);
+                    if (newItem === undefined)
+                        return;
+                    arrayData.push(newItem);
+                });
+                return arrayData;
+            }
+            else {
+                const keys = (0, utils_1.sortArray)(Object.keys(pattern), { order: 'asc' });
+                const data = [];
+                keys.forEach((key) => {
+                    const item = patternToArrayPair(pattern[key]);
+                    if (item === undefined)
+                        return;
+                    data.push([key, item]);
+                });
+                return data;
+            }
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * Stringify pattern object
+ * @param pattern
+ * @constructor
+ */
+function stringifyPattern(pattern) {
+    let pairArr = patternToArrayPair(pattern);
+    while (pairArr.find((value) => Array.isArray(value)))
+        pairArr = pairArr.flat();
+    return pairArr.join(':');
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Derived from index.js of unset-value 2.0.1, has-value 2.0.2, get-value 3.0.1, has-values 2.0.1, kind-of 6.0.3 and
+ * isobject 4.1.1 (MIT, see THIRD_PARTY_NOTICES.md): the removal of the properties of the patterns from the inputs of
+ * the actions, as 2.x
+ */
+/**
+ * Remove a property of an object by its path (unset-value): a key holding the whole path first, the keys escaping
+ * their dots ("a\.b"); a property without value (has-value) is kept
+ * @param obj
+ * @param prop
+ */
+export declare function unsetValue(obj: any, prop: string | string[]): boolean;