fix: guard debounced save against concurrent PUT calls

[kptdobe]

Problem

The debounced update handler in persistence.bindState is an async function called via lodash.debounce. If a PUT takes longer than the debounce window (2 s max-wait is 10 s), a second firing of the debounced callback will race the first — both simultaneously awaiting persistence.put against da-admin. This can cause:

• Out-of-order writes (last PUT wins, earlier content lost)
• Duplicate PUT traffic under high update rates

Fix

Introduce a saving boolean flag in the closure. If the flag is set when the debounced callback fires, the second invocation returns immediately instead of launching a concurrent PUT.

let saving = false;
ydoc.on('update', debounce(async () => {
  if (saving || !current || ydoc !== docs.get(docName)) return;
  saving = true;
  try {
    current = await persistence.update(ydoc, current, docName);
  } finally {
    saving = false;
  }
}, 2000, { maxWait: 10000 }));

Test

New test Test concurrent save calls are guarded by saving flag:

• Mocks debounce as identity so the handler fires immediately
• Mocks persistence.put with a 30 ms artificial delay and a concurrency counter
• Fires the debounced handler twice concurrently (Promise.all)
• Asserts maxConcurrentPuts === 1

The test fails on the old code (observed 12 concurrent puts) and passes after this fix.

Part of series

This is PR 4/4 fixing the image-disappears-on-drag-and-drop bug:

• PR 1/4 — Cloudflare DO Hibernation API (feat: adopt Cloudflare WebSocket Hibernation API #137)
• PR 2/4 — Always trust worker storage over stale da-admin (fix: always trust worker storage over stale da-admin on DO rehydration #138)
• PR 3/4 — Remove If-Match: * / destructive 412 handler (fix: remove If-Match header and stop clearing storage on 412 #139)
• PR 4/4 — Guard concurrent PUT calls ← this PR

🤖 Generated with Claude Code

[bosschaert]

Seems that this PR contains more than just what is described? Seems like it also contains the changes from #137 ?

It think it would be better to isolate the changes 😄

[kptdobe]

@bosschaert yes, for some reason, the PR became cumulative. I isolate the change now, it only contains the PR specific changes only.

[adobe-bot]

🎉 This PR is included in version 1.2.5 🎉

The release is available on:

• v1.2.5
• GitHub release

Your semantic-release bot 📦🚀