@kesha-antonov/react-native-background-downloader 4.0.3 → 4.1.2-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## v4.1.0
+
+> 📖 **Upgrading from v4.0.x?** See the [Migration Guide](./MIGRATION.md) for the MMKV dependency change.
+
+### ⚠️ Breaking Changes
+
+- **MMKV Dependency Changed to `compileOnly`:** The MMKV dependency is now `compileOnly` instead of `implementation` to avoid duplicate class errors when the app also uses `react-native-mmkv`. Apps not using `react-native-mmkv` must now explicitly add the MMKV dependency.
+
+### ✨ New Features
+
+- **Expo Plugin Android Support:** The Expo config plugin now automatically adds the MMKV dependency on Android. Use `addMmkvDependency: false` option if you're already using `react-native-mmkv`.
+
+### 🐛 Bug Fixes
+
+- **Duplicate Class Errors:** Fixed potential duplicate class errors when app uses both this library and `react-native-mmkv` by changing MMKV to `compileOnly` dependency
+
+### 📚 Documentation
+
+- Added documentation for MMKV dependency requirements in README
+- Updated Platform-Specific Limitations section with MMKV setup instructions
+- Added Expo plugin options documentation
+
+---
+
 ## v4.0.0
 
 > 📖 **Upgrading from v3.x?** See the [Migration Guide](./MIGRATION.md) for detailed instructions.

package/README.md

@@ -126,7 +126,7 @@ For anything **`< 0.60`** run the following link command
 
 #### Option 1: Using Expo Config Plugin (Recommended for Expo/EAS users)
 
-If you're using Expo or EAS Build, you can use the included Expo config plugin to automatically configure the iOS native code:
+If you're using Expo or EAS Build, you can use the included Expo config plugin to automatically configure the native code:
 
 **In your `app.json`:**
 ```json
@@ -152,10 +152,37 @@ export default {
 }
 ```
 
+**Plugin Options:**
+
+You can customize the plugin behavior with options:
+
+```js
+// app.config.js
+export default {
+  expo: {
+    name: "Your App",
+    plugins: [
+      ["@kesha-antonov/react-native-background-downloader", {
+        // Set to false if you're already using react-native-mmkv
+        addMmkvDependency: true,
+        // Customize the MMKV version (default: '2.2.4')
+        mmkvVersion: "2.2.4"
+      }]
+    ]
+  }
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `addMmkvDependency` | boolean | `true` | Whether to automatically add MMKV dependency on Android. Set to `false` if you're using `react-native-mmkv`. |
+| `mmkvVersion` | string | `'2.2.4'` | The version of MMKV to use on Android. |
+
 The plugin will automatically:
-- Add the required import to your AppDelegate (Objective-C) or Bridging Header (Swift)
-- Add the `handleEventsForBackgroundURLSession` method to your AppDelegate
-- Handle both React Native < 0.77 (Objective-C) and >= 0.77 (Swift) projects
+- **iOS:** Add the required import to your AppDelegate (Objective-C) or Bridging Header (Swift)
+- **iOS:** Add the `handleEventsForBackgroundURLSession` method to your AppDelegate
+- **iOS:** Handle both React Native < 0.77 (Objective-C) and >= 0.77 (Swift) projects
+- **Android:** Add the required MMKV dependency (unless `addMmkvDependency: false`)
 
 After adding the plugin, run:
 ```bash
