Merge branch 'develop'

Author: olavoparno

.all-contributorsrc

@@ -72,6 +72,15 @@
         "bug",
         "code"
       ]
+    },
+    {
+      "login": "davecarlson",
+      "name": "Dave Carlson",
+      "avatar_url": "https://avatars.githubusercontent.com/u/299702?v=4",
+      "profile": "https://github.com/davecarlson",
+      "contributions": [
+        "ideas"
+      ]
     }
   ],
   "contributorsPerLine": 7,
@@ -82,4 +91,4 @@
   "skipCi": true,
   "commitConvention": "angular",
   "commitType": "docs"
-}
+}

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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.2.8](https://github.com/the-bugging/react-use-downloader/compare/v1.2.6...v1.2.8) (2024-04-17)
+
+
+### Documentation
+
+* update .all-contributorsrc [skip ci] ([6ee52a6](https://github.com/the-bugging/react-use-downloader/commit/6ee52a6393f393d3241d68c7c68c491d6f8bfe65))
+* update README.md [skip ci] ([7b00739](https://github.com/the-bugging/react-use-downloader/commit/7b00739007fdf78b457bc22ed7d21e5e83a5a9a0))
+
 ### [1.2.7](https://github.com/the-bugging/react-use-downloader/compare/v1.2.6...v1.2.7) (2024-04-16)
 
 ### [1.2.6](https://github.com/the-bugging/react-use-downloader/compare/v1.2.5...v1.2.6) (2024-04-09)

README.md

@@ -8,7 +8,7 @@
 
 | Statements                                                                                      | Branches                                                                                 | Functions                                                                                     | Lines                                                                                 |
 | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| ![Statements](https://img.shields.io/badge/statements-87.38%25-yellow.svg?style=flat&logo=jest) | ![Branches](https://img.shields.io/badge/branches-72.5%25-red.svg?style=flat&logo=jest) | ![Functions](https://img.shields.io/badge/functions-81.81%25-yellow.svg?style=flat&logo=jest) | ![Lines](https://img.shields.io/badge/lines-88%25-yellow.svg?style=flat&logo=jest) |
+| ![Statements](https://img.shields.io/badge/statements-87.38%25-yellow.svg?style=flat&logo=jest) | ![Branches](https://img.shields.io/badge/branches-73.17%25-red.svg?style=flat&logo=jest) | ![Functions](https://img.shields.io/badge/functions-81.81%25-yellow.svg?style=flat&logo=jest) | ![Lines](https://img.shields.io/badge/lines-88%25-yellow.svg?style=flat&logo=jest) |
 
 ## Table of Contents
 
@@ -76,15 +76,15 @@ export default function App() {
 
 - An object with the following keys:
 
-| key          | description                      | arguments                                                 |
-| ------------ | -------------------------------- | --------------------------------------------------------- |
-| size         | size in bytes                    | n/a                                                       |
-| elapsed      | elapsed time in seconds          | n/a                                                       |
-| percentage   | percentage in string             | n/a                                                       |
-| download     | download function handler        | (downloadUrl: string, filename: string, timeout?: number) |
-| cancel       | cancel function handler          | n/a                                                       |
-| error        | error object from the request    | n/a                                                       |
-| isInProgress | boolean denoting download status | n/a                                                       |
+| key          | description                      | arguments                                                                                         |
+| ------------ | -------------------------------- | ------------------------------------------------------------------------------------------------- |
+| size         | size in bytes                    | n/a                                                                                               |
+| elapsed      | elapsed time in seconds          | n/a                                                                                               |
+| percentage   | percentage in string             | n/a                                                                                               |
+| download     | download function handler        | (downloadUrl: string, filename: string, timeout?: number, overrideOptions?: UseDownloaderOptions) |
+| cancel       | cancel function handler          | n/a                                                                                               |
+| error        | error object from the request    | n/a                                                                                               |
+| isInProgress | boolean denoting download status | n/a                                                                                               |
 
 ```jsx
 const { size, elapsed, percentage, download, cancel, error, isInProgress } =
@@ -123,7 +123,10 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
       <td align="center" valign="top" width="14.28%"><a href="http://bzbetty.blogspot.com"><img src="https://avatars.githubusercontent.com/u/533131?v=4?s=100" width="100px;" alt="Sam "Betty" McKoy"/><br /><sub><b>Sam "Betty" McKoy</b></sub></a><br /><a href="https://github.com/the-bugging/react-use-downloader/issues?q=author%3Abzbetty" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/peranosborn"><img src="https://avatars.githubusercontent.com/u/1318002?v=4?s=100" width="100px;" alt="Peran Osborn"/><br /><sub><b>Peran Osborn</b></sub></a><br /><a href="https://github.com/the-bugging/react-use-downloader/issues?q=author%3Aperanosborn" title="Bug reports">🐛</a> <a href="#ideas-peranosborn" title="Ideas, Planning, & Feedback">🤔</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/MarcosRS"><img src="https://avatars.githubusercontent.com/u/12486814?v=4?s=100" width="100px;" alt="Marcos"/><br /><sub><b>Marcos</b></sub></a><br /><a href="https://github.com/the-bugging/react-use-downloader/issues?q=author%3AMarcosRS" title="Bug reports">🐛</a> <a href="#ideas-MarcosRS" title="Ideas, Planning, & Feedback">🤔</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/9swampy"><img src="https://avatars.githubusercontent.com/u/523054?v=4?s=100" width="100px;" alt="9swampy"/><br /><sub><b>9swampy</b></sub></a><br /><a href="https://github.com/the-bugging/react-use-downloader/issues?q=author%3A9swampy" title="Bug reports">🐛</a> <a href="https://github.com/the-bugging/react-use-downloader/commits?author%3A9swampy" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/9swampy"><img src="https://avatars.githubusercontent.com/u/523054?v=4?s=100" width="100px;" alt="9swampy"/><br /><sub><b>9swampy</b></sub></a><br /><a href="https://github.com/the-bugging/react-use-downloader/issues?q=author%3A9swampy" title="Bug reports">🐛</a> <a href="https://github.com/the-bugging/react-use-downloader/commits?author=9swampy" title="Code">💻</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/davecarlson"><img src="https://avatars.githubusercontent.com/u/299702?v=4?s=100" width="100px;" alt="Dave Carlson"/><br /><sub><b>Dave Carlson</b></sub></a><br /><a href="#ideas-davecarlson" title="Ideas, Planning, & Feedback">🤔</a></td>
     </tr>
   </tbody>
 </table>

package.json

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

src/index.ts

@@ -8,6 +8,11 @@ import {
   UseDownloaderOptions,
 } from './types';
 
+/**
+ * Resolver function to handle the download progress.
+ * @param {ResolverProps} props
+ * @returns {Response}
+ */
 export const resolver =
   ({
     setSize,
@@ -76,6 +81,13 @@ export const resolver =
     return new Response(stream);
   };
 
+/**
+ * jsDownload function to handle the download process.
+ * @param {Blob} data
+ * @param {string} filename
+ * @param {string} mime
+ * @returns {boolean | NodeJS.Timeout}
+ */
 export const jsDownload = (
   data: Blob,
   filename: string,
@@ -118,12 +130,17 @@ export const jsDownload = (
   }, 200);
 };
 
+/**
+ * useDownloader hook to handle the download process.
+ * @param {UseDownloaderOptions} options
+ * @returns {UseDownloader}
+ */
 export default function useDownloader(
   options: UseDownloaderOptions = {}
 ): UseDownloader {
   let debugMode = false;
   try {
-      debugMode = process ? !!process?.env?.REACT_APP_DEBUG_MODE : false;
+    debugMode = process ? !!process?.env?.REACT_APP_DEBUG_MODE : false;
   } catch {
     debugMode = false;
   }
@@ -182,7 +199,7 @@ export default function useDownloader(
   }, [setControllerCallback]);
 
   const handleDownload: DownloadFunction = useCallback(
-    async (downloadUrl, filename, timeout = 0) => {
+    async (downloadUrl, filename, timeout = 0, overrideOptions = {}) => {
       if (isInProgress) return null;
 
       clearAllStateCallback();
@@ -208,6 +225,7 @@ export default function useDownloader(
       return fetch(downloadUrl, {
         method: 'GET',
         ...options,
+        ...overrideOptions,
         signal: fetchController.signal,
       })
         .then(resolverWithProgress)

src/types.ts

@@ -4,6 +4,17 @@ export type ErrorMessage = {
   errorMessage: string;
 } | null;
 
+/** useDownloader options for fetch call
+ * See fetch RequestInit for more details
+ */
+export type UseDownloaderOptions = RequestInit;
+
+/**
+ * Initiate the download of the specified asset from the specified url. Optionally supply timeout and overrideOptions.
+ * @example await download('https://example.com/file.zip', 'file.zip')
+ * @example await download('https://example.com/file.zip', 'file.zip', 500) timeouts after 500ms
+ * @example await download('https://example.com/file.zip', 'file.zip', undefined, { method: 'GET' }) skips optional timeout but supplies overrideOptions
+ */
 export type DownloadFunction = (
   /** Download url
    * @example https://upload.wikimedia.org/wikipedia/commons/4/4d/%D0%93%D0%BE%D0%B2%D0%B5%D1%80%D0%BB%D0%B0_%D1%96_%D0%9F%D0%B5%D1%82%D1%80%D0%BE%D1%81_%D0%B2_%D0%BF%D1%80%D0%BE%D0%BC%D1%96%D0%BD%D1%8F%D1%85_%D0%B2%D1%80%D0%B0%D0%BD%D1%96%D1%88%D0%BD%D1%8C%D0%BE%D0%B3%D0%BE_%D1%81%D0%BE%D0%BD%D1%86%D1%8F.jpg
@@ -14,9 +25,23 @@ export type DownloadFunction = (
    */
   filename: string,
   /** Optional timeout to download items */
-  timeout?: number
+  timeout?: number,
+  /** Optional options to supplement and/or override UseDownloader options  */
+  overrideOptions?: UseDownloaderOptions
 ) => Promise<void | null>;
 
+/**
+ * Provides access to Downloader functionality and settings.
+ *
+ * @interface EditDialogField
+ * @field {number} size in bytes.
+ * @field {number} elapsed time in seconds.
+ * @field {number} percentage in string
+ * @field {DownloadFunction} download function handler
+ * @field {void} cancel function handler
+ * @field {ErrorMessage} error object from the request
+ * @field {boolean} isInProgress boolean flag denoting download status
+ */
 export interface UseDownloader {
   /** Size in bytes */
   size: number;
@@ -60,8 +85,3 @@ interface CustomNavigator extends Navigator {
 export interface WindowDownloaderEmbedded extends Window {
   navigator: CustomNavigator;
 }
-
-/** useDownloader options for fetch call
- * See fetch RequestInit for more details
- */
-export type UseDownloaderOptions = RequestInit;