tiny-essentials 1.8.5 → 1.9.0

package/dist/v1/libs/TinyRateLimiter.cjs

@@ -0,0 +1,197 @@
+'use strict';
+
+/**
+ * Class representing a flexible rate limiter per user.
+ *
+ * This rate limiter can be configured by maximum number of hits,
+ * time interval, or a combination of both. It supports automatic
+ * cleanup of inactive users to optimize memory usage.
+ *
+ * @class
+ */
+class TinyRateLimiter {
+  /**
+   * @param {Object} options
+   * @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)
+   */
+  constructor({ maxHits, interval, cleanupInterval, maxIdle = 300000 }) {
+    /** @param {number|undefined} val */
+    const isPositiveInteger = (val) =>
+      typeof val === 'number' && Number.isFinite(val) && val >= 1 && Number.isInteger(val);
+
+    const isMaxHitsValid = isPositiveInteger(maxHits);
+    const isIntervalValid = isPositiveInteger(interval);
+    const isCleanupValid = isPositiveInteger(cleanupInterval);
+    const isMaxIdleValid = isPositiveInteger(maxIdle);
+
+    if (!isMaxHitsValid && !isIntervalValid)
+      throw new Error("RateLimiter requires at least one valid option: 'maxHits' or 'interval'.");
+    if (maxHits !== undefined && !isMaxHitsValid)
+      throw new Error("'maxHits' must be a positive integer if defined.");
+    if (interval !== undefined && !isIntervalValid)
+      throw new Error("'interval' must be a positive integer in milliseconds if defined.");
+    if (cleanupInterval !== undefined && !isCleanupValid)
+      throw new Error("'cleanupInterval' must be a positive integer in milliseconds if defined.");
+    if (!isMaxIdleValid) throw new Error("'maxIdle' must be a positive integer in milliseconds.");
+
+    this.maxHits = isMaxHitsValid ? maxHits : null;
+    this.interval = isIntervalValid ? interval : null;
+    this.cleanupInterval = isCleanupValid ? cleanupInterval : null;
+    this.maxIdle = maxIdle;
+
+    /** @type {Map<string, number[]>} */
+    this.userData = new Map();
+
+    /** @type {Map<string, number>} */
+    this.lastSeen = new Map();
+
+    // Start automatic cleanup only if cleanupInterval is valid
+    if (this.cleanupInterval !== null)
+      this._cleanupTimer = setInterval(() => this._cleanup(), this.cleanupInterval);
+  }
+
+  /**
+   * Get the interval window in milliseconds.
+   *
+   * @returns {number} The interval value.
+   * @throws {Error} If interval is not a valid finite number.
+   */
+  getInterval() {
+    if (typeof this.interval !== 'number' || !Number.isFinite(this.interval))
+      throw new Error("'interval' is not a valid finite number.");
+    return this.interval;
+  }
+
+  /**
+   * Get the maximum number of allowed hits.
+   *
+   * @returns {number} The maxHits value.
+   * @throws {Error} If maxHits is not a valid finite number.
+   */
+  getMaxHits() {
+    if (typeof this.maxHits !== 'number' || !Number.isFinite(this.maxHits)) {
+      throw new Error("'maxHits' is not a valid finite number.");
+    }
+    return this.maxHits;
+  }
+
+  /**
+   * Register a hit for a specific user
+   * @param {string} userId
+   */
+  hit(userId) {
+    const now = Date.now();
+
+    if (!this.userData.has(userId)) {
+      this.userData.set(userId, []);
+    }
+
+    const history = this.userData.get(userId);
+    if (!history) throw new Error(`No data found for userId: ${userId}`);
+
+    history.push(now);
+    this.lastSeen.set(userId, now);
+
+    // Clean up old entries
+    if (this.interval !== null) {
+      const interval = this.getInterval();
+      const cutoff = now - interval;
+      while (history.length && history[0] < cutoff) {
+        history.shift();
+      }
+    }
+
+    // Optional: keep only the last N entries for memory optimization
+    if (this.maxHits !== null) {
+      const maxHits = this.getMaxHits();
+      if (history.length > maxHits) {
+        history.splice(0, history.length - maxHits);
+      }
+    }
+  }
+
+  /**
+   * Check if the user is currently rate limited
+   * @param {string} userId
+   * @returns {boolean}
+   */
+  isRateLimited(userId) {
+    const now = Date.now();
+
+    if (!this.userData.has(userId)) return false;
+
+    const history = this.userData.get(userId);
+    if (!history) throw new Error(`No data found for userId: ${userId}`);
+
+    if (this.interval !== null) {
+      const interval = this.getInterval();
+      const recent = history.filter((t) => t > now - interval);
+      if (this.maxHits !== null) {
+        return recent.length >= this.getMaxHits();
+      }
+      return recent.length > 0;
+    }
+
+    if (this.maxHits !== null) {
+      return history.length >= this.getMaxHits();
+    }
+
+    return false;
+  }
+
+  /**
+   * Manually reset user data
+   * @param {string} userId
+   */
+  reset(userId) {
+    this.userData.delete(userId);
+    this.lastSeen.delete(userId);
+  }
+
+  /**
+   * Set hit timestamps for a user
+   * @param {string} userId
+   * @param {number[]} timestamps
+   */
+  setData(userId, timestamps) {
+    this.userData.set(userId, timestamps);
+    this.lastSeen.set(userId, Date.now());
+  }
+
+  /**
+   * Get timestamps from user
+   * @param {string} userId
+   * @returns {number[]}
+   */
+  getData(userId) {
+    return this.userData.get(userId) || [];
+  }
+
+  /**
+   * Cleanup old/inactive users
+   * @private
+   */
+  _cleanup() {
+    const now = Date.now();
+    for (const [userId, last] of this.lastSeen.entries()) {
+      if (now - last > this.maxIdle) {
+        this.userData.delete(userId);
+        this.lastSeen.delete(userId);
+      }
+    }
+  }
+
+  /**
+   * Destroy the rate limiter, stopping all intervals
+   */
+  destroy() {
+    if (this._cleanupTimer) clearInterval(this._cleanupTimer);
+    this.userData.clear();
+    this.lastSeen.clear();
+  }
+}
+
+module.exports = TinyRateLimiter;

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