@@ -439,19 +466,6 @@ import {
 } from '@kesha-antonov/react-native-background-downloader'
 ```
 
-**Default Export:**
-
-```typescript
-import RNBackgroundDownloader from '@kesha-antonov/react-native-background-downloader'
-
-// Contains all the above as properties:
-RNBackgroundDownloader.setConfig
-RNBackgroundDownloader.createDownloadTask
-RNBackgroundDownloader.getExistingDownloadTasks
-RNBackgroundDownloader.completeHandler
-RNBackgroundDownloader.directories
-```
-
 ### `createDownloadTask(options)`
 
 Download a file to destination
@@ -561,6 +575,23 @@ An absolute path to the app's documents directory. It is recommended that you us
 
 ## Platform-Specific Limitations
 
+### Android MMKV Dependency
+
+This library uses MMKV for persistent storage of download state on Android. The MMKV dependency is declared as `compileOnly`, meaning your app must provide it.
+
+**If you're using `react-native-mmkv`:** No additional setup needed - `react-native-mmkv` already provides the required MMKV dependency.
+
+**If you're NOT using `react-native-mmkv`:** Add the MMKV dependency to your app's `android/app/build.gradle`:
+
+```gradle
+dependencies {
+    // ... other dependencies
+    implementation 'com.tencent:mmkv-shared:2.2.4'  // or newer
+}
+```
+
+**Note:** MMKV 2.0.0+ is required for Android 15+ support (16KB memory page sizes).
+
 ### Android DownloadManager Limitations
 
 The Android implementation uses the system's `DownloadManager` service, which has some limitations compared to iOS:

package/android/build.gradle

@@ -5,6 +5,10 @@ def isNewArchitectureEnabled() {
     return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
 }
 
+if (isNewArchitectureEnabled()) {
+    apply plugin: 'com.facebook.react'
+}
+
 def safeExtGet(prop, fallback) {
     rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
 }
@@ -63,10 +67,11 @@ dependencies {
     //noinspection GradleDynamicVersion
     implementation 'com.facebook.react:react-native:+'
 
-    // MMKV dependency updated for 16KB page size support
-    // MMKV 2.2.0+ includes support for 16KB memory page sizes required by Android 15+
-    // Uses mmkv-shared to maintain compatibility with react-native-mmkv 4+
-    implementation 'com.tencent:mmkv-shared:2.2.0'
+    // MMKV dependency for persistent download state storage
+    // Uses compileOnly to avoid duplicate class errors when app also uses react-native-mmkv
+    // The app must provide MMKV dependency (either directly or via react-native-mmkv)
+    // MMKV 2.0.0+ is required for 16KB memory page size support (Android 15+)
+    compileOnly 'com.tencent:mmkv-shared:2.0.0'
 
     implementation 'com.google.code.gson:gson:2.12.1'
 }

package/android/src/main/java/com/eko/RNBackgroundDownloaderModuleImpl.kt

@@ -713,7 +713,10 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
         synchronized(sharedLock) {
             try {
                 val gson = Gson()
-                val str = gson.toJson(downloadIdToConfig)
+                // Create a defensive copy to prevent ConcurrentModificationException
+                // when Gson iterates over the map while another thread modifies it
+                val mapCopy = HashMap(downloadIdToConfig)
+                val str = gson.toJson(mapCopy)
 
                 if (isMMKVAvailable && mmkv != null) {
                     mmkv!!.encode("${NAME}_downloadIdToConfig", str)

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

@@ -1,6 +1,7 @@
 package com.eko
 
 import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactMethod
 import com.facebook.react.module.annotations.ReactModule
 
 @ReactModule(name = RNBackgroundDownloaderModuleImpl.NAME)
@@ -12,7 +13,7 @@ class RNBackgroundDownloaderModule(reactContext: ReactApplicationContext) :
     override fun getName(): String = RNBackgroundDownloaderModuleImpl.NAME
 
     override fun getTypedExportedConstants(): Map<String, Any>? {
-        return impl.constants
+        return impl.getConstants()
     }
 
     override fun initialize() {
@@ -53,11 +54,13 @@ class RNBackgroundDownloaderModule(reactContext: ReactApplicationContext) :
         impl.getExistingDownloadTasks(promise)
     }
 
-    override fun addListener(eventName: String) {
+    @ReactMethod
+    fun addListener(eventName: String) {
         impl.addListener(eventName)
     }
 
-    override fun removeListeners(count: Double) {
+    @ReactMethod
+    fun removeListeners(count: Double) {
         impl.removeListeners(count.toInt())
     }
 }

package/ios/RNBackgroundDownloader.mm

@@ -170,6 +170,9 @@ RCT_EXPORT_MODULE();
         decodeErrorRetriedIds = [[NSMutableSet alloc] init];
 
         [self registerBridgeListener];
+
+        // Initialize session early to receive background events on app relaunch
+        [self lazyRegisterSession];
     }
 
     return self;
@@ -307,12 +310,12 @@ RCT_EXPORT_METHOD(download: (NSDictionary *) options) {
     DLog(identifier, @"[RNBackgroundDownloader] - [download]");
     NSString *url = options[@"url"];
     NSString *destination = options[@"destination"];
-    NSString *metadata = options[@"metadata"];
+    NSString *metadata = options[@"metadata"] ?: @"";
     NSDictionary *headers = options[@"headers"];
 
     NSNumber *progressIntervalScope = options[@"progressInterval"];
     if (progressIntervalScope) {
-        progressInterval = [progressIntervalScope intValue] / 1000;
+        progressInterval = [progressIntervalScope intValue] / 1000.0;
         [mmkv setFloat:progressInterval forKey:PROGRESS_INTERVAL_KEY];
     }
 
@@ -708,7 +711,15 @@ RCT_EXPORT_METHOD(getExistingDownloadTasks: (RCTPromiseResolveBlock)resolve reje
         }];
 #endif
     } else {
-        NSDictionary *responseHeaders = ((NSHTTPURLResponse *)task.response).allHeaderFields;
+        // Safely extract response headers - may be nil if response is not an HTTP response
+        NSDictionary *responseHeaders = nil;
+        if ([task.response isKindOfClass:[NSHTTPURLResponse class]]) {
+            responseHeaders = ((NSHTTPURLResponse *)task.response).allHeaderFields;
+        }
+        // Use empty dictionary if headers are nil to prevent NSDictionary nil insertion crash
+        if (responseHeaders == nil) {
+            responseHeaders = @{};
+        }
 #ifdef RCT_NEW_ARCH_ENABLED
         [self emitOnDownloadComplete:@{
             @"id": taskConfig.id,
@@ -762,7 +773,15 @@ RCT_EXPORT_METHOD(getExistingDownloadTasks: (RCTPromiseResolveBlock)resolve reje
     }
 
     if ([self canSendEvents]) {
-        NSDictionary *responseHeaders = ((NSHTTPURLResponse *)task.response).allHeaderFields;
+        // Safely extract response headers - may be nil if response is not an HTTP response
+        NSDictionary *responseHeaders = nil;
+        if ([task.response isKindOfClass:[NSHTTPURLResponse class]]) {
+            responseHeaders = ((NSHTTPURLResponse *)task.response).allHeaderFields;
+        }
+        // Use empty dictionary if headers are nil to prevent NSDictionary nil insertion crash
+        if (responseHeaders == nil) {
+            responseHeaders = @{};
+        }
 #ifdef RCT_NEW_ARCH_ENABLED
         [self emitOnDownloadBegin:@{
             @"id": taskConfig.id,
@@ -834,11 +853,17 @@ RCT_EXPORT_METHOD(getExistingDownloadTasks: (RCTPromiseResolveBlock)resolve reje
         DLog(taskConfig.id, @"[RNBackgroundDownloader] - [didCompleteWithError] error: %@", error);
 
         // NSURLErrorCancelled (-999) is used for paused or cancelled tasks
-        NSData *resumeData = task.error.userInfo[NSURLSessionDownloadTaskResumeData];
+        // Extract resume data first before checking isPausedTask
+        NSData *resumeData = error.userInfo[NSURLSessionDownloadTaskResumeData];
         BOOL isPausedTask = (error.code == NSURLErrorCancelled && resumeData != nil);
 
         if (isPausedTask) {
             taskConfig.errorCode = error.code;
+
+            // Store resume data so we can resume the download later
+            if (taskConfig.id && resumeData) {
+                idToResumeDataMap[taskConfig.id] = resumeData;
+            }
             DLog(taskConfig.id, @"[RNBackgroundDownloader] - [didCompleteWithError] task was paused, ignoring error for %@", taskConfig.id);
             return;
         }
@@ -918,6 +943,11 @@ RCT_EXPORT_METHOD(getExistingDownloadTasks: (RCTPromiseResolveBlock)resolve reje
 }
 
 - (NSError *)getServerError:(NSURLSessionDownloadTask *)downloadTask {
+    // Safely check if response is an HTTP response
+    if (![downloadTask.response isKindOfClass:[NSHTTPURLResponse class]]) {
+        return nil; // No HTTP response, can't determine server error
+    }
+
     NSInteger statusCode = ((NSHTTPURLResponse *)downloadTask.response).statusCode;
 
     // 200: OK, 206: Partial Content (for resumed downloads)
@@ -938,6 +968,17 @@ RCT_EXPORT_METHOD(getExistingDownloadTasks: (RCTPromiseResolveBlock)resolve reje
     // Relative paths are used to recreate the Absolute path.
     NSString *rootPath = [self getRootPathFromPath:taskConfig.destination];
     NSString *fileRelativePath = [self getRelativeFilePathFromPath:taskConfig.destination];
+
+    // Check for nil paths to prevent crash
+    if (rootPath == nil || fileRelativePath == nil) {
+        if (saveError) {
+            *saveError = [NSError errorWithDomain:NSURLErrorDomain
+                                             code:NSURLErrorFileDoesNotExist
+                                         userInfo:@{NSLocalizedDescriptionKey: @"Invalid destination path"}];
+        }
+        return NO;
+    }
+
     NSString *fileAbsolutePath = [rootPath stringByAppendingPathComponent:fileRelativePath];
     NSURL *destinationURL = [NSURL fileURLWithPath:fileAbsolutePath];
 

package/package.json

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

package/plugin/build/index.d.ts

@@ -1,3 +1,16 @@
 import { ConfigPlugin } from '@expo/config-plugins';
-declare const withRNBackgroundDownloader: ConfigPlugin;
+interface PluginOptions {
+    /**
+     * Whether to automatically add the MMKV dependency to the Android app.
+     * Set to false if you're already using react-native-mmkv or want to manage the dependency yourself.
+     * @default true
+     */
+    addMmkvDependency?: boolean;
+    /**
+     * The version of MMKV to use. Only used if addMmkvDependency is true.
+     * @default '2.2.4'
+     */
+    mmkvVersion?: string;
+}
+declare const withRNBackgroundDownloader: ConfigPlugin<PluginOptions | void>;
 export default withRNBackgroundDownloader;

package/plugin/build/index.js

@@ -36,8 +36,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const config_plugins_1 = require("@expo/config-plugins");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const withRNBackgroundDownloader = (config) => {
-    // Handle AppDelegate modifications
+const withRNBackgroundDownloader = (config, options) => {
+    const { addMmkvDependency = true, mmkvVersion = '2.2.4' } = options || {};
+    // Handle iOS AppDelegate modifications
     config = (0, config_plugins_1.withAppDelegate)(config, (config) => {
         if (config.modResults.language === 'objc') {
             // For Objective-C AppDelegate.m (React Native < 0.77)
@@ -53,8 +54,30 @@ const withRNBackgroundDownloader = (config) => {
         }
         return config;
     });
+    // Handle Android MMKV dependency
+    if (addMmkvDependency)
+        config = (0, config_plugins_1.withAppBuildGradle)(config, (config) => {
+            config.modResults.contents = addMmkvDependencyAndroid(config.modResults.contents, mmkvVersion);
+            return config;
+        });
     return config;
 };
+function addMmkvDependencyAndroid(buildGradleContents, mmkvVersion) {
+    // Check if MMKV dependency is already present
+    if (buildGradleContents.includes('com.tencent:mmkv'))
+        return buildGradleContents;
+    // Find the dependencies block and add MMKV
+    const dependenciesRegex = /dependencies\s*\{/;
+    const match = buildGradleContents.match(dependenciesRegex);
+    if (match) {
+        const insertPosition = buildGradleContents.indexOf(match[0]) + match[0].length;
+        const mmkvDependency = `\n    // MMKV is required by @kesha-antonov/react-native-background-downloader\n    // If you're using react-native-mmkv, you can disable this in the plugin options\n    implementation 'com.tencent:mmkv-shared:${mmkvVersion}'`;
+        buildGradleContents = buildGradleContents.slice(0, insertPosition) +
+            mmkvDependency +
+            buildGradleContents.slice(insertPosition);
+    }
+    return buildGradleContents;
+}
 function addObjCSupport(appDelegateContents) {
     // Add import if not already present
     if (!appDelegateContents.includes('#import <RNBackgroundDownloader.h>')) {

package/src/DownloadTask.ts

@@ -29,7 +29,7 @@ if (isTurboModuleEnabled)
 else
   RNBackgroundDownloader = NativeModules.RNBackgroundDownloader
 
-export default class DownloadTask {
+export class DownloadTask {
   id: string = ''
   metadata: Metadata = {}
 

package/src/index.ts

@@ -1,5 +1,5 @@
 import { NativeModules, Platform, TurboModuleRegistry, NativeEventEmitter, NativeModule } from 'react-native'
-import DownloadTask from './DownloadTask'
+import { DownloadTask } from './DownloadTask'
 import { Config, DownloadParams, Headers, TaskInfo, TaskInfoNative } from './types'
 import { config, log, DEFAULT_PROGRESS_INTERVAL, DEFAULT_PROGRESS_MIN_BYTES } from './config'
 import type { Spec } from './NativeRNBackgroundDownloader'
@@ -305,11 +305,4 @@ export const directories = {
   },
 }
 
-export default {
-  setConfig,
-  createDownloadTask,
-  getExistingDownloadTasks,
-  completeHandler,
-
-  directories,
-}
+export type * from './types'