@lakutata/entrypoint 3.0.0-beta.0

package/dist/cjs/adapter/commander/Prompt.js

@@ -0,0 +1,164 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPrompts = loadPrompts;
+exports.prompt = prompt;
+const node_stream_1 = require("node:stream");
+const core_1 = require("@lakutata/core");
+/**
+ * The property names of the secrets, prompted without echo
+ */
+const SECRET = /pass(word)?|secret|token|api[-_]?key|credential/i;
+/**
+ * The prompts, undefined when @inquirer/prompts is not installed
+ */
+let prompts;
+/**
+ * Load the prompts
+ */
+function loadPrompts() {
+    prompts ??= Promise.resolve().then(() => __importStar(require('@inquirer/prompts'))).catch(() => undefined);
+    return prompts;
+}
+/**
+ * The type of a property, without null
+ * @param schema
+ */
+function typeOf(schema) {
+    const types = [].concat(schema.type ?? []).filter((type) => type !== 'null');
+    if (types.length)
+        return types[0];
+    if (schema.enum?.length)
+        return typeof schema.enum[0];
+    return undefined;
+}
+/**
+ * Validate an answer by the rules of its property in the DTO of the action
+ * @param dto
+ * @param property
+ */
+function validator(dto, property) {
+    let field;
+    try {
+        field = dto.Schema().extract(property).label(property);
+    }
+    catch {
+        //A property without its own rule is validated with the whole input
+        return async () => true;
+    }
+    return async (value) => {
+        try {
+            await core_1.DTO.validateAsync(value, field);
+            return true;
+        }
+        catch (error) {
+            return error.errMsg ?? error.message;
+        }
+    };
+}
+/**
+ * Prompt for the required properties missing from the input of an action, when @inquirer/prompts is installed
+ * @param action
+ * @param data
+ * @param streams
+ * @param describe the description of a property in the language of the user
+ * @param say the text of the prompts in the language of the user
+ */
+async function prompt(action, data, streams, describe = (property) => action.jsonSchema.properties?.[property]?.description, say = (key, text) => text) {
+    const schema = action.jsonSchema;
+    const missing = (schema.required ?? []).filter((property) => data[property] === undefined && schema.properties?.[property]?.default === undefined);
+    if (!missing.length)
+        return;
+    const inquirer = await loadPrompts();
+    if (!inquirer)
+        return;
+    for (const property of missing) {
+        //A prompt ends its output once answered, the output of the adapter is kept open
+        const output = new node_stream_1.PassThrough();
+        output.pipe(streams.output, { end: false });
+        try {
+            data[property] = await ask(inquirer, action, property, schema.properties?.[property] ?? {}, { input: streams.input, output: output, signal: streams.signal }, describe(property), say);
+        }
+        finally {
+            output.unpipe(streams.output);
+        }
+    }
+}
+/**
+ * Ask for a property
+ * @param inquirer
+ * @param action
+ * @param property
+ * @param propertySchema
+ * @param context
+ * @param description the description of the property in the language of the user
+ * @param say the text of the prompts in the language of the user
+ */
+async function ask(inquirer, action, property, propertySchema, context, description, say) {
+    const message = description ? `${description} (${property})` : property;
+    const validate = validator(action.dto, property);
+    const type = typeOf(propertySchema);
+    const choices = (values) => values.map((value) => ({ name: String(value), value: value }));
+    if (type === 'boolean')
+        return await inquirer.confirm({ message: message }, context);
+    if (propertySchema.enum)
+        return await inquirer.select({ message: message, choices: choices(propertySchema.enum) }, context);
+    if (type === 'array' && propertySchema.items?.enum)
+        return await inquirer.checkbox({ message: message, choices: choices(propertySchema.items.enum), validate: (selected) => validate(selected.map((choice) => choice.value)) }, context);
+    if (type === 'number' || type === 'integer')
+        return await inquirer.number({ message: message, required: true, step: type === 'integer' ? 1 : 'any', validate: validate }, context);
+    if (type === 'string' && (propertySchema.format === 'password' || SECRET.test(property)))
+        return await inquirer.password({ message: message, mask: '*', validate: validate }, context);
+    //The arrays are separated by commas, the objects are written in JSON
+    const parse = (answer) => {
+        if (type === 'array')
+            return answer.split(',').map((item) => item.trim()).filter((item) => !!item);
+        if (type === 'object')
+            return JSON.parse(answer);
+        return answer;
+    };
+    return parse(await inquirer.input({
+        message: message,
+        required: true,
+        validate: async (value) => {
+            try {
+                return await validate(parse(value));
+            }
+            catch {
+                return say('prompt.json', 'Not a JSON object');
+            }
+        }
+    }, context));
+}

