@lakutata/entrypoint 3.0.0-beta.0

package/dist/types/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/types/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/types/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;

package/dist/types/lib/pattern/GlobPattern.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A glob of the value of a pattern: "*" matches any characters, "?" one character, "**" is a literal "*" and "*?" a
+ * literal "?". It matches a whole value, converted to a string
+ */
+export declare class GlobPattern {
+    #private;
+    readonly glob: unknown;
+    /**
+     * Whether a value of a pattern is a glob
+     * @param value
+     */
+    static isGlob(value: string): boolean;
+    /**
+     * @param glob the glob, nothing is matched without it
+     */
+    constructor(glob: unknown);
+    /**
+     * The regular expression of a glob
+     * @param glob
+     */
+    protected static expression(glob: string): RegExp;
+    /**
+     * Whether the glob matches a value converted to a string
+     * @param value
+     */
+    test(value: unknown): boolean;
+    /**
+     * Whether the glob matches the value of a subject: a missing value is not matched, a primitive value (a date, a
+     * regular expression) is matched as a string. An array or an object is always matched, as gex does (it gives back
+     * the collection of its matching elements, which is never null): the routing of the actions is the one of 2.x
+     * @param value
+     */
+    matches(value: unknown): boolean;
+}

package/dist/types/lib/pattern/PatternManager.d.ts

@@ -0,0 +1,103 @@
+import { GlobPattern } from './GlobPattern.js';
+/**
+ * A pattern: its values are compared as strings
+ */
+export type Pattern = Record<string, any>;
+/**
+ * A glob of a key of a node, and the node of the patterns it matches
+ */
+type GlobBranch = {
+    glob: GlobPattern;
+    node: PatternNode;
+};
+/**
+ * A node of the decision tree: the patterns having its key are found by its value (or by a glob of it), the patterns
+ * without it are in its "star" node. The keys are ordered along the tree, as the keys of the patterns
+ */
+type PatternNode = {
+    /**
+     * The key the node decides on
+     */
+    key?: string;
+    /**
+     * The nodes of the values of the key
+     */
+    values?: Record<string, PatternNode>;
+    /**
+     * The nodes of the globs of the key
+     */
+    globs?: Record<string, GlobBranch[]>;
+    /**
+     * The node of the patterns without the key
+     */
+    star?: PatternNode;
+    /**
+     * The object of the pattern ending at the node
+     */
+    data?: unknown;
+    hasData?: boolean;
+};
+export type PatternManagerOptions = {
+    /**
+     * The values of the patterns having "*" or "?" are globs, true by default
+     */
+    globMatch?: boolean;
+};
+/**
+ * The patterns of the actions and the objects they give: a subject is matched by the most specific pattern whose
+ * properties it has (the unknown properties of the subject are ignored)
+ */
+export declare class PatternManager {
+    #private;
+    constructor(options?: PatternManagerOptions);
+    /**
+     * The glob of a value of a pattern, undefined when it is not one
+     * @param value
+     */
+    protected glob(value: string): GlobPattern | undefined;
+    /**
+     * The node of a glob of a key of a node, added once
+     * @param node
+     * @param key
+     * @param glob
+     */
+    protected globNode(node: PatternNode, key: string, glob: GlobPattern): PatternNode;
+    /**
+     * Register a pattern, and the object that will be returned if an input matches.
+     * Both keys and values are considered to be strings.
+     * Other types are converted to strings.
+     * @param pattern
+     * @param obj
+     */
+    add(pattern: Pattern, obj: any): this;
+    /**
+     * Remove this pattern, and it's object, from the matcher.
+     * @param pattern
+     */
+    remove(pattern: Pattern): this;
+    /**
+     * Return the unique match for this subject, or null if not found.
+     * The properties of the subject are matched against the patterns previously added, and the most specifc pattern wins.
+     * Unknown properties in the subject are ignored.
+     * If exact is true, then all properties of the subject must match.
+     * @param subject
+     * @param exact
+     */
+    find(subject: Pattern, exact?: boolean): any;
+    /**
+     * Return the list of registered patterns that contain this partial pattern.
+     * You can use wildcards for property values.
+     * Omitted values are not equivalent to a wildcard of "*", you must specify each property explicitly.
+     * @param partialPattern
+     * @param exact the omitted properties match nothing
+     */
+    list(partialPattern?: Pattern, exact?: boolean): {
+        match: Record<string, any>;
+        data: any;
+    }[];
+    /**
+     * Generate a string representation of the decision tree for debugging.
+     */
+    toJSON(): string;
+}
+export {};

