react-native-cloud-sync 0.4.0 โ 0.5.1
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 +75 -86
- 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 +73 -9
- 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 +73 -9
- package/lib/module/hooks.js.map +1 -1
- 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.map +1 -1
- 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.map +1 -1
- 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 +38 -28
- package/plugin/build/index.js +45 -13
- package/react-native-cloud-sync.podspec +10 -3
- package/src/hooks.ts +69 -9
- 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
|
@@ -17,79 +17,68 @@
|
|
|
17
17
|
</p>
|
|
18
18
|
|
|
19
19
|
<p align="center">
|
|
20
|
-
<a href="https://kesha-antonov.
|
|
21
|
-
<a href="https://kesha-antonov.
|
|
22
|
-
<a href="https://kesha-antonov.
|
|
23
|
-
<a href="https://kesha-antonov.
|
|
20
|
+
<a href="https://kesha-antonov.com/react-native-cloud-sync/">Documentation</a> ยท
|
|
21
|
+
<a href="https://kesha-antonov.com/react-native-cloud-sync/comparison">Comparison</a> ยท
|
|
22
|
+
<a href="https://kesha-antonov.com/react-native-cloud-sync/api">API</a> ยท
|
|
23
|
+
<a href="https://kesha-antonov.com/react-native-cloud-sync/platform-notes">Platform Notes</a>
|
|
24
24
|
</p>
|
|
25
25
|
|
|
26
|
+
<!-- author:start -->
|
|
26
27
|
<p align="center">
|
|
27
|
-
<sub>
|
|
28
|
+
<sub>Built and maintained by <a href="https://kesha-antonov.com">Kesha Antonov</a>, React Native lead engineer, <a href="https://kesha-antonov.com/react-native-developer/">available for hire</a>. More libraries, apps and case studies on <a href="https://kesha-antonov.com">kesha-antonov.com</a>.</sub>
|
|
28
29
|
</p>
|
|
30
|
+
<!-- author:end -->
|
|
29
31
|
|
|
30
|
-
<
|
|
31
|
-
|
|
32
|
-
|
|
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
|
|
32
|
+
<p align="center">
|
|
33
|
+
<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" />
|
|
34
|
+
</p>
|
|
48
35
|
|
|
49
|
-
|
|
36
|
+
<p align="center">
|
|
37
|
+
<sub>Using it in production? A โญ helps other developers find the library.</sub>
|
|
38
|
+
</p>
|
|
50
39
|
|
|
51
|
-
|
|
52
|
-
|
|
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
|
|
40
|
+
<!-- cryptoc-promo:start -->
|
|
41
|
+
<hr />
|
|
56
42
|
|
|
57
|
-
<
|
|
43
|
+
<h2 align="center">Sponsors</h2>
|
|
58
44
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
45
|
+
<p align="center">
|
|
46
|
+
<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>
|
|
47
|
+
<br />
|
|
48
|
+
<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
|
|
49
|
+
</p>
|
|
62
50
|
|
|
63
51
|
<hr />
|
|
52
|
+
<!-- cryptoc-promo:end -->
|
|
64
53
|
|
|
65
54
|
## โจ Features
|
|
66
55
|
|
|
67
|
-
- โ๏ธ Four providers
|
|
68
|
-
- ๐
|
|
69
|
-
- ๐ CloudKit
|
|
70
|
-
- ๐ `icloudDocuments` writes
|
|
71
|
-
- ๐จ Every failure is a typed rejection (`ERR_NOT_SIGNED_IN`, `ERR_QUOTA_EXCEEDED`, `ERR_RATE_LIMITED` with `retryAfterMs`, ...)
|
|
72
|
-
- ๐ค All five [`CKAccountStatus`][ckstatus] values
|
|
73
|
-
- ๐ `onRemoteChange`
|
|
74
|
-
- ๐ฆ
|
|
75
|
-
- ๐
|
|
76
|
-
- ๐งบ `multiGet`/`multiSet`/`multiRemove`/`clear`
|
|
77
|
-
- ๐ช
|
|
78
|
-
- ๐ `cloudKitEncrypted` uses CloudKit
|
|
79
|
-
- ๐งช
|
|
80
|
-
- โ๏ธ React Native 0.71
|
|
56
|
+
- โ๏ธ Four providers, one API: [`NSUbiquitousKeyValueStore`][kvs] (iCloud key-value store), [CloudKit][ck] records, [iCloud Drive][icdrive] documents and Google Drive [`appDataFolder`][appdata]. Use each directly or through one facade.
|
|
57
|
+
- ๐ Two-way sync between iOS and Android: `mirror` writes to iCloud and Drive together, `resolve` reads whichever copy is newest.
|
|
58
|
+
- ๐ CloudKit on Android and web via [CloudKit Web Services][ckws], against the same [private database][ckdb] as iOS.
|
|
59
|
+
- ๐ `icloudDocuments` writes to the user's iCloud Drive, visible in Files.app.
|
|
60
|
+
- ๐จ Every failure is a typed rejection (`ERR_NOT_SIGNED_IN`, `ERR_QUOTA_EXCEEDED`, `ERR_RATE_LIMITED` with `retryAfterMs`, ...). `null` only means "key doesn't exist".
|
|
61
|
+
- ๐ค All five [`CKAccountStatus`][ckstatus] values, plus `onAccountChange` with `identityChanged`, which drops the previous account's caches and queued writes.
|
|
62
|
+
- ๐ `onRemoteChange` on every provider and the facade, Google Drive included (via its change cursor).
|
|
63
|
+
- ๐ฆ Size tiering: 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.
|
|
64
|
+
- ๐ Durable, bounded outbox for retryable failures: backoff honours retry hints, drains on foreground, never overwrites a newer write.
|
|
65
|
+
- ๐งบ Real batching: `multiGet`/`multiSet`/`multiRemove`/`clear` send one request per provider.
|
|
66
|
+
- ๐ช Hooks from `/hooks`: `useCloudItem`, `useCloudItems`, `useCloudCollection`, `useAccountStatus`, `usePendingWrites`. Stale responses are dropped, no `setState` after unmount.
|
|
67
|
+
- ๐ `cloudKitEncrypted` uses CloudKit `encryptedValues`, so only ciphertext leaves the device. Other providers take a `codec` for your own cipher.
|
|
68
|
+
- ๐งช Exported in-memory provider with fault injection and a native mock (`/testing`, `/jest-mock`): test every failure path in Jest.
|
|
69
|
+
- โ๏ธ React Native 0.71 to 0.86+, old and new architecture.
|
|
81
70
|
|
|
82
71
|
## ๐ก Why?
|
|
83
72
|
|
|
84
|
-
|
|
73
|
+
Existing React Native cloud storage libraries each wrap one provider and repeat the same defects. Two ship a `setItem` that **reports a failed write as success** (one checks the wrong error variable, the other ignores the result). A third flattens five iCloud account states into one boolean.
|
|
85
74
|
|
|
86
|
-
A `catch { return null }` makes "not signed in", "offline", "out of storage" and "no such key"
|
|
75
|
+
A `catch { return null }` makes "not signed in", "offline", "out of storage" and "no such key" look the same, so the app can't tell the user what happened or decide whether to retry.
|
|
87
76
|
|
|
88
|
-
This library
|
|
77
|
+
This library starts from the error contract; providers come second.
|
|
89
78
|
|
|
90
79
|
## ๐ Upstream documentation
|
|
91
80
|
|
|
92
|
-
This package is a wrapper. When something behaves unexpectedly,
|
|
81
|
+
This package is a wrapper. When something behaves unexpectedly, check Apple's or Google's docs.
|
|
93
82
|
|
|
94
83
|
**Apple**
|
|
95
84
|
|
|
@@ -167,7 +156,7 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
|
|
|
167
156
|
<a id="note-6"></a>**[6]** Field type is `string | number | null`, so it can't hold binary data.
|
|
168
157
|
<a id="note-7"></a>**[7]** A mock factory exists, but isn't exported or documented.
|
|
169
158
|
<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.
|
|
159
|
+
<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.com/react-native-cloud-sync/providers/google-drive#large-files) for anything bigger; it chunks and resumes the same way.
|
|
171
160
|
|
|
172
161
|
[kuatsu]: https://github.com/kuatsu/react-native-cloud-storage
|
|
173
162
|
[ik]: https://github.com/BogdanGeorgian91/react-native-icloud-kit
|
|
@@ -179,20 +168,20 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
|
|
|
179
168
|
|
|
180
169
|
| | |
|
|
181
170
|
|---|---|
|
|
182
|
-
| [Choosing a provider](https://kesha-antonov.
|
|
183
|
-
| [iCloud key-value store](https://kesha-antonov.
|
|
184
|
-
| [CloudKit](https://kesha-antonov.
|
|
185
|
-
| [iCloud Drive](https://kesha-antonov.
|
|
186
|
-
| [Google Drive](https://kesha-antonov.
|
|
187
|
-
| [The store facade](https://kesha-antonov.
|
|
188
|
-
| [Error handling](https://kesha-antonov.
|
|
189
|
-
| [Encryption](https://kesha-antonov.
|
|
190
|
-
| [React hooks](https://kesha-antonov.
|
|
191
|
-
| [Recipes](https://kesha-antonov.
|
|
192
|
-
| [Testing](https://kesha-antonov.
|
|
193
|
-
| [API reference](https://kesha-antonov.
|
|
194
|
-
| [Platform notes](https://kesha-antonov.
|
|
195
|
-
| [Troubleshooting](https://kesha-antonov.
|
|
171
|
+
| [Choosing a provider](https://kesha-antonov.com/react-native-cloud-sync/choosing-a-provider) | Which one, what it costs, why to let the user pick |
|
|
172
|
+
| [iCloud key-value store](https://kesha-antonov.com/react-native-cloud-sync/providers/icloud-kv) | Small settings, zero friction, Apple only |
|
|
173
|
+
| [CloudKit](https://kesha-antonov.com/react-native-cloud-sync/providers/cloudkit) | Records, zones, assets, and the Android/web path |
|
|
174
|
+
| [iCloud Drive](https://kesha-antonov.com/react-native-cloud-sync/providers/icloud-drive) | Files in the user's own Drive, visible in Files.app |
|
|
175
|
+
| [Google Drive](https://kesha-antonov.com/react-native-cloud-sync/providers/google-drive) | The always-on cross-platform backend |
|
|
176
|
+
| [The store facade](https://kesha-antonov.com/react-native-cloud-sync/store) | Tiering, outbox, migration, fallthrough |
|
|
177
|
+
| [Error handling](https://kesha-antonov.com/react-native-cloud-sync/errors) | The typed contract |
|
|
178
|
+
| [Encryption](https://kesha-antonov.com/react-native-cloud-sync/encryption) | What's encrypted for you, and how to add your own |
|
|
179
|
+
| [React hooks](https://kesha-antonov.com/react-native-cloud-sync/hooks) | Binding cloud state to components |
|
|
180
|
+
| [Recipes](https://kesha-antonov.com/react-native-cloud-sync/recipes) | Backup/restore, migration, offline-first |
|
|
181
|
+
| [Testing](https://kesha-antonov.com/react-native-cloud-sync/testing) | Fault injection without a device |
|
|
182
|
+
| [API reference](https://kesha-antonov.com/react-native-cloud-sync/api) | Every export |
|
|
183
|
+
| [Platform notes](https://kesha-antonov.com/react-native-cloud-sync/platform-notes) | Entitlements, architectures, build config |
|
|
184
|
+
| [Troubleshooting](https://kesha-antonov.com/react-native-cloud-sync/troubleshooting) | Common problems and what they usually mean |
|
|
196
185
|
|
|
197
186
|
## ๐ Requirements
|
|
198
187
|
|
|
@@ -202,7 +191,7 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
|
|
|
202
191
|
| iOS | 15.1 |
|
|
203
192
|
| Node | 20 |
|
|
204
193
|
|
|
205
|
-
Both architectures supported
|
|
194
|
+
Both architectures are supported. RN 0.82 removed the Legacy Architecture, so it only matters on 0.81 and below.
|
|
206
195
|
|
|
207
196
|
### Platform support per provider
|
|
208
197
|
|
|
@@ -214,7 +203,7 @@ Both architectures supported; RN 0.82 removed Legacy Architecture, so that half
|
|
|
214
203
|
| `icloudDocuments` | native | - | - |
|
|
215
204
|
| `googleDrive` | REST | REST | REST |
|
|
216
205
|
|
|
217
|
-
An unavailable provider rejects with `ERR_UNSUPPORTED_PLATFORM
|
|
206
|
+
An unavailable provider rejects with `ERR_UNSUPPORTED_PLATFORM`; it never silently does nothing. Trade-offs: [Choosing a provider](https://kesha-antonov.com/react-native-cloud-sync/choosing-a-provider).
|
|
218
207
|
|
|
219
208
|
## ๐ฆ Installation
|
|
220
209
|
|
|
@@ -236,13 +225,13 @@ Add the config plugin, then rebuild:
|
|
|
236
225
|
}
|
|
237
226
|
```
|
|
238
227
|
|
|
239
|
-
Bare React Native and manual `ios/`
|
|
228
|
+
Bare React Native and manual `ios/` entitlements: see [Installation](https://kesha-antonov.com/react-native-cloud-sync/installation).
|
|
240
229
|
|
|
241
230
|
## ๐ Quick start
|
|
242
231
|
|
|
243
232
|
### iCloud key-value store
|
|
244
233
|
|
|
245
|
-
No sign-in
|
|
234
|
+
No sign-in, no UI: it uses the device's iCloud account.
|
|
246
235
|
|
|
247
236
|
```ts
|
|
248
237
|
import { icloudKV } from 'react-native-cloud-sync'
|
|
@@ -254,11 +243,11 @@ const theme = await icloudKV.getItem('settings/theme')
|
|
|
254
243
|
icloudKV.onRemoteChange(({ keys }) => reload(keys))
|
|
255
244
|
```
|
|
256
245
|
|
|
257
|
-
[Full guide](https://kesha-antonov.
|
|
246
|
+
[Full guide](https://kesha-antonov.com/react-native-cloud-sync/providers/icloud-kv)
|
|
258
247
|
|
|
259
248
|
### CloudKit
|
|
260
249
|
|
|
261
|
-
|
|
250
|
+
One private database on iOS, Android and web.
|
|
262
251
|
|
|
263
252
|
```ts
|
|
264
253
|
import { cloudKit, cloudKitAssets } from 'react-native-cloud-sync'
|
|
@@ -270,11 +259,11 @@ const raw = await cloudKit.getItem('playlist')
|
|
|
270
259
|
await cloudKitAssets.save({ recordName: 'avatar', fieldName: 'image', fileUri })
|
|
271
260
|
```
|
|
272
261
|
|
|
273
|
-
Android
|
|
262
|
+
Android and web need an Apple ID sign-in whose token lasts up to two weeks: fine for an explicit import, not for background sync. [Full guide](https://kesha-antonov.com/react-native-cloud-sync/providers/cloudkit)
|
|
274
263
|
|
|
275
264
|
### Sensitive data
|
|
276
265
|
|
|
277
|
-
CloudKit
|
|
266
|
+
CloudKit end-to-end encryption: Apple stores ciphertext and holds no key.
|
|
278
267
|
|
|
279
268
|
```ts
|
|
280
269
|
import { cloudKitEncrypted } from 'react-native-cloud-sync'
|
|
@@ -282,7 +271,7 @@ import { cloudKitEncrypted } from 'react-native-cloud-sync'
|
|
|
282
271
|
await cloudKitEncrypted.setItem('auth.refreshToken', token)
|
|
283
272
|
```
|
|
284
273
|
|
|
285
|
-
Apple
|
|
274
|
+
Apple only: the key lives in the user's iCloud Keychain. For cross-platform encryption use the store's `codec`. [Full guide](https://kesha-antonov.com/react-native-cloud-sync/encryption)
|
|
286
275
|
|
|
287
276
|
### iCloud Drive
|
|
288
277
|
|
|
@@ -297,11 +286,11 @@ await icloudDocuments.save({ fileUri: localPath, name: 'Export 2024.csv' })
|
|
|
297
286
|
const path = await icloudDocuments.fetch({ name: 'Export 2024.csv' })
|
|
298
287
|
```
|
|
299
288
|
|
|
300
|
-
[Full guide](https://kesha-antonov.
|
|
289
|
+
[Full guide](https://kesha-antonov.com/react-native-cloud-sync/providers/icloud-drive)
|
|
301
290
|
|
|
302
291
|
### Google Drive
|
|
303
292
|
|
|
304
|
-
|
|
293
|
+
Same behaviour on every platform, no periodic re-auth.
|
|
305
294
|
|
|
306
295
|
```ts
|
|
307
296
|
import { configureGoogleDrive, googleDrive } from 'react-native-cloud-sync'
|
|
@@ -313,7 +302,7 @@ configureGoogleDrive({
|
|
|
313
302
|
await googleDrive.setItem('playlist.json', JSON.stringify(tracks))
|
|
314
303
|
```
|
|
315
304
|
|
|
316
|
-
[Full guide](https://kesha-antonov.
|
|
305
|
+
[Full guide](https://kesha-antonov.com/react-native-cloud-sync/providers/google-drive)
|
|
317
306
|
|
|
318
307
|
### All of them at once
|
|
319
308
|
|
|
@@ -322,7 +311,7 @@ import { createCloudStore } from 'react-native-cloud-sync'
|
|
|
322
311
|
|
|
323
312
|
const store = createCloudStore({
|
|
324
313
|
providers: ['icloudKV', 'googleDrive'], // preference order
|
|
325
|
-
writeMode: 'mirror', // write to
|
|
314
|
+
writeMode: 'mirror', // write to every provider, not only the first
|
|
326
315
|
resolve: resolveByTimestamp('updatedAt'), // read whichever copy is newest
|
|
327
316
|
tiering: 'auto', // route by size
|
|
328
317
|
outboxStorage: mmkvAdapter, // survive restarts
|
|
@@ -332,7 +321,7 @@ await store.setItem('playlist', json)
|
|
|
332
321
|
await store.flushOutbox() // on reconnect
|
|
333
322
|
```
|
|
334
323
|
|
|
335
|
-
|
|
324
|
+
`mirror` copies writes to Drive so non-Apple devices can read them. `resolve` keeps an Apple device from serving a stale iCloud copy. Together they sync **both** ways across a mixed fleet. [Full guide](https://kesha-antonov.com/react-native-cloud-sync/store)
|
|
336
325
|
|
|
337
326
|
### In a component
|
|
338
327
|
|
|
@@ -342,7 +331,7 @@ import { useCloudItem } from 'react-native-cloud-sync/hooks'
|
|
|
342
331
|
const { value, setValue, loading, error } = useCloudItem<Settings>(store, 'settings')
|
|
343
332
|
```
|
|
344
333
|
|
|
345
|
-
Re-reads on remote writes, drops stale responses,
|
|
334
|
+
Re-reads on remote writes, drops stale responses, no `setState` after unmount. [Full guide](https://kesha-antonov.com/react-native-cloud-sync/hooks)
|
|
346
335
|
|
|
347
336
|
### Handling failures
|
|
348
337
|
|
|
@@ -357,7 +346,7 @@ try {
|
|
|
357
346
|
}
|
|
358
347
|
```
|
|
359
348
|
|
|
360
|
-
[Full guide](https://kesha-antonov.
|
|
349
|
+
[Full guide](https://kesha-antonov.com/react-native-cloud-sync/errors)
|
|
361
350
|
|
|
362
351
|
## ๐งช Testing
|
|
363
352
|
|
|
@@ -372,11 +361,11 @@ const provider = createMemoryProvider({
|
|
|
372
361
|
provider.emitAccountChange({ status: 'available', identityChanged: true })
|
|
373
362
|
```
|
|
374
363
|
|
|
375
|
-
|
|
364
|
+
Test signed-out, offline and account-switch paths in Jest, no device needed. [Full guide](https://kesha-antonov.com/react-native-cloud-sync/testing)
|
|
376
365
|
|
|
377
366
|
## ๐งช Example App
|
|
378
367
|
|
|
379
|
-
A playground
|
|
368
|
+
A playground for every API, plus a live sync demo for side-by-side recording:
|
|
380
369
|
|
|
381
370
|
```sh
|
|
382
371
|
cd example
|
|
@@ -392,13 +381,13 @@ Tabs: **Sync** (shared counter, one-tap mirror mode to iCloud+Drive), **iCloud K
|
|
|
392
381
|
|
|
393
382
|
## ๐ค Contributing
|
|
394
383
|
|
|
395
|
-
Issues and pull requests welcome. Run `yarn lint`, `yarn typecheck` and `yarn test`
|
|
384
|
+
Issues and pull requests welcome. Run `yarn lint`, `yarn typecheck` and `yarn test` first.
|
|
396
385
|
|
|
397
386
|
## ๐ฅ Authors
|
|
398
387
|
|
|
399
388
|
- [Kesha Antonov](https://github.com/kesha-antonov)
|
|
400
389
|
|
|
401
|
-
|
|
390
|
+
This library was built for **[cryptoc](https://cryptoc-app.web.app/)**, my crypto portfolio app.
|
|
402
391
|
|
|
403
392
|
## ๐ License
|
|
404
393
|
|
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,
|