@holoyan/adonisjs-permissions 0.8.23 → 0.10.0

package/README.md

@@ -1,5 +1,9 @@
 # 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)
 
@@ -7,6 +11,10 @@
 
 - It's simple, just star this repository, that is enough to keep me motivated to maintain this package.
 
+## Release Notes
+
+Version: >= v0.10.0
+* Added [Morph Map](https://github.com/holoyan/morph-map-js) as a dependency to handle polymorphic relations - fixed [#20](https://github.com/holoyan/adonisjs-permissions/issues/20)
 
 ## Table of Contents
 
@@ -45,9 +53,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>
 
@@ -77,7 +87,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.10.0
 
 
 Next publish config files
@@ -130,11 +140,6 @@ export default class Post extends BaseModel implements AclModelInterface {
 
 ```
 
-## Release Notes
-
-Version: >= 'v0.8.21'
-* Added `sync` methods
-
 ## Mixins
 
 If you want to be able to call `Acl` methods on a `User` model then consider using `hasPermissions` mixin
@@ -987,6 +992,139 @@ 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
 
 Model methods
@@ -1133,7 +1271,7 @@ await Acl.permission(myPermission).detachFromRole(role_slug)
 
 - [X] Scopes (Multitenancy)
 - [X] UUID support
-- [ ] Events
+- [X] Events
 - [ ] More test coverage
 - [ ] Caching
 - [ ] Integration with AdonisJs Bouncer
@@ -1143,6 +1281,16 @@ await Acl.permission(myPermission).detachFromRole(role_slug)
     npm run test
 
 
+## Version Map
+
+
+| AdonisJS Lucid version | Package version |
+|------------------------|-----------------|
+| v20.x                  | 0.10.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/models/model_has_role_permissions.js';
-import { AclModel, MorphInterface, OptionsInterface, PermissionInterface, RoleInterface, ScopeInterface } from './types.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/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/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);
+}

package/build/src/events/permissions/permissions.js

@@ -0,0 +1,113 @@
+import { BaseEvent } from '@adonisjs/core/events';
+export class PermissionCreatedEvent extends BaseEvent {
+    permission;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permission) {
+        super();
+        this.permission = permission;
+    }
+}
+export class PermissionDeletedEvent extends BaseEvent {
+    permission;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permission) {
+        super();
+        this.permission = permission;
+    }
+}
+export class PermissionsAttachedToRoleEvent extends BaseEvent {
+    permissionIds;
+    roleId;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permissionIds, roleId) {
+        super();
+        this.permissionIds = permissionIds;
+        this.roleId = roleId;
+    }
+}
+export class PermissionsDetachedFromRoleEvent extends BaseEvent {
+    permissions;
+    roleId;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permissions, roleId) {
+        super();
+        this.permissions = permissions;
+        this.roleId = roleId;
+    }
+}
+export class PermissionsAttachedToModelEvent extends BaseEvent {
+    permissionIds;
+    model;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permissionIds, model) {
+        super();
+        this.permissionIds = permissionIds;
+        this.model = model;
+    }
+}
+export class PermissionsDetachedFromModelEvent extends BaseEvent {
+    permissions;
+    model;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permissions, model) {
+        super();
+        this.permissions = permissions;
+        this.model = model;
+    }
+}
+export class PermissionsFlushedEvent extends BaseEvent {
+    model;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(model) {
+        super();
+        this.model = model;
+    }
+}
+export class PermissionsForbadeEvent extends BaseEvent {
+    permissionIds;
+    model;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permissionIds, model) {
+        super();
+        this.permissionIds = permissionIds;
+        this.model = model;
+    }
+}
+export class PermissionsUnForbadeEvent extends BaseEvent {
+    permissionIds;
+    model;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(permissionIds, model) {
+        super();
+        this.permissionIds = permissionIds;
+        this.model = model;
+    }
+}
+export class PermissionsFlushedFromRoleEvent extends BaseEvent {
+    roleId;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(roleId) {
+        super();
+        this.roleId = roleId;
+    }
+}

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

@@ -0,0 +1,40 @@
+import { BaseEvent } from '@adonisjs/core/events';
+import Role from '../../models/role.js';
+import { LucidModel } from '@adonisjs/lucid/types/model';
+export declare class RoleCreatedEvent extends BaseEvent {
+    role: Role;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(role: Role);
+}
+export declare class RoleDeletedEvent extends BaseEvent {
+    role: string;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(role: string);
+}
+export declare class RolesAttachedToModel<T extends LucidModel> extends BaseEvent {
+    roles: string[];
+    model: T;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(roles: string[], model: T);
+}
+export declare class RolesDetachedFromModelEvent<T extends LucidModel> extends BaseEvent {
+    roles: string[];
+    model: T;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(roles: string[], model: T);
+}
+export declare class RolesFlushedFromModelEvent extends BaseEvent {
+    model: LucidModel;
+    /**
+     * Accept event data as constructor parameters
+     */
+    constructor(model: LucidModel);
+}