package/dist/cjs/adapter/commander/Width.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The width of a text in a terminal, the wide characters taking two columns
+ * @param text
+ */
+export declare function displayWidth(text: string): number;
+/**
+ * Wrap a text to a width, as commander does, the lines of wide characters wrapped between them
+ * @param text
+ * @param width
+ * @param minimum the width under which the text is not wrapped
+ */
+export declare function boxWrap(text: string, width: number, minimum?: number): string;

package/dist/cjs/adapter/commander/Width.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.displayWidth = displayWidth;
+exports.boxWrap = boxWrap;
+const node_util_1 = require("node:util");
+/**
+ * The wide characters of the terminals: the Chinese, Japanese and Korean ones, the full width forms
+ */
+const WIDE = '\\u1100-\\u115F\\u2E80-\\u303E\\u3041-\\u33FF\\u3400-\\u4DBF\\u4E00-\\u9FFF\\uA000-\\uA4CF\\uAC00-\\uD7A3\\uF900-\\uFAFF\\uFE30-\\uFE4F\\uFF00-\\uFF60\\uFFE0-\\uFFE6\\u{20000}-\\u{3FFFD}';
+/**
+ * The punctuation which does not start a line
+ */
+const CLOSING = '、。，．：；！？）」』】〕〉》％,.:;!?)\\]}';
+/**
+ * The punctuation which does not end a line
+ */
+const OPENING = '（「『【〔〈《(\\[{';
+const WIDE_CHARACTER = new RegExp(`[${WIDE}]`, 'u');
+/**
+ * The chunks of a line the wrapping keeps whole: a word, or a wide character, with the punctuation opening and
+ * closing it
+ */
+const CHUNK = new RegExp(`\\s*[${OPENING}]*(?:[${WIDE}]|[^\\s${WIDE}]+)[${CLOSING}]*`, 'gu');
+/**
+ * The width of a text in a terminal, the wide characters taking two columns
+ * @param text
+ */
+function displayWidth(text) {
+    let width = 0;
+    for (const character of (0, node_util_1.stripVTControlCharacters)(text))
+        width += WIDE_CHARACTER.test(character) ? 2 : 1;
+    return width;
+}
+/**
+ * Wrap a text to a width, as commander does, the lines of wide characters wrapped between them
+ * @param text
+ * @param width
+ * @param minimum the width under which the text is not wrapped
+ */
+function boxWrap(text, width, minimum = 40) {
+    if (width < minimum)
+        return text;
+    const wrapped = [];
+    for (const line of text.split(/\r\n|\n/)) {
+        const chunks = line.match(CHUNK);
+        if (!chunks) {
+            wrapped.push('');
+            continue;
+        }
+        let current = chunks.shift();
+        let currentWidth = displayWidth(current);
+        for (const chunk of chunks) {
+            const chunkWidth = displayWidth(chunk);
+            if (currentWidth + chunkWidth <= width) {
+                current += chunk;
+                currentWidth += chunkWidth;
+                continue;
+            }
+            wrapped.push(current);
+            //The space at the break removed
+            current = chunk.trimStart();
+            currentWidth = displayWidth(current);
+        }
+        wrapped.push(current);
+    }
+    return wrapped.join('\n');
+}

package/dist/cjs/adapter/electron/ElectronIPCServiceEntrypoint.d.ts

@@ -0,0 +1,203 @@
+import type { EntrypointAdapter } from '../../channel/EntrypointAdapter.js';
+import type { MiddlewareDefinition } from '../../lib/Middleware.js';
+import { ServiceContext } from '../../context/ServiceContext.js';
+/**
+ * The part of Electron's `WebContents` (a renderer) that {@link electronIPCServiceEntrypoint} uses: the sender of the
+ * invocations and the receiver of the events pushed to its pages.
+ */
+export type IPCSender = {
+    /**
+     * Listen once to the renderer's destruction, which aborts its requests in progress and removes its clients.
+     * @param event The `'destroyed'` event.
+     * @param listener Called when the renderer is destroyed.
+     */
+    once(event: 'destroyed', listener: () => void): unknown;
+    /**
+     * Remove a `'destroyed'` listener (`removeListener` is used without it).
+     * @param event The `'destroyed'` event.
+     * @param listener The listener to remove.
+     */
+    off?(event: 'destroyed', listener: () => void): unknown;
+    /**
+     * Remove a `'destroyed'` listener, when `off` is missing.
+     * @param event The `'destroyed'` event.
+     * @param listener The listener to remove.
+     */
+    removeListener?(event: 'destroyed', listener: () => void): unknown;
+    /**
+     * Send a message to the renderer's main frame, used to push an event to a client without a known frame.
+     * @param channel The IPC channel.
+     * @param args The message's arguments.
+     */
+    send?(channel: string, ...args: unknown[]): void;
+    /**
+     * Send a message to a frame of the renderer, used to push an event to the page of a client.
+     * @param frame The frame's process id and frame id.
+     * @param channel The IPC channel.
+     * @param args The message's arguments.
+     */
+    sendToFrame?(frame: [number, number], channel: string, ...args: unknown[]): void;
+    /**
+     * Tell whether the renderer is destroyed; its clients are then dropped instead of receiving the events.
+     * @returns Whether the renderer is destroyed.
+     */
+    isDestroyed?(): boolean;
+};
+/**
+ * The part of Electron's `IpcMainInvokeEvent` that {@link electronIPCServiceEntrypoint} uses, given to the service
+ * actions through {@link ipcEventOfContext}.
+ */
+export type IPCInvokeEvent = {
+    /**
+     * The renderer that invoked.
+     */
+    readonly sender: IPCSender;
+    /**
+     * The id of the renderer process of the invoking frame.
+     */
+    readonly processId?: number;
+    /**
+     * The id of the invoking frame within its process.
+     */
+    readonly frameId?: number;
+    /**
+     * The invoking frame; a frame without `parent` is the main frame of its window.
+     */
+    readonly senderFrame?: {
+        readonly parent?: unknown;
+    } | null;
+};
+/**
+ * The part of Electron's `ipcMain` that {@link electronIPCServiceEntrypoint} uses (give a stand-in in the tests).
+ */
+export type IPCMain = {
+    /**
+     * Handle the invocations of a channel (`ipcRenderer.invoke`).
+     * @param channel The IPC channel.
+     * @param listener Answers an invocation with its result.
+     */
+    handle(channel: string, listener: (event: any, ...args: any[]) => unknown): void;
+    /**
+     * Remove the handler of a channel, when the adapter closes.
+     * @param channel The IPC channel.
+     */
+    removeHandler(channel: string): void;
+    /**
+     * Listen to the messages of a channel (`ipcRenderer.send`), used for the event subscriptions; without it, the pages
+     * are registered as clients only when they invoke with their id.
+     * @param channel The IPC channel.
+     * @param listener Called with each message.
+     */
+    on?(channel: string, listener: (event: any, ...args: any[]) => void): unknown;
+    /**
+     * Remove the listeners of a channel, when the adapter closes.
+     * @param channel The IPC channel.
+     */
+    removeAllListeners?(channel: string): unknown;
+};
+/**
+ * The options of {@link electronIPCServiceEntrypoint}.
+ */
+export type ElectronIPCServiceEntrypointOptions = {
+    /**
+     * The adapter name, to tell apart several service adapters of one entrypoint.
+     */
+    name?: string;
+    /**
+     * The IPC channel of the requests (`ipcRenderer.invoke(channel, data, clientId)`). The events pushed to the pages are
+     * sent on `<channel>:event`, and a page subscribes to them by sending its client id on `<channel>:subscribe`.
+     * @default 'lakutata:service'
+     */
+    channel?: string;
+    /**
+     * The `ipcMain` to serve the requests on.
+     * @default the `ipcMain` of Electron's main process
+     */
+    ipcMain?: IPCMain;
+    /**
+     * The middlewares of this adapter's actions, run after the entrypoint's global middlewares.
+     */
+    middlewares?: MiddlewareDefinition[];
+};
+/**
+ * Get the IPC event of a service action's request, when {@link electronIPCServiceEntrypoint} serves it (to reach the
+ * invoking renderer or frame).
+ * @param context The service action's context (`this.context` in a controller).
+ * @returns The IPC event (Electron's `IpcMainInvokeEvent`, typed as `Event`), or `undefined` when another adapter serves
+ * the request.
+ * @example
+ * ```typescript
+ * import {Controller, ServiceContext} from 'lakutata/com/entrypoint'
+ * import {ipcEventOfContext} from 'lakutata/adapter/electron'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ * import type {IpcMainInvokeEvent} from 'electron'
+ *
+ * class WindowController extends Controller {
+ *     //ipcRenderer.invoke('lakutata:service', {cmd: 'window.url'})
+ *     @ServiceAction({cmd: 'window.url'})
+ *     public async url(): Promise<string | undefined> {
+ *         return ipcEventOfContext<IpcMainInvokeEvent>(this.context as ServiceContext)?.sender.getURL()
+ *     }
+ * }
+ * ```
+ */
+export declare function ipcEventOfContext<Event extends IPCInvokeEvent = IPCInvokeEvent>(context: ServiceContext): Event | undefined;
+/**
+ * Create a service adapter of an entrypoint served over Electron's IPC, in the main process. It needs the optional
+ * peer dependency `electron`: without the `ipcMain` option, the entrypoint fails to start outside Electron's main
+ * process.
+ *
+ * A renderer invokes the channel with the action's pattern and input, and optionally its client id:
+ * `ipcRenderer.invoke('lakutata:service', {cmd: 'echo', text: 'hi'}, clientId)`. The invocation resolves to
+ * `{success, error, payload}` (see `ServiceResponseCodec`): `payload` is the result, or `error` the whole error object
+ * when the action failed (no matching action, validation…).
+ *
+ * Each page is a client, identified by the id it gives (a non-empty string of at most 200 characters), which its
+ * requests carry as `ServiceContext.clientId`. A page registers by sending its id on `<channel>:subscribe` (or with
+ * any invocation giving it); a page reloaded in the same frame replaces its previous id. The events pushed by
+ * `Entrypoint.notify` and `Entrypoint.broadcast` are sent to the page's frame on `<channel>:event` with the event name
+ * and its arguments array. A destroyed renderer drops its clients.
+ *
+ * When a renderer is destroyed, its requests in progress are aborted (their abort signal fires). When the entrypoint
+ * stops, the new invocations resolve to an `EntrypointStoppedException` error; once the requests in progress end, the
+ * IPC handlers are removed.
+ * @param options The adapter options; by default it serves the channel `'lakutata:service'` on Electron's `ipcMain`.
+ * @returns The adapter, to give to the `service` option of `buildEntrypoints`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ * import {electronIPCServiceEntrypoint} from 'lakutata/adapter/electron'
+ * import type {IpcRenderer, IpcRendererEvent} from 'electron'
+ *
+ * class EchoController extends Controller {
+ *     @ServiceAction({cmd: 'echo'})
+ *     public async echo(input: {text: string}): Promise<string> {
+ *         return input.text
+ *     }
+ * }
+ *
+ * //In the main process
+ * Application.run({
+ *     id: 'desktop.app',
+ *     name: 'Desktop',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [EchoController],
+ *             service: electronIPCServiceEntrypoint()
+ *         })
+ *     }
+ * })
+ *
+ * //In the preload script of a window
+ * declare const ipcRenderer: IpcRenderer
+ * const clientId: string = crypto.randomUUID()
+ * //The events pushed by entrypoint.notify(clientId, 'progress', 50)
+ * ipcRenderer.on('lakutata:service:event', (event: IpcRendererEvent, name: string, args: unknown[]): void => console.log(name, ...args))
+ * ipcRenderer.send('lakutata:service:subscribe', clientId)
+ * //{success: true, error: null, payload: 'hi'}
+ * console.log(await ipcRenderer.invoke('lakutata:service', {cmd: 'echo', text: 'hi'}, clientId))
+ * ```
+ */
+export declare function electronIPCServiceEntrypoint(options?: ElectronIPCServiceEntrypointOptions): EntrypointAdapter<ServiceContext>;