How kesha-antonov/react-native-background-downloader works
Project Type and Purpose
• This is an open-source React Native library/module whose sole responsibility is to provide a unified, cross-platform API for downloading large files in the background on both iOS (using NSURLSession) and Android (using DownloadManager).
• It exposes a JavaScript interface (download, checkForExistingDownloads, setConfig, etc.) and under-the-hood bridges into native code on each platform.
Key Top-Level Directories and Files
• src/ – The core TypeScript/JavaScript interface and DownloadTask abstraction.
• android/ – Android native module (Java).
• ios/ – iOS native module (Objective-C, bridging to Swift/Obj-C).
• example/ – A sample React Native app demonstrating how to integrate and use the library.
• __tests__/, __mocks__/ – Jest tests and mocks for the JS layer.
• react-native-background-downloader.podspec, android settings.gradle, build.gradle – Deployment and linking configuration.
Important Architectural Insights from README
• iOS uses a background NSURLSession and delegate callbacks (handleEventsForBackgroundURLSession).
• Android uses DownloadManager and a React Native package (RNBackgroundDownloaderPackage) plus event callbacks.
• The library supports re-attaching to “lost” downloads via checkForExistingDownloads().
Components
a. JavaScript Layer
• Your App (example or any consumer) calls download() → returns a DownloadTask instance.
• DownloadTask methods (begin, progress, done, error) register JS callbacks.
• checkForExistingDownloads(), setConfig(), completeHandler().
b. React Native Bridge
• NativeModules.RNBackgroundDownloader (Android) / RNBackgroundDownloader (iOS).
• Serialization of options and callbacks across the bridge.
c. Native Layer (Android)
• RNBackgroundDownloaderModule & RNBackgroundDownloaderPackage.
• Downloader.java orchestrates DownloadManager requests.
• Handlers: OnBegin, OnProgress; interfaces BeginCallback, ProgressCallback.
• FileUtils for path handling.
d. Native Layer (iOS)
• RNBackgroundDownloader.m/.h.
• NSURLSession with background configuration.
• Delegate methods to re-attach on app launch (application:handleEventsForBackgroundURLSession:).
e. OS-Level Download Services
• Android DownloadManager service.
• iOS NSURLSession background sessions managed by the OS.
f. JS Event Emission
• Events flow back from native → RN EventEmitter → JS callbacks fire.
Relationships and Data Flow
• For “lost tasks”: on app init JS calls checkForExistingDownloads() → Native reads persisted tasks → re-emits events.
Architectural Patterns and Principles
• Separation of Concerns: JS API vs. native implementation vs. OS service.
• Observer/Publisher-Subscriber: callbacks on DownloadTask chain.
• Platform-Abstraction Layer: single API surface while delegating platform specifics to native code.
• Resilience: re-attachment logic for terminated apps.
Technologies and Frameworks
• JavaScript/TypeScript, React Native.
• Android: Java, Gradle, DownloadManager, Project package registration.
• iOS: Objective-C, NSURLSession background configuration, CocoaPods.
• Testing: Jest, React Native mocks.
• Bundler: Metro.
Final Advice
• Full round-trip: from JS call to OS download to JS callback.
• “re-attachment” path on app restart.
• Review the README’s descriptions of iOS vs. Android flows to ensure completeness.