Merge branch 'develop'

Author: Olavo Parno

.github/workflows/npm-publish.yml

@@ -9,21 +9,21 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          node-version: 16
+          node-version: 20
       - run: npm install
       - run: npm run build
 
   publish-npm:
     needs: build
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          node-version: 16
+          node-version: 20
           registry-url: https://registry.npmjs.org/
       - run: npm install
       - run: npm publish

.github/workflows/pull-request.yml

@@ -13,13 +13,13 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.x, 14.x, 16.x]
+        node-version: [18.x, 20.x]
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
           cache: "npm"

.gitignore

@@ -9,6 +9,9 @@ build
 dist
 .rpt2_cache
 
+# Editor directories and files
+.idea
+
 # misc
 .DS_Store
 .env
@@ -24,4 +27,4 @@ yarn-error.log*
 .vercel
 
 coverage
-.dccache
+.dccache

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [1.3.0](https://github.com/the-bugging/react-use-downloader/compare/v1.2.10...v1.3.0) (2025-06-15)
+
+
+### Features
+
+* expose error response ([82e8cd2](https://github.com/the-bugging/react-use-downloader/commit/82e8cd2538e52e1a0701cdb3bcddf2a2f351473f))
+
 ### [1.2.10](https://github.com/the-bugging/react-use-downloader/compare/v1.2.9...v1.2.10) (2025-03-10)
 
 

README.md

@@ -8,7 +8,7 @@
 
 | Statements                                                                                      | Branches                                                                                 | Functions                                                                                     | Lines                                                                                 |
 | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| ![Statements](https://img.shields.io/badge/statements-86.44%25-yellow.svg?style=flat&logo=jest) | ![Branches](https://img.shields.io/badge/branches-68.62%25-red.svg?style=flat&logo=jest) | ![Functions](https://img.shields.io/badge/functions-77.14%25-red.svg?style=flat&logo=jest) | ![Lines](https://img.shields.io/badge/lines-86.91%25-yellow.svg?style=flat&logo=jest) |
+| ![Statements](https://img.shields.io/badge/statements-93.7%25-brightgreen.svg?style=flat&logo=jest) | ![Branches](https://img.shields.io/badge/branches-73.58%25-red.svg?style=flat&logo=jest) | ![Functions](https://img.shields.io/badge/functions-89.18%25-yellow.svg?style=flat&logo=jest) | ![Lines](https://img.shields.io/badge/lines-94.78%25-brightgreen.svg?style=flat&logo=jest) |
 
 ## Table of Contents
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-use-downloader",
-  "version": "1.2.10",
+  "version": "1.3.0",
   "description": "Creates a download handler function and gives progress information",
   "author": "Olavo Parno",
   "license": "MIT",

src/__tests__/index.spec.ts

@@ -8,6 +8,11 @@ import { renderHook, act } from '@testing-library/react-hooks';
 import useDownloader, { jsDownload } from '../index';
 import { WindowDownloaderEmbedded } from '../types';
 
+// Helper noop function to avoid linter error (intentionally empty for Promise executor and catch)
+function noop() {
+  /* intentionally empty for Promise executor */
+}
+
 const expectedKeys = [
   'elapsed',
   'percentage',
@@ -207,22 +212,20 @@ describe('useDownloader failures', () => {
   it('should start download with response.ok false and an error from the response', async () => {
     const { result, waitForNextUpdate } = renderHook(() => useDownloader());
 
-    global.window.fetch = jest.fn(() =>
-      Promise.resolve(
-        new Response(
-          JSON.stringify({
-            error: 'File download not allowed',
-            reason:
-              'User must complete verification before accessing this file.',
-          }),
-          {
-            status: 403,
-            statusText: 'Forbidden',
-            headers: { 'Content-Type': 'application/json' },
-          }
-        )
-      )
+    const errorResponse = new Response(
+      JSON.stringify({
+        error: 'File download not allowed',
+        reason: 'User must complete verification before accessing this file.',
+      }),
+      {
+        status: 403,
+        statusText: 'Forbidden',
+        headers: { 'Content-Type': 'application/json' },
+      }
     );
+    const resultErrorResponse = errorResponse.clone();
+
+    global.window.fetch = jest.fn(() => Promise.resolve(errorResponse));
 
     expect(result.current.error).toBeNull();
 
@@ -237,6 +240,7 @@ describe('useDownloader failures', () => {
     expect(result.current.error).toEqual({
       errorMessage:
         '403 - Forbidden: File download not allowed: User must complete verification before accessing this file.',
+      errorResponse: resultErrorResponse,
     });
   });
 
@@ -308,3 +312,75 @@ describe('useDownloader failures', () => {
     });
   });
 });
+
+describe('useDownloader cancel and error mapping', () => {
+  it('should cancel an in-progress download', async () => {
+    const { result, waitForNextUpdate } = renderHook(() => useDownloader());
+
+    // Mock fetch to return a stream that never ends
+    global.window.fetch = jest.fn(() =>
+      Promise.resolve({
+        ok: true,
+        headers: {
+          get: () => null,
+        },
+        body: {
+          getReader: () => ({
+            read: () => new Promise(noop), // never resolves, avoids linter error
+            cancel: jest.fn(),
+          }),
+        },
+        blob: () => Promise.resolve(new Blob()),
+      })
+    ) as any;
+
+    act(() => {
+      result.current.download('https://url.com', 'filename');
+    });
+
+    expect(result.current.isInProgress).toBeTruthy();
+
+    // Call cancel
+    act(() => {
+      result.current.cancel();
+    });
+
+    // Wait for state update (should not throw if no update)
+    await waitForNextUpdate({ timeout: 100 }).catch(noop);
+    expect(result.current.isInProgress).toBeFalsy();
+  });
+
+  it('should map known error messages to user-friendly errors', async () => {
+    const { result, waitForNextUpdate } = renderHook(() => useDownloader());
+
+    // Mock fetch to return a stream that errors
+    global.window.fetch = jest.fn(() =>
+      Promise.resolve({
+        ok: true,
+        headers: {
+          get: () => null,
+        },
+        body: {
+          getReader: () => ({
+            read: () =>
+              Promise.reject(
+                new Error(
+                  "Failed to execute 'enqueue' on 'ReadableStreamDefaultController': Cannot enqueue a chunk into an errored readable stream"
+                )
+              ),
+            cancel: jest.fn(),
+          }),
+        },
+        blob: () => Promise.resolve(new Blob()),
+      })
+    ) as any;
+
+    act(() => {
+      result.current.download('https://url.com', 'filename');
+    });
+
+    // Wait for state update
+    await waitForNextUpdate({ timeout: 100 }).catch(noop);
+    expect(result.current.error).toEqual({ errorMessage: 'Download canceled' });
+  });
+});

src/index.ts

@@ -22,7 +22,9 @@ export const resolver =
   }: ResolverProps) =>
   (response: Response): Response => {
     if (!response.ok) {
-      console.error(`${response.status} ${response.type} ${response.statusText}`);
+      console.error(
+        `${response.status} ${response.type} ${response.statusText}`
+      );
 
       throw response;
     }
@@ -102,14 +104,8 @@ export const jsDownload = (
 
   const currentWindow = window as unknown as WindowDownloaderEmbedded;
 
-  if (
-    typeof currentWindow.navigator
-      .msSaveBlob !== 'undefined'
-  ) {
-    return currentWindow.navigator.msSaveBlob(
-      blob,
-      filename
-    );
+  if (typeof currentWindow.navigator.msSaveBlob !== 'undefined') {
+    return currentWindow.navigator.msSaveBlob(blob, filename);
   }
 
   const blobURL =
@@ -152,7 +148,7 @@ export default function useDownloader(
   const [elapsed, setElapsed] = useState(0);
   const [percentage, setPercentage] = useState(0);
   const [size, setSize] = useState(0);
-  const [error, setError] = useState<ErrorMessage>(null);
+  const [internalError, setInternalError] = useState<ErrorMessage>(null);
   const [isInProgress, setIsInProgress] = useState(false);
 
   const controllerRef = useRef<null | ReadableStreamController<Uint8Array>>(
@@ -171,7 +167,7 @@ export default function useDownloader(
         'Download canceled',
       'The user aborted a request.': 'Download timed out',
     };
-    setError(() => {
+    setInternalError(() => {
       const resolvedError = errorMap[err.message as keyof typeof errorMap]
         ? errorMap[err.message as keyof typeof errorMap]
         : err.message;
@@ -207,7 +203,7 @@ export default function useDownloader(
       if (isInProgress) return null;
 
       clearAllStateCallback();
-      setError(() => null);
+      setInternalError(() => null);
       setIsInProgress(() => true);
 
       const intervalId = setInterval(
@@ -244,35 +240,39 @@ export default function useDownloader(
         })
         .catch(async (error) => {
           clearAllStateCallback();
+          let errorResponse = null;
 
-          
           const errorMessage = await (async () => {
             if (error instanceof Response) {
-              const contentType = error.headers.get("Content-Type") || "";
-              const isJson = contentType.includes("application/json");
-        
+              errorResponse = error.clone();
+
+              const contentType = error.headers.get('Content-Type') || '';
+              const isJson = contentType.includes('application/json');
+
               const errorBody = isJson
                 ? await error.json().catch(() => null)
                 : await error.text().catch(() => null);
-        
+
               return [
                 `${error.status} - ${error.statusText}`,
                 errorBody?.error,
-                errorBody?.reason || (typeof errorBody === "string" ? errorBody : null),
+                errorBody?.reason ||
+                  (typeof errorBody === 'string' ? errorBody : null),
               ]
                 .filter(Boolean)
-                .join(": ");
+                .join(': ');
             }
-        
-            return error?.message || "An unknown error occurred.";
+
+            return error?.message || 'An unknown error occurred.';
           })();
-        
-          setError({ errorMessage });
-        
+
+          const downloaderError: ErrorMessage = { errorMessage };
+          if (errorResponse) downloaderError.errorResponse = errorResponse;
+          setInternalError(downloaderError);
+
           clearTimeout(timeoutId);
           clearInterval(intervalId);
         });
-        
     },
     [
       isInProgress,
@@ -285,24 +285,30 @@ export default function useDownloader(
     ]
   );
 
-  return useMemo(
+  const downloadState = useMemo(
     () => ({
       elapsed,
       percentage,
       size,
+      error: internalError,
+      isInProgress,
+    }),
+    [elapsed, percentage, size, internalError, isInProgress]
+  );
+
+  const downloadActions = useMemo(
+    () => ({
       download: handleDownload,
       cancel: closeControllerCallback,
-      error,
-      isInProgress,
     }),
-    [
-      elapsed,
-      percentage,
-      size,
-      handleDownload,
-      closeControllerCallback,
-      error,
-      isInProgress,
-    ]
+    [handleDownload, closeControllerCallback]
+  );
+
+  return useMemo(
+    () => ({
+      ...downloadState,
+      ...downloadActions,
+    }),
+    [downloadState, downloadActions]
   );
 }

src/types.ts

@@ -2,6 +2,7 @@ import { SetStateAction } from 'react';
 
 export type ErrorMessage = {
   errorMessage: string;
+  errorResponse?: Response;
 } | null;
 
 /** useDownloader options for fetch call
@@ -89,6 +90,6 @@ interface CustomURL extends URL {
 
 export interface WindowDownloaderEmbedded extends Window {
   navigator: CustomNavigator;
-  URL?: CustomURL
-  webkitURL?: CustomURL
+  URL?: CustomURL;
+  webkitURL?: CustomURL;
 }