@hichchi/ngx-auth 0.0.9 → 0.0.11

package/fesm2022/hichchi-ngx-auth.mjs

@@ -1881,22 +1881,24 @@ function authGuard(param, state, fallbackRedirect) {
  * Creates a role-based authorization guard function for Angular route protection
  *
  * This function creates a route guard that protects routes based on user roles.
- * It checks if the current user's role matches the required role, and if not,
- * it evaluates the provided options to determine the appropriate action (redirect
- * or sign out).
+ * It first checks whether the current user's role matches the required role(s).
+ * If it does not match, it evaluates the provided options to determine the
+ * appropriate action (redirect or sign out).
  *
  * The guard integrates with the AuthState service to check the current user's role
- * and uses the Angular Router for navigation when redirects are needed. If no
- * matching role or redirect option is found, the user is automatically signed out.
+ * and uses the Angular Router for navigation when redirects are needed. If the
+ * required role check fails and no matching redirect option is found, the user is
+ * automatically signed out.
  *
  * Key features:
  * - Role-based route protection
+ * - Supports both a single required role and multiple allowed roles
  * - Configurable redirect options based on user roles
  * - Automatic sign-out for unauthorized access
  * - Integration with AuthState for reactive role checking
  * - Support for multiple role-based redirect scenarios
  *
- * @param role - The required role name that the user must have to access the route
+ * @param role - The required role name (or list of allowed roles) for route access
  * @param options - Array of role guard options that define redirect behavior for different user roles
  * @returns A CanActivateFn that evaluates role-based authorization and handles navigation
  *
@@ -1942,6 +1944,28 @@ function authGuard(param, state, fallbackRedirect) {
  * ];
  * ```
  *
+ * @example
+ * ```typescript
+ * // Allowing multiple roles
+ * const routes: Routes = [
+ *   {
+ *     path: 'reports',
+ *     component: ReportsComponent,
+ *     canActivate: [roleGuard(['admin', 'manager'], [
+ *       { state: 'user', redirect: '/dashboard' }
+ *     ])]
+ *   }
+ * ];
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Evaluation order:
+ * // 1) role match => allow
+ * // 2) role mismatch + matching option.state => redirect
+ * // 3) role mismatch + no matching option.state => sign out
+ * ```
+ *
  * @see {@link AuthState} Service that provides authentication and role state information
  * @see {@link RoleGuardOption} Interface for configuring role-based redirect options
  */
@@ -1950,15 +1974,14 @@ function roleGuard(role, options) {
     return async (_route, _state) => {
         const router = inject(Router);
         const authState = inject(AuthState);
-        if (!options.length) {
+        const currentRole = authState.roleName();
+        if (Array.isArray(role) ? role.includes(currentRole) : role === currentRole) {
             return true;
         }
-        for await (const option of options) {
-            if (role === authState.roleName()) {
-                return true;
-            }
-            else if (option.state === authState.roleName()) {
+        for (const option of options) {
+            if (option.state === currentRole) {
                 const redirectPath = option.redirect.startsWith("/") ? option.redirect : `/${option.redirect}`;
+                // eslint-disable-next-line no-await-in-loop
                 await router.navigateByUrl(redirectPath);
                 return false;
             }