tiny-essentials 1.28.0 → 1.28.2

package/dist/v1/libs/TinyHtml.mjs

@@ -1,5 +1,5 @@
 import { diffArrayList } from '../basics/array.mjs';
-import { diffStrings } from '../basics/text.mjs';
+import { diffObjList } from '../basics/text.mjs';
 import * as TinyCollision from '../basics/collision.mjs';
 import TinyElementObserver from './TinyElementObserver.mjs';
 // TITLE: Introduction
@@ -333,7 +333,6 @@ class TinyHtml {
      * Enables or disables debug output.
      * @param {boolean} value True to enable debug output; false to disable.
      * @throws {TypeError} Thrown if the provided value is not a boolean.
-     * @returns {void}
      */
     static set elemDebug(value) {
         if (typeof value !== 'boolean')
@@ -432,7 +431,7 @@ class TinyHtml {
                         const newVal = mutation.target.getAttribute('style') || '';
                         const oldStyles = TinyHtml.parseStyle(oldVal);
                         const newStyles = TinyHtml.parseStyle(newVal);
-                        const changes = diffStrings(oldStyles, newStyles);
+                        const changes = diffObjList(oldStyles, newStyles);
                         if (Object.keys(changes.added).length ||
                             Object.keys(changes.removed).length ||
                             Object.keys(changes.modified).length) {
@@ -511,7 +510,7 @@ class TinyHtml {
      *
      * @param {string} url - The URL of the HTML file.
      * @param {RequestInit} [ops] - Optional fetch configuration (e.g., method, headers, cache, etc).
-     * @returns {Promise<TinyHtml<TinyElement|Text>[]>} A promise that resolves with the TinyHtml instances.
+     * Returns the promise that resolves with the TinyHtml instances.
      */
     static async fetchHtmlTinyElems(url, ops) {
         const nodes = await TinyHtml.fetchHtmlNodes(url, ops);
@@ -1437,7 +1436,7 @@ class TinyHtml {
      * of the input form.
      *
      * @param {TinyElement|Text|(TinyElement|Text)[]} elems - A single element or an array of elements (DOM or TinyHtml).
-     * @returns {TinyHtml<TinyElement|Text>[]} An array of TinyHtml instances corresponding to the input elements.
+     * Returns the array of TinyHtml instances corresponding to the input elements.
      */
     static toTinyElm(elems) {
         /** @param {(TinyElement|Text)[]} item */
@@ -3706,7 +3705,7 @@ class TinyHtml {
     // TITLE: Animate DOM (cssExpand)
     /**
      * CSS expansion shorthand used by genStyleFx to include margin/padding values.
-     * @typedef {['Top', 'Right', 'Bottom', 'Left']}
+     * @type {['Top', 'Right', 'Bottom', 'Left']}
      */
     static #cssExpand = ['Top', 'Right', 'Bottom', 'Left'];
     // TITLE: Animate DOM (styleEffects)

package/dist/v1/libs/TinyI18.cjs

@@ -3,6 +3,9 @@
 var promises = require('fs/promises');
 var fs = require('fs');
 var path = require('path');
+var utils = require('./utils.cjs');
+
+const checkDestroy = utils.createCheckDestroyed('TinyI18');
 
 /**
  * Supported operating modes for TinyI18.
@@ -168,6 +171,21 @@ class TinyI18 {
     await promises.writeFile(output, JSON.stringify(merged, null, spaces), 'utf-8');
   }
 
+  /**
+   * Tracks whether the instance has been destroyed.
+   * @type {boolean}
+   */
+  #destroyed = false;
+
+  /**
+   * Gets the current destruction status of the instance.
+   *
+   * @returns {boolean} True if the instance is destroyed, false otherwise.
+   */
+  get destroyed() {
+    return this.#destroyed;
+  }
+
   /** @type {ModeTypes} */
   #mode;
   /** @type {LocaleCode} */
@@ -197,6 +215,7 @@ class TinyI18 {
    * @returns {LocaleCode|null}
    */
   get currentLocale() {
+    checkDestroy(this.#destroyed);
     return this.#currentLocale;
   }
 
@@ -206,6 +225,7 @@ class TinyI18 {
    * @type {LocaleCode}
    */
   get defaultLocale() {
+    checkDestroy(this.#destroyed);
     return this.#defaultLocale;
   }
 
@@ -216,6 +236,7 @@ class TinyI18 {
    * @type {ModeTypes}
    */
   get mode() {
+    checkDestroy(this.#destroyed);
     return this.#mode;
   }
 
@@ -226,6 +247,7 @@ class TinyI18 {
    * @type {boolean}
    */
   get strict() {
+    checkDestroy(this.#destroyed);
     return this.#strict;
   }
 
@@ -236,6 +258,7 @@ class TinyI18 {
    * @type {string|null}
    */
   get basePath() {
+    checkDestroy(this.#destroyed);
     return this.#basePath;
   }
 
@@ -244,6 +267,7 @@ class TinyI18 {
    * @returns {StatLocale[]}
    */
   get stats() {
+    checkDestroy(this.#destroyed);
     const locales = [];
     for (const loc of this.#stringTables.keys()) locales.push(this.getStatsForLocale(loc));
     return locales;
@@ -255,6 +279,7 @@ class TinyI18 {
    * @returns {Record<string, Dict>}
    */
   get stringTables() {
+    checkDestroy(this.#destroyed);
     /** @type {Record<string, Dict>} */
     const obj = {};
     for (const [locale, dict] of this.#stringTables.entries()) {
@@ -269,6 +294,7 @@ class TinyI18 {
    * @returns {Record<string, PatternEntry[]>}
    */
   get patternTables() {
+    checkDestroy(this.#destroyed);
     /** @type {Record<string, PatternEntry[]>} */
     const obj = {};
     for (const [locale, arr] of this.#patternTables.entries()) {
@@ -287,6 +313,7 @@ class TinyI18 {
    * @returns {Record<string, HelperCallback>}
    */
   get helpers() {
+    checkDestroy(this.#destroyed);
     /** @type {Record<string, HelperCallback>} */
     const obj = {};
     for (const [name, fn] of this.#helpers.entries()) {
@@ -301,6 +328,7 @@ class TinyI18 {
    * @returns {Record<string, RegExp>}
    */
   get regexCache() {
+    checkDestroy(this.#destroyed);
     /** @type {Record<string, RegExp>} */
     const obj = {};
     for (const [key, re] of this.#regexCache.entries()) {
@@ -765,6 +793,7 @@ class TinyI18 {
    * management is always controlled via the API instead of direct access.
    */
   clearRegexCache() {
+    checkDestroy(this.#destroyed);
     this.#regexCache.clear();
   }
 
@@ -774,6 +803,7 @@ class TinyI18 {
    * @param {HelperCallback} fn
    */
   registerHelper(name, fn) {
+    checkDestroy(this.#destroyed);
     if (typeof name !== 'string' || !name)
       throw new TypeError('registerHelper: "name" must be non-empty string');
     if (typeof fn !== 'function') throw new TypeError('registerHelper: "fn" must be a function');
@@ -789,6 +819,7 @@ class TinyI18 {
    * @returns {boolean} `true` if the helper was removed, `false` if it was not found.
    */
   unregisterHelper(name) {
+    checkDestroy(this.#destroyed);
     if (typeof name !== 'string' || !name)
       throw new TypeError('unregisterHelper: "name" must be non-empty string');
     return this.#helpers.delete(name);
@@ -800,6 +831,7 @@ class TinyI18 {
    * @param {Dict} data
    */
   loadLocaleLocal(locale, data) {
+    checkDestroy(this.#destroyed);
     if (this.#mode !== 'local')
       throw new TypeError('loadLocaleLocal is only available in "local" mode');
     this.#ingestLocale(locale, data);
@@ -811,6 +843,7 @@ class TinyI18 {
    * @param {LocaleCode|null} locale - null -> keep only default
    */
   async setLocale(locale) {
+    checkDestroy(this.#destroyed);
     if (locale !== null && (typeof locale !== 'string' || !locale))
       throw new TypeError('setLocale: "locale" must be string or null');
 
@@ -856,6 +889,7 @@ class TinyI18 {
    * @returns {any}
    */
   get(key, params = undefined, options = undefined) {
+    checkDestroy(this.#destroyed);
     if (typeof key !== 'string' || !key)
       throw new TypeError('get: "key" must be a non-empty string');
 
@@ -891,6 +925,7 @@ class TinyI18 {
    * @returns {any}
    */
   resolveByPattern(key, options) {
+    checkDestroy(this.#destroyed);
     if (typeof key !== 'string' || !key)
       throw new TypeError('get: "key" must be a non-empty string');
     const { locale: forceLocale } = options || {};
@@ -908,6 +943,7 @@ class TinyI18 {
    * Selected locale becomes null.
    */
   resetToDefaultOnly() {
+    checkDestroy(this.#destroyed);
     if (this.#mode === 'file') {
       for (const loc of Array.from(this.#stringTables.keys())) {
         if (loc !== this.#defaultLocale) {
@@ -925,6 +961,7 @@ class TinyI18 {
    * @throws {Error} If the locale is not registered.
    */
   getStatsForLocale(locale) {
+    checkDestroy(this.#destroyed);
     if (typeof locale !== 'string' || !locale)
       throw new TypeError('getStatsForLocale: "locale" must be a non-empty string');
     if (!this.#stringTables.has(locale))
@@ -941,6 +978,30 @@ class TinyI18 {
       isCurrent: locale === this.#currentLocale,
     };
   }
+
+  /**
+   * Destroys the TinyI18 instance, clearing all internal maps and references
+   * to free up memory. Once destroyed, the instance cannot be reused.
+   *
+   * @throws {Error} If the instance has already been destroyed.
+   * @returns {void}
+   */
+  destroy() {
+    if (this.#destroyed) return;
+
+    // Clear all internal maps to release memory
+    this.#stringTables.clear();
+    this.#patternTables.clear();
+    this.#helpers.clear();
+    this.#regexCache.clear();
+
+    // Reset locale and path configurations
+    this.#currentLocale = null;
+    this.#basePath = null;
+
+    // Mark the instance as destroyed
+    this.#destroyed = true;
+  }
 }
 
 module.exports = TinyI18;

package/dist/v1/libs/TinyI18.d.mts

@@ -1,34 +1,11 @@
-export default TinyI18;
-/**
- * Supported operating modes for TinyI18.
- * - `"local"` → All translations are managed entirely in memory (browser + Node.js).
- * - `"file"` → Translations are loaded from JSON files on disk (Node.js only).
- */
 export type ModeTypes = "local" | "file";
-/**
- * Dictionary of translation keys mapped to values.
- */
 export type Dict = Record<string, any>;
-/**
- * `$pattern` - Regex string (will be compiled into RegExp).
- *
- * `$fn` - Helper function name associated with this entry.
- *
- * `[key]` - Additional key-value pairs for interpolation or extra metadata.
- */
 export type FileValue = {
     $pattern: string;
     $fn: string;
     [key: string]: string;
 };
-/**
- * Represents a valid locale code string.
- * Example: "en", "pt-BR", "fr".
- */
 export type LocaleCode = string;
-/**
- * Represents a single regex-based translation entry.
- */
 export type PatternEntry = {
     /**
      * - Compiled regular expression used for matching.
@@ -47,7 +24,7 @@ export type FileModeEntryJSON = {
     /**
      * - regex as string e.g. "^user\\.(\\d+)$"
      */
-    $pattern?: string | undefined;
+    $pattern?: string;
     /**
      * - string or { $fn: string, args?: any }
      */
@@ -63,25 +40,22 @@ export type TinyI18Options = {
     /**
      * - Required in file mode. Directory with <locale>.json
      */
-    basePath?: string | undefined;
+    basePath?: string;
     /**
      * - Optional initial map { locale: dict } for local mode
      */
-    localResources?: Dict | undefined;
+    localResources?: Dict;
     /**
      * - If true, throws on missing keys; else returns key
      */
-    strict?: boolean | undefined;
+    strict?: boolean;
 };
 export type ResolveOptions = {
     /**
      * - force resolve using a specific locale first
      */
-    locale?: string | undefined;
+    locale?: LocaleCode;
 };
-/**
- * Represents statistics for a specific locale.
- */
 export type StatLocale = {
     /**
      * - The locale code (e.g., "en", "pt-BR").
@@ -104,30 +78,17 @@ export type StatLocale = {
      */
     isCurrent: boolean;
 };
-/**
- * Read-only view of registered helpers, exposed to function-based entries.
- *
- * Provides safe access to:
- * - check if a helper exists by name
- * - call a helper by name, passing arguments
- */
-export type HelpersReadonly<T extends unknown, R extends unknown> = {
+export type HelpersReadonly<T extends any, R extends any> = {
     /**
      * - Check if a helper with given name is registered.
      */
-    has?: ((name: string) => boolean) | undefined;
+    has?: (name: string) => boolean;
     /**
      * -
      * Invoke a helper by name with an argument and optional extras.
      */
-    call?: ((name: string, arg: T, extras?: HelpersReadonly<T, R>) => R) | undefined;
+    call?: (name: string, arg: T, extras?: HelpersReadonly<T, R>) => R;
 };
-/**
- * A helper callback function used in translations.
- *
- * - Receives user-supplied parameters and a read-only facade for calling other helpers.
- * - Must return a string (e.g. processed, interpolated, or formatted output).
- */
 export type HelperCallback = (params: Dict, helpers: HelpersReadonly<any, any>) => string;
 /**
  * Supported operating modes for TinyI18.
@@ -241,6 +202,7 @@ export type HelperCallback = (params: Dict, helpers: HelpersReadonly<any, any>)
  * - Safe: no dynamic code eval from files; functions in file mode are referenced by name ("$fn").
  */
 declare class TinyI18 {
+    #private;
     /**
      * Merges multiple JSON locale files into a single file for TinyI18 usage.
      * @param {Object} options
@@ -253,20 +215,14 @@ declare class TinyI18 {
     static mergeLocaleFiles({ files, output, spaces }: {
         files: string[];
         output: string;
-        spaces?: number | undefined;
+        spaces?: number;
     }): Promise<void>;
     /**
-     * Creates a new TinyI18 instance for managing localized strings and patterns.
+     * Gets the current destruction status of the instance.
      *
-     * Supports two modes:
-     * - "local": loads translations directly from provided objects.
-     * - "file": loads translations from JSON files on demand.
-     *
-     * Ensures the default locale is always initialized. In "file" mode, `basePath` is required.
-     *
-     * @param {TinyI18Options} options - Configuration options for the instance.
+     * @returns {boolean} True if the instance is destroyed, false otherwise.
      */
-    constructor(options: TinyI18Options);
+    get destroyed(): boolean;
     /**
      * Gets the currently selected locale, or null if only default is active.
      * @returns {LocaleCode|null}
@@ -328,6 +284,18 @@ declare class TinyI18 {
      * @returns {Record<string, RegExp>}
      */
     get regexCache(): Record<string, RegExp>;
+    /**
+     * Creates a new TinyI18 instance for managing localized strings and patterns.
+     *
+     * Supports two modes:
+     * - "local": loads translations directly from provided objects.
+     * - "file": loads translations from JSON files on demand.
+     *
+     * Ensures the default locale is always initialized. In "file" mode, `basePath` is required.
+     *
+     * @param {TinyI18Options} options - Configuration options for the instance.
+     */
+    constructor(options: TinyI18Options);
     /**
      * Clears the internal regex cache.
      *
@@ -413,6 +381,14 @@ declare class TinyI18 {
      * @throws {Error} If the locale is not registered.
      */
     getStatsForLocale(locale: LocaleCode): StatLocale;
-    #private;
+    /**
+     * Destroys the TinyI18 instance, clearing all internal maps and references
+     * to free up memory. Once destroyed, the instance cannot be reused.
+     *
+     * @throws {Error} If the instance has already been destroyed.
+     * @returns {void}
+     */
+    destroy(): void;
 }
+export default TinyI18;
 //# sourceMappingURL=TinyI18.d.mts.map

package/dist/v1/libs/TinyI18.mjs

@@ -1,6 +1,8 @@
 import { readFile, writeFile } from 'fs/promises';
 import { existsSync } from 'fs';
 import { join as pathJoin } from 'path';
+import { createCheckDestroyed } from './utils.mjs';
+const checkDestroy = createCheckDestroyed('TinyI18');
 /**
  * Supported operating modes for TinyI18.
  * - `"local"` → All translations are managed entirely in memory (browser + Node.js).
@@ -148,6 +150,19 @@ class TinyI18 {
         }
         await writeFile(output, JSON.stringify(merged, null, spaces), 'utf-8');
     }
+    /**
+     * Tracks whether the instance has been destroyed.
+     * @type {boolean}
+     */
+    #destroyed = false;
+    /**
+     * Gets the current destruction status of the instance.
+     *
+     * @returns {boolean} True if the instance is destroyed, false otherwise.
+     */
+    get destroyed() {
+        return this.#destroyed;
+    }
     /** @type {ModeTypes} */
     #mode;
     /** @type {LocaleCode} */
@@ -172,6 +187,7 @@ class TinyI18 {
      * @returns {LocaleCode|null}
      */
     get currentLocale() {
+        checkDestroy(this.#destroyed);
         return this.#currentLocale;
     }
     /**
@@ -180,6 +196,7 @@ class TinyI18 {
      * @type {LocaleCode}
      */
     get defaultLocale() {
+        checkDestroy(this.#destroyed);
         return this.#defaultLocale;
     }
     /**
@@ -189,6 +206,7 @@ class TinyI18 {
      * @type {ModeTypes}
      */
     get mode() {
+        checkDestroy(this.#destroyed);
         return this.#mode;
     }
     /**
@@ -198,6 +216,7 @@ class TinyI18 {
      * @type {boolean}
      */
     get strict() {
+        checkDestroy(this.#destroyed);
         return this.#strict;
     }
     /**
@@ -207,6 +226,7 @@ class TinyI18 {
      * @type {string|null}
      */
     get basePath() {
+        checkDestroy(this.#destroyed);
         return this.#basePath;
     }
     /**
@@ -214,6 +234,7 @@ class TinyI18 {
      * @returns {StatLocale[]}
      */
     get stats() {
+        checkDestroy(this.#destroyed);
         const locales = [];
         for (const loc of this.#stringTables.keys())
             locales.push(this.getStatsForLocale(loc));
@@ -225,6 +246,7 @@ class TinyI18 {
      * @returns {Record<string, Dict>}
      */
     get stringTables() {
+        checkDestroy(this.#destroyed);
         /** @type {Record<string, Dict>} */
         const obj = {};
         for (const [locale, dict] of this.#stringTables.entries()) {
@@ -238,6 +260,7 @@ class TinyI18 {
      * @returns {Record<string, PatternEntry[]>}
      */
     get patternTables() {
+        checkDestroy(this.#destroyed);
         /** @type {Record<string, PatternEntry[]>} */
         const obj = {};
         for (const [locale, arr] of this.#patternTables.entries()) {
@@ -255,6 +278,7 @@ class TinyI18 {
      * @returns {Record<string, HelperCallback>}
      */
     get helpers() {
+        checkDestroy(this.#destroyed);
         /** @type {Record<string, HelperCallback>} */
         const obj = {};
         for (const [name, fn] of this.#helpers.entries()) {
@@ -268,6 +292,7 @@ class TinyI18 {
      * @returns {Record<string, RegExp>}
      */
     get regexCache() {
+        checkDestroy(this.#destroyed);
         /** @type {Record<string, RegExp>} */
         const obj = {};
         for (const [key, re] of this.#regexCache.entries()) {
@@ -707,6 +732,7 @@ class TinyI18 {
      * management is always controlled via the API instead of direct access.
      */
     clearRegexCache() {
+        checkDestroy(this.#destroyed);
         this.#regexCache.clear();
     }
     /**
@@ -715,6 +741,7 @@ class TinyI18 {
      * @param {HelperCallback} fn
      */
     registerHelper(name, fn) {
+        checkDestroy(this.#destroyed);
         if (typeof name !== 'string' || !name)
             throw new TypeError('registerHelper: "name" must be non-empty string');
         if (typeof fn !== 'function')
@@ -730,6 +757,7 @@ class TinyI18 {
      * @returns {boolean} `true` if the helper was removed, `false` if it was not found.
      */
     unregisterHelper(name) {
+        checkDestroy(this.#destroyed);
         if (typeof name !== 'string' || !name)
             throw new TypeError('unregisterHelper: "name" must be non-empty string');
         return this.#helpers.delete(name);
@@ -740,6 +768,7 @@ class TinyI18 {
      * @param {Dict} data
      */
     loadLocaleLocal(locale, data) {
+        checkDestroy(this.#destroyed);
         if (this.#mode !== 'local')
             throw new TypeError('loadLocaleLocal is only available in "local" mode');
         this.#ingestLocale(locale, data);
@@ -750,6 +779,7 @@ class TinyI18 {
      * @param {LocaleCode|null} locale - null -> keep only default
      */
     async setLocale(locale) {
+        checkDestroy(this.#destroyed);
         if (locale !== null && (typeof locale !== 'string' || !locale))
             throw new TypeError('setLocale: "locale" must be string or null');
         const prev = this.#currentLocale;
@@ -791,6 +821,7 @@ class TinyI18 {
      * @returns {any}
      */
     get(key, params = undefined, options = undefined) {
+        checkDestroy(this.#destroyed);
         if (typeof key !== 'string' || !key)
             throw new TypeError('get: "key" must be a non-empty string');
         const { locale: forceLocale } = options || {};
@@ -822,6 +853,7 @@ class TinyI18 {
      * @returns {any}
      */
     resolveByPattern(key, options) {
+        checkDestroy(this.#destroyed);
         if (typeof key !== 'string' || !key)
             throw new TypeError('get: "key" must be a non-empty string');
         const { locale: forceLocale } = options || {};
@@ -839,6 +871,7 @@ class TinyI18 {
      * Selected locale becomes null.
      */
     resetToDefaultOnly() {
+        checkDestroy(this.#destroyed);
         if (this.#mode === 'file') {
             for (const loc of Array.from(this.#stringTables.keys())) {
                 if (loc !== this.#defaultLocale) {
@@ -855,6 +888,7 @@ class TinyI18 {
      * @throws {Error} If the locale is not registered.
      */
     getStatsForLocale(locale) {
+        checkDestroy(this.#destroyed);
         if (typeof locale !== 'string' || !locale)
             throw new TypeError('getStatsForLocale: "locale" must be a non-empty string');
         if (!this.#stringTables.has(locale))
@@ -869,5 +903,26 @@ class TinyI18 {
             isCurrent: locale === this.#currentLocale,
         };
     }
+    /**
+     * Destroys the TinyI18 instance, clearing all internal maps and references
+     * to free up memory. Once destroyed, the instance cannot be reused.
+     *
+     * @throws {Error} If the instance has already been destroyed.
+     * @returns {void}
+     */
+    destroy() {
+        if (this.#destroyed)
+            return;
+        // Clear all internal maps to release memory
+        this.#stringTables.clear();
+        this.#patternTables.clear();
+        this.#helpers.clear();
+        this.#regexCache.clear();
+        // Reset locale and path configurations
+        this.#currentLocale = null;
+        this.#basePath = null;
+        // Mark the instance as destroyed
+        this.#destroyed = true;
+    }
 }
 export default TinyI18;