📄 tanstack/db/latest/docs/reference/functions/createPacedMutations

function createPacedMutations<TVariables, T>(config): (variables) => Transaction<T>;


function createPacedMutations<TVariables, T>(config): (variables) => Transaction<T>;

Defined in: packages/db/src/paced-mutations.ts:87

Creates a paced mutations manager with pluggable timing strategies.

This function provides a way to control when and how optimistic mutations are persisted to the backend, using strategies like debouncing, queuing, or throttling. The optimistic updates are applied immediately via onMutate, and the actual persistence is controlled by the strategy.

The returned function accepts variables of type TVariables and returns a Transaction object that can be awaited to know when persistence completes or to handle errors.

Type Parameters
--------------- ### TVariables

TVariables = unknown

### T

T extends object = Record<string, unknown>

Parameters
---------- ### config

PacedMutationsConfig <TVariables, T>

Configuration including onMutate, mutationFn and strategy

Returns
-------

A function that accepts variables and returns a Transaction

(variables): Transaction<T>;


(variables): Transaction<T>;

### Parameters #### variables

TVariables

### Returns

Transaction <T>

Examples
--------

// Debounced mutations for auto-save
const updateTodo = createPacedMutations<string>({
  onMutate: (text) => {
    // Apply optimistic update immediately
    collection.update(id, draft => { draft.text = text })
  },
  mutationFn: async ({ transaction }) => {
    await api.save(transaction.mutations)
  },
  strategy: debounceStrategy({ wait: 500 })
})

// Call with variables, returns a transaction
const tx = updateTodo('New text')

// Await persistence or handle errors
await tx.isPersisted.promise


// Debounced mutations for auto-save
const updateTodo = createPacedMutations<string>({
  onMutate: (text) => {
    // Apply optimistic update immediately
    collection.update(id, draft => { draft.text = text })
  },
  mutationFn: async ({ transaction }) => {
    await api.save(transaction.mutations)
  },
  strategy: debounceStrategy({ wait: 500 })
})

// Call with variables, returns a transaction
const tx = updateTodo('New text')

// Await persistence or handle errors
await tx.isPersisted.promise

// Queue strategy for sequential processing
const addTodo = createPacedMutations<{ text: string }>({
  onMutate: ({ text }) => {
    collection.insert({ id: uuid(), text, completed: false })
  },
  mutationFn: async ({ transaction }) => {
    await api.save(transaction.mutations)
  },
  strategy: queueStrategy({
    wait: 200,
    addItemsTo: 'back',
    getItemsFrom: 'front'
  })
})


// Queue strategy for sequential processing
const addTodo = createPacedMutations<{ text: string }>({
  onMutate: ({ text }) => {
    collection.insert({ id: uuid(), text, completed: false })
  },
  mutationFn: async ({ transaction }) => {
    await api.save(transaction.mutations)
  },
  strategy: queueStrategy({
    wait: 200,
    addItemsTo: 'back',
    getItemsFrom: 'front'
  })
})

Edit on GitHub

Home

Partners Become a Partner

scarf analytics