tiny-essentials 1.28.18 → 1.29.0

package/dist/v1/libs/storage/TinyLocalStorage.d.mts

@@ -1,4 +1,3 @@
-import { EventEmitter } from 'events';
 export type EncodeFn = (value: any, encodeSpecialJson: encodeSpecialJson) => any;
 export type DecodeFn = {
     /**
@@ -13,6 +12,52 @@ export type DecodeFn = {
 export type encodeSpecialJson = (value: any) => any;
 export type decodeSpecialJson = (value: any) => any;
 export type LocalStorageJsonValue = (Record<string | number | symbol, any> | any[] | Map<string | number | symbol, any> | Set<any>);
+export type TinyLocalStorageEvents = {
+    /**
+     * - Emitted when a cross-tab storage event is received.
+     */
+    storage: (ev: StorageEvent) => void;
+    /**
+     * - Emitted when a JSON value is stored.
+     */
+    setJson: (name: string, data: any) => void;
+    /**
+     * - Emitted when a Date is stored.
+     */
+    setDate: (name: string, data: Date) => void;
+    /**
+     * - Emitted when a RegExp is stored.
+     */
+    setRegExp: (name: string, data: RegExp) => void;
+    /**
+     * - Emitted when a BigInt is stored.
+     */
+    setBigInt: (name: string, data: bigint) => void;
+    /**
+     * - Emitted when a Symbol is stored.
+     */
+    setSymbol: (name: string, data: symbol) => void;
+    /**
+     * - Emitted when a raw item is stored.
+     */
+    setItem: (name: string, data: any) => void;
+    /**
+     * - Emitted when a string is stored.
+     */
+    setString: (name: string, data: string) => void;
+    /**
+     * - Emitted when a number is stored.
+     */
+    setNumber: (name: string, data: number) => void;
+    /**
+     * - Emitted when a boolean is stored.
+     */
+    setBool: (name: string, data: boolean) => void;
+    /**
+     * - Emitted when an item is removed.
+     */
+    removeItem: (name: string) => void;
+};
 /**
  * A function that encodes a value into a serializable JSON-compatible format.
  *
@@ -53,6 +98,23 @@ export type LocalStorageJsonValue = (Record<string | number | symbol, any> | any
  *
  * @typedef {(Record<string|number|symbol, any> | any[] | Map<string|number|symbol, any> | Set<any>)} LocalStorageJsonValue
  */
+/**
+ * Event map for {@link TinyLocalStorage}.
+ * @typedef {Object} TinyLocalStorageEvents
+ * @property {(ev: StorageEvent) => void} storage - Emitted when a cross-tab storage event is received.
+ * @property {(name: string, data: any) => void} setJson - Emitted when a JSON value is stored.
+ * @property {(name: string, data: Date) => void} setDate - Emitted when a Date is stored.
+ * @property {(name: string, data: RegExp) => void} setRegExp - Emitted when a RegExp is stored.
+ * @property {(name: string, data: bigint) => void} setBigInt - Emitted when a BigInt is stored.
+ * @property {(name: string, data: symbol) => void} setSymbol - Emitted when a Symbol is stored.
+ * @property {(name: string, data: any) => void} setItem - Emitted when a raw item is stored.
+ * @property {(name: string, data: string) => void} setString - Emitted when a string is stored.
+ * @property {(name: string, data: number) => void} setNumber - Emitted when a number is stored.
+ * @property {(name: string, data: boolean) => void} setBool - Emitted when a boolean is stored.
+ * @property {(name: string) => void} removeItem - Emitted when an item is removed.
+ */
+/** @type {new (dbName?: string) => import('../../jsdoc/EventEmitter.mjs').ICustomEventEmitter<TinyLocalStorageEvents>} */
+declare const TypedEventEmitter: new (dbName?: string) => import('../../jsdoc/EventEmitter.mjs').ICustomEventEmitter<TinyLocalStorageEvents>;
 /**
  * A powerful wrapper for Web Storage (`localStorage` or `sessionStorage`) that supports
  * type-safe methods and full JSON-like structure encoding and decoding.
@@ -77,7 +139,7 @@ export type LocalStorageJsonValue = (Record<string | number | symbol, any> | any
  *
  * This class is suitable for applications that require structured persistence in the browser.
  */
