# Permwise

Lightweight permissions handler purely using bitwise operations written in TypeScript.

<br>

## Usage

```typescript
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
```

<br>

*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:*

```js
...

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

<br>

## 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`<br/> 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`      |

<br>

### 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) |

<br>

## Math

Checking if a permissions number contains a permission:

```typescript
( X & Y === Y )
```

Given permissions **_X_**: `1 0 1 1`
<br>
Checking for **_Y_**: `1 0 0 0`

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

<br>