feat: add custom response parser option and enhance binary data handling

Author: MattCCC

README.md

@@ -572,6 +572,7 @@ You can also use all native [`fetch()` settings](https://developer.mozilla.org/e
 | refetchOnReconnect         | `boolean`                                                                                              | `false`           | When set to `true`, automatically revalidates (refetches) data when the browser regains internet connectivity after being offline. **This uses background revalidation to silently update data** without showing loading states to users. Helps ensure your application displays fresh data after network interruptions. Works by listening to the browser's `online` event.                                                                                                                                                                                                                                                                                |
 | logger                     | `Logger`                                                                                               | `null`            | You can additionally specify logger object with your custom logger to automatically log the errors to the console. It should contain at least `error` and `warn` functions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | fetcher                    | `CustomFetcher`                                                                                        | `undefined`       | A custom fetcher async function. By default, the native `fetch()` is used. If you use your own fetcher, default response parsing e.g. `await response.json()` call will be skipped. Your fetcher should return response object / data directly.                                                                                                                                                                                                                                                                                                                                                                                                             |
+| parser                     | `(response: Response) => Promise<any>`                                                                 | `undefined`       | A custom response parser function. When provided, it replaces the built-in content-type based parsing entirely. Receives the raw `Response` object and should return the parsed data. Useful for handling custom formats like XML, CSV, or proprietary data. Can be set globally or per-request.                                                                                                                                                                                                                                                                                                                                                            |
 
 > 📋 **Additional Settings Available:**  
 > The table above shows the most commonly used settings. Many more advanced configuration options are available and documented in their respective sections below, including:
@@ -1753,23 +1754,65 @@ If the header is an HTTP-date, the delay will be calculated as the difference be
   <summary><span style="cursor:pointer">Click to expand</span></summary>
   <br>
 
-The `fetchff` plugin automatically handles response data transformation for any instance of `Response` returned by the `fetch()` (or a custom `fetcher`) based on the `Content-Type` header, ensuring that data is parsed correctly according to its format.
+The `fetchff` plugin automatically handles response data transformation for any instance of `Response` returned by the `fetch()` (or a custom `fetcher`) based on the `Content-Type` header, ensuring that data is parsed correctly according to its format. It returns functions like `response.json()` that can be called idempotently without throwing errors or consuming the underlying stream multiple times. You can also use `parser` option to fully control returned response (useful for response streaming).
 
 ### **How It Works**
 
 - **JSON (`application/json`):** Parses the response as JSON.
 - **Form Data (`multipart/form-data`):** Parses the response as `FormData`.
-- **Binary Data (`application/octet-stream`):** Parses the response as a `Blob`.
+- **Binary Data (`application/octet-stream`, images, video, audio, pdf, zip):** Parses the response as an `ArrayBuffer`. Use `response.blob()` to get a `Blob`, or `response.bytes()` to get a `Uint8Array`.
 - **URL-encoded Form Data (`application/x-www-form-urlencoded`):** Parses the response as `FormData`.
 - **Text (`text/*`):** Parses the response as plain text.
+- **Other/Custom types (XML, CSV, etc.):** Returns raw text. Use the `parser` option for custom parsing.
 
-If the `Content-Type` header is missing or not recognized, the plugin defaults to attempting JSON parsing. If that fails, it will try to parse the response as text.
+If the `Content-Type` header is missing or not recognized, the plugin defaults to returning text. If the text looks like JSON (starts with `{` or `[`), it will be auto-parsed as JSON.
 
 This approach ensures that the `fetchff` plugin can handle a variety of response formats, providing a flexible and reliable method for processing data from API requests.
 
 > ⚠️ **When using in Node.js:**  
 > In Node.js, using FormData, Blob, or ReadableStream may require additional polyfills or will not work unless your fetch polyfill supports them.
 
+### Custom `parser` Option
+
+You can provide a custom `parser` function to override the default content-type based parsing. This is useful for formats like XML, CSV, or any proprietary format. The `parser` can be set globally (via `createApiFetcher()` or `setDefaultConfig()`) or per-request.
+
+```typescript
+import { fetchf } from 'fetchff';
+
+// Example: Parse XML responses
+const { data } = await fetchf('/api/data.xml', {
+  async parser(response) {
+    const text = await response.text();
+    return new DOMParser().parseFromString(text, 'application/xml');
+  },
+});
+
+// Example: Parse CSV responses
+const { data: csvData } = await fetchf('/api/report.csv', {
+  async parser(response) {
+    const text = await response.text();
+    return text.split('\n').map((row) => row.split(','));
+  },
+});
+```
+
+You can also set it globally:
+
+```typescript
+import { createApiFetcher } from 'fetchff';
+
+const api = createApiFetcher({
+  apiUrl: 'https://example.com/api',
+  parser: async (response) => {
+    const text = await response.text();
+    return new DOMParser().parseFromString(text, 'application/xml');
+  },
+  endpoints: {
+    getReport: { url: '/report' },
+  },
+});
+```
+
 ### `onResponse` Interceptor
 
 You can use the `onResponse` interceptor to customize how the response is handled before it reaches your application. This interceptor gives you access to the raw `Response` object, allowing you to transform the data or modify the response behavior based on your needs.

src/request-handler.ts

@@ -242,7 +242,9 @@ export async function fetchf<
       if (isObject(response)) {
         // Case 1: Native Response instance
         if (typeof Response === FUNCTION && response instanceof Response) {
-          response.data = await parseResponseData(response);
+          response.data = requestConfig.parser
+            ? await requestConfig.parser(response)
+            : await parseResponseData(response);
         } else if (fn) {
           // Case 2: Custom fetcher that returns a response object
           if (!('data' in response && 'body' in response)) {

src/response-parser.ts

@@ -65,10 +65,14 @@ export async function parseResponseData<
     ) {
       data = await response.formData();
     } else if (
-      mimeType.includes(APPLICATION_CONTENT_TYPE + 'octet-stream') &&
-      typeof response.blob === FUNCTION
+      mimeType.startsWith('image/') ||
+      mimeType.startsWith('video/') ||
+      mimeType.startsWith('audio/') ||
+      mimeType.includes(APPLICATION_CONTENT_TYPE + 'octet-stream') ||
+      mimeType.includes('pdf') ||
+      mimeType.includes('zip')
     ) {
-      data = await response.blob(); // Parse as blob
+      data = await response.arrayBuffer(); // Parse as ArrayBuffer for binary types
     } else {
       data = await response.text();
 
@@ -191,13 +195,16 @@ export const prepareResponse = <
       statusText: response.statusText,
 
       // Convert methods to use arrow functions to preserve correct return types
-      blob: () => response.blob(),
-      json: () => response.json(),
-      text: () => response.text(),
+      blob: async () =>
+        data instanceof ArrayBuffer ? new Blob([data]) : new Blob(), // Lazily construct Blob from ArrayBuffer
+      json: () => Promise.resolve(data) as Promise<ResponseData>, // Return the already parsed JSON data
+      text: () => Promise.resolve(data) as Promise<string>, // Return the already parsed text data
       clone: () => response.clone(),
-      arrayBuffer: () => response.arrayBuffer(),
-      formData: () => response.formData(),
-      bytes: () => response.bytes(),
+      arrayBuffer: async () =>
+        data instanceof ArrayBuffer ? data : new ArrayBuffer(0), // Return the ArrayBuffer directly
+      formData: async () => (data instanceof FormData ? data : new FormData()), // Return the already parsed FormData
+      bytes: async () =>
+        data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(0), // Return bytes from ArrayBuffer
 
       // Enhance the response with extra information
       error,

src/types/request-handler.ts

@@ -671,6 +671,23 @@ export interface ExtendedRequestConfig<
     PathParams
   >;
 
+  /**
+   * A custom response parser function to handle response data parsing.
+   * When provided, this function is used instead of the default content-type based parsing.
+   * Useful for handling custom response formats like XML, CSV, or proprietary data formats.
+   *
+   * @example:
+   * // Parse XML responses
+   * const xmlParser = async (response: Response) => {
+   *   const text = await response.text();
+   *   return new DOMParser().parseFromString(text, 'application/xml');
+   * };
+   * const { data } = await fetchf('/api/data.xml', { parser: xmlParser });
+   *
+   * @default undefined (uses built-in content-type based parsing)
+   */
+  parser?: (response: Response) => Promise<any>;
+
   /**
    * A custom fetcher instance to handle requests instead of the default implementation.
    * When `null`, the default fetch behavior is used.

test/request-parser.spec.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 import { parseResponseData, prepareResponse } from '../src/response-parser';
 import type {
   FetchResponse,
@@ -52,15 +53,37 @@ describe('parseData()', () => {
     expect(data).toEqual(expectedData);
   });
 
-  it('should parse Blob when Content-Type is application/octet-stream', async () => {
+  it('should parse ArrayBuffer when Content-Type is application/octet-stream', async () => {
     (mockResponse.headers.get as jest.Mock).mockReturnValue(
       'application/octet-stream',
     );
-    const expectedData = new Blob(['test']);
-    (mockResponse.blob as jest.Mock).mockResolvedValue(expectedData);
+    const expectedArrayBuffer = new ArrayBuffer(8);
+    mockResponse.arrayBuffer = jest.fn().mockResolvedValue(expectedArrayBuffer);
 
     const data = await parseResponseData(mockResponse);
-    expect(data).toEqual(expectedData);
+    expect(data).toBeInstanceOf(ArrayBuffer);
+    expect(data).toEqual(expectedArrayBuffer);
+  });
+
+  it('should return a Blob from .blob() when binary ArrayBuffer is parsed', async () => {
+    // Use a real Response object to pass instanceof Response
+    const expectedArrayBuffer = new ArrayBuffer(8);
+    const realResponse = new Response(expectedArrayBuffer, {
+      status: 200,
+      headers: { 'Content-Type': 'application/octet-stream' },
+    });
+    // parseResponseData returns ArrayBuffer, but prepareResponse wraps it
+    const arrayBuffer = await parseResponseData(realResponse as any);
+    (realResponse as any).data = arrayBuffer;
+    const wrapped = prepareResponse(realResponse as any, {
+      cacheKey: 'test',
+      url: '/test',
+      method: 'GET',
+    });
+
+    const blob = await wrapped.blob();
+    expect(blob).toBeInstanceOf(Blob);
+    expect(blob.size).toBe(expectedArrayBuffer.byteLength);
   });
 
   it('should parse FormData when Content-Type is application/x-www-form-urlencoded', async () => {
@@ -192,6 +215,7 @@ describe('prepareResponse()', () => {
     } as unknown as FetchResponse;
     const config = {
       ...baseConfig,
+
       select: (data: any) => data.items,
     };