react-native-cloud-sync 0.1.0 → 0.3.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.
Files changed (57) hide show
  1. package/README.md +58 -53
  2. package/ios/CloudSyncImpl.swift +25 -2
  3. package/lib/commonjs/config.js +11 -1
  4. package/lib/commonjs/config.js.map +1 -1
  5. package/lib/commonjs/index.js +6 -0
  6. package/lib/commonjs/index.js.map +1 -1
  7. package/lib/commonjs/internal/cloudKitRest.js +205 -21
  8. package/lib/commonjs/internal/cloudKitRest.js.map +1 -1
  9. package/lib/commonjs/internal/googleDriveRest.js +173 -38
  10. package/lib/commonjs/internal/googleDriveRest.js.map +1 -1
  11. package/lib/commonjs/providers/cloudKit.js +89 -19
  12. package/lib/commonjs/providers/cloudKit.js.map +1 -1
  13. package/lib/commonjs/resolvers.js +68 -0
  14. package/lib/commonjs/resolvers.js.map +1 -1
  15. package/lib/module/config.js +10 -1
  16. package/lib/module/config.js.map +1 -1
  17. package/lib/module/index.js +1 -1
  18. package/lib/module/index.js.map +1 -1
  19. package/lib/module/internal/cloudKitRest.js +205 -21
  20. package/lib/module/internal/cloudKitRest.js.map +1 -1
  21. package/lib/module/internal/googleDriveRest.js +174 -39
  22. package/lib/module/internal/googleDriveRest.js.map +1 -1
  23. package/lib/module/providers/cloudKit.js +92 -22
  24. package/lib/module/providers/cloudKit.js.map +1 -1
  25. package/lib/module/resolvers.js +67 -0
  26. package/lib/module/resolvers.js.map +1 -1
  27. package/lib/typescript/commonjs/config.d.ts +8 -0
  28. package/lib/typescript/commonjs/config.d.ts.map +1 -1
  29. package/lib/typescript/commonjs/index.d.ts +2 -2
  30. package/lib/typescript/commonjs/index.d.ts.map +1 -1
  31. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts +90 -0
  32. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts.map +1 -1
  33. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts +73 -8
  34. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts.map +1 -1
  35. package/lib/typescript/commonjs/providers/cloudKit.d.ts +32 -13
  36. package/lib/typescript/commonjs/providers/cloudKit.d.ts.map +1 -1
  37. package/lib/typescript/commonjs/resolvers.d.ts +39 -0
  38. package/lib/typescript/commonjs/resolvers.d.ts.map +1 -1
  39. package/lib/typescript/module/config.d.ts +8 -0
  40. package/lib/typescript/module/config.d.ts.map +1 -1
  41. package/lib/typescript/module/index.d.ts +2 -2
  42. package/lib/typescript/module/index.d.ts.map +1 -1
  43. package/lib/typescript/module/internal/cloudKitRest.d.ts +90 -0
  44. package/lib/typescript/module/internal/cloudKitRest.d.ts.map +1 -1
  45. package/lib/typescript/module/internal/googleDriveRest.d.ts +73 -8
  46. package/lib/typescript/module/internal/googleDriveRest.d.ts.map +1 -1
  47. package/lib/typescript/module/providers/cloudKit.d.ts +32 -13
  48. package/lib/typescript/module/providers/cloudKit.d.ts.map +1 -1
  49. package/lib/typescript/module/resolvers.d.ts +39 -0
  50. package/lib/typescript/module/resolvers.d.ts.map +1 -1
  51. package/package.json +15 -3
  52. package/src/config.ts +12 -2
  53. package/src/index.ts +4 -1
  54. package/src/internal/cloudKitRest.ts +272 -29
  55. package/src/internal/googleDriveRest.ts +196 -42
  56. package/src/providers/cloudKit.ts +138 -41
  57. package/src/resolvers.ts +75 -0
package/README.md CHANGED
@@ -7,12 +7,13 @@
7
7
  <img src="https://img.shields.io/badge/Expo-compatible-000020.svg" alt="Expo compatible" />
8
8
  <img src="https://img.shields.io/badge/New%20Architecture-supported-success.svg" alt="New Architecture supported" />
9
9
  <img src="https://img.shields.io/badge/Legacy%20Architecture-supported-success.svg" alt="Legacy Architecture supported" />
