@holoyan/adonisjs-permissions 0.8.21 → 0.9.0

package/README.md

@@ -1,8 +1,17 @@
 # Role permissions system for AdonisJS V6+
 
+Checkout other AdonisJS packages
+
+- [AdonisJs activity log](https://github.com/holoyan/adonisjs-activitylog)
+
 [//]: # ([![test](https://github.com/holoyan/adonisjs-permissions/actions/workflows/test.yml/badge.svg)](https://github.com/holoyan/adonisjs-permissions/actions/workflows/test.yml))
 [![license](https://poser.pugx.org/silber/bouncer/license.svg)](https://github.com/holoyan/adonisjs-permissions/blob/master/LICENSE.md)
 
+## How can you support me?
+
+- It's simple, just star this repository, that is enough to keep me motivated to maintain this package.
+
+
 ## Table of Contents
 
 <details><summary>Click to expand</summary><p>
@@ -40,9 +49,11 @@
     - [The Scope middleware](#the-scope-middleware) 
     - [Default Scope](#default-scope-tenant)
   - [Transactions](#transactions)
+  - [Events] (#events)
 - [Cheat sheet](#cheat-sheet)
 - [Todo](#todo)
 - [Test](#test)
+- [Version Map](#version-map)
 - [License](#license)
 </p></details>
 
@@ -72,7 +83,7 @@ To be able to use the full power of Acl, you should have a clear understanding o
 
 ## Installation
     
-    npm i @holoyan/adonisjs-permissions@0.8.21
+    npm i @holoyan/adonisjs-permissions@0.9.0
 
 
 Next publish config files
@@ -127,8 +138,8 @@ export default class Post extends BaseModel implements AclModelInterface {
 
 ## Release Notes
 
-Version: >= 'v0.8.21'
-* Update: UUID version to ^10.0.0
+Version: >= 'v0.9.x'
+* Added [Events](#events) support
 
 ## Mixins
 
@@ -982,9 +993,279 @@ await trx.commit()
 ```
 
 
+### Events
+
+`Acl` has built-in events that you can listen to. All they are class-based. To listen to the events, you can use `emitter`
+
+```typescript
+import emitter from '@adonisjs/core/services/emitter'
+import { PermissionsAttachedToModelEvent } from '@holoyan/adonisjs-permissions/events'
+
+emitter.on(PermissionsAttachedToModelEvent, (event) => {
+  console.log('permission attached to the model')
+  console.log(event.model) // lucid model instance
+  console.log(event.permissionIds) // array of permission ids
+})
+
+await Acl.model(myUser).allow('create')
+
+```
+
+
+You can also disable events per query by calling withoutEvents() method
+
+```typescript
+
+emitter.on(RoleCreatedEvent, () => {
+  console.log('Role created') // this will not be called
+})
+
+//
+await Acl.role().withoutEvents().create({ // this one will not trigger RoleCreatedEvent
+  slug: 'admin',
+})
+
+await Acl.role().create({ // this will trigger
+  slug: 'admin',
+})
+
+```
+
+If you want to completely disable events, you can do that by calling `withoutEvents()` method on the `Acl` class
+
+```typescript
+
+Acl.withoutEvents()
+
+// any method called on the Acl will not trigger any events
+emitter.on(RoleCreatedEvent, () => {
+  console.log('Role created') // this will not be called
+})
+
+await Acl.role().create({ // this will not trigger because globaly withoutEvents() is set
+  slug: 'admin',
+})
+```
+
+List of events you can listen to:
+
+```
+
+// Permission events
+
+PermissionCreatedEvent { // only if you use Acl.permission().create() method
+  permission: Permission // created permission instance
+}
+
+PermissionDeletedEvent {
+  permission: string // slug of deleted permission
+}
+
+PermissionsAttachedToRoleEvent {
+  permissionIds: ModelIdType[],
+  roleId: ModelIdType
+}
+
+PermissionsDetachedFromRoleEvent {
+    permissions: string[],
+    roleId: ModelIdType
+}
+
+PermissionsAttachedToModelEvent<T extends LucidModel>{
+    permissionIds: ModelIdType[],
+    model: T
+}
+
+PermissionsDetachedFromModelEvent<T extends LucidModel>{
+    permissions: string[],
+    model: T
+}
+
+PermissionsFlushedEvent<T extends LucidModel> {
+    model: T
+}
+
+PermissionsForbadeEvent<T extends LucidModel> {
+    permissionIds: ModelIdType[],
+    model: T
+}
+
+PermissionsUnForbadeEvent<T extends LucidModel> {
+    permissionIds: ModelIdType[],
+    model: T
+}
+
+PermissionsFlushedFromRoleEvent{
+    roleId: ModelIdType
+}
+
+// Role events
+
+RoleCreatedEvent {
+  role: Role // created role instance
+}
+
+RoleDeletedEvent {
+  role: string // slug of deleted role
+}
+
+RolesAttachedToModel<T extends LucidModel> {
+  roles: string[], // array of role slugs
+  model: T // lucid model instance
+}
+
+RolesDetachedFromModelEvent<T extends LucidModel> {
+  roles: string[], // array of role slugs
+  model: T // lucid model instance
+}
+
+RolesFlushedFromModelEvent {
+  model: T // lucid model instance
+}
+
+```
+
+
 ## Cheat sheet
 
-Coming soon
+Model methods
+```typescript 
+// getting model roles
+await Acl.model(user).roles()
+
+// Checking the current model's roles
+await Acl.model(user).hasRole('role_slug')
+await Acl.model(user).hasAllRoles('role_slug1', 'role_slug2')
+await Acl.model(user).hasAnyRole('role_slug1', 'role_slug2')
+
+// assigning roles
+await Acl.model(user).assignRole('role_slug')
+await Acl.model(user).assign('role_slug') // alias for assignRole()
+await Acl.model(user).assignAllRoles('role_slug1', 'role_slug2')
+
+// revoking roles
+await Acl.model(user).revokeRole('role_slug')
+await Acl.model(user).revokeAllRoles('role_slug1', 'role_slug2')
+await Acl.model(user).flushRoles() // remove all roles
+
+// syncing roles
+await Acl.model(user).syncRoles(['role_slug1', 'role_slug2']) // remove all roles and assign new
+await Acl.model(user).syncRolesWithoutDetaching(['role_slug1', 'role_slug2') // assign new roles without removing old
+
+
+// getting model permissions
+
+await Acl.model(user).permissions()
+await Acl.model(user).globalPermissions() // get list of global permissions
+await Acl.mode(user).onResourcePermissions() // get list of on resrouce permissions
+await Acl.model(user).directPermissions() // list of permissions assigned to the user drectly 
+await Acl.model(user).rolePermissions() // Get permissions through roles
+await Acl.model(user).directGlobalPermissions()
+await Acl.model(user).directResourcePermissions()
+
+// checking for permission
+await Acl.model(user).hasPermission(permission)
+await Acl.model(user).hasAllPermissions([permission1, permission2])
+await Acl.model(user).hasAnyPermission([permission1, permission2])
+await Acl.model(user).hasAnyDirectPermission([permission1, permission2])
+await Acl.model(user).hasDirectPermission(permission1)
+await Acl.model(user).hasAllPermissionsDirect([permission1, permission2])
+await Acl.model(user).can(permission1) // alias for hasPermission()
+await Acl.model(user).canAll([permission1, permission2])
+await Acl.model(user).canAny([permission1, permission2])
+
+// check Contains vs hasPermission section to see the diferrence 
+await Acl.model(user).containsPermission(permission)
+await Acl.model(user).contains(permission) // alias for containsPermission
+await Acl.model(user).containsAllPermissions([permission1])
+await Acl.model(user).containsAnyPermission([permission1])
+await Acl.model(user).containsDirectPermission([permission1])
+await Acl.model(user).containsAllPermissionsDirectly([permission1])
+await Acl.model(user).containsAnyPermissionDirectly([permission1])
+
+// assigning permissions
+await Acl.model(user).assignDirectPermission(permission)
+await Acl.model(user).assignDirectAllPermissions([permission1, permission2])
+await Acl.model(user).allow(permission1) // alias for assignDirectPermission()
+await Acl.model(user).allowAll([permission1, permission2])
+
+// reviking permissions
+await Acl.model(user).revokePermission(permission1)
+await Acl.model(user).revoke(permission1) // alias for revokePermission()
+await Acl.model(user).revokeAllPermissions([permission1, permission2])
+await Acl.model(user).revokeAll([permission1, permission2]) // alias for revokeAllPermissions()
+await Acl.model(user).flushPermissions() // revoke/delete all direct assigned permissions
+await Acl.model(user).flush() // revoke/delete all assigned roles and permissions
+
+// sync permissions
+await Acl.model(user).syncPermissions([permission1, permission2]) // all direct assigned permissions will be revoked and only permission1, permission2 will be assigned
+
+// forbid/unforbiding permissions
+await Acl.model(user).forbid(permission1)
+await Acl.model(user).forbidAll([permission1, permission2])
+await Acl.model(user).unforbid(permission1)
+await Acl.model(user).unforbidAll([permission1, permission2])
+
+```
+
+Role methods 
+
+```typescript
+
+await Acl.role(myAdminRole).models() // get list of models assigned to the role
+await Acl.role(myAdminRole).modelsFor('ALIAS_FOR_MODEL')
+
+await Acl.role(myAdminRole).permissions() 
+await Acl.role(myAdminRole).globalPermissions()
+await Acl.role(myAdminRole).onResourcePermissions()
+
+// checking for a permissions
+await Acl.role(myAdminRole).hasPermission(permission)
+await Acl.role(myAdminRole).hasAllPermissions([permission1, permission2])
+await Acl.role(myAdminRole).hasAnyPermissions([permission1, permission2])
+await Acl.role(myAdminRole).can(permission) // alias for hasPermission
+await Acl.role(myAdminRole).canAll([permission1, permission2])
+await Acl.role(myAdminRole).canAny([permission1, permission2])
+
+await Acl.role(myAdminRole).containsPermission(permission)
+await Acl.role(myAdminRole).containsAllPermissions([permission1, permission2])
+await Acl.role(myAdminRole).containsAnyPermissions([permission1, permission2])
+await Acl.role(myAdminRole).forbidden(permission) // check if permission forbidden for a role
+
+// assigning permission
+await Acl.role(myAdminRole).give(permission)
+await Acl.role(myAdminRole).assign(permission) // alias for give()
+await Acl.role(myAdminRole).allow(permission) // alias for give()
+
+await Acl.role(myAdminRole).giveAll([permission1])
+await Acl.role(myAdminRole).assignAll([permission1])
+await Acl.role(myAdminRole).allowAll([permission1])
+
+// revoking permission
+await Acl.role(myAdminRole).revokePermission(permission1)
+await Acl.role(myAdminRole).revoke(permission1) // alias for revokePermission()
+await Acl.role(myAdminRole).revokeAllPermissions([permission1])
+await Acl.role(myAdminRole).revokeAll([permission1]) // alias for revokeAllPermissions()
+await Acl.role(myAdminRole).flush() // revoke all
+
+await Acl.role(myAdminRole).sync([permission1, permission2]) // revoke all and assign only permission1, permission2
+
+// forbid/unforbid
+
+await Acl.role(myAdminRole).forbid(permission)
+await Acl.role(myAdminRole).unforbid(permission)
+
+```
+
+Permission methods
+```typescript
+await Acl.permission(myPermission).roles() // list of roles
+await Acl.permission(myPermission).modelsFor('MODEL_ALIAS')
+await Acl.permission(myPermission).belongsToRole(role_slug) // check if permission belongs to role
+await Acl.permission(myPermission).attachToRole(role_slug)
+await Acl.permission(myPermission).detachFromRole(role_slug)
+
+```
 
 
 ## TODO
@@ -1001,6 +1282,16 @@ Coming soon
     npm run test
 
 
+## Version Map
+
+
+| AdonisJS Lucid version | Package version |
+|------------------------|-----------------|
+| v20.x                  | 0.9.x           |
+| v21.x                  | 1.x             |
+
+
+
 ## License
 
 

package/build/index.d.ts

@@ -8,7 +8,7 @@ export declare const Permission: typeof permission;
 export declare const Role: typeof role;
 export { configure } from './configure.js';
 export { stubsRoot } from './stubs/main.js';
-export { Acl, AclManager } from './src/acl.js';
+export { AclManager, Acl } from './src/acl.js';
 export { MorphMap, getClassPath } from './src/decorators.js';
 export * as morphMapModel from './src/morph_map.js';
 export { hasPermissions } from './src/mixins/has_permissions.js';

package/build/index.js

@@ -16,7 +16,7 @@ export const Permission = permission;
 export const Role = role;
 export { configure } from './configure.js';
 export { stubsRoot } from './stubs/main.js';
-export { Acl, AclManager } from './src/acl.js';
+export { AclManager, Acl } from './src/acl.js';
 export { MorphMap, getClassPath } from './src/decorators.js';
 export * as morphMapModel from './src/morph_map.js';
 export { hasPermissions } from './src/mixins/has_permissions.js';

package/build/providers/role_permission_provider.js

@@ -18,6 +18,15 @@ export default class RolePermissionProvider {
         this.app.container.singleton('modelManager', async () => {
             return new ModelManager();
         });
+        const wantsUuid = this.app.config.get('permissions.permissionsConfig.uuidSupport');
+        Permission.table = this.app.config.get('permissions.permissionsConfig.tables.permissions');
+        Permission.selfAssignPrimaryKey = wantsUuid;
+        Permission.uuidSupport = wantsUuid;
+        Role.table = this.app.config.get('permissions.permissionsConfig.tables.roles');
+        Role.selfAssignPrimaryKey = wantsUuid;
+        Role.uuidSupport = wantsUuid;
+        ModelRole.table = this.app.config.get('permissions.permissionsConfig.tables.modelRoles');
+        ModelPermission.table = this.app.config.get('permissions.permissionsConfig.tables.modelPermissions');
     }
     async boot() {
         const modelManager = await this.app.container.make('modelManager');
@@ -26,7 +35,9 @@ export default class RolePermissionProvider {
         modelManager.setModel('modelPermission', ModelPermission);
         modelManager.setModel('modelRole', ModelRole);
         modelManager.setModel('scope', Scope);
+        const emitter = await this.app.container.make('emitter');
         AclManager.setModelManager(modelManager);
+        AclManager.setEmitter(emitter);
         const map = await this.app.container.make('morphMap');
         map.set('permissions', Permission);
         map.set('roles', Role);

package/build/src/acl.d.ts

@@ -1,23 +1,29 @@
 import { RoleHasModelPermissions } from './services/roles/role_has_model_permissions.js';
-import { ModelHasRolePermissions } from './services/model_has_role_permissions.js';
-import { AclModel, MorphInterface, OptionsInterface, PermissionInterface, RoleInterface, ScopeInterface } from './types.js';
+import { ModelHasRolePermissions } from './services/models/model_has_role_permissions.js';
+import { AclModel, MorphInterface, OptionsInterface, PermissionInterface, RoleInterface } from './types.js';
+import PermissionHasModelRoles from './services/permissions/permission_has_model_roles.js';
 import ModelManager from './model_manager.js';
 import EmptyPermission from './services/permissions/empty_permission.js';
 import EmptyRoles from './services/roles/empty_roles.js';
+import { BaseEvent, Emitter } from '@adonisjs/core/events';
+import { Scope } from './scope.js';
 export declare class AclManager {
     private static modelManager;
     private static map;
+    private static emitter;
+    protected currentScope: Scope;
+    private readonly allowOptionsRewriting;
+    private options;
     static setModelManager(manager: ModelManager): void;
+    static getModelManager(): ModelManager;
     static setMorphMap(map: MorphInterface): void;
-    private allowOptionsRewriting;
-    private options;
+    static setEmitter(emitter: Emitter<any>): void;
     constructor(allowOptionsRewriting: boolean, defaultOptions?: OptionsInterface);
     model(model: AclModel): ModelHasRolePermissions;
     role(): EmptyRoles;
     role(role: RoleInterface): RoleHasModelPermissions;
     permission(): EmptyPermission;
-    permission(permission: PermissionInterface): EmptyPermission;
-    private createNewScope;
+    permission(permission: PermissionInterface): PermissionHasModelRoles;
     /**
      * changing global options
      * @param options
@@ -28,7 +34,12 @@ export declare class AclManager {
      * @param scope
      * @param forceUpdate
      */
-    scope(scope: ScopeInterface, forceUpdate?: boolean): this;
+    scope(scope: Scope, forceUpdate?: boolean): this;
     getScope(): any;
+    withoutEvents(): AclManager;
+    withoutEvents<T extends BaseEvent>(events: T[]): AclManager;
+    withEvents(): AclManager;
+    withEvents<T extends BaseEvent>(events: T[]): AclManager;
+    protected optionClone(): OptionsInterface;
 }
 export declare const Acl: AclManager;

package/build/src/acl.js

@@ -1,47 +1,55 @@
 import { RoleHasModelPermissions } from './services/roles/role_has_model_permissions.js';
-import { ModelHasRolePermissions } from './services/model_has_role_permissions.js';
+import { ModelHasRolePermissions } from './services/models/model_has_role_permissions.js';
 import PermissionHasModelRoles from './services/permissions/permission_has_model_roles.js';
-import ModelManager from './model_manager.js';
 import EmptyPermission from './services/permissions/empty_permission.js';
 import EmptyRoles from './services/roles/empty_roles.js';
 import { Scope } from './scope.js';
 export class AclManager {
     static modelManager;
     static map;
+    static emitter;
+    currentScope;
+    allowOptionsRewriting;
+    options = {
+        events: {
+            fire: true,
+            except: [],
+            only: [],
+        },
+    };
     static setModelManager(manager) {
         this.modelManager = manager;
     }
+    static getModelManager() {
+        return this.modelManager;
+    }
     static setMorphMap(map) {
         this.map = map;
     }
-    allowOptionsRewriting;
-    options = {};
+    static setEmitter(emitter) {
+        this.emitter = emitter;
+    }
     constructor(allowOptionsRewriting, defaultOptions) {
         this.allowOptionsRewriting = allowOptionsRewriting;
-        // default global scope
-        this.options['scope'] = this.createNewScope();
         if (defaultOptions) {
             this.options = { ...this.options, ...defaultOptions };
         }
+        this.currentScope = new Scope();
     }
     model(model) {
-        return new ModelHasRolePermissions(AclManager.modelManager, AclManager.map, { ...this.options }, model);
+        return new ModelHasRolePermissions(AclManager.modelManager, AclManager.map, this.optionClone(), new Scope().set(this.currentScope.get()), model, AclManager.emitter);
     }
     role(role) {
         if (role) {
-            return new RoleHasModelPermissions(AclManager.modelManager, AclManager.map, { ...this.options }, role);
+            return new RoleHasModelPermissions(AclManager.modelManager, AclManager.map, this.optionClone(), new Scope().set(this.currentScope.get()), role, AclManager.emitter);
         }
-        return new EmptyRoles(AclManager.modelManager, AclManager.map, { ...this.options });
+        return new EmptyRoles(AclManager.modelManager, AclManager.map, this.optionClone(), new Scope().set(this.currentScope.get()), AclManager.emitter);
     }
     permission(permission) {
         if (permission) {
-            return new PermissionHasModelRoles(AclManager.modelManager, AclManager.map, { ...this.options }, permission);
+            return new PermissionHasModelRoles(AclManager.modelManager, AclManager.map, this.optionClone(), new Scope().set(this.currentScope.get()), permission, AclManager.emitter);
         }
-        return new EmptyPermission(AclManager.modelManager, AclManager.map, { ...this.options });
-    }
-    createNewScope() {
-        const ScopeClass = AclManager.modelManager.getModel('scope');
-        return new ScopeClass().get();
+        return new EmptyPermission(AclManager.modelManager, AclManager.map, this.optionClone(), new Scope().set(this.currentScope.get()), AclManager.emitter);
     }
     /**
      * changing global options
@@ -63,16 +71,30 @@ export class AclManager {
         if (!this.allowOptionsRewriting && !forceUpdate) {
             throw new Error('Scope method call is not available on global Acl object, use AclManager to create new scoped object or use forceUpdate=true');
         }
-        this.withOptions({
-            scope: scope.get(),
-        }, forceUpdate);
+        this.currentScope = scope;
         return this;
     }
     getScope() {
         return this.options['scope'];
     }
+    withoutEvents(events) {
+        if (events?.length) {
+            this.options.events.except = events;
+            return this;
+        }
+        this.options.events.fire = false;
+        return this;
+    }
+    withEvents(events) {
+        if (events?.length) {
+            this.options.events.only = events;
+            return this;
+        }
+        this.options.events.fire = true;
+        return this;
+    }
+    optionClone() {
+        return structuredClone(this.options);
+    }
 }
-const modelManager = new ModelManager();
-modelManager.setModel('scope', Scope);
-AclManager.setModelManager(modelManager);
 export const Acl = new AclManager(false);

package/build/src/decorators.d.ts

@@ -1,4 +1,6 @@
-export declare function MorphMap(param: string): <T extends new (...args: any[]) => {}>(target: T) => void;
+export declare function MorphMap(param: string): <T extends {
+    new (...args: any[]): {};
+}>(target: T) => void;
 export declare function getClassPath<T extends {
     new (...args: any[]): {};
 }>(clazz: T): string;

package/build/src/events/index.d.ts

@@ -0,0 +1,2 @@
+export * from './roles/roles.js';
+export * from './permissions/permissions.js';

package/build/src/events/index.js

@@ -0,0 +1,2 @@
+export * from './roles/roles.js';
+export * from './permissions/permissions.js';

package/build/src/events/permissions/permissions.d.ts

@@ -0,0 +1,80 @@
+import { BaseEvent } from '@adonisjs/core/events';
+import Permission from '../../models/permission.js';
+import { ModelIdType } from '../../types.js';
+import { LucidModel } from '@adonisjs/lucid/types/model';
+export declare class PermissionCreatedEvent extends BaseEvent {
+    permission: Permission;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permission: Permission);
+}
+export declare class PermissionDeletedEvent extends BaseEvent {
+    permission: string;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permission: string);
+}
+export declare class PermissionsAttachedToRoleEvent extends BaseEvent {
+    permissionIds: ModelIdType[];
+    roleId: ModelIdType;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permissionIds: ModelIdType[], roleId: ModelIdType);
+}
+export declare class PermissionsDetachedFromRoleEvent extends BaseEvent {
+    permissions: string[];
+    roleId: ModelIdType;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permissions: string[], roleId: ModelIdType);
+}
+export declare class PermissionsAttachedToModelEvent<T extends LucidModel> extends BaseEvent {
+    permissionIds: ModelIdType[];
+    model: T;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permissionIds: ModelIdType[], model: T);
+}
+export declare class PermissionsDetachedFromModelEvent<T extends LucidModel> extends BaseEvent {
+    permissions: string[];
+    model: T;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permissions: string[], model: T);
+}
+export declare class PermissionsFlushedEvent<T extends LucidModel> extends BaseEvent {
+    model: T;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(model: T);
+}
+export declare class PermissionsForbadeEvent<T extends LucidModel> extends BaseEvent {
+    permissionIds: ModelIdType[];
+    model: T;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permissionIds: ModelIdType[], model: T);
+}
+export declare class PermissionsUnForbadeEvent<T extends LucidModel> extends BaseEvent {
+    permissionIds: ModelIdType[];
+    model: T;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permissionIds: ModelIdType[], model: T);
+}
+export declare class PermissionsFlushedFromRoleEvent extends BaseEvent {
+    roleId: ModelIdType;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(roleId: ModelIdType);
+}