@3fv/electron-utility-process-manager 1.0.6 → 1.0.8

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@3fv/electron-utility-process-manager",
-  "version": "1.0.6",
+  "version": "1.0.8",
+  "packageManager": "pnpm@12.15.0",
   "description": "electron-utility-process-manager",
   "author": "Jonathan Glanz",
   "license": "MIT",
@@ -11,54 +12,91 @@
   "type": "commonjs",
   "main": "./lib/cjs/index.js",
   "module": "./lib/mjs/index.js",
-  "types": "./lib/mjs/index.d.ts",
+  "types": "./lib/cjs/index.d.ts",
   "exports": {
     ".": {
-      "types": "./lib/mjs/index.d.ts",
-      "node": "./lib/cjs/index.js",
-      "browser": "./lib/cjs/index.js",
-      "import": "./lib/mjs/index.js",
-      "require": "./lib/cjs/index.js"
+      "node": {
+        "types": "./lib/cjs/index.d.ts",
+        "default": "./lib/cjs/index.js"
+      },
+      "browser": {
+        "types": "./lib/cjs/index.d.ts",
+        "default": "./lib/cjs/index.js"
+      },
+      "import": {
+        "types": "./lib/mjs/index.d.ts",
+        "default": "./lib/mjs/index.js"
+      },
+      "require": {
+        "types": "./lib/cjs/index.d.ts",
+        "default": "./lib/cjs/index.js"
+      }
     },
     "./main": {
-      "types": "./lib/mjs/main/index.d.ts",
-      "node": "./lib/cjs/main/index.js",
-      "import": "./lib/mjs/main/index.js",
-      "require": "./lib/cjs/main/index.js"
+      "node": {
+        "types": "./lib/cjs/main/index.d.ts",
+        "default": "./lib/cjs/main/index.js"
+      },
+      "import": {
+        "types": "./lib/mjs/main/index.d.ts",
+        "default": "./lib/mjs/main/index.js"
+      },
+      "require": {
+        "types": "./lib/cjs/main/index.d.ts",
+        "default": "./lib/cjs/main/index.js"
+      }
     },
     "./renderer": {
-      "types": "./lib/mjs/renderer/index.d.ts",
-      "node": "./lib/cjs/renderer/index.js",
-      "browser": "./lib/cjs/renderer/index.js",
-      "import": "./lib/mjs/renderer/index.js",
-      "require": "./lib/cjs/renderer/index.js"
+      "node": {
+        "types": "./lib/cjs/renderer/index.d.ts",
+        "default": "./lib/cjs/renderer/index.js"
+      },
+      "browser": {
+        "types": "./lib/cjs/renderer/index.d.ts",
+        "default": "./lib/cjs/renderer/index.js"
+      },
+      "import": {
+        "types": "./lib/mjs/renderer/index.d.ts",
+        "default": "./lib/mjs/renderer/index.js"
+      },
+      "require": {
+        "types": "./lib/cjs/renderer/index.d.ts",
+        "default": "./lib/cjs/renderer/index.js"
+      }
     },
     "./node": {
-      "types": "./lib/mjs/node/index.d.ts",
-      "node": "./lib/cjs/node/index.js",
-      "import": "./lib/mjs/node/index.js",
-      "require": "./lib/cjs/node/index.js"
+      "node": {
+        "types": "./lib/cjs/node/index.d.ts",
+        "default": "./lib/cjs/node/index.js"
+      },
+      "import": {
+        "types": "./lib/mjs/node/index.d.ts",
+        "default": "./lib/mjs/node/index.js"
+      },
+      "require": {
+        "types": "./lib/cjs/node/index.d.ts",
+        "default": "./lib/cjs/node/index.js"
+      }
     }
   },
   "scripts": {
     "build": "node ./scripts/build.mjs",
-    "build:link": "yarn run build && yarn unlink;yarn link",
-    "build:watch": "run-s build:link && yarn run build --watch",
-    "test": "yarn run build && jest",
-    "test:watch": "yarn run build && jest --watchAll --no-cache",
+    "build:watch": "pnpm run build --watch",
+    "build:examples": "pnpm --filter @3fv/electron-utility-process-manager-examples run build",
+    "example": "node ./scripts/run-example.mjs",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watchAll --no-cache",
     "test:dev": "run-s build && run-p test:watch build:watch",
-    "preversion": "yarn build",
-    "preversion::with-tests": "yarn build && yarn test",
-    "clean": "./scripts/clean.sh",
-    "postversion": "node ./scripts/release.mjs latest",
-    "release": "yarn build  && yarn version --patch --non-interactive"
+    "preversion": "pnpm build",
+    "preversion::with-tests": "pnpm build && pnpm test",
+    "release": "gh workflow run release.yml --ref master -f bump=patch"
   },
   "publishConfig": {
     "access": "public"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/3fv/electron-utility-process-manager.git"
+    "url": "git+https://github.com/3fv/electron-utility-process-manager.git"
   },
   "keywords": [
     "typescript",
@@ -66,15 +104,15 @@
     "proxy"
   ],
   "files": [
-    "**/*.d.ts",
-    "**/*.js",
-    "**/*.map",
-    "package.json"
+    "lib",
+    "!lib/**/*.tsbuildinfo",
+    "src",
+    "README.md"
   ],
   "dependencies": {
-    "@3fv/deferred": "^1.2.12",
-    "@3fv/guard": "^1.4.38",
-    "@3fv/prelude-ts": "^0.8.32",
+    "@3fv/deferred": "^1.2.17",
+    "@3fv/guard": "^1.4.41",
+    "@3fv/prelude-ts": "^0.8.45",
     "chalk": "^5.3.0",
     "debug": "^4.3.6",
     "lodash": "^4.17.21",
@@ -82,20 +120,20 @@
     "ts-pattern": "^5.5.0"
   },
   "peerDependencies": {
-    "electron": "^31"
+    "electron": ">=31"
   },
   "devDependencies": {
     "@faker-js/faker": "^8.4.1",
     "@types/chalk": "^2.2.0",
     "@types/debug": "^4.1.12",
-    "@types/jest": "^29.5.12",
+    "@types/jest": "^30.0.0",
     "@types/lodash": "^4.17.7",
     "@types/node": "^22.9.0",
     "@types/shelljs": "^0.8.15",
     "cross-env": "^7.0.3",
-    "electron": "31.3.0",
+    "electron": "45.3.2",
     "electronmon": "^2.0.3",
-    "jest": "^29.7.0",
+    "jest": "^30.5.2",
     "lodash": "^4.17.21",
     "npm-run-all": "^4.1.5",
     "prettier": "^3.3.3",
@@ -103,9 +141,9 @@
     "shelljs": "^0.8.5",
     "source-map-support": "^0.5.21",
     "supports-color": "^9.4.0",
-    "ts-jest": "^29.2.4",
+    "ts-jest": "^29.4.15",
     "ts-node": "^10.9.2",
-    "typescript": "^5.5.4",
+    "typescript": "^6.0.3",
     "zx": "^8.1.4"
   }
 }

