react-native-cloud-sync 0.4.0 → 0.5.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 (160) hide show
  1. package/README.md +18 -0
  2. package/ios/CloudSyncError.swift +21 -0
  3. package/ios/CloudSyncImpl.swift +515 -95
  4. package/ios/RNCloudSync.mm +73 -1
  5. package/jest-mock.js +1 -0
  6. package/lib/commonjs/hooks.js +73 -9
  7. package/lib/commonjs/hooks.js.map +1 -1
  8. package/lib/commonjs/internal/autoFlush.js +10 -1
  9. package/lib/commonjs/internal/autoFlush.js.map +1 -1
  10. package/lib/commonjs/internal/base64.js +25 -5
  11. package/lib/commonjs/internal/base64.js.map +1 -1
  12. package/lib/commonjs/internal/cloudKitRest.js +91 -15
  13. package/lib/commonjs/internal/cloudKitRest.js.map +1 -1
  14. package/lib/commonjs/internal/googleDriveRest.js +304 -38
  15. package/lib/commonjs/internal/googleDriveRest.js.map +1 -1
  16. package/lib/commonjs/internal/keys.js +34 -17
  17. package/lib/commonjs/internal/keys.js.map +1 -1
  18. package/lib/commonjs/internal/records.js +48 -0
  19. package/lib/commonjs/internal/records.js.map +1 -0
  20. package/lib/commonjs/providers/cloudKit.js +85 -17
  21. package/lib/commonjs/providers/cloudKit.js.map +1 -1
  22. package/lib/commonjs/providers/cloudKitEncrypted.js +30 -7
  23. package/lib/commonjs/providers/cloudKitEncrypted.js.map +1 -1
  24. package/lib/commonjs/providers/googleDrive.js +37 -2
  25. package/lib/commonjs/providers/googleDrive.js.map +1 -1
  26. package/lib/commonjs/providers/icloudDocuments.js +27 -0
  27. package/lib/commonjs/providers/icloudDocuments.js.map +1 -1
  28. package/lib/commonjs/providers/icloudKV.js +13 -3
  29. package/lib/commonjs/providers/icloudKV.js.map +1 -1
  30. package/lib/commonjs/providers/icloudKV.web.js +8 -1
  31. package/lib/commonjs/providers/icloudKV.web.js.map +1 -1
  32. package/lib/commonjs/providers/memory.js +10 -0
  33. package/lib/commonjs/providers/memory.js.map +1 -1
  34. package/lib/commonjs/resolvers.js +27 -13
  35. package/lib/commonjs/resolvers.js.map +1 -1
  36. package/lib/commonjs/specs/NativeRNCloudSync.js +3 -0
  37. package/lib/commonjs/specs/NativeRNCloudSync.js.map +1 -1
  38. package/lib/commonjs/store.js +360 -173
  39. package/lib/commonjs/store.js.map +1 -1
  40. package/lib/commonjs/types.js.map +1 -1
  41. package/lib/module/hooks.js +73 -9
  42. package/lib/module/hooks.js.map +1 -1
  43. package/lib/module/internal/autoFlush.js +10 -1
  44. package/lib/module/internal/autoFlush.js.map +1 -1
  45. package/lib/module/internal/base64.js +25 -5
  46. package/lib/module/internal/base64.js.map +1 -1
  47. package/lib/module/internal/cloudKitRest.js +89 -13
  48. package/lib/module/internal/cloudKitRest.js.map +1 -1
  49. package/lib/module/internal/googleDriveRest.js +304 -38
  50. package/lib/module/internal/googleDriveRest.js.map +1 -1
  51. package/lib/module/internal/keys.js +33 -17
  52. package/lib/module/internal/keys.js.map +1 -1
  53. package/lib/module/internal/records.js +41 -0
  54. package/lib/module/internal/records.js.map +1 -0
  55. package/lib/module/providers/cloudKit.js +86 -18
  56. package/lib/module/providers/cloudKit.js.map +1 -1
  57. package/lib/module/providers/cloudKitEncrypted.js +31 -8
  58. package/lib/module/providers/cloudKitEncrypted.js.map +1 -1
  59. package/lib/module/providers/googleDrive.js +37 -2
  60. package/lib/module/providers/googleDrive.js.map +1 -1
  61. package/lib/module/providers/icloudDocuments.js +28 -1
  62. package/lib/module/providers/icloudDocuments.js.map +1 -1
  63. package/lib/module/providers/icloudKV.js +13 -3
  64. package/lib/module/providers/icloudKV.js.map +1 -1
  65. package/lib/module/providers/icloudKV.web.js +8 -1
  66. package/lib/module/providers/icloudKV.web.js.map +1 -1
  67. package/lib/module/providers/memory.js +10 -0
  68. package/lib/module/providers/memory.js.map +1 -1
  69. package/lib/module/resolvers.js +27 -12
  70. package/lib/module/resolvers.js.map +1 -1
  71. package/lib/module/specs/NativeRNCloudSync.js +4 -0
  72. package/lib/module/specs/NativeRNCloudSync.js.map +1 -1
  73. package/lib/module/store.js +360 -173
  74. package/lib/module/store.js.map +1 -1
  75. package/lib/module/types.js.map +1 -1
  76. package/lib/typescript/commonjs/errors.d.ts +16 -16
  77. package/lib/typescript/commonjs/errors.d.ts.map +1 -1
  78. package/lib/typescript/commonjs/hooks.d.ts.map +1 -1
  79. package/lib/typescript/commonjs/internal/autoFlush.d.ts.map +1 -1
  80. package/lib/typescript/commonjs/internal/base64.d.ts.map +1 -1
  81. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts +20 -0
  82. package/lib/typescript/commonjs/internal/cloudKitRest.d.ts.map +1 -1
  83. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts +19 -0
  84. package/lib/typescript/commonjs/internal/googleDriveRest.d.ts.map +1 -1
  85. package/lib/typescript/commonjs/internal/keys.d.ts +18 -3
  86. package/lib/typescript/commonjs/internal/keys.d.ts.map +1 -1
  87. package/lib/typescript/commonjs/internal/records.d.ts +24 -0
  88. package/lib/typescript/commonjs/internal/records.d.ts.map +1 -0
  89. package/lib/typescript/commonjs/providers/cloudKit.d.ts +1 -1
  90. package/lib/typescript/commonjs/providers/cloudKit.d.ts.map +1 -1
  91. package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts +1 -1
  92. package/lib/typescript/commonjs/providers/cloudKitBackup.d.ts.map +1 -1
  93. package/lib/typescript/commonjs/providers/cloudKitEncrypted.d.ts.map +1 -1
  94. package/lib/typescript/commonjs/providers/googleDrive.d.ts.map +1 -1
  95. package/lib/typescript/commonjs/providers/googleDriveFiles.d.ts.map +1 -1
  96. package/lib/typescript/commonjs/providers/icloudDocuments.d.ts +1 -1
  97. package/lib/typescript/commonjs/providers/icloudDocuments.d.ts.map +1 -1
  98. package/lib/typescript/commonjs/providers/icloudKV.d.ts.map +1 -1
  99. package/lib/typescript/commonjs/providers/icloudKV.web.d.ts.map +1 -1
  100. package/lib/typescript/commonjs/providers/memory.d.ts.map +1 -1
  101. package/lib/typescript/commonjs/resolvers.d.ts +6 -3
  102. package/lib/typescript/commonjs/resolvers.d.ts.map +1 -1
  103. package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts +12 -3
  104. package/lib/typescript/commonjs/specs/NativeRNCloudSync.d.ts.map +1 -1
  105. package/lib/typescript/commonjs/store.d.ts.map +1 -1
  106. package/lib/typescript/commonjs/types.d.ts +31 -3
  107. package/lib/typescript/commonjs/types.d.ts.map +1 -1
  108. package/lib/typescript/module/errors.d.ts +16 -16
  109. package/lib/typescript/module/errors.d.ts.map +1 -1
  110. package/lib/typescript/module/hooks.d.ts.map +1 -1
  111. package/lib/typescript/module/internal/autoFlush.d.ts.map +1 -1
  112. package/lib/typescript/module/internal/base64.d.ts.map +1 -1
  113. package/lib/typescript/module/internal/cloudKitRest.d.ts +20 -0
  114. package/lib/typescript/module/internal/cloudKitRest.d.ts.map +1 -1
  115. package/lib/typescript/module/internal/googleDriveRest.d.ts +19 -0
  116. package/lib/typescript/module/internal/googleDriveRest.d.ts.map +1 -1
  117. package/lib/typescript/module/internal/keys.d.ts +18 -3
  118. package/lib/typescript/module/internal/keys.d.ts.map +1 -1
  119. package/lib/typescript/module/internal/records.d.ts +24 -0
  120. package/lib/typescript/module/internal/records.d.ts.map +1 -0
  121. package/lib/typescript/module/providers/cloudKit.d.ts +1 -1
  122. package/lib/typescript/module/providers/cloudKit.d.ts.map +1 -1
  123. package/lib/typescript/module/providers/cloudKitBackup.d.ts +1 -1
  124. package/lib/typescript/module/providers/cloudKitBackup.d.ts.map +1 -1
  125. package/lib/typescript/module/providers/cloudKitEncrypted.d.ts.map +1 -1
  126. package/lib/typescript/module/providers/googleDrive.d.ts.map +1 -1
  127. package/lib/typescript/module/providers/googleDriveFiles.d.ts.map +1 -1
  128. package/lib/typescript/module/providers/icloudDocuments.d.ts +1 -1
  129. package/lib/typescript/module/providers/icloudDocuments.d.ts.map +1 -1
  130. package/lib/typescript/module/providers/icloudKV.d.ts.map +1 -1
  131. package/lib/typescript/module/providers/icloudKV.web.d.ts.map +1 -1
  132. package/lib/typescript/module/providers/memory.d.ts.map +1 -1
  133. package/lib/typescript/module/resolvers.d.ts +6 -3
  134. package/lib/typescript/module/resolvers.d.ts.map +1 -1
  135. package/lib/typescript/module/specs/NativeRNCloudSync.d.ts +12 -3
  136. package/lib/typescript/module/specs/NativeRNCloudSync.d.ts.map +1 -1
  137. package/lib/typescript/module/store.d.ts.map +1 -1
  138. package/lib/typescript/module/types.d.ts +31 -3
  139. package/lib/typescript/module/types.d.ts.map +1 -1
  140. package/package.json +35 -25
  141. package/plugin/build/index.js +45 -13
  142. package/react-native-cloud-sync.podspec +10 -3
  143. package/src/hooks.ts +69 -9
  144. package/src/internal/autoFlush.ts +10 -1
  145. package/src/internal/base64.ts +26 -5
  146. package/src/internal/cloudKitRest.ts +103 -14
  147. package/src/internal/googleDriveRest.ts +338 -37
  148. package/src/internal/keys.ts +42 -16
  149. package/src/internal/records.ts +38 -0
  150. package/src/providers/cloudKit.ts +96 -20
  151. package/src/providers/cloudKitEncrypted.ts +37 -8
  152. package/src/providers/googleDrive.ts +38 -2
  153. package/src/providers/icloudDocuments.ts +40 -2
  154. package/src/providers/icloudKV.ts +13 -3
  155. package/src/providers/icloudKV.web.ts +8 -2
  156. package/src/providers/memory.ts +8 -0
  157. package/src/resolvers.ts +28 -13
  158. package/src/specs/NativeRNCloudSync.ts +16 -2
  159. package/src/store.ts +433 -190
  160. package/src/types.ts +32 -3
