@kesha-antonov/react-native-background-downloader 4.6.0 โ†’ 4.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -20,6 +20,17 @@
20
20
  Download and upload large files on iOS & Android โ€” even when your app is in the background or terminated by the OS.
21
21
  </p>
22
22
 
23
+ <p align="center">
24
+ <strong><a href="https://kesha-antonov.github.io/react-native-background-downloader/">๐Ÿ“– Documentation</a></strong> &nbsp;ยท&nbsp;
25
+ <a href="https://kesha-antonov.github.io/react-native-background-downloader/installation">Installation</a> &nbsp;ยท&nbsp;
26
+ <a href="https://kesha-antonov.github.io/react-native-background-downloader/api">API reference</a> &nbsp;ยท&nbsp;
27
+ <a href="https://kesha-antonov.github.io/react-native-background-downloader/troubleshooting">Troubleshooting</a>
28
+ </p>
29
+
30
+ <p align="center">
31
+ <sub>Using it in production? A โญ helps other developers find the library.</sub>
32
+ </p>
33
+
23
34
  ---
24
35
 
25
36
  ## โœจ Features
@@ -46,10 +57,41 @@
46
57
 
47
58
  **This Library:** `@kesha-antonov/react-native-background-downloader` wraps these native APIs in a simple, unified JavaScript interface. Start a download, close your app, reopen it hours later, and seamlessly reconnect to your ongoing downloads with a single function call.
48
59
 
