http-request-manager 15.0.16 → 15.0.17

package/README.md

@@ -1,170 +1,327 @@
 # Request Manager Service Documentation
 
 ## Summary of the Lib
-The HTTPManagerService is designed to handle HTTP requests and return Observables, providing an efficient and streamlined way to interact with external APIs or services in your Angular application. This service can be imported and used directly or extended to suit your specific needs.
+The HTTPManagerService is a collection of 4 services for HTTP and Local Storage management.
 
-## Required Configuration
+## Installation
 
-App.module.ts add the following providers - AppService
-This will allow the `http-request-manager` to use the app-id you assign as a encryption/decryption key for the `local-storage-manager`
+`npm install http-request-manager`
 
-```
-    {
-        provide: APP_ID,
-        useValue: '561324eb4fadb840330cd5ac4db67bef', // Replace with your unique application ID
-      },
-      AppService
-```
+## Services
 
-## Features of the Lib
-### Error Handling
-The example defines an errorRetry$ observable that captures errors using the catchError operator and enables retry logic. This observable can be utilized in your component templates to handle and display errors, making error management more flexible.
+### HTTP Manager Service: 
 
-### ApiRequest Configuration
-The ApiRequest object encapsulates all the necessary details for making an HTTP request:
+Http service simplifies http requests in the following ways
+  - Define a fixed endpoint service
+  - Provide a fixed set of headers or add to the headers on request
+  - Proxy Config Support
+  - Adapter for strict type checking for incoming data
+  - Mapper for data transformation for outgoing data
+  - Polling requests automatically
+  - Retry requests if failure
+  - Stream http requests from endpoint service
+  - Display Error provides a Toast (Snackbar) notification on error
 
-```ts
-apiRequest = ApiRequest.adapt({
-  server: 'nodebff/reporting-common-apis/v1',
-  path: ['dimensions','locations'],
-  adapter: DistrictData.adapt
-});
-```
+### HTTP State Manager Service
 
