tiny-essentials 1.28.19 → 1.29.1

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

@@ -0,0 +1,304 @@
+import { TinyPluginCore, TinyPlugin, TinyPluginLayer } from '../../plugin/TinyPlugin.mjs';
+/**
+ * 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 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 });
+    }
+}
+export default TinyWebWorkerEngine;

package/dist/v1/regexp/Email.cjs

@@ -0,0 +1,185 @@
+'use strict';
+
+/**
+ * A function type used to define custom validation logic for an email address.
+ * @typedef {(email: string) => boolean} EmailValidatorFn
+ */
+
+/**
+ * Configuration options for customizing email regex patterns and validation rules.
+ * @typedef {Object} EmailRegexOptions
+ * @property {string} [validName] - The regular expression pattern used to match the username portion of the email.
+ * @property {string} [validDomain] - The regular expression pattern used to match the domain portion of the email.
+ * @property {string[]} [blacklistDomains] - An array of domain strings that are explicitly forbidden during validation.
+ * @property {string[]} [whitelistDomains] - An array of domain strings that are the only permitted domains.
+ * @property {string[]} [blacklistUsernames] - An array of username strings that are explicitly forbidden during validation.
+ * @property {string[]} [whitelistUsernames] - An array of username strings that are the only permitted usernames.
+ * @property {EmailValidatorFn} [customValidator] - A callback function that receives the email string and returns a boolean to perform custom validation logic.
+ */
+
+/**
+ * Validates the EmailRegexOptions object to ensure all properties match the required types.
+ * This is a private helper used to maintain strict type safety at runtime.
+ *
+ * @param {EmailRegexOptions} options - The configuration options to validate.
+ * @throws {TypeError} If the options are not an object or if any property fails type validation.
+ * @private
+ */
+const validateEmailRegexOptions = (options) => {
+  if (options === undefined) return;
+  if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+    throw new TypeError('Options must be an object.');
+  }
+
+  /**
+   * Helper to validate if a property is an array of strings.
+   * @param {any} arr - The array to validate.
+   * @param {string} name - The name of the property for the error message.
+   * @private
+   */
+  const validateArray = (arr, name) => {
+    if (arr !== undefined) {
+      if (!Array.isArray(arr)) {
+        throw new TypeError(`${name} must be an array.`);
+      }
+      for (let i = 0; i < arr.length; i++) {
+        if (typeof arr[i] !== 'string') {
+          throw new TypeError(`All elements in ${name} must be strings.`);
+        }
+      }
+    }
+  };
+
+  validateArray(options.blacklistDomains, 'blacklistDomains');
+  validateArray(options.whitelistDomains, 'whitelistDomains');
+  validateArray(options.blacklistUsernames, 'blacklistUsernames');
+  validateArray(options.whitelistUsernames, 'whitelistUsernames');
+  if (options.customValidator !== undefined && typeof options.customValidator !== 'function') {
+    throw new TypeError('customValidator must be a function.');
+  }
+};
+
+/**
+ * Constructs a email regular expression pattern string based on the provided configuration options.
+ * @param {EmailRegexOptions} [options] - The configuration options.
+ * @returns {string} The generated regex pattern string.
+ */
+const emailStringRegexBuilder = (options = {}) => {
+  validateEmailRegexOptions(options);
+  const { validName = '[a-zA-Z0-9._%+-]+', validDomain = '[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}' } =
+    options;
+  return `${validName}@${validDomain}`;
+};
+
+/**
+ * Creates a RegExp object anchored to the start and end of the string using the provided configuration.
+ * @param {EmailRegexOptions} [options] - The configuration options.
+ * @returns {RegExp} The resulting RegExp object.
+ */
+function emailRegex(options) {
+  return new RegExp(`^${emailStringRegexBuilder(options)}$`);
+}
+
+/**
+ * Performs deep validation of an email string against specified whitelist and blacklist rules for domains and usernames.
+ *
+ * @param {string} s - The string to validate.
+ * @param {EmailRegexOptions} [options={}] - The configuration options.
+ * @returns {boolean} True if the string is a valid email, false otherwise.
+ * @throws {TypeError} If the input string is not a string.
+ */
+function verifyEmail(s, options = {}) {
+  // Runs custom validation if provided
+  if (typeof options.customValidator === 'function' && !options.customValidator(s)) {
+    return false;
+  }
+
+  // Since the regex matched, we can safely split the string into username and domain.
+  const [username, domain] = s.split('@');
+
+  // Whitelist checks: If a whitelist exists, the value MUST be in it.
+  if (
+    Array.isArray(options.whitelistDomains) &&
+    options.whitelistDomains.length > 0 &&
+    !options.whitelistDomains.includes(domain)
+  ) {
+    return false;
+  }
+  if (
+    Array.isArray(options.whitelistUsernames) &&
+    options.whitelistUsernames.length > 0 &&
+    !options.whitelistUsernames.includes(username)
+  ) {
+    return false;
+  }
+
+  // Blacklist checks: If a blacklist exists, the value MUST NOT be in it.
+  if (
+    Array.isArray(options.blacklistDomains) &&
+    options.blacklistDomains.length > 0 &&
+    options.blacklistDomains.includes(domain)
+  ) {
+    return false;
+  }
+  if (
+    Array.isArray(options.blacklistUsernames) &&
+    options.blacklistUsernames.length > 0 &&
+    options.blacklistUsernames.includes(username)
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Validates whether a given string matches the specified email pattern,
+ * respects blacklist/whitelist rules, and passes a custom validator if provided.
+ * @param {string} s - The string to validate.
+ * @param {EmailRegexOptions} [options={}] - The configuration options.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @returns {boolean} True if the string is a valid email, false otherwise.
+ * @throws {TypeError} If the input string is not a string.
+ */
+function isValidEmail(s, options = {}, regex) {
+  if (typeof s !== 'string') {
+    throw new TypeError('The input must be a string.');
+  }
+
+  const pattern = regex ?? emailRegex(options);
+  if (!pattern.test(s)) {
+    return false;
+  }
+
+  return verifyEmail(s, options);
+}
+
+/**
+ * Generates a global RegExp object used to find all occurrences of URLs within a text.
+ * @param {EmailRegexOptions} [options] - The configuration options.
+ * @returns {RegExp} The resulting global RegExp object.
+ */
+function findEmailRegex(options) {
+  return new RegExp(`\\b${emailStringRegexBuilder(options)}\\b`, 'g');
+}
+
+/**
+ * Extracts all matching email strings from a given text using the provided configuration.
+ * @param {string} text - The text to search.
+ * @param {EmailRegexOptions} [options] - The configuration options.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @returns {string[]} An array of matches or null if no matches are found.
+ * @throws {TypeError} If the input text is not a string.
+ */
+function extractEmails(text, options, regex) {
+  if (typeof text !== 'string') {
+    throw new TypeError('The input must be a string.');
+  }
+  return text.match(regex ?? findEmailRegex(options))?.filter((s) => verifyEmail(s, options)) ?? [];
+}
+
+exports.emailRegex = emailRegex;
+exports.emailStringRegexBuilder = emailStringRegexBuilder;
+exports.extractEmails = extractEmails;
+exports.findEmailRegex = findEmailRegex;
+exports.isValidEmail = isValidEmail;

package/dist/v1/regexp/Email.d.mts

@@ -0,0 +1,73 @@
+/**
+ * A function type used to define custom validation logic for an email address.
+ * @typedef {(email: string) => boolean} EmailValidatorFn
+ */
+export type EmailValidatorFn = (email: string) => boolean;
+export type EmailRegexOptions = {
+    /**
+     * - The regular expression pattern used to match the username portion of the email.
+     */
+    validName?: string;
+    /**
+     * - The regular expression pattern used to match the domain portion of the email.
+     */
+    validDomain?: string;
+    /**
+     * - An array of domain strings that are explicitly forbidden during validation.
+     */
+    blacklistDomains?: string[];
+    /**
+     * - An array of domain strings that are the only permitted domains.
+     */
+    whitelistDomains?: string[];
+    /**
+     * - An array of username strings that are explicitly forbidden during validation.
+     */
+    blacklistUsernames?: string[];
+    /**
+     * - An array of username strings that are the only permitted usernames.
+     */
+    whitelistUsernames?: string[];
+    /**
+     * - A callback function that receives the email string and returns a boolean to perform custom validation logic.
+     */
+    customValidator?: EmailValidatorFn;
+};
+/**
+ * Constructs a email regular expression pattern string based on the provided configuration options.
+ * @param {EmailRegexOptions} [options] - The configuration options.
+ * @returns {string} The generated regex pattern string.
+ */
+export declare const emailStringRegexBuilder: (options?: EmailRegexOptions) => string;
+/**
+ * Creates a RegExp object anchored to the start and end of the string using the provided configuration.
+ * @param {EmailRegexOptions} [options] - The configuration options.
+ * @returns {RegExp} The resulting RegExp object.
+ */
+export declare function emailRegex(options?: EmailRegexOptions): RegExp;
+/**
+ * Validates whether a given string matches the specified email pattern,
+ * respects blacklist/whitelist rules, and passes a custom validator if provided.
+ * @param {string} s - The string to validate.
+ * @param {EmailRegexOptions} [options={}] - The configuration options.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @returns {boolean} True if the string is a valid email, false otherwise.
+ * @throws {TypeError} If the input string is not a string.
+ */
+export declare function isValidEmail(s: string, options?: EmailRegexOptions, regex?: RegExp): boolean;
+/**
+ * Generates a global RegExp object used to find all occurrences of URLs within a text.
+ * @param {EmailRegexOptions} [options] - The configuration options.
+ * @returns {RegExp} The resulting global RegExp object.
+ */
+export declare function findEmailRegex(options?: EmailRegexOptions): RegExp;
+/**
+ * Extracts all matching email strings from a given text using the provided configuration.
+ * @param {string} text - The text to search.
+ * @param {EmailRegexOptions} [options] - The configuration options.
+ * @param {RegExp} [regex] - The regex used to execute the function.
+ * @returns {string[]} An array of matches or null if no matches are found.
+ * @throws {TypeError} If the input text is not a string.
+ */
+export declare function extractEmails(text: string, options?: EmailRegexOptions, regex?: RegExp): string[];
+//# sourceMappingURL=Email.d.mts.map

package/dist/v1/regexp/Email.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Email.d.mts","sourceRoot":"","sources":["../../../src/v1/regexp/Email.mjs"],"names":[],"mappings":"AAAA;;;GAGG;AADA,YAAsC,gBAAgB,GAA5C,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAkB;AAKtD,YAAkB,iBAAiB,GACnC;;;;IAAoB,SAAS,AAA7B,CACA,EADW,MAAM,CACjB;;;;IAAoB,WAAW,AAA/B,CACA,EADW,MAAM,CACjB;;;;IAAsB,gBAAgB,AAAtC,CACA,EADW,MAAM,EAAE,CACnB;;;;IAAsB,gBAAgB,AAAtC,CACA,EADW,MAAM,EAAE,CACnB;;;;IAAsB,kBAAkB,AAAxC,CACA,EADW,MAAM,EAAE,CACnB;;;;IAAsB,kBAAkB,AAAxC,CACA,EADW,MAAM,EAAE,CACnB;;;;IAA8B,eAAe,AAA7C,CACF,EADa,gBAAgB,CAC7B;CAAA,CAAA;AA4CD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,aAHzB,iBAAiB,KACf,MAOZ,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,AAH/B,CACA,EADQ,iBAGuB,GAFrB,MAAM,CAIlB;AAsDD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,CAAC,EANnB,MAMmB,EAAE,OAAO,AALpC,CACA,EADQ,iBAKiC,EAAE,KAAK,AAJhD,CACA,EADQ,MAIwC,GAHtC,OAAO,CAcnB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,AAHnC,CACA,EADQ,iBAG2B,GAFzB,MAAM,CAIlB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EANvB,MAMuB,EAAE,OAAO,AALxC,CACA,EADQ,iBAKgC,EAAE,KAAK,AAJ/C,CACA,EADQ,MAIuC,GAHrC,MAAM,EAAE,CAQpB"}