feat: Add paced mutations with timing strategies

[KyleAMathews]

Summary

This PR introduces a new paced mutations system for TanStack DB, enabling optimistic mutations with pluggable timing strategies. This provides a powerful way to control when and how mutations are persisted to the backend.

Powered by TanStack Pacer, which provides the underlying debounce, throttle, and queue implementations.

paced-mutations-demo.mp4

Key Design

Debounce/Throttle: Only one pending transaction (collecting mutations) and one persisting transaction (writing to backend) at a time. Multiple rapid mutations automatically merge together.

Queue: Each mutation creates a separate transaction, guaranteed to run in the order they're made (FIFO by default, configurable to LIFO).

Key Features

• Pluggable Strategy System: Debounce, queue, throttle strategies for controlling mutation timing
• Auto-merging Mutations: Multiple rapid mutations on the same item automatically merge for efficiency (debounce/throttle only)
• React Hook: usePacedMutations for easy integration in React apps
• Transaction Management: Track mutation state (pending → persisting → completed/failed)
• Interactive Demo: Slider-based demo showcasing all strategies with real-time visualization

Example Usage

Debounce Strategy (Auto-save)

import { usePacedMutations, debounceStrategy } from "@tanstack/react-db"

function AutoSaveForm() {
  const mutate = usePacedMutations({
    mutationFn: async ({ transaction }) => {
      await api.save(transaction.mutations)
    },
    strategy: debounceStrategy({ wait: 500 }),
  })

  const handleChange = (value: string) => {
    const tx = mutate(() => {
      formCollection.update(formId, (draft) => {
        draft.content = value
      })
    })

    // Optionally await persistence
    await tx.isPersisted.promise
  }

  return <textarea onChange={e => handleChange(e.target.value)} />
}

Throttle Strategy (Volume Slider)

import { usePacedMutations, throttleStrategy } from "@tanstack/react-db"

function VolumeSlider() {
  const mutate = usePacedMutations({
    mutationFn: async ({ transaction }) => {
      await api.updateVolume(transaction.mutations)
    },
    strategy: throttleStrategy({ wait: 200 }),
  })

  return (
    <input
      type="range"
      onChange={e => {
        mutate(() => {
          settingsCollection.update('volume', draft => {
            draft.value = +e.target.value
          })
        })
      }}
    />
  )
}

Queue Strategy (Sequential Processing)

import { usePacedMutations, queueStrategy } from "@tanstack/react-db"

function SequentialUpload() {
  const mutate = usePacedMutations({
    mutationFn: async ({ transaction }) => {
      await api.uploadImages(transaction.mutations)
    },
    // FIFO by default - each mutation creates a separate transaction
    // Waits 500ms between processing each transaction
    strategy: queueStrategy({ wait: 500 }),
  })

  const handleFileSelect = (files: FileList) => {
    // Each file creates its own transaction, queued for sequential processing
    Array.from(files).forEach((file, idx) => {
      mutate(() => {
        uploadCollection.insert({ id: idx, file })
      })
    })
  }

  return <input type="file" multiple onChange={e => handleFileSelect(e.target.files!)} />
}

Available Strategies

Strategy	Behavior	Guarantees
debounceStrategy	Wait for inactivity before persisting. One pending + one persisting tx at a time.	Only final state persists
throttleStrategy	Ensure minimum spacing between executions. One pending + one persisting tx at a time.	Mutations between executions are merged
queueStrategy	Each mutation becomes a separate transaction, processed sequentially in order (FIFO by default, configurable to LIFO).	All mutations guaranteed to persist in order

Core Implementation

Paced Mutations (packages/db/src/paced-mutations.ts)

• Creates transactions with autoCommit: false for strategy control
• Debounce/Throttle: Manages one ambient transaction for collecting mutations. New mutations merge into this transaction until it's persisted.
• Queue: Creates a separate transaction per mutate() call. Each transaction is queued and processed in order.
• Strategies control when commit() is called via callback

Strategies (packages/db/src/strategies/)