-### ApiRequest Options
-The following are the available options when configuring an ApiRequest object:
+Http service simplifies http request state management in the following ways
+  - Inherits from HTTP Manager Service for config options
+  - Creates a Component Store state (NGRX)
+  - Selectors for data and selecting data records
+  - Create, Update and Delete automatically updates data by endpoint and state on success
+  - Get keeps state of records
+
+### Database Storage Manager (Coming soon)
+  - Inherits from HTTP State Manager Service for config options
+  - Manages HTTP Requests caching data in local DB (IndexedDB) using DixieJS
+  - Requests check first local DB and if data is not stale, request is made and updates DB
+  - Expiry time/date can be set for DB records for caching
+
+### Local/Session Storage
+  - Allows for Local and Storage management for data Persistence
+  - Component Store (NGRX) State for changes on storage
+  - Encryption for data
+  - Expiry time/date can be set for stores
+
+## Using the Services
+
+There are three ways to use the service, depending on your needs:
+
+### Injecting the Service (Single Usage)
+
+  ```ts
+  httpManagerService = inject(HTTPManagerService)
+  ```
+
+- This approach provides a singleton state for the service, as services are provided in root (@Injectable({ providedIn: 'root' })).
+- Any components or services that inject this service will share the same state, meaning they all have access to:
+  - data$ (observable for data)
+  - isPending$ (loading state)
+  - countDown$ (loading state)
+  - error$ (error state)
+  - Methods associated with the service
+  - Since there is only one shared state, it can be reused across components without creating new instances.
+
+  Here is a very simple example
+
+  ```ts
+    //Define your API request details using the `ApiRequest` adapter
+    const apiOptions = ApiRequest.adapt({
+      server: 'myApiUrl/rest/clients' // or ['myApiUrl', 'rest', 'clients']
+    })
+
+  onFetchData() {
+
+      this.httpManagerService.getRequest<any>(apiOptions)
+      .pipe(
+        catchError(error => {
+          return throwError(() => this.errorHandling(error, 'GET'))
+        })
+      ).subscribe(data => console.log(data)))
+
+    }
+  ```
+
+### Example
+In this example, we define the endpoint URL as myApiUrl. This will return the data from the observable for your use case.
+
+The endpoint can be:
+
+A direct URL (e.g., https://apple.com/clients).
+A proxy-config file (recommended to avoid CORS issues).
+A string, an array of strings, or numbers—similar to Angular’s Router.navigate() API.
+The HTTP Service Manager automatically sanitizes the endpoint by removing redundant `/` characters and validating the URL.
+
+You can also add query parameters by passing an object:
+
+  ```ts
+    { sortBy: 'asc', filter: ['samples', 'testing'] }
+  ```
 
+This translates to: `https://apple.com/clients?sortBy=asc&filter=samples,testing`
+
+There are a number of other options available in the `ApiRequest` adapter
+
+
+### Extending a Component or Service with the Service (Multiple Instances - preferred method)
+
+This approach creates a new instance of the service for each component or service that extends it, ensuring each instance maintains its own independent state.
+
+### Observables
+- Similar to the first approach, instead of one instance of the state you are creating a new state instance
+- CRUD operations return Observables, similar to HttpClient.
+- This allows for custom error handling and executing additional actions after the request completes.
+- Since HTTP requests are asynchronous, you must subscribe to the Observable to receive data:
+
+  ```ts
+    myService.getData().subscribe(response => {
+      console.log(response);
+    });
+  ```
+
+- Alternatively, you can use the async pipe for automatic subscription and cleanup:
+
+  ```ts
+    {{ myData$ | async }}
+  ```
+
+### Example
+First we need to extend the Component or Service (recommended approach) with the `HTTPManagerService`
+
+Component Example:
+  ```ts
+  export class RequestManagerDemoComponent extends HTTPManagerService<any> implements OnInit {
+
+    constructor() { 
+      super()
+    }
+  }
+  ```
+
+Service Example:
+  ```ts
+  @Injectable({
+    providedIn: 'root'
+  })
+  export class myAPIService extends HTTPManagerService<any> {
+
+    constructor() { 
+      super()
+    }
+
+  }
+  ```
+
+In this example, we define the endpoint URL as myApiUrl. This will return the data from the observable for your use case.
+
+The endpoint can be:
+
+A direct URL (e.g., https://apple.com/clients).
+A proxy-config file (recommended to avoid CORS issues).
+A string, an array of strings, or numbers—similar to Angular’s Router.navigate() API.
+The HTTP Service Manager automatically sanitizes the endpoint by removing redundant `/` characters and validating the URL.
+
+You can also add query parameters by passing an object:
 ```ts
-apiRequest = ApiRequest.adapt({
-  server: string,
-  path: any[],
-  headers: any,
-  adapter?: any,
-  mapper?: any,
-  polling?: number, // in seconds (undefined | 0 = none)
-  retry: RetryOptions,
-  stream?: boolean
-  displayError: boolean
-});
+  { sortBy: 'asc', filter: ['samples', 'testing'] }
 ```
+This translates to: `https://apple.com/clients?sortBy=asc&filter=samples,testing`
 
-- server: The base URL or service endpoint for the API request.
-- path: Additional paths to append to the base URL for constructing the full API endpoint.
-- headers: Custom headers to include in the request, provided as an object.
-- adapter (incoming): A model adapter used to transform incoming data (e.g., DistrictData.adapt).
-- mapper (outgoing): A model adapter used to map outgoing data before sending it to the server (e.g., DistrictData.mapper).
-- polling: Enables periodic polling, where the request will be made every specified number of seconds.
-- retry: Retry logic using RetryOptions, which includes:
-  - times: Number of retry attempts.
-  - delay: Delay in milliseconds between each retry.
-- stream: A flag to indicate whether the request expects a stream of data from the server.
-- displayError: A flag to indicate whether to present the error from the request in a snackBar notification
+Lets define these query params as a variable called `PARAMS` and use them in the following request.
 
-### Additional Observables for Request Status
-- countdown$: If polling is active, this property gives feedback on when the next request will take place. It starts from the specified time in seconds and counts down to 0, triggering the next request and restarting the countdown.
-- error$: This returns any HTTP error that occurs during the request.
-- isPending$: This boolean value indicates whether the request is pending (true) or has been completed (false).
-- data$: You can access the data fetched in the request using the data$ observable. This provides the response from the server, which can be used for further processing or displaying in the UI.
+There are a number of other options available in the `ApiRequest` adapter
 
-## Usage
-To utilize the HTTPManagerService, you must import it into your service or component. Alternatively, you can extend the service by defining the required generic type for custom implementations.
+No we can define a method:
+In this example take note that the clientID has been passed to the method and the param after the apiOptions allows for further customization for the api request being made. In this case we extended the the base path defined in the `ApiRequest` options. We also added the `PARAMS` for query parameters.
 
-### Import Example #1
+Define your API request options using the 'ApiRequest' adapter
 
-```ts
-import { HTTPManagerService } from 'path-to-service';
+  ```ts
+    const apiOptions = ApiRequest.adapt({
+      server: ['myApiUrl', 'rest', 'clients']
+    })
 
-// Injecting HTTPManagerService in a Service
+    // Dynamically change these params
+    const PARAMS = {
+      sortBy: 'asc',
+      filter: ['samples', 'testing']
+    }
 
-export class DistrictService {
-  
-  httpManagerService = inject(HTTPManagerService);
+    onFetchData(clientId) {
 
-  private errorRetry = new BehaviorSubject<{ func: Function, message: string } | null>(null);
-  errorRetry$ = this.errorRetry.asObservable();
+      this.httpManagerService.getRequest<any>(apiOptions, [clientId, this.PARAMS])
+      .pipe(
+        catchError(error => {
+          return throwError(() => this.errorHandling(error, 'GET'))
+        })
+      ).subscribe(data => console.log(data)))
 
-  apiRequest = ApiRequest.adapt({
-    server: 'nodebff/reporting-common-apis/v1',
-    path: ['dimensions','locations'],
-    adapter: DistrictData.adapt
-  });
+    }
+  ```
 
-  params = {
-    type: 'DISTRICT',
-    excludeEcom: true
-  };
 
-  fetchDistrictData(params = this.params) {
+### State Observable
+- When executing CRUD operations, their results are automatically pushed into the data$ observable within the service.
+- This means you can bind the data$ observable to a component to automatically update UI elements.
+- Using this approach enables state management across components and allows data refresh actions without needing additional logic.
 
-    return this.httpManagerService.getRequest(this.apiRequest, [params])
-    .pipe(
-      catchError((error: HttpErrorResponse) => {
-        
-        // custom retry logic
-        const func = this.fetchDistrictData.bind(this);
-        const message = error.message;
-        this.errorRetry.next({ func, message });
+### Example
+First we need to extend the Component or Service (recommended approach) with the `HTTPManagerService`
 
-        return EMPTY;
-      })
-    );
+Component Example:
+The structure would be: Component extends `HTTPManagerService`
 
+  ```ts
+  export class RequestManagerDemoComponent extends HTTPManagerService<any> implements OnInit {
+
+    constructor() { 
+      super()
+    }
   }
+  ```
 
-}
-```
+Service Example:
+The structure would be: Component injects a service call `clientsService` and `clientsService` extends `HTTPManagerService`
 
-### Import Example #2
+  ```ts
+  @Injectable({
+    providedIn: 'root'
+  })
+  export class myAPIService extends HTTPManagerService<any> {
 
-In this new example:
+    constructor() { 
+      super()
+    }
 
-- Extending HTTPManagerService:
-    The DistrictService extends the HTTPManagerService with a generic type of DistrictData, which allows for reusability and scalability. By extending, the fetchDistrictData method uses the getRequest function provided by the parent class to make the request.
+  }
+  ```
 
-- Function to Make the Request:
-    The fetchDistrictData() method calls the getRequest function and immediately subscribes to the result. Since it subscribes, the request is made and the result is handled within the data$ observable.
-    If an error occurs during the request, the error is caught using catchError. The errorRetry$ observable is updated with the error details, which can be handled in the component or template.
+In this example, we define the endpoint URL as myApiUrl.
 
-```ts
-fetchDistrictData() {
+Lets define these query params as a variable called `PARAMS` and use them in the following request.
 
-  this.getRequest(this.apiRequest, [this.params])
-  .pipe(
-    catchError((error: HttpErrorResponse) => {
+No we can define a method:
+In this example the clientID has been passed to the method. 
+We also added the `PARAMS` for query parameters.
 
-      const func = this.fetchDistrictData.bind(this)
-      const message = error.message
-      this.errorRetry.next({ func, message })
+Define your API request options using the 'ApiRequest' adapter
 
-      return EMPTY
+  ```ts
+    const apiOptions = ApiRequest.adapt({
+      server: ['myApiUrl', 'rest', 'clients']
     })
-  ).subscribe()
 
-}
-```
+    // Dynamically change these params
+    const PARAMS = {
+      sortBy: 'asc',
+      filter: ['samples', 'testing']
+    }
+
+    onFetchData(clientId: number) {
+      this.httpManagerService.getRequest<any>(apiOptions, [clientId, this.PARAMS]).subscribe()
+    }
+  ```
 
