@kesha-antonov/react-native-background-downloader 4.0.2 → 4.0.3

package/README.md

@@ -49,6 +49,8 @@ The real challenge of using this method is making sure the app's UI is always up
 
 ## Getting started
 
+### Installation
+
 ```Terminal
 yarn add @kesha-antonov/react-native-background-downloader
 ```
@@ -64,7 +66,9 @@ Then:
 cd ios && pod install
 ```
 
-#### Manual Setup (Advanced)
+<details>
+<summary>Manual Setup (Advanced)</summary>
+
 If you need to manually configure the package for New Architecture:
 
 **iOS**: The library automatically detects New Architecture via compile-time flags.
@@ -82,16 +86,7 @@ protected List<ReactPackage> getPackages() {
   );
 }
 ```
-
-#### Known Issues with New Architecture
-When using larger files with the New Architecture, you may encounter `ERROR_CANNOT_RESUME` (error code 1008). This is a known limitation of Android's DownloadManager, not specific to this library or the New Architecture. The error includes enhanced messaging to help diagnose the issue.
-
-**Workaround:** If you encounter this error frequently with large files, consider:
-1. Breaking large downloads into smaller chunks
-2. Implementing retry logic in your app
-3. Using alternative download strategies for very large files
-
-The library now provides enhanced error handling for this specific case with detailed logging and cleanup.
+</details>
 
 ### Mostly automatic installation
 Any React Native version **`>= 0.60`** supports autolinking so nothing should be done.
