react-native-cloud-sync 0.3.0 → 0.5.0
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 +116 -58
- package/ios/CloudSyncError.swift +21 -0
- package/ios/CloudSyncImpl.swift +515 -95
- package/ios/RNCloudSync.mm +73 -1
- package/jest-mock.js +1 -0
- package/lib/commonjs/hooks.js +309 -3
- package/lib/commonjs/hooks.js.map +1 -1
- package/lib/commonjs/internal/autoFlush.js +10 -1
- package/lib/commonjs/internal/autoFlush.js.map +1 -1
- package/lib/commonjs/internal/base64.js +25 -5
- package/lib/commonjs/internal/base64.js.map +1 -1
- package/lib/commonjs/internal/cloudKitRest.js +91 -15
- package/lib/commonjs/internal/cloudKitRest.js.map +1 -1
- package/lib/commonjs/internal/googleDriveRest.js +304 -38
- package/lib/commonjs/internal/googleDriveRest.js.map +1 -1
- package/lib/commonjs/internal/keys.js +34 -17
- package/lib/commonjs/internal/keys.js.map +1 -1
- package/lib/commonjs/internal/records.js +48 -0
- package/lib/commonjs/internal/records.js.map +1 -0
- package/lib/commonjs/providers/cloudKit.js +85 -17
- package/lib/commonjs/providers/cloudKit.js.map +1 -1
- package/lib/commonjs/providers/cloudKitEncrypted.js +30 -7
- package/lib/commonjs/providers/cloudKitEncrypted.js.map +1 -1
- package/lib/commonjs/providers/googleDrive.js +37 -2
- package/lib/commonjs/providers/googleDrive.js.map +1 -1
- package/lib/commonjs/providers/icloudDocuments.js +27 -0
- package/lib/commonjs/providers/icloudDocuments.js.map +1 -1
- package/lib/commonjs/providers/icloudKV.js +13 -3
- package/lib/commonjs/providers/icloudKV.js.map +1 -1
- package/lib/commonjs/providers/icloudKV.web.js +8 -1
- package/lib/commonjs/providers/icloudKV.web.js.map +1 -1
- package/lib/commonjs/providers/memory.js +10 -0
- package/lib/commonjs/providers/memory.js.map +1 -1
- package/lib/commonjs/resolvers.js +27 -13
- package/lib/commonjs/resolvers.js.map +1 -1
- package/lib/commonjs/specs/NativeRNCloudSync.js +3 -0
- package/lib/commonjs/specs/NativeRNCloudSync.js.map +1 -1
- package/lib/commonjs/store.js +360 -173
- package/lib/commonjs/store.js.map +1 -1
- package/lib/commonjs/types.js.map +1 -1
- package/lib/module/hooks.js +307 -3
- package/lib/module/hooks.js.map +1 -1
- package/lib/module/index.js +2 -2
- package/lib/module/internal/autoFlush.js +10 -1
- package/lib/module/internal/autoFlush.js.map +1 -1
- package/lib/module/internal/base64.js +25 -5
- package/lib/module/internal/base64.js.map +1 -1
- package/lib/module/internal/cloudKitRest.js +89 -13
- package/lib/module/internal/cloudKitRest.js.map +1 -1
- package/lib/module/internal/googleDriveRest.js +304 -38
- package/lib/module/internal/googleDriveRest.js.map +1 -1
- package/lib/module/internal/keys.js +33 -17
- package/lib/module/internal/keys.js.map +1 -1
- package/lib/module/internal/records.js +41 -0
- package/lib/module/internal/records.js.map +1 -0
- package/lib/module/providers/cloudKit.js +86 -18
- package/lib/module/providers/cloudKit.js.map +1 -1
- package/lib/module/providers/cloudKitEncrypted.js +31 -8
- package/lib/module/providers/cloudKitEncrypted.js.map +1 -1
- package/lib/module/providers/googleDrive.js +37 -2
- package/lib/module/providers/googleDrive.js.map +1 -1
- package/lib/module/providers/icloudDocuments.js +28 -1
- package/lib/module/providers/icloudDocuments.js.map +1 -1
- package/lib/module/providers/icloudKV.js +13 -3
- package/lib/module/providers/icloudKV.js.map +1 -1
- package/lib/module/providers/icloudKV.web.js +8 -1
- package/lib/module/providers/icloudKV.web.js.map +1 -1
- package/lib/module/providers/memory.js +10 -0
- package/lib/module/providers/memory.js.map +1 -1
- package/lib/module/resolvers.js +27 -12
- package/lib/module/resolvers.js.map +1 -1
- package/lib/module/specs/NativeRNCloudSync.js +4 -0
- package/lib/module/specs/NativeRNCloudSync.js.map +1 -1
- package/lib/module/store.js +360 -173
- package/lib/module/store.js.map +1 -1
- package/lib/module/types.js.map +1 -1
- package/lib/typescript/commonjs/errors.d.ts +16 -16
- package/lib/typescript/commonjs/errors.d.ts.map +1 -1
- package/lib/typescript/commonjs/hooks.d.ts +68 -0
- package/lib/typescript/commonjs/hooks.d.ts.map +1 -1
- package/lib/typescript/commonjs/index.d.ts +2 -2
- package/lib/typescript/commonjs/internal/autoFlush.d.ts.map +1 -1
- package/lib/typescript/commonjs/internal/base64.d.ts.map +1 -1
- package/lib/typescript/commonjs/internal/cloudKitRest.d.ts +20 -0
- package/lib/typescript/commonjs/internal/cloudKitRest.d.ts.map +1 -1
- package/lib/typescript/commonjs/internal/googleDriveRest.d.ts +19 -0
- package/lib/typescript/commonjs/internal/googleDriveRest.d.ts.map +1 -1
- package/lib/typescript/commonjs/internal/keys.d.ts +18 -3
- package/lib/typescript/commonjs/internal/keys.d.ts.map +1 -1
- package/lib/typescript/commonjs/internal/records.d.ts +24 -0
- package/lib/typescript/commonjs/internal/records.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/cloudKit.d.ts +1 -1
- package/lib/typescript/commonjs/providers/cloudKit.d.ts.map +1 -1
- package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts +1 -1
- package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts.map +1 -1
- package/lib/typescript/commonjs/providers/cloudKitEncrypted.d.ts.map +1 -1
- package/lib/typescript/commonjs/providers/googleDrive.d.ts.map +1 -1
- package/lib/typescript/commonjs/providers/googleDriveFiles.d.ts.map +1 -1
- package/lib/typescript/commonjs/providers/icloudDocuments.d.ts +1 -1
- package/lib/typescript/commonjs/providers/icloudDocuments.d.ts.map +1 -1
- package/lib/typescript/commonjs/providers/icloudKV.d.ts.map +1 -1
- package/lib/typescript/commonjs/providers/icloudKV.web.d.ts.map +1 -1
- package/lib/typescript/commonjs/providers/memory.d.ts.map +1 -1
- package/lib/typescript/commonjs/resolvers.d.ts +6 -3
- package/lib/typescript/commonjs/resolvers.d.ts.map +1 -1
- package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts +12 -3
- package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts.map +1 -1
- package/lib/typescript/commonjs/store.d.ts.map +1 -1
- package/lib/typescript/commonjs/types.d.ts +31 -3
- package/lib/typescript/commonjs/types.d.ts.map +1 -1
- package/lib/typescript/module/errors.d.ts +16 -16
- package/lib/typescript/module/errors.d.ts.map +1 -1
- package/lib/typescript/module/hooks.d.ts +68 -0
- package/lib/typescript/module/hooks.d.ts.map +1 -1
- package/lib/typescript/module/index.d.ts +2 -2
- package/lib/typescript/module/internal/autoFlush.d.ts.map +1 -1
- package/lib/typescript/module/internal/base64.d.ts.map +1 -1
- package/lib/typescript/module/internal/cloudKitRest.d.ts +20 -0
- package/lib/typescript/module/internal/cloudKitRest.d.ts.map +1 -1
- package/lib/typescript/module/internal/googleDriveRest.d.ts +19 -0
- package/lib/typescript/module/internal/googleDriveRest.d.ts.map +1 -1
- package/lib/typescript/module/internal/keys.d.ts +18 -3
- package/lib/typescript/module/internal/keys.d.ts.map +1 -1
- package/lib/typescript/module/internal/records.d.ts +24 -0
- package/lib/typescript/module/internal/records.d.ts.map +1 -0
- package/lib/typescript/module/providers/cloudKit.d.ts +1 -1
- package/lib/typescript/module/providers/cloudKit.d.ts.map +1 -1
- package/lib/typescript/module/providers/cloudKitBackup.d.ts +1 -1
- package/lib/typescript/module/providers/cloudKitBackup.d.ts.map +1 -1
- package/lib/typescript/module/providers/cloudKitEncrypted.d.ts.map +1 -1
- package/lib/typescript/module/providers/googleDrive.d.ts.map +1 -1
- package/lib/typescript/module/providers/googleDriveFiles.d.ts.map +1 -1
- package/lib/typescript/module/providers/icloudDocuments.d.ts +1 -1
- package/lib/typescript/module/providers/icloudDocuments.d.ts.map +1 -1
- package/lib/typescript/module/providers/icloudKV.d.ts.map +1 -1
- package/lib/typescript/module/providers/icloudKV.web.d.ts.map +1 -1
- package/lib/typescript/module/providers/memory.d.ts.map +1 -1
- package/lib/typescript/module/resolvers.d.ts +6 -3
- package/lib/typescript/module/resolvers.d.ts.map +1 -1
- package/lib/typescript/module/specs/NativeRNCloudSync.d.ts +12 -3
- package/lib/typescript/module/specs/NativeRNCloudSync.d.ts.map +1 -1
- package/lib/typescript/module/store.d.ts.map +1 -1
- package/lib/typescript/module/types.d.ts +31 -3
- package/lib/typescript/module/types.d.ts.map +1 -1
- package/package.json +36 -23
- package/plugin/build/index.js +45 -13
- package/react-native-cloud-sync.podspec +10 -3
- package/src/hooks.ts +357 -3
- package/src/index.ts +2 -2
- package/src/internal/autoFlush.ts +10 -1
- package/src/internal/base64.ts +26 -5
- package/src/internal/cloudKitRest.ts +103 -14
- package/src/internal/googleDriveRest.ts +338 -37
- package/src/internal/keys.ts +42 -16
- package/src/internal/records.ts +38 -0
- package/src/providers/cloudKit.ts +96 -20
- package/src/providers/cloudKitEncrypted.ts +37 -8
- package/src/providers/googleDrive.ts +38 -2
- package/src/providers/icloudDocuments.ts +40 -2
- package/src/providers/icloudKV.ts +13 -3
- package/src/providers/icloudKV.web.ts +8 -2
- package/src/providers/memory.ts +8 -0
- package/src/resolvers.ts +28 -13
- package/src/specs/NativeRNCloudSync.ts +16 -2
- package/src/store.ts +433 -190
- package/src/types.ts +32 -3
package/README.md
CHANGED
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
<h1 align="center">react-native-cloud-sync</h1>
|
|
14
14
|
|
|
15
15
|
<p align="center">
|
|
16
|
-
iCloud key-value store, CloudKit and Google Drive behind one API - iOS, Android, web, both architectures.
|
|
16
|
+
iCloud key-value store, CloudKit, iCloud Drive and Google Drive behind one API - iOS, Android, web, both architectures.
|
|
17
17
|
</p>
|
|
18
18
|
|
|
19
19
|
<p align="center">
|
|
@@ -23,35 +23,91 @@
|
|
|
23
23
|
<a href="https://kesha-antonov.github.io/react-native-cloud-sync/platform-notes">Platform Notes</a>
|
|
24
24
|
</p>
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
<p align="center">
|
|
27
|
+
<img src="assets/sync-demo.gif" width="760" alt="A book saved on an iPhone syncs through iCloud to an iPad and a Mac and through Google Drive to an Android phone and the web, then un-saved on Android it syncs back everywhere" />
|
|
28
|
+
</p>
|
|
29
|
+
|
|
30
|
+
<p align="center">
|
|
31
|
+
<sub>Using it in production? A ⭐ helps other developers find the library.</sub>
|
|
32
|
+
</p>
|
|
33
|
+
|
|
34
|
+
<!-- cryptoc-promo:start -->
|
|
35
|
+
<hr />
|
|
36
|
+
|
|
37
|
+
<h2 align="center">Sponsors</h2>
|
|
38
|
+
|
|
39
|
+
<p align="center">
|
|
40
|
+
<a href="https://getstream.io/chat/sdk/react-native/?utm_source=github&utm_medium=sponsor&utm_campaign=keshaantonov&utm_term=react-native-cloud-sync"><img width="100" height="100" src="https://raw.githubusercontent.com/kesha-antonov/react-native-chat/main/media/getstream-sponsor-logo.png" alt="Stream" /></a>
|
|
41
|
+
<br />
|
|
42
|
+
<a href="https://getstream.io/chat/sdk/react-native/?utm_source=github&utm_medium=sponsor&utm_campaign=keshaantonov&utm_term=react-native-cloud-sync"><strong>Stream</strong></a> - React Native Chat SDK
|
|
43
|
+
</p>
|
|
44
|
+
|
|
45
|
+
<hr />
|
|
46
|
+
|
|
47
|
+
<table align="center">
|
|
48
|
+
<tr>
|
|
49
|
+
<td align="center" valign="top" width="190">
|
|
50
|
+
<a href="https://cryptoc-app.web.app/"><img src="https://cryptoc-app.web.app/img/icon.png?v=3" width="76" height="76" alt="cryptoc app icon" /></a>
|
|
51
|
+
<br /><br />
|
|
52
|
+
<img src="https://cryptoc-app.web.app/img/qr-get.png?v=2" width="124" height="124" alt="QR code that installs cryptoc" />
|
|
53
|
+
<br />
|
|
54
|
+
<sub>Scan to install</sub>
|
|
55
|
+
<br /><br />
|
|
56
|
+
<!-- App Store button hidden for now
|
|
57
|
+
<a href="https://apps.apple.com/app/cryptoc/id1333169178"><img height="40" src="https://cryptoc-app.web.app/img/appstore.svg?v=2" alt="Download on the App Store" /></a>
|
|
58
|
+
<br />
|
|
59
|
+
-->
|
|
60
|
+
<a href="https://play.google.com/store/apps/details?id=co.ssoul.CryptoC"><img height="59" src="https://cryptoc-app.web.app/img/googleplay.png?v=2" alt="Get it on Google Play" /></a>
|
|
61
|
+
</td>
|
|
62
|
+
<td valign="top">
|
|
63
|
+
|
|
64
|
+
### Support my work
|
|
65
|
+
|
|
66
|
+
**[cryptoc](https://cryptoc-app.web.app/)** - my crypto portfolio app. Your coins on the home screen, lock screen and watch face. iPhone, iPad, Mac, Apple Watch, Android, Android tablet and Wear OS.
|
|
67
|
+
|
|
68
|
+
- Portfolio with average buy price and 24h / 180-day / all-time P&L
|
|
69
|
+
- Widgets in three sizes, refreshed in the background - most days you never open the app
|
|
70
|
+
- Price alerts on 5,000+ coins, delivered while the app is closed
|
|
71
|
+
- **No account, no email, no exchange API keys, no ads.** Your holdings never reach a server - they sync through your own iCloud or Google Drive
|
|
72
|
+
- Free for 3 holdings, and that is not a trial timer
|
|
73
|
+
|
|
74
|
+
<sub>This is the app the library was built for. Downloading it pays for the time that goes into maintaining it.</sub>
|
|
75
|
+
|
|
76
|
+
</td>
|
|
77
|
+
</tr>
|
|
78
|
+
</table>
|
|
79
|
+
|
|
80
|
+
<hr />
|
|
81
|
+
<!-- cryptoc-promo:end -->
|
|
27
82
|
|
|
28
83
|
## ✨ Features
|
|
29
84
|
|
|
30
|
-
- ☁️ Four providers behind one API
|
|
31
|
-
-
|
|
32
|
-
-
|
|
85
|
+
- ☁️ Four providers behind one API: [`NSUbiquitousKeyValueStore`][kvs] (Apple's small key-value iCloud store), [CloudKit][ck] records, [iCloud Drive][icdrive] documents and Google Drive [`appDataFolder`][appdata]. Use them directly or through one facade.
|
|
86
|
+
- 🔄 Auto-sync between iOS and Android in **both directions**: `mirror` writes to iCloud and Drive together, `resolve` reads back whichever copy is newest, so either platform can be where the user started.
|
|
87
|
+
- 🍏 CloudKit reaches Android and web too, via [CloudKit Web Services][ckws], against the same [private database][ckdb] your iOS app uses.
|
|
88
|
+
- 📂 `icloudDocuments` writes into the user's own iCloud Drive, so the files show up in Files.app.
|
|
33
89
|
- 🚨 Every failure is a typed rejection (`ERR_NOT_SIGNED_IN`, `ERR_QUOTA_EXCEEDED`, `ERR_RATE_LIMITED` with `retryAfterMs`, ...); `null` means only "key doesn't exist".
|
|
34
90
|
- 👤 All five [`CKAccountStatus`][ckstatus] values surface as-is, plus `onAccountChange` with `identityChanged`, which drops the previous account's caches and queued writes.
|
|
35
91
|
- 🔔 `onRemoteChange` fires on every provider and the facade, including Google Drive via its change cursor.
|
|
36
|
-
- 📦 Small values go to the key-value store, larger ones to a [`CKRecord`][ckrecord] field, binary
|
|
92
|
+
- 📦 Small values go to the key-value store, larger ones to a [`CKRecord`][ckrecord] field, binary to a [`CKAsset`][ckasset] or a resumable Drive upload. The size check picks the target.
|
|
37
93
|
- 🔁 Retryable failures queue into a durable outbox: backoff honours retry hints, auto-drains on foreground, bounded, never overwrites a newer write.
|
|
38
94
|
- 🧺 `multiGet`/`multiSet`/`multiRemove`/`clear` batch for real, one request per provider.
|
|
39
|
-
- 🪝 React hooks
|
|
40
|
-
- 🔐 `cloudKitEncrypted` uses CloudKit's own `encryptedValues
|
|
41
|
-
- 🧪 An in-memory provider with fault injection, plus the native mock, both exported (`/testing`, `/jest-mock`)
|
|
42
|
-
- ⚙️ React Native 0.71 through 0.86+, old and new architecture, with the `#ifdef` bridge
|
|
95
|
+
- 🪝 React hooks from `/hooks`: `useCloudItem`, `useCloudItems`, `useCloudCollection`, `useAccountStatus`, `usePendingWrites`. They drop stale responses and never `setState` after unmount.
|
|
96
|
+
- 🔐 `cloudKitEncrypted` uses CloudKit's own `encryptedValues`, so only ciphertext leaves the device; every other provider has a `codec` seam for your own cipher.
|
|
97
|
+
- 🧪 An in-memory provider with fault injection, plus the native mock, both exported (`/testing`, `/jest-mock`), so every failure path is testable in Jest.
|
|
98
|
+
- ⚙️ React Native 0.71 through 0.86+, old and new architecture, with the `#ifdef` bridge for the legacy one.
|
|
43
99
|
|
|
44
100
|
## 💡 Why?
|
|
45
101
|
|
|
46
102
|
Cloud storage in React Native is fragmented into single-provider wrappers repeating the same defects: two ship a `setItem` that **reports a failed write as a success** (one checks the wrong error variable, the other discards the result entirely), and a third flattens five iCloud account states into one boolean.
|
|
47
103
|
|
|
48
|
-
A `catch { return null }` makes "not signed in", "offline", "out of storage" and "no such key" indistinguishable
|
|
104
|
+
A `catch { return null }` makes "not signed in", "offline", "out of storage" and "no such key" indistinguishable. The app can't tell the user anything useful, or decide whether to retry.
|
|
49
105
|
|
|
50
|
-
This library
|
|
106
|
+
This library was built error contract first, providers second.
|
|
51
107
|
|
|
52
108
|
## 📚 Upstream documentation
|
|
53
109
|
|
|
54
|
-
This package is a wrapper
|
|
110
|
+
This package is a wrapper. When something behaves unexpectedly, the answer is usually in Apple's or Google's docs.
|
|
55
111
|
|
|
56
112
|
**Apple**
|
|
57
113
|
|
|
@@ -72,7 +128,7 @@ This package is a wrapper: unexpected behavior is usually explained in Apple's o
|
|
|
72
128
|
|---|---|
|
|
73
129
|
| [The `appDataFolder`][appdata] | The hidden per-app folder this package stores into |
|
|
74
130
|
| [Drive `files` resource][drivefiles] | The REST endpoints behind the provider |
|
|
75
|
-
| [Drive API scopes][drivescopes] | Why `drive.appdata
|
|
131
|
+
| [Drive API scopes][drivescopes] | Why the scope is `drive.appdata` |
|
|
76
132
|
|
|
77
133
|
[kvs]: https://developer.apple.com/documentation/foundation/nsubiquitouskeyvaluestore
|
|
78
134
|
[ck]: https://developer.apple.com/documentation/cloudkit
|
|
@@ -96,40 +152,40 @@ This package is a wrapper: unexpected behavior is usually explained in Apple's o
|
|
|
96
152
|
|
|
97
153
|
| | **this** | [kuatsu/<br />cloud-storage][kuatsu] | [icloud-kit][ik] | [expo-cloudkit][ec] | [okwasniewski/<br />icloud-storage][ok] | [cloudkit-<br />storage][jp] |
|
|
98
154
|
|---|:---:|:---:|:---:|:---:|:---:|:---:|
|
|
99
|
-
| iCloud key-value store | ✅ | ✅ | ✅ |
|
|
100
|
-
| CloudKit records | ✅ |
|
|
101
|
-
| Google Drive | ✅ | ✅ |
|
|
155
|
+
| iCloud key-value store | ✅ | ✅ | ✅ | - | ✅ | - |
|
|
156
|
+
| CloudKit records | ✅ | - | ✅ | ✅ | - | ✅ |
|
|
157
|
+
| Google Drive | ✅ | ✅ | - | - | - | - |
|
|
102
158
|
| iOS | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
103
|
-
| Android | ✅ | ✅ |
|
|
104
|
-
| Web | ✅ | partial [[2]](#note-2) |
|
|
105
|
-
| **CloudKit on Android/web** | ✅ |
|
|
106
|
-
| New Architecture | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
159
|
+
| Android | ✅ | ✅ | - | ❌ [[1]](#note-1) | - | - |
|
|
160
|
+
| Web | ✅ | partial [[2]](#note-2) | - | - | - | - |
|
|
161
|
+
| **CloudKit on Android/web** | ✅ | - | - | ❌ [[1]](#note-1) | - | - |
|
|
162
|
+
| New Architecture | ✅ | ✅ | ✅ | ✅ | ✅ | - |
|
|
107
163
|
| **Legacy Architecture** | ✅ | ❌ | ✅ [[3]](#note-3) | ✅ [[3]](#note-3) | ✅ [[3]](#note-3) | ✅ |
|
|
108
|
-
| Typed error codes | ✅ |
|
|
109
|
-
| 5-value account status | ✅ | boolean | boolean | ✅ |
|
|
110
|
-
| Identity-change event | ✅ | ⚠️ [[4]](#note-4) |
|
|
111
|
-
| Remote-change event | ✅ | ✅ |
|
|
112
|
-
| Offline write queue | ✅ |
|
|
113
|
-
| Size tiering | ✅ |
|
|
114
|
-
| Binary / assets | ✅ [[9]](#note-9) | ✅ | ❌ [[6]](#note-6) | ✅ |
|
|
115
|
-
| User-visible iCloud Drive files | ✅ |
|
|
116
|
-
| Native end-to-end encryption | ✅ |
|
|
117
|
-
| Batch operations | ✅ |
|
|
118
|
-
| React hooks | ✅ | ✅ |
|
|
119
|
-
| Encryption seam | ✅ |
|
|
120
|
-
| Exported test harness | ✅ |
|
|
121
|
-
| Mac Catalyst | ✅ |
|
|
164
|
+
| Typed error codes | ✅ | - | partial | ✅ | - | - |
|
|
165
|
+
| 5-value account status | ✅ | boolean | boolean | ✅ | - | - |
|
|
166
|
+
| Identity-change event | ✅ | ⚠️ [[4]](#note-4) | - | ✅ | - | - |
|
|
167
|
+
| Remote-change event | ✅ | ✅ | - | n/a | ❌ [[5]](#note-5) | ✅ |
|
|
168
|
+
| Offline write queue | ✅ | - | - | ✅ | - | - |
|
|
169
|
+
| Size tiering | ✅ | - | - | - | - | - |
|
|
170
|
+
| Binary / assets | ✅ [[9]](#note-9) | ✅ | ❌ [[6]](#note-6) | ✅ | - | - |
|
|
171
|
+
| User-visible iCloud Drive files | ✅ | - | - | - | ✅ | - |
|
|
172
|
+
| Native end-to-end encryption | ✅ | - | - | - | - | - |
|
|
173
|
+
| Batch operations | ✅ | - | - | - | - | - |
|
|
174
|
+
| React hooks | ✅ | ✅ | - | - | - | - |
|
|
175
|
+
| Encryption seam | ✅ | - | - | - | - | - |
|
|
176
|
+
| Exported test harness | ✅ | - | - | ⚠️ [[7]](#note-7) | - | - |
|
|
177
|
+
| Mac Catalyst | ✅ | - | - | ⚠️ | - | - |
|
|
122
178
|
| Actively maintained | ✅ | ✅ | ✅ | ❌ [[8]](#note-8) | ❌ [[5]](#note-5) | ❌ |
|
|
123
179
|
|
|
124
180
|
<a id="note-1"></a>**[1]** expo-cloudkit's README: Android throws `CloudKitNotSupportedError` on every call.
|
|
125
181
|
<a id="note-2"></a>**[2]** Google Drive support is text-based only.
|
|
126
|
-
<a id="note-3"></a>**[3]** Via the Expo Modules API
|
|
127
|
-
<a id="note-4"></a>**[4]** Fires before JS binds the emitter, crashing with `std::bad_function_call` (SIGABRT)
|
|
182
|
+
<a id="note-3"></a>**[3]** Via the Expo Modules API; pulls in `expo-modules-core`.
|
|
183
|
+
<a id="note-4"></a>**[4]** Fires before JS binds the emitter, crashing with `std::bad_function_call` (SIGABRT); hit three times.
|
|
128
184
|
<a id="note-5"></a>**[5]** One version ever shipped; the change-listener PR has sat open since February.
|
|
129
|
-
<a id="note-6"></a>**[6]** Field type is `string | number | null
|
|
185
|
+
<a id="note-6"></a>**[6]** Field type is `string | number | null`, so it can't hold binary data.
|
|
130
186
|
<a id="note-7"></a>**[7]** A mock factory exists, but isn't exported or documented.
|
|
131
187
|
<a id="note-8"></a>**[8]** No commits since April; the last four releases shipped with Swift that didn't compile.
|
|
132
|
-
<a id="note-9"></a>**[9]** `CKAsset` on Apple platforms; CloudKit Web Services' upload-token protocol on Android/web, capped at 15 MB
|
|
188
|
+
<a id="note-9"></a>**[9]** `CKAsset` on Apple platforms; CloudKit Web Services' upload-token protocol on Android/web, capped at 15 MB by CloudKit. Use [`googleDriveFiles`](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive#large-files) for anything bigger; it chunks and resumes the same way.
|
|
133
189
|
|
|
134
190
|
[kuatsu]: https://github.com/kuatsu/react-native-cloud-storage
|
|
135
191
|
[ik]: https://github.com/BogdanGeorgian91/react-native-icloud-kit
|
|
@@ -143,7 +199,7 @@ This package is a wrapper: unexpected behavior is usually explained in Apple's o
|
|
|
143
199
|
|---|---|
|
|
144
200
|
| [Choosing a provider](https://kesha-antonov.github.io/react-native-cloud-sync/choosing-a-provider) | Which one, what it costs, why to let the user pick |
|
|
145
201
|
| [iCloud key-value store](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-kv) | Small settings, zero friction, Apple only |
|
|
146
|
-
| [CloudKit](https://kesha-antonov.github.io/react-native-cloud-sync/providers/cloudkit) | Records, zones, assets
|
|
202
|
+
| [CloudKit](https://kesha-antonov.github.io/react-native-cloud-sync/providers/cloudkit) | Records, zones, assets, and the Android/web path |
|
|
147
203
|
| [iCloud Drive](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-drive) | Files in the user's own Drive, visible in Files.app |
|
|
148
204
|
| [Google Drive](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive) | The always-on cross-platform backend |
|
|
149
205
|
| [The store facade](https://kesha-antonov.github.io/react-native-cloud-sync/store) | Tiering, outbox, migration, fallthrough |
|
|
@@ -170,13 +226,13 @@ Both architectures supported; RN 0.82 removed Legacy Architecture, so that half
|
|
|
170
226
|
|
|
171
227
|
| | iOS / macOS | Android | Web |
|
|
172
228
|
|---|:---:|:---:|:---:|
|
|
173
|
-
| `icloudKV` | native |
|
|
229
|
+
| `icloudKV` | native | - | - |
|
|
174
230
|
| `cloudKit` | native | REST | REST |
|
|
175
|
-
| `cloudKitEncrypted` | native |
|
|
176
|
-
| `icloudDocuments` | native |
|
|
231
|
+
| `cloudKitEncrypted` | native | - | - |
|
|
232
|
+
| `icloudDocuments` | native | - | - |
|
|
177
233
|
| `googleDrive` | REST | REST | REST |
|
|
178
234
|
|
|
179
|
-
An unavailable provider rejects with `ERR_UNSUPPORTED_PLATFORM`
|
|
235
|
+
An unavailable provider rejects with `ERR_UNSUPPORTED_PLATFORM` instead of silently doing nothing. [Choosing a provider](https://kesha-antonov.github.io/react-native-cloud-sync/choosing-a-provider) covers the trade-offs.
|
|
180
236
|
|
|
181
237
|
## 📦 Installation
|
|
182
238
|
|
|
@@ -204,7 +260,7 @@ Bare React Native and manual `ios/` entitlement keys: see [Installation](https:/
|
|
|
204
260
|
|
|
205
261
|
### iCloud key-value store
|
|
206
262
|
|
|
207
|
-
No sign-in
|
|
263
|
+
No sign-in and no UI; it uses the device's existing account.
|
|
208
264
|
|
|
209
265
|
```ts
|
|
210
266
|
import { icloudKV } from 'react-native-cloud-sync'
|
|
@@ -216,7 +272,7 @@ const theme = await icloudKV.getItem('settings/theme')
|
|
|
216
272
|
icloudKV.onRemoteChange(({ keys }) => reload(keys))
|
|
217
273
|
```
|
|
218
274
|
|
|
219
|
-
[Full guide
|
|
275
|
+
[Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-kv)
|
|
220
276
|
|
|
221
277
|
### CloudKit
|
|
222
278
|
|
|
@@ -232,11 +288,11 @@ const raw = await cloudKit.getItem('playlist')
|
|
|
232
288
|
await cloudKitAssets.save({ recordName: 'avatar', fieldName: 'image', fileUri })
|
|
233
289
|
```
|
|
234
290
|
|
|
235
|
-
Android/web needs an Apple ID sign-in
|
|
291
|
+
Android/web needs an Apple ID sign-in, and that token lasts up to two weeks, which suits an explicit import rather than background sync. [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/cloudkit)
|
|
236
292
|
|
|
237
293
|
### Sensitive data
|
|
238
294
|
|
|
239
|
-
CloudKit's own end-to-end encryption
|
|
295
|
+
CloudKit's own end-to-end encryption: Apple stores ciphertext and holds no key.
|
|
240
296
|
|
|
241
297
|
```ts
|
|
242
298
|
import { cloudKitEncrypted } from 'react-native-cloud-sync'
|
|
@@ -244,11 +300,11 @@ import { cloudKitEncrypted } from 'react-native-cloud-sync'
|
|
|
244
300
|
await cloudKitEncrypted.setItem('auth.refreshToken', token)
|
|
245
301
|
```
|
|
246
302
|
|
|
247
|
-
Apple-only: the key lives in the user's iCloud Keychain, so nothing server-side can decrypt it. Cross-platform needs the store's `codec` seam instead. [Full guide
|
|
303
|
+
Apple-only: the key lives in the user's iCloud Keychain, so nothing server-side can decrypt it. Cross-platform needs the store's `codec` seam instead. [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/encryption)
|
|
248
304
|
|
|
249
305
|
### iCloud Drive
|
|
250
306
|
|
|
251
|
-
Files the user can open in Files.app
|
|
307
|
+
Files the user can open in Files.app.
|
|
252
308
|
|
|
253
309
|
```ts
|
|
254
310
|
import { icloudDocuments } from 'react-native-cloud-sync'
|
|
@@ -259,7 +315,7 @@ await icloudDocuments.save({ fileUri: localPath, name: 'Export 2024.csv' })
|
|
|
259
315
|
const path = await icloudDocuments.fetch({ name: 'Export 2024.csv' })
|
|
260
316
|
```
|
|
261
317
|
|
|
262
|
-
[Full guide
|
|
318
|
+
[Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-drive)
|
|
263
319
|
|
|
264
320
|
### Google Drive
|
|
265
321
|
|
|
@@ -275,7 +331,7 @@ configureGoogleDrive({
|
|
|
275
331
|
await googleDrive.setItem('playlist.json', JSON.stringify(tracks))
|
|
276
332
|
```
|
|
277
333
|
|
|
278
|
-
[Full guide
|
|
334
|
+
[Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive)
|
|
279
335
|
|
|
280
336
|
### All of them at once
|
|
281
337
|
|
|
@@ -284,8 +340,8 @@ import { createCloudStore } from 'react-native-cloud-sync'
|
|
|
284
340
|
|
|
285
341
|
const store = createCloudStore({
|
|
286
342
|
providers: ['icloudKV', 'googleDrive'], // preference order
|
|
287
|
-
writeMode: 'mirror', // write to
|
|
288
|
-
resolve: resolveByTimestamp('updatedAt'), // read
|
|
343
|
+
writeMode: 'mirror', // write to both providers, not only the preferred one
|
|
344
|
+
resolve: resolveByTimestamp('updatedAt'), // read whichever copy is newest
|
|
289
345
|
tiering: 'auto', // route by size
|
|
290
346
|
outboxStorage: mmkvAdapter, // survive restarts
|
|
291
347
|
})
|
|
@@ -294,7 +350,7 @@ await store.setItem('playlist', json)
|
|
|
294
350
|
await store.flushOutbox() // on reconnect
|
|
295
351
|
```
|
|
296
352
|
|
|
297
|
-
Those two options make sync work in **both** directions across a mixed fleet: `mirror` copies to Drive so non-Apple devices can read it; `resolve` stops an Apple device serving a stale iCloud copy without checking Drive.
|
|
353
|
+
Those two options make sync work in **both** directions across a mixed fleet: `mirror` copies to Drive so non-Apple devices can read it; `resolve` stops an Apple device serving a stale iCloud copy without checking Drive. [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/store)
|
|
298
354
|
|
|
299
355
|
### In a component
|
|
300
356
|
|
|
@@ -304,7 +360,7 @@ import { useCloudItem } from 'react-native-cloud-sync/hooks'
|
|
|
304
360
|
const { value, setValue, loading, error } = useCloudItem<Settings>(store, 'settings')
|
|
305
361
|
```
|
|
306
362
|
|
|
307
|
-
Re-reads on remote writes, drops stale responses, never calls `setState` after unmount. [Full guide
|
|
363
|
+
Re-reads on remote writes, drops stale responses, never calls `setState` after unmount. [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/hooks)
|
|
308
364
|
|
|
309
365
|
### Handling failures
|
|
310
366
|
|
|
@@ -319,7 +375,7 @@ try {
|
|
|
319
375
|
}
|
|
320
376
|
```
|
|
321
377
|
|
|
322
|
-
[Full guide
|
|
378
|
+
[Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/errors)
|
|
323
379
|
|
|
324
380
|
## 🧪 Testing
|
|
325
381
|
|
|
@@ -334,7 +390,7 @@ const provider = createMemoryProvider({
|
|
|
334
390
|
provider.emitAccountChange({ status: 'available', identityChanged: true })
|
|
335
391
|
```
|
|
336
392
|
|
|
337
|
-
Signed-out, offline and account-switch paths, all in Jest without a device. [Full guide
|
|
393
|
+
Signed-out, offline and account-switch paths, all in Jest without a device. [Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/testing)
|
|
338
394
|
|
|
339
395
|
## 🧪 Example App
|
|
340
396
|
|
|
@@ -360,6 +416,8 @@ Issues and pull requests welcome. Run `yarn lint`, `yarn typecheck` and `yarn te
|
|
|
360
416
|
|
|
361
417
|
- [Kesha Antonov](https://github.com/kesha-antonov)
|
|
362
418
|
|
|
419
|
+
I also build **[cryptoc](https://cryptoc-app.web.app/)** - a crypto portfolio app with home screen, lock screen and Watch widgets, no account and no exchange API keys. It is where this library came from.
|
|
420
|
+
|
|
363
421
|
## 📄 License
|
|
364
422
|
|
|
365
423
|
MIT
|
package/ios/CloudSyncError.swift
CHANGED
|
@@ -69,6 +69,21 @@ enum CloudSyncError: Error {
|
|
|
69
69
|
/// (or into `nil`) is what makes a signed-out user indistinguishable from an
|
|
70
70
|
/// empty backup, which is the defect this whole package exists to avoid.
|
|
71
71
|
static func fromCKError(_ error: CKError) -> CloudSyncError {
|
|
72
|
+
// A single-item CKModifyRecordsOperation / CKFetchRecordsOperation
|
|
73
|
+
// reports a per-record failure at the operation level wrapped in
|
|
74
|
+
// `.partialFailure`. Mapping the wrapper fell through to ERR_UNKNOWN,
|
|
75
|
+
// so a quota, size-limit, permission or conflict failure on a write
|
|
76
|
+
// lost its code (and its retryAfter / serverValue) on the way to JS.
|
|
77
|
+
if error.code == .partialFailure,
|
|
78
|
+
let underlying = error.partialErrorsByItemID?.values
|
|
79
|
+
.compactMap({ $0 as? CKError })
|
|
80
|
+
// Batch siblings fail with .batchRequestFailed; the real cause
|
|
81
|
+
// is the other one.
|
|
82
|
+
.first(where: { $0.code != .batchRequestFailed })
|
|
83
|
+
?? error.partialErrorsByItemID?.values.compactMap({ $0 as? CKError }).first {
|
|
84
|
+
return fromCKError(underlying)
|
|
85
|
+
}
|
|
86
|
+
|
|
72
87
|
var info: [String: Any] = [:]
|
|
73
88
|
if let retryAfter = error.userInfo[CKErrorRetryAfterKey] as? Double {
|
|
74
89
|
info["retryAfterMs"] = retryAfter * 1000
|
|
@@ -81,6 +96,12 @@ enum CloudSyncError: Error {
|
|
|
81
96
|
message: "No iCloud account is signed in on this device.",
|
|
82
97
|
info: info
|
|
83
98
|
)
|
|
99
|
+
case .accountTemporarilyUnavailable:
|
|
100
|
+
return .coded(
|
|
101
|
+
code: CloudSyncErrorCode.accountUnavailable,
|
|
102
|
+
message: "The iCloud account is temporarily unavailable.",
|
|
103
|
+
info: info
|
|
104
|
+
)
|
|
84
105
|
case .managedAccountRestricted, .permissionFailure:
|
|
85
106
|
return .coded(
|
|
86
107
|
code: CloudSyncErrorCode.accountRestricted,
|