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.
Files changed (268) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +360 -0
  3. package/app.plugin.js +3 -0
  4. package/ios/CloudSyncError.swift +144 -0
  5. package/ios/CloudSyncImpl.swift +1263 -0
  6. package/ios/RNCloudSync.h +25 -0
  7. package/ios/RNCloudSync.mm +477 -0
  8. package/jest-mock.js +136 -0
  9. package/lib/commonjs/config.js +85 -0
  10. package/lib/commonjs/config.js.map +1 -0
  11. package/lib/commonjs/errors.js +244 -0
  12. package/lib/commonjs/errors.js.map +1 -0
  13. package/lib/commonjs/hooks.js +257 -0
  14. package/lib/commonjs/hooks.js.map +1 -0
  15. package/lib/commonjs/index.js +244 -0
  16. package/lib/commonjs/index.js.map +1 -0
  17. package/lib/commonjs/internal/autoFlush.js +65 -0
  18. package/lib/commonjs/internal/autoFlush.js.map +1 -0
  19. package/lib/commonjs/internal/base64.js +58 -0
  20. package/lib/commonjs/internal/base64.js.map +1 -0
  21. package/lib/commonjs/internal/bytes.js +32 -0
  22. package/lib/commonjs/internal/bytes.js.map +1 -0
  23. package/lib/commonjs/internal/cloudKitRest.js +527 -0
  24. package/lib/commonjs/internal/cloudKitRest.js.map +1 -0
  25. package/lib/commonjs/internal/enums.js +23 -0
  26. package/lib/commonjs/internal/enums.js.map +1 -0
  27. package/lib/commonjs/internal/googleDriveRest.js +624 -0
  28. package/lib/commonjs/internal/googleDriveRest.js.map +1 -0
  29. package/lib/commonjs/internal/keys.js +139 -0
  30. package/lib/commonjs/internal/keys.js.map +1 -0
  31. package/lib/commonjs/internal/logger.js +29 -0
  32. package/lib/commonjs/internal/logger.js.map +1 -0
  33. package/lib/commonjs/internal/nativeModule.js +125 -0
  34. package/lib/commonjs/internal/nativeModule.js.map +1 -0
  35. package/lib/commonjs/internal/timeout.js +72 -0
  36. package/lib/commonjs/internal/timeout.js.map +1 -0
  37. package/lib/commonjs/package.json +1 -0
  38. package/lib/commonjs/providers/cloudKit.js +398 -0
  39. package/lib/commonjs/providers/cloudKit.js.map +1 -0
  40. package/lib/commonjs/providers/cloudKitBackup.js +86 -0
  41. package/lib/commonjs/providers/cloudKitBackup.js.map +1 -0
  42. package/lib/commonjs/providers/cloudKitEncrypted.js +150 -0
  43. package/lib/commonjs/providers/cloudKitEncrypted.js.map +1 -0
  44. package/lib/commonjs/providers/googleDrive.js +219 -0
  45. package/lib/commonjs/providers/googleDrive.js.map +1 -0
  46. package/lib/commonjs/providers/googleDriveFiles.js +68 -0
  47. package/lib/commonjs/providers/googleDriveFiles.js.map +1 -0
  48. package/lib/commonjs/providers/icloudDocuments.js +121 -0
  49. package/lib/commonjs/providers/icloudDocuments.js.map +1 -0
  50. package/lib/commonjs/providers/icloudKV.js +171 -0
  51. package/lib/commonjs/providers/icloudKV.js.map +1 -0
  52. package/lib/commonjs/providers/icloudKV.web.js +42 -0
  53. package/lib/commonjs/providers/icloudKV.web.js.map +1 -0
  54. package/lib/commonjs/providers/memory.js +201 -0
  55. package/lib/commonjs/providers/memory.js.map +1 -0
  56. package/lib/commonjs/resolvers.js +128 -0
  57. package/lib/commonjs/resolvers.js.map +1 -0
  58. package/lib/commonjs/specs/NativeRNCloudSync.js +14 -0
  59. package/lib/commonjs/specs/NativeRNCloudSync.js.map +1 -0
  60. package/lib/commonjs/store.js +1064 -0
  61. package/lib/commonjs/store.js.map +1 -0
  62. package/lib/commonjs/testing.js +32 -0
  63. package/lib/commonjs/testing.js.map +1 -0
  64. package/lib/commonjs/types.js +86 -0
  65. package/lib/commonjs/types.js.map +1 -0
  66. package/lib/module/config.js +72 -0
  67. package/lib/module/config.js.map +1 -0
  68. package/lib/module/errors.js +231 -0
  69. package/lib/module/errors.js.map +1 -0
  70. package/lib/module/hooks.js +250 -0
  71. package/lib/module/hooks.js.map +1 -0
  72. package/lib/module/index.js +46 -0
  73. package/lib/module/index.js.map +1 -0
  74. package/lib/module/internal/autoFlush.js +62 -0
  75. package/lib/module/internal/autoFlush.js.map +1 -0
  76. package/lib/module/internal/base64.js +53 -0
  77. package/lib/module/internal/base64.js.map +1 -0
  78. package/lib/module/internal/bytes.js +28 -0
  79. package/lib/module/internal/bytes.js.map +1 -0
  80. package/lib/module/internal/cloudKitRest.js +518 -0
  81. package/lib/module/internal/cloudKitRest.js.map +1 -0
  82. package/lib/module/internal/enums.js +18 -0
  83. package/lib/module/internal/enums.js.map +1 -0
  84. package/lib/module/internal/googleDriveRest.js +620 -0
  85. package/lib/module/internal/googleDriveRest.js.map +1 -0
  86. package/lib/module/internal/keys.js +134 -0
  87. package/lib/module/internal/keys.js.map +1 -0
  88. package/lib/module/internal/logger.js +23 -0
  89. package/lib/module/internal/logger.js.map +1 -0
  90. package/lib/module/internal/nativeModule.js +117 -0
  91. package/lib/module/internal/nativeModule.js.map +1 -0
  92. package/lib/module/internal/timeout.js +67 -0
  93. package/lib/module/internal/timeout.js.map +1 -0
  94. package/lib/module/package.json +1 -0
  95. package/lib/module/providers/cloudKit.js +392 -0
  96. package/lib/module/providers/cloudKit.js.map +1 -0
  97. package/lib/module/providers/cloudKitBackup.js +82 -0
  98. package/lib/module/providers/cloudKitBackup.js.map +1 -0
  99. package/lib/module/providers/cloudKitEncrypted.js +146 -0
  100. package/lib/module/providers/cloudKitEncrypted.js.map +1 -0
  101. package/lib/module/providers/googleDrive.js +214 -0
  102. package/lib/module/providers/googleDrive.js.map +1 -0
  103. package/lib/module/providers/googleDriveFiles.js +64 -0
  104. package/lib/module/providers/googleDriveFiles.js.map +1 -0
  105. package/lib/module/providers/icloudDocuments.js +117 -0
  106. package/lib/module/providers/icloudDocuments.js.map +1 -0
  107. package/lib/module/providers/icloudKV.js +165 -0
  108. package/lib/module/providers/icloudKV.js.map +1 -0
  109. package/lib/module/providers/icloudKV.web.js +36 -0
  110. package/lib/module/providers/icloudKV.web.js.map +1 -0
  111. package/lib/module/providers/memory.js +197 -0
  112. package/lib/module/providers/memory.js.map +1 -0
  113. package/lib/module/resolvers.js +120 -0
  114. package/lib/module/resolvers.js.map +1 -0
  115. package/lib/module/specs/NativeRNCloudSync.js +12 -0
  116. package/lib/module/specs/NativeRNCloudSync.js.map +1 -0
  117. package/lib/module/store.js +1061 -0
  118. package/lib/module/store.js.map +1 -0
  119. package/lib/module/testing.js +17 -0
  120. package/lib/module/testing.js.map +1 -0
  121. package/lib/module/types.js +82 -0
  122. package/lib/module/types.js.map +1 -0
  123. package/lib/typescript/commonjs/config.d.ts +33 -0
  124. package/lib/typescript/commonjs/config.d.ts.map +1 -0
  125. package/lib/typescript/commonjs/errors.d.ts +140 -0
  126. package/lib/typescript/commonjs/errors.d.ts.map +1 -0
  127. package/lib/typescript/commonjs/hooks.d.ts +109 -0
  128. package/lib/typescript/commonjs/hooks.d.ts.map +1 -0
  129. package/lib/typescript/commonjs/index.d.ts +37 -0
  130. package/lib/typescript/commonjs/index.d.ts.map +1 -0
  131. package/lib/typescript/commonjs/internal/autoFlush.d.ts +45 -0
  132. package/lib/typescript/commonjs/internal/autoFlush.d.ts.map +1 -0
  133. package/lib/typescript/commonjs/internal/base64.d.ts +12 -0
  134. package/lib/typescript/commonjs/internal/base64.d.ts.map +1 -0
  135. package/lib/typescript/commonjs/internal/bytes.d.ts +12 -0
  136. package/lib/typescript/commonjs/internal/bytes.d.ts.map +1 -0
  137. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts +149 -0
  138. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts.map +1 -0
  139. package/lib/typescript/commonjs/internal/enums.d.ts +10 -0
  140. package/lib/typescript/commonjs/internal/enums.d.ts.map +1 -0
  141. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts +232 -0
  142. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts.map +1 -0
  143. package/lib/typescript/commonjs/internal/keys.d.ts +28 -0
  144. package/lib/typescript/commonjs/internal/keys.d.ts.map +1 -0
  145. package/lib/typescript/commonjs/internal/logger.d.ts +10 -0
  146. package/lib/typescript/commonjs/internal/logger.d.ts.map +1 -0
  147. package/lib/typescript/commonjs/internal/nativeModule.d.ts +29 -0
  148. package/lib/typescript/commonjs/internal/nativeModule.d.ts.map +1 -0
  149. package/lib/typescript/commonjs/internal/timeout.d.ts +36 -0
  150. package/lib/typescript/commonjs/internal/timeout.d.ts.map +1 -0
  151. package/lib/typescript/commonjs/package.json +1 -0
  152. package/lib/typescript/commonjs/providers/cloudKit.d.ts +86 -0
  153. package/lib/typescript/commonjs/providers/cloudKit.d.ts.map +1 -0
  154. package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts +65 -0
  155. package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts.map +1 -0
  156. package/lib/typescript/commonjs/providers/cloudKitEncrypted.d.ts +37 -0
  157. package/lib/typescript/commonjs/providers/cloudKitEncrypted.d.ts.map +1 -0
  158. package/lib/typescript/commonjs/providers/googleDrive.d.ts +35 -0
  159. package/lib/typescript/commonjs/providers/googleDrive.d.ts.map +1 -0
  160. package/lib/typescript/commonjs/providers/googleDriveFiles.d.ts +59 -0
  161. package/lib/typescript/commonjs/providers/googleDriveFiles.d.ts.map +1 -0
  162. package/lib/typescript/commonjs/providers/icloudDocuments.d.ts +101 -0
  163. package/lib/typescript/commonjs/providers/icloudDocuments.d.ts.map +1 -0
  164. package/lib/typescript/commonjs/providers/icloudKV.d.ts +26 -0
  165. package/lib/typescript/commonjs/providers/icloudKV.d.ts.map +1 -0
  166. package/lib/typescript/commonjs/providers/icloudKV.web.d.ts +12 -0
  167. package/lib/typescript/commonjs/providers/icloudKV.web.d.ts.map +1 -0
  168. package/lib/typescript/commonjs/providers/memory.d.ts +90 -0
  169. package/lib/typescript/commonjs/providers/memory.d.ts.map +1 -0
  170. package/lib/typescript/commonjs/resolvers.d.ts +60 -0
  171. package/lib/typescript/commonjs/resolvers.d.ts.map +1 -0
  172. package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts +133 -0
  173. package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts.map +1 -0
  174. package/lib/typescript/commonjs/store.d.ts +118 -0
  175. package/lib/typescript/commonjs/store.d.ts.map +1 -0
  176. package/lib/typescript/commonjs/testing.d.ts +16 -0
  177. package/lib/typescript/commonjs/testing.d.ts.map +1 -0
  178. package/lib/typescript/commonjs/types.d.ts +367 -0
  179. package/lib/typescript/commonjs/types.d.ts.map +1 -0
  180. package/lib/typescript/module/config.d.ts +33 -0
  181. package/lib/typescript/module/config.d.ts.map +1 -0
  182. package/lib/typescript/module/errors.d.ts +140 -0
  183. package/lib/typescript/module/errors.d.ts.map +1 -0
  184. package/lib/typescript/module/hooks.d.ts +109 -0
  185. package/lib/typescript/module/hooks.d.ts.map +1 -0
  186. package/lib/typescript/module/index.d.ts +37 -0
  187. package/lib/typescript/module/index.d.ts.map +1 -0
  188. package/lib/typescript/module/internal/autoFlush.d.ts +45 -0
  189. package/lib/typescript/module/internal/autoFlush.d.ts.map +1 -0
  190. package/lib/typescript/module/internal/base64.d.ts +12 -0
  191. package/lib/typescript/module/internal/base64.d.ts.map +1 -0
  192. package/lib/typescript/module/internal/bytes.d.ts +12 -0
  193. package/lib/typescript/module/internal/bytes.d.ts.map +1 -0
  194. package/lib/typescript/module/internal/cloudKitRest.d.ts +149 -0
  195. package/lib/typescript/module/internal/cloudKitRest.d.ts.map +1 -0
  196. package/lib/typescript/module/internal/enums.d.ts +10 -0
  197. package/lib/typescript/module/internal/enums.d.ts.map +1 -0
  198. package/lib/typescript/module/internal/googleDriveRest.d.ts +232 -0
  199. package/lib/typescript/module/internal/googleDriveRest.d.ts.map +1 -0
  200. package/lib/typescript/module/internal/keys.d.ts +28 -0
  201. package/lib/typescript/module/internal/keys.d.ts.map +1 -0
  202. package/lib/typescript/module/internal/logger.d.ts +10 -0
  203. package/lib/typescript/module/internal/logger.d.ts.map +1 -0
  204. package/lib/typescript/module/internal/nativeModule.d.ts +29 -0
  205. package/lib/typescript/module/internal/nativeModule.d.ts.map +1 -0
  206. package/lib/typescript/module/internal/timeout.d.ts +36 -0
  207. package/lib/typescript/module/internal/timeout.d.ts.map +1 -0
  208. package/lib/typescript/module/package.json +1 -0
  209. package/lib/typescript/module/providers/cloudKit.d.ts +86 -0
  210. package/lib/typescript/module/providers/cloudKit.d.ts.map +1 -0
  211. package/lib/typescript/module/providers/cloudKitBackup.d.ts +65 -0
  212. package/lib/typescript/module/providers/cloudKitBackup.d.ts.map +1 -0
  213. package/lib/typescript/module/providers/cloudKitEncrypted.d.ts +37 -0
  214. package/lib/typescript/module/providers/cloudKitEncrypted.d.ts.map +1 -0
  215. package/lib/typescript/module/providers/googleDrive.d.ts +35 -0
  216. package/lib/typescript/module/providers/googleDrive.d.ts.map +1 -0
  217. package/lib/typescript/module/providers/googleDriveFiles.d.ts +59 -0
  218. package/lib/typescript/module/providers/googleDriveFiles.d.ts.map +1 -0
  219. package/lib/typescript/module/providers/icloudDocuments.d.ts +101 -0
  220. package/lib/typescript/module/providers/icloudDocuments.d.ts.map +1 -0
  221. package/lib/typescript/module/providers/icloudKV.d.ts +26 -0
  222. package/lib/typescript/module/providers/icloudKV.d.ts.map +1 -0
  223. package/lib/typescript/module/providers/icloudKV.web.d.ts +12 -0
  224. package/lib/typescript/module/providers/icloudKV.web.d.ts.map +1 -0
  225. package/lib/typescript/module/providers/memory.d.ts +90 -0
  226. package/lib/typescript/module/providers/memory.d.ts.map +1 -0
  227. package/lib/typescript/module/resolvers.d.ts +60 -0
  228. package/lib/typescript/module/resolvers.d.ts.map +1 -0
  229. package/lib/typescript/module/specs/NativeRNCloudSync.d.ts +133 -0
  230. package/lib/typescript/module/specs/NativeRNCloudSync.d.ts.map +1 -0
  231. package/lib/typescript/module/store.d.ts +118 -0
  232. package/lib/typescript/module/store.d.ts.map +1 -0
  233. package/lib/typescript/module/testing.d.ts +16 -0
  234. package/lib/typescript/module/testing.d.ts.map +1 -0
  235. package/lib/typescript/module/types.d.ts +367 -0
  236. package/lib/typescript/module/types.d.ts.map +1 -0
  237. package/package.json +186 -0
  238. package/plugin/build/index.d.ts +45 -0
  239. package/plugin/build/index.js +93 -0
  240. package/react-native-cloud-sync.podspec +48 -0
  241. package/src/config.ts +94 -0
  242. package/src/errors.ts +263 -0
  243. package/src/hooks.ts +337 -0
  244. package/src/index.ts +113 -0
  245. package/src/internal/autoFlush.ts +87 -0
  246. package/src/internal/base64.ts +63 -0
  247. package/src/internal/bytes.ts +28 -0
  248. package/src/internal/cloudKitRest.ts +654 -0
  249. package/src/internal/enums.ts +35 -0
  250. package/src/internal/googleDriveRest.ts +765 -0
  251. package/src/internal/keys.ts +160 -0
  252. package/src/internal/logger.ts +23 -0
  253. package/src/internal/nativeModule.ts +149 -0
  254. package/src/internal/timeout.ts +83 -0
  255. package/src/providers/cloudKit.ts +510 -0
  256. package/src/providers/cloudKitBackup.ts +124 -0
  257. package/src/providers/cloudKitEncrypted.ts +175 -0
  258. package/src/providers/googleDrive.ts +251 -0
  259. package/src/providers/googleDriveFiles.ts +117 -0
  260. package/src/providers/icloudDocuments.ts +175 -0
  261. package/src/providers/icloudKV.ts +206 -0
  262. package/src/providers/icloudKV.web.ts +41 -0
  263. package/src/providers/memory.ts +302 -0
  264. package/src/resolvers.ts +133 -0
  265. package/src/specs/NativeRNCloudSync.ts +184 -0
  266. package/src/store.ts +1288 -0
  267. package/src/testing.ts +22 -0
  268. package/src/types.ts +426 -0
