TanStack/db @tanstack/db@0.5.4

on GitHub

Patch Changes

• Fix progressive mode to use fetchSnapshot and atomic swap (#852)

  Progressive mode was broken because requestSnapshot() injected snapshots into the stream in causally correct position, which didn't work properly with the full mode stream. This release fixes progressive mode by:

  Core Changes:

  • Use fetchSnapshot() during initial sync to fetch and apply snapshots immediately in sync transactions
  • Buffer all stream messages during initial sync (renamed flag to isBufferingInitialSync)
  • Perform atomic swap on first up-to-date: truncate snapshot data → apply buffered messages → mark ready
  • Track txids/snapshots only after atomic swap (enables correct optimistic transaction confirmation)

  Test Infrastructure:

  • Added ELECTRIC_TEST_HOOKS symbol for test control (hidden from public API)
  • Added progressiveTestControl.releaseInitialSync() to E2E test config for explicit transition control
  • Created comprehensive progressive mode E2E test suite (8 tests):
    • Explicit snapshot phase and atomic swap validation
    • Txid tracking behavior (Electric-only)
    • Multiple concurrent snapshots with deduplication
    • Incremental updates after swap
    • Predicate handling and resilience tests

  Bug Fixes:

  • Fixed type errors in test files
  • All 166 unit tests + 95 E2E tests passing

• Improved error messages when invalid source types are passed to .from() or .join() methods. When users mistakenly pass a string, null, array, or other invalid type instead of an object with a collection, they now receive a clear, actionable error message with an example of the correct usage (e.g., .from({ todos: todosCollection })). (#875)

• Migrated paced mutations implementation from @tanstack/pacer to @tanstack/pacer-lite. The lite version provides the same core functionality with minimal overhead and no external dependencies, making it more suitable for library use. This is an internal implementation change with no impact on the public API - all paced mutation strategies (debounce, throttle, queue) continue to work exactly as before. (#880)

• Add warning when calling .preload() on collections with on-demand syncMode. In on-demand mode, data is only loaded when queries request it, so calling .preload() on the collection itself is a no-op. Users should create a live query and call .preload() on that instead. (#871)