Added Support for Middleware Functions in piral-fetch

src/plugins/piral-fetch/README.md

@@ -83,6 +83,48 @@ const instance = createInstance({
 
 **Note**: `piral-fetch` plays nicely together with authentication providers such as `piral-adal`. As such authentication tokens are automatically inserted on requests to the base URL.
 
+### Middlewares
+
+`piral-fetch` allows you to configure middleware functions which are executed on each `fetch` call. Middleware functions receive the same parameters as `fetch`, plus a `next` function which calls either the next middleware or the actual `fetch` function. The following code shows an exemplary middleware which logs when requests start and finish:
+
+```ts
+const logRequests: FetchMiddleware = async (
+  path: string,
+  options: FetchOptions,
+  next: PiletFetchApiFetch,
+): Promise<FetchResponse<any>> => {
+  try {
+    console.log(`Making request to ${path}...`);
+    const response = await next(path, options);
+    console.log(`Request to ${path} returned status code ${response.code}.`);
+    return response;
+  } catch (e) {
+    console.error(`Request to ${path} threw an error: `, e);
+    throw e;
+  }
+};
+```
+
+Middlewares must be configured in the Piral instance:
+
+```ts
+const instance = createInstance({
+  plugins: [createFetchApi({
+    // important part
+    middlewares: [
+      firstMiddleware,
+      secondMiddleware,
+      thirdMiddleware,
+      logRequests,
+    ],
+    // ...other options...
+  })],
+  // ...
+});
+```
+
+Middlewares are invoked in a top-down order. In the above example, this means that `firstMiddleware` is invoked first, then `secondMiddleware`, then `thirdMiddleware`, then `logRequests` and finally the actual `fetch` function.
+
 :::
 
 ## License

src/plugins/piral-fetch/src/config.ts

@@ -1,3 +1,16 @@
+import type { FetchOptions, FetchResponse, PiletFetchApiFetch } from './types';
+
+export interface FetchMiddleware {
+  /**
+   * A middleware function for the fetch API.
+   * @param path The target of the fetch.
+   * @param options The options to be used.
+   * @param next A function that invokes the next middleware or the final `fetch`.
+   * @returns The promise waiting for the response to arrive.
+   */
+  (path: string, options: FetchOptions, next: PiletFetchApiFetch): Promise<FetchResponse<any>>;
+}
+
 export interface FetchConfig {
   /**
    * Sets the default request init settings.
@@ -9,4 +22,10 @@ export interface FetchConfig {
    * @default location.origin
    */
   base?: string;
+  /**
+   * An ordered list of middleware functions which can intercept and transform any request made via `piral-fetch`.
+   * Middleware functions are executed in a top-down order for each fetch request.
+   * @default []
+   */
+  middlewares?: Array<FetchMiddleware>;
 }

src/plugins/piral-fetch/src/create.test.ts

@@ -83,4 +83,48 @@ describe('Create fetch API Module', () => {
     const result = response.body;
     expect(result.substr(0, 5)).toBe(`<?xml`);
   });
+
+  it('invokes configured middleware function and calls API', async () => {
+    const context = { emit: vitest.fn() } as any;
+    const middleware = vitest.fn((path, options, next) => next(path, options));
+    const { fetch } = createFetchApi({
+      base: `http://localhost:${port}`,
+      middlewares: [middleware],
+    })(context) as any;
+    const response = await fetch('json');
+    const result = response.body;
+    expect(Array.isArray(result)).toBeTruthy();
+    expect(result.length).toBe(10);
+    expect(result[0]).toBe(1);
+    expect(middleware).toHaveBeenCalledOnce();
+  });
+
+  it('invokes middleware functions in top-down order', async () => {
+    const context = { emit: vitest.fn() } as any;
+    const invocationOrder: Array<number> = [];
+    const createMiddleware = (myPosition: number) => (path, options, next) => {
+      invocationOrder.push(myPosition);
+      return next(path, options);
+    };
+    const { fetch } = createFetchApi({
+      base: `http://localhost:${port}`,
+      middlewares: [createMiddleware(1), createMiddleware(2), createMiddleware(3)],
+    })(context) as any;
+    await fetch('json');
+    expect(invocationOrder).toEqual([1, 2, 3]);
+  });
+
+  it('allows middleware functions to terminate middleware chain', async () => {
+    const context = { emit: vitest.fn() } as any;
+    const expectedResponse = { code: 200, body: 'Terminated by middleware', text: 'Terminated by middleware' };
+    const middleware = () => Promise.resolve(expectedResponse);
+    const { fetch } = createFetchApi({
+      base: `http://localhost:${port}`,
+      middlewares: [middleware],
+    })(context) as any;
+    const globalFetch = vitest.spyOn(global, 'fetch');
+    const response = await fetch('json');
+    expect(response).toBe(expectedResponse);
+    expect(globalFetch).not.toHaveBeenCalled();
+  });
 });

