https://github.com/verful/adonis-permissions
Easily manage user roles and permissions on AdonisJS applications
https://github.com/verful/adonis-permissions
adonisjs permission typescript
Last synced: 6 months ago
JSON representation
Easily manage user roles and permissions on AdonisJS applications
- Host: GitHub
- URL: https://github.com/verful/adonis-permissions
- Owner: verful
- License: mit
- Created: 2022-02-24T01:21:32.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-02-05T13:03:17.000Z (over 2 years ago)
- Last Synced: 2025-08-24T06:25:14.879Z (10 months ago)
- Topics: adonisjs, permission, typescript
- Language: TypeScript
- Homepage:
- Size: 1020 KB
- Stars: 47
- Watchers: 2
- Forks: 1
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
Adonis Permissions
Easily manage user roles and permissions
[![npm-image]][npm-url] [![license-image]][license-url] [![typescript-image]][typescript-url]
## **Pre-requisites**
The `@verful/permissions` package requires `@adonisjs/core >= 5` and `@adonisjs/lucid >= 16`
## **Setup**
Install the package from the npm registry as follows.
```
npm i @verful/permissions
# or
yarn add @verful/permissions
```
Next, configure the package by running the following ace command.
```
node ace configure @verful/permissions
```
## **Getting started**
Once the package is installed the first thing you want to do is apply the `Authorizable` mixin from `@ioc:Verful/Permissions/Mixins` into a model
```typescript
import { Authorizable } from '@ioc:Verful/Permissions/Mixins'
import { compose } from '@ioc:Adonis/Core/Helpers'
import { BaseModel } from '@ioc:Adonis/Lucid/Orm'
const config = {
permissionsPivotTable: 'user_has_permissions',
rolesPivotTable: 'user_has_roles'
}
export default class User extends compose(BaseModel, Authorizable(config)) {}
```
Now its time to create the pivot-table migration files
```
node ace permissions:pivot-table
```
After the mixin is applied you can do stuff like this
```typescript
await user.givePermissionTo('view-users')
await user.assignRole('admin')
await role.givePermissionTo('edit-users')
```
## **Basic usage**
The package allows you to associate Lucid models with roles and permissions. Roles and Permissions are just Lucid models that can be directly managed like any other model
```typescript
import Permission from '@ioc:Verful/Permissions/Permission'
import Role from '@ioc:Verful/Permissions/Role'
const role = await Role.create({ name: 'writer' })
const permission = await Permission.create({ name: 'edit-posts' })
```
### **Managing permissions**
You can manage permissions for roles and models using the same methods
```typescript
// Assigning permissions
await role.givePermissionTo('do-things')
// Removing permissions
await user.revokePermissionTo('do-things')
// Synchronize permissions
await role.syncPermissions('do-things', 'try-things')
```
### **Checking for permissions**
```typescript
// Checking permissions
await role.hasPermissionTo('do-things') // returns true or false
await user.checkPermissionTo('do-things') // returns true or throws
// Returns true if the model has any of the given permissions
await role.hasAnyPermission('do-things', 'try-things')
// Returns true if the model has all of the given permissions
await user.hasAllPermissions('do-things', 'try-things')
// Returns all permission names
await user.getPermissionNames()
```
### **Managing Roles**
You can manage roles for models using the `Authorizable` mixin
```typescript
// Assign role
await user.assignRole('admin')
// Revoke role
await user.revokeRole('admin')
// Synchronize roles
await user.syncRoles('admin', 'writer', role)
```
### **Checking for roles**
Generally you should be checking against permissions vs checking for roles, but if you want to check against a role instead use one of the following methods
```typescript
await user.hasRole('admin')
// Returns true if the model has any of the given permissions
await role.hasAnyRoles('admin', 'writer')
// Returns true if the model has all of the given permissions
await user.hasAllRoles('admin', 'writer')
// Returns all role names
await user.getRoleNames()
```
### **Accessing direct and role permissions**
```typescript
// Check if the model has the permission directly
await user.hasDirectPermission('do-things')
// Check if the model has the permission via role
await user.hasPermissionViaRole('do-things')
// Get all direct permissions
await user.getDirectPermissions()
// Get all permissions via roles
await user.getPermissionsViaRoles()
// Get all permissions combined
await user.getAllPermissions()
```
[npm-image]: https://img.shields.io/npm/v/@verful/permissions.svg?style=for-the-badge&logo=npm
[npm-url]: https://npmjs.org/package/@verful/permissions "npm"
[license-image]: https://img.shields.io/npm/l/@verful/permissions?color=blueviolet&style=for-the-badge
[license-url]: LICENSE.md "license"
[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
[typescript-url]: "typescript"