package/src/common/clients.ts

@@ -0,0 +1,276 @@
+import { isDefined, isFunction } from "@3fv/guard"
+import { isMessagePort, isUtilityProcess } from "./guards.js"
+import Tracer from "tracer"
+import {
+  Defaults,
+  IPCChannel,
+  Message, MessageKind, MessageRequestFn,
+  MessageRequestMap,
+  MessageRequestNames,
+  MessageRequestParams,
+  MessageRequestReturnType, NodeEnvelope, NodeMessage,
+  PendingRequestMessage, Port
+} from "./types.js"
+import { Deferred } from "@3fv/deferred"
+
+const log = Tracer.colorConsole()
+
+/**
+ * Service client interface maps a `MessageRequestMap`
+ * to its functional methods
+ */
+export type IServiceClient<
+  ReqMap extends MessageRequestMap,
+  MType extends MessageRequestNames<ReqMap> = MessageRequestNames<ReqMap>
+> = { [Type in MType]: MessageRequestFn<ReqMap, Type> }
+
+/**
+ * Messaging client interface
+ */
+export interface IMessageClient<
+  ReqMap extends MessageRequestMap,
+  MType extends MessageRequestNames<ReqMap> = MessageRequestNames<ReqMap>
+>
+{
+  
+  /**
+   * Get the clientId for the underlying port
+   */
+  get clientId(): string
+  
+  /**
+   * A very low level function for sending `any` data
+   * to the `utilityProcess`
+   *
+   * @param data
+   */
+  sendEvent(data: any): void
+  
+  /**
+   * Execute a request, with a response expected
+   *
+   * @param type
+   * @param args determined by the typed `MessageRequestMap` & `Type` parameters
+   */
+  executeRequest<
+    Type extends MType,
+    R extends MessageRequestReturnType<ReqMap, Type> = MessageRequestReturnType<ReqMap, Type>
+  >(
+    type: Type,
+    ...args: MessageRequestParams<ReqMap, Type>
+  ): Promise<R>
+  
+  /**
+   * Close the message client
+   */
+  close(): void
+  
+  /**
+   * Resolve when client is ready to use
+   */
+  whenReady(): Promise<IMessageClient<ReqMap, MType>>
+  
+  /**
+   * Get service client from message client
+   */
+  getServiceClient(): IServiceClient<ReqMap, MType>
+}
+
+/**
+ * Generic `MessagePort` client implementation, which
+ * is functional in any process.
+ *
+ * > NOTE: Aside from the main & renderer processes,
+ * >   an `utilityProcess` could potentially also
+ * >   use this client to communicate with a separate
+ * >   `utilityProcess`
+ */
+export class MessagePortClient<
+  ReqMap extends MessageRequestMap,
+  MType extends MessageRequestNames<ReqMap> = MessageRequestNames<ReqMap>
+> implements IMessageClient<ReqMap, MType> {
+  
+  /**
+   * Used to generate IDS
+   *
+   * @private
+   */
+  private idSequence_: number = 0
+  
+  /**
+   * A `Map` responsible for mapping `messageId`
+   * values to a `PendingRequestMessage`
+   *
+   * @private
+   */
+  private readonly pendingMessages_ = new Map<number, PendingRequestMessage>()
+  
+  /**
+   * Get the next `messageId`
+   *
+   * @returns {number}
+   * @private
+   */
+  private generateMessageId(): number {
+    return this.idSequence_++
+  }
+  
+  /**
+   * Remove a pending message mapping based on supplied ID
+   *
+   * @param {number} messageId
+   * @private
+   */
+  private removePendingMessage(messageId: number): void {
+    const pending = this.pendingMessages_.get(messageId)
+    if (!pending) {
+      return
+    }
+    clearTimeout(pending.timeoutId)
+    if (!pending.deferred.isSettled()) {
+      pending.deferred.reject("The pending message is being removed before promise is settled")
+    }
+    this.pendingMessages_.delete(messageId)
+  }
+  
+  /**
+   * Handle messages posted by the `utilityProcess` via
+   * either `process.parentPort` or a specific `MessagePort`
+   *
+   * @param payloadOrEnvelopeOrData
+   * @private
+   */
+  private onMessage<Type extends MType = any>(payloadOrEnvelopeOrData: any): void {
+    const
+      // FIND THE `Message | NodeMessage` DEPENDING
+      // ON THE PROCESS AND TRANSPORT
+      payloadOrEnvelope = (
+        isDefined(payloadOrEnvelopeOrData?.["data"]) ?
+          payloadOrEnvelopeOrData["data"] :
+          payloadOrEnvelopeOrData
+      ) as Message<ReqMap, Type> | NodeMessage<ReqMap, Type>,
+      
+      // FIND THE CHANNEL & PAYLOAD DEPENDING ON THE PROCESS & TRANSPORT
+      [channel, payload] =
+        (
+          isDefined(payloadOrEnvelope?.["payload"]) ?
+            [payloadOrEnvelope["channel"] ?? IPCChannel.UPMServiceMessage, payloadOrEnvelope["payload"]] :
+            [IPCChannel.UPMServiceMessage, payloadOrEnvelope]
+        ) as [string, Message<ReqMap, Type>],
+      { messageId, result, error } = 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
+      }
+      
+      if (!!error) {
+        log.error(error)
+        pending.deferred.reject(new Error(error))
+        return
+      }
+      pending.deferred.resolve(result)
+      this.removePendingMessage(messageId)
+    } catch (err) {
+      log.error(`Failed to handle message`, err)
+    }
+  }
+  
+  
+  sendEvent(data: any): void {
+    const messageId = this.generateMessageId()
+    const payload: NodeEnvelope = {
+      channel: IPCChannel.UPMServiceMessage,
+      payload: { messageId, eventData: data, kind: MessageKind.Event }
+    }
+    
+    this.port.postMessage(payload)
+  }
+  
+  async executeRequest<
+    Type extends MType,
+    R extends MessageRequestReturnType<ReqMap, Type> = MessageRequestReturnType<ReqMap, Type>
+  >(
+    type: Type,
+    ...args: MessageRequestParams<ReqMap, Type>
+  ): Promise<R> {
+    const messageId = this.generateMessageId(),
+      pending: PendingRequestMessage<ReqMap, Type, R> = {
+        deferred: new Deferred<R>(),
+        messageId,
+        timeoutId: setTimeout(() => this.removePendingMessage(messageId), Defaults.RequestTimeout)
+      }
+    
+    this.pendingMessages_.set(messageId, pending)
+    const payload: NodeMessage<ReqMap, Type> = {
+      channel: IPCChannel.UPMServiceMessage,
+      payload: { type, messageId, args, kind: MessageKind.Request }
+    }
+    
+    this.port.postMessage(payload)
+    
+    try {
+      const result = await pending.deferred.promise
+      log.debug(`Completed utility request (messageId=${messageId})`)
+      return result
+    } catch (err) {
+      log.error(`Failed utility request (messageId=${messageId})`, err)
+      throw err
+    }
+  }
+  
+  close(): void {
+  }
+  
+  whenReady(): Promise<this> {
+    return Promise.resolve(this)
+  }
+  
+  /**
+   * Return a simple proxy facade wrapping
+   * `executeRequest` into individual methods
+   */
+  getServiceClient(): IServiceClient<ReqMap, MType> {
+    return new Proxy<IServiceClient<ReqMap, MType>>({} as any, {
+      get: (_target, prop) => {
+        if (prop === "then") {
+          return undefined
+        }
+        return (...args: any[]) => this.whenReady()
+          .then(client => client.executeRequest(prop as MType, ...args as any))
+        
+      }
+    })
+  }
+  
+  /**
+   * Create a new `MessagePortClient`
+   *
+   * @param clientId
+   * @param port
+   */
+  constructor(readonly clientId: string, readonly port: Port) {
+    if (isMessagePort(port) || isUtilityProcess(port)) {
+      if (isFunction(port?.["addEventListener"])) {
+        ;(
+          port as any
+        ).addEventListener("message", this.onMessage.bind(this))
+      } else {
+        port.on("message", this.onMessage.bind(this))
+      }
+      if (isMessagePort(port))
+        port.start()
+    } else {
+      log.error("Invalid port", port)
+      throw new Error("Invalid port")
+    }
+    
+  }
+}

