tiny-essentials 1.24.5 → 1.25.1

package/dist/v1/libs/TinyRateLimiter.mjs

@@ -1,44 +1,172 @@
-/** @typedef {(groupId: string) => void} OnMemoryExceeded */
-/** @typedef {(groupId: string) => void} OnGroupExpired */
 /**
- * Class representing a flexible rate limiter per user or group.
+ * Callback triggered when a group's stored hit history exceeds
+ * the configured memory limit.
  *
- * This rate limiter supports limiting per user or per group by mapping
- * userIds to a common groupId. All users within the same group share
- * rate limits.
+ * This callback is purely informational and does not block execution.
+ *
+ * @typedef {(groupId: string) => void} OnMemoryExceeded
+ */
+/**
+ * Callback triggered when a group is considered expired and removed
+ * during the cleanup process.
+ *
+ * This usually happens when the group remains inactive longer than
+ * its configured TTL or the global maxIdle value.
+ *
+ * @typedef {(groupId: string) => void} OnGroupExpired
+ */
+/**
+ * A lightweight and flexible rate limiter supporting both user-based
+ * and group-based throttling.
+ *
+ * ## Core Concepts
+ * - Every user belongs to a group.
+ * - If no explicit group is assigned, the user acts as their own group.
+ * - All users within the same group share the same hit history and limits.
+ *
+ * ## Supported Limiting Strategies
+ * - Max number of hits
+ * - Time-based sliding window
+ * - Combination of both
+ *
+ * ## Extra Features
+ * - Per-group TTL (time-to-live)
+ * - Automatic cleanup of inactive groups
+ * - Optional memory cap per group
+ * - Runtime metrics and statistics
+ *
+ * ## Interval Window (Sliding Window) Behavior
+ *
+ * This rate limiter uses a **sliding time window** strategy when `interval`
+ * is configured.
+ *
+ * ### How it works
+ * - Each hit is stored as a timestamp (Date.now()).
+ * - On every new hit and rate check, timestamps older than:
+ *
+ *   `now - interval`
+ *
+ *   are discarded.
+ *
+ * - Only hits that occurred within the last `interval` milliseconds
+ *   are considered valid.
+ *
+ * ### Practical example
+ * If:
+ * - interval = 10_000 (10 seconds)
+ * - maxHits = 5
+ *
+ * Then:
+ * - Any group may perform **up to 5 hits in any rolling 10-second window**.
+ * - The window moves continuously with time.
+ *
+ * This avoids burst issues common in fixed-window rate limiters.
+ *
+ * This class is designed to be deterministic, predictable,
+ * and safe to use in long-running Node.js processes.
  */
 class TinyRateLimiter {
-    /** @type {number|null} */
+    /**
+     * Maximum number of timestamps stored per group.
+     * When exceeded, older entries are discarded.
+     *
+     * `null` means unlimited.
+     *
+     * @type {number|null}
+     */
     #maxMemory = null;
-    /** @type {NodeJS.Timeout|null} */
+    /**
+     * Internal timer reference used for periodic cleanup.
+     *
+     * @type {NodeJS.Timeout|null}
+     */
     #cleanupTimer = null;
-    /** @type {number|null|undefined} */
+    /**
+     * Maximum number of allowed hits within the interval window.
+     *
+     * If `null`, hit count is not enforced.
+     *
+     * @type {number|null|undefined}
+     */
     #maxHits = null;
-    /** @type {number|null|undefined} */
+    /**
+     * Sliding window duration in milliseconds.
+     *
+     * When defined, the rate limiter operates in **sliding window mode**:
+     * only hits that occurred within the last `interval` milliseconds
+     * are considered when evaluating limits.
+     *
+     * If `null`, time-based limiting is disabled and only `maxHits`
+     * (if defined) is used.
+     *
+     * @type {number|null|undefined}
+     */
     #interval = null;
-    /** @type {number|null|undefined} */
+    /**
+     * Interval (in milliseconds) at which cleanup runs automatically.
+     *
+     * If `null`, cleanup must be triggered manually.
+     *
+     * @type {number|null|undefined}
+     */
     #cleanupInterval = null;
-    /** @type {number|null|undefined} */
+    /**
+     * Maximum allowed inactivity time (in milliseconds)
+     * before a group is considered expired.
+     *
+     * @type {number|null|undefined}
+     */
     #maxIdle = null;
-    /** @type {Map<string, number[]>} */
+    /**
+     * Stores hit timestamps per group.
+     *
+     * Key: groupId
+     * Value: array of timestamps (ms)
+     *
+     * @type {Map<string, number[]>}
+     */
     groupData = new Map(); // groupId -> timestamps[]
-    /** @type {Map<string, number>} */
+    /**
+     * Stores the timestamp of the most recent activity per group.
+     *
+     * Used for expiration and cleanup logic.
+     *
+     * @type {Map<string, number>}
+     */
     lastSeen = new Map(); // groupId -> timestamp
-    /** @type {Map<string, string>} */
+    /**
+     * Maps user IDs to their assigned group IDs.
+     *
+     * @type {Map<string, string>}
+     */
     userToGroup = new Map(); // userId -> groupId
-    /** @type {Map<string, boolean>} */
+    /**
+     * Flags whether an ID represents a true group or an implicit user group.
+     *
+     * `true`  → explicit group
+     * `false` → implicit (user acting as group)
+     *
+     * @type {Map<string, boolean>}
+     */
     groupFlags = new Map(); // groupId -> boolean
     /**
+     * Per-group TTL (time-to-live) overrides.
+     *
+     * If not defined for a group, `maxIdle` is used instead.
+     *
      * @type {Map<string, number>}
-     * Stores TTL (in ms) for each groupId individually
      */
     groupTTL = new Map();
     /**
+     * Callback invoked when a group's memory limit is exceeded.
+     *
      * @type {null|OnMemoryExceeded}
      */
     #onMemoryExceeded = null;
     /**
-     * Set the callback to be triggered when a group exceeds its limit
+     * Assign a callback to be notified when a group's stored
+     * hit history exceeds the configured memory limit.
+     *
      * @param {OnMemoryExceeded} callback
      */
     setOnMemoryExceeded(callback) {
@@ -47,12 +175,14 @@ class TinyRateLimiter {
         this.#onMemoryExceeded = callback;
     }
     /**
-     * Clear the onMemoryExceeded callback
+     * Removes the memory-exceeded callback.
      */
     clearOnMemoryExceeded() {
         this.#onMemoryExceeded = null;
     }
     /**
+     * Callback invoked when a group expires and is removed.
+     *
      * @type {null|OnGroupExpired}
      */
     #onGroupExpired = null;
@@ -70,18 +200,27 @@ class TinyRateLimiter {
         this.#onGroupExpired = callback;
     }
     /**
-     * Clear the onGroupExpired callback
+     * Removes the group-expiration callback.
      */
     clearOnGroupExpired() {
         this.#onGroupExpired = null;
     }
     /**
+     * Creates a new TinyRateLimiter instance.
+     *
+     * At least one of `maxHits` or `interval` must be provided.
+     *
      * @param {Object} options
-     * @param {number|null} [options.maxMemory] - Max memory allowed
-     * @param {number} [options.maxHits] - Max interactions allowed
-     * @param {number} [options.interval] - Time window in milliseconds
-     * @param {number} [options.cleanupInterval] - Interval for automatic cleanup (ms)
-     * @param {number} [options.maxIdle=300000] - Max idle time for a user before being cleaned (ms)
+     * @param {number|null} [options.maxMemory=100000]
+     *   Maximum timestamps stored per group (memory cap).
+     * @param {number} [options.maxHits]
+     *   Maximum number of allowed hits.
+     * @param {number} [options.interval]
+     *   Sliding time window in milliseconds.
+     * @param {number} [options.cleanupInterval]
+     *   Interval (ms) for automatic cleanup execution.
+     * @param {number} [options.maxIdle=300000]
+     *   Maximum inactivity time (ms) before a group expires.
      */
     constructor({ maxHits, interval, cleanupInterval, maxIdle = 300000, maxMemory = 100000 }) {
         /** @param {number|undefined} val */
@@ -166,10 +305,14 @@ class TinyRateLimiter {
         this.groupTTL.delete(groupId);
     }
     /**
-     * Assign a userId to a groupId, with merge if user has existing data.
+     * Assigns a user to a group.
+     *
+     * If the user already has recorded hits, those hits
+     * are merged into the target group.
+     *
      * @param {string} userId
      * @param {string} groupId
-     * @throws {Error} If userId is already assigned to a different group
+     * @throws {Error} If the user belongs to another group
      */
     assignToGroup(userId, groupId) {
         const existingGroup = this.userToGroup.get(userId);
@@ -211,7 +354,11 @@ class TinyRateLimiter {
         this.groupFlags.set(groupId, true);
     }
     /**
-     * Get the groupId for a given userId
+     * Resolves the effective group ID for a user.
+     *
+     * If the user is not explicitly assigned to a group,
+     * the user ID itself is treated as the group ID.
+     *
      * @param {string} userId
      * @returns {string}
      */
@@ -219,7 +366,25 @@ class TinyRateLimiter {
         return this.userToGroup.get(userId) || userId; // fallback: use userId as own group
     }
     /**
-     * Register a hit for a specific user
+     * Registers a hit for a user and applies the sliding window logic.
+     *
+     * ⚠️ **Important usage notice**
+     * This method **must be called before** `isRateLimited(userId)`
+     * in order for rate limit checks to work correctly.
+     *
+     * ### Sliding window cleanup
+     * When `interval` is configured:
+     * - The current timestamp is added to the group's history.
+     * - All timestamps older than `now - interval` are immediately removed.
+     *
+     * This ensures that the stored history always represents
+     * the **current active window**.
+     *
+     * ### Important notes
+     * - Cleanup happens on every hit, not on a fixed schedule.
+     * - The window continuously moves forward in time.
+     * - Memory usage is naturally bounded by time, and optionally by `maxMemory`.
+     *
      * @param {string} userId
      */
     hit(userId) {
@@ -252,7 +417,22 @@ class TinyRateLimiter {
         }
     }
     /**
-     * Check if the user (via their group) is currently rate limited
+     * Checks whether a user is currently rate limited.
+     *
+     * ### Evaluation process
+     * When `interval` is defined:
+     * 1. The cutoff time is calculated as:
+     *
+     *    `Date.now() - interval`
+     *
+     * 2. Only hits newer than this cutoff are counted.
+     * 3. If `maxHits` is defined:
+     *    - The group is limited when the count exceeds `maxHits`.
+     * 4. If `maxHits` is not defined:
+     *    - Any hit within the window causes a limited state.
+     *
+     * This guarantees consistent behavior regardless of when hits occur.
+     *
      * @param {string} userId
      * @returns {boolean}
      */
@@ -389,7 +569,11 @@ class TinyRateLimiter {
         return Object.fromEntries(this.userToGroup);
     }
     /**
-     * Get the interval window in milliseconds.
+     * Returns the configured sliding window size in milliseconds.
+     *
+     * This value represents how far back in time hits are considered
+     * valid for rate limiting decisions.
+     *
      * @returns {number}
      */
     getInterval() {

package/dist/v1/libs/TinyTextDiffer.cjs

@@ -0,0 +1,288 @@
+'use strict';
+
+/**
+ * Represents the result of a single text segment comparison.
+ * @typedef {Object} DiffResult
+ * @property {string} value - The actual string content of the segment.
+ * @property {"normal"|"added"|"deleted"} type - The status of the segment relative to the comparison.
+ */
+
+/**
+ * A utility class to store a history of text strings and compute the differences
+ * between any two versions, generating a detailed diff output.
+ */
+class TinyTextDiffer {
+  /** @type {string[]} */
+  #history = [];
+
+  /** @type {boolean} */
+  #destroyed = false;
+
+  /**
+   * Retrieves a shallow copy of the current history array.
+   * @returns {string[]}
+   */
+  get history() {
+    return [...this.#history];
+  }
+
+  /**
+   * Overwrites the current history array, ensuring all elements are valid strings.
+   * @param {string[]} history
+   */
+  set history(history) {
+    if (!Array.isArray(history)) {
+      throw new TypeError('History data must be provided as an array.');
+    }
+    if (!history.every((item) => typeof item === 'string')) {
+      throw new TypeError('All items in the history array must be strings.');
+    }
+    /** @type {string[]} */
+    this.#history = [...history];
+  }
+
+  /**
+   * Gets the total number of versions currently stored in the history.
+   * @returns {number}
+   */
+  get size() {
+    return this.#history.length;
+  }
+
+  /**
+   * Initializes a new instance of TinyTextDiffer.
+   * @param {string[]} [history=[]]
+   */
+  constructor(history = []) {
+    this.history = history;
+  }
+
+  /**
+   * @throws {Error}
+   * @returns {void}
+   */
+  #checkDestroyed() {
+    if (this.#destroyed) {
+      throw new Error('Cannot perform operations on a destroyed TinyTextDiffer instance.');
+    }
+  }
+
+  /**
+   * @param {any} index
+   * @throws {TypeError}
+   * @returns {void}
+   */
+  #checkIndex(index) {
+    if (typeof index !== 'number') {
+      throw new TypeError('The provided index must be a valid number.');
+    }
+  }
+
+  /**
+   * @param {any} text
+   * @throws {TypeError}
+   * @returns {void}
+   */
+  #checkText(text) {
+    if (typeof text !== 'string') {
+      throw new TypeError('The provided text must be a valid string.');
+    }
+  }
+
+  /**
+   * Retrieves the text string at the specified index.
+   * @param {number} index
+   * @returns {string}
+   */
+  get(index) {
+    this.#checkDestroyed();
+    this.#checkIndex(index);
+    if (typeof this.#history[index] === 'undefined') {
+      throw new Error(`No text version found at index ${index}.`);
+    }
+    return this.#history[index];
+  }
+
+  /**
+   * Checks if a text string exists at the specified index.
+   * @param {number} index
+   * @returns {boolean}
+   */
+  has(index) {
+    this.#checkDestroyed();
+    this.#checkIndex(index);
+    return typeof this.#history[index] !== 'undefined';
+  }
+
+  /**
+   * Appends a new text string to the end of the history.
+   * @param {string} text
+   * @returns {void}
+   */
+  add(text) {
+    this.#checkDestroyed();
+    this.#checkText(text);
+    this.#history.push(text);
+  }
+
+  /**
+   * Removes and returns the last text string from the history.
+   * @returns {string | undefined}
+   */
+  remove() {
+    this.#checkDestroyed();
+    return this.#history.pop();
+  }
+
+  /**
+   * Inserts a text string at the specified index position.
+   * @param {number} index
+   * @param {string} text
+   * @returns {void}
+   */
+  addAt(index, text) {
+    this.#checkDestroyed();
+    this.#checkIndex(index);
+    this.#checkText(text);
+    this.#history.splice(index, 0, text);
+  }
+
+  /**
+   * Removes the text string at the specified index position.
+   * @param {number} index
+   * @returns {boolean}
+   */
+  removeAt(index) {
+    this.#checkDestroyed();
+    this.#checkIndex(index);
+    const oldSize = this.#history.length;
+    this.#history.splice(index, 1);
+    const newSize = this.#history.length;
+    return oldSize !== newSize;
+  }
+
+  /**
+   * Empties the entire history.
+   * @returns {void}
+   */
+  clear() {
+    this.#checkDestroyed();
+    this.#history = [];
+  }
+
+  /**
+   * Compares multiple pairs of text strings from the history based on their indices.
+   * Each pair of indices (e.g., index1 and index2) will produce a DiffResult array.
+   * @param {...number} indexes - An even number of indices to be compared in pairs.
+   * @returns {(DiffResult[])[]} An array of DiffResult arrays for each compared pair.
+   */
+  compare(...indexes) {
+    this.#checkDestroyed();
+
+    /** @type {number} */
+    const totalIndexes = indexes.length;
+
+    if (totalIndexes === 0 || totalIndexes % 2 !== 0) {
+      throw new Error(
+        'The compare method requires an even number of indices to form comparison pairs.',
+      );
+    }
+
+    /** @type {(DiffResult[])[]} */
+    const results = [];
+
+    for (let i = 0; i < totalIndexes; i += 2) {
+      const i2 = i + 1;
+      if (i2 > totalIndexes - 1) continue;
+      this.#checkIndex(indexes[i]);
+      this.#checkIndex(indexes[i2]);
+
+      /** @type {string} */
+      const str1 = this.#history[indexes[i]];
+      /** @type {string} */
+      const str2 = this.#history[indexes[i2]];
+
+      results.push(this._computeDiff(str1, str2));
+    }
+
+    return results;
+  }
+
+  /**
+   * Computes the Longest Common Subsequence (LCS) to generate the diff result.
+   * @private
+   * @param {string} str1
+   * @param {string} str2
+   * @returns {DiffResult[]}
+   */
+  _computeDiff(str1, str2) {
+    /** @type {number} */
+    const len1 = str1.length;
+    /** @type {number} */
+    const len2 = str2.length;
+
+    /** @type {number[][]} */
+    const matrix = Array(len1 + 1)
+      .fill(null)
+      .map(() => Array(len2 + 1).fill(0));
+
+    /** @type {number} */
+    let i = 1;
+    /** @type {number} */
+    let j = 1;
+
+    for (i = 1; i <= len1; i++) {
+      for (j = 1; j <= len2; j++) {
+        if (str1[i - 1] === str2[j - 1]) {
+          matrix[i][j] = matrix[i - 1][j - 1] + 1;
+        } else {
+          matrix[i][j] = Math.max(matrix[i - 1][j], matrix[i][j - 1]);
+        }
+      }
+    }
+
+    i = len1;
+    j = len2;
+
+    /** @type {DiffResult[]} */
+    const result = [];
+
+    while (i > 0 || j > 0) {
+      if (i > 0 && j > 0 && str1[i - 1] === str2[j - 1]) {
+        result.unshift({ value: str1[i - 1], type: 'normal' });
+        i--;
+        j--;
+      } else if (j > 0 && (i === 0 || matrix[i][j - 1] >= matrix[i - 1][j])) {
+        result.unshift({ value: str2[j - 1], type: 'added' });
+        j--;
+      } else if (i > 0 && (j === 0 || matrix[i][j - 1] < matrix[i - 1][j])) {
+        result.unshift({ value: str1[i - 1], type: 'deleted' });
+        i--;
+      }
+    }
+
+    return result.reduce((/** @type {DiffResult[]} */ acc, /** @type {DiffResult} */ curr) => {
+      /** @type {number} */
+      const lastIndex = acc.length - 1;
+
+      if (acc.length > 0 && acc[lastIndex].type === curr.type) {
+        acc[lastIndex].value += curr.value;
+      } else {
+        acc.push(curr);
+      }
+      return acc;
+    }, []);
+  }
+
+  /**
+   * Cleans up internal references and marks the instance as destroyed to prevent memory leaks.
+   * @returns {void}
+   */
+  destroy() {
+    if (this.#destroyed) return;
+    this.#history = [];
+    this.#destroyed = true;
+  }
+}
+
+module.exports = TinyTextDiffer;