Features

• Wraps Discord's BigInt permission bitfields in a clean, readable API
• No discord.js dependency — works in dashboards, REST APIs, standalone scripts
• ADMINISTRATOR always passes has() and any() checks automatically
• Immutable — add() and remove() return new instances
• Full TypeScript types with all 50 permission names · Zero dependencies · Node.js 18+

Installation

npm install @disckit/permissions
yarn add @disckit/permissions
pnpm add @disckit/permissions

TypeScript / ESM

Types are bundled — no extra install needed.
Supports both CommonJS and ESM:

// ESM
import { Permissions, PermissionsBits } from '@disckit/permissions';

// CommonJS
const { Permissions, PermissionsBits } = require('@disckit/permissions');

Usage

From a raw Discord bitfield

const { Permissions } = require('@disckit/permissions');

// Raw bigint from Discord API (e.g. member.permissions)
const perms = Permissions.from(8n); // 8n = ADMINISTRATOR

perms.has('ADMINISTRATOR');   // → true
perms.has('SEND_MESSAGES');   // → true  (ADMINISTRATOR bypasses all checks)
perms.has('BAN_MEMBERS');     // → true

From permission names

const modPerms = new Permissions(['KICK_MEMBERS', 'BAN_MEMBERS', 'MANAGE_MESSAGES']);

modPerms.has('KICK_MEMBERS');          // → true
modPerms.has('ADMINISTRATOR');         // → false
modPerms.any(['KICK_MEMBERS', 'BAN_MEMBERS']); // → true  (at least one matches)

// What's missing from a required set?
modPerms.missing(['KICK_MEMBERS', 'MANAGE_ROLES']);
// → ['MANAGE_ROLES']

Immutable add / remove

const base = new Permissions(['SEND_MESSAGES', 'READ_MESSAGE_HISTORY']);

const withEmbeds = base.add('EMBED_LINKS');
// base is unchanged — withEmbeds is a new instance

const reduced = withEmbeds.remove('SEND_MESSAGES');
reduced.toArray(); // → ['READ_MESSAGE_HISTORY', 'EMBED_LINKS']

Dashboard usage (no discord.js)

// Received from your API: member's permission bitfield as a string
const raw = req.body.permissions; // e.g. "2147483647"
const perms = new Permissions(BigInt(raw));

if (!perms.has('MANAGE_GUILD')) {
  return res.status(403).json({ error: 'Missing MANAGE_GUILD' });
}

Using PermissionsBits directly

const { PermissionsBits } = require('@disckit/permissions');

// Raw bigint constants — all 50 Discord permissions
PermissionsBits.ADMINISTRATOR;  // → 8n
PermissionsBits.BAN_MEMBERS;    // → 4n
PermissionsBits.SEND_MESSAGES;  // → 2048n

API Reference

new Permissions(input?)

input can be: bigint, number, PermissionName, or PermissionName[]

| Method | Returns | Description | |--------|---------|-------------| | has(perms) | boolean | All given permissions are set. ADMINISTRATOR always returns true | | any(perms) | boolean | At least one of the given permissions is set | | missing(perms) | PermissionName[] | Names in perms that are NOT set | | add(perms) | Permissions | New instance with permissions added | | remove(perms) | Permissions | New instance with permissions removed | | toArray() | PermissionName[] | All set permission names | | toString() | string | Bitfield as decimal string (safe for JSON) | | bitfield | bigint | Raw permission bitfield |

diff(other) → { added: PermissionName[], removed: PermissionName[] }

Returns which permissions were added or removed compared to another bitfield. Useful for logging role changes in Event Log handlers.

const before = new Permissions(['SEND_MESSAGES']);
const after  = new Permissions(['SEND_MESSAGES', 'MANAGE_MESSAGES']);
after.diff(before);
// → { added: ['MANAGE_MESSAGES'], removed: [] }

Permissions.from(input) — static

Alias for new Permissions(input).

PermissionsBits

Frozen object with all 50 Discord permission flags as bigint constants.

Links

• npm
• GitHub
• disckit monorepo