package/src/common/guards.ts

@@ -0,0 +1,11 @@
+import type { UtilityProcess } from "electron"
+import { isFunction } from "@3fv/guard"
+import { Port } from "./types.js"
+
+export function isMessagePort(port: Port): port is Electron.MessagePortMain {
+  return isFunction(port?.["close"])
+}
+
+export function isUtilityProcess(port: Port): port is UtilityProcess {
+  return !!port && !isMessagePort(port)
+}

package/src/common/index.ts

@@ -0,0 +1,3 @@
+export * from "./types.js"
+export * from "./guards.js"
+export * from "./clients.js"

package/src/common/types.ts

@@ -0,0 +1,106 @@
+import type { UtilityProcess } from "electron"
+import { Deferred } from "@3fv/deferred"
+
+
+export const Defaults = { RequestTimeout: 120000 }
+
+export enum MessageKind {
+  Event = "Event",
+  Request = "Request",
+  Response = "Response"
+}
+
+export enum IPCChannel {
+  UPMServiceMessage = "UPMServiceMessage",
+  UPMServiceNewClient = "UPMServiceNewClient"
+}
+
+export enum NodeMessageType {
+  UPMNodeEventMessage = "UPMNodeEventMessage",
+  UPMNodeRequestResponse = "UPMNodeRequestResponseMessage",
+}
+
+export type MessageRequestFnBase = (...args:any[]) => Promise<any>
+export type MessageRequestMap = {}
+export type MessageRequestNames<ReqMap extends MessageRequestMap> = keyof ReqMap
+export type MessageRequestFn<ReqMap extends MessageRequestMap, Name extends MessageRequestNames<ReqMap>> = ReqMap[Name] extends MessageRequestFnBase ? ReqMap[Name] : never
+export type MessageRequestParams<ReqMap extends MessageRequestMap, Name extends MessageRequestNames<ReqMap>> = ReqMap[Name] extends MessageRequestFnBase ? Parameters<ReqMap[Name]> : never
+export type MessageRequestReturnType<ReqMap extends MessageRequestMap, Name extends MessageRequestNames<ReqMap>> = ReqMap[Name] extends MessageRequestFnBase ? Awaited<ReturnType<ReqMap[Name]>> : never
+
+export interface Message<
+  ReqMap extends MessageRequestMap = any,
+  Type extends MessageRequestNames<ReqMap> = MessageRequestNames<ReqMap>,
+  Args extends MessageRequestParams<ReqMap, Type> = MessageRequestParams<ReqMap, Type>,
+  R extends MessageRequestReturnType<ReqMap, Type> = MessageRequestReturnType<ReqMap, Type>
+>
+{
+  type: Type;
+  kind: MessageKind;
+  messageId: number;
+  eventData?: any
+  args?: Args
+  result?: R
+  error?: string
+}
+
+export interface NodeEnvelope<Payload extends {} = any> {
+  channel: IPCChannel
+  payload: Payload
+}
+
+export type RequestHandler<
+  ReqMap extends MessageRequestMap = any,
+  Type extends MessageRequestNames<ReqMap> = MessageRequestNames<ReqMap>,
+  Args extends MessageRequestParams<ReqMap, Type> = MessageRequestParams<ReqMap, Type>,
+  R extends MessageRequestReturnType<ReqMap, Type> = MessageRequestReturnType<ReqMap, Type>
+> = (type: Type, messageId: number, ...args: Args) => Promise<R>
+
+
+export type NodeMessage<
+  ReqMap extends MessageRequestMap = any,
+  Type extends MessageRequestNames<ReqMap> = MessageRequestNames<ReqMap>> = NodeEnvelope<Message<ReqMap, Type>>
+
+export interface PendingRequestMessage<
+  ReqMap extends MessageRequestMap = any,
+  Type extends MessageRequestNames<ReqMap> = MessageRequestNames<ReqMap>,
+  R extends MessageRequestReturnType<ReqMap, Type> = MessageRequestReturnType<ReqMap, Type>
+>
+{
+  deferred: Deferred<R>
+  
+  timeoutId: ReturnType<typeof setTimeout>
+  
+  messageId: number
+}
+
+/**
+ * @returns true if payload was handled, false if not
+ */
+export type EventHandler = (clientId: string, port: Port, payload: any) => boolean
+
+/**
+ * Port of any kind
+ */
+export type Port = MessagePort | Electron.MessagePortMain | Electron.ParentPort | UtilityProcess
+
+/**
+ * Debugging & Inspection config
+ */
+export type ServiceInspectConfig = number | {
+  port: number
+  break?: boolean
+}
+
+/**
+ * Configuration to use when creating/launching
+ * a service (`Electron.UtilityProcess`)
+ */
+export interface CreateServiceConfig {
+  serviceName: string
+  inspect: false | ServiceInspectConfig
+}
+
+/**
+ * Optional/Partial `CreateServiceConfig`
+ */
+export type CreateServiceOptions = Partial<CreateServiceConfig>

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./common/index.js"
+import * as UPM from "./common/index.js"
+
+export {
+  UPM
+}
+
+export default UPM