10
+ <a href="https://github.com/sponsors/kesha-antonov"><img src="https://img.shields.io/badge/sponsor-%E2%9D%A4-ea4aaa.svg?logo=github-sponsors" alt="Sponsor this project" /></a>
10
11
  </p>
11
12
 
12
13
  <h1 align="center">react-native-cloud-sync</h1>
13
14
 
14
15
  <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
+ iCloud key-value store, CloudKit and Google Drive behind one API - iOS, Android, web, both architectures.
16
17
  </p>
17
18
 
18
19
  <p align="center">
@@ -26,42 +27,42 @@
26
27
 
27
28
  ## ✨ Features
28
29
 
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.
30
+ - ☁️ Four providers behind one API - [`NSUbiquitousKeyValueStore`][kvs] (Apple's small key-value iCloud store), [CloudKit][ck] records, [iCloud Drive][icdrive] documents, Google Drive [`appDataFolder`][appdata] - directly or through one facade.
31
+ - 🍏 CloudKit reaches Android and web too, via [CloudKit Web Services][ckws] - the same [private database][ckdb] your iOS app uses.
32
+ - 📂 `icloudDocuments` writes into the user's real iCloud Drive, visible in Files.app - unlike an invisible `CKAsset`.
33
+ - 🚨 Every failure is a typed rejection (`ERR_NOT_SIGNED_IN`, `ERR_QUOTA_EXCEEDED`, `ERR_RATE_LIMITED` with `retryAfterMs`, ...); `null` means only "key doesn't exist".
34
+ - 👤 All five [`CKAccountStatus`][ckstatus] values surface as-is, plus `onAccountChange` with `identityChanged`, which drops the previous account's caches and queued writes.
35
+ - 🔔 `onRemoteChange` fires on every provider and the facade, including Google Drive via its change cursor.
36
+ - 📦 Small values go to the key-value store, larger ones to a [`CKRecord`][ckrecord] field, binary as a [`CKAsset`][ckasset] or a resumable Drive upload - sized automatically.
37
+ - 🔁 Retryable failures queue into a durable outbox: backoff honours retry hints, auto-drains on foreground, bounded, never overwrites a newer write.
38
+ - 🧺 `multiGet`/`multiSet`/`multiRemove`/`clear` batch for real, one request per provider.
39
+ - 🪝 React hooks - `useCloudItem`, `useAccountStatus`, `usePendingWrites` from `/hooks` - without the stale-response and unmounted-`setState` bugs.
40
+ - 🔐 `cloudKitEncrypted` uses CloudKit's own `encryptedValues` - ciphertext only, no key exposed; elsewhere, a `codec` seam for your own cipher.
41
+ - 🧪 An in-memory provider with fault injection, plus the native mock, both exported (`/testing`, `/jest-mock`) - every failure path testable in Jest.
42
+ - ⚙️ React Native 0.71 through 0.86+, old and new architecture, with the `#ifdef` bridge to prove it.
42
43
 
43
44
  ## 💡 Why?
44
45
 
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
+ 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.
46
47
 
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
+ A `catch { return null }` makes "not signed in", "offline", "out of storage" and "no such key" indistinguishable - apps can't tell the user anything useful, or decide whether to retry.
48
49
 
49
- This library starts from the opposite end: the error contract first, then the providers.
50
+ This library starts from the opposite end: the error contract first, providers second.
50
51
 
51
52
  ## 📚 Upstream documentation
52
53
 
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
+ This package is a wrapper: unexpected behavior is usually explained in Apple's or Google's docs, not ours.
54
55
 
55
56
  **Apple**
56
57
 
57
58
  | | |
58
59
  |---|---|
59
- | [`NSUbiquitousKeyValueStore`][kvs] | The iCloud key-value store, and its 1 MB / 1024-key limits |
60
+ | [`NSUbiquitousKeyValueStore`][kvs] | The iCloud key-value store; 1 MB / 1024-key limits |
60
61
  | [CloudKit][ck] · [`CKDatabase`][ckdb] · [`CKRecord`][ckrecord] | Records in the user's private database |
61
62
  | [`CKAsset`][ckasset] · [`CKRecordZone`][ckzone] | Binary assets and custom zones |
62
63
  | [`CKAccountStatus`][ckstatus] | The five account states this package surfaces verbatim |
63
64
  | [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
+ | [Authentication][ckauth] · [Data size limits][cklimits] · [Error codes][ckerrors] | Worth reading before shipping CloudKit on Android |
65
66
  | [iCloud entitlements][entitlements] | The keys the config plugin writes |
66
67
  | [CloudKit Console][console] | Where containers, schemas, API tokens and the sign-in callback live |
67
68
 
@@ -71,7 +72,7 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
71
72
  |---|---|
72
73
  | [The `appDataFolder`][appdata] | The hidden per-app folder this package stores into |
73
74
  | [Drive `files` resource][drivefiles] | The REST endpoints behind the provider |
74
- | [Drive API scopes][drivescopes] | Why `drive.appdata` and not something broader |
75
+ | [Drive API scopes][drivescopes] | Why `drive.appdata`, not something broader |
75
76
 
76
77
  [kvs]: https://developer.apple.com/documentation/foundation/nsubiquitouskeyvaluestore
77
78
  [ck]: https://developer.apple.com/documentation/cloudkit
@@ -99,36 +100,36 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
99
100
  | CloudKit records | ✅ | – | ✅ | ✅ | – | ✅ |
100
101
  | Google Drive | ✅ | ✅ | – | – | – | – |
101
102
  | iOS | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
102
- | Android | ✅ | ✅ | – | ❌ [^1] | – | – |
103
- | Web | ✅ | partial [^2] | – | – | – | – |
104
- | **CloudKit on Android/web** | ✅ | – | – | ❌ [^1] | – | – |
103
+ | Android | ✅ | ✅ | – | ❌ [[1]](#note-1) | – | – |
104
+ | Web | ✅ | partial [[2]](#note-2) | – | – | – | – |
105
+ | **CloudKit on Android/web** | ✅ | – | – | ❌ [[1]](#note-1) | – | – |
105
106
  | New Architecture | ✅ | ✅ | ✅ | ✅ | ✅ | – |
106
- | **Legacy Architecture** | ✅ | ❌ | ✅ [^3] | ✅ [^3] | ✅ [^3] | ✅ |
107
+ | **Legacy Architecture** | ✅ | ❌ | ✅ [[3]](#note-3) | ✅ [[3]](#note-3) | ✅ [[3]](#note-3) | ✅ |
107
108
  | Typed error codes | ✅ | – | partial | ✅ | – | – |
108
109
  | 5-value account status | ✅ | boolean | boolean | ✅ | – | – |
109
- | Identity-change event | ✅ | ⚠️ [^4] | – | ✅ | – | – |
110
- | Remote-change event | ✅ | ✅ | – | n/a | ❌ [^5] | ✅ |
110
+ | Identity-change event | ✅ | ⚠️ [[4]](#note-4) | – | ✅ | – | – |
111
+ | Remote-change event | ✅ | ✅ | – | n/a | ❌ [[5]](#note-5) | ✅ |
111
112
  | Offline write queue | ✅ | – | – | ✅ | – | – |
112
113
  | Size tiering | ✅ | – | – | – | – | – |
113
- | Binary / assets | ✅ [^9] | ✅ | ❌ [^6] | ✅ | – | – |
114
+ | Binary / assets | ✅ [[9]](#note-9) | ✅ | ❌ [[6]](#note-6) | ✅ | – | – |
114
115
  | User-visible iCloud Drive files | ✅ | – | – | – | ✅ | – |
115
116
  | Native end-to-end encryption | ✅ | – | – | – | – | – |
116
117
  | Batch operations | ✅ | – | – | – | – | – |
117
118
  | React hooks | ✅ | ✅ | – | – | – | – |
118
119
  | Encryption seam | ✅ | – | – | – | – | – |
119
- | Exported test harness | ✅ | – | – | ⚠️ [^7] | – | – |
120
+ | Exported test harness | ✅ | – | – | ⚠️ [[7]](#note-7) | – | – |
120
121
  | 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.
122
+ | Actively maintained | ✅ | ✅ | ✅ | ❌ [[8]](#note-8) | ❌ [[5]](#note-5) | ❌ |
123
+
124
+ <a id="note-1"></a>**[1]** expo-cloudkit's README: Android throws `CloudKitNotSupportedError` on every call.
125
+ <a id="note-2"></a>**[2]** Google Drive support is text-based only.
126
+ <a id="note-3"></a>**[3]** Via the Expo Modules API - pulls in `expo-modules-core`.
127
+ <a id="note-4"></a>**[4]** Fires before JS binds the emitter, crashing with `std::bad_function_call` (SIGABRT) - hit three times.
128
+ <a id="note-5"></a>**[5]** One version ever shipped; the change-listener PR has sat open since February.
129
+ <a id="note-6"></a>**[6]** Field type is `string | number | null` - can't hold binary data.
130
+ <a id="note-7"></a>**[7]** A mock factory exists, but isn't exported or documented.
131
+ <a id="note-8"></a>**[8]** No commits since April; the last four releases shipped with Swift that didn't compile.
132
+ <a id="note-9"></a>**[9]** `CKAsset` on Apple platforms; CloudKit Web Services' upload-token protocol on Android/web, capped at 15 MB (CloudKit's limit, not this package's). 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.
132
133
 
133
134
  [kuatsu]: https://github.com/kuatsu/react-native-cloud-storage
134
135
  [ik]: https://github.com/BogdanGeorgian91/react-native-icloud-kit
@@ -140,14 +141,14 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
140
141
 
141
142
  | | |
142
143
  |---|---|
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
+ | [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 |
144
145
  | [iCloud key-value store](https://kesha-antonov.github.io/react-native-cloud-sync/providers/icloud-kv) | Small settings, zero friction, Apple only |
145
146
  | [CloudKit](https://kesha-antonov.github.io/react-native-cloud-sync/providers/cloudkit) | Records, zones, assets - and the Android/web path |
146
147
  | [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
148
  | [Google Drive](https://kesha-antonov.github.io/react-native-cloud-sync/providers/google-drive) | The always-on cross-platform backend |
148
149
  | [The store facade](https://kesha-antonov.github.io/react-native-cloud-sync/store) | Tiering, outbox, migration, fallthrough |
149
150
  | [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
+ | [Encryption](https://kesha-antonov.github.io/react-native-cloud-sync/encryption) | What's encrypted for you, and how to add your own |
151
152
  | [React hooks](https://kesha-antonov.github.io/react-native-cloud-sync/hooks) | Binding cloud state to components |
152
153
  | [Recipes](https://kesha-antonov.github.io/react-native-cloud-sync/recipes) | Backup/restore, migration, offline-first |
153
154
  | [Testing](https://kesha-antonov.github.io/react-native-cloud-sync/testing) | Fault injection without a device |
@@ -163,7 +164,7 @@ This package is a wrapper. When something behaves unexpectedly, the answer is us
163
164
  | iOS | 15.1 |
164
165
  | Node | 20 |
165
166
 
166
- Both architectures are supported. React Native 0.82 removed the Legacy Architecture, so that half matters only on 0.81 and below.
167
+ Both architectures supported; RN 0.82 removed Legacy Architecture, so that half only matters on 0.81 and below.
167
168
 
168
169
  ### Platform support per provider
169
170
 
@@ -175,7 +176,7 @@ Both architectures are supported. React Native 0.82 removed the Legacy Architect
175
176
  | `icloudDocuments` | native | – | – |
176
177
  | `googleDrive` | REST | REST | REST |
177
178
 
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
+ An unavailable provider rejects with `ERR_UNSUPPORTED_PLATFORM` rather than silently no-op'ing - [Choosing a provider](https://kesha-antonov.github.io/react-native-cloud-sync/choosing-a-provider) covers the trade-offs.
179
180
 
180
181
  ## 📦 Installation
181
182
 
@@ -197,13 +198,13 @@ Add the config plugin, then rebuild:
197
198
  }
198
199
  ```
199
200
 
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
+ Bare React Native and manual `ios/` entitlement keys: see [Installation](https://kesha-antonov.github.io/react-native-cloud-sync/installation).
201
202
 
202
203
  ## 🚀 Quick start
203
204
 
204
205
  ### iCloud key-value store
205
206
 
206
- No sign-in, no UI - it uses the account already on the device.
207
+ No sign-in, no UI - uses the device's existing account.
207
208
 
208
209
  ```ts
209
210
  import { icloudKV } from 'react-native-cloud-sync'
@@ -231,7 +232,7 @@ const raw = await cloudKit.getItem('playlist')
231
232
  await cloudKitAssets.save({ recordName: 'avatar', fieldName: 'image', fileUri })
232
233
  ```
233
234
 
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
+ Android/web needs an Apple ID sign-in whose token lasts up to two weeks - an explicit import, not background sync. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/providers/cloudkit)
235
236
 
236
237
  ### Sensitive data
237
238
 
@@ -243,7 +244,7 @@ import { cloudKitEncrypted } from 'react-native-cloud-sync'
243
244
  await cloudKitEncrypted.setItem('auth.refreshToken', token)
244
245
  ```
245
246
 
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
+ 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)
247
248
 
248
249
  ### iCloud Drive
249
250
 
@@ -293,7 +294,7 @@ await store.setItem('playlist', json)
293
294
  await store.flushOutbox() // on reconnect
294
295
  ```
295
296
 
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
+ 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. Either platform can be where the user started. [Full guide →](https://kesha-antonov.github.io/react-native-cloud-sync/store)
297
298
 
298
299
  ### In a component
299
300
 
@@ -303,7 +304,7 @@ import { useCloudItem } from 'react-native-cloud-sync/hooks'
303
304
  const { value, setValue, loading, error } = useCloudItem<Settings>(store, 'settings')
304
305
  ```
305
306
 
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
+ 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)
307
308
 
308
309
  ### Handling failures
309
310
 
@@ -333,11 +334,11 @@ const provider = createMemoryProvider({
333
334
  provider.emitAccountChange({ status: 'available', identityChanged: true })
334
335
  ```
335
336
 
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
+ 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)
337
338
 
338
339
  ## 🧪 Example App
339
340
 
340
- A playground covering every API, plus a live sync demo built for side-by-side recording:
341
+ A playground covering every API, plus a live sync demo for side-by-side recording:
341
342
 
342
343
  ```sh
343
344
  cd example
@@ -345,7 +346,11 @@ yarn installDevBuild:ios # or :android
345
346
  yarn start:web
346
347
  ```
347
348
 
348
- Tabs: **Sync** (shared counter across devices), **iCloud KV**, **CloudKit**, **Drive**, **Files** (large-file backup/restore, including a working `GoogleDriveFileAdapter`), **Store** and **Faults**.
349
+ 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
+
351
+ <p align="center">
352
+ <img src="assets/screenshots/sync.png" width="18%" alt="Sync demo tab - shared counter with mirror provider selection" />&nbsp;&nbsp;<img src="assets/screenshots/icloud-kv.png" width="18%" alt="iCloud key-value store tab" />&nbsp;&nbsp;<img src="assets/screenshots/cloudkit.png" width="18%" alt="CloudKit tab - record read/write and oversized-write handling" />&nbsp;&nbsp;<img src="assets/screenshots/drive.png" width="18%" alt="Google Drive tab - OAuth token configuration and file operations" />&nbsp;&nbsp;<img src="assets/screenshots/store.png" width="18%" alt="Store facade tab - size tiering across providers" />
353
+ </p>
349
354
 
350
355
  ## 🤝 Contributing
351
356
 
@@ -817,13 +817,36 @@ import Foundation
817
817
  ) {
818
818
  let operation = CKFetchRecordsOperation(recordIDs: [id])
819
819
  operation.desiredKeys = [Self.sizeField(fieldName)]
820
+
821
+ // Best-effort means exactly one call to `completion`, from whichever
822
+ // block actually fires - never zero. Only `perRecordResultBlock` was
823
+ // wired here, but CloudKit does not always get that far: a failure at
824
+ // the OPERATION level (no signed-in account, before evaluating a
825
+ // single record) fires the operation-level completion block instead
826
+ // and never touches `perRecordResultBlock` at all. Without a fallback
827
+ // there, `completion` was silently never called - which means
828
+ // `ckFetchAsset`'s continuation into `fetchAsset` never runs, and the
829
+ // whole promise hangs forever with no error, no timeout, and no way
830
+ // for the caller to tell a stuck restore from a slow one.
831
+ var settled = false
832
+ let settle = { (size: Int) in
833
+ if settled { return }
834
+ settled = true
835
+ completion(size)
836
+ }
837
+
820
838
  operation.perRecordResultBlock = { _, result in
821
839
  guard case let .success(record) = result,
822
840
  let size = record[Self.sizeField(fieldName)] as? Int else {
823
- completion(0)
841
+ settle(0)
824
842
  return
825
843
  }
826
- completion(size)
844
+ settle(size)
845
+ }
846
+ operation.fetchRecordsResultBlock = { _ in
847
+ // Only reaches here without having settled when no per-record
848
+ // block fired at all - the operation-level failure case.
849
+ settle(0)
827
850
  }
828
851
  database.add(operation)
829
852
  }
@@ -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] googleDriveFiles needs a file adapter. Call configureGoogleDriveFiles({ ' + 'statSize, readChunk, writeChunk, appendChunk }) before saving or fetching a file.', {
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":";;;;;;;;;;;;;;;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,wFAAwF,GACtF,mFAAmF,EACrF;IAAEC,QAAQ,EAAE;EAAc,CAC5B,CAAC;EAEH,OAAOR,gBAAgB;AACzB;AAEO,SAASiB,4BAA4BA,CAAA,EAAY;EACtD,OAAOjB,gBAAgB,IAAI,IAAI;AACjC;;AAEA;AACO,SAASkB,aAAaA,CAAA,EAAS;EACpCpB,cAAc,GAAG,IAAI;EACrBC,WAAW,GAAG,IAAI;EAClBC,gBAAgB,GAAG,IAAI;AACzB","ignoreList":[]}
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":[]}
@@ -207,6 +207,12 @@ Object.defineProperty(exports, "resolveByTimestamp", {
207
207
  return _resolvers.resolveByTimestamp;
208
208
  }
209
209
  });
210
+ Object.defineProperty(exports, "resolveByUnion", {
211
+ enumerable: true,
212
+ get: function () {
213
+ return _resolvers.resolveByUnion;
214
+ }
215
+ });
210
216
  Object.defineProperty(exports, "resolveFirstOf", {
211
217
  enumerable: true,
212
218
  get: function () {
@@ -1 +1 @@
1
- {"version":3,"names":["_icloudKV","require","_cloudKit","_cloudKitBackup","_cloudKitEncrypted","_icloudDocuments","_googleDrive","_googleDriveFiles","_memory","_store","_resolvers","_keys","_config","_base","_errors","_types","_logger"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAQA,IAAAA,SAAA,GAAAC,OAAA;AAKA,IAAAC,SAAA,GAAAD,OAAA;AAMA,IAAAE,eAAA,GAAAF,OAAA;AACA,IAAAG,kBAAA,GAAAH,OAAA;AACA,IAAAI,gBAAA,GAAAJ,OAAA;AACA,IAAAK,YAAA,GAAAL,OAAA;AACA,IAAAM,iBAAA,GAAAN,OAAA;AACA,IAAAO,OAAA,GAAAP,OAAA;AAGA,IAAAQ,MAAA,GAAAR,OAAA;AAQA,IAAAS,UAAA,GAAAT,OAAA;AAQA,IAAAU,KAAA,GAAAV,OAAA;AAWA,IAAAW,OAAA,GAAAX,OAAA;AAgBA,IAAAY,KAAA,GAAAZ,OAAA;AAGA,IAAAa,OAAA,GAAAb,OAAA;AAqCA,IAAAc,MAAA,GAAAd,OAAA;AAEA,IAAAe,OAAA,GAAAf,OAAA","ignoreList":[]}
1
+ {"version":3,"names":["_icloudKV","require","_cloudKit","_cloudKitBackup","_cloudKitEncrypted","_icloudDocuments","_googleDrive","_googleDriveFiles","_memory","_store","_resolvers","_keys","_config","_base","_errors","_types","_logger"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAQA,IAAAA,SAAA,GAAAC,OAAA;AAKA,IAAAC,SAAA,GAAAD,OAAA;AAMA,IAAAE,eAAA,GAAAF,OAAA;AACA,IAAAG,kBAAA,GAAAH,OAAA;AACA,IAAAI,gBAAA,GAAAJ,OAAA;AACA,IAAAK,YAAA,GAAAL,OAAA;AACA,IAAAM,iBAAA,GAAAN,OAAA;AACA,IAAAO,OAAA,GAAAP,OAAA;AAGA,IAAAQ,MAAA,GAAAR,OAAA;AAQA,IAAAS,UAAA,GAAAT,OAAA;AASA,IAAAU,KAAA,GAAAV,OAAA;AAWA,IAAAW,OAAA,GAAAX,OAAA;AAkBA,IAAAY,KAAA,GAAAZ,OAAA;AAGA,IAAAa,OAAA,GAAAb,OAAA;AAqCA,IAAAc,MAAA,GAAAd,OAAA;AAEA,IAAAe,OAAA,GAAAf,OAAA","ignoreList":[]}