60
+ ## โš–๏ธ Comparison
61
+
62
+ How this library compares to other file transfer options in the React Native ecosystem:
63
+
64
+ | Capability | **This library** | `expo-file-system` | `react-native-blob-util` | `react-native-fs` |
65
+ |---|:--:|:--:|:--:|:--:|
66
+ | Background downloads on iOS | โœ… | โœ… <sup>1</sup> | โŒ | โœ… <sup>4</sup> |
67
+ | Background downloads on Android | โœ… | โŒ <sup>2</sup> | โš ๏ธ <sup>3</sup> | โŒ |
68
+ | Background uploads | โœ… iOS + Android | โš ๏ธ iOS only | โŒ | โŒ |
69
+ | **Reconnect to transfers after app restart** | โœ… | โŒ <sup>2</sup> | โŒ | โŒ |
70
+ | Pause / resume | โœ… iOS + Android | โš ๏ธ iOS only | โŒ | โš ๏ธ iOS only <sup>5</sup> |
71
+ | Progress events | โœ… | โœ… | โœ… | โœ… |
72
+ | Expo config plugin | โœ… | built in | โŒ | โŒ |
73
+ | New Architecture (TurboModules) | โœ… | โœ… | โœ… | โš ๏ธ via community fork |
74
+ | General filesystem API | โŒ | โœ… | โœ… | โœ… |
75
+
76
+ <sup>1</sup> Via `sessionType: 'background'` (iOS only).
77
+
78
+ <sup>2</sup> From the Expo docs: *"Android accepts this option for API consistency and ignores it"*, and *"the JavaScript `DownloadTask` instance is not restored if the app is terminated or relaunched, so its promise, progress callbacks, and cancellation state are only available while the original JS runtime is still alive."*
79
+
80
+ <sup>3</sup> Via `useDownloadManager: true`, which is `GET`-only and can only write to external storage.
81
+
82
+ <sup>4</sup> Via the `background: true` option (iOS only).
83
+
84
+ <sup>5</sup> Via the `resumable` callback (iOS only).
85
+
86
+ **The key difference is the highlighted row.** Several libraries can hand a transfer to the OS. This is the one that can find those transfers again after your app has been killed and relaunched - [`getExistingDownloadTasks()`](#re-attaching-to-background-tasks) returns live task objects you can re-bind your UI to, on both platforms.
87
+
88
+ **When you probably don't need this library:** if your files are small, or a failed transfer can simply be restarted from zero next time the user opens the app, `expo-file-system` is simpler and already in your project. Reach for this one when a transfer is long enough that losing it costs the user real time.
89
+
49
90
  ## ๐Ÿ“– Table of Contents
50
91
 
51
92
  - [โœจ Features](#-features)
52
93
  - [๐Ÿ’ก Why?](#-why)
94
+ - [โš–๏ธ Comparison](#๏ธ-comparison)
53
95
  - [๐Ÿ“– Table of Contents](#-table-of-contents)
54
96
  - [๐Ÿ“‹ Requirements](#-requirements)
55
97
  - [๐Ÿ“ฆ Installation](#-installation)
@@ -926,7 +968,45 @@ If you're using `react-native-mmkv`, you don't need to add the MMKV dependency m
926
968
  <details>
927
969
  <summary><strong>EXC_BAD_ACCESS crash on iOS with react-native-mmkv</strong></summary>
928
970
 
929
- This was fixed in v4.4.0. Update to the latest version. If you're not using `react-native-mmkv`, add `pod 'MMKV', '>= 1.0.0'` to your Podfile.
971
+ This was fixed in v4.4.0. Update to the latest version. The podspec declares the MMKV dependency itself, so you don't need to add anything to your Podfile. If you do pin it manually, exclude the broken 2.4.1 release (see the entry below):
972
+
973
+ ```ruby
974
+ pod 'MMKV', '>= 1.0.0', '!= 2.4.1'
975
+ ```
976
+ </details>
977
+
978
+ <details>
979
+ <summary><strong>iOS build fails with "use of undeclared identifier 'memset_s'" (MMKVCore)</strong></summary>
980
+
981
+ ```text
982
+ Pods/MMKVCore/Core/aes/AESCrypt.cpp:83:11
983
+ (void)memset_s(ptr, len, 0, len);
984
+ ^ use of undeclared identifier 'memset_s'
985
+ ```
986
+
987
+ This is an upstream bug in **MMKVCore 2.4.1** ([Tencent/MMKV#1675](https://github.com/Tencent/MMKV/issues/1675)) - it does not compile on Apple platforms. Update to the latest version of this library: the podspec now excludes exactly that release, so a fresh `pod install` resolves `MMKVCore 2.4.0` instead.
988
+
989
+ If you are on a version with the fix and still hitting this, your `Podfile.lock` is pinning the broken version. Refresh it:
990
+
991
+ ```bash
992
+ cd ios
993
+ pod update MMKV MMKVCore
994
+ ```
995
+
996
+ If some other pod in your graph forces `MMKVCore 2.4.1` and you cannot move off it, define the missing feature-test macro on the command line (the `#define` inside `AESCrypt.cpp` lands too late because CocoaPods force-includes the generated prefix header first):
997
+
998
+ ```ruby
999
+ # ios/Podfile
1000
+ post_install do |installer|
1001
+ installer.pods_project.targets.each do |target|
1002
+ next unless target.name == 'MMKVCore'
1003
+ target.build_configurations.each do |config|
1004
+ config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= ['$(inherited)']
1005
+ config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] << '__STDC_WANT_LIB_EXT1__=1'
1006
+ end
1007
+ end
1008
+ end
1009
+ ```
930
1010
  </details>
931
1011
 
932
1012
  <details>
@@ -1,5 +1,11 @@
1
1
  apply plugin: 'com.android.library'
2
- apply plugin: 'kotlin-android'
2
+ // AGP 9 ships built-in Kotlin support and registers the `kotlin` extension
3
+ // itself. Applying the Kotlin plugin on top of it fails configuration with
4
+ // "Cannot add extension with name 'kotlin'". Only apply it when nothing has
5
+ // registered that extension yet.
6
+ if (project.extensions.findByName('kotlin') == null) {
7
+ apply plugin: 'kotlin-android'
8
+ }
3
9
 
4
10
  def isNewArchitectureEnabled() {
5
11
  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
package/package.json CHANGED
@@ -1,18 +1,43 @@
1
1
  {
2
2
  "name": "@kesha-antonov/react-native-background-downloader",
3
- "version": "4.6.0",
4
- "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.",
3
+ "version": "4.6.2",
4
+ "description": "Background file downloads and uploads for React Native and Expo. Large files keep transferring on iOS and Android while your app is in the background or terminated. Pause/resume, progress events, TurboModules, TypeScript.",
5
5
  "keywords": [
6
6
  "react-native",
7
+ "expo",
8
+ "expo-plugin",
7
9
  "background",
10
+ "background-download",
11
+ "background-upload",
8
12
  "download",
9
- "large files"
13
+ "downloader",
14
+ "upload",
15
+ "uploader",
16
+ "file-download",
17
+ "file-upload",
18
+ "file-transfer",
19
+ "large-files",
20
+ "resumable",
21
+ "resumable-download",
22
+ "pause-resume",
23
+ "progress",
24
+ "ios",
25
+ "android",
26
+ "nsurlsession",
27
+ "urlsession",
28
+ "downloadmanager",
29
+ "foreground-service",
30
+ "turbomodule",
31
+ "new-architecture",
32
+ "typescript",
33
+ "offline",
34
+ "offline-first"
10
35
  ],
11
36
  "repository": {
12
37
  "type": "git",
13
38
  "url": "git+https://github.com/kesha-antonov/react-native-background-downloader.git"
14
39
  },
15
- "homepage": "https://github.com/kesha-antonov/react-native-background-downloader",
40
+ "homepage": "https://kesha-antonov.github.io/react-native-background-downloader/",
16
41
  "license": "Apache-2.0",
17
42
  "author": {
18
43
  "name": "Kesha Antonov, Eko labs",
@@ -27,7 +27,20 @@ Pod::Spec.new do |s|
27
27
  # resolve a newer MMKV when another pod (e.g. react-native-mmkv, which pins an
28
28
  # exact MMKVCore) requires one - we just don't impose our own higher floor.
29
29
  # See https://github.com/kesha-antonov/react-native-background-downloader/issues/162
30
- s.dependency 'MMKV', '>= 1.2.0'
30
+ #
31
+ # 2.4.1 is excluded: MMKVCore 2.4.1 fails to compile on Apple platforms with
32
+ # "use of undeclared identifier 'memset_s'" in Core/aes/AESCrypt.cpp. It defines
33
+ # __STDC_WANT_LIB_EXT1__ at the top of the .cpp, but CocoaPods force-includes the
34
+ # generated prefix header (-include ...-prefix.pch) first, so <string.h> is already
35
+ # parsed by then and Darwin never declares memset_s. Only that single release is
36
+ # blocked, so a fixed 2.4.2+ will be picked up without another release here.
37
+ # See https://github.com/Tencent/MMKV/issues/1675
38
+ # and https://github.com/kesha-antonov/react-native-background-downloader/issues/175
39
+ s.dependency 'MMKV', '>= 1.2.0', '!= 2.4.1'
40
+ # MMKVCore must be excluded explicitly as well: the broken source file lives in
41
+ # MMKVCore, and MMKV 2.4.0 depends on 'MMKVCore (~> 2.4.0)', which would still
42
+ # resolve to the broken 2.4.1 on its own.
43
+ s.dependency 'MMKVCore', '!= 2.4.1'
31
44
 
32
45
  # Enable codegen for new architecture
33
46
  if ENV['RCT_NEW_ARCH_ENABLED'] == '1'