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

package/lib/services/queue/api-queue.service.d.ts

@@ -4,71 +4,256 @@ import { ApiQueueItem } from '@eui/base';
 import { LogService } from '../log';
 import { StoreService } from '../store';
 import * as i0 from "@angular/core";
+/**
+ * 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);
+ * });
+ */
 export declare class ApiQueueService {
     protected store: StoreService;
     protected http: HttpClient;
     protected logService: LogService;
     constructor(store: StoreService, http: HttpClient, 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: string, item: ApiQueueItem): void;
     /**
-     * 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(): Observable<ApiQueueItem[]>;
     /**
-     * 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: string): Observable<ApiQueueItem>;
     /**
-     * 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: string): void;
     /**
-     * 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(): void;
     /**
-     * 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');
+     *   }
+     * });
      */
     processQueueItem(id: string): Observable<any>;
     /**
-     * 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
+     * });
      */
-    processAllQueueItems(continueOnError?: boolean): Observable<any[]>;
+    processAllQueueItems<T = any>(continueOnError?: boolean): Observable<T[]>;
     /**
-     * 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
+     * });
      */
     processAllQueueItemsSequential(ascending?: boolean): Observable<any>;
     /**
-     * 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
      */
     protected sortOnTimestamp(a: [string, ApiQueueItem], b: [string, ApiQueueItem]): number;
     /**
-     * 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`.
      */
     private buildHttpRequest;
     static ɵfac: i0.ɵɵFactoryDeclaration<ApiQueueService, [null, null, { optional: true; }]>;

package/lib/services/queue/api-queue.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-queue.service.d.ts","sourceRoot":"","sources":["../../../../src/lib/services/queue/api-queue.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAgB,MAAM,MAAM,CAAC;AAEhD,OAAO,EAA0C,YAAY,EAAE,MAAM,WAAW,CAAC;AAEjF,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,YAAY,EAAwE,MAAM,UAAU,CAAC;;AAE9G,qBAGa,eAAe;IAEpB,SAAS,CAAC,KAAK,EAAE,YAAY;IAC7B,SAAS,CAAC,IAAI,EAAE,UAAU;IACd,SAAS,CAAC,UAAU,EAAE,UAAU;gBAFlC,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,UAAU,EACJ,UAAU,EAAE,UAAU;IAGhD;;;;;OAKG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI;IAUlD;;;OAGG;IACH,QAAQ,IAAI,UAAU,CAAC,YAAY,EAAE,CAAC;IActC;;;;OAIG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC,YAAY,CAAC;IAalD;;;OAGG;IACH,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIjC;;OAEG;IACH,kBAAkB,IAAI,IAAI;IAI1B;;;;OAIG;IAGH,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC;IAc7C;;;;OAIG;IAGH,oBAAoB,CAAC,eAAe,UAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC;IAuB/D;;;;;OAKG;IAGH,8BAA8B,CAAC,SAAS,UAAO,GAAG,UAAU,CAAC,GAAG,CAAC;IAUjE;;;;;;OAMG;IACH,SAAS,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,MAAM;IAIvF;;;;;;OAMG;IAIH,OAAO,CAAC,gBAAgB;yCApKf,eAAe;6CAAf,eAAe;CAuK3B"}
+{"version":3,"file":"api-queue.service.d.ts","sourceRoot":"","sources":["../../../../src/lib/services/queue/api-queue.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAsB,MAAM,MAAM,CAAC;AAEtD,OAAO,EAA0C,YAAY,EAAE,MAAM,WAAW,CAAC;AAEjF,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,YAAY,EAAwE,MAAM,UAAU,CAAC;;AAE9G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAGa,eAAe;IAEpB,SAAS,CAAC,KAAK,EAAE,YAAY;IAC7B,SAAS,CAAC,IAAI,EAAE,UAAU;IACd,SAAS,CAAC,UAAU,EAAE,UAAU;gBAFlC,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,UAAU,EACJ,UAAU,EAAE,UAAU;IAGhD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI;IAUlD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,IAAI,UAAU,CAAC,YAAY,EAAE,CAAC;IActC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC,YAAY,CAAC;IAalD;;;;;;;;;;;;;;;;;OAiBG;IACH,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIjC;;;;;;;;;;;;;;OAcG;IACH,kBAAkB,IAAI,IAAI;IAI1B;;;;;;;;;;;;;;;;;;;OAmBG;IAGH,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC;IAc7C;;;;;;;;;;;;;;;;;;;OAmBG;IAGH,oBAAoB,CAAC,CAAC,GAAG,GAAG,EAAE,eAAe,UAAO,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC;IAqBtE;;;;;;;;;;;;;;;;;;;;OAoBG;IAGH,8BAA8B,CAAC,SAAS,UAAO,GAAG,UAAU,CAAC,GAAG,CAAC;IAWjE;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,MAAM;IAIvF;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IAIH,OAAO,CAAC,gBAAgB;yCA1Tf,eAAe;6CAAf,eAAe;CA6T3B"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@eui/core",
-    "version": "17.0.0-rc.7",
+    "version": "17.0.0-rc.8",
     "tag": "next",
     "description": "eUI core package - holding UI components for Desktop applications",
     "homepage": "https://eui.ecdevops.eu",