@lakutata/entrypoint 3.0.0-beta.0

package/dist/esm/lib/Prefix.js

@@ -0,0 +1,143 @@
+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);
+};
+import { DTO } from '@lakutata/core';
+import { Expect, IndexSignature } from '@lakutata/core/decorator/dto';
+import { InvalidPrefixException } from '../exceptions/InvalidPrefixException.js';
+/**
+ * A controller's action prefixes, given to `@Prefix`. The packages of the other channels add their own prefix keys
+ * (declaration merging); the keys are kept even when not declared here.
+ * @example
+ * ```typescript
+ * import {Controller} from 'lakutata/com/entrypoint'
+ * import {CLIAction, GET, Prefix, ServiceAction} from 'lakutata/decorator/ctrl'
+ *
+ * //GET /users/:id, the command user:get, the pattern {resource: 'user', act: 'get'}
+ * @Prefix({route: '/users', command: 'user', pattern: {resource: 'user'}})
+ * class UserController extends Controller {
+ *     @GET('/:id')
+ *     @CLIAction('get')
+ *     @ServiceAction({act: 'get'})
+ *     public async get(input: {id: string}): Promise<{id: string}> {
+ *         return {id: input.id}
+ *     }
+ * }
+ * ```
+ */
+let PrefixOptions = class PrefixOptions extends DTO {
+};
+__decorate([
+    Expect(DTO.String().optional()),
+    __metadata("design:type", String)
+], PrefixOptions.prototype, "route", void 0);
+__decorate([
+    Expect(DTO.String().optional()),
+    __metadata("design:type", String)
+], PrefixOptions.prototype, "command", void 0);
+__decorate([
+    Expect(DTO.Object().optional()),
+    __metadata("design:type", Object)
+], PrefixOptions.prototype, "pattern", void 0);
+PrefixOptions = __decorate([
+    IndexSignature(DTO.Any())
+], PrefixOptions);
+export { PrefixOptions };
+const CONTROLLER_PREFIX = Symbol('ENTRYPOINT.CONTROLLER.PREFIX');
+/**
+ * Set a controller class's prefixes, merged over the ones already set on the class (by the decorators of the other
+ * channels). Used by `@Prefix` and by the prefix decorators of the packages providing a channel.
+ * @param controller The controller class.
+ * @param options The prefixes to set.
+ * @throws {Error} When the merged prefixes are invalid (the validation error of {@link PrefixOptions}).
+ * @example
+ * ```typescript
+ * import {Controller} from 'lakutata/com/entrypoint'
+ * import {setPrefix} from '@lakutata/entrypoint/channel'
+ *
+ * //A decorator of a "queue" channel prefixing the topics of a controller
+ * export function TopicPrefix(topic: string) {
+ *     return (target: typeof Controller): void => setPrefix(target, {topic: topic})
+ * }
+ * ```
+ */
+export function setPrefix(controller, options) {
+    const own = Reflect.getOwnMetadata(CONTROLLER_PREFIX, controller);
+    Reflect.defineMetadata(CONTROLLER_PREFIX, PrefixOptions.validate({ ...own, ...options }), controller);
+}
+/**
+ * Get a controller's prefixes: the ones of the class, or else of its nearest parent class declaring them (they are not
+ * merged across the hierarchy).
+ * @param controller The controller class.
+ * @returns The prefixes, `undefined` when neither the class nor its parents declare any.
+ * @example
+ * ```typescript
+ * import {Controller} from 'lakutata/com/entrypoint'
+ * import {Prefix} from 'lakutata/decorator/ctrl'
+ * import {getPrefix} from '@lakutata/entrypoint/channel'
+ *
+ * @Prefix({route: '/users'})
+ * class UserController extends Controller {
+ * }
+ *
+ * class AdminController extends UserController {
+ * }
+ *
+ * console.log(getPrefix(AdminController)?.route) //'/users'
+ * ```
+ */
+export function getPrefix(controller) {
+    for (let current = controller; current && current !== Function.prototype; current = Object.getPrototypeOf(current)) {
+        const prefix = Reflect.getOwnMetadata(CONTROLLER_PREFIX, current);
+        if (prefix)
+            return prefix;
+    }
+    return undefined;
+}
+/**
+ * Join a route prefix and a route
+ * @param prefix
+ * @param route
+ */
+export function prefixRoute(prefix, route) {
+    const segments = [prefix, route].map((part) => part.replace(/^\/+|\/+$/g, '')).filter(Boolean);
+    return `/${segments.join('/')}`;
+}
+/**
+ * Join a command prefix and a command
+ * @param prefix
+ * @param command
+ */
+export function prefixCommand(prefix, command) {
+    return command ? `${prefix}:${command}` : prefix;
+}
+/**
+ * Merge a pattern prefix into a pattern, a key cannot have different values
+ * @param prefix
+ * @param pattern
+ * @param path
+ */
+export function prefixPattern(prefix, pattern, path = '') {
+    const merged = { ...pattern };
+    for (const [key, value] of Object.entries(prefix)) {
+        if (!(key in merged)) {
+            merged[key] = value;
+        }
+        else if (value !== null && typeof value === 'object' && merged[key] !== null && typeof merged[key] === 'object') {
+            merged[key] = prefixPattern(value, merged[key], `${path}${key}.`);
+        }
+        else if (merged[key] !== value) {
+            throw new InvalidPrefixException('The pattern prefix sets "{key}" to {prefix}, the pattern sets it to {pattern}', {
+                key: `${path}${key}`,
+                prefix: JSON.stringify(value),
+                pattern: JSON.stringify(merged[key])
+            });
+        }
+    }
+    return merged;
+}

