@gruvjs/permissions 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,62 @@
+<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/permissions"><img src="https://img.shields.io/npm/v/@gruvjs/permissions.svg?maxAge=3600" alt="npm version" /></a>
+    <a href="https://www.npmjs.com/package/@gruvjs/permissions"><img src="https://img.shields.io/npm/dt/@gruvjs/permissions.svg?maxAge=3600" alt="npm downloads" /></a>
+  </p>
+</div>
+
+## About
+
+`@gruvjs/permissions` is a human-readable Discord permission bitfield manager. No discord.js required.
+
+Node.js 18.0.0 or newer is required.
+
+## Installation
+
+```sh
+npm install @gruvjs/permissions
+yarn add @gruvjs/permissions
+pnpm add @gruvjs/permissions
+```
+
+## Examples
+
+```js
+const { Permissions } = require("@gruvjs/permissions");
+
+// From a raw Discord bitfield (e.g. from a guild member object)
+const perms = Permissions.from(8n);
+perms.has("ADMINISTRATOR");      // → true
+perms.has("SEND_MESSAGES");      // → true (ADMINISTRATOR bypasses all checks)
+
+// Build from permission names
+const modPerms = new Permissions(["KICK_MEMBERS", "BAN_MEMBERS", "MANAGE_MESSAGES"]);
+modPerms.has("KICK_MEMBERS");    // → true
+modPerms.has("ADMINISTRATOR");   // → false
+
+// Check if any match (useful for "can moderate" checks)
+modPerms.any(["KICK_MEMBERS", "BAN_MEMBERS", "MODERATE_MEMBERS"]); // → true
+
+// Find what's missing
+modPerms.missing(["KICK_MEMBERS", "MANAGE_ROLES"]); // → ["MANAGE_ROLES"]
+
+// Immutable add/remove
+const updated = modPerms.add("MANAGE_ROLES");
+const reduced = modPerms.remove("BAN_MEMBERS");
+
+// All set permission names
+modPerms.toArray(); // → ["KICK_MEMBERS", "BAN_MEMBERS", "MANAGE_MESSAGES"]
+```
+
+See the [docs](./docs) folder for detailed usage.
+
+## Links
+
+- [npm](https://www.npmjs.com/package/@gruvjs/permissions)
+- [GitHub](https://github.com/gruvjs/gruvjs/tree/main/packages/permissions)
+- [gruvjs monorepo](https://github.com/gruvjs/gruvjs)

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@gruvjs/permissions",
+  "version": "1.0.0",
+  "description": "Human-readable Discord permission bitfields. No discord.js required.",
+  "main": "src/index.js",
+  "author": "gruvjs",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "discord",
+    "permissions",
+    "bitfield",
+    "bot",
+    "zero-dependency"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gruvjs/gruvjs.git",
+    "directory": "packages/permissions"
+  },
+  "bugs": {
+    "url": "https://github.com/gruvjs/gruvjs/issues"
+  },
+  "homepage": "https://github.com/gruvjs/gruvjs/tree/main/packages/permissions#readme",
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "scripts": {
+    "test": "node tests/run.js"
+  }
+}

package/src/core/Permissions.js

@@ -0,0 +1,80 @@
+const { PermissionsBits } = require("../data/PermissionsBits");
+
+/**
+ * Wraps a Discord permission bitfield in a clean, human-readable API.
+ * Does not require discord.js.
+ */
+class Permissions {
+  /**
+   * @param {bigint|number|string|string[]} [input]
+   *   - bigint / number → raw bitfield
+   *   - string          → single permission name (e.g. "ADMINISTRATOR")
+   *   - string[]        → array of permission names
+   */
+  constructor(input) {
+    this._bitfield = Permissions._resolve(input ?? 0n);
+  }
+
+  // ── Checks ─────────────────────────────────────────────────────────────────
+
+  /** Returns true if ALL of the given permissions are set. ADMINISTRATOR always returns true. */
+  has(perms) {
+    const bits = Permissions._resolve(perms);
+    if (this._bitfield & PermissionsBits.ADMINISTRATOR) return true;
+    return (this._bitfield & bits) === bits;
+  }
+
+  /** Returns true if ANY of the given permissions are set. ADMINISTRATOR always returns true. */
+  any(perms) {
+    const bits = Permissions._resolve(perms);
+    if (this._bitfield & PermissionsBits.ADMINISTRATOR) return true;
+    return (this._bitfield & bits) !== 0n;
+  }
+
+  /** Returns the permission names that are in perms but NOT in this bitfield. */
+  missing(perms) {
+    return perms.filter((p) => !this.has(p));
+  }
+
+  // ── Mutation (returns new instance — originals are never mutated) ───────────
+
+  /** Returns a new Permissions with the given permissions added. */
+  add(perms) { return new Permissions(this._bitfield | Permissions._resolve(perms)); }
+
+  /** Returns a new Permissions with the given permissions removed. */
+  remove(perms) { return new Permissions(this._bitfield & ~Permissions._resolve(perms)); }
+
+  // ── Output ─────────────────────────────────────────────────────────────────
+
+  get bitfield() { return this._bitfield; }
+
+  /** Returns all set permission names. Does NOT expand ADMINISTRATOR. */
+  toArray() {
+    return Object.entries(PermissionsBits)
+      .filter(([, bit]) => (this._bitfield & bit) === bit)
+      .map(([name]) => name);
+  }
+
+  /** Returns the bitfield as a decimal string — safe for JSON serialization. */
+  toString() { return this._bitfield.toString(); }
+  toJSON()   { return this.toString(); }
+
+  // ── Static ─────────────────────────────────────────────────────────────────
+
+  static from(bitfield)  { return new Permissions(bitfield); }
+  static resolve(names)  { return Permissions._resolve(names); }
+
+  static _resolve(input) {
+    if (typeof input === "bigint")  return input;
+    if (typeof input === "number")  return BigInt(input);
+    if (typeof input === "string") {
+      const bit = PermissionsBits[input];
+      if (bit === undefined) throw new RangeError(`Unknown permission: "${input}"`);
+      return bit;
+    }
+    if (Array.isArray(input)) return input.reduce((acc, p) => acc | Permissions._resolve(p), 0n);
+    throw new TypeError(`Cannot resolve permissions from: ${typeof input}`);
+  }
+}
+
+module.exports = { Permissions };

package/src/data/PermissionsBits.js

@@ -0,0 +1,58 @@
+/**
+ * All Discord permission flags as named BigInt constants.
+ * Matches the Discord API permission bitfield values.
+ * @type {Readonly<Record<string, bigint>>}
+ */
+const PermissionsBits = Object.freeze({
+  CREATE_INSTANT_INVITE:               1n << 0n,
+  KICK_MEMBERS:                        1n << 1n,
+  BAN_MEMBERS:                         1n << 2n,
+  ADMINISTRATOR:                       1n << 3n,
+  MANAGE_CHANNELS:                     1n << 4n,
+  MANAGE_GUILD:                        1n << 5n,
+  ADD_REACTIONS:                       1n << 6n,
+  VIEW_AUDIT_LOG:                      1n << 7n,
+  PRIORITY_SPEAKER:                    1n << 8n,
+  STREAM:                              1n << 9n,
+  VIEW_CHANNEL:                        1n << 10n,
+  SEND_MESSAGES:                       1n << 11n,
+  SEND_TTS_MESSAGES:                   1n << 12n,
+  MANAGE_MESSAGES:                     1n << 13n,
+  EMBED_LINKS:                         1n << 14n,
+  ATTACH_FILES:                        1n << 15n,
+  READ_MESSAGE_HISTORY:                1n << 16n,
+  MENTION_EVERYONE:                    1n << 17n,
+  USE_EXTERNAL_EMOJIS:                 1n << 18n,
+  VIEW_GUILD_INSIGHTS:                 1n << 19n,
+  CONNECT:                             1n << 20n,
+  SPEAK:                               1n << 21n,
+  MUTE_MEMBERS:                        1n << 22n,
+  DEAFEN_MEMBERS:                      1n << 23n,
+  MOVE_MEMBERS:                        1n << 24n,
+  USE_VAD:                             1n << 25n,
+  CHANGE_NICKNAME:                     1n << 26n,
+  MANAGE_NICKNAMES:                    1n << 27n,
+  MANAGE_ROLES:                        1n << 28n,
+  MANAGE_WEBHOOKS:                     1n << 29n,
+  MANAGE_GUILD_EXPRESSIONS:            1n << 30n,
+  USE_APPLICATION_COMMANDS:            1n << 31n,
+  REQUEST_TO_SPEAK:                    1n << 32n,
+  MANAGE_EVENTS:                       1n << 33n,
+  MANAGE_THREADS:                      1n << 34n,
+  CREATE_PUBLIC_THREADS:               1n << 35n,
+  CREATE_PRIVATE_THREADS:              1n << 36n,
+  USE_EXTERNAL_STICKERS:               1n << 37n,
+  SEND_MESSAGES_IN_THREADS:            1n << 38n,
+  USE_EMBEDDED_ACTIVITIES:             1n << 39n,
+  MODERATE_MEMBERS:                    1n << 40n,
+  VIEW_CREATOR_MONETIZATION_ANALYTICS: 1n << 41n,
+  USE_SOUNDBOARD:                      1n << 42n,
+  CREATE_GUILD_EXPRESSIONS:            1n << 43n,
+  CREATE_EVENTS:                       1n << 44n,
+  USE_EXTERNAL_SOUNDS:                 1n << 45n,
+  SEND_VOICE_MESSAGES:                 1n << 46n,
+  SEND_POLLS:                          1n << 49n,
+  USE_EXTERNAL_APPS:                   1n << 50n,
+});
+
+module.exports = { PermissionsBits };

package/src/index.js

@@ -0,0 +1,7 @@
+// Data
+const { PermissionsBits } = require("./data/PermissionsBits");
+
+// Core
+const { Permissions }     = require("./core/Permissions");
+
+module.exports = { Permissions, PermissionsBits };