@eui/core 17.0.0-rc.7 → 17.0.0-rc.8

package/fesm2022/eui-core.mjs

@@ -6,7 +6,7 @@ import { InjectionToken, Injectable, Inject, Injector, NgModule, Optional, APP_I
 import * as extendProxy from 'extend';
 import * as i1$1 from '@ngrx/effects';
 import { createEffect, ofType } from '@ngrx/effects';
-import { fromEvent, merge, throwError, of, forkJoin, BehaviorSubject, defer, firstValueFrom, from, Subject, Observable } from 'rxjs';
+import { fromEvent, merge, throwError, of, forkJoin, from, BehaviorSubject, defer, firstValueFrom, Subject, Observable } from 'rxjs';
 import { map, mapTo, mergeMap, tap, debounceTime, distinctUntilChanged, take, switchMap, catchError, concatMap, filter, takeUntil, finalize } from 'rxjs/operators';
 import * as i1$2 from '@ngx-translate/core';
 import { TranslateLoader } from '@ngx-translate/core';
@@ -1257,6 +1257,40 @@ function GrowlHttpErrorCallbackFn(error, injector) {
     asService.growlError(error.statusText);
 }
 
+/**
+ * Service class for managing and processing a queue of API requests.
+ *
+ * This service provides functionality to add, remove, process, and manage HTTP requests stored in a queue.
+ * It enables sequential or bulk processing of requests, ensuring controlled execution and handling of API calls.
+ * The service methods offer features like processing individual items, processing all items in the queue either
+ * sequentially or all at once, and removing items from the queue. Each method is designed to handle specific aspects
+ * of queue management and processing, with attention to details like order of execution and error handling.
+ *
+ * Usage of this service is ideal in scenarios where API requests need to be managed in a queue structure, allowing
+ * for controlled execution and monitoring of these requests.
+ *
+ * @example
+ * // Adding a new item to the queue
+ * apiQueueService.addQueueItem({ id: 'item124', method: 'POST', uri: '/api/data', payload: {...} });
+ *
+ * // Processing a single item from the queue
+ * apiQueueService.processQueueItem('item123').subscribe(result => {
+ *   console.log('Processed item 123 with result:', result);
+ * });
+ *
+ * // Processing all items in the queue in sequential order
+ * apiQueueService.processAllQueueItemsSequential(false).subscribe(results => {
+ *   console.log('Processed all items in descending order of their timestamp:', results);
+ * });
+ *
+ * // Removing an item from the queue
+ * apiQueueService.removeQueueItem('item123');
+ *
+ * // Processing all items in the queue and continuing on error
+ * apiQueueService.processAllQueueItems(true).subscribe(results => {
+ *   console.log('Processed all items in the queue with continuation on errors:', results);
+ * });
+ */
 class ApiQueueService {
     constructor(store, http, logService) {
         this.store = store;
@@ -1264,10 +1298,26 @@ class ApiQueueService {
         this.logService = logService;
     }
     /**
-     * Adds an item in the queue by dispatching an action to the store.
-     * @param id - The id of the item inside the queue.
-     * WARNING if matches any other queue item id will overwrite it.
-     * @param item - an item for Queue
+     * Adds an item to the queue by dispatching an action to the store.
+     * This function is specifically designed to enqueue API call requests represented by `ApiQueueItem` objects.
+     * Each item is identified by a unique `id`, which is used to manage the queue.
+     *
+     * @param {string} id - The unique identifier for the queue item. It's crucial to ensure that this ID is unique within the queue.
+     *                      If an item with the same ID already exists, the new item will overwrite the existing one.
+     *                      WARNING: Duplicate IDs will lead to overwriting of queue items.
+     *
+     * @param {ApiQueueItem} item - The item to be enqueued. This should be an object of type `ApiQueueItem`.
+     *                              The `method` property of the item must be one of the allowed methods ('post', 'put', 'get').
+     *                              If an unsupported method is provided, the function will throw an error.
+     *
+     * @throws {Error} Throws an error if the `method` property of the `item` is not one of the allowed methods.
+     *                 The error message is: `[ApiQueue] method "${item.method}" is not allowed`.
+     *
+     * @example
+     * // Example of adding an item to the API queue
+     * addQueueItem('12345', { method: 'post', url: '/api/data', payload: {...} });
+     *
+     * @returns {void} This function does not return a value. It adds the item to the queue via a dispatch action.
      */
     addQueueItem(id, item) {
         const allowedMethods = ['post', 'put', 'get'];
@@ -1277,8 +1327,25 @@ class ApiQueueService {
         this.store.dispatch(new AddApiQueueItemAction({ id, item }));
     }
     /**
-     * Subscribes to the store to retrieve queue and then converts the queue object to an array of items.
-     * @return An Observable of array of all items inside the current queue (ApiQueueItem[])
+     * Retrieves the current state of the API queue and converts it into an array of Observables.
+     *
+     * This method subscribes to the store to access the API queue. It then maps the queue object,
+     * which is an associative array, into a linear array of ApiQueueItem instances. If the queue is empty,
+     * a warning is logged. This method is useful for tracking the state and contents of the API queue
+     * at a given moment.
+     *
+     * Note: This method takes a snapshot of the queue at the time of subscription. It does not provide
+     * a continuous stream of queue updates. To get real-time updates, consider subscribing directly
+     * to the store's observable.
+     *
+     * @returns {Observable<ApiQueueItem[]>} An Observable that emits an array of ApiQueueItem.
+     * The array represents all items currently in the queue. If the queue is empty, it emits an empty array.
+     *
+     * @example
+     * // Example usage
+     * this.getQueue().subscribe(queueItems => {
+     *   console.log('Current queue items:', queueItems);
+     * });
      */
     getQueue() {
         return this.store.select(getApiQueue).pipe(take(1), map((queue) => {
@@ -1290,9 +1357,29 @@ class ApiQueueService {
         }));
     }
     /**
-     * Subscribes to the store to retrieve an item from the queue.
-     * @param id - id of the item inside the queue
-     * @return An Observable of ApiQueueItem type
+     * Retrieves a specific item from the API queue by its ID.
+     *
+     * This method subscribes to the store and selects a single item from the API queue based on the provided ID.
+     * It employs a pipeline to fetch the item: the `getApiQueueItem` selector is used to retrieve the item,
+     * and a `map` operator processes the result. If the item with the specified ID does not exist in the queue,
+     * a warning is logged, and `null` is returned.
+     *
+     * This method is ideal for accessing a specific queue item when its ID is known, allowing for targeted
+     * operations or checks on that particular item.
+     *
+     * @param {string} id - The unique identifier of the item within the queue.
+     * @returns {Observable<ApiQueueItem | null>} An Observable emitting the requested ApiQueueItem.
+     * If no item with the given ID exists in the queue, the Observable emits `null`.
+     *
+     * @example
+     * // Example usage
+     * this.getQueueItem('item123').subscribe(item => {
+     *   if (item) {
+     *     console.log('Found item:', item);
+     *   } else {
+     *     console.log('Item not found in the queue');
+     *   }
+     * });
      */
     getQueueItem(id) {
         return this.store.select(getApiQueueItem(id)).pipe(take(1), map((queue) => {
@@ -1304,24 +1391,65 @@ class ApiQueueService {
         }));
     }
     /**
-     * Removes a given item from the queue.
-     * @param id - id of the item inside the queue
+     * Removes a specific item from the API queue using its ID.
+     *
+     * This method dispatches an action to remove an item from the queue, identified by the provided ID.
+     * It is essential for managing the queue by eliminating items that are no longer needed or have been processed.
+     * The function does not return any value, as it primarily triggers an action within the store.
+     *
+     * Note: This method assumes the existence of the item in the queue. It does not perform a check
+     * to confirm the presence of the item before attempting to remove it. Therefore, it's recommended
+     * to verify the item's existence in the queue if uncertainty exists.
+     *
+     * @param {string} id - The unique identifier of the item to be removed from the queue.
+     *
+     * @example
+     * // Example usage
+     * this.removeQueueItem('item123');
+     * // The item with ID 'item123' will be dispatched for removal from the queue.
      */
     removeQueueItem(id) {
         this.store.dispatch(new RemoveApiQueueItemAction(id));
     }
     /**
-     * Removes all items placed in the queue.
+     * Clears all items from the API queue.
+     *
+     * This method dispatches an action to empty the entire API queue, effectively removing all items that are currently queued.
+     * It is useful for scenarios where a complete reset of the queue is required, such as during initialization or after processing
+     * a batch of items. The function does not return any value, as its primary purpose is to trigger a state change in the store.
+     *
+     * Note: Use this method with caution as it will irreversibly clear all items in the queue. Ensure that this action does not
+     * disrupt any ongoing processes that rely on the queue's contents.
+     *
+     * @example
+     * // Example usage
+     * this.removeAllQueueItem();
+     * // This will dispatch an action to empty the entire API queue.
      */
     removeAllQueueItem() {
         this.store.dispatch(new EmptyApiQueueAction(null));
     }
     /**
-     * Process an item from the queue.
-     * @param id - id of the item inside the queue
-     * @return An Observable of type any
+     * Processes an item from the API queue identified by its ID.
+     *
+     * Retrieves the specified item from the queue and applies processing logic as defined in `buildHttpRequest`.
+     * If the item is not found, logs a warning and returns an Observable emitting `null`.
+     *
+     * @param {string} id - The unique identifier of the item within the queue to be processed.
+     * @returns {Observable<any>} An Observable that emits the result of processing the queue item.
+     * If the item does not exist, the Observable emits `null`.
+     *
+     * @example
+     * // Example usage
+     * this.processQueueItem('item123').subscribe(result => {
+     *   if (result) {
+     *     console.log('Processing result:', result);
+     *   } else {
+     *     console.log('Item not found in the queue');
+     *   }
+     * });
      */
-    // TODO: find the correct type or turn into a generic, https://www.typescriptlang.org/docs/handbook/2/generics.html
+    // TODO: Replace `any` with a more specific type or make the method generic, https://www.typescriptlang.org/docs/handbook/2/generics.html
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     processQueueItem(id) {
         return this.store.select(getApiQueueItem(id)).pipe(take(1), switchMap((queue) => {
@@ -1333,11 +1461,26 @@ class ApiQueueService {
         }));
     }
     /**
-     * Process all the items inside the queue.
-     * @param [continueOnError=true] - in case of an item request fails continue with the rest in queue
-     * @return An Observable with an array which contains all responses from all items in queue.
+     * Processes all items in the API queue and collects their responses.
+     *
+     * Iterates over each item in the queue and processes them using `buildHttpRequest`. If a request fails,
+     * the method can either continue processing the remaining items or stop, based on the `continueOnError` parameter.
+     * It returns an Observable that emits an array containing the responses or errors from all the processed items.
+     *
+     * The function currently returns `Observable<any[]>` indicating an array of any type. Future improvements
+     * should aim to specify a more accurate return type or utilize generics for increased type safety.
+     *
+     * @param {boolean} [continueOnError=true] - Determines whether to continue with the next item in the queue
+     *                                           after a request failure. Defaults to `true`.
+     * @returns {Observable<any[]>} An Observable emitting an array of either responses or errors from the processed
+     *                              queue items.
+     *
+     * @example
+     * this.processAllQueueItems().subscribe(results => {
+     *   // Handle the array of responses or errors
+     * });
      */
-    // TODO: find the correct type or turn into a generic, https://www.typescriptlang.org/docs/handbook/2/generics.html
+    // TODO: Refine the return type to be more specific or implement generics, https://www.typescriptlang.org/docs/handbook/2/generics.html
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     processAllQueueItems(continueOnError = true) {
         return this.store.select(getApiQueue).pipe(map((queue) => Object.entries(queue).map(([key, value]) => this.buildHttpRequest(key, value).pipe(catchError((error) => {
@@ -1346,40 +1489,80 @@ class ApiQueueService {
                 throw error;
             }
             return of(error);
-        })))), 
-        // TODO: find the correct type or turn into a generic, https://www.typescriptlang.org/docs/handbook/2/generics.html
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        switchMap((obsQueue) => forkJoin(Array.from(obsQueue))));
+        })))), switchMap((obsQueue) => forkJoin(Array.from(obsQueue))));
     }
     /**
-     * Process all items in queue after it order them based on their timestamp. Beware that order
-     * matter in execution of Http Request in queue. When a request completes only then next will begin. Emission
-     * or Http response follows order.
-     * @param [ascending=true] - sets the order of queue items based on timestamp
+     * Processes all items in the queue sequentially, based on their timestamp ordering.
+     *
+     * This method first orders the items in the API queue by their timestamp, either in ascending or descending
+     * order as specified by the `ascending` parameter. It then processes each item using `buildHttpRequest`, ensuring
+     * that each request is completed before the next begins. This sequential processing is crucial when the order of
+     * execution matters for HTTP requests in the queue. The method returns an Observable that emits the responses
+     * following the same order as the queue items were processed.
+     *
+     * The function currently returns `Observable<any>`, indicating a broad type. Future improvements should focus on
+     * specifying a more accurate return type or utilizing generics for increased type safety.
+     *
+     * @param {boolean} [ascending=true] - Determines whether the queue items are processed in ascending order of their
+     *                                     timestamp. Defaults to `true`.
+     * @returns {Observable<any>} An Observable emitting the responses of the HTTP requests in the order they were processed.
+     *
+     * @example
+     * this.processAllQueueItemsSequential().subscribe(response => {
+     *   // Handle each response in the order of queue processing
+     * });
      */
-    // TODO: find the correct type or turn into a generic, https://www.typescriptlang.org/docs/handbook/2/generics.html
+    // TODO: Refine the return type for more specific or implement generics, https://www.typescriptlang.org/docs/handbook/2/generics.html
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     processAllQueueItemsSequential(ascending = true) {
-        return this.store.select(getApiQueue).pipe(concatMap((queue) => Object.entries(queue)
+        return this.store.select(getApiQueue).pipe(switchMap((queue) => from(Object.entries(queue)
             .sort((a, b) => (ascending ? this.sortOnTimestamp(a, b) : this.sortOnTimestamp(b, a)))
-            .map(([id, item]) => this.buildHttpRequest(id, item))));
+            .map(([id, item]) => this.buildHttpRequest(id, item)))
+            .pipe(concatMap(x => x))));
     }
     /**
-     * Short dates ascending based on input
-     * @param a - Date one
-     * @param b - Date two
+     * Compares two queue items based on their timestamp and determines their order.
+     *
+     * This protected method is used to sort queue items. It takes two queue items as input, each represented
+     * as a tuple containing an item ID and the `ApiQueueItem` object. The method compares these items based on
+     * the `timestamp` property of the `ApiQueueItem` objects. It returns a number indicating the order in which
+     * these items should be sorted.
      *
+     * A positive return value indicates that the first item should come after the second, a negative value
+     * indicates the opposite, and zero indicates that they are equal in terms of timestamp.
+     *
+     * @param {[string, ApiQueueItem]} a - The first queue item tuple for comparison.
+     * @param {[string, ApiQueueItem]} b - The second queue item tuple for comparison.
+     * @returns {number} A number indicating the order of the items: negative if `a` is earlier than `b`,
+     *                  positive if `a` is later than `b`, and zero if they are equal.
      * @beta
      */
     sortOnTimestamp(a, b) {
         return +new Date(a[1].timestamp) - +new Date(b[1].timestamp);
     }
     /**
-     * build and HttpRequest Observable based on the given queue.
-     * After successful request completion removes the item from the queue.
-     * @param id - id of the item inside the queue
-     * @param item - the item of the queue that matches the id.
-     * @return An Observable of HttpClient Request
+     * Constructs and executes an HTTP request based on the provided queue item details.
+     *
+     * This private method takes an ID and an `ApiQueueItem` object to build and execute an HTTP request.
+     * It determines the HTTP method (like GET, POST, etc.) from the `method` property of the `ApiQueueItem`,
+     * and uses the `uri` and `payload` properties for the request's URL and body, respectively. After the
+     * request is executed, the corresponding queue item is removed from the queue.
+     *
+     * The method is generic, allowing the caller to specify the expected response type `T`. By default,
+     * it uses `any` type, but specifying a more concrete type enhances type safety and clarity in usage.
+     *
+     * @param {string} id - The ID of the queue item being processed.
+     * @param {ApiQueueItem} item - The queue item containing details for the HTTP request.
+     * @returns {Observable<T>} An Observable of type T, representing the response of the HTTP request.
+     *
+     * @example
+     * // Example usage for a specific response type
+     * this.buildHttpRequest<MyResponseType>('item123', queueItem)
+     *     .subscribe(response => {
+     *         // Handle the response
+     *     });
+     *
+     * @template T - The expected type of the HTTP response. Defaults to `any`.
      */
     // TODO: add type for T and deprecate old function
     // TODO: find the correct type or turn into a generic, https://www.typescriptlang.org/docs/handbook/2/generics.html
@@ -2227,7 +2410,7 @@ class EuiDynamicMenuService {
     }
     filterEuiMenuItemsWithRights(links) {
         return links.filter((link) => {
-            if (link.hasChildren) {
+            if (link.children != null) {
                 link.children = this.filterEuiMenuItemsWithRights(link.children);
             }
             // First check if the user is denied access: