@3fv/electron-utility-process-manager 1.0.2 → 1.0.4

package/lib/mjs/main/UPMMainService.d.ts

@@ -1,22 +1,35 @@
 import { MessagePortMain } from "electron";
 import * as UPM from "../common/index.js";
-import { IServiceClient } from "../common/index.js";
-export interface UPMMainServiceConfig {
-}
-export type UPMMainServiceOptions = Partial<UPMMainServiceConfig>;
+/**
+ * Contains & Manages a `Utility/Process`
+ * providing simplified messaging & event
+ * propagation.
+ */
 export declare class UPMMainService<ReqMap extends UPM.MessageRequestMap = any, MType extends UPM.MessageRequestNames<ReqMap> = UPM.MessageRequestNames<ReqMap>> implements UPM.IMessageClient<ReqMap, MType> {
     readonly serviceName: string;
     readonly entryFile: string;
+    /**
+     * As this container/wrapper implements
+     * `IMessageClient`, it needs to provide
+     * a `clientId`, which is constant in the
+     * main process
+     */
     readonly clientId: string;
-    private readonly config_;
-    private readyDeferred_;
-    private killDeferred_;
-    private lastMessageId_;
-    private childProcess_;
-    private pendingMessages_;
-    private messageChannels_;
-    private init;
-    private onMessage;
+    /**
+     * Send an event as `fire-and-forget`
+     *
+     * @param data
+     * @param port
+     */
+    sendEvent(data: any, port?: UPM.Port): void;
+    /**
+     * Send request
+     *
+     * @param type
+     * @param args
+     */
+    executeRequest<Type extends MType, R extends UPM.MessageRequestReturnType<ReqMap, Type> = UPM.MessageRequestReturnType<ReqMap, Type>>(type: Type, ...args: UPM.MessageRequestParams<ReqMap, Type>): Promise<R>;
+    close(): void;
     /**
      * Resolves when ready
      *
@@ -27,7 +40,15 @@ export declare class UPMMainService<ReqMap extends UPM.MessageRequestMap = any,
      * Return a simple proxy facade wrapping
      * `executeRequest` into individual methods
      */
-    getServiceClient(): IServiceClient<ReqMap, MType>;
+    getServiceClient(): UPM.IServiceClient<ReqMap, MType>;
+    private readonly config_;
+    private readyDeferred_;
+    private killDeferred_;
+    private messageIdSeq_;
+    private childProcess_;
+    private pendingMessages_;
+    private messageChannels_;
+    private onServiceExit;
     /**
      * Returned client side port (for Renderer)
      * @param clientId
@@ -38,33 +59,93 @@ export declare class UPMMainService<ReqMap extends UPM.MessageRequestMap = any,
      * (useful to avoid congestion on default child_process channel)
      *
      * @param {string} clientId
-     * @returns {UPM.MessagePortClient<MessageRequestMap, MessageType>}
+     * @returns {UPM.MessagePortClient}
      */
     createMainClient(clientId: string): UPM.MessagePortClient<ReqMap, MType>;
+    /**
+     * Service is still in a healthy/running/runnable state
+     */
+    get isRunning(): boolean;
+    /**
+     * Stop the service (kill)
+     */
+    stop(): Promise<void>;
+    /**
+     * Resource management & cleanup
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Initialize the service
+     *
+     * @private
+     */
+    private init;
+    /**
+     * OnMessage really only handles `results` from
+     * `executeRequest(...)`; this may be expanded in
+     * the future
+     *
+     * @param payload
+     * @private
+     */
+    private onMessage;
+    /**
+     * This handler is currently unused, but
+     * could be attached to a `MessagePort.on('close')`
+     * event
+     *
+     * @param id
+     * @param channel
+     * @private
+     */
     private onPortClose;
-    private closeMessageChannel;
-    close(): void;
     /**
-     * Send an event as `fire-and-forget`
+     * Close a message channel
      *
-     * @param data
-     * @param port
+     * @param id
+     * @param channel
+     * @private
      */
-    sendEvent(data: any, port?: UPM.Port): void;
+    private closeMessageChannel;
     /**
-     * Send request
+     * Kill the service
      *
-     * @param type
-     * @param args
+     * @private
      */
-    executeRequest<Type extends MType, R extends UPM.MessageRequestReturnType<ReqMap, Type> = UPM.MessageRequestReturnType<ReqMap, Type>>(type: Type, ...args: UPM.MessageRequestParams<ReqMap, Type>): Promise<R>;
-    stop(): Promise<void>;
     private kill;
+    /**
+     * Close all message channels
+     *
+     * @private
+     */
     private removeAllMessageChannels;
+    /**
+     * Remove all pending messages
+     *
+     * @private
+     */
     private cancelAllPendingMessages;
-    constructor(serviceName: string, entryFile: string, options?: UPMMainServiceOptions);
+    /**
+     * Remove a pending message from the queue,
+     * whether settled or not
+     *
+     * @param messageId
+     * @private
+     */
     private removePendingMessage;
+    /**
+     * Generate next message id
+     *
+     * @private
+     */
     private generateMessageId;
-    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Construct a new service
+     *
+     * @param serviceName
+     * @param entryFile
+     * @param options
+     */
+    constructor(serviceName: string, entryFile: string, options?: UPM.CreateServiceOptions);
 }
 export default UPMMainService;

package/lib/mjs/main/UPMMainService.js

@@ -1,68 +1,66 @@
 import { app, MessageChannelMain, utilityProcess } from "electron";
-import { assert, getValue, isString } from "@3fv/guard";
+import { assert, getValue, isNumber, isString } from "@3fv/guard";
 import Fsx from "fs-extra";
 import { Deferred } from "@3fv/deferred";
 import * as UPM from "../common/index.js";
-import { isEmpty, negate } from "lodash";
+import { defaults, isEmpty, negate } from "lodash";
 import Tracer from "tracer";
+import { asOption } from "@3fv/prelude-ts";
+import { match } from "ts-pattern";
 const log = Tracer.colorConsole();
 const isNotEmpty = negate(isEmpty);
+/**
+ * Contains & Manages a `Utility/Process`
+ * providing simplified messaging & event
+ * propagation.
+ */
 export class UPMMainService {
-    async init() {
-        let deferred = this.readyDeferred_;
-        if (deferred) {
-            return deferred.promise;
-        }
-        deferred = this.readyDeferred_ = new Deferred();
-        try {
-            const exitListener = (code) => {
-                if (code !== 0) {
-                    deferred.reject(new Error(`process exited with code ${code} upon starting`));
-                }
-            };
-            const spawnListener = async () => {
-                this.childProcess_.off("exit", exitListener);
-                this.childProcess_.on("message", this.onMessage.bind(this));
-                deferred.resolve(this);
-            };
-            this.childProcess_ = utilityProcess
-                .fork(this.entryFile, [], {
-                serviceName: this.serviceName,
-                env: Object.assign(Object.assign({}, process.env), { IN_CHILD_PROCESS: "true", APP_NAME: app.name })
-            })
-                .on("spawn", spawnListener)
-                .on("exit", exitListener);
-            await deferred.promise;
-        }
-        catch (err) {
-            deferred.reject(err);
-        }
-        return deferred.promise;
+    /**
+     * Send an event as `fire-and-forget`
+     *
+     * @param data
+     * @param port
+     */
+    sendEvent(data, port = this.childProcess_) {
+        const messageId = this.generateMessageId();
+        const payload = {
+            channel: UPM.IPCChannel.UPMServiceMessage,
+            payload: { messageId, eventData: data, kind: UPM.MessageKind.Event }
+        };
+        port.postMessage(payload);
     }
-    onMessage(payload) {
-        const { type, kind, messageId, result, error } = payload;
+    /**
+     * Send request
+     *
+     * @param type
+     * @param args
+     */
+    async executeRequest(type, ...args) {
+        assert(!!this.childProcess_, "The process is not running");
+        const messageId = this.generateMessageId(), pending = {
+            deferred: new Deferred(),
+            messageId,
+            timeoutId: setTimeout(() => this.removePendingMessage(messageId), UPM.Defaults.RequestTimeout)
+        };
+        this.pendingMessages_.set(messageId, pending);
+        const payload = {
+            channel: UPM.IPCChannel.UPMServiceMessage,
+            payload: { type, messageId, args, kind: UPM.MessageKind.Request }
+        };
+        this.childProcess_.postMessage(payload);
         try {
-            const pending = this.pendingMessages_.get(messageId);
-            if (!pending) {
-                log.info(`Unable to find pending record ${messageId}`);
-                return;
-            }
-            if (pending.deferred.isSettled()) {
-                log.error(`Already settled record ${messageId}`);
-                return;
-            }
-            this.removePendingMessage(messageId);
-            if (!!error) {
-                log.error(error);
-                pending.deferred.reject(new Error(error));
-                return;
-            }
-            pending.deferred.resolve(result);
+            const result = await pending.deferred.promise;
+            log.debug(`Completed utility request (messageId=${messageId})`);
+            return result;
         }
         catch (err) {
-            log.error(`Failed to handle message`, err);
+            log.error(`Failed utility request (messageId=${messageId})`, err);
+            throw err;
         }
     }
+    close() {
+        log.warn("Close has no effect when called via the main process");
+    }
     /**
      * Resolves when ready
      *
@@ -86,6 +84,22 @@ export class UPMMainService {
             }
         });
     }
+    onServiceExit(code) {
+        log.warn(`Service Exit (code=${code})`);
+        let deferred = this.killDeferred_;
+        if (deferred) {
+            if (!deferred.isSettled()) {
+                deferred.resolve(code);
+            }
+            else {
+                log.warn(`kill deferred is already settled (code=${code})`);
+            }
+            return;
+        }
+        this.killDeferred_ = Deferred.resolve(code);
+        this.cancelAllPendingMessages();
+        this.removeAllMessageChannels();
+    }
     /**
      * Returned client side port (for Renderer)
      * @param clientId
@@ -98,8 +112,7 @@ export class UPMMainService {
         try {
             this.childProcess_.postMessage({
                 message: {
-                    channel: UPM.IPCChannel.UPMServiceNewClient,
-                    payload: { clientId }
+                    channel: UPM.IPCChannel.UPMServiceNewClient, payload: { clientId }
                 }
             }, [port1]);
         }
@@ -115,97 +128,162 @@ export class UPMMainService {
      * (useful to avoid congestion on default child_process channel)
      *
      * @param {string} clientId
-     * @returns {UPM.MessagePortClient<MessageRequestMap, MessageType>}
+     * @returns {UPM.MessagePortClient}
      */
     createMainClient(clientId) {
         return new UPM.MessagePortClient(clientId, this.createMessageChannel(clientId));
     }
-    onPortClose(id, channel) {
-        log.info(`main side of message channel(id=${id}) closed`);
-        this.closeMessageChannel(id, channel);
+    /**
+     * Service is still in a healthy/running/runnable state
+     */
+    get isRunning() {
+        return !this.killDeferred_;
     }
-    closeMessageChannel(id, channel) {
-        if (this.messageChannels_.has(id)) {
-            this.messageChannels_.delete(id);
-        }
-        ;
-        [channel.port1, channel.port2].forEach(p => getValue(() => p.close()));
+    /**
+     * Stop the service (kill)
+     */
+    async stop() {
+        await this.kill();
     }
-    close() {
-        log.warn("Close has no effect when called via the main process");
+    /**
+     * Resource management & cleanup
+     */
+    async [Symbol.asyncDispose]() {
+        await this.stop();
     }
     /**
-     * Send an event as `fire-and-forget`
+     * Initialize the service
      *
-     * @param data
-     * @param port
+     * @private
      */
-    sendEvent(data, port = this.childProcess_) {
-        const messageId = this.generateMessageId();
-        const payload = {
-            channel: UPM.IPCChannel.UPMServiceMessage,
-            payload: { messageId, eventData: data, kind: UPM.MessageKind.Event }
-        };
-        port.postMessage(payload);
+    async init() {
+        let deferred = this.readyDeferred_;
+        if (deferred) {
+            return deferred.promise;
+        }
+        deferred = this.readyDeferred_ = new Deferred();
+        try {
+            const exitListener = (code) => {
+                if (code !== 0) {
+                    deferred.reject(new Error(`process exited with code ${code} upon starting`));
+                }
+            };
+            const spawnListener = async () => {
+                this.childProcess_.off("exit", exitListener);
+                this.childProcess_.on("exit", this.onServiceExit.bind(this));
+                this.childProcess_.on("message", this.onMessage.bind(this));
+                deferred.resolve(this);
+            };
+            // BUILD ADDITIONAL FORK OPTIONS
+            const childProcessOptions = asOption(this.config_.inspect)
+                .filter(it => it !== false)
+                .map(it => ({
+                execArgv: [
+                    match(it)
+                        .when(isNumber, port => `--inspect=${port}`)
+                        .otherwise(({ port, break: shouldBreak }) => {
+                        const ext = shouldBreak ? "-brk" : "";
+                        return `--inspect${ext}=${port}`;
+                    })
+                ]
+            }))
+                .getOrElse({});
+            // FORK
+            this.childProcess_ = utilityProcess
+                .fork(this.entryFile, [], Object.assign(Object.assign({}, childProcessOptions), { serviceName: this.serviceName, env: Object.assign(Object.assign({}, process.env), { IN_CHILD_PROCESS: "true", APP_NAME: app.name }) }))
+                .on("spawn", spawnListener)
+                .on("exit", exitListener);
+            await deferred.promise;
+        }
+        catch (err) {
+            deferred.reject(err);
+        }
+        return deferred.promise;
     }
     /**
-     * Send request
+     * OnMessage really only handles `results` from
+     * `executeRequest(...)`; this may be expanded in
+     * the future
      *
-     * @param type
-     * @param args
+     * @param payload
+     * @private
      */
-    async executeRequest(type, ...args) {
-        assert(!!this.childProcess_, "The process is not running");
-        const messageId = this.generateMessageId(), pending = {
-            deferred: new Deferred(),
-            messageId,
-            timeoutId: setTimeout(() => this.removePendingMessage(messageId), UPM.Defaults.RequestTimeout)
-        };
-        this.pendingMessages_.set(messageId, pending);
-        const payload = {
-            channel: UPM.IPCChannel.UPMServiceMessage,
-            payload: { type, messageId, args, kind: UPM.MessageKind.Request }
-        };
-        this.childProcess_.postMessage(payload);
+    onMessage(payload) {
+        const { messageId, result, error } = payload;
         try {
-            const result = await pending.deferred.promise;
-            log.debug(`Completed utility request (messageId=${messageId})`);
-            return result;
+            const pending = this.pendingMessages_.get(messageId);
+            if (!pending) {
+                log.info(`Unable to find pending record ${messageId}`);
+                return;
+            }
+            if (pending.deferred.isSettled()) {
+                log.error(`Already settled record ${messageId}`);
+                return;
+            }
+            this.removePendingMessage(messageId);
+            if (!!error) {
+                log.error(error);
+                pending.deferred.reject(new Error(error));
+                return;
+            }
+            pending.deferred.resolve(result);
         }
         catch (err) {
-            log.error(`Failed utility request (messageId=${messageId})`, err);
-            throw err;
+            log.error(`Failed to handle message`, err);
         }
     }
-    async stop() {
-        await this.kill();
+    /**
+     * This handler is currently unused, but
+     * could be attached to a `MessagePort.on('close')`
+     * event
+     *
+     * @param id
+     * @param channel
+     * @private
+     */
+    // noinspection JSUnusedLocalSymbols
+    onPortClose(id, channel) {
+        log.info(`main side of message channel(id=${id}) closed`);
+        this.closeMessageChannel(id, channel);
     }
-    async kill() {
-        if (!this.readyDeferred_) {
-            return;
-        }
-        let killDeferred = this.killDeferred_;
-        if (killDeferred) {
-            return killDeferred.promise;
+    /**
+     * Close a message channel
+     *
+     * @param id
+     * @param channel
+     * @private
+     */
+    closeMessageChannel(id, channel) {
+        if (this.messageChannels_.has(id)) {
+            this.messageChannels_.delete(id);
         }
-        if (!this.readyDeferred_.isSettled()) {
-            await this.readyDeferred_.promise.catch(err => log.error(`ignoring error`, err));
+        Array(channel.port1, channel.port2)
+            .forEach(p => {
+            getValue(() => p.close());
+        });
+    }
+    /**
+     * Kill the service
+     *
+     * @private
+     */
+    async kill() {
+        var _a, _b;
+        if (!this.readyDeferred_ ||
+            !this.readyDeferred_.isSettled() ||
+            !this.childProcess_ ||
+            this.killDeferred_) {
+            log.error("Service is not ready OR the process is not running");
+            // noinspection ES6MissingAwait
+            return (_b = (_a = this.killDeferred_) === null || _a === void 0 ? void 0 : _a.promise) !== null && _b !== void 0 ? _b : Promise.resolve(0);
         }
+        let killDeferred = this.killDeferred_ = new Deferred();
+        // GET THE PROCESS
         const process = this.childProcess_;
-        if (!process) {
-            log.error("The process is not running");
-            return 0;
-        }
+        // CANCEL ALL PENDING MESSAGES & REMOVE ALL CHANNELS
         this.cancelAllPendingMessages();
         this.removeAllMessageChannels();
-        killDeferred = this.killDeferred_ = new Deferred();
         try {
-            process.once("exit", (code) => {
-                if (code !== 0) {
-                    log.error(`Process exited with code ${code} upon stopping`);
-                }
-                killDeferred.resolve(code);
-            });
             process.kill();
         }
         catch (err) {
@@ -214,33 +292,33 @@ export class UPMMainService {
         }
         return await killDeferred.promise;
     }
+    /**
+     * Close all message channels
+     *
+     * @private
+     */
     removeAllMessageChannels() {
         for (const [id, channel] of [...this.messageChannels_.entries()]) {
             this.closeMessageChannel(id, channel);
         }
     }
+    /**
+     * Remove all pending messages
+     *
+     * @private
+     */
     cancelAllPendingMessages() {
         for (const key of [...this.pendingMessages_.keys()]) {
             this.removePendingMessage(key);
         }
     }
-    constructor(serviceName, entryFile, options = {}) {
-        this.serviceName = serviceName;
-        this.entryFile = entryFile;
-        this.clientId = "main";
-        this.readyDeferred_ = null;
-        this.killDeferred_ = null;
-        this.lastMessageId_ = 0;
-        this.childProcess_ = null;
-        this.pendingMessages_ = new Map();
-        this.messageChannels_ = new Map();
-        //super()
-        assert(isString(entryFile) && isNotEmpty(entryFile) && Fsx.existsSync(entryFile), `entry file must be provided (${entryFile})`);
-        this.config_ = Object.assign({}, options);
-        this.init().catch(err => {
-            log.error(`Failed to init utility process`, err);
-        });
-    }
+    /**
+     * Remove a pending message from the queue,
+     * whether settled or not
+     *
+     * @param messageId
+     * @private
+     */
     removePendingMessage(messageId) {
         const pending = this.pendingMessages_.get(messageId);
         if (!pending) {
@@ -252,11 +330,46 @@ export class UPMMainService {
         }
         this.pendingMessages_.delete(messageId);
     }
+    /**
+     * Generate next message id
+     *
+     * @private
+     */
     generateMessageId() {
-        return this.lastMessageId_++;
+        return this.messageIdSeq_++;
     }
-    async [Symbol.asyncDispose]() {
-        await this.stop();
+    /**
+     * Construct a new service
+     *
+     * @param serviceName
+     * @param entryFile
+     * @param options
+     */
+    constructor(serviceName, entryFile, options = {}) {
+        this.serviceName = serviceName;
+        this.entryFile = entryFile;
+        /**
+         * As this container/wrapper implements
+         * `IMessageClient`, it needs to provide
+         * a `clientId`, which is constant in the
+         * main process
+         */
+        this.clientId = "main";
+        this.readyDeferred_ = null;
+        this.killDeferred_ = null;
+        this.messageIdSeq_ = 0;
+        this.childProcess_ = null;
+        this.pendingMessages_ = new Map();
+        this.messageChannels_ = new Map();
+        assert(isString(entryFile) &&
+            isNotEmpty(entryFile) &&
+            Fsx.existsSync(entryFile), `entry file must be provided (${entryFile})`);
+        this.config_ = defaults(Object.assign({}, options), {
+            serviceName, inspect: false
+        });
+        this.init().catch(err => {
+            log.error(`Failed to init utility process`, err);
+        });
     }
 }
 export default UPMMainService;