@@ -12,6 +12,7 @@ var _bytes = require("./internal/bytes.js");
12
12
  var _keys = require("./internal/keys.js");
13
13
  var _timeout = require("./internal/timeout.js");
14
14
  var _autoFlush = require("./internal/autoFlush.js");
15
+ var _records = require("./internal/records.js");
15
16
  var _errors = require("./errors.js");
16
17
  var _types = require("./types.js");
17
18
  /**
@@ -30,20 +31,16 @@ var _types = require("./types.js");
30
31
  const OUTBOX_KEY = 'rncs.outbox.v1';
31
32
 
32
33
  /**
33
- * Identity of a queued write: one entry per (provider, key).
34
+ * Providers whose queued writes are never handed to `outboxStorage`.
34
35
  *
35
- * A single helper rather than a template literal at each site, because the two
36
- * places that build it have to agree exactly - when they did not, a flush
37
- * failed to recognise the entries it had just processed and wrote every one of
38
- * them straight back, so a drained queue never shrank.
39
- *
40
- * The separator is an escaped NUL, which cannot appear in a provider name or a
41
- * key, so the two halves can never run together and make two different pairs
42
- * collide.
36
+ * `cloudKitEncrypted` encrypts on device, inside the native layer, so the value
37
+ * the store hands it is the app's plaintext. Persisting a failed write to the
38
+ * durable outbox - typically an unencrypted MMKV or AsyncStorage file - would
39
+ * leave exactly the data the app chose end-to-end encryption for sitting on
40
+ * disk in the clear, for up to `outboxMaxAgeMs`. Those entries are queued in
41
+ * memory instead: retried for as long as the process lives, lost on restart.
43
42
  */