• Debounce: Resets timer on each mutation, commits after inactivity (via TanStack Pacer)
• Queue: Each mutation gets its own transaction, processes sequentially in FIFO order (configurable to LIFO) (via TanStack Pacer)
• Throttle: Ensure minimum spacing between executions (via TanStack Pacer)

React Hook (packages/react-db/src/usePacedMutations.ts)

• Memoized strategy and mutationFn to prevent unnecessary recreations
• Returns stable mutate callback
• Full TypeScript support with generics

Demo Application

Interactive demo at examples/react/paced-mutations-demo/ showcasing:

• Slider interface that triggers mutations on every change (demonstrates rapid mutations naturally)
• All three strategies with configurable options (300ms default)
• Real-time transaction timeline visualization
• Optimistic vs synced state comparison
• Detailed timing metrics (pending time, persisting time, total duration)
• Fake server sync to demonstrate realistic optimistic updates

Tests

Comprehensive test suite for all strategies:

• ✅ Debounce: batching and timer reset behavior
• ✅ Queue: sequential processing with separate transactions per mutation
• ✅ Throttle: leading/trailing edge execution
• ✅ 100% coverage on usePacedMutations hook
• ✅ All tests passing

Bug Fixes

• Fixed queue strategy to create separate transactions per mutation (clears activeTransaction after each)
• Fixed queue strategy to properly commit captured transactions (prevents "no active transaction" errors)
• Fixed queue strategy to default to FIFO order (addItemsTo='back', getItemsFrom='front')
• Fixed slider value resetting to 0 after persistence (use mutation.modified instead of mutation.changes)

Use Cases

Debounce Strategy:

• Auto-save forms
• Search-as-you-type
• Settings panels

Queue Strategy:

• Sequential workflows (file uploads, multi-step processes)
• Rate-limited APIs
• Audit trails where every operation must be recorded

Throttle Strategy:

• Analytics tracking
• Progress updates
• Volume/brightness sliders

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 7b4e55a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 13 packages

Name	Type
@tanstack/db	Patch
@tanstack/react-db	Patch
@tanstack/angular-db	Patch
@tanstack/electric-db-collection	Patch
@tanstack/query-db-collection	Patch
@tanstack/rxdb-db-collection	Patch
@tanstack/solid-db	Patch
@tanstack/svelte-db	Patch
@tanstack/trailbase-db-collection	Patch
@tanstack/vue-db	Patch
todos	Patch
@tanstack/db-example-paced-mutations-demo	Patch
@tanstack/db-example-react-todo	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

More templates

• todos
• @tanstack/db-example-paced-mutations-demo
• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• @tanstack/db-example-solid-todo

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@704

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@704

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@704

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@704

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@704

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@704

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@704

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@704

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@704

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@704

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@704

commit: 7b4e55a

[github-actions]

Size Change: +1.53 kB (+1.81%)

Total Size: 85.8 kB

Filename	Size	Change
./packages/db/dist/esm/index.js	1.69 kB	+69 B (+4.25%)
./packages/db/dist/esm/paced-mutations.js	528 B	+528 B (new file)	🆕
./packages/db/dist/esm/strategies/debounceStrategy.js	248 B	+248 B (new file)	🆕
./packages/db/dist/esm/strategies/queueStrategy.js	433 B	+433 B (new file)	🆕
./packages/db/dist/esm/strategies/throttleStrategy.js	248 B	+248 B (new file)	🆕

ℹ️ View Unchanged

