tiny-essentials 1.28.18 → 1.29.0

package/dist/v1/libs/worker/browser/TinyWebWorker.d.mts

@@ -0,0 +1,97 @@
+import { TinyPluginCore } from '../../plugin/TinyPlugin.mjs';
+export type MessagePayload = any;
+export type ApiHandlerOptions = {
+    /**
+     * - The payload received from the worker.
+     */
+    data?: MessagePayload;
+    /**
+     * - The request ID.
+     */
+    correlationId: string;
+};
+export type ApiHandlerCallback = (options: ApiHandlerOptions) => Promise<MessagePayload | undefined> | (MessagePayload | undefined);
+/**
+ * The data payload contained within the message.
+ * @typedef {any} MessagePayload
+ */
+/**
+ * @typedef {Object} ApiHandlerOptions
+ * @property {MessagePayload} [data] - The payload received from the worker.
+ * @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.
+ */
+/**
+ * Manages Web Worker initialization, lifecycle, and strictly typed messaging.
+ */
+declare class TinyWebWorker extends TinyPluginCore {
+    #private;
+    /** @returns {boolean} True if the worker is ready. */
+    get isReady(): boolean;
+    /** @returns {boolean} True if the instance has been destroyed. */
+    get isDestroyed(): boolean;
+    /** @returns {Worker | null} The native worker instance. */
+    get worker(): Worker | null;
+    /**
+     * @param {Object} options - Configuration options for the instance.
+     * @param {string} options.id - The unique identifier for this manager instance.
+     * @param {string | URL} options.workerUrl - The path to the web worker file.
+     * @param {WorkerOptions} [options.workerOptions={}] - Native worker options.
+     * @param {boolean} [options.debugMode=false] - Whether to enable internal debug logging.
+     * @param {boolean} [options.useLogColors=false] - Whether to enable log color support.
+     * @param {Partial<Console>} [options.logger=console] - A custom logger object.
+     * @throws {TypeError} If parameters are not the correct types.
+     */
+    constructor({ id, workerUrl, workerOptions, logger, debugMode, useLogColors }: {
+        id: string;
+        workerUrl: string | URL;
+        workerOptions?: WorkerOptions;
+        debugMode?: boolean;
+        useLogColors?: boolean;
+        logger?: Partial<Console>;
+    });
+    /**
+     * Initializes the Web Worker and sets up the message bridges.
+     * @returns {Promise<void>} Resolves when the engine inside the worker signals readiness.
+     */
+    init(): Promise<void>;
+    /**
+     * Sends a message to the active Web Worker.
+     * @param {string} type
+     * @param {MessagePayload} [data]
+     */
+    emitMessage(type: string, data?: MessagePayload): void;
+    /**
+     * Registers a handler for API calls coming from the Worker.
+     * @param {string} type
+     * @param {ApiHandlerCallback} callback
+     */
+    onApi(type: string, callback: ApiHandlerCallback): void;
+    /**
+     * Removes a registered API handler.
+     * @param {string} type
+     */
+    offApi(type: string): boolean;
+    /**
+     * Sends an API request to the Web Worker and waits for the response.
+     * @param {string} type - The API call identifier.
+     * @param {MessagePayload} [data] - The request payload.
+     * @param {number} [timeout=10000] - Maximum waiting time in milliseconds.
+     * @returns {Promise<any>}
+     */
+    emitApi(type: string, data?: MessagePayload, timeout?: number): Promise<any>;
+    /**
+     * Terminates the Web Worker immediately and cleans up listeners.
+     */
+    terminate(): void;
+    /**
+     * Hard destroys the instance, clearing all references to avoid memory leaks.
+     */
+    destroy(): void;
+}
+export default TinyWebWorker;
+//# sourceMappingURL=TinyWebWorker.d.mts.map

