http-request-manager 18.15.33 → 18.15.34

package/src/lib/services/request-manager-services/README.md

@@ -0,0 +1,282 @@
+# Request Manager Service Documentation
+
+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.
+
+## 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.
+
+### Import Example #1 (Injecting the Service)
+
+```ts
+import { HTTPManagerService } from 'path-to-service';
+
+export class DistrictService {
+
+  httpManagerService = inject(HTTPManagerService);
+
+  private errorRetry = new BehaviorSubject<{ func: Function, message: string } | null>(null);
+  errorRetry$ = this.errorRetry.asObservable();
+
+  apiRequest = ApiRequest.adapt({
+    server: 'nodebff/reporting-common-apis/v1',
+    path: ['dimensions','locations'],
+    adapter: DistrictData.adapt
+  });
+
+  params = {
+    type: 'DISTRICT',
+    excludeEcom: true
+  };
+
+  fetchDistrictData(params = this.params) {
+
+    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 });
+
+        return EMPTY;
+      })
+    );
+
+  }
+
+}
+```
+
+### Import Example #1 (Subscribing to the service)
+
+- 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.
+
+```ts
+export class DistrictService extends HTTPManagerService<DistrictData> {
+
+}
+```
+
+- 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.
+
+```ts
+codefetchDistrictData() {
+
+  this.getRequest(this.apiRequest, [this.params])
+  .pipe(
+    catchError((error: HttpErrorResponse) => {
+
+      const func = this.fetchDistrictData.bind(this)
+      const message = error.message
+      this.errorRetry.next({ func, message })
+
+      return EMPTY
+    })
+  ).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.
+
+### Component Example:
+
+In the component, the data fetched by fetchDistrictData() can be accessed by assigning the result to data$, like this:
+
+```ts
+this.data$ = this.awardsFilterStoresService.fetchData(this.payload)
+```
+
+This data$ observable is then used in the template to display the data asynchronously:htmlCopy code{{ data$ | async }}
+
+Template Example:
+
+The template uses the Angular async pipe to subscribe and display the data from data$. The async pipe manages the subscription and unsubscription automatically, simplifying the handling of observables in the template:
+
+```html
+<div *ngIf="data$ | async as data">
+<!-- Use data here -->
+</div>
+```
+
+By extending the HTTPManagerService, you benefit from reusable request logic and observables that provide seamless integration with Angular components and templates.
+
+## Key Features of the Service
+
+### 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.
+ApiRequest Configuration:
+
+The ApiRequest object encapsulates all the necessary details for making an HTTP request:
+
+```ts
+apiRequest = ApiRequest.adapt({
+  server: 'nodebff/reporting-common-apis/v1',
+  path: ['dimensions','locations'],
+  adapter: DistrictData.adapt
+});
+```
+
+### 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
+});
+```
+
+- 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: Indicate whether the request expects a stream of data from the server.
+- displayError: Error will be presented as a SnackBar notification with description of error
+
+  When stream: true, the data$ observable will continuously receive the updated data from the stream. This means that data$ represents the data being streamed from the server, and it will keep updating as new data arrives. You can also apply an adapter to transform the streamed data before it's delivered to data$.
+
+  For example, if you want to transform the incoming stream data using an adapter, you can specify the adapter in the ApiRequest configuration:
+
+  ```ts
+  apiRequest = ApiRequest.adapt({
+    server: 'nodebff/reporting-common-apis/v1',
+    path: ['dimensions','locations'],
+    adapter: DistrictData.adapt,
+    stream: true
+  });
+  ```
+
+  In this case, DistrictData.adapt will transform the data from the stream as it updates, ensuring that the data$ observable emits the adapted version of the streamed data.
+
+### State Manager Request Tracking Options (Database Only)
+
+For HTTPManagerStateService request methods, you can also pass request options such as:
+
+- ignoreQueryParams
+- queryParamsExpiresIn
+
+These options are applied only when database mode is enabled (DatabaseStorage configured in HTTPManagerStateService).
+
+- Database enabled: repeated query tracking and expiry-based re-fetch are active.
+- Database disabled: tracker is bypassed and requests call API directly.
+
+These are not base HTTPManagerService ApiRequest options.
+
+### Example Breakdown
+
+- The DistrictService demonstrates how to set up and use the HTTPManagerService to fetch district data by sending a GET request.
+- It uses the ApiRequest object to define the request configuration, including the API server, endpoint paths, and an adapter for data transformation.
+- The fetchDistrictData function handles errors gracefully by retrying the request when an error occurs, and the errorRetry$ observable is exposed for use in templates if necessary.
+- This setup ensures the service is flexible and ready for expansion, allowing for seamless API integrations with error handling and retry capabilities.
+
+### Additional Observables for Request Status:
+
+There are several other observables that can help you understand the status of the request:
+
+- 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.
+
+## Interceptors
+
+There are a few interceptors that may be used in your project that will provide a number of convinces for general use case headers.
+
+These are the interceptors that are automatically added to the Module by default
+
+1 - WithCredentialsInterceptor
+2 - RequestHeadersInterceptor
+3 - ProxyDebuggerInterceptor
+
+### Credentials-Interceptor
+
+This interceptor adds the 'credentials' header to all requests, ensuring cookies are maintained across both the module and its children.
+
+`{ withCredentials: true }`
+
+### Proxy-Debugger-Interceptor (Not Imported as Default)
+
+The Proxy-Debugger has to be imported into your app module and all proxies defined for checking all http requests.
+If there is an Http request that is being proxied, the interceptor will provide the following information in the console.
+
+a) `requestUrl` - current URL used by the request
+b) `payload` - payload in request
+c) `headers` - headers in request
+c) `proxyPath` - proxyPath to replace in requestUrl
+d) `actualPath` - request url will proxy target
+
+In your providers for your `app.module.ts` - add the following
+
+a) The `ProxyDebuggerInterceptor` interceptor
+b) Proxy Config Object from your `proxy.config.json` file
+
+For more information on setting up proxy in Angular please refer to this article
+
+[Angular proxy configuration for API calls](https://dev.to/developersmill/angular-proxy-configuration-for-api-calls-130b)
+
+Below is a sample proxy-config.json file.
+
+```ts
+  { provide: HTTP_INTERCEPTORS, useClass: ProxyDebuggerInterceptor, multi: true },
+  {
+    provide: PROXY_CONFIG,
+    useValue: {
+      "/localAPI/*": {
+        target: "https://httpbin.org",
+        secure: false,
+        changeOrigin: true,
+        pathRewrite: { "^/localAPI": "" },
+        logLevel: "debug",
+      },
+      "/docs/*": {
+        target: "https://anotherapi.com",
+        secure: true,
+        changeOrigin: false,
+        pathRewrite: { "^/api": "" },
+        logLevel: "info",
+      },
+    },
+  },
+```
+
+### Request-Header-Interceptor
+
+This interceptor adds the following headers to every request
+
+    'Content-Type': 'application/json',
+    'Accept-Language': this.language || 'en-CA',
+    'Current-Date': this.currentDate
+
+The language change is detected by the `TranslateService` service from NRGX
+The currentDate format is `YYYY-MM-DD`