Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

offline-transactions: confirm writes off the serial drain (hold optimistic state through the post-commit sync window)

未关闭
  • 哪里不对？
#1,602 0 条评论 2 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

  • #1603 来自 @TomasGonzalez —— 已关闭，未合并

评估

难度
5/5
预计耗时
一周以上
新手友好度
35/100
Issue 类型
功能
描述清晰度
基本清楚
活跃度
冷清
技术栈
typescript
领域
databases

调研方向

从 TransactionExecutor.restoreOptimisticState 和提议的 OptimisticHold.ts 原语开始，然后检查现有的恢复清理逻辑及相关测试。当提交后确认能够在不阻塞串行写入的情况下保持乐观状态、被拒绝的钩子不会重试或回滚已提交的写入，并且所述上限和 changeset 都得到覆盖时，此变更就完成了。

由索引模型根据 Issue 内容生成。

描述

Summary

@tanstack/offline-transactions drains the outbox serially — one mutationFn at a time — which is what preserves create-then-update / FK ordering. But there is no built-in way to keep a row's optimistic state painted through the gap between "the server committed the write" and "the sync stream echoed it back." Both available workarounds are bad, and this hurts real apps using an async confirmation stream (e.g. ElectricSQL's awaitTxId).

The gap

The executor drops a transaction's optimistic overlay the instant its mutationFn resolves (resolveTransaction → cleanupRestorationTransaction). If the synced data hasn't caught up yet, the row flickers (disappears, then reappears when sync delivers it).

To avoid the flicker today, you must await the confirmation inside the mutationFn:

mutationFn: async ({ transaction }) => {
  const { txid } = await postToServer(transaction)
  await collection.utils.awaitTxId(txid) // runs ON the serial path
}

But the drain is serial, so this await blocks the next write. With an Electric shape stream whose awaitTxId budget is ~10s, drain throughput collapses to ~1 write / 10s, and each settled write tends to spawn a duplicate "already-applied" resend. So you're forced to choose between slow drain (await inline) and UI flicker (don't await). Neither is acceptable.

Notably, the library already has the right primitive — TransactionExecutor.restoreOptimisticState creates a standalone createTransaction({ autoCommit: false }), applies the mutations, registers it on each collection's _state, and cleanupRestorationTransaction tears it down — but it's private and only wired for rehydrate-on-load, not for the post-commit confirm window.

Proposed API

An opt-in OfflineConfig.confirmWrite hook that runs after the write commits and its outbox entry is removed, but off the serial drain path:

startOfflineExecutor({
  // ...
  confirmWrite: async ({ mutations, result }) => {
    // result = whatever your mutationFn returned (e.g. a server txid)
    await Promise.all(
      collectionsOf(mutations).map((c) => c.utils.awaitTxId(result.txid)),
    )
  },
})

While the returned promise is pending, the library keeps the committed mutations' optimistic overlay painted (reusing the existing hold primitive) and releases it when the hook settles. The serial chain still serializes the POSTs (ordering preserved); only the confirmation moves off it.

Key semantics:

  • Never rolls back — the write is already durably committed, so a rejected/timed-out hook just releases the overlay early (possible brief flicker), never data loss. Timeout / verify-by-state logic lives inside the hook.
  • Never throws into the drain — a throw can't make the executor retry an already-committed write.
  • No flicker — the hold is registered synchronously, before the original overlay is dropped.
  • Bounded — a maxConfirmationHolds cap avoids O(n²) optimistic-recompute churn on a large, fast drain.
  • Fully opt-in — with no confirmWrite, behavior is unchanged.

Context

We hit exactly this in production (offline-first app on Electric). We currently work around it with an external module that reaches into collection._state and re-implements the library's private hold/teardown — fragile, and it duplicates internals. A first-class hook would let that module collapse to the small callback above.

I have a PR ready that implements this (new confirmWrite/maxConfirmationHolds/getActiveConfirmationHoldCount, the create/release primitive factored into OptimisticHold.ts and shared with restoreOptimisticState, tests, changeset). Happy to bikeshed the hook name (confirmWrite / awaitSync / confirmTransaction) and the default cap. Will link it here.

主要语言
TypeScript
星标
3.9k
派生
272
平均合并
1 天 45 分钟
30 天内合并 PR
208

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

TanStack/db 的其他 Issue

查看 TanStack/db 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。