tiny-essentials 1.8.4 → 1.9.0

package/dist/legacy/libs/rule3.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 /**
  * Rule of Three utility.
  * Performs direct or inverse proportional calculation.

package/dist/legacy/momentjs/getAge.cjs

@@ -2,9 +2,6 @@
 
 var moment = require('moment');
 
-// @ts-nocheck
-
-
 /**
  * Calculates the age based on the given date.
  *

package/dist/legacy/momentjs/getAge.d.mts

@@ -6,4 +6,5 @@
  * @returns {number|null} The age in years, or null if `timeData` is not provided.
  */
 export default function getAge(timeData?: number | string, now?: moment.Moment | null): number | null;
+import moment from 'moment';
 //# sourceMappingURL=getAge.d.mts.map

package/dist/legacy/momentjs/getAge.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import moment from 'moment';
 /**
  * Calculates the age based on the given date.

package/dist/legacy/momentjs/index.cjs

@@ -3,7 +3,7 @@
 var timeDuration = require('./timeDuration.cjs');
 var getAge = require('./getAge.cjs');
 
-// @ts-nocheck
+
 
 exports.timeDuration = timeDuration;
 exports.getAge = getAge;

package/dist/legacy/momentjs/index.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import timeDuration from './timeDuration.mjs';
 import getAge from './getAge.mjs';
 export { timeDuration, getAge };

package/dist/legacy/momentjs/timeDuration.cjs

@@ -2,9 +2,6 @@
 
 var moment = require('moment');
 
-// @ts-nocheck
-
-
 /**
  * Calculates the time duration between the current time and a given time offset.
  *
@@ -19,6 +16,7 @@ function timeDuration(timeData = 0, durationType = 'asSeconds', now = null) {
     if (!now) now = moment();
 
     var duration = moment.duration(now.clone().add(timeData, 'milliseconds').diff(now.clone()));
+    // @ts-ignore
     const result = duration[durationType]();
 
     // Complete

package/dist/legacy/momentjs/timeDuration.d.mts

@@ -7,4 +7,5 @@
  * @returns {number|null} The calculated duration in the specified unit (default: seconds), or `null` if `timeData` is not provided.
  */
 export default function timeDuration(timeData?: number, durationType?: string, now?: moment.Moment | null): number | null;
+import moment from 'moment';
 //# sourceMappingURL=timeDuration.d.mts.map

