react-native-cloud-sync 0.2.0 → 0.4.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 +120 -80
- package/lib/commonjs/config.js +11 -1
- package/lib/commonjs/config.js.map +1 -1
- package/lib/commonjs/hooks.js +242 -0
- package/lib/commonjs/hooks.js.map +1 -1
- package/lib/commonjs/index.js.map +1 -1
- package/lib/commonjs/internal/cloudKitRest.js +205 -21
- package/lib/commonjs/internal/cloudKitRest.js.map +1 -1
- package/lib/commonjs/internal/googleDriveRest.js +173 -38
- package/lib/commonjs/internal/googleDriveRest.js.map +1 -1
- package/lib/commonjs/providers/cloudKit.js +89 -19
- package/lib/commonjs/providers/cloudKit.js.map +1 -1
- package/lib/module/config.js +10 -1
- package/lib/module/config.js.map +1 -1
- package/lib/module/hooks.js +240 -0
- package/lib/module/hooks.js.map +1 -1
- package/lib/module/index.js +2 -2
- package/lib/module/index.js.map +1 -1
- package/lib/module/internal/cloudKitRest.js +205 -21
- package/lib/module/internal/cloudKitRest.js.map +1 -1
- package/lib/module/internal/googleDriveRest.js +174 -39
- package/lib/module/internal/googleDriveRest.js.map +1 -1
- package/lib/module/providers/cloudKit.js +92 -22
- package/lib/module/providers/cloudKit.js.map +1 -1
- package/lib/typescript/commonjs/config.d.ts +8 -0
- package/lib/typescript/commonjs/config.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 +3 -3
- package/lib/typescript/commonjs/index.d.ts.map +1 -1
- package/lib/typescript/commonjs/internal/cloudKitRest.d.ts +90 -0
- package/lib/typescript/commonjs/internal/cloudKitRest.d.ts.map +1 -1
- package/lib/typescript/commonjs/internal/googleDriveRest.d.ts +73 -8
- package/lib/typescript/commonjs/internal/googleDriveRest.d.ts.map +1 -1
- package/lib/typescript/commonjs/providers/cloudKit.d.ts +32 -13
- package/lib/typescript/commonjs/providers/cloudKit.d.ts.map +1 -1
- package/lib/typescript/module/config.d.ts +8 -0
- package/lib/typescript/module/config.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 +3 -3
- package/lib/typescript/module/index.d.ts.map +1 -1
- package/lib/typescript/module/internal/cloudKitRest.d.ts +90 -0
- package/lib/typescript/module/internal/cloudKitRest.d.ts.map +1 -1
- package/lib/typescript/module/internal/googleDriveRest.d.ts +73 -8
- package/lib/typescript/module/internal/googleDriveRest.d.ts.map +1 -1
- package/lib/typescript/module/providers/cloudKit.d.ts +32 -13
- package/lib/typescript/module/providers/cloudKit.d.ts.map +1 -1
- package/package.json +5 -2
- package/src/config.ts +12 -2
- package/src/hooks.ts +294 -0
- package/src/index.ts +5 -3
- package/src/internal/cloudKitRest.ts +272 -29
- package/src/internal/googleDriveRest.ts +196 -42
- package/src/providers/cloudKit.ts +138 -41
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 -
|
|
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,46 +23,84 @@
|
|
|
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
|
+
<sub>Using it in production? A ⭐ helps other developers find the library.</sub>
|
|
28
|
+
</p>
|
|
29
|
+
|
|
30
|
+
<hr />
|
|
31
|
+
|
|
32
|
+
<table align="center">
|
|
33
|
+
<tr>
|
|
34
|
+
<td align="center" valign="top" width="190">
|
|
35
|
+
<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>
|
|
36
|
+
<br /><br />
|
|
37
|
+
<img src="https://cryptoc-app.web.app/img/qr-get.png?v=2" width="124" height="124" alt="QR code that installs cryptoc" />
|
|
38
|
+
<br />
|
|
39
|
+
<sub>Scan to install</sub>
|
|
40
|
+
<br /><br />
|
|
41
|
+
<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>
|
|
42
|
+
<br />
|
|
43
|
+
<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>
|
|
44
|
+
</td>
|
|
45
|
+
<td valign="top">
|
|
46
|
+
|
|
47
|
+
### Support my work
|
|
48
|
+
|
|
49
|
+
**[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.
|
|
50
|
+
|
|
51
|
+
- Portfolio with average buy price and 24h / 180-day / all-time P&L
|
|
52
|
+
- Widgets in three sizes, refreshed in the background - most days you never open the app
|
|
53
|
+
- Price alerts on 5,000+ coins, delivered while the app is closed
|
|
54
|
+
- **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
|
|
55
|
+
- Free for 3 holdings, and that is not a trial timer
|
|
56
|
+
|
|
57
|
+
<sub>This is the app the library was built for. Downloading it pays for the time that goes into maintaining it.</sub>
|
|
58
|
+
|
|
59
|
+
</td>
|
|
60
|
+
</tr>
|
|
61
|
+
</table>
|
|
62
|
+
|
|
63
|
+
<hr />
|
|
27
64
|
|
|
28
65
|
## ✨ Features
|
|
29
66
|
|
|
30
|
-
- ☁️
|
|
31
|
-
-
|
|
32
|
-
-
|
|
33
|
-
-
|
|
34
|
-
-
|
|
35
|
-
-
|
|
36
|
-
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
-
|
|
41
|
-
-
|
|
42
|
-
-
|
|
67
|
+
- ☁️ 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.
|
|
68
|
+
- 🔄 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.
|
|
69
|
+
- 🍏 CloudKit reaches Android and web too, via [CloudKit Web Services][ckws], against the same [private database][ckdb] your iOS app uses.
|
|
70
|
+
- 📂 `icloudDocuments` writes into the user's own iCloud Drive, so the files show up in Files.app.
|
|
71
|
+
- 🚨 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".
|
|
72
|
+
- 👤 All five [`CKAccountStatus`][ckstatus] values surface as-is, plus `onAccountChange` with `identityChanged`, which drops the previous account's caches and queued writes.
|
|
73
|
+
- 🔔 `onRemoteChange` fires on every provider and the facade, including Google Drive via its change cursor.
|
|
74
|
+
- 📦 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.
|
|
75
|
+
- 🔁 Retryable failures queue into a durable outbox: backoff honours retry hints, auto-drains on foreground, bounded, never overwrites a newer write.
|
|
76
|
+
- 🧺 `multiGet`/`multiSet`/`multiRemove`/`clear` batch for real, one request per provider.
|
|
77
|
+
- 🪝 React hooks from `/hooks`: `useCloudItem`, `useCloudItems`, `useCloudCollection`, `useAccountStatus`, `usePendingWrites`. They drop stale responses and never `setState` after unmount.
|
|
78
|
+
- 🔐 `cloudKitEncrypted` uses CloudKit's own `encryptedValues`, so only ciphertext leaves the device; every other provider has a `codec` seam for your own cipher.
|
|
79
|
+
- 🧪 An in-memory provider with fault injection, plus the native mock, both exported (`/testing`, `/jest-mock`), so every failure path is testable in Jest.
|
|
80
|
+
- ⚙️ React Native 0.71 through 0.86+, old and new architecture, with the `#ifdef` bridge for the legacy one.
|
|
43
81
|
|
|
44
82
|
## 💡 Why?
|
|
45
83
|
|
|
46
|
-
Cloud storage in React Native is fragmented into single-provider wrappers
|
|
84
|
+
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
85
|
|
|
48
|
-
|
|
86
|
+
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
87
|
|
|
50
|
-
This library
|
|
88
|
+
This library was built error contract first, providers second.
|
|
51
89
|
|
|
52
90
|
## 📚 Upstream documentation
|
|
53
91
|
|
|
54
|
-
This package is a wrapper. When something behaves unexpectedly, the answer is usually in Apple's or Google's
|
|
92
|
+
This package is a wrapper. When something behaves unexpectedly, the answer is usually in Apple's or Google's docs.
|
|
55
93
|
|
|
56
94
|
**Apple**
|
|
57
95
|
|
|
58
96
|
| | |
|
|
59
97
|
|---|---|
|
|
60
|
-
| [`NSUbiquitousKeyValueStore`][kvs] | The iCloud key-value store
|
|
98
|
+
| [`NSUbiquitousKeyValueStore`][kvs] | The iCloud key-value store; 1 MB / 1024-key limits |
|
|
61
99
|
| [CloudKit][ck] · [`CKDatabase`][ckdb] · [`CKRecord`][ckrecord] | Records in the user's private database |
|
|
62
100
|
| [`CKAsset`][ckasset] · [`CKRecordZone`][ckzone] | Binary assets and custom zones |
|
|
63
101
|
| [`CKAccountStatus`][ckstatus] | The five account states this package surfaces verbatim |
|
|
64
102
|
| [CloudKit Web Services][ckws] | The REST API behind the Android and web paths |
|
|
65
|
-
| [Authentication][ckauth] · [Data size limits][cklimits] · [Error codes][ckerrors] |
|
|
103
|
+
| [Authentication][ckauth] · [Data size limits][cklimits] · [Error codes][ckerrors] | Worth reading before shipping CloudKit on Android |
|
|
66
104
|
| [iCloud entitlements][entitlements] | The keys the config plugin writes |
|
|
67
105
|
| [CloudKit Console][console] | Where containers, schemas, API tokens and the sign-in callback live |
|
|
68
106
|
|
|
@@ -72,7 +110,7 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
|
|
|
72
110
|
|---|---|
|
|
73
111
|
| [The `appDataFolder`][appdata] | The hidden per-app folder this package stores into |
|
|
74
112
|
| [Drive `files` resource][drivefiles] | The REST endpoints behind the provider |
|
|
75
|
-
| [Drive API scopes][drivescopes] | Why `drive.appdata`
|
|
113
|
+
| [Drive API scopes][drivescopes] | Why the scope is `drive.appdata` |
|
|
76
114
|
|
|
77
115
|
[kvs]: https://developer.apple.com/documentation/foundation/nsubiquitouskeyvaluestore
|
|
78
116
|
[ck]: https://developer.apple.com/documentation/cloudkit
|
|
@@ -96,40 +134,40 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
|
|
|
96
134
|
|
|
97
135
|
| | **this** | [kuatsu/<br />cloud-storage][kuatsu] | [icloud-kit][ik] | [expo-cloudkit][ec] | [okwasniewski/<br />icloud-storage][ok] | [cloudkit-<br />storage][jp] |
|
|
98
136
|
|---|:---:|:---:|:---:|:---:|:---:|:---:|
|
|
99
|
-
| iCloud key-value store | ✅ | ✅ | ✅ |
|
|
100
|
-
| CloudKit records | ✅ |
|
|
101
|
-
| Google Drive | ✅ | ✅ |
|
|
137
|
+
| iCloud key-value store | ✅ | ✅ | ✅ | - | ✅ | - |
|
|
138
|
+
| CloudKit records | ✅ | - | ✅ | ✅ | - | ✅ |
|
|
139
|
+
| Google Drive | ✅ | ✅ | - | - | - | - |
|
|
102
140
|
| iOS | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
103
|
-
| Android | ✅ | ✅ |
|
|
104
|
-
| Web | ✅ | partial [
|
|
105
|
-
| **CloudKit on Android/web** | ✅ |
|
|
106
|
-
| New Architecture | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
107
|
-
| **Legacy Architecture** | ✅ | ❌ | ✅ [
|
|
108
|
-
| Typed error codes | ✅ |
|
|
109
|
-
| 5-value account status | ✅ | boolean | boolean | ✅ |
|
|
110
|
-
| Identity-change event | ✅ | ⚠️ [
|
|
111
|
-
| Remote-change event | ✅ | ✅ |
|
|
112
|
-
| Offline write queue | ✅ |
|
|
113
|
-
| Size tiering | ✅ |
|
|
114
|
-
| Binary / assets | ✅ [
|
|
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 | ✅ |
|
|
122
|
-
| Actively maintained | ✅ | ✅ | ✅ | ❌ [
|
|
123
|
-
|
|
124
|
-
[
|
|
125
|
-
[
|
|
126
|
-
[
|
|
127
|
-
[
|
|
128
|
-
[
|
|
129
|
-
[
|
|
130
|
-
[
|
|
131
|
-
[
|
|
132
|
-
[
|
|
141
|
+
| Android | ✅ | ✅ | - | ❌ [[1]](#note-1) | - | - |
|
|
142
|
+
| Web | ✅ | partial [[2]](#note-2) | - | - | - | - |
|
|
143
|
+
| **CloudKit on Android/web** | ✅ | - | - | ❌ [[1]](#note-1) | - | - |
|
|
144
|
+
| New Architecture | ✅ | ✅ | ✅ | ✅ | ✅ | - |
|
|
145
|
+
| **Legacy Architecture** | ✅ | ❌ | ✅ [[3]](#note-3) | ✅ [[3]](#note-3) | ✅ [[3]](#note-3) | ✅ |
|
|
146
|
+
| Typed error codes | ✅ | - | partial | ✅ | - | - |
|
|
147
|
+
| 5-value account status | ✅ | boolean | boolean | ✅ | - | - |
|
|
148
|
+
| Identity-change event | ✅ | ⚠️ [[4]](#note-4) | - | ✅ | - | - |
|
|
149
|
+
| Remote-change event | ✅ | ✅ | - | n/a | ❌ [[5]](#note-5) | ✅ |
|
|
150
|
+
| Offline write queue | ✅ | - | - | ✅ | - | - |
|
|
151
|
+
| Size tiering | ✅ | - | - | - | - | - |
|
|
152
|
+
| Binary / assets | ✅ [[9]](#note-9) | ✅ | ❌ [[6]](#note-6) | ✅ | - | - |
|
|
153
|
+
| User-visible iCloud Drive files | ✅ | - | - | - | ✅ | - |
|
|
154
|
+
| Native end-to-end encryption | ✅ | - | - | - | - | - |
|
|
155
|
+
| Batch operations | ✅ | - | - | - | - | - |
|
|
156
|
+
| React hooks | ✅ | ✅ | - | - | - | - |
|
|
157
|
+
| Encryption seam | ✅ | - | - | - | - | - |
|
|
158
|
+
| Exported test harness | ✅ | - | - | ⚠️ [[7]](#note-7) | - | - |
|
|
159
|
+
| Mac Catalyst | ✅ | - | - | ⚠️ | - | - |
|
|
160
|
+
| Actively maintained | ✅ | ✅ | ✅ | ❌ [[8]](#note-8) | ❌ [[5]](#note-5) | ❌ |
|
|
161
|
+
|
|
162
|
+
<a id="note-1"></a>**[1]** expo-cloudkit's README: Android throws `CloudKitNotSupportedError` on every call.
|
|
163
|
+
<a id="note-2"></a>**[2]** Google Drive support is text-based only.
|
|
164
|
+
<a id="note-3"></a>**[3]** Via the Expo Modules API; pulls in `expo-modules-core`.
|
|
165
|
+
<a id="note-4"></a>**[4]** Fires before JS binds the emitter, crashing with `std::bad_function_call` (SIGABRT); hit three times.
|
|
166
|
+
<a id="note-5"></a>**[5]** One version ever shipped; the change-listener PR has sat open since February.
|
|
167
|
+
<a id="note-6"></a>**[6]** Field type is `string | number | null`, so it can't hold binary data.
|
|
168
|
+
<a id="note-7"></a>**[7]** A mock factory exists, but isn't exported or documented.
|
|
169
|
+
<a id="note-8"></a>**[8]** No commits since April; the last four releases shipped with Swift that didn't compile.
|
|
170
|
+
<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
171
|
|
|
134
172
|
[kuatsu]: https://github.com/kuatsu/react-native-cloud-storage
|
|
135
173
|
[ik]: https://github.com/BogdanGeorgian91/react-native-icloud-kit
|
|
@@ -141,14 +179,14 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
|
|
|
141
179
|
|
|
142
180
|
| | |
|
|
143
181
|
|---|---|
|
|
144
|
-
| [Choosing a provider](https://kesha-antonov.github.io/react-native-cloud-sync/choosing-a-provider) | Which one, what
|
|
182
|
+
| [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
183
|
| [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
|
|
184
|
+
| [CloudKit](https://kesha-antonov.github.io/react-native-cloud-sync/providers/cloudkit) | Records, zones, assets, and the Android/web path |
|
|
147
185
|
| [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
186
|
| [Google Drive](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive) | The always-on cross-platform backend |
|
|
149
187
|
| [The store facade](https://kesha-antonov.github.io/react-native-cloud-sync/store) | Tiering, outbox, migration, fallthrough |
|
|
150
188
|
| [Error handling](https://kesha-antonov.github.io/react-native-cloud-sync/errors) | The typed contract |
|
|
151
|
-
| [Encryption](https://kesha-antonov.github.io/react-native-cloud-sync/encryption) | What
|
|
189
|
+
| [Encryption](https://kesha-antonov.github.io/react-native-cloud-sync/encryption) | What's encrypted for you, and how to add your own |
|
|
152
190
|
| [React hooks](https://kesha-antonov.github.io/react-native-cloud-sync/hooks) | Binding cloud state to components |
|
|
153
191
|
| [Recipes](https://kesha-antonov.github.io/react-native-cloud-sync/recipes) | Backup/restore, migration, offline-first |
|
|
154
192
|
| [Testing](https://kesha-antonov.github.io/react-native-cloud-sync/testing) | Fault injection without a device |
|
|
@@ -164,19 +202,19 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
|
|
|
164
202
|
| iOS | 15.1 |
|
|
165
203
|
| Node | 20 |
|
|
166
204
|
|
|
167
|
-
Both architectures
|
|
205
|
+
Both architectures supported; RN 0.82 removed Legacy Architecture, so that half only matters on 0.81 and below.
|
|
168
206
|
|
|
169
207
|
### Platform support per provider
|
|
170
208
|
|
|
171
209
|
| | iOS / macOS | Android | Web |
|
|
172
210
|
|---|:---:|:---:|:---:|
|
|
173
|
-
| `icloudKV` | native |
|
|
211
|
+
| `icloudKV` | native | - | - |
|
|
174
212
|
| `cloudKit` | native | REST | REST |
|
|
175
|
-
| `cloudKitEncrypted` | native |
|
|
176
|
-
| `icloudDocuments` | native |
|
|
213
|
+
| `cloudKitEncrypted` | native | - | - |
|
|
214
|
+
| `icloudDocuments` | native | - | - |
|
|
177
215
|
| `googleDrive` | REST | REST | REST |
|
|
178
216
|
|
|
179
|
-
|
|
217
|
+
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
218
|
|
|
181
219
|
## 📦 Installation
|
|
182
220
|
|
|
@@ -198,13 +236,13 @@ Add the config plugin, then rebuild:
|
|
|
198
236
|
}
|
|
199
237
|
```
|
|
200
238
|
|
|
201
|
-
Bare React Native
|
|
239
|
+
Bare React Native and manual `ios/` entitlement keys: see [Installation](https://kesha-antonov.github.io/react-native-cloud-sync/installation).
|
|
202
240
|
|
|
203
241
|
## 🚀 Quick start
|
|
204
242
|
|
|
205
243
|
### iCloud key-value store
|
|
206
244
|
|
|
207
|
-
No sign-in
|
|
245
|
+
No sign-in and no UI; it uses the device's existing account.
|
|
208
246
|
|
|
209
247
|
```ts
|
|
210
248
|
import { icloudKV } from 'react-native-cloud-sync'
|
|
@@ -216,7 +254,7 @@ const theme = await icloudKV.getItem('settings/theme')
|
|
|
216
254
|
icloudKV.onRemoteChange(({ keys }) => reload(keys))
|
|
217
255
|
```
|
|
218
256
|
|
|
219
|
-
[Full guide
|
|
257
|
+
[Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-kv)
|
|
220
258
|
|
|
221
259
|
### CloudKit
|
|
222
260
|
|
|
@@ -232,11 +270,11 @@ const raw = await cloudKit.getItem('playlist')
|
|
|
232
270
|
await cloudKitAssets.save({ recordName: 'avatar', fieldName: 'image', fileUri })
|
|
233
271
|
```
|
|
234
272
|
|
|
235
|
-
|
|
273
|
+
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
274
|
|
|
237
275
|
### Sensitive data
|
|
238
276
|
|
|
239
|
-
CloudKit's own end-to-end encryption
|
|
277
|
+
CloudKit's own end-to-end encryption: Apple stores ciphertext and holds no key.
|
|
240
278
|
|
|
241
279
|
```ts
|
|
242
280
|
import { cloudKitEncrypted } from 'react-native-cloud-sync'
|
|
@@ -244,11 +282,11 @@ import { cloudKitEncrypted } from 'react-native-cloud-sync'
|
|
|
244
282
|
await cloudKitEncrypted.setItem('auth.refreshToken', token)
|
|
245
283
|
```
|
|
246
284
|
|
|
247
|
-
Apple-only
|
|
285
|
+
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
286
|
|
|
249
287
|
### iCloud Drive
|
|
250
288
|
|
|
251
|
-
Files the user can open in Files.app
|
|
289
|
+
Files the user can open in Files.app.
|
|
252
290
|
|
|
253
291
|
```ts
|
|
254
292
|
import { icloudDocuments } from 'react-native-cloud-sync'
|
|
@@ -259,7 +297,7 @@ await icloudDocuments.save({ fileUri: localPath, name: 'Export 2024.csv' })
|
|
|
259
297
|
const path = await icloudDocuments.fetch({ name: 'Export 2024.csv' })
|
|
260
298
|
```
|
|
261
299
|
|
|
262
|
-
[Full guide
|
|
300
|
+
[Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-drive)
|
|
263
301
|
|
|
264
302
|
### Google Drive
|
|
265
303
|
|
|
@@ -275,7 +313,7 @@ configureGoogleDrive({
|
|
|
275
313
|
await googleDrive.setItem('playlist.json', JSON.stringify(tracks))
|
|
276
314
|
```
|
|
277
315
|
|
|
278
|
-
[Full guide
|
|
316
|
+
[Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive)
|
|
279
317
|
|
|
280
318
|
### All of them at once
|
|
281
319
|
|
|
@@ -284,8 +322,8 @@ import { createCloudStore } from 'react-native-cloud-sync'
|
|
|
284
322
|
|
|
285
323
|
const store = createCloudStore({
|
|
286
324
|
providers: ['icloudKV', 'googleDrive'], // preference order
|
|
287
|
-
writeMode: 'mirror', // write to
|
|
288
|
-
resolve: resolveByTimestamp('updatedAt'), // read
|
|
325
|
+
writeMode: 'mirror', // write to both providers, not only the preferred one
|
|
326
|
+
resolve: resolveByTimestamp('updatedAt'), // read whichever copy is newest
|
|
289
327
|
tiering: 'auto', // route by size
|
|
290
328
|
outboxStorage: mmkvAdapter, // survive restarts
|
|
291
329
|
})
|
|
@@ -294,7 +332,7 @@ await store.setItem('playlist', json)
|
|
|
294
332
|
await store.flushOutbox() // on reconnect
|
|
295
333
|
```
|
|
296
334
|
|
|
297
|
-
Those two options
|
|
335
|
+
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
336
|
|
|
299
337
|
### In a component
|
|
300
338
|
|
|
@@ -304,7 +342,7 @@ import { useCloudItem } from 'react-native-cloud-sync/hooks'
|
|
|
304
342
|
const { value, setValue, loading, error } = useCloudItem<Settings>(store, 'settings')
|
|
305
343
|
```
|
|
306
344
|
|
|
307
|
-
Re-reads
|
|
345
|
+
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
346
|
|
|
309
347
|
### Handling failures
|
|
310
348
|
|
|
@@ -319,7 +357,7 @@ try {
|
|
|
319
357
|
}
|
|
320
358
|
```
|
|
321
359
|
|
|
322
|
-
[Full guide
|
|
360
|
+
[Full guide](https://kesha-antonov.github.io/react-native-cloud-sync/errors)
|
|
323
361
|
|
|
324
362
|
## 🧪 Testing
|
|
325
363
|
|
|
@@ -334,11 +372,11 @@ const provider = createMemoryProvider({
|
|
|
334
372
|
provider.emitAccountChange({ status: 'available', identityChanged: true })
|
|
335
373
|
```
|
|
336
374
|
|
|
337
|
-
Signed-out, offline
|
|
375
|
+
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
376
|
|
|
339
377
|
## 🧪 Example App
|
|
340
378
|
|
|
341
|
-
A playground covering every API, plus a live sync demo
|
|
379
|
+
A playground covering every API, plus a live sync demo for side-by-side recording:
|
|
342
380
|
|
|
343
381
|
```sh
|
|
344
382
|
cd example
|
|
@@ -346,7 +384,7 @@ yarn installDevBuild:ios # or :android
|
|
|
346
384
|
yarn start:web
|
|
347
385
|
```
|
|
348
386
|
|
|
349
|
-
Tabs: **Sync** (shared counter
|
|
387
|
+
Tabs: **Sync** (shared counter, one-tap mirror mode to iCloud+Drive), **iCloud KV**, **CloudKit**, **Drive**, **Files** (large-file backup/restore via `GoogleDriveFileAdapter`), **Store**, **Faults**.
|
|
350
388
|
|
|
351
389
|
<p align="center">
|
|
352
390
|
<img src="assets/screenshots/sync.png" width="18%" alt="Sync demo tab - shared counter with mirror provider selection" /> <img src="assets/screenshots/icloud-kv.png" width="18%" alt="iCloud key-value store tab" /> <img src="assets/screenshots/cloudkit.png" width="18%" alt="CloudKit tab - record read/write and oversized-write handling" /> <img src="assets/screenshots/drive.png" width="18%" alt="Google Drive tab - OAuth token configuration and file operations" /> <img src="assets/screenshots/store.png" width="18%" alt="Store facade tab - size tiering across providers" />
|
|
@@ -360,6 +398,8 @@ Issues and pull requests welcome. Run `yarn lint`, `yarn typecheck` and `yarn te
|
|
|
360
398
|
|
|
361
399
|
- [Kesha Antonov](https://github.com/kesha-antonov)
|
|
362
400
|
|
|
401
|
+
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.
|
|
402
|
+
|
|
363
403
|
## 📄 License
|
|
364
404
|
|
|
365
405
|
MIT
|
package/lib/commonjs/config.js
CHANGED
|
@@ -10,6 +10,7 @@ exports.configureGoogleDriveFiles = configureGoogleDriveFiles;
|
|
|
10
10
|
exports.getCloudKitClient = getCloudKitClient;
|
|
11
11
|
exports.getGoogleDriveClient = getGoogleDriveClient;
|
|
12
12
|
exports.getGoogleDriveFileAdapter = getGoogleDriveFileAdapter;
|
|
13
|
+
exports.getSharedFileAdapter = void 0;
|
|
13
14
|
exports.isCloudKitConfigured = isCloudKitConfigured;
|
|
14
15
|
exports.isGoogleDriveConfigured = isGoogleDriveConfigured;
|
|
15
16
|
exports.isGoogleDriveFilesConfigured = isGoogleDriveFilesConfigured;
|
|
@@ -67,11 +68,20 @@ function configureGoogleDriveFiles(adapter) {
|
|
|
67
68
|
driveFileAdapter = adapter;
|
|
68
69
|
}
|
|
69
70
|
function getGoogleDriveFileAdapter() {
|
|
70
|
-
if (driveFileAdapter == null) throw new _errors.CloudSyncError(_errors.ErrorCode.CONTAINER_MISCONFIGURED, '[RNCloudSync]
|
|
71
|
+
if (driveFileAdapter == null) throw new _errors.CloudSyncError(_errors.ErrorCode.CONTAINER_MISCONFIGURED, '[RNCloudSync] This needs a file adapter. Call configureGoogleDriveFiles({ ' + 'statSize, readChunk, writeChunk, appendChunk }) before saving or fetching a file - shared ' + 'by googleDriveFiles and by cloudKitAssets on Android/web.', {
|
|
71
72
|
provider: 'googleDrive'
|
|
72
73
|
});
|
|
73
74
|
return driveFileAdapter;
|
|
74
75
|
}
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* Same adapter and same `configureGoogleDriveFiles` call, under a name that
|
|
79
|
+
* doesn't imply it's Drive-specific. `cloudKitAssets`'s REST path (Android/web)
|
|
80
|
+
* reads and writes local files the exact same way `googleDriveFiles` does, and
|
|
81
|
+
* asking a host app to register two near-identical adapters for that would be
|
|
82
|
+
* pure friction for no benefit.
|
|
83
|
+
*/
|
|
84
|
+
const getSharedFileAdapter = exports.getSharedFileAdapter = getGoogleDriveFileAdapter;
|
|
75
85
|
function isGoogleDriveFilesConfigured() {
|
|
76
86
|
return driveFileAdapter != null;
|
|
77
87
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"names":["_cloudKitRest","require","_googleDriveRest","_errors","cloudKitClient","driveClient","driveFileAdapter","configureCloudKit","config","CloudKitRestClient","getCloudKitClient","CloudSyncError","ErrorCode","CONTAINER_MISCONFIGURED","provider","isCloudKitConfigured","configureGoogleDrive","GoogleDriveClient","getGoogleDriveClient","isGoogleDriveConfigured","configureGoogleDriveFiles","adapter","getGoogleDriveFileAdapter","isGoogleDriveFilesConfigured","__resetConfig"],"sourceRoot":"../../src","sources":["config.ts"],"mappings":"
|
|
1
|
+
{"version":3,"names":["_cloudKitRest","require","_googleDriveRest","_errors","cloudKitClient","driveClient","driveFileAdapter","configureCloudKit","config","CloudKitRestClient","getCloudKitClient","CloudSyncError","ErrorCode","CONTAINER_MISCONFIGURED","provider","isCloudKitConfigured","configureGoogleDrive","GoogleDriveClient","getGoogleDriveClient","isGoogleDriveConfigured","configureGoogleDriveFiles","adapter","getGoogleDriveFileAdapter","getSharedFileAdapter","exports","isGoogleDriveFilesConfigured","__resetConfig"],"sourceRoot":"../../src","sources":["config.ts"],"mappings":";;;;;;;;;;;;;;;;AACA,IAAAA,aAAA,GAAAC,OAAA;AAEA,IAAAC,gBAAA,GAAAD,OAAA;AACA,IAAAE,OAAA,GAAAF,OAAA;AAEA,IAAIG,cAAyC,GAAG,IAAI;AACpD,IAAIC,WAAqC,GAAG,IAAI;AAChD,IAAIC,gBAA+C,GAAG,IAAI;;AAE1D;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,iBAAiBA,CAACC,MAA0B,EAAQ;EAClEJ,cAAc,GAAG,IAAIK,gCAAkB,CAACD,MAAM,CAAC;AACjD;AAEO,SAASE,iBAAiBA,CAAA,EAAuB;EACtD,IAAIN,cAAc,IAAI,IAAI,EACxB,MAAM,IAAIO,sBAAc,CACtBC,iBAAS,CAACC,uBAAuB,EACjC,sFAAsF,GACpF,wFAAwF,GACxF,6BAA6B,EAC/B;IAAEC,QAAQ,EAAE;EAAW,CACzB,CAAC;EAEH,OAAOV,cAAc;AACvB;AAEO,SAASW,oBAAoBA,CAAA,EAAY;EAC9C,OAAOX,cAAc,IAAI,IAAI;AAC/B;;AAEA;AACO,SAASY,oBAAoBA,CAACR,MAAyB,EAAQ;EACpEH,WAAW,GAAG,IAAIY,kCAAiB,CAACT,MAAM,CAAC;AAC7C;AAEO,SAASU,oBAAoBA,CAAA,EAAsB;EACxD,IAAIb,WAAW,IAAI,IAAI,EACrB,MAAM,IAAIM,sBAAc,CACtBC,iBAAS,CAACC,uBAAuB,EACjC,4EAA4E,GAC1E,0DAA0D,EAC5D;IAAEC,QAAQ,EAAE;EAAc,CAC5B,CAAC;EAEH,OAAOT,WAAW;AACpB;AAEO,SAASc,uBAAuBA,CAAA,EAAY;EACjD,OAAOd,WAAW,IAAI,IAAI;AAC5B;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASe,yBAAyBA,CAACC,OAA+B,EAAQ;EAC/Ef,gBAAgB,GAAGe,OAAO;AAC5B;AAEO,SAASC,yBAAyBA,CAAA,EAA2B;EAClE,IAAIhB,gBAAgB,IAAI,IAAI,EAC1B,MAAM,IAAIK,sBAAc,CACtBC,iBAAS,CAACC,uBAAuB,EACjC,4EAA4E,GAC1E,4FAA4F,GAC5F,2DAA2D,EAC7D;IAAEC,QAAQ,EAAE;EAAc,CAC5B,CAAC;EAEH,OAAOR,gBAAgB;AACzB;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMiB,oBAAoB,GAAAC,OAAA,CAAAD,oBAAA,GAAGD,yBAAyB;AAEtD,SAASG,4BAA4BA,CAAA,EAAY;EACtD,OAAOnB,gBAAgB,IAAI,IAAI;AACjC;;AAEA;AACO,SAASoB,aAAaA,CAAA,EAAS;EACpCtB,cAAc,GAAG,IAAI;EACrBC,WAAW,GAAG,IAAI;EAClBC,gBAAgB,GAAG,IAAI;AACzB","ignoreList":[]}
|