package/dist/v1/libs/worker/browser/TinyWebWorker.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TinyWebWorker.d.mts","sourceRoot":"","sources":["../../../../../src/v1/libs/worker/browser/TinyWebWorker.mjs"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAO1D,YAAe,cAAc,GAAnB,GAAG,CAAgB;AAI7B,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;AAfD;;;GAGG;AAEH;;;;GAIG;AAEH;;;;GAIG;AAEH;;GAEG;AACH,cAAM,aAAc,SAAQ,cAAc;;IAsCxC,sDAAsD;IACtD,IAAI,OAAO,IADG,OAAO,CAGpB;IAED,kEAAkE;IAClE,IAAI,WAAW,IADD,OAAO,CAGpB;IAED,2DAA2D;IAC3D,IAAI,MAAM,IADI,MAAM,GAAG,IAAI,CAI1B;IAED;;;;;;;;;OASG;IACH,YAAY,EAAE,EAAE,EAAE,SAAS,EAAE,aAAkB,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,EAR/E;QAAwB,EAAE,EAAlB,MAAM,CACd;QAA8B,SAAS,EAA/B,MAAM,GAAG,GAAG,CACpB;QAAgC,aAAa,AAA7C,CACA,EADQ,aAAa,CACrB;QAA0B,SAAS,AAAnC,CACA,EADQ,OAAO,CACf;QAA0B,YAAY,AAAtC,CACA,EADQ,OAAO,CACf;QAAmC,MAAM,AAAzC,CACA,EADQ,OAAO,CAAC,OAAO,CAAC,CACxB;KAE+E,EAoBjF;IAED;;;OAGG;IACG,IAAI,IAFG,OAAO,CAAC,IAAI,CAAC,CA8GzB;IAwBD;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAHL,MAGK,EAAE,IAAI,AAFnB,CAA8B,EAAtB,cAEW,QAErB;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAHC,MAGD,EAAE,QAAQ,EAFT,kBAES,QAGnB;IAED;;;OAGG;IACH,MAAM,CAAC,IAAI,EAFA,MAEA,WAEV;IAED;;;;;;OAMG;IACG,OAAO,CAAC,IAAI,EALP,MAKO,EAAE,IAAI,AAJrB,CACA,EADQ,cAIa,EAAE,OAAO,AAH9B,CACA,EADQ,MAG8B,GAF5B,OAAO,CAAC,GAAG,CAAC,CAwBxB;IAED;;OAEG;IACH,SAAS,SAgBR;IAED;;OAEG;IACH,OAAO,SAON;CACF;eAEc,aAAa"}

package/dist/v1/libs/worker/browser/TinyWebWorker.mjs

