add method ensureDownloadsAreRunning + explanation in readme. v2.6.0

README.md

@@ -254,6 +254,51 @@ A class representing a download task created by `RNBackgroundDownloader.download
 Finishes download job on iOS and informs OS that app can be closed in background if needed.
 After finishing download in background you have some time to process your JS logic and finish the job.
 
+### `ensureDownloadsAreRunning`
+
+Pauses and resumes all downloads - this is fix for stuck downloads. Use it when your app loaded and is ready for handling downloads (all your logic loaded and ready to handle download callbacks).
+
+Here's example of how you can use it:
+
+1. When your app just loaded
+
+Either stop all tasks:
+
+```javascript
+const tasks = await checkForExistingDownloads()
+for (const task of tasks)
+	task.stop()
+```
+
+Or re-attach them:
+
+```javascript
+const tasks = await checkForExistingDownloads()
+for (const task of tasks) {
+	task.pause()
+	//
+	// YOUR LOGIC OF RE-ATTACHING DOWLOADS TO YOUR STUFF
+	// ...
+	//
+}
+```
+
+2. Prepare your app to handle downloads... (load your state etc.)
+
+3. Add listener to handle when your app goes foreground (be sure to do it only after you stopped all tasks or re-attached them!)
+
+```javascript
+
+function handleAppStateChange (appState) {
+	if (appState !== 'active')
+		return
+
+	ensureDownloadsAreRunning()
+}
+
+const appStateChangeListener = AppState.addEventListener('change', handleAppStateChange)
+```
+
 ### `Callback Methods`
 Use these methods to stay updated on what's happening with the task.
 

index.js

@@ -32,14 +32,14 @@ RNBackgroundDownloaderEmitter.addListener('downloadBegin', ({ id, expectedBytes,
   task?.onBegin({ expectedBytes, headers })
 })
 
-export function setHeaders (h = {}) {
+export function setHeaders(h = {}) {
   if (typeof h !== 'object')
     throw new Error('[RNBackgroundDownloader] headers must be an object')
 
   headers = h
 }
 
-export function checkForExistingDownloads () {
+export function checkForExistingDownloads() {
   return RNBackgroundDownloader.checkForExistingDownloads()
     .then(foundTasks => {
       return foundTasks.map(taskInfo => {
@@ -55,7 +55,7 @@ export function checkForExistingDownloads () {
           if (taskInfo.bytesWritten === taskInfo.totalBytes)
             task.state = 'DONE'
           else
-          // IOS completed the download but it was not done.
+            // IOS completed the download but it was not done.
             return null
         }
         tasksMap.set(taskInfo.id, task)
@@ -64,25 +64,38 @@ export function checkForExistingDownloads () {
     })
 }
 
-export function completeHandler (jobId) {
+export function ensureDownloadsAreRunning() {
+  return checkForExistingDownloads()
+    .then(tasks => {
+      for (const task of tasks)
+        if (task.state === 'DOWNLOADING') {
+          task.pause()
+          task.resume()
+        }
+    })
+}
+
+export function completeHandler(jobId) {
   return RNBackgroundDownloader.completeHandler(jobId)
 }
 
-export function download (options) {
+export function download(options) {
   if (!options.id || !options.url || !options.destination)
     throw new Error('[RNBackgroundDownloader] id, url and destination are required')
 
-  options.headers = options.headers && typeof options.headers === 'object'
-    ? { ...headers, ...options.headers }
-    : headers
+  options.headers = { ...headers, ...(options.headers || {}) }
 
-  options.metadata = options.metadata && typeof options.metadata === 'object'
-    ? JSON.stringify(options.metadata)
-    : JSON.stringify({})
+  options.metadata = JSON.stringify(
+    options.metadata && typeof options.metadata === 'object'
+      ? options.metadata
+      : {}
+  )
 
-  RNBackgroundDownloader.download(options)
   const task = new DownloadTask({ id: options.id, metadata: options.metadata })
   tasksMap.set(options.id, task)
+
+  RNBackgroundDownloader.download(options)
+
   return task
 }
 
@@ -104,6 +117,7 @@ export const Priority = {
 export default {
   download,
   checkForExistingDownloads,
+  ensureDownloadsAreRunning,
   completeHandler,
   setHeaders,
   directories,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-background-downloader",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "A library for React-Native to help you download large files on iOS and Android both in the foreground and most importantly in the background.",
   "keywords": [
     "react-native",