Function createPacedMutations

packages/db/src/paced-mutations.ts:87–169

(
  config: PacedMutationsConfig<TVariables, T>,
)

 * ```
 */
export function createPacedMutations<
  TVariables = unknown,
  T extends object = Record<string, unknown>,
>(
  config: PacedMutationsConfig<TVariables, T>,
): (variables: TVariables) => Transaction<T> {
  const { onMutate, mutationFn, strategy, ...transactionConfig } = config

  // The currently active transaction (pending, not yet persisting)
  let activeTransaction: Transaction<T> | null = null

  // Commit callback that the strategy will call when it's time to persist
  const commitCallback = () => {
    if (!activeTransaction) {
      throw new Error(
        `Strategy callback called but no active transaction exists. This indicates a bug in the strategy implementation.`,
      )
    }

    if (activeTransaction.state !== `pending`) {
      throw new Error(
        `Strategy callback called but active transaction is in state "${activeTransaction.state}". Expected "pending".`,
      )
    }

    const txToCommit = activeTransaction

    // Clear active transaction reference before committing
    activeTransaction = null

    // Commit the transaction
    txToCommit.commit().catch(() => {
      // Errors are handled via transaction.isPersisted.promise
      // This catch prevents unhandled promise rejections
    })

    return txToCommit
  }

  /**
   * Executes a mutation with the given variables. Creates a new transaction if none is active,
   * or adds to the existing active transaction. The strategy controls when
   * the transaction is actually committed.
   */
  function mutate(variables: TVariables): Transaction<T> {
    // Create a new transaction if we don't have an active one
    if (!activeTransaction || activeTransaction.state !== `pending`) {
      activeTransaction = createTransaction<T>({
        ...transactionConfig,
        mutationFn,
        autoCommit: false,
      })
    }

    // Execute onMutate with variables to apply optimistic updates
    activeTransaction.mutate(() => {
      onMutate(variables)
    })