tiny-essentials 1.8.5 → 1.9.1

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/TinyLevelUp.md

@@ -1,108 +1,248 @@
+# 📚 TinyLevelUp Documentation
 
-### TinyLevelUp 🎮
+A lightweight XP-based leveling system for managing user experience and levels. Great for games, communities, or reward-based applications! 🎮✨
 
-This class manages user level-up logic based on experience points. It provides methods to handle experience points (exp) adjustments, level progression, and random experience generation.
+---
+
+## 📐 Type Definitions
+
+### `UserEditor` ✍️
 
-#### Constructor 🛠️
+Represents the structure of a user object used in the leveling system.
 
-- **`constructor(giveExp: number, expLevel: number)`**  
-  Initializes the class with the base experience value for random experience generation and the base experience required to level up.
+```ts
+{
+  exp: number;       // Current experience points of the user
+  level: number;     // Current level of the user
+  totalExp: number;  // Total accumulated experience
+}
+```
+
+---
 
-  - `giveExp` (`number`): The base experience value used for random experience generation. 🎲
-  - `expLevel` (`number`): The base experience required to level up for each level. 📈
+## 🏗️ Class: `TinyLevelUp`
 
-#### Methods 🔧
+Handles experience logic, leveling up/down, validation, and XP generation.
 
-- **`expValidator(user: UserEditor)`**  
-  Validates and adjusts the user's level based on their current experience. If the user's experience is above or below the required threshold, their level is adjusted accordingly. ⚖️
+### 🆕 Constructor
 
-  - `user` (`UserEditor`): The user object containing `exp` (experience), `level` (current level), and `totalExp` (total experience). 👤
-  
-  - **Returns**: `UserResult` - The updated user object. 🔄
+```ts
+new TinyLevelUp(giveExp: number, expLevel: number)
+```
 
-- **`getTotalExp(user: { exp: number, level: number })`**  
-  Calculates the total experience based on the user's level and experience. 📊
+* `giveExp`: Base XP value for random XP generation 🎲
+* `expLevel`: Base XP required per level up 🔺
 
-  - `user` (`Object`): The user object containing `exp` (experience) and `level` (level). 👤
-  
-  - **Returns**: `number` - The total experience of the user. 🔢
+---
 
-- **`expGenerator(multi: number = 1)`**  
-  Generates random experience points based on a configured multiplier. 🎲
+## 🧰 Methods
 
-  - `multi` (`number`): A multiplier for experience generation. Default is `1`. 💯
+### ➕ `createUser()`
 
-  - **Returns**: `number` - The generated experience points. 💥
+Creates a fresh user at level 1 with no XP.
 
-- **`progress(user: { level: number })`**  
-  Gets the experience points required to reach the next level. ⏩
+```ts
+createUser(): UserEditor
+```
 
-  - `user` (`Object`): The user object containing the `level`. 👤
+---
 
-  - **Returns**: `number` - The experience required for the next level. 📈
+### 🔎 `validateUser(user)`
 
-- **`getProgress(user: { level: number })`**  
-  An alias for `progress`. Returns the experience points required to reach the next level. ⏩
+Throws an error if the user object is malformed or contains invalid values.
 
-  - `user` (`Object`): The user object containing the `level`. 👤
+```ts
+validateUser(user: UserEditor): void
+```
 
-  - **Returns**: `number` - The experience required for the next level. 📈
+🚨 Throws if:
 
-- **`set(user: UserEditor, value: number)`**  
-  Sets the user's experience value and adjusts their level if necessary. 📝
+* `exp`, `level`, or `totalExp` are not valid numbers.
 
-  - `user` (`UserEditor`): The user object containing `exp`, `level`, and `totalExp`. 👤
-  - `value` (`number`): The new experience value to set for the user. 💡
+---
 
-  - **Returns**: `UserResult` - The updated user object. 🔄
+### ✅ `isValidUser(user)`
 
-- **`give(user: UserEditor, extraExp: number = 0, type: 'add' | 'extra' = 'add', multi: number = 1)`**  
-  Adds experience to the user and adjusts their level if necessary. Experience can be added with or without a multiplier. ➕
+Checks if the given user object is valid (without throwing errors).
 
-  - `user` (`UserEditor`): The user object containing `exp`, `level`, and `totalExp`. 👤
-  - `extraExp` (`number`): Additional experience to be added. 💯
-  - `type` (`'add' | 'extra'`): Type of experience addition. `'add'` adds random experience, while `'extra'` adds specified experience. 🔧
-  - `multi` (`number`): Multiplier for experience generation. Default is `1`. 💥
+```ts
+isValidUser(user: UserEditor): boolean
+```
 
-  - **Returns**: `UserResult` - The updated user object. 🔄
+---
 
-- **`remove(user: UserEditor, extraExp: number = 0, type: 'add' | 'extra' = 'add', multi: number = 1)`**  
-  Removes experience from the user and adjusts their level if necessary. Experience can be removed with or without a multiplier. ➖
+### 🎁 `getGiveExpBase()`
 