src/plugins/piral-fetch/src/fetch.ts

@@ -1,47 +1,74 @@
-import { FetchConfig } from './config';
-import { FetchOptions, FetchResponse } from './types';
+import { FetchConfig, FetchMiddleware } from './config';
+import { FetchOptions, FetchResponse, PiletFetchApiFetch } from './types';
 
 const headerAccept = 'accept';
 const headerContentType = 'content-type';
 const mimeApplicationJson = 'application/json';
 
 export function httpFetch<T>(config: FetchConfig, path: string, options: FetchOptions = {}): Promise<FetchResponse<T>> {
-  const baseInit = config.default || {};
-  const baseHeaders = baseInit.headers || {};
-  const baseUrl = config.base || location.origin;
-  const { method = 'get', body, headers = {}, cache = baseInit.cache, mode = baseInit.mode, result = 'auto', signal } = options;
-  const json =
-    Array.isArray(body) ||
-    typeof body === 'number' ||
-    (typeof body === 'object' && body instanceof FormData === false && body instanceof Blob === false);
-  const url = new URL(path, baseUrl);
-  const init: RequestInit = {
-    ...baseInit,
-    method,
-    body: json ? JSON.stringify(body) : (body as BodyInit),
-    headers: {
-      ...baseHeaders,
-      ...headers,
-    },
-    cache,
-    mode,
-    signal,
-  };
+  // fetcher makes the actual HTTP request.
+  // It is used as the last step in the upcoming middleware chain and does *not* call/require next
+  // (which is undefined in this case).
+  const fetcher: FetchMiddleware = (path, options) => {
+    const baseInit = config.default || {};
+    const baseHeaders = baseInit.headers || {};
+    const baseUrl = config.base || location.origin;
+    const {
+      method = 'get',
+      body,
+      headers = {},
+      cache = baseInit.cache,
+      mode = baseInit.mode,
+      result = 'auto',
+      signal,
+    } = options;
+    const json =
+      Array.isArray(body) ||
+      typeof body === 'number' ||
+      (typeof body === 'object' && body instanceof FormData === false && body instanceof Blob === false);
+    const url = new URL(path, baseUrl);
+    const init: RequestInit = {
+      ...baseInit,
+      method,
+      body: json ? JSON.stringify(body) : (body as BodyInit),
+      headers: {
+        ...baseHeaders,
+        ...headers,
+      },
+      cache,
+      mode,
+      signal,
+    };
 
-  if (json) {
-    init.headers[headerContentType] = 'application/json';
-    init.headers[headerAccept] = mimeApplicationJson;
-  }
+    if (json) {
+      init.headers[headerContentType] = 'application/json';
+      init.headers[headerAccept] = mimeApplicationJson;
+    }
 
-  return fetch(url.href, init).then((res) => {
-    const contentType = res.headers.get(headerContentType);
-    const json = result === 'json' || (result === 'auto' && !!contentType && contentType.indexOf('json') !== -1);
-    const promise = json ? res.json() : res.text();
+    return fetch(url.href, init).then((res) => {
+      const contentType = res.headers.get(headerContentType);
+      const json = result === 'json' || (result === 'auto' && !!contentType && contentType.indexOf('json') !== -1);
+      const promise = json ? res.json() : res.text();
 
-    return promise.then((body) => ({
-      body,
-      code: res.status,
-      text: res.statusText,
-    }));
+      return promise.then((body) => ({
+        body,
+        code: res.status,
+        text: res.statusText,
+      }));
+    });
+  };
+
+  // Prepare the middleware chain. Middlewares are called in a top-down order.
+  // Every configured middleware function must receive a `next` function with the same shape
+  // as a `fetch` function. `next` invokes the next function in the chain.
+  // `fetcher` from above is the last function in the chain and always terminates it.
+  const middlewareFns = [...(config.middlewares || []), fetcher];
+  let middlewareChain: Array<PiletFetchApiFetch>;
+  middlewareChain = middlewareFns.map((middleware, i) => {
+    const next: PiletFetchApiFetch = (path, options) => middlewareChain[i + 1](path, options);
+    const invoke: PiletFetchApiFetch = (path, options) => middleware(path, options, next);
+    return invoke;
   });
+
+  return middlewareChain[0](path, options);
 }