@@ -255,16 +250,18 @@ let task = createDownloadTask({
 // starts download
 task.start()
 
+// ...later
+
 // Pause the task (iOS only)
 // Note: On Android, pause/resume is not supported by DownloadManager
-task.pause()
+await task.pause()
 
 // Resume after pause (iOS only)
 // Note: On Android, pause/resume is not supported by DownloadManager
-task.resume()
+await task.resume()
 
 // Cancel the task
-task.stop()
+await task.stop()
 ```
 
 ### Platform-Aware Pause/Resume
@@ -291,18 +288,18 @@ const task = createDownloadTask({
 task.start()
 
 // Platform-aware pause/resume handling
-function pauseDownloadTask() {
+async function pauseDownloadTask() {
   if (Platform.OS === 'ios') {
-    task.pause()
+    await task.pause()
     console.log('Download paused')
   } else {
     console.log('Pause not supported on Android. Consider using stop() instead.')
   }
 }
 
-function resumeDownloadTask() {
+async function resumeDownloadTask() {
   if (Platform.OS === 'ios') {
-    task.resume()
+    await task.resume()
     console.log('Download resumed')
   } else {
     console.log('Resume not supported on Android. You may need to restart the download.')
@@ -437,7 +434,6 @@ import {
   setConfig,
   createDownloadTask,
   getExistingDownloadTasks,
-  ensureDownloadsAreRunning,
   completeHandler,
   directories
 } from '@kesha-antonov/react-native-background-downloader'
@@ -452,7 +448,6 @@ import RNBackgroundDownloader from '@kesha-antonov/react-native-background-downl
 RNBackgroundDownloader.setConfig
 RNBackgroundDownloader.createDownloadTask
 RNBackgroundDownloader.getExistingDownloadTasks
-RNBackgroundDownloader.ensureDownloadsAreRunning
 RNBackgroundDownloader.completeHandler
 RNBackgroundDownloader.directories
 ```
@@ -531,62 +526,6 @@ After finishing download in background you have some time to process your JS log
 
 **Note:** This should be called after processing your download in the `done` callback to properly signal completion to the OS.
 
-### `ensureDownloadsAreRunning()` (iOS only)
-
-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).
-
-**returns**
-
-`Promise<void>` - A promise that resolves when all downloads have been paused and resumed
-
-Here's example of how you can use it:
-
-1. When your app just loaded
-
-Either stop all tasks:
-
-```javascript
-import { getExistingDownloadTasks } from '@kesha-antonov/react-native-background-downloader'
-
-const tasks = await getExistingDownloadTasks()
-for (const task of tasks)
-  task.stop()
-```
-
-Or re-attach them:
-
-```javascript
-import { getExistingDownloadTasks } from '@kesha-antonov/react-native-background-downloader'
-
-const tasks = await getExistingDownloadTasks()
-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
-import { ensureDownloadsAreRunning } from '@kesha-antonov/react-native-background-downloader'
-
-function handleAppStateChange (appState) {
-  if (appState !== 'active')
-    return
-
-  ensureDownloadsAreRunning()
-}
-
-const appStateChangeListener = AppState.addEventListener('change', handleAppStateChange)
-```
-
-4. Call `ensureDownloadsAreRunning()` after all was setup.
-
 ### `Callback Methods`
 Use these methods to stay updated on what's happening with the task.
 
@@ -599,18 +538,18 @@ All callback methods return the current instance of the `DownloadTask` for chain
 | `done`     | `{ bytesDownloaded: number, bytesTotal: number }` | Called when the download is done, the file is at the destination you've set |
 | `error`    | `{ error: string, errorCode: number }` | Called when the download stops due to an error |
 
-### `pause()`  (iOS only)
-Pauses the download
+### `pause(): Promise<void>`  (iOS only)
+Pauses the download. Returns a promise that resolves when the pause operation is complete.
 
 **Note:** This functionality is not supported on Android due to limitations in the DownloadManager API. On Android, calling this method will log a warning but will not crash the application.
 
-### `resume()`  (iOS only)
-Resumes a paused download
+### `resume(): Promise<void>`  (iOS only)
+Resumes a paused download. Returns a promise that resolves when the resume operation is complete.
 
 **Note:** This functionality is not supported on Android due to limitations in the DownloadManager API. On Android, calling this method will log a warning but will not crash the application.
 
-### `stop()`
-Stops the download for good and removes the file that was written so far
+### `stop(): Promise<void>`
+Stops the download for good and removes the file that was written so far. Returns a promise that resolves when the stop operation is complete.
 
 ## Constants
 
@@ -661,11 +600,19 @@ In case of error `java.lang.IllegalStateException: TypeToken must be created wit
 -keepattributes AnnotationDefault,RuntimeVisibleAnnotations
 ```
 
+## Known Issues with New Architecture
+When using larger files with the New Architecture, you may encounter `ERROR_CANNOT_RESUME` (error code 1008). This is a known limitation of Android's DownloadManager, not specific to this library or the New Architecture. The error includes enhanced messaging to help diagnose the issue.
+
+**Workaround:** If you encounter this error frequently with large files, consider:
+1. Breaking large downloads into smaller chunks
+2. Implementing retry logic in your app
+3. Using alternative download strategies for very large files
+
+The library now provides enhanced error handling for this specific case with detailed logging and cleanup.
+
 ## TODO
 
-- [ ] Write better examples - current kinda old and shallow
 - [ ] Write better API for downloads - current kinda boilerplate
-- [ ] Add more tests
 
 ## Authors
 

package/android/src/newarch/java/com/eko/RNBackgroundDownloaderModule.kt

@@ -29,16 +29,19 @@ class RNBackgroundDownloaderModule(reactContext: ReactApplicationContext) :
         impl.download(options)
     }
 