@@ -0,0 +1,86 @@
+export default TinyRateLimiter;
+/**
+ * Class representing a flexible rate limiter per user.
+ *
+ * This rate limiter can be configured by maximum number of hits,
+ * time interval, or a combination of both. It supports automatic
+ * cleanup of inactive users to optimize memory usage.
+ *
+ * @class
+ */
+declare class TinyRateLimiter {
+    /**
+     * @param {Object} options
+     * @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)
+     */
+    constructor({ maxHits, interval, cleanupInterval, maxIdle }: {
+        maxHits?: number | undefined;
+        interval?: number | undefined;
+        cleanupInterval?: number | undefined;
+        maxIdle?: number | undefined;
+    });
+    maxHits: number | null | undefined;
+    interval: number | null | undefined;
+    cleanupInterval: number | null | undefined;
+    maxIdle: number;
+    /** @type {Map<string, number[]>} */
+    userData: Map<string, number[]>;
+    /** @type {Map<string, number>} */
+    lastSeen: Map<string, number>;
+    _cleanupTimer: NodeJS.Timeout | undefined;
+    /**
+     * Get the interval window in milliseconds.
+     *
+     * @returns {number} The interval value.
+     * @throws {Error} If interval is not a valid finite number.
+     */
+    getInterval(): number;
+    /**
+     * Get the maximum number of allowed hits.
+     *
+     * @returns {number} The maxHits value.
+     * @throws {Error} If maxHits is not a valid finite number.
+     */
+    getMaxHits(): number;
+    /**
+     * Register a hit for a specific user
+     * @param {string} userId
+     */
+    hit(userId: string): void;
+    /**
+     * Check if the user is currently rate limited
+     * @param {string} userId
+     * @returns {boolean}
+     */
+    isRateLimited(userId: string): boolean;
+    /**
+     * Manually reset user data
+     * @param {string} userId
+     */
+    reset(userId: string): void;
+    /**
+     * Set hit timestamps for a user
+     * @param {string} userId
+     * @param {number[]} timestamps
+     */
+    setData(userId: string, timestamps: number[]): void;
+    /**
+     * Get timestamps from user
+     * @param {string} userId
+     * @returns {number[]}
+     */
+    getData(userId: string): number[];
+    /**
+     * Cleanup old/inactive users
+     * @private
+     */
+    private _cleanup;
+    /**
+     * Destroy the rate limiter, stopping all intervals
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=TinyRateLimiter.d.mts.map

package/dist/v1/libs/TinyRateLimiter.mjs

@@ -0,0 +1,173 @@
+/**
+ * Class representing a flexible rate limiter per user.
+ *
+ * This rate limiter can be configured by maximum number of hits,
+ * time interval, or a combination of both. It supports automatic
+ * cleanup of inactive users to optimize memory usage.
+ *
+ * @class
+ */
+class TinyRateLimiter {
+    /**
+     * @param {Object} options
+     * @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)
+     */
+    constructor({ maxHits, interval, cleanupInterval, maxIdle = 300000 }) {
+        /** @param {number|undefined} val */
+        const isPositiveInteger = (val) => typeof val === 'number' && Number.isFinite(val) && val >= 1 && Number.isInteger(val);
+        const isMaxHitsValid = isPositiveInteger(maxHits);
+        const isIntervalValid = isPositiveInteger(interval);
+        const isCleanupValid = isPositiveInteger(cleanupInterval);
+        const isMaxIdleValid = isPositiveInteger(maxIdle);
+        if (!isMaxHitsValid && !isIntervalValid)
+            throw new Error("RateLimiter requires at least one valid option: 'maxHits' or 'interval'.");
+        if (maxHits !== undefined && !isMaxHitsValid)
+            throw new Error("'maxHits' must be a positive integer if defined.");
+        if (interval !== undefined && !isIntervalValid)
+            throw new Error("'interval' must be a positive integer in milliseconds if defined.");
+        if (cleanupInterval !== undefined && !isCleanupValid)
+            throw new Error("'cleanupInterval' must be a positive integer in milliseconds if defined.");
+        if (!isMaxIdleValid)
+            throw new Error("'maxIdle' must be a positive integer in milliseconds.");
+        this.maxHits = isMaxHitsValid ? maxHits : null;
+        this.interval = isIntervalValid ? interval : null;
+        this.cleanupInterval = isCleanupValid ? cleanupInterval : null;
+        this.maxIdle = maxIdle;
+        /** @type {Map<string, number[]>} */
+        this.userData = new Map();
+        /** @type {Map<string, number>} */
+        this.lastSeen = new Map();
+        // Start automatic cleanup only if cleanupInterval is valid
+        if (this.cleanupInterval !== null)
+            this._cleanupTimer = setInterval(() => this._cleanup(), this.cleanupInterval);
+    }
+    /**
+     * Get the interval window in milliseconds.
+     *
+     * @returns {number} The interval value.
+     * @throws {Error} If interval is not a valid finite number.
+     */
+    getInterval() {
+        if (typeof this.interval !== 'number' || !Number.isFinite(this.interval))
+            throw new Error("'interval' is not a valid finite number.");
+        return this.interval;
+    }
+    /**
+     * Get the maximum number of allowed hits.
+     *
+     * @returns {number} The maxHits value.
+     * @throws {Error} If maxHits is not a valid finite number.
+     */
+    getMaxHits() {
+        if (typeof this.maxHits !== 'number' || !Number.isFinite(this.maxHits)) {
+            throw new Error("'maxHits' is not a valid finite number.");
+        }
+        return this.maxHits;
+    }
+    /**
+     * Register a hit for a specific user
+     * @param {string} userId
+     */
+    hit(userId) {
+        const now = Date.now();
+        if (!this.userData.has(userId)) {
+            this.userData.set(userId, []);
+        }
+        const history = this.userData.get(userId);
+        if (!history)
+            throw new Error(`No data found for userId: ${userId}`);
+        history.push(now);
+        this.lastSeen.set(userId, now);
+        // Clean up old entries
+        if (this.interval !== null) {
+            const interval = this.getInterval();
+            const cutoff = now - interval;
+            while (history.length && history[0] < cutoff) {
+                history.shift();
+            }
+        }
+        // Optional: keep only the last N entries for memory optimization
+        if (this.maxHits !== null) {
+            const maxHits = this.getMaxHits();
+            if (history.length > maxHits) {
+                history.splice(0, history.length - maxHits);
+            }
+        }
+    }
+    /**
+     * Check if the user is currently rate limited
+     * @param {string} userId
+     * @returns {boolean}
+     */
+    isRateLimited(userId) {
+        const now = Date.now();
+        if (!this.userData.has(userId))
+            return false;
+        const history = this.userData.get(userId);
+        if (!history)
+            throw new Error(`No data found for userId: ${userId}`);
+        if (this.interval !== null) {
+            const interval = this.getInterval();
+            const recent = history.filter((t) => t > now - interval);
+            if (this.maxHits !== null) {
+                return recent.length >= this.getMaxHits();
+            }
+            return recent.length > 0;
+        }
+        if (this.maxHits !== null) {
+            return history.length >= this.getMaxHits();
+        }
+        return false;
+    }
+    /**
+     * Manually reset user data
+     * @param {string} userId
+     */
+    reset(userId) {
+        this.userData.delete(userId);
+        this.lastSeen.delete(userId);
+    }
+    /**
+     * Set hit timestamps for a user
+     * @param {string} userId
+     * @param {number[]} timestamps
+     */
+    setData(userId, timestamps) {
+        this.userData.set(userId, timestamps);
+        this.lastSeen.set(userId, Date.now());
+    }
+    /**
+     * Get timestamps from user
+     * @param {string} userId
+     * @returns {number[]}
+     */
+    getData(userId) {
+        return this.userData.get(userId) || [];
+    }
+    /**
+     * Cleanup old/inactive users
+     * @private
+     */
+    _cleanup() {
+        const now = Date.now();
+        for (const [userId, last] of this.lastSeen.entries()) {
+            if (now - last > this.maxIdle) {
+                this.userData.delete(userId);
+                this.lastSeen.delete(userId);
+            }
+        }
+    }
+    /**
+     * Destroy the rate limiter, stopping all intervals
+     */
+    destroy() {
+        if (this._cleanupTimer)
+            clearInterval(this._cleanupTimer);
+        this.userData.clear();
+        this.lastSeen.clear();
+    }
+}
+export default TinyRateLimiter;

package/docs/README.md

@@ -23,6 +23,7 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🗂️ **[TinyPromiseQueue](./libs/TinyPromiseQueue.md)** — A class that allows sequential execution of asynchronous tasks, supporting task delays, cancellation, and queue management.
 - 🏅 **[TinyLevelUp](./libs/TinyLevelUp.md)** — A class to manage user level-up logic based on experience points, providing methods for experience validation, addition, removal, and calculation.
 - 🎨 **[ColorSafeStringify](./libs/ColorSafeStringify.md)** — A utility for applying customizable ANSI colors to JSON strings in terminal outputs, supporting presets and fine-grained type-based highlighting.
+- 🚦 **[TinyRateLimiter](./libs/TinyRateLimiter.md)** — A flexible per-user rate limiter supporting time windows, hit caps, and automatic cleanup of inactive users.
 
 ---
 

package/docs/libs/TinyRateLimiter.md

@@ -0,0 +1,156 @@
+# 🧠 `TinyRateLimiter` – A Simple Per-User Rate Limiter
+
+The `TinyRateLimiter` is a flexible and lightweight JavaScript class designed to help you limit actions (like requests or commands) per user. You can define rules like **maximum hits**, **time windows**, and benefit from automatic memory cleanup. ✨
+
+---
+
+## 📦 Constructor
+
+```js
+new TinyRateLimiter(options)
+```
+
+### 🔧 Options
+
+| Option            | Type     | Default     | Description                                    |
+| ----------------- | -------- | ----------- | ---------------------------------------------- |
+| `maxHits`         | `number` | `undefined` | Max number of hits per user before blocking 🚧 |
+| `interval`        | `number` | `undefined` | Time window in milliseconds ⏱️                 |
+| `cleanupInterval` | `number` | `undefined` | Interval to auto-clean inactive users 🧹       |
+| `maxIdle`         | `number` | `300000`    | Max idle time per user before cleanup 💤       |
+
+> ⚠️ At least one of `maxHits` or `interval` must be defined.
+
+---
+
+## 📋 Methods
+
+### 🚀 `hit(userId: string): void`
+
+Registers a hit for the given `userId`.
+
+```js
+rateLimiter.hit("user123");
+```
+
+It tracks timestamps internally and automatically cleans old entries based on `interval` and `maxHits`.
+
+---
+
+### ❌ `isRateLimited(userId: string): boolean`
+
+Checks if the given `userId` is currently rate limited.
+
+```js
+if (rateLimiter.isRateLimited("user123")) {
+  console.log("Too many actions! Please slow down.");
+}
+```
+
+---
+
+### 🔁 `reset(userId: string): void`
+
+Resets all stored data for the given user.
+
+```js
+rateLimiter.reset("user123");
+```
+
+---
+
+### 🛠️ `setData(userId: string, timestamps: number[]): void`
+
+Sets the hit timestamps for a specific user. Useful for restoring or mocking state.
+
+```js
+rateLimiter.setData("user123", [Date.now() - 1000, Date.now()]);
+```
+
+---
+
+### 📥 `getData(userId: string): number[]`
+
+Returns all hit timestamps for a given user.
+
+```js
+const hits = rateLimiter.getData("user123");
+console.log(hits); // [timestamp1, timestamp2, ...]
+```
+
+---
+
+### 🧠 `getMaxHits(): number`
+
+Returns the configured `maxHits` value, or throws if invalid.
+
+---
+
+### ⏳ `getInterval(): number`
+
+Returns the configured `interval` value, or throws if invalid.
+
+---
+
+### 🧼 `destroy(): void`
+
+Stops internal timers and clears all stored data. Ideal for cleanup in tests or long-running apps.
+
+```js
+rateLimiter.destroy();
+```
+
+---
+
+## 🧽 Automatic Cleanup
+
+Inactive users are automatically removed every `cleanupInterval` milliseconds if they haven't had any hits for longer than `maxIdle`.
+
+This helps reduce memory usage and keeps your limiter lean and clean! 🪶
+
+---
+
+## 💥 Errors
+
+The constructor will throw if:
+
+* Neither `maxHits` nor `interval` are provided.
+* Any of the values are not positive integers.
+
+---
+
+## 🧪 Example Usage
+
+```js
+const limiter = new TinyRateLimiter({
+  maxHits: 5,
+  interval: 10000,
+  cleanupInterval: 60000,
+  maxIdle: 120000
+});
+
+limiter.hit("user42");
+
+if (limiter.isRateLimited("user42")) {
+  console.log("Rate limited! 🛑");
+} else {
+  console.log("Action allowed ✅");
+}
+```
+
+---
+
+## 🌈 Summary
+
+| Feature              | Support |
+| -------------------- | ------- |
+| Per-user tracking    | ✅       |
+| Max hits             | ✅       |
+| Time window interval | ✅       |
+| Automatic cleanup    | ✅       |
+| Manual data control  | ✅       |
+| Lightweight + fast   | ✅       |
+
+---
+
+Made with 💜 to protect your app from spammers and abusers — in a cute and efficient way! 😄

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.8.5",
+  "version": "1.9.0",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",
@@ -10,6 +10,7 @@
     "test:mjs:promisequeue": "node test/index.mjs promiseQueue",
     "test:mjs:objtype": "node test/index.mjs objType",
     "test:mjs:jsoncolor": "node test/index.mjs colorStringify",
+    "test:mjs:ratelimit": "node test/index.mjs rateLimit",
     "fix:prettier": "npm run fix:prettier:src && npm run fix:prettier:test && npm run fix:prettier:rollup.config && npm run fix:prettier:webpack.config",
     "fix:prettier:src": "prettier --write ./src/*",
     "fix:prettier:test": "prettier --write ./test/*",