Merge branch 'develop'

the-bugging · Apr 17, 2024 · 0585038 · 0585038
2 parents 4a5261e + 21c00f6
commit 0585038
Show file tree

Hide file tree

Showing 6 changed files with 79 additions and 21 deletions.
diff --git a/.all-contributorsrc b/.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"
-}
+}
diff --git a/CHANGELOG.md b/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)

diff --git a/README.md b/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>

diff --git a/package.json b/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",

diff --git a/src/index.ts b/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)

diff --git a/src/types.ts b/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;