package/src/store.ts ADDED
@@ -0,0 +1,1288 @@
1
+ import { icloudKV } from './providers/icloudKV'
2
+ import { cloudKit } from './providers/cloudKit'
3
+ import { cloudKitEncrypted } from './providers/cloudKitEncrypted'
4
+ import { googleDrive } from './providers/googleDrive'
5
+ import { byteLength } from './internal/bytes'
6
+ import { assertKey } from './internal/keys'
7
+ import { withTimeout } from './internal/timeout'
8
+ import { attachAutoFlush } from './internal/autoFlush'
9
+ import { CloudSyncError, ErrorCode, isRetryable, normalizeError } from './errors'
10
+ import {
11
+ DEFAULT_TIERING,
12
+ type AccountChangeEvent,
13
+ type CloudProvider,
14
+ type CloudStoreOptions,
15
+ type DropReason,
16
+ type DroppedWrite,
17
+ type ItemWithMeta,
18
+ type OutboxEntry,
19
+ type ProviderName,
20
+ type QuotaInfo,
21
+ type RemoteChangeEvent,
22
+ type ResolveCandidate,
23
+ type TieringConfig,
24
+ type Unsubscribe,
25
+ type ValueCodec,
26
+ } from './types'
27
+
28
+ /**
29
+ * A durable place to park failed writes.
30
+ *
31
+ * Defaults to memory, which is honest but loses the queue on app restart. Pass
32
+ * an MMKV-backed adapter in production so an offline write survives being
33
+ * killed - that is the whole point of the outbox.
34
+ *
35
+ * Both methods are synchronous: the outbox is read and rewritten on the write
36
+ * path, where there is nowhere to await. AsyncStorage therefore cannot be
37
+ * wrapped directly; keep a synchronous cache in front of it if that is the
38
+ * only store you have.
39
+ */
40
+ export interface OutboxStorage {
41
+ getString: (key: string) => string | null | undefined
42
+ set: (key: string, value: string) => void
43
+ }
44
+
45
+ const OUTBOX_KEY = 'rncs.outbox.v1'
46
+
47
+ /**
48
+ * Identity of a queued write: one entry per (provider, key).
49
+ *
50
+ * A single helper rather than a template literal at each site, because the two
51
+ * places that build it have to agree exactly - when they did not, a flush
52
+ * failed to recognise the entries it had just processed and wrote every one of
53
+ * them straight back, so a drained queue never shrank.
54
+ *
55
+ * The separator is an escaped NUL, which cannot appear in a provider name or a
56
+ * key, so the two halves can never run together and make two different pairs
57
+ * collide.
58
+ */
59
+ function outboxId(provider: ProviderName, key: string): string {
60
+ return `${provider}\u0000${key}`
61
+ }
62
+
63
+ const DEFAULT_OUTBOX_MAX_ENTRIES = 1000
64
+ const DEFAULT_OUTBOX_MAX_ATTEMPTS = 12
65
+ const DEFAULT_OUTBOX_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
66
+ const DEFAULT_AVAILABILITY_TTL_MS = 3_000
67
+
68
+ const BUILT_IN: Record<string, CloudProvider> = {
69
+ icloudKV,
70
+ cloudKit,
71
+ cloudKitEncrypted,
72
+ googleDrive,
73
+ }
74
+
75
+ export interface MigrateOptions {
76
+ from: ProviderName
77
+ to: ProviderName
78
+ /**
79
+ * Keep going when a single key fails instead of aborting the whole
80
+ * migration. Default true.
81
+ *
82
+ * A serial loop that throws on the first bad key leaves the user half
83
+ * migrated with no record of how far it got, which is the worst of both
84
+ * outcomes. The failures come back in the result instead.
85
+ */
86
+ continueOnError?: boolean
87
+ /** Only migrate keys this returns true for. */
88
+ filter?: (key: string) => boolean
89
+ /** Called after each key, for a progress bar over a long migration. */
90
+ onProgress?: (done: number, total: number) => void
91
+ }
92
+
93
+ export interface MigrateResult {
94
+ copied: string[]
95
+ /** Keys that held no value at the source and so had nothing to copy. */
96
+ skipped: string[]
97
+ /** Keys that could not be copied, with the reason for each. */
98
+ failed: { key: string; error: CloudSyncError }[]
99
+ }
100
+
101
+ export interface FlushResult {
102
+ drained: number
103
+ remaining: number
104
+ /** Entries abandoned during this flush. Also reported through `onDropped`. */
105
+ dropped: DroppedWrite[]
106
+ }
107
+
108
+ export interface CloudStore {
109
+ getItem: (key: string) => Promise<string | null>
110
+ setItem: (key: string, value: string) => Promise<void>
111
+ removeItem: (key: string) => Promise<void>
112
+ getAllKeys: () => Promise<string[]>
113
+
114
+ /** Reads many keys, batching per provider where the provider supports it. */
115
+ multiGet: (keys: string[]) => Promise<[string, string | null][]>
116
+ /** Writes many pairs, batching per destination. */
117
+ multiSet: (entries: [string, string][]) => Promise<void>
118
+ /** Removes many keys, batching per provider. */
119
+ multiRemove: (keys: string[]) => Promise<void>
120
+ /**
121
+ * Removes every key this store can see. Enumerated, not hardcoded - a
122
+ * "delete my data" flow that forgets a key has not deleted the user's data.
123
+ */
124
+ clear: () => Promise<{ removed: string[] }>
125
+
126
+ /**
127
+ * Every key and value the store can see, as one object.
128
+ *
129
+ * `getAllKeys()` followed by `multiGet()`, so it costs whatever those cost -
130
+ * one batched request per provider that batches, a loop where one does not.
131
+ * Here because it is the shape a debug screen or an export actually wants,
132
+ * and because every key-value library being migrated from has it.
133
+ */
134
+ getAllItems: () => Promise<Record<string, string>>
135
+
136
+ /** Per-provider storage usage, for the providers that report it. */
137
+ getQuota: () => Promise<QuotaInfo[]>
138
+
139
+ /** Copies every key from one provider to another. Does not delete the source. */
140
+ migrate: (opts: MigrateOptions) => Promise<MigrateResult>
141
+
142
+ /** Attempts to drain queued writes. Safe to call on reconnect or foreground. */
143
+ flushOutbox: () => Promise<FlushResult>
144
+ /** Entries still waiting, for surfacing a "pending sync" indicator. */
145
+ pendingWrites: () => OutboxEntry[]
146
+ /**
147
+ * Abandons queued writes, optionally only those matching `filter`. Returns
148
+ * how many were removed.
149
+ *
150
+ * The counterpart to `pendingWrites()`: a UI that can show a stuck write
151
+ * should be able to let the user give up on it.
152
+ */
153
+ discardPendingWrites: (filter?: (e: OutboxEntry) => boolean) => number
154
+
155
+ /** Registers an extra provider (e.g. the in-memory test double). */
156
+ registerProvider: (provider: CloudProvider) => void
157
+
158
+ /**
159
+ * Remote-change events from every configured provider, merged.
160
+ *
161
+ * Previously only the raw providers exposed this, so the facade - the
162
+ * recommended entry point - could not be subscribed to at all.
163
+ */
164
+ onRemoteChange: (listener: (e: RemoteChangeEvent) => void) => Unsubscribe
165
+ /**
166
+ * Account-change events from every configured provider, merged.
167
+ *
168
+ * The store also acts on these itself: an `identityChanged` event drops
169
+ * provider caches and abandons queued writes, because both belong to the
170
+ * account that just went away.
171
+ */
172
+ onAccountChange: (listener: (e: AccountChangeEvent) => void) => Unsubscribe
173
+
174
+ /** Releases the store's own provider subscriptions. */
175
+ dispose: () => void
176
+ }
177
+
178
+ export function createCloudStore(
179
+ options: CloudStoreOptions & { outboxStorage?: OutboxStorage }
180
+ ): CloudStore {
181
+ const custom = new Map<string, CloudProvider>()
182
+ const useOutbox = options.outbox ?? true
183
+ const writeMode = options.writeMode ?? 'failover'
184
+ const resolveValue = options.resolve
185
+ // Repair defaults on with a resolver: without it the losing store keeps its
186
+ // old value and every read has to resolve again, forever.
187
+ const repairOnRead = options.repairOnRead ?? (resolveValue != null)
188
+ const storage: OutboxStorage = options.outboxStorage ?? createMemoryOutboxStorage()
189
+ const codec: ValueCodec | null = options.codec ?? null
190
+ const validateKeys = options.validateKeys ?? true
191
+ const timeoutMs = options.timeoutMs
192
+ const availabilityTtlMs = options.availabilityTtlMs ?? DEFAULT_AVAILABILITY_TTL_MS
193
+ const maxEntries = options.outboxMaxEntries ?? DEFAULT_OUTBOX_MAX_ENTRIES
194
+ const maxAttempts = options.outboxMaxAttempts ?? DEFAULT_OUTBOX_MAX_ATTEMPTS
195
+ const maxAgeMs = options.outboxMaxAgeMs ?? DEFAULT_OUTBOX_MAX_AGE_MS
196
+
197
+ const tiering: TieringConfig | null
198
+ = options.tiering === 'off'
199
+ ? null
200
+ : options.tiering === 'auto' || options.tiering == null
201
+ ? DEFAULT_TIERING
202
+ : options.tiering
203
+
204
+ // ------------------------------------------------------------- providers
205
+
206
+ function resolveProvider(name: ProviderName): CloudProvider {
207
+ const found = custom.get(name) ?? BUILT_IN[name]
208
+ if (found == null)
209
+ throw new CloudSyncError(
210
+ ErrorCode.CONTAINER_MISCONFIGURED,
211
+ `[RNCloudSync] Unknown provider '${name}'. Register it with registerProvider() first.`
212
+ )
213
+
214
+ return found
215
+ }
216
+
217
+ /**
218
+ * Memoised `isAvailable()`.
219
+ *
220
+ * The store asks before every operation, and for `icloudKV` that is a bridge
221
+ * hop while for `googleDrive` it invokes the host's `getAccessToken`. A loop
222
+ * over 100 keys used to cost 100+ probes on top of the work itself. Held
223
+ * briefly, so a token expiring mid-session is still noticed quickly.
224
+ */
225
+ const availability = new Map<string, { at: number; ok: boolean }>()
226
+
227
+ async function isAvailable(p: CloudProvider): Promise<boolean> {
228
+ if (availabilityTtlMs <= 0) return probe(p)
229
+
230
+ const now = Date.now()
231
+ const cached = availability.get(p.name)
232
+ if (cached != null && now - cached.at < availabilityTtlMs) return cached.ok
233
+
234
+ const ok = await probe(p)
235
+ availability.set(p.name, { at: Date.now(), ok })
236
+ return ok
237
+ }
238
+
239
+ async function probe(p: CloudProvider): Promise<boolean> {
240
+ try {
241
+ return await run(p, () => p.isAvailable())
242
+ }
243
+ catch {
244
+ // `isAvailable` is documented as non-throwing, but a timeout wrapper or a
245
+ // third-party provider can still reject. Unavailable is the safe reading.
246
+ return false
247
+ }
248
+ }
249
+
250
+ function invalidateAvailability(): void {
251
+ availability.clear()
252
+ }
253
+
254
+ /** Applies the configured per-operation timeout, if any. */
255
+ function run<T>(p: CloudProvider, op: () => Promise<T>): Promise<T> {
256
+ if (timeoutMs == null) return op()
257
+ return withTimeout(op(), timeoutMs, p.name)
258
+ }
259
+
260
+ /**
261
+ * Every configured provider that is currently usable, in preference order.
262
+ *
263
+ * Ordering is preserved so `mirror` writes hit the preferred store first -
264
+ * if the process dies mid-write, the copy that landed is the one reads reach
265
+ * first.
266
+ */
267
+ async function allAvailable(): Promise<CloudProvider[]> {
268
+ const found: CloudProvider[] = []
269
+ for (const name of options.providers) {
270
+ const p = resolveProvider(name)
271
+ if (await isAvailable(p)) found.push(p)
272
+ }
273
+ return found
274
+ }
275
+
276
+ /** First configured+available provider, in the caller's preference order. */
277
+ async function primary(): Promise<CloudProvider> {
278
+ for (const name of options.providers) {
279
+ const p = resolveProvider(name)
280
+ if (await isAvailable(p)) return p
281
+ }
282
+ throw noneAvailable()
283
+ }
284
+
285
+ function noneAvailable(): CloudSyncError {
286
+ return new CloudSyncError(
287
+ ErrorCode.NOT_SIGNED_IN,
288
+ `[RNCloudSync] None of the configured providers (${options.providers.join(', ')}) `
289
+ + `is currently available.`
290
+ )
291
+ }
292
+
293
+ function checkKey(key: string): void {
294
+ if (validateKeys) assertKey(key, options.providers)
295
+ }
296
+
297
+ // ----------------------------------------------------------------- codec
298
+
299
+ async function encode(key: string, value: string): Promise<string> {
300
+ return codec == null ? value : await codec.encode(value, key)
301
+ }
302
+
303
+ async function decode(key: string, value: string): Promise<string> {
304
+ return codec == null ? value : await codec.decode(value, key)
305
+ }
306
+
307
+ // ---------------------------------------------------------------- outbox
308
+
309
+ function readOutbox(): OutboxEntry[] {
310
+ const raw = storage.getString(OUTBOX_KEY)
311
+ if (raw == null) return []
312
+ try {
313
+ const parsed: unknown = JSON.parse(raw)
314
+ return Array.isArray(parsed) ? (parsed as OutboxEntry[]) : []
315
+ }
316
+ catch {
317
+ return []
318
+ }
319
+ }
320
+
321
+ function writeOutbox(entries: OutboxEntry[]): void {
322
+ storage.set(OUTBOX_KEY, JSON.stringify(entries))
323
+ }
324
+
325
+ function reportDropped(entry: OutboxEntry, reason: DropReason, error?: CloudSyncError): void {
326
+ options.onDropped?.({ entry, reason, error })
327
+ }
328
+
329
+ function enqueue(
330
+ key: string,
331
+ value: string | null,
332
+ provider: ProviderName,
333
+ lastErrorCode?: string
334
+ ): void {
335
+ if (!useOutbox) return
336
+ const entries = readOutbox().filter(e => !(e.key === key && e.provider === provider))
337
+ entries.push({
338
+ key,
339
+ value,
340
+ provider,
341
+ attempts: 0,
342
+ nextAttemptAt: Date.now(),
343
+ enqueuedAt: Date.now(),
344
+ lastErrorCode,
345
+ })
346
+
347
+ // An unbounded queue is a slow leak: every enqueue rewrites the whole blob,
348
+ // so a long offline stretch degrades the write path itself. Drop the oldest
349
+ // and say so, rather than growing without limit or failing silently.
350
+ while (entries.length > maxEntries) {
351
+ const evicted = entries.shift()
352
+ if (evicted != null) reportDropped(evicted, 'queueFull')
353
+ }
354
+
355
+ writeOutbox(entries)
356
+ }
357
+
358
+ /**
359
+ * Forgets any queued write for this key/provider.
360
+ *
361
+ * Called after a *successful* direct write, and this is not an optimisation.
362
+ * Without it: an offline `setItem(k, v1)` queues v1, a later online
363
+ * `setItem(k, v2)` succeeds directly, and the next flush writes v1 back over
364
+ * v2. The queue has to be invalidated by the newer write that superseded it.
365
+ */
366
+ function dequeue(key: string, provider: ProviderName): void {
367
+ if (!useOutbox) return
368
+ const entries = readOutbox()
369
+ const kept = entries.filter(e => !(e.key === key && e.provider === provider))
370
+ if (kept.length !== entries.length) writeOutbox(kept)
371
+ }
372
+
373
+ function dequeueMany(keys: string[], provider: ProviderName): void {
374
+ if (!useOutbox || keys.length === 0) return
375
+ const drop = new Set(keys)
376
+ const entries = readOutbox()
377
+ const kept = entries.filter(e => !(drop.has(e.key) && e.provider === provider))
378
+ if (kept.length !== entries.length) writeOutbox(kept)
379
+ }
380
+
381
+ // ------------------------------------------------------------ size rules
382
+
383
+ /**
384
+ * The byte ceiling tiering imposes on a provider, or null when it imposes
385
+ * none. This is what routes a value to the right backing store by size.
386
+ *
387
+ * Both thresholds are honoured. Drive stores whole files and has no
388
+ * comparable small ceiling, so it is the destination of last resort.
389
+ */
390
+ function limitFor(provider: CloudProvider): number | null {
391
+ if (tiering == null) return null
392
+ if (provider.name === 'icloudKV') return tiering.kvMaxBytes
393
+ if (provider.name === 'cloudKit') return tiering.recordMaxBytes
394
+ return null
395
+ }
396
+
397
+ function canHold(provider: CloudProvider, value: string): boolean {
398
+ const limit = limitFor(provider)
399
+ return limit == null || byteLength(value) <= limit
400
+ }
401
+
402
+ /**
403
+ * Picks the destination for a `failover` write when the preferred provider is
404
+ * too small for the value.
405
+ *
406
+ * Candidates must be both large enough AND currently available: routing to a
407
+ * provider that is configured but unreachable just converts a size problem
408
+ * into a write failure.
409
+ */
410
+ async function providerForSize(
411
+ value: string,
412
+ preferred: CloudProvider
413
+ ): Promise<CloudProvider> {
414
+ if (canHold(preferred, value)) return preferred
415
+
416
+ const bytes = byteLength(value)
417
+ for (const name of options.providers) {
418
+ if (name === preferred.name) continue
419
+ const candidate = resolveProvider(name)
420
+ if (!canHold(candidate, value)) continue
421
+ if (!(await isAvailable(candidate))) continue
422
+ return candidate
423
+ }
424
+
425
+ throw new CloudSyncError(
426
+ ErrorCode.PAYLOAD_TOO_LARGE,
427
+ `[RNCloudSync] Value is ${bytes} bytes, above the ${limitFor(preferred)}-byte limit for `
428
+ + `'${preferred.name}', and no larger-capacity provider is configured and available. Add `
429
+ + `'cloudKit' or 'googleDrive' to providers.`,
430
+ { limitBytes: limitFor(preferred) ?? undefined, actualBytes: bytes, provider: preferred.name }
431
+ )
432
+ }
433
+
434
+ // ----------------------------------------------------------------- reads
435
+
436
+ async function readOne(p: CloudProvider, key: string): Promise<ItemWithMeta | null> {
437
+ if (p.getItemWithMeta != null) return await run(p, () => p.getItemWithMeta!(key))
438
+ const value = await run(p, () => p.getItem(key))
439
+ return value == null ? null : { value }
440
+ }
441
+
442
+ async function readBatch(p: CloudProvider, keys: string[]): Promise<(string | null)[]> {
443
+ if (p.multiGet != null) return await run(p, () => p.multiGet!(keys))
444
+
445
+ const out: (string | null)[] = []
446
+ for (const key of keys) out.push(await run(p, () => p.getItem(key)))
447
+ return out
448
+ }
449
+
450
+ async function writeBatch(p: CloudProvider, entries: [string, string][]): Promise<void> {
451
+ if (entries.length === 0) return
452
+ if (p.multiSet != null) {
453
+ await run(p, () => p.multiSet!(entries))
454
+ return
455
+ }
456
+ for (const [key, value] of entries) await run(p, () => p.setItem(key, value))
457
+ }
458
+
459
+ async function removeBatch(p: CloudProvider, keys: string[]): Promise<void> {
460
+ if (keys.length === 0) return
461
+ if (p.multiRemove != null) {
462
+ await run(p, () => p.multiRemove!(keys))
463
+ return
464
+ }
465
+ for (const key of keys) await run(p, () => p.removeItem(key))
466
+ }
467
+
468
+ // ---------------------------------------------------------------- writes
469
+
470
+ /** Single-destination write, queueing a retryable failure. */
471
+ async function writeOne(target: CloudProvider, key: string, value: string): Promise<void> {
472
+ try {
473
+ await run(target, () => target.setItem(key, value))
474
+ // This write supersedes anything queued for the same destination.
475
+ dequeue(key, target.name)
476
+ }
477
+ catch (e) {
478
+ const err = normalizeError(e, target.name)
479
+ if (useOutbox && isRetryable(err)) {
480
+ enqueue(key, value, target.name, err.code)
481
+ options.onError?.(err)
482
+ return
483
+ }
484
+ throw err
485
+ }
486
+ }
487
+
488
+ /**
489
+ * Removes a key from providers that are reachable but cannot hold this value.
490
+ *
491
+ * Without this, `mirror` plus tiering strands stale data: a value that grows
492
+ * past `kvMaxBytes` is written to CloudKit and Drive and *skipped* on the
493
+ * key-value store, which keeps the older, smaller copy. A read with no
494
+ * resolver prefers that provider and returns the stale value forever, and
495
+ * read repair never cleans it up because it applies the same size guard.
496
+ * The copy the value no longer fits in has to go.
497
+ */
498
+ async function evictWhereTooLarge(
499
+ targets: CloudProvider[],
500
+ key: string,
501
+ value: string
502
+ ): Promise<void> {
503
+ for (const target of targets) {
504
+ if (canHold(target, value)) continue
505
+ try {
506
+ await run(target, () => target.removeItem(key))
507
+ dequeue(key, target.name)
508
+ }
509
+ catch (e) {
510
+ // Best effort. A stale copy left behind is reported, not fatal - the
511
+ // value itself did land somewhere.
512
+ options.onError?.(normalizeError(e, target.name))
513
+ }
514
+ }
515
+ }
516
+
517
+ /**
518
+ * Mirrored write.
519
+ *
520
+ * Succeeds if at least one destination took the value, because one good copy
521
+ * plus a queued retry is a better outcome than rejecting a write the user has
522
+ * already been told about. Retryable failures go to the outbox per provider,
523
+ * so they converge without re-sending to the ones that already succeeded.
524
+ *
525
+ * Rejects only when nothing stored it - silence there would be the false
526
+ * success this package exists to avoid.
527
+ */
528
+ async function writeMany(targets: CloudProvider[], key: string, value: string): Promise<void> {
529
+ const eligible = targets.filter(t => canHold(t, value))
530
+
531
+ if (eligible.length === 0) {
532
+ if (targets.length === 0) throw noneAvailable()
533
+
534
+ // Every destination exists but the value is too large for all of them.
535
+ const bytes = byteLength(value)
536
+ const largest = targets
537
+ .map(limitFor)
538
+ .filter((n): n is number => n != null)
539
+ .reduce<number | undefined>((a, b) => (a == null || b > a ? b : a), undefined)
540
+ throw new CloudSyncError(
541
+ ErrorCode.PAYLOAD_TOO_LARGE,
542
+ `[RNCloudSync] Value is ${bytes} bytes and does not fit in any configured provider.`,
543
+ { actualBytes: bytes, limitBytes: largest }
544
+ )
545
+ }
546
+
547
+ let stored = 0
548
+ let fatal: CloudSyncError | null = null
549
+
550
+ for (const target of eligible)
551
+ try {
552
+ await run(target, () => target.setItem(key, value))
553
+ dequeue(key, target.name)
554
+ stored += 1
555
+ }
556
+ catch (e) {
557
+ const err = normalizeError(e, target.name)
558
+ if (useOutbox && isRetryable(err)) {
559
+ enqueue(key, value, target.name, err.code)
560
+ options.onError?.(err)
561
+ continue
562
+ }
563
+ fatal ??= err
564
+ options.onError?.(err)
565
+ }
566
+
567
+ // Only once the value has a home somewhere: dropping the old copy first
568
+ // would open a window in which the key exists nowhere.
569
+ if (stored > 0) await evictWhereTooLarge(targets, key, value)
570
+
571
+ // Nothing stored it and nothing was queued - that has to surface.
572
+ if (stored === 0 && fatal != null) throw fatal
573
+ }
574
+
575
+ /** Mirrored delete, with the same at-least-one rule. */
576
+ async function removeMany(targets: CloudProvider[], key: string): Promise<void> {
577
+ // Nothing to delete from is a failed delete, not a completed one. Without
578
+ // this, a mirrored `removeItem` with every provider unavailable resolved
579
+ // successfully having removed the key from nowhere - the same false success
580
+ // this package exists to avoid, and which `writeMany` already refuses.
581
+ if (targets.length === 0) throw noneAvailable()
582
+
583
+ let removed = 0
584
+ let fatal: CloudSyncError | null = null
585
+
586
+ for (const target of targets)
587
+ try {
588
+ await run(target, () => target.removeItem(key))
589
+ dequeue(key, target.name)
590
+ removed += 1
591
+ }
592
+ catch (e) {
593
+ const err = normalizeError(e, target.name)
594
+ if (useOutbox && isRetryable(err)) {
595
+ enqueue(key, null, target.name, err.code)
596
+ options.onError?.(err)
597
+ continue
598
+ }
599
+ fatal ??= err
600
+ options.onError?.(err)
601
+ }
602
+
603
+ if (removed === 0 && fatal != null) throw fatal
604
+ }
605
+
606
+ /**
607
+ * Writes the resolved value back to providers that disagreed, and to
608
+ * reachable providers that were missing it entirely.
609
+ *
610
+ * A provider the winner no longer fits in has its stale copy removed instead
611
+ * of being silently left holding it - see {@link evictWhereTooLarge}.
612
+ */
613
+ async function repair(
614
+ key: string,
615
+ winner: string,
616
+ candidates: ResolveCandidate[],
617
+ reachable: Map<ProviderName, CloudProvider>
618
+ ): Promise<void> {
619
+ const byProvider = new Map(candidates.map(c => [c.provider, c.value]))
620
+ const stored = await encode(key, winner)
621
+
622
+ for (const [name, provider] of reachable) {
623
+ if (byProvider.get(name) === winner) continue
624
+
625
+ if (!canHold(provider, stored)) {
626
+ if (!byProvider.has(name)) continue
627
+ try {
628
+ await run(provider, () => provider.removeItem(key))
629
+ }
630
+ catch (e) {
631
+ options.onError?.(normalizeError(e, name))
632
+ }
633
+ continue
634
+ }
635
+
636
+ try {
637
+ await run(provider, () => provider.setItem(key, stored))
638
+ }
639
+ catch (e) {
640
+ options.onError?.(normalizeError(e, name))
641
+ }
642
+ }
643
+ }
644
+
645
+ // ---------------------------------------------------------------- events
646
+
647
+ const remoteListeners = new Set<(e: RemoteChangeEvent) => void>()
648
+ const accountListeners = new Set<(e: AccountChangeEvent) => void>()
649
+ let providerSubscriptions: Unsubscribe[] | null = null
650
+ let flushing: Promise<FlushResult> | null = null
651
+
652
+ /**
653
+ * Subscribes to every configured provider exactly once, lazily.
654
+ *
655
+ * Lazy because `createCloudStore` is often called at module scope, before the
656
+ * native module or a Drive token exists, and eagerly subscribing there would
657
+ * resolve providers too early.
658
+ */
659
+ function ensureSubscribed(): void {
660
+ if (providerSubscriptions != null) return
661
+ providerSubscriptions = []
662
+
663
+ for (const name of options.providers) {
664
+ let p: CloudProvider
665
+ try {
666
+ p = resolveProvider(name)
667
+ }
668
+ catch {
669
+ // An unregistered provider is reported loudly by every other path;
670
+ // subscription should not be the thing that throws first.
671
+ continue
672
+ }
673
+
674
+ if (p.onRemoteChange != null)
675
+ providerSubscriptions.push(p.onRemoteChange((e) => {
676
+ for (const l of remoteListeners) l(e)
677
+ }))
678
+
679
+ if (p.onAccountChange != null)
680
+ providerSubscriptions.push(p.onAccountChange((e) => {
681
+ if (isDuplicateAccountEvent(e)) return
682
+ handleAccountChange(e)
683
+ for (const l of accountListeners) l(e)
684
+ }))
685
+ }
686
+ }
687
+
688
+ /**
689
+ * Collapses the same account event arriving from several providers at once.
690
+ *
691
+ * On Apple platforms `icloudKV` and `cloudKit` both listen to the same two
692
+ * system notifications and relabel them with their own provider name -
693
+ * correctly, because an Apple ID change matters to both. The consequence is
694
+ * that a store configured with both delivers one system event to app
695
+ * listeners twice.
696
+ *
697
+ * Deduplicated on the event's content rather than its provider, over a short
698
+ * window: the providers emit within the same tick, so anything that looks
699
+ * identical that soon after is the same underlying notification. A genuine
700
+ * second change of the same shape inside the window is vanishingly unlikely,
701
+ * and would only cost a repeat of work that is already idempotent.
702
+ */
703
+ const ACCOUNT_EVENT_DEDUPE_MS = 250
704
+ let lastAccountEvent: { key: string; at: number } | null = null
705
+
706
+ function isDuplicateAccountEvent(e: AccountChangeEvent): boolean {
707
+ const key = `${e.status}\u0000${String(e.identityChanged)}`
708
+ const now = Date.now()
709
+ const seen = lastAccountEvent != null
710
+ && lastAccountEvent.key === key
711
+ && now - lastAccountEvent.at < ACCOUNT_EVENT_DEDUPE_MS
712
+
713
+ lastAccountEvent = { key, at: now }
714
+ return seen
715
+ }
716
+
717
+ /**
718
+ * The store's own reaction to an account event.
719
+ *
720
+ * A different Apple ID or Google account is now signed in, so three pieces of
721
+ * state belong to somebody who is no longer here: memoised availability,
722
+ * whatever the providers cached (Drive file ids, CloudKit reachability), and
723
+ * the outbox. Queued writes are the dangerous one - an entry carries no
724
+ * account identity, so flushing after a switch would write the previous
725
+ * user's data into the new user's account.
726
+ */
727
+ function handleAccountChange(e: AccountChangeEvent): void {
728
+ invalidateAvailability()
729
+ if (!e.identityChanged) return
730
+
731
+ for (const name of options.providers)
732
+ try {
733
+ resolveProvider(name).clearCaches?.()
734
+ }
735
+ catch {
736
+ // Nothing to clear on a provider that will not resolve.
737
+ }
738
+
739
+ const pending = readOutbox()
740
+ if (pending.length === 0) return
741
+ writeOutbox([])
742
+ for (const entry of pending) reportDropped(entry, 'accountChanged')
743
+ }
744
+
745
+ // ------------------------------------------------------------------ read
746
+
747
+ /**
748
+ * Reads one key across the configured providers.
749
+ *
750
+ * Returns `{ found: false }` only when at least one provider was reachable
751
+ * and none of them held the key. When *nothing* was reachable the caller is
752
+ * told, because resolving `null` there is indistinguishable from "no such
753
+ * key" - and the documented first-launch recipe reacts to `null` by seeding
754
+ * empty state, which is how a signed-out user's real backup gets overwritten.
755
+ */
756
+ async function readAcross(
757
+ key: string
758
+ ): Promise<{ found: boolean; value: string | null; reachedAny: boolean }> {
759
+ let lastError: unknown = null
760
+ let reachedAny = false
761
+
762
+ // No resolver: first non-null wins and we stop looking. Cheap, and right
763
+ // when only one population of devices ever writes.
764
+ if (resolveValue == null) {
765
+ for (const name of options.providers) {
766
+ const p = resolveProvider(name)
767
+ try {
768
+ if (!(await isAvailable(p))) continue
769
+ const hit = await readOne(p, key)
770
+ reachedAny = true
771
+ if (hit != null) return { found: true, value: await decode(key, hit.value), reachedAny }
772
+ }
773
+ catch (e) {
774
+ lastError = e
775
+ }
776
+ }
777
+ if (lastError != null) throw normalizeError(lastError)
778
+ return { found: false, value: null, reachedAny }
779
+ }
780
+
781
+ // With a resolver: consult every available provider, because the first one
782
+ // holding a value is not necessarily holding the newest. This is what makes
783
+ // sync work in both directions across a mixed fleet.
784
+ const candidates: ResolveCandidate[] = []
785
+ const reachable = new Map<ProviderName, CloudProvider>()
786
+
787
+ for (const name of options.providers) {
788
+ const p = resolveProvider(name)
789
+ try {
790
+ if (!(await isAvailable(p))) continue
791
+ const hit = await readOne(p, key)
792
+ // Only a provider we actually read from is a repair target. Marking it
793
+ // reachable before the read meant a provider whose read merely failed
794
+ // - a transient network blip - was repaired too, overwriting whatever
795
+ // it held with another provider's value. If the copy we could not read
796
+ // was the newer one, that silently destroyed it.
797
+ reachable.set(p.name, p)
798
+ reachedAny = true
799
+ if (hit != null)
800
+ candidates.push({
801
+ provider: p.name,
802
+ value: await decode(key, hit.value),
803
+ modifiedAt: hit.modifiedAt,
804
+ })
805
+ }
806
+ catch (e) {
807
+ lastError = e
808
+ }
809
+ }
810
+
811
+ if (candidates.length === 0) {
812
+ if (lastError != null) throw normalizeError(lastError)
813
+ return { found: false, value: null, reachedAny }
814
+ }
815
+
816
+ const winner = resolveValue(candidates)
817
+ if (winner == null) return { found: false, value: null, reachedAny }
818
+
819
+ // Best-effort convergence. Never fails the read - the caller already has
820
+ // the right answer, and a failed repair only costs another resolve later.
821
+ if (repairOnRead) void repair(key, winner, candidates, reachable)
822
+
823
+ return { found: true, value: winner, reachedAny }
824
+ }
825
+
826
+ // ------------------------------------------------------------------ API
827
+
828
+ const store: CloudStore = {
829
+ getItem: async (key: string) => {
830
+ checkKey(key)
831
+ const result = await readAcross(key)
832
+ // Nothing was reachable, so this is not an absent key - it is an unknown
833
+ // one. Saying `null` here is the false negative the error contract exists
834
+ // to prevent.
835
+ if (!result.reachedAny) throw noneAvailable()
836
+ return result.found ? result.value : null
837
+ },
838
+
839
+ setItem: async (key: string, value: string) => {
840
+ checkKey(key)
841
+ const stored = await encode(key, value)
842
+
843
+ if (writeMode === 'failover') {
844
+ const target = await providerForSize(stored, await primary())
845
+ await writeOne(target, key, stored)
846
+ return
847
+ }
848
+ await writeMany(await allAvailable(), key, stored)
849
+ },
850
+
851
+ removeItem: async (key: string) => {
852
+ checkKey(key)
853
+ // A mirrored write must be a mirrored delete. Removing from only the
854
+ // preferred provider would leave a copy behind that reads then fall
855
+ // through to and resurrect.
856
+ const targets = writeMode === 'mirror' ? await allAvailable() : [await primary()]
857
+ await removeMany(targets, key)
858
+ },
859
+
860
+ getAllKeys: async () => {
861
+ const seen = new Set<string>()
862
+ for (const name of options.providers) {
863
+ const p = resolveProvider(name)
864
+ try {
865
+ if (!(await isAvailable(p))) continue
866
+ for (const k of await run(p, () => p.getAllKeys())) seen.add(k)
867
+ }
868
+ catch {
869
+ // A provider that cannot list should not hide the ones that can.
870
+ }
871
+ }
872
+ return [...seen]
873
+ },
874
+
875
+ multiGet: async (keys: string[]) => {
876
+ for (const key of keys) checkKey(key)
877
+ if (keys.length === 0) return []
878
+
879
+ const answers = new Map<string, string | null>()
880
+
881
+ // A resolving read has to see every provider's copy of every key, so
882
+ // there is no early exit to exploit - but each provider is still a single
883
+ // batched request rather than one per key.
884
+ if (resolveValue != null) {
885
+ const perKey = new Map<string, ResolveCandidate[]>(keys.map(k => [k, []]))
886
+ let reachedAny = false
887
+
888
+ for (const name of options.providers) {
889
+ const p = resolveProvider(name)
890
+ try {
891
+ if (!(await isAvailable(p))) continue
892
+ const values = await readBatch(p, keys)
893
+ reachedAny = true
894
+ for (let i = 0; i < keys.length; i += 1) {
895
+ const raw = values[i]
896
+ if (raw == null) continue
897
+ perKey.get(keys[i])!.push({ provider: p.name, value: await decode(keys[i], raw) })
898
+ }
899
+ }
900
+ catch {
901
+ // Same rule as `getAllKeys`: one provider failing to answer must not
902
+ // erase the answers the others gave.
903
+ }
904
+ }
905
+
906
+ if (!reachedAny) throw noneAvailable()
907
+ for (const key of keys) {
908
+ const candidates = perKey.get(key)!
909
+ answers.set(key, candidates.length === 0 ? null : resolveValue(candidates))
910
+ }
911
+ return keys.map(k => [k, answers.get(k) ?? null] as [string, string | null])
912
+ }
913
+
914
+ // No resolver: ask each provider only for the keys still unanswered, so a
915
+ // second provider is consulted for the tail rather than for everything.
916
+ let outstanding = [...keys]
917
+ let reachedAny = false
918
+
919
+ for (const name of options.providers) {
920
+ if (outstanding.length === 0) break
921
+ const p = resolveProvider(name)
922
+ try {
923
+ if (!(await isAvailable(p))) continue
924
+ const values = await readBatch(p, outstanding)
925
+ reachedAny = true
926
+ const stillMissing: string[] = []
927
+ for (let i = 0; i < outstanding.length; i += 1) {
928
+ const raw = values[i]
929
+ if (raw == null) stillMissing.push(outstanding[i])
930
+ else answers.set(outstanding[i], await decode(outstanding[i], raw))
931
+ }
932
+ outstanding = stillMissing
933
+ }
934
+ catch {
935
+ // Leave those keys outstanding for the next provider.
936
+ }
937
+ }
938
+
939
+ if (!reachedAny) throw noneAvailable()
940
+ return keys.map(k => [k, answers.get(k) ?? null] as [string, string | null])
941
+ },
942
+
943
+ multiSet: async (entries: [string, string][]) => {
944
+ for (const [key] of entries) checkKey(key)
945
+ if (entries.length === 0) return
946
+
947
+ const encoded: [string, string][] = []
948
+ for (const [key, value] of entries) encoded.push([key, await encode(key, value)])
949
+
950
+ if (writeMode === 'failover') {
951
+ // Tiering can route two values in the same batch to two different
952
+ // providers, so group by destination rather than assuming one target.
953
+ const preferred = await primary()
954
+ const byTarget = new Map<string, { provider: CloudProvider; items: [string, string][] }>()
955
+
956
+ for (const [key, value] of encoded) {
957
+ const target = await providerForSize(value, preferred)
958
+ const bucket = byTarget.get(target.name)
959
+ ?? { provider: target, items: [] as [string, string][] }
960
+ bucket.items.push([key, value])
961
+ byTarget.set(target.name, bucket)
962
+ }
963
+
964
+ for (const { provider, items } of byTarget.values())
965
+ try {
966
+ await writeBatch(provider, items)
967
+ dequeueMany(items.map(([k]) => k), provider.name)
968
+ }
969
+ catch (e) {
970
+ const err = normalizeError(e, provider.name)
971
+ if (useOutbox && isRetryable(err)) {
972
+ for (const [key, value] of items) enqueue(key, value, provider.name, err.code)
973
+ options.onError?.(err)
974
+ continue
975
+ }
976
+ throw err
977
+ }
978
+ return
979
+ }
980
+
981
+ const targets = await allAvailable()
982
+ if (targets.length === 0) throw noneAvailable()
983
+
984
+ let anyStored = false
985
+ let fatal: CloudSyncError | null = null
986
+
987
+ for (const target of targets) {
988
+ const fits = encoded.filter(([, value]) => canHold(target, value))
989
+ if (fits.length === 0) continue
990
+ try {
991
+ await writeBatch(target, fits)
992
+ dequeueMany(fits.map(([k]) => k), target.name)
993
+ anyStored = true
994
+ }
995
+ catch (e) {
996
+ const err = normalizeError(e, target.name)
997
+ if (useOutbox && isRetryable(err)) {
998
+ for (const [key, value] of fits) enqueue(key, value, target.name, err.code)
999
+ options.onError?.(err)
1000
+ continue
1001
+ }
1002
+ fatal ??= err
1003
+ options.onError?.(err)
1004
+ }
1005
+ }
1006
+
1007
+ if (anyStored)
1008
+ for (const [key, value] of encoded) await evictWhereTooLarge(targets, key, value)
1009
+
1010
+ if (!anyStored && fatal != null) throw fatal
1011
+ if (!anyStored && fatal == null) {
1012
+ const bytes = Math.max(...encoded.map(([, v]) => byteLength(v)))
1013
+ throw new CloudSyncError(
1014
+ ErrorCode.PAYLOAD_TOO_LARGE,
1015
+ `[RNCloudSync] No configured provider can hold these values (largest is ${bytes} bytes).`,
1016
+ { actualBytes: bytes }
1017
+ )
1018
+ }
1019
+ },
1020
+
1021
+ multiRemove: async (keys: string[]) => {
1022
+ for (const key of keys) checkKey(key)
1023
+ if (keys.length === 0) return
1024
+
1025
+ const targets = writeMode === 'mirror' ? await allAvailable() : [await primary()]
1026
+ if (targets.length === 0) throw noneAvailable()
1027
+
1028
+ let removedAnywhere = false
1029
+ let fatal: CloudSyncError | null = null
1030
+
1031
+ for (const target of targets)
1032
+ try {
1033
+ await removeBatch(target, keys)
1034
+ dequeueMany(keys, target.name)
1035
+ removedAnywhere = true
1036
+ }
1037
+ catch (e) {
1038
+ const err = normalizeError(e, target.name)
1039
+ if (useOutbox && isRetryable(err)) {
1040
+ for (const key of keys) enqueue(key, null, target.name, err.code)
1041
+ options.onError?.(err)
1042
+ continue
1043
+ }
1044
+ fatal ??= err
1045
+ options.onError?.(err)
1046
+ }
1047
+
1048
+ if (!removedAnywhere && fatal != null) throw fatal
1049
+ },
1050
+
1051
+ clear: async () => {
1052
+ const keys = await store.getAllKeys()
1053
+ if (keys.length === 0) return { removed: [] }
1054
+ await store.multiRemove(keys)
1055
+ return { removed: keys }
1056
+ },
1057
+
1058
+ getAllItems: async () => {
1059
+ const keys = await store.getAllKeys()
1060
+ if (keys.length === 0) return {}
1061
+
1062
+ const out: Record<string, string> = {}
1063
+ for (const [key, value] of await store.multiGet(keys))
1064
+ if (value != null) out[key] = value
1065
+
1066
+ return out
1067
+ },
1068
+
1069
+ getQuota: async () => {
1070
+ const out: QuotaInfo[] = []
1071
+ for (const name of options.providers) {
1072
+ const p = resolveProvider(name)
1073
+ if (p.getQuota == null) continue
1074
+ try {
1075
+ if (!(await isAvailable(p))) continue
1076
+ const quota = await run(p, () => p.getQuota!())
1077
+ if (quota != null) out.push(quota)
1078
+ }
1079
+ catch (e) {
1080
+ options.onError?.(normalizeError(e, name))
1081
+ }
1082
+ }
1083
+ return out
1084
+ },
1085
+
1086
+ migrate: async ({ from, to, continueOnError = true, filter, onProgress }) => {
1087
+ const src = resolveProvider(from)
1088
+ const dst = resolveProvider(to)
1089
+ const all = await run(src, () => src.getAllKeys())
1090
+ const keys = filter == null ? all : all.filter(filter)
1091
+
1092
+ const copied: string[] = []
1093
+ const skipped: string[] = []
1094
+ const failed: { key: string; error: CloudSyncError }[] = []
1095
+
1096
+ // Values move verbatim. Both ends sit behind the same codec, so decoding
1097
+ // on the way out only to re-encode on the way in would be wasted work -
1098
+ // and, for a codec with a random nonce, would rewrite every byte.
1099
+ for (const key of keys) {
1100
+ try {
1101
+ const value = await run(src, () => src.getItem(key))
1102
+ if (value == null) {
1103
+ skipped.push(key)
1104
+ }
1105
+ else {
1106
+ await run(dst, () => dst.setItem(key, value))
1107
+ copied.push(key)
1108
+ }
1109
+ }
1110
+ catch (e) {
1111
+ const err = normalizeError(e, from)
1112
+ failed.push({ key, error: err })
1113
+ options.onError?.(err)
1114
+ // Aborting on the first bad key leaves the user half migrated with no
1115
+ // record of how far it got, which is the worst of both outcomes.
1116
+ if (!continueOnError) break
1117
+ }
1118
+ onProgress?.(copied.length + skipped.length + failed.length, keys.length)
1119
+ }
1120
+
1121
+ return { copied, skipped, failed }
1122
+ },
1123
+
1124
+ flushOutbox: async () => {
1125
+ // Two flushes at once - a reconnect and a foreground firing together -
1126
+ // would each snapshot the queue and each re-send every entry in it.
1127
+ if (flushing != null) return await flushing
1128
+ flushing = drain().finally(() => {
1129
+ flushing = null
1130
+ })
1131
+ return await flushing
1132
+ },
1133
+
1134
+ pendingWrites: () => readOutbox(),
1135
+
1136
+ discardPendingWrites: (filter) => {
1137
+ const entries = readOutbox()
1138
+ const kept: OutboxEntry[] = []
1139
+ const removed: OutboxEntry[] = []
1140
+ for (const entry of entries)
1141
+ if (filter == null || filter(entry)) removed.push(entry)
1142
+ else kept.push(entry)
1143
+
1144
+ if (removed.length === 0) return 0
1145
+ writeOutbox(kept)
1146
+ for (const entry of removed) reportDropped(entry, 'discarded')
1147
+ return removed.length
1148
+ },
1149
+
1150
+ registerProvider: (provider: CloudProvider) => {
1151
+ custom.set(provider.name, provider)
1152
+ availability.delete(provider.name)
1153
+ // A provider registered after the first subscription would otherwise
1154
+ // never be listened to. Cheapest correct fix is to resubscribe.
1155
+ if (providerSubscriptions != null) {
1156
+ for (const un of providerSubscriptions) un()
1157
+ providerSubscriptions = null
1158
+ if (remoteListeners.size > 0 || accountListeners.size > 0) ensureSubscribed()
1159
+ }
1160
+ },
1161
+
1162
+ onRemoteChange: (listener) => {
1163
+ ensureSubscribed()
1164
+ remoteListeners.add(listener)
1165
+ return () => {
1166
+ remoteListeners.delete(listener)
1167
+ }
1168
+ },
1169
+
1170
+ onAccountChange: (listener) => {
1171
+ ensureSubscribed()
1172
+ accountListeners.add(listener)
1173
+ return () => {
1174
+ accountListeners.delete(listener)
1175
+ }
1176
+ },
1177
+
1178
+ dispose: () => {
1179
+ if (providerSubscriptions != null) for (const un of providerSubscriptions) un()
1180
+ providerSubscriptions = null
1181
+ remoteListeners.clear()
1182
+ accountListeners.clear()
1183
+ detachAutoFlush?.()
1184
+ detachAutoFlush = null
1185
+ },
1186
+ }
1187
+
1188
+ // Attached last, so the store it flushes is fully built by the time the first
1189
+ // foreground event or timer tick can reach it.
1190
+ let detachAutoFlush: Unsubscribe | null = null
1191
+ if (options.autoFlush != null && options.autoFlush !== false)
1192
+ detachAutoFlush = attachAutoFlush(
1193
+ () => store.flushOutbox(),
1194
+ options.autoFlush === true ? {} : options.autoFlush
1195
+ )
1196
+
1197
+ async function drain(): Promise<FlushResult> {
1198
+ const entries = readOutbox()
1199
+ if (entries.length === 0) return { drained: 0, remaining: 0, dropped: [] }
1200
+
1201
+ const now = Date.now()
1202
+ const keep: OutboxEntry[] = []
1203
+ const dropped: DroppedWrite[] = []
1204
+ const handled = new Set<string>()
1205
+ let drained = 0
1206
+
1207
+ function drop(entry: OutboxEntry, reason: DropReason, error?: CloudSyncError): void {
1208
+ dropped.push({ entry, reason, error })
1209
+ reportDropped(entry, reason, error)
1210
+ }
1211
+
1212
+ for (const entry of entries) {
1213
+ handled.add(outboxId(entry.provider, entry.key))
1214
+
1215
+ if (now - entry.enqueuedAt > maxAgeMs) {
1216
+ drop(entry, 'expired')
1217
+ continue
1218
+ }
1219
+ if (entry.nextAttemptAt > now) {
1220
+ keep.push(entry)
1221
+ continue
1222
+ }
1223
+
1224
+ let p: CloudProvider
1225
+ try {
1226
+ p = resolveProvider(entry.provider)
1227
+ }
1228
+ catch (e) {
1229
+ // The provider it targeted is gone. Nothing will ever drain this.
1230
+ drop(entry, 'notRetryable', normalizeError(e, entry.provider))
1231
+ continue
1232
+ }
1233
+
1234
+ try {
1235
+ if (entry.value == null) await run(p, () => p.removeItem(entry.key))
1236
+ else await run(p, () => p.setItem(entry.key, entry.value!))
1237
+ drained += 1
1238
+ }
1239
+ catch (e) {
1240
+ const err = normalizeError(e, entry.provider)
1241
+ options.onError?.(err)
1242
+
1243
+ // A write only enters the queue for a retryable reason. If retrying it
1244
+ // now fails for one the user must act on - quota, signed out, a payload
1245
+ // the store will never accept - re-queueing turns it into a poison
1246
+ // entry that retries forever, never drains, and never surfaces.
1247
+ if (!isRetryable(err)) {
1248
+ drop(entry, 'notRetryable', err)
1249
+ continue
1250
+ }
1251
+
1252
+ const attempts = entry.attempts + 1
1253
+ if (attempts >= maxAttempts) {
1254
+ drop({ ...entry, attempts, lastErrorCode: err.code }, 'tooManyAttempts', err)
1255
+ continue
1256
+ }
1257
+
1258
+ // Exponential backoff, honouring a server-supplied retry hint when
1259
+ // there is one (CloudKit sends `retryAfter`, Drive `Retry-After`).
1260
+ const backoff = err.retryAfterMs ?? Math.min(2 ** attempts * 1000, 5 * 60_000)
1261
+ keep.push({
1262
+ ...entry,
1263
+ attempts,
1264
+ nextAttemptAt: Date.now() + backoff,
1265
+ lastErrorCode: err.code,
1266
+ })
1267
+ }
1268
+ }
1269
+
1270
+ // Merge rather than overwrite. A `setItem` that failed while this flush was
1271
+ // awaiting the network enqueued itself into storage; writing the snapshot
1272
+ // back wholesale would silently discard it.
1273
+ const arrived = readOutbox().filter(e => !handled.has(outboxId(e.provider, e.key)))
1274
+ writeOutbox([...keep, ...arrived])
1275
+
1276
+ return { drained, remaining: keep.length + arrived.length, dropped }
1277
+ }
1278
+
1279
+ return store
1280
+ }
1281
+
1282
+ function createMemoryOutboxStorage(): OutboxStorage {
1283
+ const map = new Map<string, string>()
1284
+ return {
1285
+ getString: (k: string) => map.get(k),
1286
+ set: (k: string, v: string) => { map.set(k, v) },
1287
+ }
1288
+ }