@holoyan/adonisjs-permissions 1.0.5 → 1.2.0

package/README.md

@@ -12,6 +12,11 @@ Checkout other AdonisJS packages
 - It's simple, just star this repository, that is enough to keep me motivated to maintain this package.
 
 
+## Release Notes
+
+Version: >= v1.2.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
 
 <details><summary>Click to expand</summary><p>
@@ -49,6 +54,7 @@ Checkout other AdonisJS packages
     - [The Scope middleware](#the-scope-middleware) 
     - [Default Scope](#default-scope-tenant)
   - [Transactions](#transactions)
+  - [Events](#events)
 - [Cheat sheet](#cheat-sheet)
 - [Todo](#todo)
 - [Test](#test)
@@ -104,7 +110,7 @@ Example.
 ```typescript
 
 import { BaseModel, column } from '@adonisjs/lucid/orm'
-import { MorphMap } from '@holoyan/adonisjs-permissions'
+import { MorphMap } from '@holoyan/morph-map-js'  // (NOTE upper case `MorphMap`)
 import { AclModelInterface } from '@holoyan/adonisjs-permissions/types'
 
 @MorphMap('users')
@@ -135,11 +141,6 @@ export default class Post extends BaseModel implements AclModelInterface {
 
 ```
 
-## Release Notes
-
-Version: >= v1.0.3
-* Added `sync` method
-
 ## Mixins
 
 If you want to be able to call `Acl` methods on a `User` model then consider using `hasPermissions` mixin
@@ -147,7 +148,7 @@ If you want to be able to call `Acl` methods on a `User` model then consider usi
 ```typescript
 
 import { BaseModel, column } from '@adonisjs/lucid/orm'
-import { MorphMap } from '@holoyan/adonisjs-permissions'
+import { MorphMap } from '@holoyan/morph-map-js'  // (NOTE upper case `MorphMap`)
 import { AclModelInterface } from '@holoyan/adonisjs-permissions/types'
 
 // import mixin
@@ -992,6 +993,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
@@ -1138,7 +1272,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
@@ -1153,7 +1287,7 @@ await Acl.permission(myPermission).detachFromRole(role_slug)
 
 | AdonisJS Lucid version | Package version |
 |------------------------|-----------------|
-| v20.x                  | 0.8.x           |
+| v20.x                  | 0.10.x          |
 | v21.x                  | 1.x             |
 
 

package/build/index.d.ts

@@ -8,8 +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';
 export { Scope } from './src/scope.js';

package/build/index.js

@@ -16,8 +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';
 export { Scope } from './src/scope.js';

package/build/providers/role_permission_provider.d.ts

@@ -1,9 +1,9 @@
 import { ApplicationService } from '@adonisjs/core/types';
 import ModelManager from '../src/model_manager.js';
-import MorphMap from '../src/morph_map.js';
+import { MorphMapManager } from '@holoyan/morph-map-js';
 declare module '@adonisjs/core/types' {
     interface ContainerBindings {
-        morphMap: MorphMap;
+        morphMap: MorphMapManager;
         modelManager: ModelManager;
     }
 }

package/build/providers/role_permission_provider.js

@@ -4,8 +4,8 @@ import ModelPermission from '../src/models/model_permission.js';
 import ModelRole from '../src/models/model_role.js';
 import ModelManager from '../src/model_manager.js';
 import { AclManager } from '../src/acl.js';
-import MorphMap from '../src/morph_map.js';
 import { Scope } from '../src/scope.js';
+import { morphMap } from '@holoyan/morph-map-js';
 export default class RolePermissionProvider {
     app;
     constructor(app) {
@@ -13,11 +13,20 @@ export default class RolePermissionProvider {
     }
     register() {
         this.app.container.singleton('morphMap', async () => {
-            return new MorphMap();
+            return morphMap;
         });
         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,10 +35,12 @@ 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);
+        // map.set('permissions', Permission)
+        // map.set('roles', Role)
         AclManager.setMorphMap(map);
     }
 }

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/decorators.js

@@ -1,19 +1,11 @@
-import app from '@adonisjs/core/services/app';
+import { morphMap, getClassPath as baseGetClassPath } from '@holoyan/morph-map-js';
+// keep for backward compatibility
 export function MorphMap(param) {
     return function (target) {
-        const service = async function () {
-            var result = await app.container.make('morphMap');
-            result.set(param, target);
-            return param;
-        };
-        target.prototype.__morphMapName = service();
+        morphMap.set(param, target);
         target.prototype.__morphMapName = param;
     };
 }
 export function getClassPath(clazz) {
-    const morphMapName = clazz.prototype.__morphMapName;
-    if (!morphMapName) {
-        throw new Error('morph map name not specified');
-    }
-    return morphMapName;
+    return baseGetClassPath(clazz);
 }

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;
+    }
+}