@thalesrc/hermes 7.3.0 → 7.5.1

package/worker/message-host.cjs

@@ -3,39 +3,161 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkerMessageHost = void 0;
 const rxjs_1 = require("rxjs");
 const message_host_1 = require("../message-host");
-const REQUESTS$ = Symbol('Requests');
-const HANDLER = Symbol('Handler');
-const WORKER = Symbol('Worker');
+const selectors_1 = require("../selectors");
+const initializer_1 = require("./initializer");
+const noop_1 = require("@thalesrc/js-utils/function/noop");
+const WORKER = Symbol('Host Worker');
+const HANDLER = Symbol('Host Message Handler');
+const REQUESTS$ = Symbol('Host Requests Stream');
+/**
+ * WorkerMessageHost
+ *
+ * Host implementation for Web Worker communication. Receives messages from and sends
+ * responses to Web Workers using the Worker postMessage API.
+ *
+ * This class can be used in two contexts:
+ * - **Main thread**: Provide a Worker instance to receive messages from that specific worker
+ * - **Worker thread**: Omit the worker parameter to receive messages from the main thread via self
+ *
+ * The worker parameter supports multiple types for flexibility:
+ * - Direct Worker instance
+ * - Promise that resolves to a Worker (for async worker initialization)
+ * - Function that returns a Worker (for lazy initialization)
+ * - Function that returns a Promise<Worker> (for async lazy initialization)
+ *
+ * The `initialize()` method allows dynamic worker management, enabling you to switch
+ * workers at runtime or re-establish connections after errors.
+ *
+ * @example
+ * // In main thread - receive messages from a specific worker
+ * const worker = new Worker('./worker.js');
+ * const host = new WorkerMessageHost(worker);
+ *
+ * @example
+ * // In worker thread - receive messages from main thread
+ * const host = new WorkerMessageHost();
+ *
+ * @example
+ * // With async worker initialization
+ * const workerPromise = import('./worker.js').then(m => new m.MyWorker());
+ * const host = new WorkerMessageHost(workerPromise);
+ *
+ * @example
+ * // With lazy initialization
+ * const host = new WorkerMessageHost(() =>
+ *   document.querySelector('[data-worker]') ? new Worker('./worker.js') : undefined
+ * );
+ *
+ * @example
+ * // Re-initialize with a different worker
+ * const host = new WorkerMessageHost();
+ * // Later, switch to a different worker
+ * host.initialize(new Worker('./different-worker.js'));
+ */
 class WorkerMessageHost extends message_host_1.MessageHost {
+    /**
+     * Observable stream of incoming messages from the worker or main thread
+     * @private
+     */
     [REQUESTS$] = new rxjs_1.Subject();
-    [WORKER];
+    /**
+     * Promise resolving to the Worker instance or undefined if running in worker context
+     * @private
+     */
+    [WORKER] = Promise.resolve(undefined);
+    /**
+     * Creates a new WorkerMessageHost instance
+     *
+     * @param worker - Optional worker configuration:
+     *   - Worker: Direct worker instance (main thread)
+     *   - Promise<Worker>: Promise resolving to worker (async initialization)
+     *   - () => Worker: Function returning worker (lazy initialization)
+     *   - () => Promise<Worker>: Function returning promise (async lazy initialization)
+     *   - undefined: Omit for worker thread context (uses self)
+     */
     constructor(worker) {
         super();
-        if (worker) {
-            this[WORKER] = worker;
-            worker.addEventListener('message', this[HANDLER]);
-        }
-        else {
-            addEventListener('message', this[HANDLER]);
-        }
-        this.listen(this[REQUESTS$]);
+        this.initialize(worker);
+        this[selectors_1.LISTEN](this[REQUESTS$]);
     }
-    response(message) {
-        if (this[WORKER]) {
-            this[WORKER].postMessage(message);
-        }
-        else {
-            postMessage(message);
+    /**
+     * Initializes or re-initializes the worker connection.
+     *
+     * This method sets up message listeners for the provided worker. If a worker
+     * was previously initialized, it cleans up the old connection before establishing
+     * the new one. This allows for dynamic worker management, such as:
+     * - Switching between different workers at runtime
+     * - Re-establishing connections after worker errors
+     * - Lazy initialization when the worker is conditionally needed
+     *
+     * @param worker - Optional worker configuration:
+     *   - Worker: Direct worker instance (main thread)
+     *   - Promise<Worker>: Promise resolving to worker (async initialization)
+     *   - () => Worker: Function returning worker (lazy initialization)
+     *   - () => Promise<Worker>: Function returning promise (async lazy initialization)
+     *   - undefined: Omit for worker thread context (uses self)
+     *
+     * @example
+     * // Switch to a different worker dynamically
+     * const host = new WorkerMessageHost(oldWorker);
+     * host.initialize(newWorker); // Cleans up old listener, sets up new one
+     *
+     * @example
+     * // Re-initialize after worker error
+     * worker.onerror = () => {
+     *   host.initialize(new Worker('./worker.js'));
+     * };
+     */
+    initialize(worker) {
+        // Ensure WORKER is initialized if not already
+        if (!this[WORKER]) {
+            this[WORKER] = Promise.resolve(undefined);
         }
+        this[WORKER] = (0, initializer_1.initializer)(this[WORKER], worker, this[HANDLER]);
     }
+    /**
+     * Sends a response message back to the worker or main thread
+     *
+     * @param message - The response message to send
+     * @internal Used by the message handling system to send responses
+     */
+    [selectors_1.RESPONSE](message) {
+        this[WORKER].then(worker => {
+            if (worker) {
+                worker.postMessage(message);
+            }
+            else {
+                postMessage(message);
+            }
+        }).catch(noop_1.noop);
+    }
+    /**
+     * Terminates the worker connection and cleans up message listeners.
+     *
+     * This method should be called when you're done with the host to prevent memory leaks.
+     * It removes the message event listener from either the Worker instance (main thread)
+     * or the global scope (worker thread).
+     *
+     * @example
+     * // Clean up when done
+     * const host = new WorkerMessageHost(worker);
+     * // ... use the host ...
+     * host.terminate(); // Clean up listeners
+     */
     terminate() {
-        if (this[WORKER]) {
-            this[WORKER].removeEventListener('message', this[HANDLER]);
-        }
-        else {
-            removeEventListener('message', this[HANDLER]);
-        }
+        this[WORKER].then(worker => {
+            if (worker) {
+                worker.removeEventListener('message', this[HANDLER]);
+            }
+            else {
+                removeEventListener('message', this[HANDLER]);
+            }
+        }).catch(noop_1.noop);
     }
+    /**
+     * Handles incoming messages and forwards them to the requests stream
+     * @private
+     */
     [HANDLER] = (event) => {
         this[REQUESTS$].next(event.data);
     };

package/worker/message-host.d.ts

@@ -1,14 +1,131 @@
 import { MessageHost } from "../message-host";
 import { MessageResponse } from "../message-response.type";
-declare const REQUESTS$: unique symbol;
-declare const HANDLER: unique symbol;
+import { RESPONSE } from "../selectors";
+import { ClientWorkerArg } from "./initializer";
 declare const WORKER: unique symbol;
+declare const HANDLER: unique symbol;
+declare const REQUESTS$: unique symbol;
+/**
+ * WorkerMessageHost
+ *
+ * Host implementation for Web Worker communication. Receives messages from and sends
+ * responses to Web Workers using the Worker postMessage API.
+ *
+ * This class can be used in two contexts:
+ * - **Main thread**: Provide a Worker instance to receive messages from that specific worker
+ * - **Worker thread**: Omit the worker parameter to receive messages from the main thread via self
+ *
+ * The worker parameter supports multiple types for flexibility:
+ * - Direct Worker instance
+ * - Promise that resolves to a Worker (for async worker initialization)
+ * - Function that returns a Worker (for lazy initialization)
+ * - Function that returns a Promise<Worker> (for async lazy initialization)
+ *
+ * The `initialize()` method allows dynamic worker management, enabling you to switch
+ * workers at runtime or re-establish connections after errors.
+ *
+ * @example
+ * // In main thread - receive messages from a specific worker
+ * const worker = new Worker('./worker.js');
+ * const host = new WorkerMessageHost(worker);
+ *
+ * @example
+ * // In worker thread - receive messages from main thread
+ * const host = new WorkerMessageHost();
+ *
+ * @example
+ * // With async worker initialization
+ * const workerPromise = import('./worker.js').then(m => new m.MyWorker());
+ * const host = new WorkerMessageHost(workerPromise);
+ *
+ * @example
+ * // With lazy initialization
+ * const host = new WorkerMessageHost(() =>
+ *   document.querySelector('[data-worker]') ? new Worker('./worker.js') : undefined
+ * );
+ *
+ * @example
+ * // Re-initialize with a different worker
+ * const host = new WorkerMessageHost();
+ * // Later, switch to a different worker
+ * host.initialize(new Worker('./different-worker.js'));
+ */
 export declare class WorkerMessageHost extends MessageHost {
+    /**
+     * Observable stream of incoming messages from the worker or main thread
+     * @private
+     */
     private [REQUESTS$];
+    /**
+     * Promise resolving to the Worker instance or undefined if running in worker context
+     * @private
+     */
     private [WORKER];
+    /**
+     * Creates a new WorkerMessageHost instance
+     *
+     * @param worker - Optional worker configuration:
+     *   - Worker: Direct worker instance (main thread)
+     *   - Promise<Worker>: Promise resolving to worker (async initialization)
+     *   - () => Worker: Function returning worker (lazy initialization)
+     *   - () => Promise<Worker>: Function returning promise (async lazy initialization)
+     *   - undefined: Omit for worker thread context (uses self)
+     */
     constructor(worker?: Worker);
-    protected response(message: MessageResponse): void;
+    /**
+     * Initializes or re-initializes the worker connection.
+     *
+     * This method sets up message listeners for the provided worker. If a worker
+     * was previously initialized, it cleans up the old connection before establishing
+     * the new one. This allows for dynamic worker management, such as:
+     * - Switching between different workers at runtime
+     * - Re-establishing connections after worker errors
+     * - Lazy initialization when the worker is conditionally needed
+     *
+     * @param worker - Optional worker configuration:
+     *   - Worker: Direct worker instance (main thread)
+     *   - Promise<Worker>: Promise resolving to worker (async initialization)
+     *   - () => Worker: Function returning worker (lazy initialization)
+     *   - () => Promise<Worker>: Function returning promise (async lazy initialization)
+     *   - undefined: Omit for worker thread context (uses self)
+     *
+     * @example
+     * // Switch to a different worker dynamically
+     * const host = new WorkerMessageHost(oldWorker);
+     * host.initialize(newWorker); // Cleans up old listener, sets up new one
+     *
+     * @example
+     * // Re-initialize after worker error
+     * worker.onerror = () => {
+     *   host.initialize(new Worker('./worker.js'));
+     * };
+     */
+    initialize(worker: ClientWorkerArg): void;
+    /**
+     * Sends a response message back to the worker or main thread
+     *
+     * @param message - The response message to send
+     * @internal Used by the message handling system to send responses
+     */
+    protected [RESPONSE](message: MessageResponse): void;
+    /**
+     * Terminates the worker connection and cleans up message listeners.
+     *
+     * This method should be called when you're done with the host to prevent memory leaks.
+     * It removes the message event listener from either the Worker instance (main thread)
+     * or the global scope (worker thread).
+     *
+     * @example
+     * // Clean up when done
+     * const host = new WorkerMessageHost(worker);
+     * // ... use the host ...
+     * host.terminate(); // Clean up listeners
+     */
     terminate(): void;
+    /**
+     * Handles incoming messages and forwards them to the requests stream
+     * @private
+     */
     private [HANDLER];
 }
 export {};

package/worker/message-host.js

@@ -1,38 +1,160 @@
 import { Subject } from "rxjs";
 import { MessageHost } from "../message-host";
-const REQUESTS$ = Symbol('Requests');
-const HANDLER = Symbol('Handler');
-const WORKER = Symbol('Worker');
+import { LISTEN, RESPONSE } from "../selectors";
+import { initializer } from "./initializer";
+import { noop } from "@thalesrc/js-utils/function/noop";
+const WORKER = Symbol('Host Worker');
+const HANDLER = Symbol('Host Message Handler');
+const REQUESTS$ = Symbol('Host Requests Stream');
+/**
+ * WorkerMessageHost
+ *
+ * Host implementation for Web Worker communication. Receives messages from and sends
+ * responses to Web Workers using the Worker postMessage API.
+ *
+ * This class can be used in two contexts:
+ * - **Main thread**: Provide a Worker instance to receive messages from that specific worker
+ * - **Worker thread**: Omit the worker parameter to receive messages from the main thread via self
+ *
+ * The worker parameter supports multiple types for flexibility:
+ * - Direct Worker instance
+ * - Promise that resolves to a Worker (for async worker initialization)
+ * - Function that returns a Worker (for lazy initialization)
+ * - Function that returns a Promise<Worker> (for async lazy initialization)
+ *
+ * The `initialize()` method allows dynamic worker management, enabling you to switch
+ * workers at runtime or re-establish connections after errors.
+ *
+ * @example
+ * // In main thread - receive messages from a specific worker
+ * const worker = new Worker('./worker.js');
+ * const host = new WorkerMessageHost(worker);
+ *
+ * @example
+ * // In worker thread - receive messages from main thread
+ * const host = new WorkerMessageHost();
+ *
+ * @example
+ * // With async worker initialization
+ * const workerPromise = import('./worker.js').then(m => new m.MyWorker());
+ * const host = new WorkerMessageHost(workerPromise);
+ *
+ * @example
+ * // With lazy initialization
+ * const host = new WorkerMessageHost(() =>
+ *   document.querySelector('[data-worker]') ? new Worker('./worker.js') : undefined
+ * );
+ *
+ * @example
+ * // Re-initialize with a different worker
+ * const host = new WorkerMessageHost();
+ * // Later, switch to a different worker
+ * host.initialize(new Worker('./different-worker.js'));
+ */
 export class WorkerMessageHost extends MessageHost {
+    /**
+     * Observable stream of incoming messages from the worker or main thread
+     * @private
+     */
     [REQUESTS$] = new Subject();
-    [WORKER];
+    /**
+     * Promise resolving to the Worker instance or undefined if running in worker context
+     * @private
+     */
+    [WORKER] = Promise.resolve(undefined);
+    /**
+     * Creates a new WorkerMessageHost instance
+     *
+     * @param worker - Optional worker configuration:
+     *   - Worker: Direct worker instance (main thread)
+     *   - Promise<Worker>: Promise resolving to worker (async initialization)
+     *   - () => Worker: Function returning worker (lazy initialization)
+     *   - () => Promise<Worker>: Function returning promise (async lazy initialization)
+     *   - undefined: Omit for worker thread context (uses self)
+     */
     constructor(worker) {
         super();
-        if (worker) {
-            this[WORKER] = worker;
-            worker.addEventListener('message', this[HANDLER]);
-        }
-        else {
-            addEventListener('message', this[HANDLER]);
-        }
-        this.listen(this[REQUESTS$]);
+        this.initialize(worker);
+        this[LISTEN](this[REQUESTS$]);
     }
-    response(message) {
-        if (this[WORKER]) {
-            this[WORKER].postMessage(message);
-        }
-        else {
-            postMessage(message);
+    /**
+     * Initializes or re-initializes the worker connection.
+     *
+     * This method sets up message listeners for the provided worker. If a worker
+     * was previously initialized, it cleans up the old connection before establishing
+     * the new one. This allows for dynamic worker management, such as:
+     * - Switching between different workers at runtime
+     * - Re-establishing connections after worker errors
+     * - Lazy initialization when the worker is conditionally needed
+     *
+     * @param worker - Optional worker configuration:
+     *   - Worker: Direct worker instance (main thread)
+     *   - Promise<Worker>: Promise resolving to worker (async initialization)
+     *   - () => Worker: Function returning worker (lazy initialization)
+     *   - () => Promise<Worker>: Function returning promise (async lazy initialization)
+     *   - undefined: Omit for worker thread context (uses self)
+     *
+     * @example
+     * // Switch to a different worker dynamically
+     * const host = new WorkerMessageHost(oldWorker);
+     * host.initialize(newWorker); // Cleans up old listener, sets up new one
+     *
+     * @example
+     * // Re-initialize after worker error
+     * worker.onerror = () => {
+     *   host.initialize(new Worker('./worker.js'));
+     * };
+     */
+    initialize(worker) {
+        // Ensure WORKER is initialized if not already
+        if (!this[WORKER]) {
+            this[WORKER] = Promise.resolve(undefined);
         }
+        this[WORKER] = initializer(this[WORKER], worker, this[HANDLER]);
     }
+    /**
+     * Sends a response message back to the worker or main thread
+     *
+     * @param message - The response message to send
+     * @internal Used by the message handling system to send responses
+     */
+    [RESPONSE](message) {
+        this[WORKER].then(worker => {
+            if (worker) {
+                worker.postMessage(message);
+            }
+            else {
+                postMessage(message);
+            }
+        }).catch(noop);
+    }
+    /**
+     * Terminates the worker connection and cleans up message listeners.
+     *
+     * This method should be called when you're done with the host to prevent memory leaks.
+     * It removes the message event listener from either the Worker instance (main thread)
+     * or the global scope (worker thread).
+     *
+     * @example
+     * // Clean up when done
+     * const host = new WorkerMessageHost(worker);
+     * // ... use the host ...
+     * host.terminate(); // Clean up listeners
+     */
     terminate() {
-        if (this[WORKER]) {
-            this[WORKER].removeEventListener('message', this[HANDLER]);
-        }
-        else {
-            removeEventListener('message', this[HANDLER]);
-        }
+        this[WORKER].then(worker => {
+            if (worker) {
+                worker.removeEventListener('message', this[HANDLER]);
+            }
+            else {
+                removeEventListener('message', this[HANDLER]);
+            }
+        }).catch(noop);
     }
+    /**
+     * Handles incoming messages and forwards them to the requests stream
+     * @private
+     */
     [HANDLER] = (event) => {
         this[REQUESTS$].next(event.data);
     };

package/worker/message-host.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../libs/hermes/src/worker/message-host.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAQ9C,MAAM,SAAS,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;AACrC,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;AAClC,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;AAEhC,MAAM,OAAO,iBAAkB,SAAQ,WAAW;IACxC,CAAC,SAAS,CAAC,GAAG,IAAI,OAAO,EAAW,CAAC;IACrC,CAAC,MAAM,CAAC,CAAqB;IAErC,YAAY,MAAe;QACzB,KAAK,EAAE,CAAC;QAER,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;YACtB,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QACpD,CAAC;aAAM,CAAC;YACN,gBAAgB,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7C,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAC/B,CAAC;IAES,QAAQ,CAAC,OAAwB;QACzC,IAAI,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACjB,IAAI,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC;aAAM,CAAC;YACL,WAAmB,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAEM,SAAS;QACd,IAAI,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACjB,IAAI,CAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7D,CAAC;aAAM,CAAC;YACN,mBAAmB,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAEO,CAAC,OAAO,CAAC,GAAG,CAAC,KAA4B,EAAE,EAAE;QACnD,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC,CAAA;CACF","file":"message-host.js","sourcesContent":["import { Subject } from \"rxjs\";\nimport { MessageHost } from \"../message-host\";\nimport { MessageResponse } from \"../message-response.type\";\nimport { Message } from \"../message.interface\";\n\ninterface MessageEvent<T> {\n  data: T;\n}\n\nconst REQUESTS$ = Symbol('Requests');\nconst HANDLER = Symbol('Handler');\nconst WORKER = Symbol('Worker');\n\nexport class WorkerMessageHost extends MessageHost {\n  private [REQUESTS$] = new Subject<Message>();\n  private [WORKER]: Worker | undefined;\n\n  constructor(worker?: Worker) {\n    super();\n\n    if (worker) {\n      this[WORKER] = worker;\n      worker.addEventListener('message', this[HANDLER]);\n    } else {\n      addEventListener('message', this[HANDLER]);\n    }\n\n    this.listen(this[REQUESTS$]);\n  }\n\n  protected response(message: MessageResponse) {\n    if (this[WORKER]) {\n      this[WORKER].postMessage(message);\n    } else {\n      (postMessage as any)(message);\n    }\n  }\n\n  public terminate() {\n    if (this[WORKER]) {\n      this[WORKER].removeEventListener('message', this[HANDLER]);\n    } else {\n      removeEventListener('message', this[HANDLER]);\n    }\n  }\n\n  private [HANDLER] = (event: MessageEvent<Message>) => {\n    this[REQUESTS$].next(event.data);\n  }\n}\n"]}
+{"version":3,"sources":["../../../../../libs/hermes/src/worker/message-host.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAwC,WAAW,EAAE,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,IAAI,EAAE,MAAM,kCAAkC,CAAC;AAExD,MAAM,MAAM,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;AACrC,MAAM,OAAO,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAC/C,MAAM,SAAS,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,OAAO,iBAAkB,SAAQ,WAAW;IAChD;;;OAGG;IACK,CAAC,SAAS,CAAC,GAAG,IAAI,OAAO,EAAW,CAAC;IAE7C;;;OAGG;IACK,CAAC,MAAM,CAAC,GAAwB,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEnE;;;;;;;;;OASG;IACH,YAAY,MAAe;QACzB,KAAK,EAAE,CAAC;QAER,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,UAAU,CAAC,MAAuB;QAChC,8CAA8C;QAC9C,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAClB,IAAI,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC5C,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,GAAG,WAAW,CACxB,IAAI,CAAC,MAAM,CAAC,EACZ,MAAM,EACN,IAAI,CAAC,OAAO,CAAC,CACd,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACO,CAAC,QAAQ,CAAC,CAAC,OAAwB;QAC3C,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE;YACzB,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YAC9B,CAAC;iBAAM,CAAC;gBACL,WAAmB,CAAC,OAAO,CAAC,CAAC;YAChC,CAAC;QACH,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IAED;;;;;;;;;;;;OAYG;IACI,SAAS;QACd,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE;YACzB,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YACvD,CAAC;iBAAM,CAAC;gBACN,mBAAmB,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YAChD,CAAC;QACH,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IAED;;;OAGG;IACK,CAAC,OAAO,CAAC,GAAG,CAAC,KAA4B,EAAE,EAAE;QACnD,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC,CAAC;CACH","file":"message-host.js","sourcesContent":["import { Subject } from \"rxjs\";\nimport { MessageHost } from \"../message-host\";\nimport { MessageResponse } from \"../message-response.type\";\nimport { Message } from \"../message.interface\";\nimport { LISTEN, RESPONSE } from \"../selectors\";\nimport { ClientWorkerArg, ClientWorkerPromise, initializer } from \"./initializer\";\nimport { noop } from \"@thalesrc/js-utils/function/noop\";\n\nconst WORKER = Symbol('Host Worker');\nconst HANDLER = Symbol('Host Message Handler');\nconst REQUESTS$ = Symbol('Host Requests Stream');\n\n/**\n * WorkerMessageHost\n *\n * Host implementation for Web Worker communication. Receives messages from and sends\n * responses to Web Workers using the Worker postMessage API.\n *\n * This class can be used in two contexts:\n * - **Main thread**: Provide a Worker instance to receive messages from that specific worker\n * - **Worker thread**: Omit the worker parameter to receive messages from the main thread via self\n *\n * The worker parameter supports multiple types for flexibility:\n * - Direct Worker instance\n * - Promise that resolves to a Worker (for async worker initialization)\n * - Function that returns a Worker (for lazy initialization)\n * - Function that returns a Promise<Worker> (for async lazy initialization)\n *\n * The `initialize()` method allows dynamic worker management, enabling you to switch\n * workers at runtime or re-establish connections after errors.\n *\n * @example\n * // In main thread - receive messages from a specific worker\n * const worker = new Worker('./worker.js');\n * const host = new WorkerMessageHost(worker);\n *\n * @example\n * // In worker thread - receive messages from main thread\n * const host = new WorkerMessageHost();\n *\n * @example\n * // With async worker initialization\n * const workerPromise = import('./worker.js').then(m => new m.MyWorker());\n * const host = new WorkerMessageHost(workerPromise);\n *\n * @example\n * // With lazy initialization\n * const host = new WorkerMessageHost(() =>\n *   document.querySelector('[data-worker]') ? new Worker('./worker.js') : undefined\n * );\n *\n * @example\n * // Re-initialize with a different worker\n * const host = new WorkerMessageHost();\n * // Later, switch to a different worker\n * host.initialize(new Worker('./different-worker.js'));\n */\nexport class WorkerMessageHost extends MessageHost {\n  /**\n   * Observable stream of incoming messages from the worker or main thread\n   * @private\n   */\n  private [REQUESTS$] = new Subject<Message>();\n\n  /**\n   * Promise resolving to the Worker instance or undefined if running in worker context\n   * @private\n   */\n  private [WORKER]: ClientWorkerPromise = Promise.resolve(undefined);\n\n  /**\n   * Creates a new WorkerMessageHost instance\n   *\n   * @param worker - Optional worker configuration:\n   *   - Worker: Direct worker instance (main thread)\n   *   - Promise<Worker>: Promise resolving to worker (async initialization)\n   *   - () => Worker: Function returning worker (lazy initialization)\n   *   - () => Promise<Worker>: Function returning promise (async lazy initialization)\n   *   - undefined: Omit for worker thread context (uses self)\n   */\n  constructor(worker?: Worker) {\n    super();\n\n    this.initialize(worker);\n    this[LISTEN](this[REQUESTS$]);\n  }\n\n  /**\n   * Initializes or re-initializes the worker connection.\n   *\n   * This method sets up message listeners for the provided worker. If a worker\n   * was previously initialized, it cleans up the old connection before establishing\n   * the new one. This allows for dynamic worker management, such as:\n   * - Switching between different workers at runtime\n   * - Re-establishing connections after worker errors\n   * - Lazy initialization when the worker is conditionally needed\n   *\n   * @param worker - Optional worker configuration:\n   *   - Worker: Direct worker instance (main thread)\n   *   - Promise<Worker>: Promise resolving to worker (async initialization)\n   *   - () => Worker: Function returning worker (lazy initialization)\n   *   - () => Promise<Worker>: Function returning promise (async lazy initialization)\n   *   - undefined: Omit for worker thread context (uses self)\n   *\n   * @example\n   * // Switch to a different worker dynamically\n   * const host = new WorkerMessageHost(oldWorker);\n   * host.initialize(newWorker); // Cleans up old listener, sets up new one\n   *\n   * @example\n   * // Re-initialize after worker error\n   * worker.onerror = () => {\n   *   host.initialize(new Worker('./worker.js'));\n   * };\n   */\n  initialize(worker: ClientWorkerArg) {\n    // Ensure WORKER is initialized if not already\n    if (!this[WORKER]) {\n      this[WORKER] = Promise.resolve(undefined);\n    }\n\n    this[WORKER] = initializer(\n      this[WORKER],\n      worker,\n      this[HANDLER]\n    );\n  }\n\n  /**\n   * Sends a response message back to the worker or main thread\n   *\n   * @param message - The response message to send\n   * @internal Used by the message handling system to send responses\n   */\n  protected [RESPONSE](message: MessageResponse) {\n    this[WORKER].then(worker => {\n      if (worker) {\n        worker.postMessage(message);\n      } else {\n        (postMessage as any)(message);\n      }\n    }).catch(noop);\n  }\n\n  /**\n   * Terminates the worker connection and cleans up message listeners.\n   *\n   * This method should be called when you're done with the host to prevent memory leaks.\n   * It removes the message event listener from either the Worker instance (main thread)\n   * or the global scope (worker thread).\n   *\n   * @example\n   * // Clean up when done\n   * const host = new WorkerMessageHost(worker);\n   * // ... use the host ...\n   * host.terminate(); // Clean up listeners\n   */\n  public terminate() {\n    this[WORKER].then(worker => {\n      if (worker) {\n        worker.removeEventListener('message', this[HANDLER]);\n      } else {\n        removeEventListener('message', this[HANDLER]);\n      }\n    }).catch(noop);\n  }\n\n  /**\n   * Handles incoming messages and forwards them to the requests stream\n   * @private\n   */\n  private [HANDLER] = (event: MessageEvent<Message>) => {\n    this[REQUESTS$].next(event.data);\n  };\n}\n"]}

package/worker/message-service.cjs

@@ -4,9 +4,120 @@ exports.WorkerMessageService = void 0;
 const mixin_1 = require("@thalesrc/js-utils/class/mixin");
 const message_client_1 = require("./message-client");
 const message_host_1 = require("./message-host");
+/**
+ * WorkerMessageService
+ *
+ * Bidirectional communication service for Web Workers that combines both client and host
+ * capabilities. This class extends both WorkerMessageClient and WorkerMessageHost through
+ * mixin composition, enabling full duplex communication - it can both send messages and
+ * respond to incoming requests simultaneously.
+ *
+ * This class is useful when you need a single instance to handle both:
+ * - **Sending messages**: Using the @Request decorator to call methods on the other side
+ * - **Receiving messages**: Using the @Response decorator to handle incoming requests
+ *
+ * Like its parent classes, this can be used in two contexts:
+ * - **Main thread**: Provide a Worker instance for bidirectional communication with that worker
+ * - **Worker thread**: Omit the worker parameter for bidirectional communication with main thread
+ *
+ * The worker parameter supports multiple types for flexibility:
+ * - Direct Worker instance
+ * - Promise that resolves to a Worker (for async worker initialization)
+ * - Function that returns a Worker (for lazy initialization)
+ * - Function that returns a Promise<Worker> (for async lazy initialization)
+ *
+ * @example
+ * // In main thread - full duplex communication with worker
+ * const worker = new Worker('./worker.js');
+ * const service = new WorkerMessageService(worker);
+ *
+ * class MainAPI extends WorkerMessageService {
+ *   // Send messages to worker
+ *   @Request()
+ *   fetchData(): Observable<Data> {
+ *     return null!;
+ *   }
+ *
+ *   // Respond to worker requests
+ *   @Listen()
+ *   saveToLocalStorage(data: any) {
+ *     localStorage.setItem('data', JSON.stringify(data));
+ *     return [];
+ *   }
+ * }
+ *
+ * @example
+ * // In worker thread - full duplex communication with main thread
+ * const service = new WorkerMessageService();
+ *
+ * class WorkerAPI extends WorkerMessageService {
+ *   // Respond to main thread requests
+ *   @Listen()
+ *   fetchData() {
+ *     return from(fetch('/api/data').then(r => r.json()));
+ *   }
+ *
+ *   // Send messages to main thread
+ *   @Request()
+ *   saveToLocalStorage(data: any): Observable<void> {
+ *     return null!;
+ *   }
+ * }
+ *
+ * @example
+ * // With async worker initialization
+ * const workerPromise = import('./worker.js').then(m => new m.MyWorker());
+ * const service = new WorkerMessageService(workerPromise);
+ *
+ * @example
+ * // Re-initialize with a different worker
+ * const service = new WorkerMessageService();
+ * // Later, switch to a different worker
+ * service.initialize(new Worker('./different-worker.js'));
+ */
 class WorkerMessageService extends (0, mixin_1.mixin)(message_host_1.WorkerMessageHost, message_client_1.WorkerMessageClient) {
+    /**
+     * Creates a new WorkerMessageService instance with bidirectional communication
+     *
+     * @param worker - Optional worker configuration:
+     *   - Worker: Direct worker instance (main thread)
+     *   - Promise<Worker>: Promise resolving to worker (async initialization)
+     *   - () => Worker: Function returning worker (lazy initialization)
+     *   - () => Promise<Worker>: Function returning promise (async lazy initialization)
+     *   - undefined: Omit for worker thread context (uses self)
+     */
     constructor(worker) {
         super([worker], [worker]);
+        this.initialize(worker);
     }
+    /**
+     * Initializes or re-initializes the worker connection for both client and host.
+     *
+     * This method sets up message listeners for both sending and receiving messages.
+     * If a worker was previously initialized, it cleans up the old connections before
+     * establishing new ones. This allows for dynamic worker management.
+     *
+     * @param worker - Optional worker configuration:
+     *   - Worker: Direct worker instance (main thread)
+     *   - Promise<Worker>: Promise resolving to worker (async initialization)
+     *   - () => Worker: Function returning worker (lazy initialization)
+     *   - () => Promise<Worker>: Function returning promise (async lazy initialization)
+     *   - undefined: Omit for worker thread context (uses self)
+     *
+     * @example
+     * // Switch to a different worker dynamically
+     * const service = new WorkerMessageService(oldWorker);
+     * service.initialize(newWorker); // Cleans up old listeners, sets up new ones
+     *
+     * @example
+     * // Re-initialize after worker error
+     * worker.onerror = () => {
+     *   service.initialize(new Worker('./worker.js'));
+     * };
+     */
+    initialize = (worker) => {
+        message_host_1.WorkerMessageHost.prototype.initialize.call(this, worker);
+        message_client_1.WorkerMessageClient.prototype.initialize.call(this, worker);
+    };
 }
 exports.WorkerMessageService = WorkerMessageService;