@gruvjs/cooldown 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saiteja Madha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+<div align="center">
+  <br />
+  <p>
+    <a href="https://github.com/gruvjs/gruvjs"><img src="https://raw.githubusercontent.com/gruvjs/gruvjs/main/assets/logo.svg" width="546" alt="gruvjs" /></a>
+  </p>
+  <br />
+  <p>
+    <a href="https://www.npmjs.com/package/@gruvjs/cooldown"><img src="https://img.shields.io/npm/v/@gruvjs/cooldown.svg?maxAge=3600" alt="npm version" /></a>
+    <a href="https://www.npmjs.com/package/@gruvjs/cooldown"><img src="https://img.shields.io/npm/dt/@gruvjs/cooldown.svg?maxAge=3600" alt="npm downloads" /></a>
+  </p>
+</div>
+
+## About
+
+`@gruvjs/cooldown` is a per-user, per-guild, per-command cooldown manager for bots. Supports bypass lists and per-check duration overrides.
+
+Node.js 18.0.0 or newer is required.
+
+## Installation
+
+```sh
+npm install @gruvjs/cooldown
+yarn add @gruvjs/cooldown
+pnpm add @gruvjs/cooldown
+```
+
+## Examples
+
+```js
+const { CooldownManager } = require("@gruvjs/cooldown");
+
+const cooldowns = new CooldownManager({
+  default: 3000,            // 3s default for all commands
+  bypass:  ["OWNER_ID"],    // these users always bypass cooldowns
+});
+
+// In your command handler:
+const result = cooldowns.check("ping", interaction.user.id);
+
+if (!result.ok) {
+  return interaction.reply(`Please wait ${result.remainingText} before using this command again.`);
+}
+
+// execute command...
+
+// Per-command duration override
+cooldowns.check("ban", userId, { duration: 10_000 }); // 10s just for /ban
+
+// Reset manually (e.g. after a premium bypass)
+cooldowns.reset("ping", userId);
+cooldowns.resetCommand("ping"); // reset for all users
+
+// Bypass list management
+cooldowns.addBypass("MOD_ID");
+cooldowns.removeBypass("MOD_ID");
+
+// Stats
+cooldowns.stats(); // → { active: 5, bypassed: 2 }
+```
+
+See the [docs](./docs) folder for detailed usage.
+
+## Links
+
+- [npm](https://www.npmjs.com/package/@gruvjs/cooldown)
+- [GitHub](https://github.com/gruvjs/gruvjs/tree/main/packages/cooldown)
+- [gruvjs monorepo](https://github.com/gruvjs/gruvjs)

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@gruvjs/cooldown",
+  "version": "1.0.0",
+  "description": "Per-user, per-guild, per-command cooldown manager for bots. Supports bypass lists and duration overrides.",
+  "main": "src/index.js",
+  "author": "gruvjs",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "cooldown",
+    "bot",
+    "discord",
+    "rate-limit",
+    "command",
+    "zero-dependency"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gruvjs/gruvjs.git",
+    "directory": "packages/cooldown"
+  },
+  "bugs": {
+    "url": "https://github.com/gruvjs/gruvjs/issues"
+  },
+  "homepage": "https://github.com/gruvjs/gruvjs/tree/main/packages/cooldown#readme",
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "scripts": {
+    "test": "node tests/run.js"
+  }
+}

package/src/core/CooldownManager.js

@@ -0,0 +1,110 @@
+const { formatMs } = require("../util/formatMs");
+
+/**
+ * Per-user, per-guild, per-command cooldown manager.
+ *
+ * Unlike a generic rate limiter, CooldownManager is designed for bot commands:
+ * it tracks per-key cooldowns, supports bypass lists (owner/mods) and
+ * per-check duration overrides.
+ */
+class CooldownManager {
+  /**
+   * @param {object}   [options]
+   * @param {number}   [options.default=3000]   Default cooldown in ms.
+   * @param {string[]} [options.bypass=[]]      IDs that always bypass cooldowns.
+   * @param {number}   [options.sweepEveryMs=0] Auto-sweep interval. 0 = disabled.
+   */
+  constructor(options = {}) {
+    this._default   = options.default ?? 3000;
+    this._bypass    = new Set(options.bypass ?? []);
+    this._cooldowns = new Map(); // `${command}:${key}` → expiresAt (ms)
+
+    this._sweepTimer = null;
+    if (options.sweepEveryMs > 0) {
+      this._sweepTimer = setInterval(() => this._sweep(), options.sweepEveryMs);
+      if (this._sweepTimer.unref) this._sweepTimer.unref();
+    }
+  }
+
+  // ── Core ───────────────────────────────────────────────────────────────────
+
+  /**
+   * Checks and applies a cooldown for a command + key combination.
+   *
+   * @param {string}  command
+   * @param {string}  key       User ID, guild ID, or any string identifier
+   * @param {object}  [options]
+   * @param {number}  [options.duration]  Override duration for this check
+   * @returns {{ ok: boolean, remaining: number, remainingText: string, expiresAt: number }}
+   */
+  check(command, key, options = {}) {
+    if (this._bypass.has(key)) return { ok: true, remaining: 0, remainingText: "0s", expiresAt: 0 };
+
+    const mapKey    = `${command}:${key}`;
+    const now       = Date.now();
+    const expiresAt = this._cooldowns.get(mapKey) ?? 0;
+
+    if (expiresAt > now) {
+      const remaining = expiresAt - now;
+      return { ok: false, remaining, remainingText: formatMs(remaining), expiresAt };
+    }
+
+    const duration = options.duration ?? this._default;
+    this._cooldowns.set(mapKey, now + duration);
+    return { ok: true, remaining: 0, remainingText: "0s", expiresAt: now + duration };
+  }
+
+  /**
+   * Peeks at a cooldown without applying it.
+   * @param {string} command
+   * @param {string} key
+   */
+  peek(command, key) {
+    if (this._bypass.has(key)) return { ok: true, remaining: 0, remainingText: "0s", expiresAt: 0 };
+    const now       = Date.now();
+    const expiresAt = this._cooldowns.get(`${command}:${key}`) ?? 0;
+    const remaining = Math.max(0, expiresAt - now);
+    return { ok: remaining === 0, remaining, remainingText: formatMs(remaining), expiresAt };
+  }
+
+  /** Resets the cooldown for a specific command + key. */
+  reset(command, key) { this._cooldowns.delete(`${command}:${key}`); }
+
+  /** Resets all cooldowns for a command across all keys. */
+  resetCommand(command) {
+    const prefix = `${command}:`;
+    for (const k of this._cooldowns.keys()) {
+      if (k.startsWith(prefix)) this._cooldowns.delete(k);
+    }
+  }
+
+  /** Resets all cooldowns. */
+  resetAll() { this._cooldowns.clear(); }
+
+  // ── Bypass ─────────────────────────────────────────────────────────────────
+
+  addBypass(id)    { this._bypass.add(id); return this; }
+  removeBypass(id) { this._bypass.delete(id); return this; }
+  isBypassed(id)   { return this._bypass.has(id); }
+
+  // ── Stats / lifecycle ──────────────────────────────────────────────────────
+
+  stats() {
+    const now = Date.now();
+    let active = 0;
+    for (const exp of this._cooldowns.values()) if (exp > now) active++;
+    return { active, bypassed: this._bypass.size };
+  }
+
+  destroy() {
+    if (this._sweepTimer) clearInterval(this._sweepTimer);
+    this._cooldowns.clear();
+  }
+
+  _sweep() {
+    const now = Date.now();
+    for (const [k, exp] of this._cooldowns) if (exp <= now) this._cooldowns.delete(k);
+  }
+}
+
+module.exports = { CooldownManager };

package/src/index.js

@@ -0,0 +1,4 @@
+// Core
+const { CooldownManager } = require("./core/CooldownManager");
+
+module.exports = { CooldownManager };

package/src/util/formatMs.js

@@ -0,0 +1,22 @@
+/**
+ * Formats a millisecond duration as a short human-readable string.
+ *
+ * @param {number} ms
+ * @returns {string}
+ *
+ * @example
+ *   formatMs(0)         // → "0s"
+ *   formatMs(500)       // → "500ms"
+ *   formatMs(2500)      // → "2.5s"
+ *   formatMs(90_000)    // → "2m"
+ *   formatMs(3_600_000) // → "1h"
+ */
+function formatMs(ms) {
+  if (ms <= 0)        return "0s";
+  if (ms < 1000)      return `${ms}ms`;
+  if (ms < 60_000)    return `${(ms / 1000).toFixed(1).replace(/\.0$/, "")}s`;
+  if (ms < 3_600_000) return `${Math.ceil(ms / 60_000)}m`;
+  return `${Math.ceil(ms / 3_600_000)}h`;
+}
+
+module.exports = { formatMs };