1.1.0 • Published 1 year ago
permwise v1.1.0
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 ) ); // trueNOTE: 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