44
- function outboxId(provider, key) {
45
- return `${provider}\u0000${key}`;
46
- }
43
+ const MEMORY_ONLY_OUTBOX_PROVIDERS = new Set(['cloudKitEncrypted']);
47
44
  const DEFAULT_OUTBOX_MAX_ENTRIES = 1000;
48
45
  const DEFAULT_OUTBOX_MAX_ATTEMPTS = 12;
49
46
  const DEFAULT_OUTBOX_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
@@ -162,18 +159,44 @@ function createCloudStore(options) {
162
159
 
163
160
  // ---------------------------------------------------------------- outbox
164
161
 
162
+ /** Queued writes that must not reach durable storage - see {@link MEMORY_ONLY_OUTBOX_PROVIDERS}. */
163
+ let volatileOutbox = [];
165
164
  function readOutbox() {
165
+ return [...readDurableOutbox(), ...volatileOutbox];
166
+ }
167
+ function readDurableOutbox() {
166
168
  const raw = storage.getString(OUTBOX_KEY);
167
169
  if (raw == null) return [];
168
170
  try {
169
171
  const parsed = JSON.parse(raw);
170
- return Array.isArray(parsed) ? parsed : [];
172
+ // Entry by entry: one malformed record in a shared storage file must not
173
+ // throw on every later write path that reads the queue.
174
+ return Array.isArray(parsed) ? parsed.filter(isOutboxEntry).filter(e => !MEMORY_ONLY_OUTBOX_PROVIDERS.has(e.provider)) : [];
171
175
  } catch {
172
176
  return [];
173
177
  }
174
178
  }
179
+
180
+ /**
181
+ * Bumped on every rewrite, so a flush can tell cheaply whether the queue
182
+ * changed under it while it was awaiting the network.
183
+ */
184
+ let outboxVersion = 0;
175
185
  function writeOutbox(entries) {
176
- storage.set(OUTBOX_KEY, JSON.stringify(entries));
186
+ outboxVersion += 1;
187
+ volatileOutbox = entries.filter(e => MEMORY_ONLY_OUTBOX_PROVIDERS.has(e.provider));
188
+ storage.set(OUTBOX_KEY, JSON.stringify(entries.filter(e => !MEMORY_ONLY_OUTBOX_PROVIDERS.has(e.provider))));
189
+ }
190
+
191
+ // An earlier version persisted these entries like any other. Move them into
192
+ // memory and rewrite the durable copy without them, so plaintext a previous
193
+ // run left on disk does not outlive this one.
194
+ try {
195
+ const raw = storage.getString(OUTBOX_KEY);
196
+ const parsed = raw == null ? null : JSON.parse(raw);
197
+ if (Array.isArray(parsed) && parsed.some(e => isOutboxEntry(e) && MEMORY_ONLY_OUTBOX_PROVIDERS.has(e.provider))) writeOutbox(parsed.filter(isOutboxEntry));
198
+ } catch {
199
+ // Unreadable storage is handled - as an empty queue - by readOutbox.
177
200
  }
178
201
  function reportDropped(entry, reason, error) {
179
202
  options.onDropped?.({
@@ -227,6 +250,47 @@ function createCloudStore(options) {
227
250
  if (kept.length !== entries.length) writeOutbox(kept);
228
251
  }
229
252
 
253
+ // ------------------------------------------------------- per-key ordering
254
+
255
+ /**
256
+ * Serialises every operation on one (provider, key) pair.
257
+ *
258
+ * Without it a flush could be re-sending a queued v1 while a newer direct
259
+ * `setItem(k, v2)` ran alongside it, and whichever request the server saw
260
+ * last won - so v1 could land on top of v2. Holding the pair for the whole
261
+ * of "send, then update the outbox" makes the two strictly ordered: either
262
+ * the flush sends v1 first and v2 lands after it, or v2 lands first, drops
263
+ * the queued v1, and the flush finds nothing left to send.
264
+ *
265
+ * A batch takes every pair it touches at once. Waiters only ever wait on
266
+ * holders registered before them, so this cannot deadlock - but nothing
267
+ * holding a pair may try to take the same pair again.
268
+ *
269
+ * With `timeoutMs`, a timed-out request releases the pair while the request
270
+ * itself may still be in flight; a promise cannot be cancelled.
271
+ */
272
+ const keyLocks = new Map();
273
+ async function withKeys(provider, keys, fn) {
274
+ const ids = [...new Set(keys)].map(k => `${provider}\u0000${k}`);
275
+ const before = [];
276
+ for (const id of ids) {
277
+ const held = keyLocks.get(id);
278
+ if (held != null) before.push(held);
279
+ }
280
+ let release;
281
+ const mine = new Promise(resolve => {
282
+ release = resolve;
283
+ });
284
+ for (const id of ids) keyLocks.set(id, mine);
285
+ try {
286
+ if (before.length > 0) await Promise.all(before);
287
+ return await fn();
288
+ } finally {
289
+ release();
290
+ for (const id of ids) if (keyLocks.get(id) === mine) keyLocks.delete(id);
291
+ }
292
+ }
293
+
230
294
  // ------------------------------------------------------------ size rules
231
295
 
232
296
  /**
@@ -239,7 +303,8 @@ function createCloudStore(options) {
239
303
  function limitFor(provider) {
240
304
  if (tiering == null) return null;
241
305
  if (provider.name === 'icloudKV') return tiering.kvMaxBytes;
242
- if (provider.name === 'cloudKit') return tiering.recordMaxBytes;
306
+ // Encrypted records are still CKRecords, under the same 1 MB ceiling.
307
+ if (provider.name === 'cloudKit' || provider.name === 'cloudKitEncrypted') return tiering.recordMaxBytes;
243
308
  return null;
244
309
  }
245
310
  function canHold(provider, value) {
@@ -287,6 +352,27 @@ function createCloudStore(options) {
287
352
  for (const key of keys) out.push(await run(p, () => p.getItem(key)));
288
353
  return out;
289
354
  }
355
+
356
+ /**
357
+ * A batched read for a resolver, with server timestamps when the resolver
358
+ * uses them - so `multiGet` resolves exactly as `getItem` does. Stays one
359
+ * request per provider when the resolver ignores timestamps, or when the
360
+ * provider can batch them.
361
+ */
362
+ async function readBatchForResolve(p, keys, withMeta) {
363
+ if (withMeta) {
364
+ if (p.multiGetWithMeta != null) return await run(p, () => p.multiGetWithMeta(keys));
365
+ if (p.getItemWithMeta != null) {
366
+ const out = [];
367
+ for (const key of keys) out.push(await readOne(p, key));
368
+ return out;
369
+ }
370
+ }
371
+ const values = await readBatch(p, keys);
372
+ return values.map(value => value == null ? null : {
373
+ value
374
+ });
375
+ }
290
376
  async function writeBatch(p, entries) {
291
377
  if (entries.length === 0) return;
292
378
  if (p.multiSet != null) {
@@ -306,21 +392,50 @@ function createCloudStore(options) {
306
392
 
307
393
  // ---------------------------------------------------------------- writes
308
394
 
309
- /** Single-destination write, queueing a retryable failure. */
395
+ /**
396
+ * Single-destination write, queueing a retryable failure. Resolves true when
397
+ * the value landed, false when it was queued instead.
398
+ */
310
399
  async function writeOne(target, key, value) {
311
- try {
312
- await run(target, () => target.setItem(key, value));
313
- // This write supersedes anything queued for the same destination.
314
- dequeue(key, target.name);
315
- } catch (e) {
316
- const err = (0, _errors.normalizeError)(e, target.name);
317
- if (useOutbox && (0, _errors.isRetryable)(err)) {
318
- enqueue(key, value, target.name, err.code);
400
+ return await withKeys(target.name, [key], async () => {
401
+ try {
402
+ await run(target, () => target.setItem(key, value));
403
+ // This write supersedes anything queued for the same destination.
404
+ dequeue(key, target.name);
405
+ return true;
406
+ } catch (e) {
407
+ const err = (0, _errors.normalizeError)(e, target.name);
408
+ if (useOutbox && (0, _errors.isRetryable)(err)) {
409
+ enqueue(key, value, target.name, err.code);
410
+ options.onError?.(err);
411
+ return false;
412
+ }
413
+ throw err;
414
+ }
415
+ });
416
+ }
417
+
418
+ /**
419
+ * One destination's share of a multi-destination operation, under that
420
+ * destination's lock. Resolves 'done' or 'queued', or the fatal error -
421
+ * already reported through `onError` - for the caller to weigh.
422
+ */
423
+ async function attempt(target, keys, send, queued) {
424
+ return await withKeys(target.name, keys, async () => {
425
+ try {
426
+ await run(target, send);
427
+ dequeueMany(keys, target.name);
428
+ return 'done';
429
+ } catch (e) {
430
+ const err = (0, _errors.normalizeError)(e, target.name);
319
431
  options.onError?.(err);
320
- return;
432
+ if (useOutbox && (0, _errors.isRetryable)(err)) {
433
+ keys.forEach((key, i) => enqueue(key, queued[i], target.name, err.code));
434
+ return 'queued';
435
+ }
436
+ return err;
321
437
  }
322
- throw err;
323
- }
438
+ });
324
439
  }
325
440
 
326
441
  /**
@@ -336,14 +451,16 @@ function createCloudStore(options) {
336
451
  async function evictWhereTooLarge(targets, key, value) {
337
452
  for (const target of targets) {
338
453
  if (canHold(target, value)) continue;
339
- try {
340
- await run(target, () => target.removeItem(key));
341
- dequeue(key, target.name);
342
- } catch (e) {
343
- // Best effort. A stale copy left behind is reported, not fatal - the
344
- // value itself did land somewhere.
345
- options.onError?.((0, _errors.normalizeError)(e, target.name));
346
- }
454
+ await withKeys(target.name, [key], async () => {
455
+ try {
456
+ await run(target, () => target.removeItem(key));
457
+ dequeue(key, target.name);
458
+ } catch (e) {
459
+ // Best effort. A stale copy left behind is reported, not fatal - the
460
+ // value itself did land somewhere.
461
+ options.onError?.((0, _errors.normalizeError)(e, target.name));
462
+ }
463
+ });
347
464
  }
348
465
  }
349
466
 
@@ -373,19 +490,9 @@ function createCloudStore(options) {
373
490
  }
374
491
  let stored = 0;
375
492
  let fatal = null;
376
- for (const target of eligible) try {
377
- await run(target, () => target.setItem(key, value));
378
- dequeue(key, target.name);
379
- stored += 1;
380
- } catch (e) {
381
- const err = (0, _errors.normalizeError)(e, target.name);
382
- if (useOutbox && (0, _errors.isRetryable)(err)) {
383
- enqueue(key, value, target.name, err.code);
384
- options.onError?.(err);
385
- continue;
386
- }
387
- fatal ??= err;
388
- options.onError?.(err);
493
+ for (const target of eligible) {
494
+ const outcome = await attempt(target, [key], () => target.setItem(key, value), [value]);
495
+ if (outcome === 'done') stored += 1;else if (outcome !== 'queued') fatal ??= outcome;
389
496
  }
390
497
 
391
498
  // Only once the value has a home somewhere: dropping the old copy first
@@ -405,19 +512,9 @@ function createCloudStore(options) {
405
512
  if (targets.length === 0) throw noneAvailable();
406
513
  let removed = 0;
407
514
  let fatal = null;
408
- for (const target of targets) try {
409
- await run(target, () => target.removeItem(key));
410
- dequeue(key, target.name);
411
- removed += 1;
412
- } catch (e) {
413
- const err = (0, _errors.normalizeError)(e, target.name);
414
- if (useOutbox && (0, _errors.isRetryable)(err)) {
415
- enqueue(key, null, target.name, err.code);
416
- options.onError?.(err);
417
- continue;
418
- }
419
- fatal ??= err;
420
- options.onError?.(err);
515
+ for (const target of targets) {
516
+ const outcome = await attempt(target, [key], () => target.removeItem(key), [null]);
517
+ if (outcome === 'done') removed += 1;else if (outcome !== 'queued') fatal ??= outcome;
421
518
  }
422
519
  if (removed === 0 && fatal != null) throw fatal;
423
520
  }
@@ -428,27 +525,59 @@ function createCloudStore(options) {
428
525
  *
429
526
  * A provider the winner no longer fits in has its stale copy removed instead
430
527
  * of being silently left holding it - see {@link evictWhereTooLarge}.
528
+ *
529
+ * The outbox is consulted per provider, under that provider's lock for the
530
+ * key. A queued write there is this device's own pending value, so it is
531
+ * weighed as one more candidate:
532
+ *
533
+ * - if the resolver still prefers the winner, the queued write is older
534
+ * news - it is dropped once the repair lands, or the next flush would
535
+ * put it back on top of the repaired value;
536
+ * - if the resolver prefers the queued value, that provider is left alone
537
+ * and the outbox delivers it;
538
+ * - a queued delete is left to land, since repairing would resurrect a
539
+ * value the user removed.
431
540
  */
432
- async function repair(key, winner, candidates, reachable) {
541
+ async function repair(resolve, key, winner, candidates, reachable) {
433
542
  const byProvider = new Map(candidates.map(c => [c.provider, c.value]));
434
543
  const stored = await encode(key, winner);
435
- for (const [name, provider] of reachable) {
436
- if (byProvider.get(name) === winner) continue;
437
- if (!canHold(provider, stored)) {
438
- if (!byProvider.has(name)) continue;
439
- try {
544
+ for (const [name, provider] of reachable) await withKeys(name, [key], async () => {
545
+ try {
546
+ const queued = readOutbox().find(e => e.provider === name && e.key === key);
547
+ if (queued != null) {
548
+ if (queued.value == null) return;
549
+ const pending = await decode(key, queued.value);
550
+ const pick = resolve([...candidates, {
551
+ provider: name,
552
+ value: pending,
553
+ modifiedAt: queued.enqueuedAt
554
+ }]);
555
+ if (pick !== winner) return;
556
+ }
557
+ if (byProvider.get(name) !== winner) if (canHold(provider, stored)) {
558
+ await run(provider, () => provider.setItem(key, stored));
559
+ } else {
560
+ if (!byProvider.has(name)) return;
440
561
  await run(provider, () => provider.removeItem(key));
441
- } catch (e) {
442
- options.onError?.((0, _errors.normalizeError)(e, name));
443
562
  }
444
- continue;
445
- }
446
- try {
447
- await run(provider, () => provider.setItem(key, stored));
563
+ if (queued != null) dequeue(key, name);
448
564
  } catch (e) {
449
565
  options.onError?.((0, _errors.normalizeError)(e, name));
450
566
  }
451
- }
567
+ });
568
+ }
569
+
570
+ /** Resolves one key's candidates and, if configured, starts read repair. */
571
+ function settle(resolve, key, candidates, reachable) {
572
+ const winner = resolve(candidates);
573
+ if (winner == null) return null;
574
+
575
+ // Best-effort convergence. Never fails the read - the caller already has
576
+ // the right answer, and a failed repair only costs another resolve later.
577
+ if (repairOnRead) void repair(resolve, key, winner, candidates, reachable).catch(e => {
578
+ options.onError?.((0, _errors.normalizeError)(e));
579
+ });
580
+ return winner;
452
581
  }
453
582
 
454
583
  // ---------------------------------------------------------------- events
@@ -615,16 +744,12 @@ function createCloudStore(options) {
615
744
  reachedAny
616
745
  };
617
746
  }
618
- const winner = resolveValue(candidates);
747
+ const winner = settle(resolveValue, key, candidates, reachable);
619
748
  if (winner == null) return {
620
749
  found: false,
621
750
  value: null,
622
751
  reachedAny
623
752
  };
624
-
625
- // Best-effort convergence. Never fails the read - the caller already has
626
- // the right answer, and a failed repair only costs another resolve later.
627
- if (repairOnRead) void repair(key, winner, candidates, reachable);
628
753
  return {
629
754
  found: true,
630
755
  value: winner,
@@ -648,19 +773,25 @@ function createCloudStore(options) {
648
773
  checkKey(key);
649
774
  const stored = await encode(key, value);
650
775
  if (writeMode === 'failover') {
651
- const target = await providerForSize(stored, await primary());
652
- await writeOne(target, key, stored);
776
+ const preferred = await primary();
777
+ const target = await providerForSize(stored, preferred);
778
+ const landed = await writeOne(target, key, stored);
779
+ // Tiering routed the value past the preferred provider, which may still
780
+ // hold an older, smaller copy - and reads reach that one first. Without
781
+ // this, a value that grows past `kvMaxBytes` reads back stale forever.
782
+ if (landed && target !== preferred) await evictWhereTooLarge([preferred], key, stored);
653
783
  return;
654
784
  }
655
785
  await writeMany(await allAvailable(), key, stored);
656
786
  },
657
787
  removeItem: async key => {
658
788
  checkKey(key);
659
- // A mirrored write must be a mirrored delete. Removing from only the
660
- // preferred provider would leave a copy behind that reads then fall
661
- // through to and resurrect.
662
- const targets = writeMode === 'mirror' ? await allAvailable() : [await primary()];
663
- await removeMany(targets, key);
789
+ // A delete has to reach every provider reads fall through to, in both
790
+ // modes. Mirror wrote everywhere; failover may have written to a later
791
+ // provider too - because the preferred one was down at the time, or
792
+ // because tiering routed a large value past it. Removing from only the
793
+ // preferred provider leaves that copy behind for reads to resurrect.
794
+ await removeMany(await allAvailable(), key);
664
795
  },
665
796
  getAllKeys: async () => {
666
797
  const seen = new Set();
@@ -685,21 +816,30 @@ function createCloudStore(options) {
685
816
  // batched request rather than one per key.
686
817
  if (resolveValue != null) {
687
818
  const perKey = new Map(keys.map(k => [k, []]));
819
+ const reachable = new Map();
820
+ // Same candidates `getItem` would build, timestamps included, so the
821
+ // two reads cannot resolve the same key differently.
822
+ const withMeta = resolveValue.usesModifiedAt !== false;
688
823
  let reachedAny = false;
689
824
  for (const name of options.providers) {
690
825
  const p = resolveProvider(name);
691
826
  try {
692
827
  if (!(await isAvailable(p))) continue;
693
- const values = await readBatch(p, keys);
694
- reachedAny = true;
828
+ const hits = await readBatchForResolve(p, keys, withMeta);
829
+ const found = [];
695
830
  for (let i = 0; i < keys.length; i += 1) {
696
- const raw = values[i];
697
- if (raw == null) continue;
698
- perKey.get(keys[i]).push({
831
+ const hit = hits[i];
832
+ if (hit == null) continue;
833
+ found.push([keys[i], {
699
834
  provider: p.name,
700
- value: await decode(keys[i], raw)
701
- });
835
+ value: await decode(keys[i], hit.value),
836
+ modifiedAt: hit.modifiedAt
837
+ }]);
702
838
  }
839
+ // Only a provider read in full is a repair target - see readAcross.
840
+ reachable.set(p.name, p);
841
+ reachedAny = true;
842
+ for (const [key, candidate] of found) perKey.get(key).push(candidate);
703
843
  } catch {
704
844
  // Same rule as `getAllKeys`: one provider failing to answer must not
705
845
  // erase the answers the others gave.
@@ -708,7 +848,7 @@ function createCloudStore(options) {
708
848
  if (!reachedAny) throw noneAvailable();
709
849
  for (const key of keys) {
710
850
  const candidates = perKey.get(key);
711
- answers.set(key, candidates.length === 0 ? null : resolveValue(candidates));
851
+ answers.set(key, candidates.length === 0 ? null : settle(resolveValue, key, candidates, reachable));
712
852
  }
713
853
  return keys.map(k => [k, answers.get(k) ?? null]);
714
854
  }
@@ -759,17 +899,13 @@ function createCloudStore(options) {
759
899
  for (const {
760
900
  provider,
761
901
  items
762
- } of byTarget.values()) try {
763
- await writeBatch(provider, items);
764
- dequeueMany(items.map(([k]) => k), provider.name);
765
- } catch (e) {
766
- const err = (0, _errors.normalizeError)(e, provider.name);
767
- if (useOutbox && (0, _errors.isRetryable)(err)) {
768
- for (const [key, value] of items) enqueue(key, value, provider.name, err.code);
769
- options.onError?.(err);
770
- continue;
771
- }
772
- throw err;
902
+ } of byTarget.values()) {
903
+ const outcome = await attempt(provider, items.map(([k]) => k), () => writeBatch(provider, items), items.map(([, v]) => v));
904
+ if (outcome === 'queued') continue;
905
+ if (outcome !== 'done') throw outcome;
906
+ // Same stale-copy rule as `setItem`: values routed past the
907
+ // preferred provider must not leave an older copy there.
908
+ if (provider !== preferred) for (const [key, value] of items) await evictWhereTooLarge([preferred], key, value);
773
909
  }
774
910
  return;
775
911
  }
@@ -780,20 +916,8 @@ function createCloudStore(options) {
780
916
  for (const target of targets) {
781
917
  const fits = encoded.filter(([, value]) => canHold(target, value));
782
918
  if (fits.length === 0) continue;
783
- try {
784
- await writeBatch(target, fits);
785
- dequeueMany(fits.map(([k]) => k), target.name);
786
- anyStored = true;
787
- } catch (e) {
788
- const err = (0, _errors.normalizeError)(e, target.name);
789
- if (useOutbox && (0, _errors.isRetryable)(err)) {
790
- for (const [key, value] of fits) enqueue(key, value, target.name, err.code);
791
- options.onError?.(err);
792
- continue;
793
- }
794
- fatal ??= err;
795
- options.onError?.(err);
796
- }
919
+ const outcome = await attempt(target, fits.map(([k]) => k), () => writeBatch(target, fits), fits.map(([, v]) => v));
920
+ if (outcome === 'done') anyStored = true;else if (outcome !== 'queued') fatal ??= outcome;
797
921
  }
798
922
  if (anyStored) for (const [key, value] of encoded) await evictWhereTooLarge(targets, key, value);
799
923
  if (!anyStored && fatal != null) throw fatal;
@@ -807,23 +931,15 @@ function createCloudStore(options) {
807
931
  multiRemove: async keys => {
808
932
  for (const key of keys) checkKey(key);
809
933
  if (keys.length === 0) return;
810
- const targets = writeMode === 'mirror' ? await allAvailable() : [await primary()];
934
+
935
+ // Every available provider, in both modes - see `removeItem`.
936
+ const targets = await allAvailable();
811
937
  if (targets.length === 0) throw noneAvailable();
812
938
  let removedAnywhere = false;
813
939
  let fatal = null;
814
- for (const target of targets) try {
815
- await removeBatch(target, keys);
816
- dequeueMany(keys, target.name);
817
- removedAnywhere = true;
818
- } catch (e) {
819
- const err = (0, _errors.normalizeError)(e, target.name);
820
- if (useOutbox && (0, _errors.isRetryable)(err)) {
821
- for (const key of keys) enqueue(key, null, target.name, err.code);
822
- options.onError?.(err);
823
- continue;
824
- }
825
- fatal ??= err;
826
- options.onError?.(err);
940
+ for (const target of targets) {
941
+ const outcome = await attempt(target, keys, () => removeBatch(target, keys), keys.map(() => null));
942
+ if (outcome === 'done') removedAnywhere = true;else if (outcome !== 'queued') fatal ??= outcome;
827
943
  }
828
944
  if (!removedAnywhere && fatal != null) throw fatal;
829
945
  },
@@ -841,7 +957,9 @@ function createCloudStore(options) {
841
957
  const keys = await store.getAllKeys();
842
958
  if (keys.length === 0) return {};
843
959
  const out = {};
844
- for (const [key, value] of await store.multiGet(keys)) if (value != null) out[key] = value;
960
+ // Keys come from provider listings; a file named `__proto__` must land
961
+ // as an entry, not be swallowed by the prototype setter.
962
+ for (const [key, value] of await store.multiGet(keys)) if (value != null) (0, _records.setOwn)(out, key, value);
845
963
  return out;
846
964
  },
847
965
  getQuota: async () => {
@@ -878,16 +996,19 @@ function createCloudStore(options) {
878
996
  // on the way out only to re-encode on the way in would be wasted work -
879
997
  // and, for a codec with a random nonce, would rewrite every byte.
880
998
  for (const key of keys) {
999
+ // Which end failed, so the error names the provider that raised it.
1000
+ let side = from;
881
1001
  try {
882
1002
  const value = await run(src, () => src.getItem(key));
883
1003
  if (value == null) {
884
1004
  skipped.push(key);
885
1005
  } else {
886
- await run(dst, () => dst.setItem(key, value));
1006
+ side = to;
1007
+ await withKeys(to, [key], () => run(dst, () => dst.setItem(key, value)));
887
1008
  copied.push(key);
888
1009
  }
889
1010
  } catch (e) {
890
- const err = (0, _errors.normalizeError)(e, from);
1011
+ const err = (0, _errors.normalizeError)(e, side);
891
1012
  failed.push({
892
1013
  key,
893
1014
  error: err
@@ -972,10 +1093,26 @@ function createCloudStore(options) {
972
1093
  dropped: []
973
1094
  };
974
1095
  const now = Date.now();
1096
+ // Each kept entry alongside the snapshot entry it came from, so the final
1097
+ // merge can check that the original is still the one queued.
975
1098
  const keep = [];
976
1099
  const dropped = [];
977
- const handled = new Set();
978
1100
  let drained = 0;
1101
+
1102
+ // The queue can change while this flush awaits the network: a newer write
1103
+ // supersedes an entry (dequeue or replace), `discardPendingWrites` removes
1104
+ // one, or an account switch empties it. An entry that is no longer queued
1105
+ // must not be sent - after an account switch that would write the previous
1106
+ // user's data into the new account - nor written back at the end.
1107
+ let seenVersion = outboxVersion;
1108
+ let current = entries;
1109
+ function stillQueued(entry) {
1110
+ if (outboxVersion !== seenVersion) {
1111
+ current = readOutbox();
1112
+ seenVersion = outboxVersion;
1113
+ }
1114
+ return current.some(e => sameEntry(e, entry));
1115
+ }
979
1116
  function drop(entry, reason, error) {
980
1117
  dropped.push({
981
1118
  entry,
@@ -984,14 +1121,28 @@ function createCloudStore(options) {
984
1121
  });
985
1122
  reportDropped(entry, reason, error);
986
1123
  }
1124
+
1125
+ /**
1126
+ * Takes a delivered entry out of storage straight away, rather than at the
1127
+ * final merge, so nothing consulting the outbox meanwhile - read repair,
1128
+ * `pendingWrites()` - mistakes it for a write still waiting.
1129
+ */
1130
+ function removeExact(entry) {
1131
+ const queued = readOutbox();
1132
+ const rest = queued.filter(e => !sameEntry(e, entry));
1133
+ if (rest.length !== queued.length) writeOutbox(rest);
1134
+ }
987
1135
  for (const entry of entries) {
988
- handled.add(outboxId(entry.provider, entry.key));
1136
+ if (!stillQueued(entry)) continue;
989
1137
  if (now - entry.enqueuedAt > maxAgeMs) {
990
1138
  drop(entry, 'expired');
991
1139
  continue;
992
1140
  }
993
1141
  if (entry.nextAttemptAt > now) {
994
- keep.push(entry);
1142
+ keep.push({
1143
+ entry,
1144
+ from: entry
1145
+ });
995
1146
  continue;
996
1147
  }
997
1148
  let p;
@@ -1002,56 +1153,92 @@ function createCloudStore(options) {
1002
1153
  drop(entry, 'notRetryable', (0, _errors.normalizeError)(e, entry.provider));
1003
1154
  continue;
1004
1155
  }
1005
- try {
1006
- if (entry.value == null) await run(p, () => p.removeItem(entry.key));else await run(p, () => p.setItem(entry.key, entry.value));
1007
- drained += 1;
1008
- } catch (e) {
1009
- const err = (0, _errors.normalizeError)(e, entry.provider);
1010
- options.onError?.(err);
1011
-
1012
- // A write only enters the queue for a retryable reason. If retrying it
1013
- // now fails for one the user must act on - quota, signed out, a payload
1014
- // the store will never accept - re-queueing turns it into a poison
1015
- // entry that retries forever, never drains, and never surfaces.
1016
- if (!(0, _errors.isRetryable)(err)) {
1017
- drop(entry, 'notRetryable', err);
1018
- continue;
1019
- }
1020
- const attempts = entry.attempts + 1;
1021
- if (attempts >= maxAttempts) {
1022
- drop({
1023
- ...entry,
1024
- attempts,
1025
- lastErrorCode: err.code
1026
- }, 'tooManyAttempts', err);
1027
- continue;
1156
+ const provider = p;
1157
+ // Under the pair's lock, so a direct write to the same key cannot run
1158
+ // alongside this re-send - see `withKeys`. Checked again once the lock
1159
+ // is held: a direct write that got there first has dropped this entry.
1160
+ await withKeys(entry.provider, [entry.key], async () => {
1161
+ if (!stillQueued(entry)) return;
1162
+ try {
1163
+ if (entry.value == null) await run(provider, () => provider.removeItem(entry.key));else await run(provider, () => provider.setItem(entry.key, entry.value));
1164
+ drained += 1;
1165
+ removeExact(entry);
1166
+ } catch (e) {
1167
+ retryLater(entry, (0, _errors.normalizeError)(e, entry.provider));
1028
1168
  }
1169
+ });
1170
+ }
1171
+ function retryLater(entry, err) {
1172
+ options.onError?.(err);
1029
1173
 
1030
- // Exponential backoff, honouring a server-supplied retry hint when
1031
- // there is one (CloudKit sends `retryAfter`, Drive `Retry-After`).
1032
- const backoff = err.retryAfterMs ?? Math.min(2 ** attempts * 1000, 5 * 60_000);
1033
- keep.push({
1174
+ // A write only enters the queue for a retryable reason. If retrying it
1175
+ // now fails for one the user must act on - quota, signed out, a payload
1176
+ // the store will never accept - re-queueing turns it into a poison
1177
+ // entry that retries forever, never drains, and never surfaces.
1178
+ if (!(0, _errors.isRetryable)(err)) {
1179
+ drop(entry, 'notRetryable', err);
1180
+ return;
1181
+ }
1182
+ const attempts = entry.attempts + 1;
1183
+ if (attempts >= maxAttempts) {
1184
+ drop({
1034
1185
  ...entry,
1035
1186
  attempts,
1036
- nextAttemptAt: Date.now() + backoff,
1037
1187
  lastErrorCode: err.code
1038
- });
1188
+ }, 'tooManyAttempts', err);
1189
+ return;
1039
1190
  }
1191
+
1192
+ // Exponential backoff, honouring a server-supplied retry hint when
1193
+ // there is one (CloudKit sends `retryAfter`, Drive `Retry-After`).
1194
+ // Clamped again here: a third-party provider can set any number.
1195
+ const backoff = (0, _records.clampRetryAfterMs)(err.retryAfterMs) ?? Math.min(2 ** attempts * 1000, 5 * 60_000);
1196
+ keep.push({
1197
+ entry: {
1198
+ ...entry,
1199
+ attempts,
1200
+ nextAttemptAt: Date.now() + backoff,
1201
+ lastErrorCode: err.code
1202
+ },
1203
+ from: entry
1204
+ });
1040
1205
  }
1041
1206
 
1042
1207
  // Merge rather than overwrite. A `setItem` that failed while this flush was
1043
- // awaiting the network enqueued itself into storage; writing the snapshot
1044
- // back wholesale would silently discard it.
1045
- const arrived = readOutbox().filter(e => !handled.has(outboxId(e.provider, e.key)));
1046
- writeOutbox([...keep, ...arrived]);
1208
+ // awaiting the network enqueued itself into storage - possibly replacing
1209
+ // an entry for the same key with a newer value - and writing the snapshot
1210
+ // back wholesale would silently discard it. Equally, a kept entry whose
1211
+ // original was removed meanwhile (superseded, discarded, account switch)
1212
+ // must stay removed.
1213
+ const latest = readOutbox();
1214
+ const kept = keep.filter(({
1215
+ from
1216
+ }) => latest.some(e => sameEntry(e, from))).map(({
1217
+ entry
1218
+ }) => entry);
1219
+ const arrived = latest.filter(e => !entries.some(s => sameEntry(s, e)));
1220
+ writeOutbox([...kept, ...arrived]);
1047
1221
  return {
1048
1222
  drained,
1049
- remaining: keep.length + arrived.length,
1223
+ remaining: kept.length + arrived.length,
1050
1224
  dropped
1051
1225
  };
1052
1226
  }
1053
1227
  return store;
1054
1228
  }
1229
+
1230
+ /**
1231
+ * The same queued write, not merely one for the same key: a newer write to the
1232
+ * key replaces the entry with a fresh `enqueuedAt` and value.
1233
+ */
1234
+ function sameEntry(a, b) {
1235
+ return a.provider === b.provider && a.key === b.key && a.enqueuedAt === b.enqueuedAt && a.value === b.value;
1236
+ }
1237
+ function isOutboxEntry(e) {
1238
+ if (e == null || typeof e !== 'object') return false;
1239
+ const o = e;
1240
+ return typeof o.key === 'string' && typeof o.provider === 'string' && (o.value === null || typeof o.value === 'string') && typeof o.attempts === 'number' && typeof o.nextAttemptAt === 'number' && typeof o.enqueuedAt === 'number';
1241
+ }
1055
1242
  function createMemoryOutboxStorage() {
1056
1243
  const map = new Map();
1057
1244
  return {