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