-  - `user` (`UserEditor`): The user object containing `exp`, `level`, and `totalExp`. 👤
-  - `extraExp` (`number`): Additional experience to be removed. 💣
-  - `type` (`'add' | 'extra'`): Type of experience removal. `'add'` removes random experience, while `'extra'` removes specified experience. 🔧
-  - `multi` (`number`): Multiplier for experience generation. Default is `1`. 💥
+Returns the base XP value used for generating XP.
 
-  - **Returns**: `UserResult` - The updated user object. 🔄
+```ts
+getGiveExpBase(): number
+```
 
-### Type Definitions 📚
+---
 
-- **`UserResult`**  
-  Represents the structure of a user object after level validation. 🧑‍💻
+### 🧮 `getExpLevelBase()`
 
-  - `exp` (`number`): The user's experience. 🎯
-  - `level` (`number`): The user's current level. 🏆
-  - `totalExp` (`number`): The user's total experience. 📊
+Returns the base XP required per level.
 
-- **`UserEditor`**  
-  Represents the user object before level validation. 🔧
+```ts
+getExpLevelBase(): number
+```
 
-  - `exp` (`number`): The user's experience. 🎯
-  - `level` (`number`): The user's current level. 🏆
-  - `totalExp` (`any`): The user's total experience (can be calculated using `getTotalExp`). 📊
+---
 
-### Example Usage 💡
+### ⚖️ `expValidator(user)`
 
-```javascript
-const user = { exp: 50, level: 1, totalExp: 50 };
-const levelUpSystem = new TinyLevelUp(100, 1000);
+Validates and adjusts user level based on current XP.
 
-// Add experience and check updated user stats
-levelUpSystem.give(user);
-console.log(user); // { exp: 112, level: 1, totalExp: 112 }
+```ts
+expValidator(user: UserEditor): UserEditor
 ```
 
+* Levels up/down the user if needed.
+* Applies "extra" XP appropriately.
+
 ---
 
-This class can be used to manage user experience points and level-ups in any system requiring user progression logic. 🚀
+### 📊 `getTotalExp(user)`
+
+Calculates total accumulated XP (including current level and progress).
+
+```ts
+getTotalExp(user: UserEditor): number
+```
+
+---
+
+### 🎲 `expGenerator(multi = 1)`
+
+Generates a random XP value based on the multiplier.
+
+```ts
+expGenerator(multi?: number): number
+```
+
+---
+
+### ⏩ `progress(user)`
+
+Returns XP required to reach the next level.
+
+```ts
+progress(user: UserEditor): number
+```
+
+---
+
+### 📈 `getProgress(user)`
+
+Alias for `progress()`. Returns XP needed to reach the next level.
+
+```ts
+getProgress(user: UserEditor): number
+```
+
+---
+
+### ✍️ `set(user, value)`
+
+Sets the current XP for the user and updates their level if necessary.
+
+```ts
+set(user: UserEditor, value: number): UserEditor
+```
+
+---
+
+### ⬆️ `give(user, extraExp?, type?, multi?)`
+
+Adds experience to the user and auto-levels if needed.
+
+```ts
+give(
+  user: UserEditor,
+  extraExp?: number,
+  type?: 'add' | 'extra',
+  multi?: number
+): UserEditor
+```
+
+* `type = 'add'`: Adds generated XP + extra
+* `type = 'extra'`: Adds only extra
+
+---
+
+### ⬇️ `remove(user, extraExp?, type?, multi?)`
+
+Removes experience from the user and updates their level if necessary.
+
+```ts
+remove(
+  user: UserEditor,
+  extraExp?: number,
+  type?: 'add' | 'extra',
+  multi?: number
+): UserEditor
+```
+
+* `type = 'add'`: Removes generated XP + extra
+* `type = 'extra'`: Removes only extra
+
+---
+
+### 🔍 `getMissingExp(user)`
+
+**Description:**
+Calculates how much experience is missing for the user to reach the next level.
+
+---
+
+**Parameters:**
+
+* `user` (UserEditor) — The user object containing experience and level properties.
+
+---
+
+**Returns:**
+
+* `number` — The amount of experience points still needed to level up.
+
+---
+
+**Throws:**
+
+* `Error` — If any property (`exp`, `level`, or `totalExp`) in the `user` object is not a valid number. ⚠️
+
+---
+
+**Example usage:**
+
+```js
+const missing = tinyLevelUp.getMissingExp(user);
+console.log(`You need ${missing} more XP to level up! 🚀`);
+```
+
+---
+
+## 🌟 Example Usage
+
+```js
+import TinyLevelUp from './TinyLevelUp.js';
+
+const levelSystem = new TinyLevelUp(15, 10);
+const user = levelSystem.createUser();
+
+levelSystem.give(user); // Adds random XP
+console.log(user);
+
+levelSystem.set(user, 50); // Manually set XP
+console.log(user.level);
+```
+
+---
+
+## 💬 Notes
+
+* All methods throw if invalid values are passed ❗
+* You can use `isValidUser()` for safe checks without exceptions 🛡️
+* This system is deterministic and extendable!