react-native-cloud-sync 0.1.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/LICENSE +21 -0
- package/README.md +360 -0
- package/app.plugin.js +3 -0
- package/ios/CloudSyncError.swift +144 -0
- package/ios/CloudSyncImpl.swift +1263 -0
- package/ios/RNCloudSync.h +25 -0
- package/ios/RNCloudSync.mm +477 -0
- package/jest-mock.js +136 -0
- package/lib/commonjs/config.js +85 -0
- package/lib/commonjs/config.js.map +1 -0
- package/lib/commonjs/errors.js +244 -0
- package/lib/commonjs/errors.js.map +1 -0
- package/lib/commonjs/hooks.js +257 -0
- package/lib/commonjs/hooks.js.map +1 -0
- package/lib/commonjs/index.js +244 -0
- package/lib/commonjs/index.js.map +1 -0
- package/lib/commonjs/internal/autoFlush.js +65 -0
- package/lib/commonjs/internal/autoFlush.js.map +1 -0
- package/lib/commonjs/internal/base64.js +58 -0
- package/lib/commonjs/internal/base64.js.map +1 -0
- package/lib/commonjs/internal/bytes.js +32 -0
- package/lib/commonjs/internal/bytes.js.map +1 -0
- package/lib/commonjs/internal/cloudKitRest.js +527 -0
- package/lib/commonjs/internal/cloudKitRest.js.map +1 -0
- package/lib/commonjs/internal/enums.js +23 -0
- package/lib/commonjs/internal/enums.js.map +1 -0
- package/lib/commonjs/internal/googleDriveRest.js +624 -0
- package/lib/commonjs/internal/googleDriveRest.js.map +1 -0
- package/lib/commonjs/internal/keys.js +139 -0
- package/lib/commonjs/internal/keys.js.map +1 -0
- package/lib/commonjs/internal/logger.js +29 -0
- package/lib/commonjs/internal/logger.js.map +1 -0
- package/lib/commonjs/internal/nativeModule.js +125 -0
- package/lib/commonjs/internal/nativeModule.js.map +1 -0
- package/lib/commonjs/internal/timeout.js +72 -0
- package/lib/commonjs/internal/timeout.js.map +1 -0
- package/lib/commonjs/package.json +1 -0
- package/lib/commonjs/providers/cloudKit.js +398 -0
- package/lib/commonjs/providers/cloudKit.js.map +1 -0
- package/lib/commonjs/providers/cloudKitBackup.js +86 -0
- package/lib/commonjs/providers/cloudKitBackup.js.map +1 -0
- package/lib/commonjs/providers/cloudKitEncrypted.js +150 -0
- package/lib/commonjs/providers/cloudKitEncrypted.js.map +1 -0
- package/lib/commonjs/providers/googleDrive.js +219 -0
- package/lib/commonjs/providers/googleDrive.js.map +1 -0
- package/lib/commonjs/providers/googleDriveFiles.js +68 -0
- package/lib/commonjs/providers/googleDriveFiles.js.map +1 -0
- package/lib/commonjs/providers/icloudDocuments.js +121 -0
- package/lib/commonjs/providers/icloudDocuments.js.map +1 -0
- package/lib/commonjs/providers/icloudKV.js +171 -0
- package/lib/commonjs/providers/icloudKV.js.map +1 -0
- package/lib/commonjs/providers/icloudKV.web.js +42 -0
- package/lib/commonjs/providers/icloudKV.web.js.map +1 -0
- package/lib/commonjs/providers/memory.js +201 -0
- package/lib/commonjs/providers/memory.js.map +1 -0
- package/lib/commonjs/resolvers.js +128 -0
- package/lib/commonjs/resolvers.js.map +1 -0
- package/lib/commonjs/specs/NativeRNCloudSync.js +14 -0
- package/lib/commonjs/specs/NativeRNCloudSync.js.map +1 -0
- package/lib/commonjs/store.js +1064 -0
- package/lib/commonjs/store.js.map +1 -0
- package/lib/commonjs/testing.js +32 -0
- package/lib/commonjs/testing.js.map +1 -0
- package/lib/commonjs/types.js +86 -0
- package/lib/commonjs/types.js.map +1 -0
- package/lib/module/config.js +72 -0
- package/lib/module/config.js.map +1 -0
- package/lib/module/errors.js +231 -0
- package/lib/module/errors.js.map +1 -0
- package/lib/module/hooks.js +250 -0
- package/lib/module/hooks.js.map +1 -0
- package/lib/module/index.js +46 -0
- package/lib/module/index.js.map +1 -0
- package/lib/module/internal/autoFlush.js +62 -0
- package/lib/module/internal/autoFlush.js.map +1 -0
- package/lib/module/internal/base64.js +53 -0
- package/lib/module/internal/base64.js.map +1 -0
- package/lib/module/internal/bytes.js +28 -0
- package/lib/module/internal/bytes.js.map +1 -0
- package/lib/module/internal/cloudKitRest.js +518 -0
- package/lib/module/internal/cloudKitRest.js.map +1 -0
- package/lib/module/internal/enums.js +18 -0
- package/lib/module/internal/enums.js.map +1 -0
- package/lib/module/internal/googleDriveRest.js +620 -0
- package/lib/module/internal/googleDriveRest.js.map +1 -0
- package/lib/module/internal/keys.js +134 -0
- package/lib/module/internal/keys.js.map +1 -0
- package/lib/module/internal/logger.js +23 -0
- package/lib/module/internal/logger.js.map +1 -0
- package/lib/module/internal/nativeModule.js +117 -0
- package/lib/module/internal/nativeModule.js.map +1 -0
- package/lib/module/internal/timeout.js +67 -0
- package/lib/module/internal/timeout.js.map +1 -0
- package/lib/module/package.json +1 -0
- package/lib/module/providers/cloudKit.js +392 -0
- package/lib/module/providers/cloudKit.js.map +1 -0
- package/lib/module/providers/cloudKitBackup.js +82 -0
- package/lib/module/providers/cloudKitBackup.js.map +1 -0
- package/lib/module/providers/cloudKitEncrypted.js +146 -0
- package/lib/module/providers/cloudKitEncrypted.js.map +1 -0
- package/lib/module/providers/googleDrive.js +214 -0
- package/lib/module/providers/googleDrive.js.map +1 -0
- package/lib/module/providers/googleDriveFiles.js +64 -0
- package/lib/module/providers/googleDriveFiles.js.map +1 -0
- package/lib/module/providers/icloudDocuments.js +117 -0
- package/lib/module/providers/icloudDocuments.js.map +1 -0
- package/lib/module/providers/icloudKV.js +165 -0
- package/lib/module/providers/icloudKV.js.map +1 -0
- package/lib/module/providers/icloudKV.web.js +36 -0
- package/lib/module/providers/icloudKV.web.js.map +1 -0
- package/lib/module/providers/memory.js +197 -0
- package/lib/module/providers/memory.js.map +1 -0
- package/lib/module/resolvers.js +120 -0
- package/lib/module/resolvers.js.map +1 -0
- package/lib/module/specs/NativeRNCloudSync.js +12 -0
- package/lib/module/specs/NativeRNCloudSync.js.map +1 -0
- package/lib/module/store.js +1061 -0
- package/lib/module/store.js.map +1 -0
- package/lib/module/testing.js +17 -0
- package/lib/module/testing.js.map +1 -0
- package/lib/module/types.js +82 -0
- package/lib/module/types.js.map +1 -0
- package/lib/typescript/commonjs/config.d.ts +33 -0
- package/lib/typescript/commonjs/config.d.ts.map +1 -0
- package/lib/typescript/commonjs/errors.d.ts +140 -0
- package/lib/typescript/commonjs/errors.d.ts.map +1 -0
- package/lib/typescript/commonjs/hooks.d.ts +109 -0
- package/lib/typescript/commonjs/hooks.d.ts.map +1 -0
- package/lib/typescript/commonjs/index.d.ts +37 -0
- package/lib/typescript/commonjs/index.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/autoFlush.d.ts +45 -0
- package/lib/typescript/commonjs/internal/autoFlush.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/base64.d.ts +12 -0
- package/lib/typescript/commonjs/internal/base64.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/bytes.d.ts +12 -0
- package/lib/typescript/commonjs/internal/bytes.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/cloudKitRest.d.ts +149 -0
- package/lib/typescript/commonjs/internal/cloudKitRest.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/enums.d.ts +10 -0
- package/lib/typescript/commonjs/internal/enums.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/googleDriveRest.d.ts +232 -0
- package/lib/typescript/commonjs/internal/googleDriveRest.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/keys.d.ts +28 -0
- package/lib/typescript/commonjs/internal/keys.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/logger.d.ts +10 -0
- package/lib/typescript/commonjs/internal/logger.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/nativeModule.d.ts +29 -0
- package/lib/typescript/commonjs/internal/nativeModule.d.ts.map +1 -0
- package/lib/typescript/commonjs/internal/timeout.d.ts +36 -0
- package/lib/typescript/commonjs/internal/timeout.d.ts.map +1 -0
- package/lib/typescript/commonjs/package.json +1 -0
- package/lib/typescript/commonjs/providers/cloudKit.d.ts +86 -0
- package/lib/typescript/commonjs/providers/cloudKit.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts +65 -0
- package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/cloudKitEncrypted.d.ts +37 -0
- package/lib/typescript/commonjs/providers/cloudKitEncrypted.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/googleDrive.d.ts +35 -0
- package/lib/typescript/commonjs/providers/googleDrive.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/googleDriveFiles.d.ts +59 -0
- package/lib/typescript/commonjs/providers/googleDriveFiles.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/icloudDocuments.d.ts +101 -0
- package/lib/typescript/commonjs/providers/icloudDocuments.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/icloudKV.d.ts +26 -0
- package/lib/typescript/commonjs/providers/icloudKV.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/icloudKV.web.d.ts +12 -0
- package/lib/typescript/commonjs/providers/icloudKV.web.d.ts.map +1 -0
- package/lib/typescript/commonjs/providers/memory.d.ts +90 -0
- package/lib/typescript/commonjs/providers/memory.d.ts.map +1 -0
- package/lib/typescript/commonjs/resolvers.d.ts +60 -0
- package/lib/typescript/commonjs/resolvers.d.ts.map +1 -0
- package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts +133 -0
- package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts.map +1 -0
- package/lib/typescript/commonjs/store.d.ts +118 -0
- package/lib/typescript/commonjs/store.d.ts.map +1 -0
- package/lib/typescript/commonjs/testing.d.ts +16 -0
- package/lib/typescript/commonjs/testing.d.ts.map +1 -0
- package/lib/typescript/commonjs/types.d.ts +367 -0
- package/lib/typescript/commonjs/types.d.ts.map +1 -0
- package/lib/typescript/module/config.d.ts +33 -0
- package/lib/typescript/module/config.d.ts.map +1 -0
- package/lib/typescript/module/errors.d.ts +140 -0
- package/lib/typescript/module/errors.d.ts.map +1 -0
- package/lib/typescript/module/hooks.d.ts +109 -0
- package/lib/typescript/module/hooks.d.ts.map +1 -0
- package/lib/typescript/module/index.d.ts +37 -0
- package/lib/typescript/module/index.d.ts.map +1 -0
- package/lib/typescript/module/internal/autoFlush.d.ts +45 -0
- package/lib/typescript/module/internal/autoFlush.d.ts.map +1 -0
- package/lib/typescript/module/internal/base64.d.ts +12 -0
- package/lib/typescript/module/internal/base64.d.ts.map +1 -0
- package/lib/typescript/module/internal/bytes.d.ts +12 -0
- package/lib/typescript/module/internal/bytes.d.ts.map +1 -0
- package/lib/typescript/module/internal/cloudKitRest.d.ts +149 -0
- package/lib/typescript/module/internal/cloudKitRest.d.ts.map +1 -0
- package/lib/typescript/module/internal/enums.d.ts +10 -0
- package/lib/typescript/module/internal/enums.d.ts.map +1 -0
- package/lib/typescript/module/internal/googleDriveRest.d.ts +232 -0
- package/lib/typescript/module/internal/googleDriveRest.d.ts.map +1 -0
- package/lib/typescript/module/internal/keys.d.ts +28 -0
- package/lib/typescript/module/internal/keys.d.ts.map +1 -0
- package/lib/typescript/module/internal/logger.d.ts +10 -0
- package/lib/typescript/module/internal/logger.d.ts.map +1 -0
- package/lib/typescript/module/internal/nativeModule.d.ts +29 -0
- package/lib/typescript/module/internal/nativeModule.d.ts.map +1 -0
- package/lib/typescript/module/internal/timeout.d.ts +36 -0
- package/lib/typescript/module/internal/timeout.d.ts.map +1 -0
- package/lib/typescript/module/package.json +1 -0
- package/lib/typescript/module/providers/cloudKit.d.ts +86 -0
- package/lib/typescript/module/providers/cloudKit.d.ts.map +1 -0
- package/lib/typescript/module/providers/cloudKitBackup.d.ts +65 -0
- package/lib/typescript/module/providers/cloudKitBackup.d.ts.map +1 -0
- package/lib/typescript/module/providers/cloudKitEncrypted.d.ts +37 -0
- package/lib/typescript/module/providers/cloudKitEncrypted.d.ts.map +1 -0
- package/lib/typescript/module/providers/googleDrive.d.ts +35 -0
- package/lib/typescript/module/providers/googleDrive.d.ts.map +1 -0
- package/lib/typescript/module/providers/googleDriveFiles.d.ts +59 -0
- package/lib/typescript/module/providers/googleDriveFiles.d.ts.map +1 -0
- package/lib/typescript/module/providers/icloudDocuments.d.ts +101 -0
- package/lib/typescript/module/providers/icloudDocuments.d.ts.map +1 -0
- package/lib/typescript/module/providers/icloudKV.d.ts +26 -0
- package/lib/typescript/module/providers/icloudKV.d.ts.map +1 -0
- package/lib/typescript/module/providers/icloudKV.web.d.ts +12 -0
- package/lib/typescript/module/providers/icloudKV.web.d.ts.map +1 -0
- package/lib/typescript/module/providers/memory.d.ts +90 -0
- package/lib/typescript/module/providers/memory.d.ts.map +1 -0
- package/lib/typescript/module/resolvers.d.ts +60 -0
- package/lib/typescript/module/resolvers.d.ts.map +1 -0
- package/lib/typescript/module/specs/NativeRNCloudSync.d.ts +133 -0
- package/lib/typescript/module/specs/NativeRNCloudSync.d.ts.map +1 -0
- package/lib/typescript/module/store.d.ts +118 -0
- package/lib/typescript/module/store.d.ts.map +1 -0
- package/lib/typescript/module/testing.d.ts +16 -0
- package/lib/typescript/module/testing.d.ts.map +1 -0
- package/lib/typescript/module/types.d.ts +367 -0
- package/lib/typescript/module/types.d.ts.map +1 -0
- package/package.json +186 -0
- package/plugin/build/index.d.ts +45 -0
- package/plugin/build/index.js +93 -0
- package/react-native-cloud-sync.podspec +48 -0
- package/src/config.ts +94 -0
- package/src/errors.ts +263 -0
- package/src/hooks.ts +337 -0
- package/src/index.ts +113 -0
- package/src/internal/autoFlush.ts +87 -0
- package/src/internal/base64.ts +63 -0
- package/src/internal/bytes.ts +28 -0
- package/src/internal/cloudKitRest.ts +654 -0
- package/src/internal/enums.ts +35 -0
- package/src/internal/googleDriveRest.ts +765 -0
- package/src/internal/keys.ts +160 -0
- package/src/internal/logger.ts +23 -0
- package/src/internal/nativeModule.ts +149 -0
- package/src/internal/timeout.ts +83 -0
- package/src/providers/cloudKit.ts +510 -0
- package/src/providers/cloudKitBackup.ts +124 -0
- package/src/providers/cloudKitEncrypted.ts +175 -0
- package/src/providers/googleDrive.ts +251 -0
- package/src/providers/googleDriveFiles.ts +117 -0
- package/src/providers/icloudDocuments.ts +175 -0
- package/src/providers/icloudKV.ts +206 -0
- package/src/providers/icloudKV.web.ts +41 -0
- package/src/providers/memory.ts +302 -0
- package/src/resolvers.ts +133 -0
- package/src/specs/NativeRNCloudSync.ts +184 -0
- package/src/store.ts +1288 -0
- package/src/testing.ts +22 -0
- package/src/types.ts +426 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kesha Antonov
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,360 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://www.npmjs.com/package/react-native-cloud-sync"><img src="https://img.shields.io/npm/v/react-native-cloud-sync.svg" alt="npm version" /></a>
|
|
3
|
+
<a href="https://www.npmjs.com/package/react-native-cloud-sync"><img src="https://img.shields.io/npm/dm/react-native-cloud-sync.svg" alt="npm downloads" /></a>
|
|
4
|
+
<a href="https://github.com/kesha-antonov/react-native-cloud-sync/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/react-native-cloud-sync.svg" alt="license" /></a>
|
|
5
|
+
<img src="https://img.shields.io/badge/platforms-iOS%20%7C%20Android%20%7C%20Web-lightgrey.svg" alt="platforms" />
|
|
6
|
+
<img src="https://img.shields.io/badge/TypeScript-ready-blue.svg" alt="TypeScript" />
|
|
7
|
+
<img src="https://img.shields.io/badge/Expo-compatible-000020.svg" alt="Expo compatible" />
|
|
8
|
+
<img src="https://img.shields.io/badge/New%20Architecture-supported-success.svg" alt="New Architecture supported" />
|
|
9
|
+
<img src="https://img.shields.io/badge/Legacy%20Architecture-supported-success.svg" alt="Legacy Architecture supported" />
|
|
10
|
+
</p>
|
|
11
|
+
|
|
12
|
+
<h1 align="center">react-native-cloud-sync</h1>
|
|
13
|
+
|
|
14
|
+
<p align="center">
|
|
15
|
+
iCloud key-value store, CloudKit and Google Drive behind one API - on iOS, Android and the web, on both React Native architectures.
|
|
16
|
+
</p>
|
|
17
|
+
|
|
18
|
+
<p align="center">
|
|
19
|
+
<a href="https://kesha-antonov.github.io/react-native-cloud-sync/">Documentation</a> ·
|
|
20
|
+
<a href="https://kesha-antonov.github.io/react-native-cloud-sync/comparison">Comparison</a> ·
|
|
21
|
+
<a href="https://kesha-antonov.github.io/react-native-cloud-sync/api">API</a> ·
|
|
22
|
+
<a href="https://kesha-antonov.github.io/react-native-cloud-sync/platform-notes">Platform Notes</a>
|
|
23
|
+
</p>
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## ✨ Features
|
|
28
|
+
|
|
29
|
+
- ☁️ **Four providers, one API** - [`NSUbiquitousKeyValueStore`][kvs] (iCloud's key-value store), [CloudKit][ck] records, [iCloud Drive][icdrive] documents and Google Drive [`appDataFolder`][appdata], each usable directly or through a single facade.
|
|
30
|
+
- 🍏 **CloudKit from Android and the web** - the same [private database][ckdb] your iOS app writes to, over [CloudKit Web Services][ckws]. No other React Native library offers this.
|
|
31
|
+
- 📂 **Files the user can actually see** - `icloudDocuments` writes into their iCloud Drive, visible in Files.app. A `CKAsset` is invisible to the user; this is the one thing no CloudKit API can do.
|
|
32
|
+
- 🚨 **Errors you can act on** - every failure is a typed rejection (`ERR_NOT_SIGNED_IN`, `ERR_QUOTA_EXCEEDED`, `ERR_RATE_LIMITED` with `retryAfterMs`, ...). `null` means one thing only: the key does not exist - never "we could not reach the cloud".
|
|
33
|
+
- 👤 **Real account lifecycle** - all five [`CKAccountStatus`][ckstatus] values, plus `onAccountChange` with an `identityChanged` flag. The store acts on it too: provider caches and queued writes belonging to the previous user are dropped, not leaked into the next account.
|
|
34
|
+
- 🔔 **Remote change events** - `onRemoteChange` on every provider *and* on the facade, including Google Drive via its change cursor.
|
|
35
|
+
- 📦 **Automatic size tiering** - small values to the key-value store, larger to a [`CKRecord`][ckrecord] field. Binary goes in as a [`CKAsset`][ckasset] or a resumable Drive upload. Store limits stop leaking into your product code.
|
|
36
|
+
- 🔁 **Durable outbox** - retryable failures are queued and retried with backoff that honours server retry hints, drained automatically on foreground, bounded so it cannot grow forever, and never allowed to overwrite a newer write.
|
|
37
|
+
- 🧺 **Batch operations** - `multiGet`/`multiSet`/`multiRemove`/`clear`, one request per provider that genuinely batches rather than a loop wearing a batch's clothes.
|
|
38
|
+
- 🪝 **React hooks** - `useCloudItem`, `useAccountStatus`, `usePendingWrites`, from `/hooks`, without the stale-response and unmounted-`setState` bugs every hand-rolled version has.
|
|
39
|
+
- 🔐 **Real end-to-end encryption** - `cloudKitEncrypted` uses CloudKit's own `encryptedValues`, so Apple stores ciphertext and holds no key, with nothing for you to manage. Everywhere else, a `codec` seam for a cipher you chose - because Drive's `appDataFolder` is plaintext to anything holding the OAuth token.
|
|
40
|
+
- 🧪 **A real testing story** - an in-memory provider with fault injection plus the native mock itself, both exported from the package (`/testing`, `/jest-mock`), so signed-out, offline, quota-exceeded and account-switch paths are all testable in Jest.
|
|
41
|
+
- ⚙️ **Old and new architecture** - React Native 0.71 through 0.86+, with the `#ifdef` bridge to prove it.
|
|
42
|
+
|
|
43
|
+
## 💡 Why?
|
|
44
|
+
|
|
45
|
+
Cloud storage in React Native is fragmented into single-provider wrappers, and almost all of them repeat the same handful of defects. Two independent libraries in this space ship a `setItem` that **reports a failed write as a success** - one checks the wrong error variable in its completion block, the other discards the operation result entirely. A third flattens five distinct iCloud account states into one boolean. A fourth has an open issue titled *"Idea: Listening for changes"* whose author replied *"Good idea, let's do it!"*, opened the PR himself, and left it unmerged for six months.
|
|
46
|
+
|
|
47
|
+
The common thread is that failure paths are treated as an afterthought. A `catch { return null }` makes "not signed in", "offline", "out of storage" and "no such key" indistinguishable - so apps cannot tell the user anything useful, and cannot decide whether to retry.
|
|
48
|
+
|
|
49
|
+
This library starts from the opposite end: the error contract first, then the providers.
|
|
50
|
+
|
|
51
|
+
## 📚 Upstream documentation
|
|
52
|
+
|
|
53
|
+
This package is a wrapper. When something behaves unexpectedly, the answer is usually in Apple's or Google's documentation rather than ours - so here is where to look.
|
|
54
|
+
|
|
55
|
+
**Apple**
|
|
56
|
+
|
|
57
|
+
| | |
|
|
58
|
+
|---|---|
|
|
59
|
+
| [`NSUbiquitousKeyValueStore`][kvs] | The iCloud key-value store, and its 1 MB / 1024-key limits |
|
|
60
|
+
| [CloudKit][ck] · [`CKDatabase`][ckdb] · [`CKRecord`][ckrecord] | Records in the user's private database |
|
|
61
|
+
| [`CKAsset`][ckasset] · [`CKRecordZone`][ckzone] | Binary assets and custom zones |
|
|
62
|
+
| [`CKAccountStatus`][ckstatus] | The five account states this package surfaces verbatim |
|
|
63
|
+
| [CloudKit Web Services][ckws] | The REST API behind the Android and web paths |
|
|
64
|
+
| [Authentication][ckauth] · [Data size limits][cklimits] · [Error codes][ckerrors] | The three pages worth reading before shipping CloudKit on Android |
|
|
65
|
+
| [iCloud entitlements][entitlements] | The keys the config plugin writes |
|
|
66
|
+
| [CloudKit Console][console] | Where containers, schemas, API tokens and the sign-in callback live |
|
|
67
|
+
|
|
68
|
+
**Google**
|
|
69
|
+
|
|
70
|
+
| | |
|
|
71
|
+
|---|---|
|
|
72
|
+
| [The `appDataFolder`][appdata] | The hidden per-app folder this package stores into |
|
|
73
|
+
| [Drive `files` resource][drivefiles] | The REST endpoints behind the provider |
|
|
74
|
+
| [Drive API scopes][drivescopes] | Why `drive.appdata` and not something broader |
|
|
75
|
+
|
|
76
|
+
[kvs]: https://developer.apple.com/documentation/foundation/nsubiquitouskeyvaluestore
|
|
77
|
+
[ck]: https://developer.apple.com/documentation/cloudkit
|
|
78
|
+
[ckdb]: https://developer.apple.com/documentation/cloudkit/ckdatabase
|
|
79
|
+
[ckrecord]: https://developer.apple.com/documentation/cloudkit/ckrecord
|
|
80
|
+
[ckasset]: https://developer.apple.com/documentation/cloudkit/ckasset
|
|
81
|
+
[ckzone]: https://developer.apple.com/documentation/cloudkit/ckrecordzone
|
|
82
|
+
[ckstatus]: https://developer.apple.com/documentation/cloudkit/ckaccountstatus
|
|
83
|
+
[ckws]: https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/index.html
|
|
84
|
+
[ckauth]: https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/SettingUpWebServices.html
|
|
85
|
+
[cklimits]: https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/PropertyMetrics.html
|
|
86
|
+
[ckerrors]: https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/ErrorCodes.html
|
|
87
|
+
[entitlements]: https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_icloud-services
|
|
88
|
+
[console]: https://icloud.developer.apple.com/dashboard/
|
|
89
|
+
[icdrive]: https://developer.apple.com/documentation/foundation/filemanager/1411653-url
|
|
90
|
+
[appdata]: https://developers.google.com/workspace/drive/api/guides/appdata
|
|
91
|
+
[drivefiles]: https://developers.google.com/workspace/drive/api/reference/rest/v3/files
|
|
92
|
+
[drivescopes]: https://developers.google.com/workspace/drive/api/guides/api-specific-auth
|
|
93
|
+
|
|
94
|
+
## ⚖️ Comparison
|
|
95
|
+
|
|
96
|
+
| | **this** | [kuatsu/<br />cloud-storage][kuatsu] | [icloud-kit][ik] | [expo-cloudkit][ec] | [okwasniewski/<br />icloud-storage][ok] | [cloudkit-<br />storage][jp] |
|
|
97
|
+
|---|:---:|:---:|:---:|:---:|:---:|:---:|
|
|
98
|
+
| iCloud key-value store | ✅ | ✅ | ✅ | – | ✅ | – |
|
|
99
|
+
| CloudKit records | ✅ | – | ✅ | ✅ | – | ✅ |
|
|
100
|
+
| Google Drive | ✅ | ✅ | – | – | – | – |
|
|
101
|
+
| iOS | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
102
|
+
| Android | ✅ | ✅ | – | ❌ [^1] | – | – |
|
|
103
|
+
| Web | ✅ | partial [^2] | – | – | – | – |
|
|
104
|
+
| **CloudKit on Android/web** | ✅ | – | – | ❌ [^1] | – | – |
|
|
105
|
+
| New Architecture | ✅ | ✅ | ✅ | ✅ | ✅ | – |
|
|
106
|
+
| **Legacy Architecture** | ✅ | ❌ | ✅ [^3] | ✅ [^3] | ✅ [^3] | ✅ |
|
|
107
|
+
| Typed error codes | ✅ | – | partial | ✅ | – | – |
|
|
108
|
+
| 5-value account status | ✅ | boolean | boolean | ✅ | – | – |
|
|
109
|
+
| Identity-change event | ✅ | ⚠️ [^4] | – | ✅ | – | – |
|
|
110
|
+
| Remote-change event | ✅ | ✅ | – | n/a | ❌ [^5] | ✅ |
|
|
111
|
+
| Offline write queue | ✅ | – | – | ✅ | – | – |
|
|
112
|
+
| Size tiering | ✅ | – | – | – | – | – |
|
|
113
|
+
| Binary / assets | ✅ [^9] | ✅ | ❌ [^6] | ✅ | – | – |
|
|
114
|
+
| User-visible iCloud Drive files | ✅ | – | – | – | ✅ | – |
|
|
115
|
+
| Native end-to-end encryption | ✅ | – | – | – | – | – |
|
|
116
|
+
| Batch operations | ✅ | – | – | – | – | – |
|
|
117
|
+
| React hooks | ✅ | ✅ | – | – | – | – |
|
|
118
|
+
| Encryption seam | ✅ | – | – | – | – | – |
|
|
119
|
+
| Exported test harness | ✅ | – | – | ⚠️ [^7] | – | – |
|
|
120
|
+
| Mac Catalyst | ✅ | – | – | ⚠️ | – | – |
|
|
121
|
+
| Actively maintained | ✅ | ✅ | ✅ | ❌ [^8] | ❌ [^5] | ❌ |
|
|
122
|
+
|
|
123
|
+
[^1]: expo-cloudkit's README states Android returns `CloudKitNotSupportedError` on every call.
|
|
124
|
+
[^2]: Text-based Google Drive operations only.
|
|
125
|
+
[^3]: Expo Modules API supports both architectures, but these packages require `expo-modules-core`.
|
|
126
|
+
[^4]: The event exists and has crashed with `std::bad_function_call` (SIGABRT) when it fires before JS binds the emitter - reported independently three times.
|
|
127
|
+
[^5]: One version ever published; the change-listener PR has been open since February.
|
|
128
|
+
[^6]: Its field type is `string | number | null`, so binary data cannot be stored at all.
|
|
129
|
+
[^7]: A mock factory exists but is not exported from the package entry and is not mentioned in the README.
|
|
130
|
+
[^8]: No commits since April; four npm releases shipped with Swift that did not compile.
|
|
131
|
+
[^9]: `CKAsset`, streamed from disk, on Apple platforms. Not yet implemented over CloudKit Web Services, so on Android and web asset calls reject with `ERR_UNSUPPORTED_PLATFORM` rather than appearing to work - use [`googleDriveFiles`](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive#large-files) for binaries there, which chunks and resumes the same way `CKAsset` does.
|
|
132
|
+
|
|
133
|
+
[kuatsu]: https://github.com/kuatsu/react-native-cloud-storage
|
|
134
|
+
[ik]: https://github.com/BogdanGeorgian91/react-native-icloud-kit
|
|
135
|
+
[ec]: https://github.com/DevLab-Innovations/expo-cloudkit
|
|
136
|
+
[ok]: https://github.com/okwasniewski/expo-icloud-storage
|
|
137
|
+
[jp]: https://github.com/jacobp100/react-native-cloudkit-storage
|
|
138
|
+
|
|
139
|
+
## 📖 Documentation
|
|
140
|
+
|
|
141
|
+
| | |
|
|
142
|
+
|---|---|
|
|
143
|
+
| [Choosing a provider](https://kesha-antonov.github.io/react-native-cloud-sync/choosing-a-provider) | Which one, what each costs you, and why to let the user pick |
|
|
144
|
+
| [iCloud key-value store](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-kv) | Small settings, zero friction, Apple only |
|
|
145
|
+
| [CloudKit](https://kesha-antonov.github.io/react-native-cloud-sync/providers/cloudkit) | Records, zones, assets - and the Android/web path |
|
|
146
|
+
| [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 |
|
|
147
|
+
| [Google Drive](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive) | The always-on cross-platform backend |
|
|
148
|
+
| [The store facade](https://kesha-antonov.github.io/react-native-cloud-sync/store) | Tiering, outbox, migration, fallthrough |
|
|
149
|
+
| [Error handling](https://kesha-antonov.github.io/react-native-cloud-sync/errors) | The typed contract |
|
|
150
|
+
| [Encryption](https://kesha-antonov.github.io/react-native-cloud-sync/encryption) | What is encrypted for you, and how to add end-to-end yourself |
|
|
151
|
+
| [React hooks](https://kesha-antonov.github.io/react-native-cloud-sync/hooks) | Binding cloud state to components |
|
|
152
|
+
| [Recipes](https://kesha-antonov.github.io/react-native-cloud-sync/recipes) | Backup/restore, migration, offline-first |
|
|
153
|
+
| [Testing](https://kesha-antonov.github.io/react-native-cloud-sync/testing) | Fault injection without a device |
|
|
154
|
+
| [API reference](https://kesha-antonov.github.io/react-native-cloud-sync/api) | Every export |
|
|
155
|
+
| [Platform notes](https://kesha-antonov.github.io/react-native-cloud-sync/platform-notes) | Entitlements, architectures, build config |
|
|
156
|
+
| [Troubleshooting](https://kesha-antonov.github.io/react-native-cloud-sync/troubleshooting) | Common problems and what they usually mean |
|
|
157
|
+
|
|
158
|
+
## 📋 Requirements
|
|
159
|
+
|
|
160
|
+
| | Minimum |
|
|
161
|
+
|---|---|
|
|
162
|
+
| React Native | 0.71 |
|
|
163
|
+
| iOS | 15.1 |
|
|
164
|
+
| Node | 20 |
|
|
165
|
+
|
|
166
|
+
Both architectures are supported. React Native 0.82 removed the Legacy Architecture, so that half matters only on 0.81 and below.
|
|
167
|
+
|
|
168
|
+
### Platform support per provider
|
|
169
|
+
|
|
170
|
+
| | iOS / macOS | Android | Web |
|
|
171
|
+
|---|:---:|:---:|:---:|
|
|
172
|
+
| `icloudKV` | native | – | – |
|
|
173
|
+
| `cloudKit` | native | REST | REST |
|
|
174
|
+
| `cloudKitEncrypted` | native | – | – |
|
|
175
|
+
| `icloudDocuments` | native | – | – |
|
|
176
|
+
| `googleDrive` | REST | REST | REST |
|
|
177
|
+
|
|
178
|
+
Where a provider is unavailable it rejects with `ERR_UNSUPPORTED_PLATFORM` rather than silently doing nothing. [Choosing a provider](https://kesha-antonov.github.io/react-native-cloud-sync/choosing-a-provider) covers the trade-offs.
|
|
179
|
+
|
|
180
|
+
## 📦 Installation
|
|
181
|
+
|
|
182
|
+
```sh
|
|
183
|
+
npx expo install react-native-cloud-sync
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Add the config plugin, then rebuild:
|
|
187
|
+
|
|
188
|
+
```json
|
|
189
|
+
{
|
|
190
|
+
"expo": {
|
|
191
|
+
"plugins": [
|
|
192
|
+
["react-native-cloud-sync", {
|
|
193
|
+
"containerIdentifier": "iCloud.com.your.app"
|
|
194
|
+
}]
|
|
195
|
+
]
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Bare React Native, and the raw entitlement keys if you manage `ios/` yourself: see [Installation](https://kesha-antonov.github.io/react-native-cloud-sync/installation).
|
|
201
|
+
|
|
202
|
+
## 🚀 Quick start
|
|
203
|
+
|
|
204
|
+
### iCloud key-value store
|
|
205
|
+
|
|
206
|
+
No sign-in, no UI - it uses the account already on the device.
|
|
207
|
+
|
|
208
|
+
```ts
|
|
209
|
+
import { icloudKV } from 'react-native-cloud-sync'
|
|
210
|
+
|
|
211
|
+
await icloudKV.setItem('settings/theme', 'dark')
|
|
212
|
+
const theme = await icloudKV.getItem('settings/theme')
|
|
213
|
+
// null means the key does not exist. Nothing else returns null.
|
|
214
|
+
|
|
215
|
+
icloudKV.onRemoteChange(({ keys }) => reload(keys))
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
[Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-kv)
|
|
219
|
+
|
|
220
|
+
### CloudKit
|
|
221
|
+
|
|
222
|
+
The same private database from iOS, Android and web.
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
import { cloudKit, cloudKitAssets } from 'react-native-cloud-sync'
|
|
226
|
+
|
|
227
|
+
await cloudKit.setItem('playlist', JSON.stringify(tracks))
|
|
228
|
+
const raw = await cloudKit.getItem('playlist')
|
|
229
|
+
|
|
230
|
+
// Anything above the 1 MB record limit goes in as a streamed CKAsset.
|
|
231
|
+
await cloudKitAssets.save({ recordName: 'avatar', fieldName: 'image', fileUri })
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
On Android and web this needs an Apple ID sign-in whose token lasts at most two weeks, so treat it as an explicit import rather than background sync. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/providers/cloudkit)
|
|
235
|
+
|
|
236
|
+
### Sensitive data
|
|
237
|
+
|
|
238
|
+
CloudKit's own end-to-end encryption - Apple stores ciphertext and holds no key.
|
|
239
|
+
|
|
240
|
+
```ts
|
|
241
|
+
import { cloudKitEncrypted } from 'react-native-cloud-sync'
|
|
242
|
+
|
|
243
|
+
await cloudKitEncrypted.setItem('auth.refreshToken', token)
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Apple-only by construction: the key lives in the user's iCloud Keychain, so nothing server-side can decrypt it. For cross-platform encryption, the store takes a `codec`. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/encryption)
|
|
247
|
+
|
|
248
|
+
### iCloud Drive
|
|
249
|
+
|
|
250
|
+
Files the user can open in Files.app - not hidden in a private database.
|
|
251
|
+
|
|
252
|
+
```ts
|
|
253
|
+
import { icloudDocuments } from 'react-native-cloud-sync'
|
|
254
|
+
|
|
255
|
+
await icloudDocuments.save({ fileUri: localPath, name: 'Export 2024.csv' })
|
|
256
|
+
|
|
257
|
+
// A listed file may be a placeholder with no local bytes. fetch() downloads it.
|
|
258
|
+
const path = await icloudDocuments.fetch({ name: 'Export 2024.csv' })
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
[Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-drive)
|
|
262
|
+
|
|
263
|
+
### Google Drive
|
|
264
|
+
|
|
265
|
+
Identical behaviour on every platform, no periodic re-auth.
|
|
266
|
+
|
|
267
|
+
```ts
|
|
268
|
+
import { configureGoogleDrive, googleDrive } from 'react-native-cloud-sync'
|
|
269
|
+
|
|
270
|
+
configureGoogleDrive({
|
|
271
|
+
getAccessToken: async () => (await GoogleSignin.getTokens()).accessToken,
|
|
272
|
+
})
|
|
273
|
+
|
|
274
|
+
await googleDrive.setItem('playlist.json', JSON.stringify(tracks))
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
[Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive)
|
|
278
|
+
|
|
279
|
+
### All of them at once
|
|
280
|
+
|
|
281
|
+
```ts
|
|
282
|
+
import { createCloudStore } from 'react-native-cloud-sync'
|
|
283
|
+
|
|
284
|
+
const store = createCloudStore({
|
|
285
|
+
providers: ['icloudKV', 'googleDrive'], // preference order
|
|
286
|
+
writeMode: 'mirror', // write to BOTH, not just the first
|
|
287
|
+
resolve: resolveByTimestamp('updatedAt'), // read the newest, not the first
|
|
288
|
+
tiering: 'auto', // route by size
|
|
289
|
+
outboxStorage: mmkvAdapter, // survive restarts
|
|
290
|
+
})
|
|
291
|
+
|
|
292
|
+
await store.setItem('playlist', json)
|
|
293
|
+
await store.flushOutbox() // on reconnect
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
Those two options are what make sync work in **both** directions across a mixed fleet - an Android phone and an iPad, a browser and a Mac. `mirror` puts a copy in Drive so a non-Apple device has something to read; `resolve` stops an Apple device serving its own stale iCloud copy without ever consulting Drive. Either platform can be the one the user started on. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/store)
|
|
297
|
+
|
|
298
|
+
### In a component
|
|
299
|
+
|
|
300
|
+
```tsx
|
|
301
|
+
import { useCloudItem } from 'react-native-cloud-sync/hooks'
|
|
302
|
+
|
|
303
|
+
const { value, setValue, loading, error } = useCloudItem<Settings>(store, 'settings')
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
Re-reads when another device writes, drops stale responses, and never calls `setState` after unmount. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/hooks)
|
|
307
|
+
|
|
308
|
+
### Handling failures
|
|
309
|
+
|
|
310
|
+
```ts
|
|
311
|
+
import { isRetryable, requiresUserAction } from 'react-native-cloud-sync'
|
|
312
|
+
|
|
313
|
+
try {
|
|
314
|
+
await store.setItem('k', 'v')
|
|
315
|
+
} catch (e) {
|
|
316
|
+
if (requiresUserAction(e)) promptUser(e.code) // signed out, out of storage
|
|
317
|
+
else if (isRetryable(e)) scheduleRetry(e.retryAfterMs)
|
|
318
|
+
}
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
[Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/errors)
|
|
322
|
+
|
|
323
|
+
## 🧪 Testing
|
|
324
|
+
|
|
325
|
+
```ts
|
|
326
|
+
import { ErrorCode } from 'react-native-cloud-sync'
|
|
327
|
+
import { createMemoryProvider } from 'react-native-cloud-sync/testing'
|
|
328
|
+
|
|
329
|
+
const provider = createMemoryProvider({
|
|
330
|
+
faults: { setItem: { code: ErrorCode.QUOTA_EXCEEDED } },
|
|
331
|
+
})
|
|
332
|
+
|
|
333
|
+
provider.emitAccountChange({ status: 'available', identityChanged: true })
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
Signed-out, offline, quota-exceeded, rate-limited and account-switch paths, all in Jest without a device. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/testing)
|
|
337
|
+
|
|
338
|
+
## 🧪 Example App
|
|
339
|
+
|
|
340
|
+
A playground covering every API, plus a live sync demo built for side-by-side recording:
|
|
341
|
+
|
|
342
|
+
```sh
|
|
343
|
+
cd example
|
|
344
|
+
yarn installDevBuild:ios # or :android
|
|
345
|
+
yarn start:web
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
Tabs: **Sync** (shared counter across devices), **iCloud KV**, **CloudKit**, **Drive**, **Files** (large-file backup/restore, including a working `GoogleDriveFileAdapter`), **Store** and **Faults**.
|
|
349
|
+
|
|
350
|
+
## 🤝 Contributing
|
|
351
|
+
|
|
352
|
+
Issues and pull requests welcome. Run `yarn lint`, `yarn typecheck` and `yarn test` before opening one.
|
|
353
|
+
|
|
354
|
+
## 👥 Authors
|
|
355
|
+
|
|
356
|
+
- [Kesha Antonov](https://github.com/kesha-antonov)
|
|
357
|
+
|
|
358
|
+
## 📄 License
|
|
359
|
+
|
|
360
|
+
MIT
|
package/app.plugin.js
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
import CloudKit
|
|
2
|
+
import Foundation
|
|
3
|
+
|
|
4
|
+
/// The error vocabulary, kept identical to `src/errors.ts` and to the Kotlin
|
|
5
|
+
/// side. These strings are public API - apps branch on them.
|
|
6
|
+
@objc public class CloudSyncErrorCode: NSObject {
|
|
7
|
+
@objc public static let notSignedIn = "ERR_NOT_SIGNED_IN"
|
|
8
|
+
@objc public static let accountRestricted = "ERR_ACCOUNT_RESTRICTED"
|
|
9
|
+
@objc public static let accountUnavailable = "ERR_ACCOUNT_UNAVAILABLE"
|
|
10
|
+
@objc public static let accountUndetermined = "ERR_ACCOUNT_UNDETERMINED"
|
|
11
|
+
@objc public static let authExpired = "ERR_AUTH_EXPIRED"
|
|
12
|
+
@objc public static let networkUnavailable = "ERR_NETWORK_UNAVAILABLE"
|
|
13
|
+
@objc public static let quotaExceeded = "ERR_QUOTA_EXCEEDED"
|
|
14
|
+
@objc public static let rateLimited = "ERR_RATE_LIMITED"
|
|
15
|
+
@objc public static let payloadTooLarge = "ERR_PAYLOAD_TOO_LARGE"
|
|
16
|
+
@objc public static let invalidKey = "ERR_INVALID_KEY"
|
|
17
|
+
@objc public static let timeout = "ERR_TIMEOUT"
|
|
18
|
+
@objc public static let conflict = "ERR_CONFLICT"
|
|
19
|
+
@objc public static let containerMisconfigured = "ERR_CONTAINER_MISCONFIGURED"
|
|
20
|
+
@objc public static let unsupportedPlatform = "ERR_UNSUPPORTED_PLATFORM"
|
|
21
|
+
@objc public static let cancelled = "ERR_CANCELLED"
|
|
22
|
+
@objc public static let unknown = "ERR_UNKNOWN"
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
enum CloudSyncError: Error {
|
|
26
|
+
case coded(code: String, message: String, info: [String: Any])
|
|
27
|
+
|
|
28
|
+
var code: String {
|
|
29
|
+
switch self {
|
|
30
|
+
case let .coded(code, _, _): return code
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
var message: String {
|
|
35
|
+
switch self {
|
|
36
|
+
case let .coded(_, message, _): return message
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
var info: [String: Any] {
|
|
41
|
+
switch self {
|
|
42
|
+
case let .coded(_, _, info): return info
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/// Bridges to an `NSError` so `reject(code, message, error)` carries the
|
|
47
|
+
/// extra fields (`retryAfterMs`, `limitBytes`, ...) into JS `userInfo`.
|
|
48
|
+
var asNSError: NSError {
|
|
49
|
+
var userInfo: [String: Any] = info
|
|
50
|
+
userInfo[NSLocalizedDescriptionKey] = message
|
|
51
|
+
return NSError(domain: "RNCloudSync", code: 0, userInfo: userInfo)
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
static func from(_ error: Error) -> CloudSyncError {
|
|
55
|
+
if let already = error as? CloudSyncError { return already }
|
|
56
|
+
guard let ckError = error as? CKError else {
|
|
57
|
+
return .coded(
|
|
58
|
+
code: CloudSyncErrorCode.unknown,
|
|
59
|
+
message: error.localizedDescription,
|
|
60
|
+
info: [:]
|
|
61
|
+
)
|
|
62
|
+
}
|
|
63
|
+
return fromCKError(ckError)
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/// Maps CloudKit's error codes onto the shared vocabulary.
|
|
67
|
+
///
|
|
68
|
+
/// The mapping matters more than it looks: collapsing these into one failure
|
|
69
|
+
/// (or into `nil`) is what makes a signed-out user indistinguishable from an
|
|
70
|
+
/// empty backup, which is the defect this whole package exists to avoid.
|
|
71
|
+
static func fromCKError(_ error: CKError) -> CloudSyncError {
|
|
72
|
+
var info: [String: Any] = [:]
|
|
73
|
+
if let retryAfter = error.userInfo[CKErrorRetryAfterKey] as? Double {
|
|
74
|
+
info["retryAfterMs"] = retryAfter * 1000
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
switch error.code {
|
|
78
|
+
case .notAuthenticated:
|
|
79
|
+
return .coded(
|
|
80
|
+
code: CloudSyncErrorCode.notSignedIn,
|
|
81
|
+
message: "No iCloud account is signed in on this device.",
|
|
82
|
+
info: info
|
|
83
|
+
)
|
|
84
|
+
case .managedAccountRestricted, .permissionFailure:
|
|
85
|
+
return .coded(
|
|
86
|
+
code: CloudSyncErrorCode.accountRestricted,
|
|
87
|
+
message: "This iCloud account is restricted from using CloudKit.",
|
|
88
|
+
info: info
|
|
89
|
+
)
|
|
90
|
+
case .networkUnavailable, .networkFailure, .serviceUnavailable:
|
|
91
|
+
return .coded(
|
|
92
|
+
code: CloudSyncErrorCode.networkUnavailable,
|
|
93
|
+
message: "Could not reach iCloud: \(error.localizedDescription)",
|
|
94
|
+
info: info
|
|
95
|
+
)
|
|
96
|
+
case .quotaExceeded:
|
|
97
|
+
return .coded(
|
|
98
|
+
code: CloudSyncErrorCode.quotaExceeded,
|
|
99
|
+
message: "The iCloud account is out of storage.",
|
|
100
|
+
info: info
|
|
101
|
+
)
|
|
102
|
+
case .requestRateLimited, .zoneBusy:
|
|
103
|
+
return .coded(
|
|
104
|
+
code: CloudSyncErrorCode.rateLimited,
|
|
105
|
+
message: "CloudKit is rate limiting requests.",
|
|
106
|
+
info: info
|
|
107
|
+
)
|
|
108
|
+
case .limitExceeded:
|
|
109
|
+
return .coded(
|
|
110
|
+
code: CloudSyncErrorCode.payloadTooLarge,
|
|
111
|
+
message: "The record exceeds CloudKit's size limit.",
|
|
112
|
+
info: info
|
|
113
|
+
)
|
|
114
|
+
case .serverRecordChanged:
|
|
115
|
+
if let server = error.userInfo[CKRecordChangedErrorServerRecordKey] as? CKRecord,
|
|
116
|
+
let value = server[CloudSyncImpl.valueField] as? String {
|
|
117
|
+
info["serverValue"] = value
|
|
118
|
+
}
|
|
119
|
+
return .coded(
|
|
120
|
+
code: CloudSyncErrorCode.conflict,
|
|
121
|
+
message: "A newer version of this record exists on the server.",
|
|
122
|
+
info: info
|
|
123
|
+
)
|
|
124
|
+
case .badContainer, .missingEntitlement, .badDatabase:
|
|
125
|
+
return .coded(
|
|
126
|
+
code: CloudSyncErrorCode.containerMisconfigured,
|
|
127
|
+
message: "CloudKit container or entitlement problem: \(error.localizedDescription)",
|
|
128
|
+
info: info
|
|
129
|
+
)
|
|
130
|
+
case .operationCancelled:
|
|
131
|
+
return .coded(
|
|
132
|
+
code: CloudSyncErrorCode.cancelled,
|
|
133
|
+
message: "The CloudKit operation was cancelled.",
|
|
134
|
+
info: info
|
|
135
|
+
)
|
|
136
|
+
default:
|
|
137
|
+
return .coded(
|
|
138
|
+
code: CloudSyncErrorCode.unknown,
|
|
139
|
+
message: error.localizedDescription,
|
|
140
|
+
info: info
|
|
141
|
+
)
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
}
|