Filename	Size
./packages/db/dist/esm/collection/change-events.js	1.63 kB
./packages/db/dist/esm/collection/changes.js	1.01 kB
./packages/db/dist/esm/collection/events.js	413 B
./packages/db/dist/esm/collection/index.js	3.23 kB
./packages/db/dist/esm/collection/indexes.js	1.16 kB
./packages/db/dist/esm/collection/lifecycle.js	1.8 kB
./packages/db/dist/esm/collection/mutations.js	2.52 kB
./packages/db/dist/esm/collection/state.js	3.79 kB
./packages/db/dist/esm/collection/subscription.js	2.2 kB
./packages/db/dist/esm/collection/sync.js	2.2 kB
./packages/db/dist/esm/deferred.js	230 B
./packages/db/dist/esm/errors.js	3.48 kB
./packages/db/dist/esm/event-emitter.js	798 B
./packages/db/dist/esm/indexes/auto-index.js	794 B
./packages/db/dist/esm/indexes/base-index.js	835 B
./packages/db/dist/esm/indexes/btree-index.js	2 kB
./packages/db/dist/esm/indexes/lazy-index.js	1.21 kB
./packages/db/dist/esm/indexes/reverse-index.js	577 B
./packages/db/dist/esm/local-only.js	967 B
./packages/db/dist/esm/local-storage.js	2.4 kB
./packages/db/dist/esm/optimistic-action.js	294 B
./packages/db/dist/esm/proxy.js	3.86 kB
./packages/db/dist/esm/query/builder/functions.js	615 B
./packages/db/dist/esm/query/builder/index.js	4.04 kB
./packages/db/dist/esm/query/builder/ref-proxy.js	938 B
./packages/db/dist/esm/query/compiler/evaluators.js	1.55 kB
./packages/db/dist/esm/query/compiler/expressions.js	760 B
./packages/db/dist/esm/query/compiler/group-by.js	2.04 kB
./packages/db/dist/esm/query/compiler/index.js	2.21 kB
./packages/db/dist/esm/query/compiler/joins.js	2.65 kB
./packages/db/dist/esm/query/compiler/order-by.js	1.43 kB
./packages/db/dist/esm/query/compiler/select.js	1.28 kB
./packages/db/dist/esm/query/ir.js	785 B
./packages/db/dist/esm/query/live-query-collection.js	404 B
./packages/db/dist/esm/query/live/collection-config-builder.js	5.54 kB
./packages/db/dist/esm/query/live/collection-registry.js	233 B
./packages/db/dist/esm/query/live/collection-subscriber.js	2.11 kB
./packages/db/dist/esm/query/optimizer.js	3.26 kB
./packages/db/dist/esm/scheduler.js	1.29 kB
./packages/db/dist/esm/SortedMap.js	1.24 kB
./packages/db/dist/esm/transactions.js	3.05 kB
./packages/db/dist/esm/utils.js	1.01 kB
./packages/db/dist/esm/utils/browser-polyfills.js	365 B
./packages/db/dist/esm/utils/btree.js	6.01 kB
./packages/db/dist/esm/utils/comparison.js	754 B
./packages/db/dist/esm/utils/index-optimization.js	1.73 kB

_{compressed-size-action::db-package-size}

[github-actions]

Size Change: 0 B

Total Size: 2.89 kB

ℹ️ View Unchanged

Filename	Size
./packages/react-db/dist/esm/index.js	168 B
./packages/react-db/dist/esm/useLiveInfiniteQuery.js	1.41 kB
./packages/react-db/dist/esm/useLiveQuery.js	1.31 kB

_{compressed-size-action::react-db-package-size}

[samwillis]

I like this a lot, we're nearly there I think.

My final question is on the queued mutation, the queue is scoped to a single mutation function, but I suspect in reality there will be multiple mutation functions doing different things: create an issue, then create a comment. I may have missed it but does this support that?

Maybe the queue options can take a key, or a queue instance?

I think it could also be worth being more explicit in the docs how the queue version is different than normal mutations - maybe explain in the docs that normal mutations are not queued, then cross linking to the queued version.

[KyleAMathews]

the queue is scoped to a single mutation function, but I suspect in reality there will be multiple mutation functions doing different things: create an issue, then create a comment. I may have missed it but does this support that?

Yeah each hook creates a separate mutator — this is the same as the useMutation hook from Query.

So e.g.

const saveComment = usePacedMutatioin(...)

// in an onChange for the textarea
onChange={(e) => saveComment(e.value)}

[KyleAMathews]

Re docs — this is what I put there — seems clear enough?

---

Key Design

The fundamental difference between strategies is how they handle transactions:

Debounce/Throttle: Only one pending transaction (collecting mutations) and one persisting transaction (writing to backend) at a time. Multiple rapid mutations automatically merge together into a single transaction.

Queue: Each mutation creates a separate transaction, guaranteed to run in the order they're made (FIFO by default, configurable to LIFO). All mutations are guaranteed to persist.