Allow to provide arbitrary user data carried by the http request

Author: nebarf

README.md

@@ -43,6 +43,7 @@ Just follow links below to get an overview of library features.
   - [Abortable request return](#abortable-request-return)
   - [Example – Abortable request](#example--abortable-request)
   - [Example – Get request](#example--get-request)
+  - [Example – Http context](#example--http-context)
 - [Request hooks](#request-hooks)
   - [Http request hook params](#http-request-hook-params)
   - [Http request hook return](#http-request-hook-return)
@@ -182,6 +183,7 @@ The complete *public API* exposed by the hook:
 | baseUrlOverride | string | The base url of the request. If provided, it would override the [provider](#provider) base url.
 | relativeUrl | string | The url relative to the base one (e.g. posts/1).
 | parser | [HttpResponseParser](src/client/types.ts) | An optional response parser that would override the [provider](#provider) global one. |
+| context | [HttpContext](src/client/http-context.ts) | An optional context that carries arbitrary user defined data. See examples.|
 | requestOptions | [HttpRequestOptions](./src/client/types.ts) | The options carried by the fetch request. |
 
 ### Request return
@@ -285,6 +287,49 @@ function App() {
 export default App;
 ```
 
+### Example – Http context
+```js
+import React, { useEffect } from 'react';
+import {
+  useHttpClient,
+  useHttpEvent,
+  RequestStartedEvent,
+  HttpContextToken,
+  HttpContext, } from 'react-http-fetch';
+
+const showGlobalLoader = new HttpContextToken(true);
+const reqContext = new HttpContext().set(showGlobalLoader, false);
+
+function App() {
+  const { request } = useHttpClient();
+
+  useHttpEvent(RequestStartedEvent, (payload) => {
+    console.log('Show global loader:', payload.context.get(showGlobalLoader));
+  });
+
+  useEffect(
+    () => {
+      const fetchTodo = async () => {
+        await request({
+          baseUrlOverride: 'https://jsonplaceholder.typicode.com',
+          relativeUrl: 'todos/1',
+          context: reqContext,
+        });
+      };
+
+      fetchTodo();
+    },
+    [request]
+  );
+
+  return (
+    <h1>Http Context</h1>
+  );
+}
+
+export default App;
+```
+
 <br>
 
 ## Request hooks
@@ -296,6 +341,7 @@ The library provides a hook `useHttpRequest` managing the state of the http requ
 | baseUrlOverride | string | The base url of the request. If provided, it would override the [provider](#provider) base url.
 | relativeUrl | string | The url relative to the base one (e.g. posts/1).
 | parser | [HttpResponseParser](src/client/types.ts) | An optional response parser that would override the [provider](#provider) global one. |
+| context | [HttpContext](src/client/http-context.ts) | An optional context that carries arbitrary user defined data. See examples.|
 | requestOptions | [HttpRequestOptions](./src/client/types.ts) | The options carried by the fetch request. |
 | initialData | any | The value that the state assumes initially before the request is send. |
 | fetchOnBootstrap | boolean | Tell if the fetch must be triggered automatically when mounting the component or not. In the second case we would like to have a manual fetch, this is optained by a request function returned by the hook. |

src/client/http-context.ts

@@ -0,0 +1,47 @@
+export class HttpContextToken<ValueT> {
+  constructor(public readonly defaultValue: ValueT) {}
+}
+
+export class HttpContext {
+  private readonly map = new Map<HttpContextToken<unknown>, unknown>();
+
+  /**
+   * Store a value in the context. If a value is already present it will be overwritten.
+   */
+  set<T>(token: HttpContextToken<T>, value: T): HttpContext {
+    this.map.set(token, value);
+    return this;
+  }
+
+  /**
+   * Retrieve the value associated with the given token.
+   */
+  get<T>(token: HttpContextToken<T>): T | undefined {
+    if (!this.map.has(token)) {
+      this.map.set(token, token.defaultValue);
+    }
+    return this.map.get(token) as T;
+  }
+
+  /**
+   * Delete the value associated with the given token.
+   */
+  delete(token: HttpContextToken<unknown>): HttpContext {
+    this.map.delete(token);
+    return this;
+  }
+
+  /**
+   * Checks for existence of a given token.
+   */
+  has(token: HttpContextToken<unknown>): boolean {
+    return this.map.has(token);
+  }
+
+  /**
+   * @returns a list of tokens currently stored in the context.
+   */
+  keys(): IterableIterator<HttpContextToken<unknown>> {
+    return this.map.keys();
+  }
+}

src/client/http-request.ts

@@ -1,4 +1,5 @@
 import { HttpMethod } from '../enum';
+import { HttpContext, HttpContextToken } from './http-context';
 
 export interface HttpRequestProps<HttpRequestBodyT> {
   baseUrl: string;
@@ -10,6 +11,7 @@ export interface HttpRequestProps<HttpRequestBodyT> {
   queryParams?: Record<string, string>;
   relativeUrl: string;
   signal?: AbortSignal;
+  context?: HttpContext;
 }
 
 export class HttpRequest<HttpRequestBodyT> implements HttpRequestProps<HttpRequestBodyT> {
@@ -60,6 +62,11 @@ export class HttpRequest<HttpRequestBodyT> implements HttpRequestProps<HttpReque
    */
   private _signal?: AbortSignal;
 
+  /**
+   * The request context storing arbitrary user defined data.
+   */
+  private _context?: HttpContext;
+
   constructor(requestOpts: HttpRequestProps<HttpRequestBodyT>) {
     const {
       baseUrl,
@@ -71,6 +78,7 @@ export class HttpRequest<HttpRequestBodyT> implements HttpRequestProps<HttpReque
       queryParams,
       relativeUrl,
       signal,
+      context,
     } = requestOpts;
 
     this._baseUrl = baseUrl;
@@ -82,6 +90,7 @@ export class HttpRequest<HttpRequestBodyT> implements HttpRequestProps<HttpReque
     this._queryParams = queryParams;
     this._relativeUrl = relativeUrl;
     this._signal = signal;
+    this._context = context;
   }
 
   get baseUrl(): string {
@@ -138,4 +147,14 @@ export class HttpRequest<HttpRequestBodyT> implements HttpRequestProps<HttpReque
     }
     return `${this.url}?${this.serializedQueryParams}`;
   }
+
+  get context(): HttpContext | undefined {
+    return this._context;
+  }
+
+  getContextValue<ContextTokenValueT>(
+    token: HttpContextToken<ContextTokenValueT>
+  ): ContextTokenValueT | undefined {
+    return this.context ? this.context.get(token) : undefined;
+  }
 }

src/client/index.ts

@@ -1,3 +1,4 @@
 export * from './use-http-client';
 export * from './types';
 export * from './http-request';
+export * from './http-context';

src/client/types.ts

@@ -1,4 +1,5 @@
 import { HttpMethod } from '../enum';
+import { HttpContext } from './http-context';
 
 export interface UseHttpClientParams {
   baseUrl: string;
@@ -13,6 +14,7 @@ export interface PerformHttpRequestParams<HttpRequestBodyT> {
   relativeUrl: string;
   parser: HttpResponseParser;
   baseUrlOverride: string;
+  context: HttpContext;
   requestOptions: Partial<HttpRequestOptions<HttpRequestBodyT>>;
 }
 

src/client/use-http-client.ts

@@ -32,6 +32,7 @@ export const useHttpClient = (): UseHttpClientReturn => {
       baseUrlOverride,
       parser,
       relativeUrl,
+      context,
       requestOptions,
     }: Partial<PerformHttpRequestParams<HttpRequestBodyT>>): Promise<HttpResponseT> => {
       /**
@@ -69,6 +70,7 @@ export const useHttpClient = (): UseHttpClientReturn => {
         body: body || undefined,
         baseUrl: computedBaseUrl,
         relativeUrl: relativeUrl || '',
+        context,
       });
 
       /**
@@ -157,6 +159,7 @@ export const useHttpClient = (): UseHttpClientReturn => {
       parser,
       relativeUrl,
       requestOptions,
+      context,
     }: Partial<
       PerformHttpRequestParams<HttpRequestBodyT>
     >): AbortableHttpRequestReturn<HttpResponseT> => {
@@ -167,6 +170,7 @@ export const useHttpClient = (): UseHttpClientReturn => {
         baseUrlOverride,
         parser,
         relativeUrl,
+        context,
         requestOptions: {
           ...requestOptions,
           signal,

src/request/types.ts

@@ -1,4 +1,5 @@
 import { HttpRequestOptions, HttpResponseParser } from '../client';
+import { HttpContext } from '../client/http-context';
 import { HttpRequestState } from './state-reducer';
 
 export interface UseHttpRequestParams<InitialDataT, HttpRequestBodyT> {
@@ -8,6 +9,7 @@ export interface UseHttpRequestParams<InitialDataT, HttpRequestBodyT> {
   requestOptions: Partial<HttpRequestOptions<HttpRequestBodyT>>;
   initialData: InitialDataT;
   fetchOnBootstrap: boolean;
+  context: HttpContext;
 }
 
 export interface UseHttpAbortableRequestReturn<HttpResponseT> {

src/request/use-http-request.ts

@@ -46,6 +46,7 @@ export const useHttpRequest = <HttpResponseT, HttpRequestBodyT = unknown>(
       parser: params.parser,
       relativeUrl: params.relativeUrl,
       requestOptions: params.requestOptions,
+      context: params.context,
     }),
     [params],
     fastCompare
@@ -59,12 +60,13 @@ export const useHttpRequest = <HttpResponseT, HttpRequestBodyT = unknown>(
       source: Partial<PerformHttpRequestParams<HttpRequestBodyT>>,
       override: Partial<PerformHttpRequestParams<HttpRequestBodyT>>
     ): Partial<PerformHttpRequestParams<HttpRequestBodyT>> => {
-      const { baseUrlOverride, parser, relativeUrl, requestOptions } = override;
+      const { baseUrlOverride, parser, relativeUrl, requestOptions, context } = override;
 
       return {
         baseUrlOverride: baseUrlOverride || source.baseUrlOverride,
         parser: parser || source.parser,
         relativeUrl: relativeUrl || source.relativeUrl,
+        context: context || source.context,
         requestOptions: {
           body: requestOptions?.body || source.requestOptions?.body,
           credentials: requestOptions?.credentials || source.requestOptions?.credentials,