package/dist/types/lib/schedule/Cron.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A cron expression, as `@Schedule` uses it: `second minute hour day-of-month month day-of-week`, the second optional
+ * (0 when omitted). Each field accepts `*` (or `?`), values, ranges (`1-5`), steps (`*\/15`, `10/5`, `1-30/2`) and lists
+ * (`1,15`); the months and the days of the week also accept their English three-letter names (`jan`, `mon`), and the
+ * day of the week 7 is Sunday like 0. The macros `@yearly`, `@annually`, `@monthly`, `@weekly`, `@daily`, `@midnight`
+ * and `@hourly` are accepted. When both the day of the month and the day of the week are restricted, a day matching
+ * either of them matches.
+ * @example
+ * ```typescript
+ * import {Cron} from 'lakutata/com/entrypoint'
+ *
+ * //At 09:30 on the weekdays, in Shanghai
+ * const cron: Cron = new Cron('30 9 * * mon-fri', 'Asia/Shanghai')
+ * const next: Date | undefined = cron.next(new Date('2026-01-02T12:00:00Z'))
+ * console.log(next?.toISOString()) //2026-01-05T01:30:00.000Z
+ * console.log(new Cron('0 0 30 2 *').next()) //undefined: February has no 30th
+ * ```
+ */
+export declare class Cron {
+    #private;
+    readonly expression: string;
+    readonly timezone?: string | undefined;
+    /**
+     * Parse a cron expression.
+     * @param expression The expression, 5 or 6 fields separated by spaces, or a macro (case-insensitive).
+     * @param timezone The IANA time zone the expression's times are in (`Asia/Shanghai`); the local time zone when
+     * omitted.
+     * @throws {SyntaxError} When the expression does not have 5 or 6 fields, or a field has a value out of its range,
+     * a reversed range or an invalid step.
+     * @throws {RangeError} When the time zone is unknown.
+     */
+    constructor(expression: string, timezone?: string | undefined);
+    /**
+     * Find the next time matching the expression, strictly after a time, to the second. When the clocks go back, the
+     * times of the repeated hour match once; the times skipped when the clocks go forward never match.
+     * @param after The time to search from, a date or milliseconds since the epoch; now by default.
+     * @returns The next matching time, `undefined` when none matches within eight years (such as February 30th).
+     */
+    next(after?: Date | number): Date | undefined;
+}
+/**
+ * Parse a duration into milliseconds, as `@Schedule` reads its intervals.
+ * @param duration A number of milliseconds, or a text of numbers with their units (`ms`, `s`, `m`, `h`, `d`), summed
+ * and case-insensitive: `500ms`, `30s`, `1.5h`, `1h 30m`, `1d`.
+ * @returns The duration in milliseconds.
+ * @throws {SyntaxError} When the duration is not positive (or not finite), or the text has an unknown part.
+ * @example
+ * ```typescript
+ * import {parseDuration} from 'lakutata/com/entrypoint'
+ *
+ * console.log(parseDuration('1h30m')) //5400000
+ * console.log(parseDuration('500ms')) //500
+ * console.log(parseDuration(2000)) //2000
+ * ```
+ */
+export declare function parseDuration(duration: number | string): number;

package/dist/types/types/CLIContextParams.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The parameters creating a `CLIContext`, given by the CLI adapters.
+ */
+export type CLIContextParams = {
+    /**
+     * The command of the action as declared, its controller prefix included (`'user:get <id>'`).
+     */
+    readonly command: string;
+    /**
+     * The input of the action before its validation: the positional arguments and the options of the command, by the
+     * names of the DTO properties.
+     */
+    readonly data: Record<string, any>;
+};

package/dist/types/types/ErrorDescription.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The error number and message of an error, as `describeError()` gives them and the HTTP responders answer them
+ * (`{errno, errMsg}`).
+ */
+export type ErrorDescription = {
+    /**
+     * The `errno` of the error, else its `code`, else `'E_UNKNOWN'`.
+     */
+    errno: string | number;
+    /**
+     * The `errMsg` of the error, else its `message`, else the error converted to a string.
+     */
+    errMsg: string;
+};

package/dist/types/types/HTTPContextParams.d.ts

@@ -0,0 +1,27 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+/**
+ * The parameters creating an `HTTPContext`, given by the HTTP adapters.
+ */
+export type HTTPContextParams = {
+    /**
+     * The route of the action as declared, its controller prefix included (`'/users/:id'`).
+     */
+    readonly route: string;
+    /**
+     * The HTTP method of the action, as declared (`'get'`).
+     */
+    readonly method: string;
+    /**
+     * The Node.js request.
+     */
+    readonly request: IncomingMessage;
+    /**
+     * The Node.js response.
+     */
+    readonly response: ServerResponse;
+    /**
+     * The input of the action before its validation: by default, the query string merged with the parsed body (the
+     * route parameters are given apart, to the dispatch).
+     */
+    readonly data: Record<string, any>;
+};

package/dist/types/types/ScheduleContextParams.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The parameters creating a `ScheduleContext`, given by the schedule adapter.
+ */
+export type ScheduleContextParams = {
+    /**
+     * The schedule of the action, as a text (`'every 30s'`, `'cron 0 * * * *'`).
+     */
+    readonly schedule: string;
+    /**
+     * The time the run was planned for.
+     */
+    readonly scheduledAt: Date;
+    /**
+     * The number of the run, from 1.
+     */
+    readonly run: number;
+    /**
+     * The input of the run: an empty object for the schedule adapter.
+     */
+    readonly data: Record<string, any>;
+};