-declare class TinyLocalStorage extends EventEmitter {
+declare class TinyLocalStorage extends TypedEventEmitter {
     #private;
     /**
      * Checks whether a JSON-serializable type is already registered.

package/dist/v1/libs/storage/TinyLocalStorage.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"TinyLocalStorage.d.mts","sourceRoot":"","sources":["../../../../src/v1/libs/storage/TinyLocalStorage.mjs"],"names":[],"mappings":"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"}
+{"version":3,"file":"TinyLocalStorage.d.mts","sourceRoot":"","sources":["../../../../src/v1/libs/storage/TinyLocalStorage.mjs"],"names":[],"mappings":"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"}

package/dist/v1/libs/storage/TinyLocalStorage.mjs

@@ -60,6 +60,23 @@ const customTypesFreezed = new Set([
  *
  * @typedef {(Record<string|number|symbol, any> | any[] | Map<string|number|symbol, any> | Set<any>)} LocalStorageJsonValue
  */
+/**
+ * Event map for {@link TinyLocalStorage}.
+ * @typedef {Object} TinyLocalStorageEvents
+ * @property {(ev: StorageEvent) => void} storage - Emitted when a cross-tab storage event is received.
+ * @property {(name: string, data: any) => void} setJson - Emitted when a JSON value is stored.
+ * @property {(name: string, data: Date) => void} setDate - Emitted when a Date is stored.
+ * @property {(name: string, data: RegExp) => void} setRegExp - Emitted when a RegExp is stored.
+ * @property {(name: string, data: bigint) => void} setBigInt - Emitted when a BigInt is stored.
+ * @property {(name: string, data: symbol) => void} setSymbol - Emitted when a Symbol is stored.
+ * @property {(name: string, data: any) => void} setItem - Emitted when a raw item is stored.
+ * @property {(name: string, data: string) => void} setString - Emitted when a string is stored.
+ * @property {(name: string, data: number) => void} setNumber - Emitted when a number is stored.
+ * @property {(name: string, data: boolean) => void} setBool - Emitted when a boolean is stored.
+ * @property {(name: string) => void} removeItem - Emitted when an item is removed.
+ */
+/** @type {new (dbName?: string) => import('../../jsdoc/EventEmitter.mjs').ICustomEventEmitter<TinyLocalStorageEvents>} */
+const TypedEventEmitter = /** @type {any} */ (EventEmitter);
 /**
  * A powerful wrapper for Web Storage (`localStorage` or `sessionStorage`) that supports
  * type-safe methods and full JSON-like structure encoding and decoding.
@@ -84,7 +101,7 @@ const customTypesFreezed = new Set([
  *
  * This class is suitable for applications that require structured persistence in the browser.
  */
-class TinyLocalStorage extends EventEmitter {
+class TinyLocalStorage extends TypedEventEmitter {
     /**
      * Checks whether a JSON-serializable type is already registered.
      *

package/dist/v1/libs/storage/TinyMapCache.cjs

@@ -0,0 +1,373 @@
+'use strict';
+
+var events = require('events');
+
+/**
+ * @template T
+ * @callback ForEachCallback
+ * @param {T} data - The value of the current entry.
+ * @param {string} key - The key of the current entry.
+ * @param {TinyMapCache<T>} cache - The cache instance that is being iterated.
+ * @returns {void}
+ */
+
+/**
+ * @template T
+ * @typedef {Object} SetEventPayload
+ * @property {string} key - The key that was set.
+ * @property {T} data - The data that was set.
+ */
+
+/**
+ * @template T
+ * @typedef {Object} GetEventPayload
+ * @property {string} key - The key that was accessed.
+ * @property {boolean} hit - True if the key was found and is valid, false otherwise.
+ */
+
+/**
+ * @template T
+ * @typedef {Object} DeleteEventPayload
+ * @property {string} key - The key that was removed.
+ */
+
+/**
+ * @template T
+ * @typedef {Object} ExpireEventPayload
+ * @property {string} key - The key that expired.
+ * @property {T} data - The data that was removed due to expiration.
+ */
+
+/**
+ * @typedef {Object} PurgeEventPayload
+ * @property {number} count - The number of items removed during purge.
+ */
+
+/**
+ * @template T
+ * @typedef {Object} CacheEntry
+ * @property {T} data - The actual data being stored.
+ * @property {number} timestamp - The Unix timestamp (ms) when the data was stored.
+ */
+
+/**
+ * A Map collection where keys are strings and values are CacheEntry objects.
+ * @template T
+ * @typedef {Map<string, CacheEntry<T>>} CacheMap
+ */
+
+/**
+ * A plain object representation of the cache, where keys are strings and values are CacheEntry objects.
+ * @template T
+ * @typedef {Object.<string, CacheEntry<T>>} CacheObject
+ */
+
+/**
+ * Event map for {@link TinyMapCache}.
+ * @template T
+ * @typedef {Object} TinyMapCacheEvents
+ * @property {(payload: SetEventPayload<T>) => void} set - Emitted when an item is stored.
+ * @property {(payload: DeleteEventPayload<T>) => void} delete - Emitted when an item is removed.
+ * @property {(payload: ExpireEventPayload<T>) => void} expire - Emitted when an item expires.
+ * @property {(payload: PurgeEventPayload) => void} purge - Emitted after a purge cycle removes items.
+ * @property {() => void} clear - Emitted when the cache is cleared.
+ */
+
+/**
+ * @template T
+ * @typedef {import('../../jsdoc/EventEmitter.mjs').ICustomEventEmitter<TinyMapCacheEvents<T>>} TinyMapCacheEmitter
+ */
+
+/** @type {new () => TinyMapCacheEmitter<any>} */
+const TypedEventEmitter = /** @type {any} */ (events.EventEmitter);
+
+/**
+ * @template {any} T
+ * In-memory cache manager to prevent duplicate requests.
+ */
+class TinyMapCache extends TypedEventEmitter {
+  /**
+   * A private collection of all active `TinyMapCache` instances.
+   * This set is used to facilitate cascaded operations (like `purgeExpired`) across all existing cache instances.
+   * @type {Set<TinyMapCache<any>>}
+   */
+  static #instances = new Set();
+
+  /**
+   * A collection of all active `TinyMapCache` instances.
+   * This collection is used to facilitate cascaded operations (like `purgeExpired`) across all existing cache instances.
+   * @type {Array<TinyMapCache<any>>}
+   */
+  static get activeInstances() {
+    return Array.from(TinyMapCache.#instances);
+  }
+
+  /**
+   * Returns the total number of active `TinyMapCache` instances currently being tracked.
+   * @returns {number} The count of active instances.
+   */
+  static get activeInstancesSize() {
+    return TinyMapCache.#instances.size;
+  }
+
+  constructor() {
+    super();
+  }
+
+  /** @type {CacheMap<T>} */
+  #cache = new Map();
+  /**
+   * Time-to-live: 5 minutes in milliseconds
+   * @type {number}
+   */
+  #ttl = 300000;
+
+  /**
+   * Gets the current Time-To-Live (TTL) in milliseconds.
+   * @returns {number}
+   */
+  get ttl() {
+    return this.#ttl;
+  }
+
+  /**
+   * Sets the Time-To-Live (TTL) in milliseconds.
+   * @param {number} value - The new TTL value.
+   * @throws {TypeError} If the value is not a number.
+   * @throws {RangeError} If the value is less than 0.
+   */
+  set ttl(value) {
+    if (typeof value !== 'number') {
+      throw new TypeError('The TTL value must be a number.');
+    }
+    if (value < 0) {
+      throw new RangeError('The TTL value cannot be negative.');
+    }
+    this.#ttl = value;
+  }
+
+  /**
+   * Returns the number of items currently stored in the cache.
+   * @returns {number}
+   */
+  get size() {
+    return this.#cache.size;
+  }
+
+  /**
+   * Checks if a specific key exists in the cache.
+   *
+   * Note: This method triggers a full purge of all expired items in the cache.
+   * @param {string} key - The identifier for the data.
+   * @returns {boolean} True if the key exists, false otherwise.
+   * @throws {TypeError} If the key is not a string.
+   */
+  has(key) {
+    if (typeof key !== 'string') {
+      throw new TypeError('The cache key must be a string.');
+    }
+    this.purgeExpired(true);
+    return this.#cache.has(key);
+  }
+
+  /**
+   * Removes the item associated with the specified key from the cache.
+   *
+   * Note: This method triggers a full purge of all expired items in the cache.
+   * @param {string} key - The identifier for the data.
+   * @returns {boolean} True if an element in the Map existed and has been removed, false otherwise.
+   * @throws {TypeError} If the key is not a string.
+   */
+  delete(key) {
+    if (typeof key !== 'string') {
+      throw new TypeError('The cache key must be a string.');
+    }
+    this.purgeExpired(true);
+    const deleted = this.#cache.delete(key);
+    if (deleted) {
+      /** @type {DeleteEventPayload<T>} */
+      const payload = { key };
+      this.emit('delete', payload);
+    }
+    return deleted;
+  }
+
+  /**
+   * Saves an item to the cache.
+   *
+   * Note: This method triggers a full purge of all expired items in the cache.
+   * @param {string} key - The identifier for the data.
+   * @param {T} data - The data to be stored.
+   * @throws {TypeError} If the key is not a string.
+   */
+  set(key, data) {
+    if (typeof key !== 'string') {
+      throw new TypeError('The cache key must be a string.');
+    }
+    this.purgeExpired(true);
+    if (!TinyMapCache.#instances.has(this)) TinyMapCache.#instances.add(this);
+
+    this.#cache.set(key, {
+      data,
+      timestamp: Date.now(),
+    });
+
+    /** @type {SetEventPayload<T>} */
+    const payload = { key, data };
+    this.emit('set', payload);
+  }
+
+  /**
+   * Retrieves an item if it is still valid.
+   *
+   * Note: This method triggers a full purge of all expired items in the cache.
+   * @param {string} key - The identifier for the data.
+   * @returns {T | null} The data if valid, or null if expired/not found.
+   * @throws {TypeError} If the key is not a string.
+   */
+  get(key) {
+    if (typeof key !== 'string') {
+      throw new TypeError('The cache key must be a string.');
+    }
+    this.purgeExpired(true);
+    const cached = this.#cache.get(key);
+    if (!cached) return null;
+
+    return cached.data;
+  }
+
+  /**
+   * Returns the string tag used by `Object.prototype.toString`.
+   * @returns {string} The string tag for this class.
+   */
+  get [Symbol.toStringTag]() {
+    return 'TinyMapCache';
+  }
+
+  /**
+   * Returns a new iterator that yields the keys of all valid (non-expired) entries.
+   *
+   * Note: This method triggers a full purge of all expired items in the cache.
+   * @returns {IterableIterator<string>} An iterator over the cache keys.
+   */
+  keys() {
+    this.purgeExpired(true);
+    return this.#validEntries()
+      .map(([key]) => key)
+      .values();
+  }
+
+  /**
+   * Returns a new iterator that yields the values of all valid (non-expired) entries.
+   *
+   * Note: This method triggers a full purge of all expired items in the cache.
+   * @returns {IterableIterator<T>} An iterator over the cache values.
+   */
+  values() {
+    this.purgeExpired(true);
+    return this.#validEntries()
+      .map(([, data]) => data)
+      .values();
+  }
+
+  /**
+   * Returns a new iterator that yields the `[key, value]` pairs of all valid (non-expired) entries.
+   *
+   * Note: This method triggers a full purge of all expired items in the cache.
+   * @returns {IterableIterator<[string, T]>} An iterator over the cache entries.
+   */
+  entries() {
+    this.purgeExpired(true);
+    return this.#validEntries().values();
+  }
+
+  /**
+   * Returns a new iterator over the `[key, value]` pairs of all valid (non-expired) entries.
+   * Alias for `entries()`, enabling `for...of` and spread syntax.
+   *
+   * Note: This method triggers a full purge of all expired items in the cache.
+   * @returns {IterableIterator<[string, T]>} An iterator over the cache entries.
+   */
+  [Symbol.iterator]() {
+    return this.entries();
+  }
+
+  /**
+   * Executes a provided function once for each valid (non-expired) entry.
+   *
+   * Note: This method triggers a full purge of all expired items in the cache.
+   * @param {ForEachCallback<T>} callbackFn - The function to execute for each entry.
+   * @param {any} [thisArg] - The value to use as `this` when executing `callbackFn`.
+   * @returns {void}
+   * @throws {TypeError} If the callback is not a function.
+   */
+  forEach(callbackFn, thisArg) {
+    if (typeof callbackFn !== 'function') {
+      throw new TypeError('The callback must be a function.');
+    }
+    this.purgeExpired(true);
+    for (const [key, data] of this.#validEntries()) {
+      callbackFn.call(thisArg, data, key, this);
+    }
+  }
+
+  /**
+   * Builds a snapshot of all valid (non-expired) entries as `[key, value]` pairs.
+   * Expired entries are expected to be removed beforehand via `purgeExpired`.
+   * @returns {Array<[string, T]>} The list of valid entries.
+   */
+  #validEntries() {
+    /** @type {Array<[string, T]>} */
+    const entries = [];
+    for (const [key, entry] of this.#cache.entries()) {
+      entries.push([key, entry.data]);
+    }
+    return entries;
+  }
+
+  /**
+   * Iterates through the current cache and removes all entries that have exceeded the TTL.
+   * @param {boolean} [clearAll=true] - If true, triggers a purge on all other active cache instances.
+   * @returns {void}
+   */
+  purgeExpired(clearAll = false) {
+    const now = Date.now();
+    let purgedCount = 0;
+
+    for (const [key, entry] of this.#cache.entries()) {
+      if (now - entry.timestamp > this.#ttl) {
+        this.#cache.delete(key);
+        purgedCount++;
+
+        /** @type {ExpireEventPayload<T>} */
+        const expirePayload = { key, data: entry.data };
+        this.emit('expire', expirePayload);
+      }
+    }
+
+    if (purgedCount > 0) {
+      /** @type {PurgeEventPayload} */
+      const purgePayload = { count: purgedCount };
+      this.emit('purge', purgePayload);
+    }
+
+    if (this.#cache.size < 1) TinyMapCache.#instances.delete(this);
+
+    if (clearAll)
+      TinyMapCache.#instances.forEach((i) => {
+        if (i !== this) i.purgeExpired(false);
+      });
+  }
+
+  /**
+   * Removes all items from the cache.
+   * @returns {void}
+   */
+  clear() {
+    TinyMapCache.#instances.delete(this);
+    this.#cache.clear();
+    this.emit('clear');
+  }
+}
+
+module.exports = TinyMapCache;