package/dist/esm/lib/Result.js

@@ -0,0 +1,147 @@
+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 class StatusResult extends 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;
+    }
+}
+/**
+ * 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 class FileResult extends 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;
+    }
+}
+/**
+ * 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 class EventsResult extends 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;
+    }
+}
+/**
+ * Build the results an action returns to describe its output beyond its data.
+ */
+export 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, 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/esm/lib/ServiceResponseCodec.js

@@ -0,0 +1,113 @@
+import { ServiceInvokeException } from '../exceptions/ServiceInvokeException.js';
+import { ActionResult } from './ActionResult.js';
+import { StatusResult } from './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)
+ * }
+ * ```
+ */
+export 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 StatusResult)
+            return result.data;
+        if (result instanceof 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(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;
+    }
+}

package/dist/esm/lib/StringifyPattern.js

@@ -0,0 +1,55 @@
+import { sortArray } from '@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 = [];
+                sortArray(pattern, { order: 'asc' }).forEach((item) => {
+                    const newItem = patternToArrayPair(item);
+                    if (newItem === undefined)
+                        return;
+                    arrayData.push(newItem);
+                });
+                return arrayData;
+            }
+            else {
+                const keys = 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
+ */
+export function stringifyPattern(pattern) {
+    let pairArr = patternToArrayPair(pattern);
+    while (pairArr.find((value) => Array.isArray(value)))
+        pairArr = pairArr.flat();
+    return pairArr.join(':');
+}

package/dist/esm/lib/UnsetValue.js

@@ -0,0 +1,213 @@
+/**
+ * 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
+ */
+function isObjectValue(val) {
+    return val != null && typeof val === 'object' && !Array.isArray(val);
+}
+/**
+ * The type of a value (kind-of)
+ * @param val
+ */
+function kindOf(val) {
+    if (val === undefined)
+        return 'undefined';
+    if (val === null)
+        return 'null';
+    const type = typeof val;
+    if (type === 'boolean' || type === 'string' || type === 'number' || type === 'symbol')
+        return type;
+    if (type === 'function')
+        return ctorName(val) === 'GeneratorFunction' ? 'generatorfunction' : 'function';
+    if (Array.isArray(val))
+        return 'array';
+    if (val.constructor && typeof val.constructor.isBuffer === 'function' && val.constructor.isBuffer(val))
+        return 'buffer';
+    if (isArguments(val))
+        return 'arguments';
+    if (val instanceof Date || (typeof val.toDateString === 'function' && typeof val.getDate === 'function' && typeof val.setDate === 'function'))
+        return 'date';
+    if (val instanceof Error || (typeof val.message === 'string' && val.constructor && typeof val.constructor.stackTraceLimit === 'number'))
+        return 'error';
+    if (val instanceof RegExp || (typeof val.flags === 'string' && typeof val.ignoreCase === 'boolean' && typeof val.multiline === 'boolean' && typeof val.global === 'boolean'))
+        return 'regexp';
+    switch (ctorName(val)) {
+        case 'Symbol':
+            return 'symbol';
+        case 'Promise':
+            return 'promise';
+        case 'WeakMap':
+            return 'weakmap';
+        case 'WeakSet':
+            return 'weakset';
+        case 'Map':
+            return 'map';
+        case 'Set':
+            return 'set';
+        case 'Int8Array':
+        case 'Uint8Array':
+        case 'Uint8ClampedArray':
+        case 'Int16Array':
+        case 'Uint16Array':
+        case 'Int32Array':
+        case 'Uint32Array':
+        case 'Float32Array':
+        case 'Float64Array':
+            return ctorName(val).toLowerCase();
+    }
+    if (typeof val.throw === 'function' && typeof val.return === 'function' && typeof val.next === 'function')
+        return 'generator';
+    const tag = Object.prototype.toString.call(val);
+    switch (tag) {
+        case '[object Object]':
+            return 'object';
+        case '[object Map Iterator]':
+            return 'mapiterator';
+        case '[object Set Iterator]':
+            return 'setiterator';
+        case '[object String Iterator]':
+            return 'stringiterator';
+        case '[object Array Iterator]':
+            return 'arrayiterator';
+    }
+    return tag.slice(8, -1).toLowerCase().replace(/\s/g, '');
+}
+function ctorName(val) {
+    return typeof val.constructor === 'function' ? val.constructor.name : null;
+}
+function isArguments(val) {
+    try {
+        if (typeof val.length === 'number' && typeof val.callee === 'function')
+            return true;
+    }
+    catch (error) {
+        if (error.message.indexOf('callee') !== -1)
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether a value has a value (has-values): not undefined, an empty string, array, object, map or set, an empty
+ * regular expression, buffer or error message
+ * @param val
+ */
+function hasValues(val) {
+    switch (kindOf(val)) {
+        case 'boolean':
+        case 'date':
+        case 'function':
+        case 'null':
+        case 'number':
+            return true;
+        case 'undefined':
+            return false;
+        case 'regexp':
+            return val.source !== '(?:)' && val.source !== '';
+        case 'buffer':
+            return val.toString() !== '';
+        case 'error':
+            return val.message !== '';
+        case 'string':
+        case 'arguments':
+            return val.length !== 0;
+        case 'file':
+        case 'map':
+        case 'set':
+            return val.size !== 0;
+        case 'array':
+        case 'object':
+            for (const key of Object.keys(val))
+                if (hasValues(val[key]))
+                    return true;
+            return false;
+        default:
+            return true;
+    }
+}
+function isValidObject(val) {
+    return isObjectValue(val) || Array.isArray(val) || typeof val === 'function';
+}
+/**
+ * The value of a path (get-value): a key holding the whole path first, the keys escaping their dots ("a\.b"), the keys
+ * containing dots
+ * @param target
+ * @param path
+ */
+function getValue(target, path) {
+    if (!isValidObject(target))
+        return target;
+    const isArray = Array.isArray(path);
+    if (typeof path !== 'string' && !isArray)
+        return target;
+    if (typeof path === 'string' && path in target)
+        return target[path];
+    const segs = isArray ? path : path.split('.');
+    const len = segs.length;
+    let idx = 0;
+    do {
+        let prop = segs[idx];
+        if (typeof prop === 'number')
+            prop = String(prop);
+        while (prop && prop.slice(-1) === '\\')
+            prop = prop.slice(0, -1) + '.' + (segs[++idx] || '');
+        if (prop in target) {
+            target = target[prop];
+        }
+        else {
+            let hasProp = false;
+            let n = idx + 1;
+            while (n < len) {
+                prop = prop + '.' + segs[n++];
+                if ((hasProp = prop in target)) {
+                    target = target[prop];
+                    idx = n - 1;
+                    break;
+                }
+            }
+            if (!hasProp)
+                return undefined;
+        }
+    } while (++idx < len && isValidObject(target));
+    return idx === len ? target : undefined;
+}
+/**
+ * Whether a path has a value (has-value)
+ * @param obj
+ * @param path
+ */
+function hasValue(obj, path) {
+    const isObject = obj != null && (typeof obj === 'object' || typeof obj === 'function');
+    if (isObject && (typeof path === 'string' || Array.isArray(path)))
+        return hasValues(getValue(obj, path));
+    return false;
+}
+/**
+ * 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 function unsetValue(obj, prop) {
+    if (!isObjectValue(obj))
+        throw new TypeError('expected an object.');
+    const isArray = Array.isArray(prop);
+    if (!isArray && Object.prototype.hasOwnProperty.call(obj, prop)) {
+        delete obj[prop];
+        return true;
+    }
+    if (hasValue(obj, prop)) {
+        const segs = isArray ? prop.slice() : prop.split('.');
+        let last = segs.pop();
+        while (segs.length && segs[segs.length - 1].slice(-1) === '\\')
+            last = segs.pop().slice(0, -1) + '.' + last;
+        while (segs.length) {
+            const key = segs.shift();
+            if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+                throw new Error(`Cannot set unsafe key: "${key}"`);
+            obj = obj[key];
+        }
+        return delete obj[last];
+    }
+    return true;
+}