tiny-essentials 1.28.18 → 1.29.0

package/dist/v1/libs/worker/engine/TinyWebWorkerEngine.cjs

@@ -0,0 +1,346 @@
+'use strict';
+
+var TinyPlugin = require('../../plugin/TinyPlugin.cjs');
+
+/**
+ * The data payload contained within the message.
+ * @typedef {any} MessagePayload
+ */
+
+/**
+ * A function that handles the actual postMessage call back to the main thread.
+ * @callback MessageApiReply
+ * @param {string} type - The type identifier for the api reply message.
+ * @param {MessagePayload} [data] - The payload to be sent in the api reply.
+ * @param {number} [timeout=10000] - Wait time.
+ * @returns {Promise<any>}
+ */
+
+/**
+ * @typedef {Object} ApiHandlerOptions
+ * @property {MessagePayload} [data] - The payload received from the main thread.
+ * @property {string} correlationId - The request ID.
+ */
+
+/**
+ * @callback ApiHandlerCallback
+ * @param {ApiHandlerOptions} options - Options for the API handler.
+ * @returns {Promise<MessagePayload|undefined> | (MessagePayload|undefined)} The response payload.
+ */
+
+/**
+ * An enriched message object containing the event and utility methods for responding.
+ * @typedef {Object} MessageObj
+ * @property {string} type - The identifier for the message type.
+ * @property {MessageEvent} event - The original message event.
+ * @property {MessagePayload} [data] - The payload sent within the message.
+ */
+
+/**
+ * A callback function executed when a registered message type is received.
+ * @callback MessageCallback
+ * @param {MessageObj} msg - The enriched message data object.
+ */
+
+/** @type {DedicatedWorkerGlobalScope} */
+// @ts-ignore
+const workerScope = self;
+
+/**
+ * The reserved message type used by the engine to announce that it is ready to receive messages.
+ * @type {string}
+ */
+const READY_EVENT_TYPE = 'ww:EngineReady';
+
+/**
+ * A function used to install a plugin into the engine.
+ * @template {TinyPluginLayer} Layer
+ * @template {string} IdString
+ * @template {string} VersionString
+ * @template {any[]} Options
+ * @typedef {import('../../plugin/TinyPlugin.mjs').TinyPluginInstaller<TinyWebWorkerEngine, Layer, IdString, VersionString, Options>} SwPluginInstaller
+ */
+
+/**
+ * Represents a plugin instance designed to be integrated into a TinyWebWorkerEngine.
+ * @template {TinyPluginLayer} Layer
+ * @template {string} IdString
+ * @template {string} VersionString
+ * @template {any[]} Options
+ * @typedef {TinyPlugin<TinyWebWorkerEngine, Layer, IdString, VersionString, Options>} TinyServiceWorkerPlugin
+ */
+
+/**
+ * Manages the lifecycle and execution of modules inside a Dedicated Web Worker.
+ */
+class TinyWebWorkerEngine extends TinyPlugin.TinyPluginCore {
+  /**
+   * Validates if an event type is a reserved name for the internal lifecycle.
+   * @param {string} type - The name of the event to validate.
+   * @throws {TypeError} If the event name is in the reserved list.
+   */
+  static #validateEventType(type) {
+    if (type.startsWith('ww:')) {
+      throw new TypeError(
+        `The event type "${type}" is reserved for internal Web Worker lifecycle management.`,
+      );
+    }
+  }
+
+  /** @type {Map<string, ApiHandlerCallback>} */
+  #apiHandlers = new Map();
+
+  /** @type {Map<string, MessageCallback>} */
+  #messages = new Map();
+
+  /** @type {Map<string, {resolve: (value: any) => void, reject: (reason: Error) => void, timer: NodeJS.Timeout}>} */
+  #pendingRequests = new Map();
+
+  /** @type {boolean} */
+  #started = false;
+
+  /**
+   * Indicates if the engine has been initialized.
+   * @returns {boolean} True if started, false otherwise.
+   */
+  get started() {
+    return this.#started;
+  }
+
+  /**
+   * Initializes a new instance of the TinyWebWorkerEngine.
+   * @param {Object} [lgConfig] - Configuration options for the instance.
+   * @param {boolean} [lgConfig.debugMode=false] - Whether to enable internal debug logging.
+   * @param {boolean} [lgConfig.useLogColors=false] - Whether to enable log color support.
+   * @param {Partial<Console>} [lgConfig.logger=console] - A custom logger object.
+   */
+  constructor(lgConfig = {}) {
+    super({
+      logCfg: {
+        id: '[_main_class_TinyWW-Engine_reset_]',
+        logger: lgConfig.logger ?? console,
+        debugMode: lgConfig.debugMode ?? false,
+        useLogColors: lgConfig.useLogColors ?? false,
+      },
+    });
+  }
+
+  /**
+   * Registers a handler for API calls coming from the main thread.
+   * @param {string} type - The identifier for the call.
+   * @param {ApiHandlerCallback} callback - Function that processes the request and returns a payload.
+   * @throws {TypeError} If callback is not a function.
+   */
+  onApi(type, callback) {
+    if (typeof callback !== 'function') throw new TypeError('Callback must be a function.');
+    this.#apiHandlers.set(type, callback);
+  }
+
+  /**
+   * Removes a registered API handler.
+   * @param {string} type - The identifier for the call.
+   * @returns {boolean} True if the handler was removed.
+   */
+  offApi(type) {
+    return this.#apiHandlers.delete(type);
+  }
+
+  /**
+   * Adds a message listener for unidirectional messages.
+   * @param {string} type - The identifier for the message type.
+   * @param {MessageCallback} callback - The callback to execute.
+   * @throws {TypeError} If callback is not a function.
+   */
+  addMessageListener(type, callback) {
+    if (typeof callback !== 'function') throw new TypeError('Callback must be a function.');
+    this.#messages.set(type, callback);
+  }
+
+  /**
+   * Removes a message listener.
+   * @param {string} type - The identifier for the message type.
+   * @returns {boolean} True if the listener was removed.
+   */
+  removeMessageListener(type) {
+    return this.#messages.delete(type);
+  }
+
+  /**
+   * Sends a unidirectional message to the main thread.
+   *
+   * Note: this intentionally reuses the `emit` name with a message-oriented
+   * signature. The rest parameter keeps it assignable to the inherited
+   * `EventEmitter.emit` contract.
+   *
+   * @override
+   * @param {string} type - The identifier for the message type.
+   * @param {...any} args - The data content (only the first argument is used).
+   * @returns {boolean} Always true when the message is dispatched.
+   * @throws {TypeError} If type is not a string or data is invalid.
+   */
+  emit(type, ...args) {
+    const data = args[0];
+    if (typeof type !== 'string') throw new TypeError('type must be a string.');
+    if (
+      typeof data !== 'undefined' &&
+      (Array.isArray(data) || typeof data !== 'object' || data === null)
+    ) {
+      throw new TypeError('data must be a non-null object.');
+    }
+
+    TinyWebWorkerEngine.#validateEventType(type);
+    workerScope.postMessage({ type, data });
+    return true;
+  }
+
+  /**
+   * Sends a request to the main thread and waits for a response.
+   * @param {string} type - The identifier for the call.
+   * @param {MessagePayload} [data] - The request payload.
+   * @param {number} [timeout=10000] - Maximum waiting time in milliseconds.
+   * @returns {Promise<any>} A promise that resolves with the result object.
+   * @throws {Error} If the timeout is reached.
+   */
+  async emitApi(type, data, timeout = 10000) {
+    const correlationId = crypto.randomUUID();
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (this.#pendingRequests.has(correlationId)) {
+          this.#pendingRequests.delete(correlationId);
+          reject(new Error(`API timeout: ${type}`));
+        }
+      }, timeout);
+
+      this.#pendingRequests.set(correlationId, { resolve, reject, timer });
+
+      workerScope.postMessage({
+        type,
+        data,
+        correlationId,
+        isApi: true,
+      });
+    });
+  }
+
+  /**
+   * Initializes the Web Worker event listeners.
+   * @returns {void}
+   * @throws {Error} If the engine has already been started.
+   */
+  init() {
+    if (this.#started) throw new Error('TinyWebWorkerEngine is already initialized.');
+
+    workerScope.addEventListener('message', (event) => {
+      const payload = event.data;
+
+      // Strict validation
+      if (Array.isArray(payload) || typeof payload !== 'object' || payload === null) return;
+      if (typeof payload.type !== 'string') return;
+      if (
+        typeof payload.data !== 'undefined' &&
+        (Array.isArray(payload.data) || typeof payload.data !== 'object' || payload.data === null)
+      )
+        return;
+
+      const { type, data, correlationId, isApi, error } = payload;
+
+      // 1. Handle API responses coming from the Main Thread
+      if (type === 'ww:ApiResponse') {
+        if (typeof correlationId !== 'string') {
+          this.log('error', 'Received API response with missing or invalid "correlationId".');
+          return;
+        }
+        const pending = this.#pendingRequests.get(correlationId);
+        if (pending) {
+          clearTimeout(pending.timer);
+          this.#pendingRequests.delete(correlationId);
+          if (error) {
+            pending.reject(new Error(error));
+          } else {
+            pending.resolve(data);
+          }
+        }
+        return;
+      }
+
+      // 2. Handle API calls coming from the Main Thread
+      if (isApi === true) {
+        if (typeof correlationId !== 'string') {
+          this.log('error', 'Received API request with missing or invalid "correlationId".');
+          return;
+        }
+
+        const handler = this.#apiHandlers.get(type);
+        if (!handler) {
+          workerScope.postMessage({
+            correlationId,
+            type: 'ww:ApiResponse',
+            error: `No API handler registered in worker for type: ${type}`,
+          });
+          return;
+        }
+
+        try {
+          /** @param {MessagePayload} [r] */
+          const sendResult = (r) =>
+            workerScope.postMessage({
+              correlationId,
+              type: 'ww:ApiResponse',
+              data: r,
+            });
+
+          const result = handler({
+            data,
+            correlationId,
+          });
+
+          if (result instanceof Promise) {
+            result.then(sendResult).catch((err) => {
+              workerScope.postMessage({
+                correlationId,
+                type: 'ww:ApiResponse',
+                error: err instanceof Error ? err.message : String(err),
+              });
+            });
+          } else {
+            sendResult(result);
+          }
+        } catch (err) {
+          workerScope.postMessage({
+            correlationId,
+            type: 'ww:ApiResponse',
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+        return;
+      }
+
+      // 3. Handle standard unidirectional messages
+      const messageHandler = this.#messages.get(type);
+
+      /** @type {MessageObj} */
+      const msgData = { type, event, data };
+      super.emit('beforeMessage', msgData);
+
+      if (messageHandler) {
+        try {
+          messageHandler(msgData);
+        } catch (err) {
+          this.log('error', `Error executing handler for message type "${type}":`, err);
+          super.emit('messageError', { type, error: err, data: msgData });
+        }
+      }
+      super.emit('afterMessage', msgData);
+    });
+
+    this.#started = true;
+    this.log('info', 'Web Worker Engine initialized.');
+
+    // NOTE: workerScope.postMessage is called directly on purpose.
+    // The public emit() method rejects every "ww:" prefixed type, and this signal is internal.
+    workerScope.postMessage({ type: READY_EVENT_TYPE });
+  }
+}
+
+module.exports = TinyWebWorkerEngine;

package/dist/v1/libs/worker/engine/TinyWebWorkerEngine.d.mts

@@ -0,0 +1,127 @@
+import { TinyPluginCore, TinyPlugin, TinyPluginLayer } from '../../plugin/TinyPlugin.mjs';
+export type MessagePayload = any;
+export type MessageApiReply = (type: string, data?: MessagePayload, timeout?: number) => Promise<any>;
+export type ApiHandlerOptions = {
+    /**
+     * - The payload received from the main thread.
+     */
+    data?: MessagePayload;
+    /**
+     * - The request ID.
+     */
+    correlationId: string;
+};
+export type ApiHandlerCallback = (options: ApiHandlerOptions) => Promise<MessagePayload | undefined> | (MessagePayload | undefined);
+export type MessageObj = {
+    /**
+     * - The identifier for the message type.
+     */
+    type: string;
+    /**
+     * - The original message event.
+     */
+    event: MessageEvent;
+    /**
+     * - The payload sent within the message.
+     */
+    data?: MessagePayload;
+};
+export type MessageCallback = (msg: MessageObj) => any;
+export type SwPluginInstaller<Layer extends TinyPluginLayer, IdString extends string, VersionString extends string, Options extends any[]> = import('../../plugin/TinyPlugin.mjs').TinyPluginInstaller<TinyWebWorkerEngine, Layer, IdString, VersionString, Options>;
+export type TinyServiceWorkerPlugin<Layer extends TinyPluginLayer, IdString extends string, VersionString extends string, Options extends any[]> = TinyPlugin<TinyWebWorkerEngine, Layer, IdString, VersionString, Options>;
+/**
+ * A function used to install a plugin into the engine.
+ * @template {TinyPluginLayer} Layer
+ * @template {string} IdString
+ * @template {string} VersionString
+ * @template {any[]} Options
+ * @typedef {import('../../plugin/TinyPlugin.mjs').TinyPluginInstaller<TinyWebWorkerEngine, Layer, IdString, VersionString, Options>} SwPluginInstaller
+ */
+/**
+ * Represents a plugin instance designed to be integrated into a TinyWebWorkerEngine.
+ * @template {TinyPluginLayer} Layer
+ * @template {string} IdString
+ * @template {string} VersionString
+ * @template {any[]} Options
+ * @typedef {TinyPlugin<TinyWebWorkerEngine, Layer, IdString, VersionString, Options>} TinyServiceWorkerPlugin
+ */
+/**
+ * Manages the lifecycle and execution of modules inside a Dedicated Web Worker.
+ */
+declare class TinyWebWorkerEngine extends TinyPluginCore {
+    #private;
+    /**
+     * Indicates if the engine has been initialized.
+     * @returns {boolean} True if started, false otherwise.
+     */
+    get started(): boolean;
+    /**
+     * Initializes a new instance of the TinyWebWorkerEngine.
+     * @param {Object} [lgConfig] - Configuration options for the instance.
+     * @param {boolean} [lgConfig.debugMode=false] - Whether to enable internal debug logging.
+     * @param {boolean} [lgConfig.useLogColors=false] - Whether to enable log color support.
+     * @param {Partial<Console>} [lgConfig.logger=console] - A custom logger object.
+     */
+    constructor(lgConfig?: {
+        debugMode?: boolean;
+        useLogColors?: boolean;
+        logger?: Partial<Console>;
+    });
+    /**
+     * Registers a handler for API calls coming from the main thread.
+     * @param {string} type - The identifier for the call.
+     * @param {ApiHandlerCallback} callback - Function that processes the request and returns a payload.
+     * @throws {TypeError} If callback is not a function.
+     */
+    onApi(type: string, callback: ApiHandlerCallback): void;
+    /**
+     * Removes a registered API handler.
+     * @param {string} type - The identifier for the call.
+     * @returns {boolean} True if the handler was removed.
+     */
+    offApi(type: string): boolean;
+    /**
+     * Adds a message listener for unidirectional messages.
+     * @param {string} type - The identifier for the message type.
+     * @param {MessageCallback} callback - The callback to execute.
+     * @throws {TypeError} If callback is not a function.
+     */
+    addMessageListener(type: string, callback: MessageCallback): void;
+    /**
+     * Removes a message listener.
+     * @param {string} type - The identifier for the message type.
+     * @returns {boolean} True if the listener was removed.
+     */
+    removeMessageListener(type: string): boolean;
+    /**
+     * Sends a unidirectional message to the main thread.
+     *
+     * Note: this intentionally reuses the `emit` name with a message-oriented
+     * signature. The rest parameter keeps it assignable to the inherited
+     * `EventEmitter.emit` contract.
+     *
+     * @override
+     * @param {string} type - The identifier for the message type.
+     * @param {...any} args - The data content (only the first argument is used).
+     * @returns {boolean} Always true when the message is dispatched.
+     * @throws {TypeError} If type is not a string or data is invalid.
+     */
+    emit(type: string, ...args: any[]): boolean;
+    /**
+     * Sends a request to the main thread and waits for a response.
+     * @param {string} type - The identifier for the call.
+     * @param {MessagePayload} [data] - The request payload.
+     * @param {number} [timeout=10000] - Maximum waiting time in milliseconds.
+     * @returns {Promise<any>} A promise that resolves with the result object.
+     * @throws {Error} If the timeout is reached.
+     */
+    emitApi(type: string, data?: MessagePayload, timeout?: number): Promise<any>;
+    /**
+     * Initializes the Web Worker event listeners.
+     * @returns {void}
+     * @throws {Error} If the engine has already been started.
+     */
+    init(): void;
+}
+export default TinyWebWorkerEngine;
+//# sourceMappingURL=TinyWebWorkerEngine.d.mts.map

package/dist/v1/libs/worker/engine/TinyWebWorkerEngine.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TinyWebWorkerEngine.d.mts","sourceRoot":"","sources":["../../../../../../src/v1/libs/worker/engine/TinyWebWorkerEngine.mjs"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAIvF,YAAe,cAAc,GAAnB,GAAG,CAAgB;AAK7B,YAAU,eAAe,GACzB,CAAgB,IAAI,EAAZ,MACR,EAAyB,IAAI,AAA7B,CACA,EADQ,cACR,EAAiB,OAAO,AAAxB,CACA,EADQ,MACR,KAAU,OAAO,CAAC,GAAG,CACvB,CAAA;AAGE,YAAkB,iBAAiB,GACnC;;;;IAA4B,IAAI,AAAhC,CACA,EADW,cAAc,CACzB;;;;IAAmB,aAAa,EAArB,MAAM,CACnB;CAAA,CAAA;AAGE,YAAU,kBAAkB,GAC5B,CAA2B,OAAO,EAA1B,iBACR,KAAU,OAAO,CAAC,cAAc,GAAC,SAAS,CAAC,GAAG,CAAC,cAAc,GAAC,SAAS,CACzE,CAAA;AAIE,YAAkB,UAAU,GAC5B;;;;IAAmB,IAAI,EAAZ,MAAM,CACjB;;;;IAAyB,KAAK,EAAnB,YAAY,CACvB;;;;IAA4B,IAAI,AAAhC,CACF,EADa,cAAc,CAC3B;CAAA,CAAA;AAIE,YAAU,eAAe,GACzB,CAAoB,GAAG,EAAf,UACV,QAAA,CAAA;AAkBE,YAAmI,iBAAiB,CAJxH,KAAK,SAAtB,eAAsB,EACd,QAAQ,SAAhB,MAAgB,EACR,aAAa,SAArB,MAAqB,EACd,OAAO,SAAd,GAAG,EAAW,IACf,OAAO,6BAA6B,EAAE,mBAAmB,CAAC,mBAAmB,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,CAAC,CAAmB;AASpJ,YAAoF,uBAAuB,CAJ/E,KAAK,SAAtB,eAAsB,EACd,QAAQ,SAAhB,MAAgB,EACR,aAAa,SAArB,MAAqB,EACd,OAAO,SAAd,GAAG,EAAW,IACf,UAAU,CAAC,mBAAmB,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,CAAC,CAAyB;AAf9G;;;;;;;GAOG;AAEH;;;;;;;GAOG;AAEH;;GAEG;AACH,cAAM,mBAAoB,SAAQ,cAAc;;IA0B9C;;;OAGG;IACH,IAAI,OAAO,IAFE,OAAO,CAInB;IAED;;;;;;OAMG;IACH,YAAY,QAAQ,AALjB,CAIF,EAHE;QAA2B,SAAS,AAApC,CACA,EADQ,OAAO,CACf;QAA2B,YAAY,AAAvC,CACA,EADQ,OAAO,CACf;QAAoC,MAAM,AAA1C,CACF,EADU,OAAO,CAAC,OAAO,CAAC,CAC1B;KACwB,EASxB;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI,EAJC,MAID,EAAE,QAAQ,EAHT,kBAGS,QAGnB;IAED;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAHA,MAGA,GAFE,OAAO,CAInB;IAED;;;;;OAKG;IACH,kBAAkB,CAAC,IAAI,EAJZ,MAIY,EAAE,QAAQ,EAHtB,eAGsB,QAGhC;IAED;;;;OAIG;IACH,qBAAqB,CAAC,IAAI,EAHf,MAGe,GAFb,OAAO,CAInB;IAED;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,IAAI,EALE,MAKF,EAAE,GAAG,IAAI,EAJJ,GAAG,EAIC,GAHL,OAAO,CAgBnB;IAED;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,EANP,MAMO,EAAE,IAAI,AALrB,CACA,EADQ,cAKa,EAAE,OAAO,AAJ9B,CACA,EADQ,MAI8B,GAH5B,OAAO,CAAC,GAAG,CAAC,CAuBxB;IAED;;;;OAIG;IACH,IAAI,IAHS,IAAI,CAmHhB;CACF;eAEc,mBAAmB"}