tiny-essentials 1.28.18 → 1.29.0

package/dist/v1/libs/utils/TinyThrottledApi.mjs

@@ -0,0 +1,294 @@
+import { EventEmitter } from 'events';
+import TinyPromiseQueue from './TinyPromiseQueue.mjs';
+import { waitForTrue } from '../../basics/promiseUtils.mjs';
+import TinyTimeout from '../math/TinyTimeout.mjs';
+import { createCheckDestroyed } from './tools.mjs';
+const checkDestroy = createCheckDestroyed('TinyThrottledApi');
+/**
+ * @template T
+ * @typedef {Promise<T>} QueueResult
+ * Represents the eventual result of a queued operation.
+ */
+/**
+ * Event map for {@link TinyThrottledApi}.
+ * @typedef {Object} TinyThrottledApiEvents
+ * @property {(id: string) => void} ExecTask - Emitted when a task starts executing.
+ * @property {(id: string) => void} TaskEnded - Emitted when a task finishes executing.
+ * @property {(id: string) => void} WaitingTask - Emitted when a task is queued and waiting for a slot.
+ * @property {() => void} Destroyed - Emitted when the instance is destroyed.
+ * @property {(value: number) => void} SetConcurrencyLimit - Emitted when the concurrency limit changes.
+ * @property {(value: number) => void} SetTimeoutValue - Emitted when the timeout value changes.
+ * @property {(value: number) => void} SetTimeoutLimit - Emitted when the timeout limit changes.
+ */
+/** @type {new () => import('../../jsdoc/EventEmitter.mjs').ICustomEventEmitter<TinyThrottledApiEvents>} */
+const TypedEventEmitter = /** @type {any} */ (EventEmitter);
+/**
+ * A client that manages asynchronous requests with a concurrency limit.
+ * It uses TinyPromiseQueue to manage waiting tasks and waitForTrue to poll for availability.
+ * @template {(...args: any) => Promise<any>} API
+ */
+class TinyThrottledApi extends TypedEventEmitter {
+    static TinyTimeout = TinyTimeout;
+    /** @type {number} The current number of active asynchronous operations. */
+    #activeCount = 0;
+    /** @type {number} The maximum number of concurrent operations allowed. */
+    #concurrencyLimit;
+    /** @type {TinyPromiseQueue} The internal queue used to manage pending tasks. */
+    #queue = new TinyPromiseQueue();
+    /** @type {API} The target API function to be executed. */
+    #api;
+    /** @type {TinyTimeout|null} The optional timeout instance to regulate execution frequency. */
+    #timeoutInstance;
+    /** @type {number} - Base delay multiplier in milliseconds. */
+    #timeoutValue = 100;
+    /** @type {number|null} - Optional maximum delay cap. */
+    #timeoutLimit = 5000;
+    /** @type {boolean} Indicates whether the instance has been destroyed. */
+    #isDestroyed = false;
+    /** @type {boolean} Indicates whether the first execution should be delayed by the timeout. */
+    #timeoutFirst = false;
+    /**
+     * Initializes a new instance of the TinyThrottledApi class.
+     *
+     * @param {number} concurrencyLimit - The maximum number of simultaneous requests.
+     * @param {API} api - The API implementation.
+     * @param {TinyTimeout|null} [timeoutInstance=null] - Optional TinyTimeout instance to regulate execution frequency.
+     * @throws {TypeError} If concurrencyLimit is not a positive number.
+     * @throws {TypeError} If API is not a function.
+     */
+    constructor(concurrencyLimit, api, timeoutInstance = null) {
+        super();
+        if (typeof concurrencyLimit !== 'number' || concurrencyLimit <= 0) {
+            throw new TypeError('Concurrency limit must be a positive number.');
+        }
+        if (typeof api !== 'function') {
+            throw new TypeError('API must be a function.');
+        }
+        if (typeof timeoutInstance !== 'undefined' &&
+            timeoutInstance !== null &&
+            !(timeoutInstance instanceof TinyTimeout)) {
+            throw new TypeError('timeoutInstance must be a TinyTimeout instance.');
+        }
+        this.#concurrencyLimit = concurrencyLimit;
+        this.#api = api;
+        this.#timeoutInstance = timeoutInstance ?? null;
+    }
+    /**
+     * Executes an API request, respecting the concurrency limit and optional rate limiting.
+     *
+     * @param {Parameters<API>} args
+     * @returns {QueueResult<ReturnType<API>>} A promise that resolves with the API result.
+     * @throws {TypeError} If the internal state is corrupted.
+     */
+    async exec(...args) {
+        checkDestroy(this.#isDestroyed);
+        const id = crypto.randomUUID(); // Using UUID for better collision resistance
+        // If we are under the limit, reserve the slot SYNCHRONOUSLY to prevent race conditions.
+        if (this.#activeCount < this.#concurrencyLimit) {
+            this.#activeCount++;
+            this.emit('ExecTask', id);
+            const final = await this.#performRequest(...args);
+            this.emit('TaskEnded', id);
+            return final;
+        }
+        // If we reached the limit, queue a task that waits for a slot.
+        return this.#queue.enqueue(async () => {
+            this.emit('WaitingTask', id);
+            // The task in the queue waits until a slot is available via polling.
+            const waitCounter = () => waitForTrue(() => this.#activeCount < this.#concurrencyLimit);
+            // If a TinyTimeout instance is provided, we wait for its next scheduled "tick".
+            // This introduces a dynamic delay that increases as more tasks are processed.
+            const waitTimeout = async () => {
+                if (this.#timeoutInstance) {
+                    await new Promise((resolve) => {
+                        // We use a constant ID so the frequency is tracked across all calls to this instance.
+                        if (this.#timeoutInstance)
+                            this.#timeoutInstance.set('api_throttle', resolve, this.#timeoutValue, this.#timeoutLimit);
+                        else
+                            resolve(undefined);
+                    });
+                }
+            };
+            if (this.#timeoutFirst) {
+                await waitTimeout();
+                await waitCounter();
+            }
+            else {
+                await waitCounter();
+                await waitTimeout();
+            }
+            // Once available and the throttle allows, we reserve the slot.
+            this.#activeCount++;
+            this.emit('ExecTask', id);
+            const final = await this.#performRequest(...args);
+            this.emit('TaskEnded', id);
+            return final;
+        }, undefined, id);
+    }
+    /**
+     * Cleans up the instance, removing all listeners and stopping pending tasks.
+     * @returns {void}
+     */
+    destroy() {
+        if (this.#isDestroyed)
+            return;
+        this.removeAllListeners();
+        this.#isDestroyed = true;
+        this.emit('Destroyed');
+    }
+    /**
+     * Internal method to handle the actual execution and counter management.
+     *
+     * @param {Parameters<API>} args
+     * @returns {QueueResult<ReturnType<API>>}
+     */
+    async #performRequest(...args) {
+        try {
+            const apiFunction = this.#api;
+            return await apiFunction(...args);
+        }
+        finally {
+            // The decrement happens here, ensuring the slot is released even on failure.
+            this.#activeCount--;
+        }
+    }
+    /**
+     * Returns whether the instance has been destroyed.
+     * @returns {boolean}
+     */
+    get isDestroyed() {
+        return this.#isDestroyed;
+    }
+    /**
+     * Gets the internal task queue.
+     * @returns {TinyPromiseQueue} The internal task queue.
+     */
+    get queue() {
+        checkDestroy(this.#isDestroyed);
+        return this.#queue;
+    }
+    /**
+     * Gets the original API function.
+     * @returns {API} The original API function.
+     */
+    get api() {
+        checkDestroy(this.#isDestroyed);
+        return this.#api;
+    }
+    /**
+     * Gets the current concurrency limit.
+     * @returns {number} The current concurrency limit.
+     */
+    get concurrencyLimit() {
+        checkDestroy(this.#isDestroyed);
+        return this.#concurrencyLimit;
+    }
+    /**
+     * Sets a new concurrency limit.
+     * @param {number} value - The new maximum number of simultaneous requests.
+     * @throws {TypeError} If value is not a positive number.
+     */
+    set concurrencyLimit(value) {
+        checkDestroy(this.#isDestroyed);
+        if (typeof value !== 'number' || value <= 0) {
+            throw new TypeError('Concurrency limit must be a positive number.');
+        }
+        this.#concurrencyLimit = value;
+        this.emit('SetConcurrencyLimit', value);
+    }
+    /**
+     * Gets the current TinyTimeout instance used for rate limiting.
+     * @returns {TinyTimeout|null}
+     */
+    get timeoutInstance() {
+        checkDestroy(this.#isDestroyed);
+        return this.#timeoutInstance;
+    }
+    /**
+     * Gets the current base delay multiplier in milliseconds.
+     * @returns {number}
+     */
+    get timeoutValue() {
+        checkDestroy(this.#isDestroyed);
+        return this.#timeoutValue;
+    }
+    /**
+     * Sets a new base delay multiplier in milliseconds.
+     * @param {number} value - The new base delay multiplier.
+     * @throws {TypeError} If the value is not a number.
+     * @throws {RangeError} If the value is a negative number.
+     */
+    set timeoutValue(value) {
+        checkDestroy(this.#isDestroyed);
+        if (typeof value !== 'number') {
+            throw new TypeError('Timeout value must be a number.');
+        }
+        if (value < 0) {
+            throw new RangeError('Timeout value cannot be negative.');
+        }
+        this.#timeoutValue = value;
+        this.emit('SetTimeoutValue', value);
+    }
+    /**
+     * Gets the current maximum delay cap.
+     * @returns {number|null}
+     */
+    get timeoutLimit() {
+        checkDestroy(this.#isDestroyed);
+        return this.#timeoutLimit;
+    }
+    /**
+     * Gets whether the first execution should be delayed by the timeout.
+     * @returns {boolean}
+     */
+    get timeoutFirst() {
+        return this.#timeoutFirst;
+    }
+    /**
+     * Sets whether the first execution should be delayed by the timeout.
+     * @param {boolean} value - The new boolean value.
+     * @throws {TypeError} If the value is not a boolean.
+     */
+    set timeoutFirst(value) {
+        if (typeof value !== 'boolean') {
+            throw new TypeError('timeoutFirst must be a boolean.');
+        }
+        this.#timeoutFirst = value;
+    }
+    /**
+     * Sets a new maximum delay cap.
+     * @param {number} value - The new maximum delay cap.
+     * @throws {TypeError} If the value is not a number.
+     * @throws {RangeError} If the value is a negative number.
+     */
+    set timeoutLimit(value) {
+        checkDestroy(this.#isDestroyed);
+        if (typeof value !== 'number') {
+            throw new TypeError('Timeout limit must be a number.');
+        }
+        if (value < 0) {
+            throw new RangeError('Timeout limit cannot be negative.');
+        }
+        this.#timeoutLimit = value;
+        this.emit('SetTimeoutLimit', value);
+    }
+    /**
+     * Returns the number of currently active requests.
+     *
+     * @returns {number}
+     */
+    get activeCount() {
+        checkDestroy(this.#isDestroyed);
+        return this.#activeCount;
+    }
+    /**
+     * Returns the number of tasks waiting in the queue.
+     *
+     * @returns {number}
+     */
+    get queuedCount() {
+        checkDestroy(this.#isDestroyed);
+        return this.#queue.getQueuedIds().length;
+    }
+}
+export default TinyThrottledApi;

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

@@ -0,0 +1,342 @@
+'use strict';
+
+var TinyPlugin = require('../../plugin/TinyPlugin.cjs');
+var tools = require('../../utils/tools.cjs');
+
+const checkDestroy = tools.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 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 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.`);
+  }
+}
+
+module.exports = TinyWebWorker;