@hichchi/ngx-auth 0.0.9 → 0.0.11

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hichchi/ngx-auth",
   "description": "A utility library for Angular applications with common services, interceptors, and state management",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "publishConfig": {
     "access": "public"
   },
@@ -19,10 +19,10 @@
     "@angular/core": "^21.1.4",
     "@angular/forms": "^21.1.4",
     "@angular/router": "^21.1.4",
-    "@hichchi/nest-connector": "0.0.9",
-    "@hichchi/ngx-ui": "0.0.9",
-    "@hichchi/ngx-utils": "0.0.9",
-    "@hichchi/utils": "0.0.9",
+    "@hichchi/nest-connector": "0.0.11",
+    "@hichchi/ngx-ui": "0.0.11",
+    "@hichchi/ngx-utils": "0.0.11",
+    "@hichchi/utils": "0.0.11",
     "@ngrx/signals": "^21.0.1",
     "rxjs": "^7.8.2"
   },

package/types/hichchi-ngx-auth.d.ts

@@ -194,10 +194,10 @@ interface AuthGuardOption {
     redirect: string;
 }
 
-interface RoleGuardOption {
-    /** The required state of the role */
-    state?: string;
-    /** The route to redirect to if the role exist */
+interface RoleGuardOption<T = string> {
+    /** Role name that should be redirected when the required role check fails */
+    state?: T;
+    /** Route path to navigate to when `state` matches the current role */
     redirect: string;
 }
 
@@ -568,22 +568,24 @@ declare function authGuard(condition: AuthGuardCondition, state: boolean, fallba
  * 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
  *
@@ -629,10 +631,32 @@ declare function authGuard(condition: AuthGuardCondition, state: boolean, fallba
  * ];
  * ```
  *
+ * @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
  */
-declare function roleGuard(role: string, options: RoleGuardOption[]): CanActivateFn;
+declare function roleGuard<T = string>(role: T | T[], options: RoleGuardOption<T>[]): CanActivateFn;
 
 /**
  * Array of authentication error codes that should trigger token refresh instead of immediate redirect
@@ -895,7 +919,7 @@ declare const AuthState: _angular_core.Type<{
 /**
  * Public typed shape of the `AuthState` signal store.
  */
-type AuthState<D = unknown, R extends string = string, P extends string = string, U extends User<R, P> = User<R, P>> = {
+type AuthState<D = unknown, R extends string = string, P extends string = string, U = User<R, P>> = {
     signedIn: Signal<boolean>;
     sessionId: Signal<string | null>;
     user: Signal<U | null>;
@@ -905,7 +929,9 @@ type AuthState<D = unknown, R extends string = string, P extends string = string
     refreshTokenExpiresOn: Signal<Date | null>;
     data: Signal<D>;
     hasAccessToken: Signal<boolean>;
-    role: Signal<U["role"] | null | undefined>;
+    role: Signal<U extends {
+        role: infer T;
+    } ? T : null | undefined>;
     roleName: Signal<R | null | undefined>;
     permissions: Signal<P[]>;
     emailVerified: Signal<boolean>;