package/dist/types/types/ServiceContextParams.d.ts

@@ -0,0 +1,16 @@
+import { type ActionPattern } from '@lakutata/core';
+/**
+ * The parameters creating a `ServiceContext`, given by the service adapters (which may add their own, such as the
+ * Socket.IO socket).
+ */
+export type ServiceContextParams = {
+    /**
+     * The message received: an object, matched against the actions' patterns.
+     */
+    readonly data: ActionPattern;
+    /**
+     * The id of the client of the request, which `Entrypoint.notify()` pushes the events to; omitted for the transports
+     * without clients.
+     */
+    readonly clientId?: string;
+};

package/package.json

@@ -0,0 +1,152 @@
+{
+  "name": "@lakutata/entrypoint",
+  "version": "3.0.0-beta.0",
+  "description": "The entrypoint component of the lakutata framework: controllers and the dispatch of the CLI, HTTP and service actions.",
+  "type": "module",
+  "main": "./dist/cjs/exports/Entrypoint.js",
+  "types": "./dist/cjs/exports/Entrypoint.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/exports/Entrypoint.d.ts",
+        "default": "./dist/esm/exports/Entrypoint.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/Entrypoint.d.ts",
+        "default": "./dist/cjs/exports/Entrypoint.js"
+      }
+    },
+    "./decorator/ctrl": {
+      "import": {
+        "types": "./dist/types/exports/CTRLDecorators.d.ts",
+        "default": "./dist/esm/exports/CTRLDecorators.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/CTRLDecorators.d.ts",
+        "default": "./dist/cjs/exports/CTRLDecorators.js"
+      }
+    },
+    "./channel": {
+      "import": {
+        "types": "./dist/types/exports/Channel.d.ts",
+        "default": "./dist/esm/exports/Channel.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/Channel.d.ts",
+        "default": "./dist/cjs/exports/Channel.js"
+      }
+    },
+    "./adapter/express": {
+      "import": {
+        "types": "./dist/types/exports/ExpressAdapter.d.ts",
+        "default": "./dist/esm/exports/ExpressAdapter.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/ExpressAdapter.d.ts",
+        "default": "./dist/cjs/exports/ExpressAdapter.js"
+      }
+    },
+    "./adapter/commander": {
+      "import": {
+        "types": "./dist/types/exports/CommanderAdapter.d.ts",
+        "default": "./dist/esm/exports/CommanderAdapter.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/CommanderAdapter.d.ts",
+        "default": "./dist/cjs/exports/CommanderAdapter.js"
+      }
+    },
+    "./adapter/fastify": {
+      "import": {
+        "types": "./dist/types/exports/FastifyAdapter.d.ts",
+        "default": "./dist/esm/exports/FastifyAdapter.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/FastifyAdapter.d.ts",
+        "default": "./dist/cjs/exports/FastifyAdapter.js"
+      }
+    },
+    "./adapter/socket.io": {
+      "import": {
+        "types": "./dist/types/exports/SocketIOAdapter.d.ts",
+        "default": "./dist/esm/exports/SocketIOAdapter.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/SocketIOAdapter.d.ts",
+        "default": "./dist/cjs/exports/SocketIOAdapter.js"
+      }
+    },
+    "./adapter/electron": {
+      "import": {
+        "types": "./dist/types/exports/ElectronAdapter.d.ts",
+        "default": "./dist/esm/exports/ElectronAdapter.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/ElectronAdapter.d.ts",
+        "default": "./dist/cjs/exports/ElectronAdapter.js"
+      }
+    },
+    "./adapter/jsonrpc": {
+      "import": {
+        "types": "./dist/types/exports/JSONRPCAdapter.d.ts",
+        "default": "./dist/esm/exports/JSONRPCAdapter.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/JSONRPCAdapter.d.ts",
+        "default": "./dist/cjs/exports/JSONRPCAdapter.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\"",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs-pkg": "node ../../scripts/package-build/cjs-package.mjs",
+    "build:js": "npm run build:cjs && npm run build:esm && npm run build:cjs-pkg",
+    "rebuild": "npm run clean && npm run build:js",
+    "compile": "npm run rebuild",
+    "test:unit": "npm run compile && node --test \"dist/esm/tests/*.spec.js\""
+  },
+  "peerDependencies": {
+    "@inquirer/prompts": "^7.0.0 || ^8.0.0",
+    "@lakutata/core": "3.0.0-beta.0",
+    "@lakutata/utils": "3.0.0-beta.0",
+    "commander": "^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0",
+    "express": "^4.21.0 || ^5.0.0",
+    "fastify": "^5.0.0",
+    "socket.io": "^4.0.0",
+    "ws": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "commander": {
+      "optional": true
+    },
+    "@inquirer/prompts": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "socket.io": {
+      "optional": true
+    },
+    "ws": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "!dist/*/tests",
+    "*.md",
+    "LICENSE",
+    "package.json",
+    "THIRD_PARTY_NOTICES.md"
+  ]
+}