@yuuvis/client-core 2.20.1 → 2.21.0

package/fesm2022/yuuvis-client-core.mjs

@@ -4514,47 +4514,128 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.20", ngImpo
         }] });
 
 /**
- * Service for managing Identity Management (IDM) operations.
- * Provides functionality for querying users, roles, and organization entities,
- * with built-in caching mechanisms to optimize performance.
+ * Centralized service for Identity Management (IDM) operations.
+ *
+ * Provides a typed API for querying users, roles, and organization entities
+ * from the IDM backend, with a built-in client-side caching layer that
+ * minimizes redundant HTTP calls.
+ *
+ * **Key Features:**
+ * - User lookup by ID with automatic 1-hour TTL cache
+ * - Unified search across users and roles via a single method
+ * - Role listing with optional name filter
+ * - Cache persisted to IndexedDB/localStorage (survives page refresh)
+ * - In-memory cache hydrated on service creation for instant access
+ *
+ * **Caching Strategy:**
+ * All cached users are stored as a single map ({@link IdmUserCache}) under one
+ * storage key. This enables atomic load on startup — one read populates the
+ * entire in-memory cache — and avoids N+1 reads when resolving multiple users
+ * (e.g. audit trails, comment threads, assignment lists). Per-entry TTL is
+ * enforced via {@link IdmCachedUser.expires}.
+ *
+ * ```
+ * getUserById("abc")
+ *   ├─ Cache hit & valid  → return immediately (no HTTP)
+ *   └─ Cache miss/expired → GET /idm/users/abc
+ *                           ├─ Update in-memory cache
+ *                           ├─ Persist to ClientCacheService
+ *                           └─ Return YuvUser
+ * ```
+ *
+ * **API Endpoints:**
+ * | Method                     | Endpoint             |
+ * |----------------------------|----------------------|
+ * | `queryOrganizationEntity`  | `GET /idm/search`    |
+ * | `getRoles`                 | `GET /idm/roles`     |
+ * | `getUserById`              | `GET /idm/users/:id` |
+ *
+ * **Usage:**
+ * ```ts
+ * const idm = inject(IdmService);
+ *
+ * // Search users and roles
+ * idm.queryOrganizationEntity('admin', ['user', 'role'])
+ *   .subscribe(entries => console.log(entries));
+ *
+ * // Get a user by ID (cached)
+ * idm.getUserById('user-uuid').subscribe(user => console.log(user?.title));
+ *
+ * // List roles
+ * idm.getRoles('ADMIN').subscribe(roles => console.log(roles));
+ * ```
+ *
+ * @see {@link ClientCacheService} for the underlying persistence layer
+ * @see {@link YuvUser} for the application-level user model
  */
 class IdmService {
-    #backend;
-    #clientCache;
-    #IDM_USER_CACHE_KEY;
-    #IDM_USER_CACHE_TTL; // 1 hour in milliseconds
+    //#region Dependencies
+    #backend = inject(BackendService);
+    #clientCache = inject(ClientCacheService);
+    //#endregion
+    //#region Cache configuration
+    #cacheKey = 'yuv-idm-user-cache';
+    /**
+     * Time-to-live for cached user entries (in milliseconds).
+     *
+     * After this period a cached entry is considered stale and the next
+     * {@link getUserById} call for that user will re-fetch from the backend.
+     *
+     * **Timeline:**
+     * ```
+     * [User fetched] ─────────── 1 hour ──────────► [Entry expires]
+     *                 cache hit returns instantly     next access re-fetches
+     * ```
+     *
+     * @default 1 hour (3600000 milliseconds)
+     */
+    #cacheTtl = 60 * 60 * 1000;
+    #userCache = {};
+    //#endregion
     constructor() {
-        this.#backend = inject(BackendService);
-        this.#clientCache = inject(ClientCacheService);
-        this.#IDM_USER_CACHE_KEY = 'yuv-idm-user-cache';
-        this.#IDM_USER_CACHE_TTL = 60 * 60 * 1000; // 1 hour in milliseconds
-        this.userCache = {};
-        this.#loadIdmCache();
+        this.#loadCacheFromStorage();
     }
+    //#region Public methods
     /**
-     * Queries organization entities (users and/or roles) based on search term.
+     * Searches organization entities (users and/or roles) by a free-text term.
+     *
+     * Returns a unified {@link OrganizationSetEntry} array so consumers
+     * (autocomplete fields, assignment dialogs, permission pickers) can
+     * treat users and roles interchangeably.
      *
-     * @param term - The search term to filter entities
-     * @param targetTypes - Array of entity types to search for ('user', 'role')
+     * @param term - Free-text search term to filter entities
+     * @param targetTypes - Entity types to include in results (`'user'`, `'role'`, or both)
      * @param size - Optional maximum number of results to return
-     * @returns Observable array of organization set entries matching the search criteria
+     * @returns Observable of matching organization entities
+     *
+     * @example
+     * ```ts
+     * // Search for users and roles matching "admin"
+     * idmService.queryOrganizationEntity('admin', ['user', 'role'], 10)
+     *   .subscribe(entries => {
+     *     const users = entries.filter(e => e.type === 'user');
+     *     const roles = entries.filter(e => e.type === 'role');
+     *   });
+     * ```
      */
     queryOrganizationEntity(term, targetTypes, size) {
-        const searchParams = new URLSearchParams();
-        searchParams.set('search', term);
-        size && searchParams.set('size', size.toString());
-        return this.#backend.get(`/idm/search?${searchParams.toString()}`).pipe(map$1((res) => [
+        const params = new URLSearchParams();
+        params.set('search', term);
+        if (size) {
+            params.set('size', size.toString());
+        }
+        return this.#backend.get(`/idm/search?${params.toString()}`).pipe(map$1((res) => [
             ...(targetTypes.includes('user')
-                ? res.users.map((u) => ({
-                    id: u.id,
-                    title: `${u.lastname}, ${u.firstname} (${u.username})`, // TODO: u.title,
+                ? res.users.map((user) => ({
+                    id: user.id,
+                    title: `${user.lastname}, ${user.firstname} (${user.username})`,
                     type: 'user'
                 }))
                 : []),
             ...(targetTypes.includes('role')
-                ? res.roles.map((u) => ({
-                    id: u.name,
-                    title: u.name,
+                ? res.roles.map((role) => ({
+                    id: role.name,
+                    title: role.name,
                     type: 'role'
                 }))
                 : [])
@@ -4563,42 +4644,66 @@ class IdmService {
     /**
      * Retrieves available roles, optionally filtered by a search term.
      *
+     * Returns an empty array on error to ensure consumers can always
+     * safely iterate the result without null-checking.
+     *
      * @param role - Optional search term to filter roles by name
-     * @returns Observable array of role objects containing name and description
+     * @returns Observable of role objects containing name and description
+     *
+     * @example
+     * ```ts
+     * // List all roles
+     * idmService.getRoles().subscribe(roles => console.log(roles));
+     *
+     * // Filter roles by name
+     * idmService.getRoles('ADMIN').subscribe(roles => console.log(roles));
+     * ```
      */
     getRoles(role) {
-        const searchParams = new URLSearchParams();
-        role && searchParams.set('search', role);
-        return this.#backend.get(`/idm/roles?${searchParams.toString()}`).pipe(catchError$1(() => of([])));
+        const params = new URLSearchParams();
+        if (role) {
+            params.set('search', role);
+        }
+        return this.#backend.get(`/idm/roles?${params.toString()}`).pipe(catchError$1(() => of([])));
     }
     /**
-     * Retrieves user information by user ID with automatic caching.
-     * Uses a 1-hour TTL cache to minimize backend requests.
+     * Retrieves a user by ID with automatic caching.
+     *
+     * Checks the in-memory cache first. If a valid (non-expired) entry exists,
+     * it is returned immediately without an HTTP call. Otherwise, the user is
+     * fetched from the backend, stored in both the in-memory and persistent
+     * cache, and returned as a {@link YuvUser}.
      *
-     * @param id - The unique identifier of the user
-     * @returns Observable of YuvUser object or null if user is not found
+     * Returns `null` if the user is not found or the request fails,
+     * so consumers can safely use the result without try/catch.
+     *
+     * @param id - Unique user identifier (UUID)
+     * @returns Observable of the user model, or `null` if not found / on error
+     *
+     * @example
+     * ```ts
+     * idmService.getUserById('550e8400-e29b-41d4-a716-446655440000')
+     *   .subscribe(user => {
+     *     if (user) {
+     *       console.log(user.getFullName());
+     *     }
+     *   });
+     * ```
      */
     getUserById(id) {
-        const cachedUser = this.userCache[id];
-        const isCacheValid = cachedUser && Date.now() < cachedUser.expires;
-        if (isCacheValid) {
-            return of(new YuvUser(cachedUser.user));
-        }
-        else {
-            return this.#backend.get(`/idm/users/${id}`).pipe(switchMap$1((user) => {
-                this.userCache[id] = {
-                    expires: Date.now() + this.#IDM_USER_CACHE_TTL,
-                    user
-                };
-                return this.#clientCache.updateCache(this.#IDM_USER_CACHE_KEY, this.userCache).pipe(map$1(() => user));
-            }), map$1((user) => (user ? new YuvUser(user) : null)), catchError$1(() => of(null)));
+        if (id in this.#userCache && Date.now() < this.#userCache[id].expires) {
+            return of(new YuvUser(this.#userCache[id].user));
         }
+        return this.#backend.get(`/idm/users/${id}`).pipe(switchMap$1((user) => {
+            this.#userCache[id] = { expires: Date.now() + this.#cacheTtl, user };
+            return this.#clientCache.updateCache(this.#cacheKey, this.#userCache).pipe(map$1(() => user));
+        }), map$1((user) => new YuvUser(user)), catchError$1(() => of(null)));
     }
-    #loadIdmCache() {
-        return this.#clientCache.getFromCache(this.#IDM_USER_CACHE_KEY).subscribe({
-            next: (cache) => {
-                this.userCache = cache || {};
-            }
+    //#endregion
+    //#region Cache
+    #loadCacheFromStorage() {
+        this.#clientCache.getFromCache(this.#cacheKey).subscribe({
+            next: (cache) => (this.#userCache = cache || {})
         });
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.2.20", ngImport: i0, type: IdmService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }