@pstl/perms

Permwise

Lightweight permissions handler purely using bitwise operations written in TypeScript.

Usage

import { Role, Shift } from "@pstl/perms";

// Create permission numbers
const PERMISSION_1: number = Shift( 0 ); // 1 << 0
const PERMISSION_2: number = Shift( 1 ); // 1 << 1
const PERMISSION_3: number = Shift( 2 ); // 1 << 2

// Create new Role object
const role: Role = new Role()
    .addPermissions( [ PERMISSION_1, PERMISSION_2, PERMISSION_3 ] )
    .removePermission( PERMISSION_2 );

console.log( role.has( PERMISSION_2 ) ); // false
console.log( role.has( PERMISSION_1 ) ); // true

role.addPermission( PERMISSION_2 );

console.log( role.has( PERMISSION_2 ) ); // true

NOTE: BigInt only allows for up to 2^52 or else bitwise operations are inaccurate. This means there are a maximum of 53 permissions supported in this method. If you wish to expand that, you could create "subgroup" permissions. For example:

...

// Where group is an isolated set of permissions
const Permissions = [
    group_1, group_2, group_3, ..., group_n
]

Role Class

Methods

Method	Parameters	Description	Return Type
has	perm: number	Checks if this Role has a permission	boolean
hasExplicit	perm: number	Checks if this Role explicitly has a permission (without Administrator override option)	boolean
has
static	perms: number perm: number	Checks if a given permissions number contains a permission	boolean
addPermission	perms: number	Adds a permission to a Role	Role
addPermissions	perms: Array<number>	Adds a list of permissions to a Role	Role
removePermission	perm: number	Removes a permission from a Role	Role
removePermissions	perms: Array<number>	Removes a list of permissions from a Role	Role

Properties

Property	Type	Default	Description
name	string	null	An optional property that describes the Role
permissions	number	0	A number that contains all bitwise-calculated permission numbers (default=0)
override	number	null	A permission override that gives a user access to all permissions (Administrator override)

Math

Checking if a permissions number contains a permission:

( X & Y === Y )

Given permissions X: 1 0 1 1
Checking for Y: 1 0 0 0

1 0 1 1 & 1 0 0 0 = 1 0 0 0