@kesha-antonov/react-native-background-downloader 4.0.0-alpha.1 → 4.0.2

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## v4.0.0-alpha.0
+## v4.0.0
 
 > 📖 **Upgrading from v3.x?** See the [Migration Guide](./MIGRATION.md) for detailed instructions.
 

package/README.md

@@ -5,11 +5,9 @@
 
 [![npm version](https://badge.fury.io/js/@kesha-antonov%2Freact-native-background-downloader.svg)](https://badge.fury.io/js/@kesha-antonov%2Freact-native-background-downloader)
 
-## 🎉 Version 4.0.0-alpha.0 Released!
+## 🎉 Version 4.0.0 Released!
 
-**v4.0.0-alpha.0** is now available with full **React Native New Architecture (TurboModules)** support!
-
-> ⚠️ **Alpha Release:** This version is in alpha state. Please report any issues you encounter.
+**v4.0.0** is now available with full **React Native New Architecture (TurboModules)** support!
 
 ### What's New
 - ✅ Full TurboModules support for iOS and Android

package/ios/RNBackgroundDownloader.mm

@@ -58,16 +58,16 @@ RCT_EXPORT_MODULE();
 // Enable interop layer so NativeModules.RNBackgroundDownloader is available
 // This is required for NativeEventEmitter to work with TurboModules
 + (BOOL)requiresMainQueueSetup {
-    return YES;
+    return NO;
 }
 
 #pragma mark - Helper methods
 
 - (BOOL)canSendEvents {
-    // Always return YES - let RCTEventEmitter handle listener management
-    // The warning "Sending X with no listeners registered" is harmless
-    // and events will be properly received once JS listeners are set up
-    return YES;
+    // Only send events if JavaScript has fully loaded
+    // This prevents "Invariant Violation: Failed to call into JavaScript module method"
+    // errors that occur when native code tries to send events before the JS bridge is ready
+    return isJavascriptLoaded;
 }
 
 - (RNBGDTaskConfig *)configForTask:(NSURLSessionTask *)task {
@@ -126,6 +126,11 @@ RCT_EXPORT_MODULE();
     self = [super initWithDisabledObservation];
 #endif
     if (self) {
+#ifdef RCT_NEW_ARCH_ENABLED
+        // TurboModules are lazily initialized when JS first accesses them,
+        // so JavaScript is ready when init is called
+        isJavascriptLoaded = YES;
+#endif
         [MMKV initializeMMKV:nil];
         mmkv = [MMKV mmkvWithID:@"RNBackgroundDownloader"];
 
@@ -368,7 +373,7 @@ RCT_EXPORT_METHOD(download: (NSDictionary *) options) {
     }
 }
 
-- (void)pauseTask:(NSString *)identifier {
+- (void)pauseTaskInternal:(NSString *)identifier {
     DLog(identifier, @"[RNBackgroundDownloader] - [pauseTask]");
     @synchronized (sharedLock) {
         NSURLSessionDownloadTask *task = self->idToTaskMap[identifier];
@@ -392,13 +397,17 @@ RCT_EXPORT_METHOD(download: (NSDictionary *) options) {
     }
 }
 
-#ifndef RCT_NEW_ARCH_ENABLED
+#ifdef RCT_NEW_ARCH_ENABLED
+- (void)pauseTask:(NSString *)identifier {
+    [self pauseTaskInternal:identifier];
+}
+#else
 RCT_EXPORT_METHOD(pauseTask: (NSString *)id) {
-    [self pauseTask:id];
+    [self pauseTaskInternal:id];
 }
 #endif
 
-- (void)resumeTask:(NSString *)identifier {
+- (void)resumeTaskInternal:(NSString *)identifier {
     DLog(identifier, @"[RNBackgroundDownloader] - [resumeTask]");
     @synchronized (sharedLock) {
         [self lazyRegisterSession];
@@ -449,13 +458,17 @@ RCT_EXPORT_METHOD(pauseTask: (NSString *)id) {
     }
 }
 
-#ifndef RCT_NEW_ARCH_ENABLED
+#ifdef RCT_NEW_ARCH_ENABLED
+- (void)resumeTask:(NSString *)identifier {
+    [self resumeTaskInternal:identifier];
+}
+#else
 RCT_EXPORT_METHOD(resumeTask: (NSString *)id) {
-    [self resumeTask:id];
+    [self resumeTaskInternal:id];
 }
 #endif
 
-- (void)stopTask:(NSString *)identifier {
+- (void)stopTaskInternal:(NSString *)identifier {
     DLog(identifier, @"[RNBackgroundDownloader] - [stopTask]");
     @synchronized (sharedLock) {
         NSURLSessionDownloadTask *task = self->idToTaskMap[identifier];
@@ -468,9 +481,13 @@ RCT_EXPORT_METHOD(resumeTask: (NSString *)id) {
     }
 }
 
-#ifndef RCT_NEW_ARCH_ENABLED
+#ifdef RCT_NEW_ARCH_ENABLED
+- (void)stopTask:(NSString *)identifier {
+    [self stopTaskInternal:identifier];
+}
+#else
 RCT_EXPORT_METHOD(stopTask: (NSString *)id) {
-    [self stopTask:id];
+    [self stopTaskInternal:id];
 }
 #endif
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kesha-antonov/react-native-background-downloader",
-  "version": "4.0.0-alpha.1",
+  "version": "4.0.2",
   "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",
@@ -83,9 +83,9 @@
     "@babel/preset-typescript": "^7.28.5",
     "@babel/runtime": "^7.28.4",
     "@expo/config-plugins": "^54.0.2",
-    "@react-native/babel-preset": "^0.81.4",
-    "@react-native/eslint-config": "^0.81.4",
-    "@react-native/metro-config": "^0.81.4",
+    "@react-native/babel-preset": "^0.81.5",
+    "@react-native/eslint-config": "^0.81.5",
+    "@react-native/metro-config": "^0.81.5",
     "@typescript-eslint/eslint-plugin": "^8.46.1",
     "@typescript-eslint/parser": "^8.46.1",
     "babel-jest": "^29.7.0",
@@ -105,7 +105,7 @@
     "lint-staged": ">=16",
     "metro-react-native-babel-preset": "^0.77.0",
     "react": "19.1.0",
-    "react-native": "0.81.4",
+    "react-native": "0.81.5",
     "react-native-fs": "^2.20.0",
     "react-native-vector-icons": "^10.3.0",
     "react-test-renderer": "19.2.0",

package/src/DownloadTask.ts

@@ -15,7 +15,7 @@ import {
   DownloadTaskState,
   Metadata,
 } from './types'
-import { config, log } from '.'
+import { config, log } from './config'
 import type { Spec } from './NativeRNBackgroundDownloader'
 
 // Try to get the native module using TurboModuleRegistry first (new architecture),

package/src/config.ts

@@ -0,0 +1,23 @@
+import { Headers } from './types'
+
+export const DEFAULT_PROGRESS_INTERVAL = 1000
+export const DEFAULT_PROGRESS_MIN_BYTES = 1024 * 1024 // 1MB
+
+interface ConfigState {
+  headers: Headers
+  progressInterval: number
+  progressMinBytes: number
+  isLogsEnabled: boolean
+}
+
+export const config: ConfigState = {
+  headers: {},
+  progressInterval: DEFAULT_PROGRESS_INTERVAL,
+  progressMinBytes: DEFAULT_PROGRESS_MIN_BYTES,
+  isLogsEnabled: false,
+}
+
+export const log = (...args: unknown[]): void => {
+  if (config.isLogsEnabled)
+    console.log('[RNBackgroundDownloader]', ...args)
+}

package/src/index.ts

@@ -1,9 +1,10 @@
-import { NativeModules, Platform, TurboModuleRegistry, DeviceEventEmitter } from 'react-native'
+import { NativeModules, Platform, TurboModuleRegistry, NativeEventEmitter, NativeModule } from 'react-native'
 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'
 
-type NativeModule = Spec & {
+type RNBackgroundDownloaderModule = Spec & {
   TaskRunning: number
   TaskSuspended: number
   TaskCanceling: number
@@ -11,61 +12,61 @@ type NativeModule = Spec & {
   documents: string
 }
 
-// Try to get the native module using TurboModuleRegistry first (new architecture),
-// then fall back to NativeModules (old architecture)
-let RNBackgroundDownloader: NativeModule
-
-// Try TurboModules first
-const turboModule = TurboModuleRegistry.get<Spec>('RNBackgroundDownloader')
-const isNewArchitecture = turboModule != null
-
-if (turboModule) {
-  // TurboModules use getConstants() method
-  const constants = turboModule.getConstants()
-  RNBackgroundDownloader = Object.assign(turboModule, constants) as NativeModule
-} else {
-  // Fall back to old architecture
-  RNBackgroundDownloader = NativeModules.RNBackgroundDownloader
-
-  // For old architecture, constants may need to be fetched via getConstants() as well
-  if (RNBackgroundDownloader && !RNBackgroundDownloader.documents && typeof RNBackgroundDownloader.getConstants === 'function') {
-    const constants = RNBackgroundDownloader.getConstants()
-    if (constants)
-      Object.assign(RNBackgroundDownloader, constants)
+// Lazy initialization state
+let RNBackgroundDownloader: RNBackgroundDownloaderModule & NativeModule
+let turboModule: Spec | null = null
+let isNewArchitecture = false
+let isInitialized = false
+
+/**
+ * Lazily initialize the native module.
+ * This is called on first actual use of the module, not at import time.
+ * This prevents issues with module loading before React Native's bridge is ready.
+ */
+function ensureNativeModuleInitialized (): RNBackgroundDownloaderModule & NativeModule {
+  if (isInitialized && RNBackgroundDownloader)
+    return RNBackgroundDownloader
+
+  // Try TurboModules first
+  turboModule = TurboModuleRegistry.get<Spec>('RNBackgroundDownloader')
+  // Check if the new architecture event emitters are available
+  // TurboModuleRegistry.get() can return a module even with old arch, but event emitters won't exist
+  isNewArchitecture = turboModule != null && typeof turboModule.onDownloadBegin === 'function'
+
+  if (isNewArchitecture && turboModule) {
+    // New architecture: TurboModules use getConstants() method
+    const constants = turboModule.getConstants()
+    RNBackgroundDownloader = Object.assign(turboModule, constants) as RNBackgroundDownloaderModule & NativeModule
+  } else {
+    // Fall back to old architecture - must use NativeModules for proper event emission
+    RNBackgroundDownloader = NativeModules.RNBackgroundDownloader
+
+    // For old architecture, constants may need to be fetched via getConstants() as well
+    if (RNBackgroundDownloader && !RNBackgroundDownloader.documents && typeof RNBackgroundDownloader.getConstants === 'function') {
+      const constants = RNBackgroundDownloader.getConstants()
+      if (constants)
+        Object.assign(RNBackgroundDownloader, constants)
+    }
   }
-}
 
-if (!RNBackgroundDownloader)
-  throw new Error(
-    'The package \'@kesha-antonov/react-native-background-downloader\' doesn\'t seem to be linked. Make sure: \n\n' +
-    Platform.select({ ios: '- You have run \'pod install\'\n', default: '' }) +
-    '- You rebuilt the app after installing the package\n' +
-    '- You are not using Expo Go\n'
-  )
+  if (!RNBackgroundDownloader)
+    throw new Error(
+      'The package \'@kesha-antonov/react-native-background-downloader\' doesn\'t seem to be linked. Make sure: \n\n' +
+      Platform.select({ ios: '- You have run \'pod install\'\n', default: '' }) +
+      '- You rebuilt the app after installing the package\n' +
+      '- You are not using Expo Go\n'
+    )
 
-const MIN_PROGRESS_INTERVAL = 250
-const DEFAULT_PROGRESS_INTERVAL = 1000
-const DEFAULT_PROGRESS_MIN_BYTES = 1024 * 1024 // 1MB
-const tasksMap = new Map<string, DownloadTask>()
+  isInitialized = true
 
-interface ConfigState {
-  headers: Headers
-  progressInterval: number
-  progressMinBytes: number
-  isLogsEnabled: boolean
-}
+  // Initialize event listeners after native module is ready
+  initializeEventListeners()
 
-export const config: ConfigState = {
-  headers: {},
-  progressInterval: DEFAULT_PROGRESS_INTERVAL,
-  progressMinBytes: DEFAULT_PROGRESS_MIN_BYTES,
-  isLogsEnabled: false,
+  return RNBackgroundDownloader
 }
 
-export const log = (...args: unknown[]): void => {
-  if (config.isLogsEnabled)
-    console.log('[RNBackgroundDownloader]', ...args)
-}
+const MIN_PROGRESS_INTERVAL = 250
+const tasksMap = new Map<string, DownloadTask>()
 
 interface DownloadBeginEvent {
   id: string
@@ -92,74 +93,89 @@ interface DownloadFailedEvent {
 }
 
 // Set up event listeners based on architecture
-if (isNewArchitecture && turboModule) {
-  // New architecture: use EventEmitter from TurboModule spec
-  turboModule.onDownloadBegin((data: DownloadBeginEvent) => {
-    const { id, ...rest } = data
-    log('downloadBegin', id, rest)
-    const task = tasksMap.get(id)
-    task?.onBegin(rest)
-  })
-
-  turboModule.onDownloadProgress((events: DownloadProgressEvent[]) => {
-    log('downloadProgress', events)
-    for (const event of events) {
-      const { id, ...rest } = event
+// For old architecture, we need to defer NativeEventEmitter creation
+// to avoid issues during module initialization
+let eventListenersInitialized = false
+
+function initializeEventListeners () {
+  if (eventListenersInitialized) return
+  eventListenersInitialized = true
+
+  if (isNewArchitecture && turboModule) {
+    // New architecture: use EventEmitter from TurboModule spec
+    turboModule.onDownloadBegin((data: DownloadBeginEvent) => {
+      const { id, ...rest } = data
+      log('downloadBegin', id, rest)
       const task = tasksMap.get(id)
-      task?.onProgress(rest)
-    }
-  })
-
-  turboModule.onDownloadComplete((data: DownloadCompleteEvent) => {
-    const { id, ...rest } = data
-    log('downloadComplete', id, rest)
-    const task = tasksMap.get(id)
-    task?.onDone(rest)
-    tasksMap.delete(id)
-  })
+      task?.onBegin(rest)
+    })
+
+    turboModule.onDownloadProgress((events: DownloadProgressEvent[]) => {
+      log('downloadProgress', events)
+      for (const event of events) {
+        const { id, ...rest } = event
+        const task = tasksMap.get(id)
+        task?.onProgress(rest)
+      }
+    })
 
-  turboModule.onDownloadFailed((data: DownloadFailedEvent) => {
-    const { id, ...rest } = data
-    log('downloadFailed', id, rest)
-    const task = tasksMap.get(id)
-    task?.onError(rest)
-    tasksMap.delete(id)
-  })
-} else {
-  // Old architecture: use DeviceEventEmitter
-  DeviceEventEmitter.addListener('downloadBegin', (data: DownloadBeginEvent) => {
-    const { id, ...rest } = data
-    log('downloadBegin', id, rest)
-    const task = tasksMap.get(id)
-    task?.onBegin(rest)
-  })
+    turboModule.onDownloadComplete((data: DownloadCompleteEvent) => {
+      const { id, ...rest } = data
+      log('downloadComplete', id, rest)
+      const task = tasksMap.get(id)
+      task?.onDone(rest)
+      tasksMap.delete(id)
+    })
 
-  DeviceEventEmitter.addListener('downloadProgress', (events: DownloadProgressEvent[]) => {
-    log('downloadProgress', events)
-    for (const event of events) {
-      const { id, ...rest } = event
+    turboModule.onDownloadFailed((data: DownloadFailedEvent) => {
+      const { id, ...rest } = data
+      log('downloadFailed', id, rest)
       const task = tasksMap.get(id)
-      task?.onProgress(rest)
-    }
-  })
+      task?.onError(rest)
+      tasksMap.delete(id)
+    })
+  } else {
+    // Old architecture: use NativeEventEmitter with the native module
+    // RCTEventEmitter on native side requires NativeEventEmitter on JS side
+    const eventEmitter = new NativeEventEmitter(RNBackgroundDownloader)
+
+    eventEmitter.addListener('downloadBegin', (data: DownloadBeginEvent) => {
+      const { id, ...rest } = data
+      log('downloadBegin', id, rest)
+      const task = tasksMap.get(id)
+      task?.onBegin(rest)
+    })
+
+    eventEmitter.addListener('downloadProgress', (events: DownloadProgressEvent[]) => {
+      log('downloadProgress', events)
+      for (const event of events) {
+        const { id, ...rest } = event
+        const task = tasksMap.get(id)
+        task?.onProgress(rest)
+      }
+    })
 
-  DeviceEventEmitter.addListener('downloadComplete', (data: DownloadCompleteEvent) => {
-    const { id, ...rest } = data
-    log('downloadComplete', id, rest)
-    const task = tasksMap.get(id)
-    task?.onDone(rest)
-    tasksMap.delete(id)
-  })
+    eventEmitter.addListener('downloadComplete', (data: DownloadCompleteEvent) => {
+      const { id, ...rest } = data
+      log('downloadComplete', id, rest)
+      const task = tasksMap.get(id)
+      task?.onDone(rest)
+      tasksMap.delete(id)
+    })
 
-  DeviceEventEmitter.addListener('downloadFailed', (data: DownloadFailedEvent) => {
-    const { id, ...rest } = data
-    log('downloadFailed', id, rest)
-    const task = tasksMap.get(id)
-    task?.onError(rest)
-    tasksMap.delete(id)
-  })
+    eventEmitter.addListener('downloadFailed', (data: DownloadFailedEvent) => {
+      const { id, ...rest } = data
+      log('downloadFailed', id, rest)
+      const task = tasksMap.get(id)
+      task?.onError(rest)
+      tasksMap.delete(id)
+    })
+  }
 }
 
+// Event listeners are now initialized lazily when ensureNativeModuleInitialized() is called
+// This ensures the bridge is ready before any native module access
+
 export function setConfig ({
   headers = {},
   progressInterval = DEFAULT_PROGRESS_INTERVAL,
@@ -182,7 +198,8 @@ export function setConfig ({
 }
 
 export const getExistingDownloadTasks = async (): Promise<DownloadTask[]> => {
-  const downloads = await RNBackgroundDownloader.getExistingDownloadTasks()
+  const nativeModule = ensureNativeModuleInitialized()
+  const downloads = await nativeModule.getExistingDownloadTasks()
   const downloadTasks: DownloadTask[] = downloads.map(downloadInfo => {
     // Parse metadata from JSON string to object
     let metadata = {}
@@ -202,15 +219,15 @@ export const getExistingDownloadTasks = async (): Promise<DownloadTask[]> => {
     const task = new DownloadTask(taskInfo, tasksMap.get(taskInfo.id))
 
     switch (taskInfo.state) {
-      case RNBackgroundDownloader.TaskRunning: {
+      case nativeModule.TaskRunning: {
         task.state = 'DOWNLOADING'
         break
       }
-      case RNBackgroundDownloader.TaskSuspended: {
+      case nativeModule.TaskSuspended: {
         task.state = 'PAUSED'
         break
       }
-      case RNBackgroundDownloader.TaskCanceling: {
+      case nativeModule.TaskCanceling: {
         // On iOS, paused tasks (via cancelByProducingResumeData) are in Canceling state with errorCode -999
         if (taskInfo.errorCode === -999) {
           task.state = 'PAUSED'
@@ -220,7 +237,7 @@ export const getExistingDownloadTasks = async (): Promise<DownloadTask[]> => {
         }
         break
       }
-      case RNBackgroundDownloader.TaskCompleted: {
+      case nativeModule.TaskCompleted: {
         if (taskInfo.bytesDownloaded === taskInfo.bytesTotal)
           task.state = 'DONE'
         else
@@ -254,7 +271,8 @@ export const completeHandler = (jobId: string) => {
     return
   }
 
-  return RNBackgroundDownloader.completeHandler(jobId)
+  const nativeModule = ensureNativeModuleInitialized()
+  return nativeModule.completeHandler(jobId)
 }
 
 export function createDownloadTask ({
@@ -263,6 +281,9 @@ export function createDownloadTask ({
   isNotificationVisible = false,
   ...rest
 }: TaskInfo & DownloadParams) {
+  // Ensure native module and event listeners are initialized before creating tasks
+  ensureNativeModuleInitialized()
+
   if (!rest.id || !rest.url || !rest.destination)
     throw new Error('[RNBackgroundDownloader] id, url and destination are required')
 
@@ -287,8 +308,11 @@ export function createDownloadTask ({
   return task
 }
 
+// Use getter to lazily initialize native module when directories are accessed
 export const directories = {
-  documents: RNBackgroundDownloader.documents,
+  get documents () {
+    return ensureNativeModuleInitialized().documents
+  },
 }
 
 export default {