@holoyan/adonisjs-permissions 1.3.0 → 1.3.1

package/README.md

@@ -14,8 +14,8 @@ Checkout other AdonisJS packages
 
 ## Release Notes
 
-Version: >= v1.3.0
-* Added [query helpers](#permissionqueryhelpers-mixin) mixin. To make it easier to query users(models) based on their roles and permissions
+Version: >= v1.3.1
+* Added [canPartially](#checking-partial-permissions) method
 
 ## Table of Contents
 
@@ -504,6 +504,21 @@ await Acl.role(role).hasAnyPermission(['update', 'read'])
 
 ```
 
+### Checking partial permissions
+
+Sometimes you might want to check if a user has a specific permission on any instance of a model class, rather than checking for global permissions or permissions on a specific instance. For this purpose, you can use the `canPartially` method:
+
+```typescript
+
+const postWithId = await Post.find(id)
+await Acl.model(user).allow('create', postWithId) // allow 'create' on post instance
+
+// This is useful when you want to know if a user has permission on at least one instance
+Acl.model(user).can('create') // will return false
+Acl.model(user).can('create', Post) // will return false
+Acl.model(user).canPartially('create', Post) // will return true because user has a 'create' permission on postWithId instance
+```
+
 ### Middleware
 
 You are free to do your check anywhere, for example we can create [named](https://docs.adonisjs.com/guides/middleware#named-middleware-collection) middleware and do checking

package/build/src/mixins/has_permissions.d.ts

@@ -142,6 +142,12 @@ export declare function hasPermissions(): <Model extends NormalizeConstructor<ty
          */
         canAll(permissions: string[], target?: AclModel | Function): Promise<boolean>;
         canAny(permissions: string[], target?: AclModel | Function): Promise<boolean>;
+        /**
+         * Check if a model has permission on any instance of a model class
+         * @param permission
+         * @param targetClass
+         */
+        canPartially(permission: string, targetClass: Function): Promise<boolean>;
         /**
          * Check if model has any permission
          * @param permission

package/build/src/mixins/has_permissions.js

@@ -204,6 +204,14 @@ export function hasPermissions() {
             canAny(permissions, target) {
                 return Acl.model(this).canAny(permissions, target);
             }
+            /**
+             * Check if a model has permission on any instance of a model class
+             * @param permission
+             * @param targetClass
+             */
+            canPartially(permission, targetClass) {
+                return Acl.model(this).canPartially(permission, targetClass);
+            }
             /**
              * Check if model has any permission
              * @param permission

package/build/src/services/helper.d.ts

@@ -22,3 +22,8 @@ export declare function destructTarget(map: MorphInterface, target?: AclModel |
     targetId: ModelIdType | null;
 };
 export declare function applyTargetRestriction(table: string, q: ManyToManySubQueryBuilderContract<typeof Permission> | ModelQueryBuilderContract<typeof Permission, PermissionInterface> | RelationSubQueryBuilderContract<typeof ModelRole>, entityType: string | null, entityId: ModelIdType | null): void;
+/**
+ * Apply target restriction for partial permission checks
+ * This function doesn't check entity_id when only entityType is provided
+ */
+export declare function applyPartialTargetRestriction(table: string, q: ManyToManySubQueryBuilderContract<typeof Permission> | ModelQueryBuilderContract<typeof Permission, PermissionInterface> | RelationSubQueryBuilderContract<typeof ModelRole>, entityType: string): void;

package/build/src/services/helper.js

@@ -80,3 +80,10 @@ export function applyTargetRestriction(table, q, entityType, entityId) {
         q.where(table + '.entity_type', '*').whereNull(table + '.entity_id');
     }
 }
+/**
+ * Apply target restriction for partial permission checks
+ * This function doesn't check entity_id when only entityType is provided
+ */
+export function applyPartialTargetRestriction(table, q, entityType) {
+    q.where(table + '.entity_type', entityType).whereNotNull(table + '.entity_id');
+}

package/build/src/services/models/model_has_role_permissions.d.ts

@@ -102,6 +102,24 @@ export declare class ModelHasRolePermissions extends BaseAdapter {
     can(permission: string, target?: AclModel | Function): Promise<boolean>;
     canAll(permissions: string[], target?: AclModel | Function): Promise<boolean>;
     canAny(permissions: string[], target?: AclModel | Function): Promise<boolean>;
+    /**
+     * Check if model has permission on any instance of a model class
+     * @param permission
+     * @param targetClass
+     */
+    hasPartialPermission(permission: string, targetClass: Function): Promise<boolean>;
+    /**
+     * Check if model has any of the permissions on any instance of a model class
+     * @param permissions
+     * @param targetClass
+     */
+    hasAnyPartialPermission(permissions: string[], targetClass: Function): Promise<boolean>;
+    /**
+     * Check if a model has permission on any instance of a model class
+     * @param permission
+     * @param targetClass
+     */
+    canPartially(permission: string, targetClass: Function): Promise<boolean>;
     /**
      * calls assignDirectAllPermissions()
      * @param permission

package/build/src/services/models/model_has_role_permissions.js

@@ -213,6 +213,31 @@ export class ModelHasRolePermissions extends BaseAdapter {
     canAny(permissions, target) {
         return this.hasAnyPermission(permissions, target);
     }
+    /**
+     * Check if model has permission on any instance of a model class
+     * @param permission
+     * @param targetClass
+     */
+    async hasPartialPermission(permission, targetClass) {
+        return this.hasAnyPartialPermission([permission], targetClass);
+    }
+    /**
+     * Check if model has any of the permissions on any instance of a model class
+     * @param permissions
+     * @param targetClass
+     */
+    async hasAnyPartialPermission(permissions, targetClass) {
+        const entityType = this.map.getAlias(targetClass);
+        return await this.permissionService.hasAnyPartial(this.map.getAlias(this.model), this.model.getModelId(), permissions, entityType);
+    }
+    /**
+     * Check if a model has permission on any instance of a model class
+     * @param permission
+     * @param targetClass
+     */
+    canPartially(permission, targetClass) {
+        return this.hasPartialPermission(permission, targetClass);
+    }
     /**
      * calls assignDirectAllPermissions()
      * @param permission

package/build/src/services/permissions/permissions_service.d.ts

@@ -57,6 +57,10 @@ export default class PermissionsService extends BaseService {
      * has any of permissions
      */
     hasAny(modelType: string, modelId: ModelIdType, permission: string[], entityType: string | null, entityId: ModelIdType | null): Promise<boolean>;
+    /**
+     * has any of permissions on any instance of a model class
+     */
+    hasAnyPartial(modelType: string, modelId: ModelIdType, permissions: string[], entityType: string): Promise<boolean>;
     /**
      * has all permissions
      */
@@ -109,6 +113,7 @@ export default class PermissionsService extends BaseService {
     reverseModelPermissionQuery(conditions: Partial<ModelPermissionsQuery>): ModelQueryBuilderContract<typeof import("../../models/model_permission.js").default, import("../../models/model_permission.js").default>;
     findAssignableEntity(permission: string[], entityClass: string | null, entityId: ModelIdType | null, allowed: boolean): ModelQueryBuilderContract<typeof Permission, Permission>;
     private applyTargetRestriction;
+    private applyPartialTargetRestriction;
     private applyScopes;
     private applyModelPermissionScopes;
 }

package/build/src/services/permissions/permissions_service.js

@@ -1,5 +1,5 @@
 import BaseService from '../base_service.js';
-import { applyTargetRestriction } from '../helper.js';
+import { applyTargetRestriction, applyPartialTargetRestriction } from '../helper.js';
 export default class PermissionsService extends BaseService {
     options;
     scope;
@@ -204,6 +204,27 @@ export default class PermissionsService extends BaseService {
         const r = await q.distinct(this.permissionTable + '.id').select(this.permissionTable + '.id');
         return r.length > 0;
     }
+    /**
+     * has any of permissions on any instance of a model class
+     */
+    async hasAnyPartial(modelType, modelId, permissions, entityType) {
+        const { slugs, ids } = this.formatList(permissions);
+        const q = this.modelPermissionQueryWithForbiddenCheck({
+            modelType,
+            modelId,
+            directPermissions: this.map.getAlias(this.roleClassName) === modelType,
+            permissionSlugs: slugs,
+            permissionIds: ids,
+            entity: {
+                type: entityType,
+                id: null,
+            },
+        });
+        // We use applyPartialTargetRestriction which doesn't check entity_id when only entityType is provided
+        this.applyPartialTargetRestriction(this.permissionTable, q, entityType);
+        const r = await q.distinct(this.permissionTable + '.id').select(this.permissionTable + '.id');
+        return r.length > 0;
+    }
     /**
      * has all permissions
      */
@@ -496,6 +517,9 @@ export default class PermissionsService extends BaseService {
     applyTargetRestriction(table, q, entityType, entityId) {
         applyTargetRestriction(table, q, entityType, entityId);
     }
+    applyPartialTargetRestriction(table, q, entityType) {
+        applyPartialTargetRestriction(table, q, entityType);
+    }
     applyScopes(q) {
         q.where(this.permissionTable + '.scope', this.scope.get());
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@holoyan/adonisjs-permissions",
   "description": "AdonisJs roles and permissions system",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "engines": {
     "node": ">=18.16.0"
   },