@@ -0,0 +1,305 @@
+import { TinyPluginCore } from '../../plugin/TinyPlugin.mjs';
+import { createCheckDestroyed } from '../../utils/tools.mjs';
+const checkDestroy = createCheckDestroyed('TinyWebWorker');
+/**
+ * The data payload contained within the message.
+ * @typedef {any} MessagePayload
+ */
+/**
+ * @typedef {Object} ApiHandlerOptions
+ * @property {MessagePayload} [data] - The payload received from the worker.
+ * @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.
+ */
+/**
+ * Manages Web Worker initialization, lifecycle, and strictly typed messaging.
+ */
+class TinyWebWorker extends 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 starts with the reserved prefix 'ww:'.
+     */
+    static #validateEventType(type) {
+        if (type.startsWith('ww:')) {
+            throw new TypeError(`The event type "${type}" is reserved for internal Web Worker lifecycle management.`);
+        }
+    }
+    /** @type {Worker | null} The active Web Worker instance. */
+    #worker = null;
+    /** @type {string} The unique identifier for this instance. */
+    #id;
+    /** @type {string | URL} The URL of the web worker file. */
+    #workerUrl;
+    /** @type {WorkerOptions} Options for the worker initialization. */
+    #workerOptions;
+    /** @type {boolean} Indicates if the worker is fully initialized and ready. */
+    #isReady = false;
+    /** @type {boolean} Internal flag to track if the instance has been destroyed. */
+    #isDestroyed = false;
+    /** @type {Map<string, {resolve: (value: any) => void, reject: (reason: Error) => void, timer: NodeJS.Timeout}>} */
+    #pendingRequests = new Map();
+    /** @type {Map<string, ApiHandlerCallback>} A map of registered API handlers. */
+    #apiHandlers = new Map();
+    /** @type {((event: MessageEvent) => void) | null} */
+    #messageHandler = null;
+    /** @type {((event: ErrorEvent) => void) | null} */
+    #errorHandler = null;
+    /** @returns {boolean} True if the worker is ready. */
+    get isReady() {
+        return this.#isReady;
+    }
+    /** @returns {boolean} True if the instance has been destroyed. */
+    get isDestroyed() {
+        return this.#isDestroyed;
+    }
+    /** @returns {Worker | null} The native worker instance. */
+    get worker() {
+        checkDestroy(this.#isDestroyed);
+        return this.#worker;
+    }
+    /**
+     * @param {Object} options - Configuration options for the instance.
+     * @param {string} options.id - The unique identifier for this manager instance.
+     * @param {string | URL} options.workerUrl - The path to the web worker file.
+     * @param {WorkerOptions} [options.workerOptions={}] - Native worker options.
+     * @param {boolean} [options.debugMode=false] - Whether to enable internal debug logging.
+     * @param {boolean} [options.useLogColors=false] - Whether to enable log color support.
+     * @param {Partial<Console>} [options.logger=console] - A custom logger object.
+     * @throws {TypeError} If parameters are not the correct types.
+     */
+    constructor({ id, workerUrl, workerOptions = {}, logger, debugMode, useLogColors }) {
+        super({
+            logCfg: {
+                id: '[_sub_class_TinyWebWorker_reset_]',
+                logger: logger ?? console,
+                debugMode: debugMode ?? false,
+                useLogColors: useLogColors ?? false,
+            },
+        });
+        if (typeof id !== 'string' || id.trim() === '') {
+            throw new TypeError('The "id" parameter must be a non-empty string.');
+        }
+        if (typeof workerUrl !== 'string' && !(workerUrl instanceof URL)) {
+            throw new TypeError('The "workerUrl" parameter must be a string or URL.');
+        }
+        this.#id = id;
+        this.#workerUrl = workerUrl;
+        this.#workerOptions = workerOptions;
+    }
+    /**
+     * Initializes the Web Worker and sets up the message bridges.
+     * @returns {Promise<void>} Resolves when the engine inside the worker signals readiness.
+     */
+    async init() {
+        checkDestroy(this.#isDestroyed);
+        if (this.#worker)
+            throw new Error('Worker is already initialized.');
+        return new Promise((resolve, reject) => {
+            try {
+                this.#worker = new Worker(this.#workerUrl, this.#workerOptions);
+            }
+            catch (error) {
+                this.log('error', 'Failed to instantiate Worker:', error);
+                return reject(error);
+            }
+            this.#messageHandler = (event) => {
+                const payload = event.data;
+                if (Array.isArray(payload) || typeof payload !== 'object' || payload === null)
+                    return;
+                if (typeof payload.type !== 'string')
+                    return;
+                // Engine Ready signal
+                if (payload.type === 'ww:EngineReady') {
+                    this.#isReady = true;
+                    super.emit('ww:Started');
+                    resolve();
+                    return;
+                }
+                const type = payload.type;
+                const data = payload.data;
+                const correlationId = payload.correlationId;
+                const isApi = payload.isApi;
+                // 1. API responses coming from the Worker
+                if (type === 'ww:ApiResponse') {
+                    if (typeof correlationId !== 'string')
+                        return;
+                    const pending = this.#pendingRequests.get(correlationId);
+                    if (pending) {
+                        clearTimeout(pending.timer);
+                        this.#pendingRequests.delete(correlationId);
+                        if (payload.error) {
+                            pending.reject(new Error(payload.error));
+                        }
+                        else {
+                            pending.resolve(data);
+                        }
+                    }
+                    return;
+                }
+                // 2. API requests coming from the Worker
+                if (isApi === true) {
+                    if (typeof correlationId !== 'string')
+                        return;
+                    const handler = this.#apiHandlers.get(type);
+                    if (!handler) {
+                        this.#worker?.postMessage({
+                            correlationId,
+                            type: 'ww:ApiResponse',
+                            error: `No API handler registered in Main Thread for type: ${type}`,
+                        });
+                        return;
+                    }
+                    try {
+                        /** @param {MessagePayload} [r] */
+                        const sendResult = (r) => this.#worker?.postMessage({
+                            correlationId,
+                            type: 'ww:ApiResponse',
+                            data: r,
+                        });
+                        const result = handler({ data, correlationId });
+                        if (result instanceof Promise)
+                            result.then(sendResult).catch((err) => {
+                                this.#worker?.postMessage({
+                                    correlationId,
+                                    type: 'ww:ApiResponse',
+                                    error: err instanceof Error ? err.message : String(err),
+                                });
+                            });
+                        else
+                            sendResult(result);
+                    }
+                    catch (error) {
+                        this.#worker?.postMessage({
+                            correlationId,
+                            type: 'ww:ApiResponse',
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                    return;
+                }
+                // 3. Emit standard event to plugins/listeners
+                super.emit(type, { data, event });
+            };
+            this.#errorHandler = (errorEvent) => {
+                this.log('error', `Worker Error [${this.#id}]:`, errorEvent.message);
+                super.emit('ww:Error', { error: errorEvent });
+                // Calling reject() after the promise is already resolved is a no-op,
+                // so this is safe for runtime errors that happen after startup.
+                reject(new Error(`Web Worker [${this.#id}] failed to start: ${errorEvent.message || 'unknown error'}`));
+            };
+            this.#worker.addEventListener('message', this.#messageHandler);
+            this.#worker.addEventListener('error', this.#errorHandler);
+        });
+    }
+    /**
+     * Internal sender method.
+     * @param {string} type
+     * @param {MessagePayload} [data]
+     * @param {boolean} strictMode
+     */
+    #emitMessage(type, data, strictMode = false) {
+        checkDestroy(this.#isDestroyed);
+        if (!this.#worker)
+            throw new Error('Worker is not initialized.');
+        if (typeof type !== 'string')
+            throw new TypeError('Payload.type must be a string.');
+        if (typeof data !== 'undefined' &&
+            (Array.isArray(data) || typeof data !== 'object' || data === null)) {
+            throw new TypeError('Payload.data must be a non-null object.');
+        }
+        if (strictMode)
+            TinyWebWorker.#validateEventType(type);
+        this.#worker.postMessage({ type, data });
+    }
+    /**
+     * Sends a message to the active Web Worker.
+     * @param {string} type
+     * @param {MessagePayload} [data]
+     */
+    emitMessage(type, data) {
+        this.#emitMessage(type, data, true);
+    }
+    /**
+     * Registers a handler for API calls coming from the Worker.
+     * @param {string} type
+     * @param {ApiHandlerCallback} callback
+     */
+    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
+     */
+    offApi(type) {
+        return this.#apiHandlers.delete(type);
+    }
+    /**
+     * Sends an API request to the Web Worker and waits for the response.
+     * @param {string} type - The API call identifier.
+     * @param {MessagePayload} [data] - The request payload.
+     * @param {number} [timeout=10000] - Maximum waiting time in milliseconds.
+     * @returns {Promise<any>}
+     */
+    async emitApi(type, data, timeout = 10000) {
+        checkDestroy(this.#isDestroyed);
+        if (!this.#worker)
+            throw new Error('Worker is not initialized.');
+        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 request timeout: ${type} (ID: ${correlationId})`));
+                }
+            }, timeout);
+            this.#pendingRequests.set(correlationId, { resolve, reject, timer });
+            this.#worker?.postMessage({
+                type,
+                data,
+                correlationId,
+                isApi: true,
+            });
+        });
+    }
+    /**
+     * Terminates the Web Worker immediately and cleans up listeners.
+     */
+    terminate() {
+        if (this.#isDestroyed)
+            return;
+        if (this.#worker) {
+            if (this.#messageHandler)
+                this.#worker.removeEventListener('message', this.#messageHandler);
+            if (this.#errorHandler)
+                this.#worker.removeEventListener('error', this.#errorHandler);
+            this.#worker.terminate();
+            this.log('info', `Web Worker [${this.#id}] terminated.`);
+        }
+        this.#worker = null;
+        this.#messageHandler = null;
+        this.#errorHandler = null;
+        this.#isReady = false;
+        super.emit('ww:Terminated');
+    }
+    /**
+     * Hard destroys the instance, clearing all references to avoid memory leaks.
+     */
+    destroy() {
+        if (this.#isDestroyed)
+            return;
+        this.terminate();
+        this.removeAllListeners();
+        this.destroyPlugins();
+        this.#isDestroyed = true;
+        this.log('info', `[${this.#id}] Destroyed successfully.`);
+    }
+}
+export default TinyWebWorker;