-    override fun pauseTask(id: String) {
+    override fun pauseTask(id: String, promise: com.facebook.react.bridge.Promise) {
         impl.pauseTask(id)
+        promise.resolve(null)
     }
 
-    override fun resumeTask(id: String) {
+    override fun resumeTask(id: String, promise: com.facebook.react.bridge.Promise) {
         impl.resumeTask(id)
+        promise.resolve(null)
     }
 
-    override fun stopTask(id: String) {
+    override fun stopTask(id: String, promise: com.facebook.react.bridge.Promise) {
         impl.stopTask(id)
+        promise.resolve(null)
     }
 
     override fun completeHandler(jobId: String, promise: com.facebook.react.bridge.Promise) {

package/android/src/oldarch/java/com/eko/RNBackgroundDownloaderModule.kt

@@ -33,18 +33,21 @@ class RNBackgroundDownloaderModule(reactContext: ReactApplicationContext) :
     }
 
     @ReactMethod
-    fun pauseTask(id: String) {
+    fun pauseTask(id: String, promise: Promise) {
         impl.pauseTask(id)
+        promise.resolve(null)
     }
 
     @ReactMethod
-    fun resumeTask(id: String) {
+    fun resumeTask(id: String, promise: Promise) {
         impl.resumeTask(id)
+        promise.resolve(null)
     }
 
     @ReactMethod
-    fun stopTask(id: String) {
+    fun stopTask(id: String, promise: Promise) {
         impl.stopTask(id)
+        promise.resolve(null)
     }
 
     @ReactMethod

package/ios/RNBackgroundDownloader.mm

@@ -373,7 +373,7 @@ RCT_EXPORT_METHOD(download: (NSDictionary *) options) {
     }
 }
 
-- (void)pauseTaskInternal:(NSString *)identifier {
+- (void)pauseTaskInternal:(NSString *)identifier resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject {
     DLog(identifier, @"[RNBackgroundDownloader] - [pauseTask]");
     @synchronized (sharedLock) {
         NSURLSessionDownloadTask *task = self->idToTaskMap[identifier];
@@ -392,22 +392,25 @@ RCT_EXPORT_METHOD(download: (NSDictionary *) options) {
                     }
                     // Keep the identifier in idsToPauseSet until resume or stop is called
                 }
+                resolve(nil);
             }];
+        } else {
+            resolve(nil);
         }
     }
 }
 
-#ifdef RCT_NEW_ARCH_ENABLED
-- (void)pauseTask:(NSString *)identifier {
-    [self pauseTaskInternal:identifier];
+- (void)pauseTask:(NSString *)identifier resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject {
+    [self pauseTaskInternal:identifier resolve:resolve reject:reject];
 }
-#else
-RCT_EXPORT_METHOD(pauseTask: (NSString *)id) {
-    [self pauseTaskInternal:id];
+
+#ifndef RCT_NEW_ARCH_ENABLED
+RCT_EXPORT_METHOD(pauseTask:(NSString *)id resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+    [self pauseTaskInternal:id resolve:resolve reject:reject];
 }
 #endif
 
-- (void)resumeTaskInternal:(NSString *)identifier {
+- (void)resumeTaskInternal:(NSString *)identifier resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject {
     DLog(identifier, @"[RNBackgroundDownloader] - [resumeTask]");
     @synchronized (sharedLock) {
         [self lazyRegisterSession];
@@ -456,19 +459,20 @@ RCT_EXPORT_METHOD(pauseTask: (NSString *)id) {
             DLog(identifier, @"[RNBackgroundDownloader] - [resumeTask] no task or resume data found for %@", identifier);
         }
     }
+    resolve(nil);
 }
 
-#ifdef RCT_NEW_ARCH_ENABLED
-- (void)resumeTask:(NSString *)identifier {
-    [self resumeTaskInternal:identifier];
+- (void)resumeTask:(NSString *)identifier resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject {
+    [self resumeTaskInternal:identifier resolve:resolve reject:reject];
 }
-#else
-RCT_EXPORT_METHOD(resumeTask: (NSString *)id) {
-    [self resumeTaskInternal:id];
+
+#ifndef RCT_NEW_ARCH_ENABLED
+RCT_EXPORT_METHOD(resumeTask:(NSString *)id resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+    [self resumeTaskInternal:id resolve:resolve reject:reject];
 }
 #endif
 
-- (void)stopTaskInternal:(NSString *)identifier {
+- (void)stopTaskInternal:(NSString *)identifier resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject {
     DLog(identifier, @"[RNBackgroundDownloader] - [stopTask]");
     @synchronized (sharedLock) {
         NSURLSessionDownloadTask *task = self->idToTaskMap[identifier];
@@ -479,15 +483,16 @@ RCT_EXPORT_METHOD(resumeTask: (NSString *)id) {
         [self->idToResumeDataMap removeObjectForKey:identifier];
         [idsToPauseSet removeObject:identifier];
     }
+    resolve(nil);
 }
 
-#ifdef RCT_NEW_ARCH_ENABLED
-- (void)stopTask:(NSString *)identifier {
-    [self stopTaskInternal:identifier];
+- (void)stopTask:(NSString *)identifier resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject {
+    [self stopTaskInternal:identifier resolve:resolve reject:reject];
 }
-#else
-RCT_EXPORT_METHOD(stopTask: (NSString *)id) {
-    [self stopTaskInternal:id];
+
+#ifndef RCT_NEW_ARCH_ENABLED
+RCT_EXPORT_METHOD(stopTask:(NSString *)id resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+    [self stopTaskInternal:id resolve:resolve reject:reject];
 }
 #endif
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kesha-antonov/react-native-background-downloader",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "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",

package/src/DownloadTask.ts

@@ -129,17 +129,17 @@ export default class DownloadTask {
     this.downloadParams = downloadParams
   }
 
-  pause () {
+  async pause (): Promise<void> {
     log('DownloadTask: pause', this.id)
     this.state = 'PAUSED'
-    RNBackgroundDownloader.pauseTask(this.id)
+    await RNBackgroundDownloader.pauseTask(this.id)
   }
 
-  resume () {
+  async resume (): Promise<void> {
     log('DownloadTask: resume', this.id)
     this.state = 'DOWNLOADING'
     this.errorCode = 0
-    RNBackgroundDownloader.resumeTask(this.id)
+    await RNBackgroundDownloader.resumeTask(this.id)
   }
 
   start () {
@@ -163,11 +163,11 @@ export default class DownloadTask {
     })
   }
 
-  stop () {
+  async stop (): Promise<void> {
     log('DownloadTask: stop', this.id)
 
     this.state = 'STOPPED'
-    RNBackgroundDownloader.stopTask(this.id)
+    await RNBackgroundDownloader.stopTask(this.id)
   }
 
   tryParseJson (metadata?: string | Metadata): Metadata | null {

package/src/NativeRNBackgroundDownloader.ts

@@ -58,9 +58,9 @@ export interface Spec extends TurboModule {
     maxRedirects?: number
   }): void
 
-  pauseTask(id: string): void
-  resumeTask(id: string): void
-  stopTask(id: string): void
+  pauseTask(id: string): Promise<void>
+  resumeTask(id: string): Promise<void>
+  stopTask(id: string): Promise<void>
 
   completeHandler(jobId: string): Promise<void>
 

package/src/index.ts

@@ -255,16 +255,6 @@ export const getExistingDownloadTasks = async (): Promise<DownloadTask[]> => {
   return downloadTasks
 }
 
-export const ensureDownloadsAreRunning = async (): Promise<void> => {
-  const tasks: DownloadTask[] = await getExistingDownloadTasks()
-  const tasksDownloading = tasks.filter(task => task.state === 'DOWNLOADING')
-
-  for (const task of tasksDownloading) {
-    task.pause()
-    task.resume()
-  }
-}
-
 export const completeHandler = (jobId: string) => {
   if (jobId == null) {
     log('completeHandler: jobId is empty')
@@ -319,7 +309,6 @@ export default {
   setConfig,
   createDownloadTask,
   getExistingDownloadTasks,
-  ensureDownloadsAreRunning,
   completeHandler,
 
   directories,

package/src/types.ts

@@ -94,15 +94,14 @@ export interface DownloadTask {
 
   setDownloadParams: (params: DownloadParams) => void
   start: () => void
-  pause: () => void
-  resume: () => void
-  stop: () => void
+  pause: () => Promise<void>
+  resume: () => Promise<void>
+  stop: () => Promise<void>
 
   tryParseJson: (metadata?: string | Metadata) => Metadata | null
 }
 
 export type getExistingDownloadTasks = () => Promise<DownloadTask[]>
-export type EnsureDownloadsAreRunning = () => Promise<void>
 
 export interface DownloadOption {
   id: string