-### Data Observable
-The result of the request is stored in the data$ observable, which is inherited from the parent class (HTTPManagerService). This observable is connected to a component for further usage.
+  In the above case we are not using the data returning from the Observable but rather executing the api call, like a refresh if called again
 
-### Component Example
-In the component, the data fetched by fetchDistrictData() can be accessed by assigning the result to data$, like this:
+  To access the data from the observable, you need to bind the observable if your using a component that injects the service that extends the `HTTPManagerService`
+
+  In the component where the service was injected, we define
+
+  ```ts
+    data$ = this.clientsService.data$
+    isPending$ = this.clientsService.isPending$
+    error$ = this.clientsService.error$
+  ```
+  By doing this gives your component the state of the data and other feedback states for the request that now you can use in your template.
 
 ```ts
-this.data$ = this.awardsFilterStoresService.fetchData(this.payload)
+  {{ data$ | async }}
+  {{ isPending$ | async }}
+  {{ error$ | async }}
 ```
 
-This data$ observable is then used in the template to display the data asynchronously:
 
-```html
-<div *ngIf="data$ | async as data">
-<!-- Use data here -->
-</div>
+### ApiRequest Options
+The following are the available options when configuring an ApiRequest object:
+
+```ts
+apiRequest = ApiRequest.adapt({
+  server: string,
+  path: any[],
+  headers: any,
+  adapter?: any,
+  mapper?: any,
+  polling?: number, // in seconds (undefined | 0 = none)
+  retry: RetryOptions,
+  stream?: boolean
+  displayError: boolean
+});
 ```
 
-By extending the HTTPManagerService, you benefit from reusable request logic and observables that provide seamless integration with Angular components and templates.
+| **Property**   | **Description**                                                                   | **Type**                   | **Required** |
+|--------------|--------------------------------------------------------------------------------|---------------------------|------------|
+| `server`     | The base URL or service endpoint for the API request.                         | `string`                   | ✅         |
+| `path`       | Additional paths to append to the base URL for constructing the full API endpoint. | `any[]`                    | ✅         |
+| `headers`    | Custom headers to include in the request, provided as an object.             | `any`                      | ✅         |
+| `adapter`    | A model adapter used to transform incoming data (e.g., `DistrictData.adapt`). | `any`                      | ❌         |
+| `mapper`     | A model adapter used to map outgoing data before sending it to the server (e.g., `DistrictData.mapper`). | `any` | ❌         |
+| `polling`    | Enables periodic polling, where the request will be made every specified number of seconds. | `number` (seconds)         | ❌         |
+| `retry`      | Retry logic using `RetryOptions`, which includes: <br> - `times`: Number of retry attempts. <br> - `delay`: Delay in milliseconds between retries. | `RetryOptions`             | ✅         |
+| `stream`     | A flag to indicate whether the request expects a stream of data from the server. | `boolean`                  | ❌         |
+| `displayError` | A flag to indicate whether to present the error from the request in a snackbar notification. | `boolean`                  | ✅         |
+
+
+### Additional Observables for Request Status
+- countdown$: If polling is active, this property gives feedback on when the next request will take place. It starts from the specified time in seconds and counts down to 0, triggering the next request and restarting the countdown.
+- error$: This returns any HTTP error that occurs during the request.
+- isPending$: This boolean value indicates whether the request is pending (true) or has been completed (false).
+- data$: You can access the data fetched in the request using the data$ observable. This provides the response from the server, which can be used for further processing or displaying in the UI.
+
+## Importing Module forRoot() Configuration
 
 
-# Interceptors
+# Available Interceptors
 
 There are 3 interceptors that you can import into your project for api requests. 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "http-request-manager",
-  "version": "15.0.16",
+  "version": "15.0.17",
   "peerDependencies": {
     "@angular/cdk": "^15.2.9",
     "@angular/common": "^15.2.0",