package/dist/legacy/momentjs/timeDuration.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import moment from 'moment';
 /**
  * Calculates the time duration between the current time and a given time offset.
@@ -14,6 +13,7 @@ export default function timeDuration(timeData = 0, durationType = 'asSeconds', n
         if (!now)
             now = moment();
         var duration = moment.duration(now.clone().add(timeData, 'milliseconds').diff(now.clone()));
+        // @ts-ignore
         const result = duration[durationType]();
         // Complete
         return result;

package/dist/legacy/socket.io/antiFlood/index.cjs

@@ -3,7 +3,7 @@
 var install = require('./install.cjs');
 var verify = require('./verify.cjs');
 
-// @ts-nocheck
+
 
 exports.install = install;
 exports.verify = verify;

package/dist/legacy/socket.io/antiFlood/index.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import install from './install.mjs';
 import verify from './verify.mjs';
 export { verify, install };

package/dist/legacy/socket.io/antiFlood/install.cjs

@@ -2,21 +2,19 @@
 
 var userIP = require('../../http/userIP.cjs');
 
-// @ts-nocheck
-
-
 /**
  * Installs the authorization middleware for socket connections.
  *
  * This middleware checks the user's IP address and allows or denies the socket connection based on whether
  * the IP is in the block list or not.
  *
- * @param {Record<string, any>} io - The Socket.IO server instance.
- * @param {Record<string, any>} ioCache - The cache object containing blocked IPs.
+ * @param {*} io - The Socket.IO server instance.
+ * @param {Object} ioCache - The cache object containing blocked IPs.
  * @param {Array<*>} ioCache.blocklick - The list of blocked IP addresses.
  * @returns {void} This function does not return a value, it just sets the authorization logic for socket connections.
  */
 function install(io, ioCache) {
+  // @ts-ignore
   io.set('authorization', function (socket, callback) {
     // Get User IP
     const ip = userIP(socket.handshake);

package/dist/legacy/socket.io/antiFlood/install.d.mts

@@ -4,10 +4,12 @@
  * This middleware checks the user's IP address and allows or denies the socket connection based on whether
  * the IP is in the block list or not.
  *
- * @param {Record<string, any>} io - The Socket.IO server instance.
- * @param {Record<string, any>} ioCache - The cache object containing blocked IPs.
+ * @param {*} io - The Socket.IO server instance.
+ * @param {Object} ioCache - The cache object containing blocked IPs.
  * @param {Array<*>} ioCache.blocklick - The list of blocked IP addresses.
  * @returns {void} This function does not return a value, it just sets the authorization logic for socket connections.
  */
-export default function install(io: Record<string, any>, ioCache: Record<string, any>): void;
+export default function install(io: any, ioCache: {
+    blocklick: Array<any>;
+}): void;
 //# sourceMappingURL=install.d.mts.map

package/dist/legacy/socket.io/antiFlood/install.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import userIp from '../../http/userIP.mjs';
 /**
  * Installs the authorization middleware for socket connections.
@@ -6,12 +5,13 @@ import userIp from '../../http/userIP.mjs';
  * This middleware checks the user's IP address and allows or denies the socket connection based on whether
  * the IP is in the block list or not.
  *
- * @param {Record<string, any>} io - The Socket.IO server instance.
- * @param {Record<string, any>} ioCache - The cache object containing blocked IPs.
+ * @param {*} io - The Socket.IO server instance.
+ * @param {Object} ioCache - The cache object containing blocked IPs.
  * @param {Array<*>} ioCache.blocklick - The list of blocked IP addresses.
  * @returns {void} This function does not return a value, it just sets the authorization logic for socket connections.
  */
 export default function install(io, ioCache) {
+    // @ts-ignore
     io.set('authorization', function (socket, callback) {
         // Get User IP
         const ip = userIp(socket.handshake);

package/dist/legacy/socket.io/antiFlood/verify.cjs

@@ -2,10 +2,14 @@
 
 var userIP = require('../../http/userIP.cjs');
 
-// @ts-nocheck
+/** @typedef {Record<string, { timeout: number, tries: number }>} FloodTimeout */
 
+/**
+ * Panel
+ *
+ * @type {FloodTimeout}
+ */
 
-// Panel
 const floodPanel = {};
 
 /**
@@ -27,14 +31,14 @@ setInterval(function () {
  * If the attempts exceed a threshold, the IP is temporarily banned and disconnected.
  *
  * @param {Record<string, any>} socket - The socket object representing the connection.
- * @param {Record<string, any>} ioCache - The cache object that holds the blocklist and flood panel data.
+ * @param {Object} ioCache - The cache object that holds the blocklist and flood panel data.
  * @param {Array<*>} ioCache.blocklick - The list of blocked IPs.
- * @param {Record<string, any>} floodPanel - The object tracking flooding attempts and timeouts for each IP.
  * @returns {void} This function does not return anything, it modifies the floodPanel and blocklist.
  */
 function verify(socket, ioCache) {
   // Get User IP
-  const ip = userIP(socket.handshake);
+  const ipData = userIP(socket.handshake);
+  const ip = ipData.value ? ipData.value[0] : '';
 
   /**
    * Verifies the IP for flooding attempts and manages timeout and blocklist.
@@ -71,7 +75,7 @@ function verify(socket, ioCache) {
 
   // Catch-all Event Listener
   var onevent = socket.onevent;
-  socket.onevent = function (packet) {
+  socket.onevent = function (/** @type {{ data: string[]; }} */ packet) {
     var args = packet.data || [];
     onevent.call(this, packet); // original call
     packet.data = ['*'].concat(args);

package/dist/legacy/socket.io/antiFlood/verify.d.mts

@@ -5,10 +5,15 @@
  * If the attempts exceed a threshold, the IP is temporarily banned and disconnected.
  *
  * @param {Record<string, any>} socket - The socket object representing the connection.
- * @param {Record<string, any>} ioCache - The cache object that holds the blocklist and flood panel data.
+ * @param {Object} ioCache - The cache object that holds the blocklist and flood panel data.
  * @param {Array<*>} ioCache.blocklick - The list of blocked IPs.
- * @param {Record<string, any>} floodPanel - The object tracking flooding attempts and timeouts for each IP.
  * @returns {void} This function does not return anything, it modifies the floodPanel and blocklist.
  */
-export default function verify(socket: Record<string, any>, ioCache: Record<string, any>): void;
+export default function verify(socket: Record<string, any>, ioCache: {
+    blocklick: Array<any>;
+}): void;
+export type FloodTimeout = Record<string, {
+    timeout: number;
+    tries: number;
+}>;
 //# sourceMappingURL=verify.d.mts.map

package/dist/legacy/socket.io/antiFlood/verify.mjs

@@ -1,6 +1,10 @@
-// @ts-nocheck
 import userIp from '../../http/userIP.mjs';
-// Panel
+/** @typedef {Record<string, { timeout: number, tries: number }>} FloodTimeout */
+/**
+ * Panel
+ *
+ * @type {FloodTimeout}
+ */
 const floodPanel = {};
 /**
  * Periodically decrements the timeout for each IP in the flood panel and removes expired entries.
@@ -21,14 +25,14 @@ setInterval(function () {
  * If the attempts exceed a threshold, the IP is temporarily banned and disconnected.
  *
  * @param {Record<string, any>} socket - The socket object representing the connection.
- * @param {Record<string, any>} ioCache - The cache object that holds the blocklist and flood panel data.
+ * @param {Object} ioCache - The cache object that holds the blocklist and flood panel data.
  * @param {Array<*>} ioCache.blocklick - The list of blocked IPs.
- * @param {Record<string, any>} floodPanel - The object tracking flooding attempts and timeouts for each IP.
  * @returns {void} This function does not return anything, it modifies the floodPanel and blocklist.
  */
 export default function verify(socket, ioCache) {
     // Get User IP
-    const ip = userIp(socket.handshake);
+    const ipData = userIp(socket.handshake);
+    const ip = ipData.value ? ipData.value[0] : '';
     /**
      * Verifies the IP for flooding attempts and manages timeout and blocklist.
      */
@@ -59,7 +63,7 @@ export default function verify(socket, ioCache) {
     }
     // Catch-all Event Listener
     var onevent = socket.onevent;
-    socket.onevent = function (packet) {
+    socket.onevent = function (/** @type {{ data: string[]; }} */ packet) {
         var args = packet.data || [];
         onevent.call(this, packet); // original call
         packet.data = ['*'].concat(args);

package/dist/legacy/socket.io/cookie-session.cjs

@@ -1,7 +1,5 @@
 'use strict';
 
-// @ts-nocheck
-
 /**
  * Handles the cookie session for a socket connection by simulating an Express request and response.
  * This function uses the provided session module to manage session data for the socket connection.
@@ -13,6 +11,7 @@
 function cookieSession(socket, sessionModule) {
   return new Promise((resolve) => {
     // Express Simulator
+    /** @type {Record<*,*>} */
     let req = {
       connection: { encrypted: false },
       headers: { cookie: socket.request.headers.cookie },

package/dist/legacy/socket.io/cookie-session.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 /**
  * Handles the cookie session for a socket connection by simulating an Express request and response.
  * This function uses the provided session module to manage session data for the socket connection.
@@ -10,6 +9,7 @@
 export default function cookieSession(socket, sessionModule) {
     return new Promise((resolve) => {
         // Express Simulator
+        /** @type {Record<*,*>} */
         let req = {
             connection: { encrypted: false },
             headers: { cookie: socket.request.headers.cookie },

package/dist/legacy/socket.io/discord.cjs

@@ -2,9 +2,6 @@
 
 var getUser = require('../firebase/discord/api/getUser.cjs');
 
-// @ts-nocheck
-
-
 /**
  * Handles the Discord OAuth2 authentication for a user, stores user data in an in-memory cache,
  * and manages the user's socket connection and disconnection events.

package/dist/legacy/socket.io/discord.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import getUser from '../firebase/discord/api/getUser.mjs';
 /**
  * Handles the Discord OAuth2 authentication for a user, stores user data in an in-memory cache,

package/dist/legacy/socket.io/index.cjs

@@ -4,9 +4,6 @@ var index = require('./antiFlood/index.cjs');
 var discord = require('./discord.cjs');
 var cookieSession = require('./cookie-session.cjs');
 
-// @ts-nocheck
-
-
 const socketIo = {
   antiFlood: index,
   'cookie-session': cookieSession,

package/dist/legacy/socket.io/index.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import * as antiFlood from './antiFlood/index.mjs';
 import discord from './discord.mjs';
 import cookieSession from './cookie-session.mjs';

package/dist/v1/basics/index.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var arraySortPositions = require('../../legacy/libs/arraySortPositions.cjs');
 var replaceAsync = require('../../legacy/libs/replaceAsync.cjs');
 var array = require('./array.cjs');
 var clock = require('./clock.cjs');
@@ -9,6 +10,7 @@ var text = require('./text.cjs');
 
 
 
+exports.arraySortPositions = arraySortPositions;
 exports.asyncReplace = replaceAsync;
 exports.shuffleArray = array.shuffleArray;
 exports.formatCustomTimer = clock.formatCustomTimer;

package/dist/v1/basics/index.d.mts

@@ -1,3 +1,4 @@
+import arraySortPositions from '../../legacy/libs/arraySortPositions.mjs';
 import { formatBytes } from './simpleMath.mjs';
 import { addAiMarkerShortcut } from './text.mjs';
 import { extendObjType } from './objFilter.mjs';
@@ -16,5 +17,5 @@ import { getTimeDuration } from './clock.mjs';
 import { shuffleArray } from './array.mjs';
 import { toTitleCase } from './text.mjs';
 import { toTitleCaseLowerFirst } from './text.mjs';
-export { formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
+export { arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
 //# sourceMappingURL=index.d.mts.map

package/dist/v1/basics/index.mjs

@@ -1,7 +1,8 @@
+import arraySortPositions from '../../legacy/libs/arraySortPositions.mjs';
 import asyncReplace from '../../legacy/libs/replaceAsync.mjs';
 import { shuffleArray } from './array.mjs';
 import { formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration } from './clock.mjs';
 import { countObj, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType, } from './objFilter.mjs';
 import { formatBytes, getAge, getSimplePerc, ruleOfThree } from './simpleMath.mjs';
 import { addAiMarkerShortcut, toTitleCase, toTitleCaseLowerFirst } from './text.mjs';
-export { formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+export { arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };

package/dist/v1/build/TinyRateLimiter.cjs

@@ -0,0 +1,7 @@
+'use strict';
+
+var TinyRateLimiter = require('../libs/TinyRateLimiter.cjs');
+
+
+
+exports.TinyRateLimiter = TinyRateLimiter;

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

@@ -0,0 +1,3 @@
+export { TinyRateLimiter };
+import TinyRateLimiter from '../libs/TinyRateLimiter.mjs';
+//# sourceMappingURL=TinyRateLimiter.d.mts.map

package/dist/v1/build/TinyRateLimiter.mjs

@@ -0,0 +1,2 @@
+import TinyRateLimiter from '../libs/TinyRateLimiter.mjs';
+export { TinyRateLimiter };

package/dist/v1/index.cjs

@@ -2,6 +2,7 @@
 
 var replaceAsync = require('../legacy/libs/replaceAsync.cjs');
 var userLevel = require('../legacy/libs/userLevel.cjs');
+var arraySortPositions = require('../legacy/libs/arraySortPositions.cjs');
 var array = require('./basics/array.cjs');
 var clock = require('./basics/clock.cjs');
 var objFilter = require('./basics/objFilter.cjs');
@@ -9,11 +10,13 @@ var simpleMath = require('./basics/simpleMath.cjs');
 var text = require('./basics/text.cjs');
 var ColorSafeStringify = require('./libs/ColorSafeStringify.cjs');
 var TinyPromiseQueue = require('./libs/TinyPromiseQueue.cjs');
+var TinyRateLimiter = require('./libs/TinyRateLimiter.cjs');
 
 
 
 exports.asyncReplace = replaceAsync;
 exports.TinyLevelUp = userLevel;
+exports.arraySortPositions = arraySortPositions;
 exports.shuffleArray = array.shuffleArray;
 exports.formatCustomTimer = clock.formatCustomTimer;
 exports.formatDayTimer = clock.formatDayTimer;
@@ -34,3 +37,4 @@ exports.toTitleCase = text.toTitleCase;
 exports.toTitleCaseLowerFirst = text.toTitleCaseLowerFirst;
 exports.ColorSafeStringify = ColorSafeStringify;
 exports.TinyPromiseQueue = TinyPromiseQueue;
+exports.TinyRateLimiter = TinyRateLimiter;

package/dist/v1/index.d.mts

@@ -1,6 +1,8 @@
+import TinyRateLimiter from './libs/TinyRateLimiter.mjs';
 import ColorSafeStringify from './libs/ColorSafeStringify.mjs';
 import TinyPromiseQueue from './libs/TinyPromiseQueue.mjs';
 import TinyLevelUp from '../legacy/libs/userLevel.mjs';
+import arraySortPositions from '../legacy/libs/arraySortPositions.mjs';
 import { formatBytes } from './basics/simpleMath.mjs';
 import { addAiMarkerShortcut } from './basics/text.mjs';
 import { extendObjType } from './basics/objFilter.mjs';
@@ -20,5 +22,5 @@ import { getTimeDuration } from './basics/clock.mjs';
 import { shuffleArray } from './basics/array.mjs';
 import { toTitleCase } from './basics/text.mjs';
 import { toTitleCaseLowerFirst } from './basics/text.mjs';
-export { ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
+export { TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
 //# sourceMappingURL=index.d.mts.map

package/dist/v1/index.mjs

@@ -1,5 +1,6 @@
 import asyncReplace from '../legacy/libs/replaceAsync.mjs';
 import TinyLevelUp from '../legacy/libs/userLevel.mjs';
+import arraySortPositions from '../legacy/libs/arraySortPositions.mjs';
 import { shuffleArray } from './basics/array.mjs';
 import { formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, } from './basics/clock.mjs';
 import { countObj, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType, checkObj, } from './basics/objFilter.mjs';
@@ -7,4 +8,5 @@ import { formatBytes, getAge, getSimplePerc, ruleOfThree } from './basics/simple
 import { addAiMarkerShortcut, toTitleCase, toTitleCaseLowerFirst } from './basics/text.mjs';
 import ColorSafeStringify from './libs/ColorSafeStringify.mjs';
 import TinyPromiseQueue from './libs/TinyPromiseQueue.mjs';
-export { ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+import TinyRateLimiter from './libs/TinyRateLimiter.mjs';
+export { TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };

package/dist/v1/libs/TinyRateLimit.cjs

@@ -0,0 +1,196 @@
+'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=60000] - Interval for automatic cleanup (ms)
+   * @param {number} [options.maxIdle=300000] - Max idle time for a user before being cleaned (ms)
+   */
+  constructor({ maxHits, interval, cleanupInterval = 60000, 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 (!isCleanupValid)
+      throw new Error("'cleanupInterval' must be a positive integer in milliseconds.");
+    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 = cleanupInterval;
+    this.maxIdle = maxIdle;
+
+    /** @type {Map<string, number[]>} */
+    this.userData = new Map();
+
+    /** @type {Map<string, number>} */
+    this.lastSeen = new Map();
+
+    // Start automatic cleanup
+    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() {
+    clearInterval(this._cleanupTimer);
+    this.userData.clear();
+    this.lastSeen.clear();
+  }
+}
+
+module.exports = TinyRateLimiter;