@tanstack/db 0.4.15 → 0.4.16

package/src/paced-mutations.ts

@@ -0,0 +1,169 @@
+import { createTransaction } from "./transactions"
+import type { MutationFn, Transaction } from "./types"
+import type { Strategy } from "./strategies/types"
+
+/**
+ * Configuration for creating a paced mutations manager
+ */
+export interface PacedMutationsConfig<
+  TVariables = unknown,
+  T extends object = Record<string, unknown>,
+> {
+  /**
+   * Callback to apply optimistic updates immediately.
+   * Receives the variables passed to the mutate function.
+   */
+  onMutate: (variables: TVariables) => void
+  /**
+   * Function to execute the mutation on the server.
+   * Receives the transaction parameters containing all merged mutations.
+   */
+  mutationFn: MutationFn<T>
+  /**
+   * Strategy for controlling mutation execution timing
+   * Examples: debounceStrategy, queueStrategy, throttleStrategy
+   */
+  strategy: Strategy
+  /**
+   * Custom metadata to associate with transactions
+   */
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * 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.
+ *
+ * @param config - Configuration including onMutate, mutationFn and strategy
+ * @returns A function that accepts variables and returns a Transaction
+ *
+ * @example
+ * ```ts
+ * // Debounced mutations for auto-save
+ * const updateTodo = createPacedMutations<string>({
+ *   onMutate: (text) => {
+ *     // Apply optimistic update immediately
+ *     collection.update(id, draft => { draft.text = text })
+ *   },
+ *   mutationFn: async (text, { 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
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Queue strategy for sequential processing
+ * const addTodo = createPacedMutations<{ text: string }>({
+ *   onMutate: ({ text }) => {
+ *     collection.insert({ id: uuid(), text, completed: false })
+ *   },
+ *   mutationFn: async ({ text }, { transaction }) => {
+ *     await api.save(transaction.mutations)
+ *   },
+ *   strategy: queueStrategy({
+ *     wait: 200,
+ *     addItemsTo: 'back',
+ *     getItemsFrom: 'front'
+ *   })
+ * })
+ * ```
+ */
+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)
+    })
+
+    // Save reference before calling strategy.execute
+    const txToReturn = activeTransaction
+
+    // For queue strategy, pass a function that commits the captured transaction
+    // This prevents the error when commitCallback tries to access the cleared activeTransaction
+    if (strategy._type === `queue`) {
+      const capturedTx = activeTransaction
+      activeTransaction = null // Clear so next mutation creates a new transaction
+      strategy.execute(() => {
+        capturedTx.commit().catch(() => {
+          // Errors are handled via transaction.isPersisted.promise
+        })
+        return capturedTx
+      })
+    } else {
+      // For debounce/throttle, use commitCallback which manages activeTransaction
+      strategy.execute(commitCallback)
+    }
+
+    return txToReturn
+  }
+
+  return mutate
+}

package/src/query/optimizer.ts

@@ -330,9 +330,22 @@ function applySingleLevelOptimization(query: QueryIR): QueryIR {
     return query
   }
 
-  // Skip optimization if there are no joins - predicate pushdown only benefits joins
-  // Single-table queries don't benefit from this optimization
+  // For queries without joins, combine multiple WHERE clauses into a single clause
+  // to avoid creating multiple filter operators in the pipeline
   if (!query.join || query.join.length === 0) {
+    // Only optimize if there are multiple WHERE clauses to combine
+    if (query.where.length > 1) {
+      // Combine multiple WHERE clauses into a single AND expression
+      const splitWhereClauses = splitAndClauses(query.where)
+      const combinedWhere = combineWithAnd(splitWhereClauses)
+
+      return {
+        ...query,
+        where: [combinedWhere],
+      }
+    }
+
+    // For single WHERE clauses, no optimization needed
     return query
   }
 
@@ -674,6 +687,20 @@ function applyOptimizations(
     // If optimized and no outer JOINs - don't keep (original behavior)
   }
 
+  // Combine multiple remaining WHERE clauses into a single clause to avoid
+  // multiple filter operations in the pipeline (performance optimization)
+  // First flatten any nested AND expressions to avoid and(and(...), ...)
+  const finalWhere: Array<Where> =
+    remainingWhereClauses.length > 1
+      ? [
+          combineWithAnd(
+            remainingWhereClauses.flatMap((clause) =>
+              splitAndClausesRecursive(getWhereExpression(clause))
+            )
+          ),
+        ]
+      : remainingWhereClauses
+
   // Create a completely new query object to ensure immutability
   const optimizedQuery: QueryIR = {
     // Copy all non-optimized fields as-is
@@ -692,8 +719,8 @@ function applyOptimizations(
     from: optimizedFrom,
     join: optimizedJoins,
 
-    // Only include WHERE clauses that weren't successfully optimized
-    where: remainingWhereClauses.length > 0 ? remainingWhereClauses : [],
+    // Include combined WHERE clauses
+    where: finalWhere.length > 0 ? finalWhere : [],
   }
 
   return optimizedQuery

package/src/strategies/debounceStrategy.ts

@@ -0,0 +1,45 @@
+import { Debouncer } from "@tanstack/pacer/debouncer"
+import type { DebounceStrategy, DebounceStrategyOptions } from "./types"
+import type { Transaction } from "../transactions"
+
+/**
+ * Creates a debounce strategy that delays transaction execution until after
+ * a period of inactivity.
+ *
+ * Ideal for scenarios like search inputs or auto-save fields where you want
+ * to wait for the user to stop typing before persisting changes.
+ *
+ * @param options - Configuration for the debounce behavior
+ * @returns A debounce strategy instance
+ *
+ * @example
+ * ```ts
+ * const mutate = useSerializedTransaction({
+ *   mutationFn: async ({ transaction }) => {
+ *     await api.save(transaction.mutations)
+ *   },
+ *   strategy: debounceStrategy({ wait: 500 })
+ * })
+ * ```
+ */
+export function debounceStrategy(
+  options: DebounceStrategyOptions
+): DebounceStrategy {
+  const debouncer = new Debouncer(
+    (callback: () => Transaction) => callback(),
+    options
+  )
+
+  return {
+    _type: `debounce`,
+    options,
+    execute: <T extends object = Record<string, unknown>>(
+      fn: () => Transaction<T>
+    ) => {
+      debouncer.maybeExecute(fn as () => Transaction)
+    },
+    cleanup: () => {
+      debouncer.cancel()
+    },
+  }
+}

package/src/strategies/index.ts

@@ -0,0 +1,17 @@
+// Export all strategy factories
+export { debounceStrategy } from "./debounceStrategy"
+export { queueStrategy } from "./queueStrategy"
+export { throttleStrategy } from "./throttleStrategy"
+
+// Export strategy types
+export type {
+  Strategy,
+  BaseStrategy,
+  DebounceStrategy,
+  DebounceStrategyOptions,
+  QueueStrategy,
+  QueueStrategyOptions,
+  ThrottleStrategy,
+  ThrottleStrategyOptions,
+  StrategyOptions,
+} from "./types"

package/src/strategies/queueStrategy.ts

@@ -0,0 +1,75 @@
+import { AsyncQueuer } from "@tanstack/pacer/async-queuer"
+import type { QueueStrategy, QueueStrategyOptions } from "./types"
+import type { Transaction } from "../transactions"
+
+/**
+ * Creates a queue strategy that processes all mutations in order with proper serialization.
+ *
+ * Unlike other strategies that may drop executions, queue ensures every
+ * mutation is processed sequentially. Each transaction commit completes before
+ * the next one starts. Useful when data consistency is critical and
+ * every operation must complete in order.
+ *
+ * @param options - Configuration for queue behavior (FIFO/LIFO, timing, size limits)
+ * @returns A queue strategy instance
+ *
+ * @example
+ * ```ts
+ * // FIFO queue - process in order received
+ * const mutate = usePacedMutations({
+ *   mutationFn: async ({ transaction }) => {
+ *     await api.save(transaction.mutations)
+ *   },
+ *   strategy: queueStrategy({
+ *     wait: 200,
+ *     addItemsTo: 'back',
+ *     getItemsFrom: 'front'
+ *   })
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // LIFO queue - process most recent first
+ * const mutate = usePacedMutations({
+ *   mutationFn: async ({ transaction }) => {
+ *     await api.save(transaction.mutations)
+ *   },
+ *   strategy: queueStrategy({
+ *     wait: 200,
+ *     addItemsTo: 'back',
+ *     getItemsFrom: 'back'
+ *   })
+ * })
+ * ```
+ */
+export function queueStrategy(options?: QueueStrategyOptions): QueueStrategy {
+  const queuer = new AsyncQueuer<void>({
+    concurrency: 1, // Process one at a time to ensure serialization
+    wait: options?.wait,
+    maxSize: options?.maxSize,
+    addItemsTo: options?.addItemsTo ?? `back`, // Default FIFO: add to back
+    getItemsFrom: options?.getItemsFrom ?? `front`, // Default FIFO: get from front
+    started: true, // Start processing immediately
+  })
+
+  return {
+    _type: `queue`,
+    options,
+    execute: <T extends object = Record<string, unknown>>(
+      fn: () => Transaction<T>
+    ) => {
+      // Wrap the callback in an async function that waits for persistence
+      queuer.addItem(async () => {
+        const transaction = fn()
+        // Wait for the transaction to be persisted before processing next item
+        // Note: fn() already calls commit(), we just wait for it to complete
+        await transaction.isPersisted.promise
+      })
+    },
+    cleanup: () => {
+      queuer.stop()
+      queuer.clear()
+    },
+  }
+}

package/src/strategies/throttleStrategy.ts

@@ -0,0 +1,62 @@
+import { Throttler } from "@tanstack/pacer/throttler"
+import type { ThrottleStrategy, ThrottleStrategyOptions } from "./types"
+import type { Transaction } from "../transactions"
+
+/**
+ * Creates a throttle strategy that ensures transactions are evenly spaced
+ * over time.
+ *
+ * Provides smooth, controlled execution patterns ideal for UI updates like
+ * sliders, progress bars, or scroll handlers where you want consistent
+ * execution timing.
+ *
+ * @param options - Configuration for throttle behavior
+ * @returns A throttle strategy instance
+ *
+ * @example
+ * ```ts
+ * // Throttle slider updates to every 200ms
+ * const mutate = useSerializedTransaction({
+ *   mutationFn: async ({ transaction }) => {
+ *     await api.updateVolume(transaction.mutations)
+ *   },
+ *   strategy: throttleStrategy({ wait: 200 })
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Throttle with leading and trailing execution
+ * const mutate = useSerializedTransaction({
+ *   mutationFn: async ({ transaction }) => {
+ *     await api.save(transaction.mutations)
+ *   },
+ *   strategy: throttleStrategy({
+ *     wait: 500,
+ *     leading: true,
+ *     trailing: true
+ *   })
+ * })
+ * ```
+ */
+export function throttleStrategy(
+  options: ThrottleStrategyOptions
+): ThrottleStrategy {
+  const throttler = new Throttler(
+    (callback: () => Transaction) => callback(),
+    options
+  )
+
+  return {
+    _type: `throttle`,
+    options,
+    execute: <T extends object = Record<string, unknown>>(
+      fn: () => Transaction<T>
+    ) => {
+      throttler.maybeExecute(fn as () => Transaction)
+    },
+    cleanup: () => {
+      throttler.cancel()
+    },
+  }
+}

package/src/strategies/types.ts

@@ -0,0 +1,130 @@
+import type { Transaction } from "../transactions"
+
+/**
+ * Base strategy interface that all strategy implementations must conform to
+ */
+export interface BaseStrategy<TName extends string = string> {
+  /** Type discriminator for strategy identification */
+  _type: TName
+
+  /**
+   * Execute a function according to the strategy's timing rules
+   * @param fn - The function to execute
+   * @returns The result of the function execution (if applicable)
+   */
+  execute: <T extends object = Record<string, unknown>>(
+    fn: () => Transaction<T>
+  ) => void | Promise<void>
+
+  /**
+   * Clean up any resources held by the strategy
+   * Should be called when the strategy is no longer needed
+   */
+  cleanup: () => void
+}
+
+/**
+ * Options for debounce strategy
+ * Delays execution until after a period of inactivity
+ */
+export interface DebounceStrategyOptions {
+  /** Wait time in milliseconds before execution */
+  wait: number
+  /** Execute immediately on the first call */
+  leading?: boolean
+  /** Execute after the wait period on the last call */
+  trailing?: boolean
+}
+
+/**
+ * Debounce strategy that delays execution until activity stops
+ */
+export interface DebounceStrategy extends BaseStrategy<`debounce`> {
+  options: DebounceStrategyOptions
+}
+
+/**
+ * Options for queue strategy
+ * Processes all executions in order (FIFO/LIFO)
+ */
+export interface QueueStrategyOptions {
+  /** Wait time between processing queue items (milliseconds) */
+  wait?: number
+  /** Maximum queue size (items are dropped if exceeded) */
+  maxSize?: number
+  /** Where to add new items in the queue */
+  addItemsTo?: `front` | `back`
+  /** Where to get items from when processing */
+  getItemsFrom?: `front` | `back`
+}
+
+/**
+ * Queue strategy that processes all executions in order
+ * FIFO: { addItemsTo: 'back', getItemsFrom: 'front' }
+ * LIFO: { addItemsTo: 'back', getItemsFrom: 'back' }
+ */
+export interface QueueStrategy extends BaseStrategy<`queue`> {
+  options?: QueueStrategyOptions
+}
+
+/**
+ * Options for throttle strategy
+ * Ensures executions are evenly spaced over time
+ */
+export interface ThrottleStrategyOptions {
+  /** Minimum wait time between executions (milliseconds) */
+  wait: number
+  /** Execute immediately on the first call */
+  leading?: boolean
+  /** Execute on the last call after wait period */
+  trailing?: boolean
+}
+
+/**
+ * Throttle strategy that spaces executions evenly over time
+ */
+export interface ThrottleStrategy extends BaseStrategy<`throttle`> {
+  options: ThrottleStrategyOptions
+}
+
+/**
+ * Options for batch strategy
+ * Groups multiple executions together
+ */
+export interface BatchStrategyOptions {
+  /** Maximum items per batch */
+  maxSize?: number
+  /** Maximum wait time before processing batch (milliseconds) */
+  wait?: number
+  /** Custom logic to determine when to execute batch */
+  getShouldExecute?: (items: Array<any>) => boolean
+}
+
+/**
+ * Batch strategy that groups multiple executions together
+ */
+export interface BatchStrategy extends BaseStrategy<`batch`> {
+  options?: BatchStrategyOptions
+}
+
+/**
+ * Union type of all available strategies
+ */
+export type Strategy =
+  | DebounceStrategy
+  | QueueStrategy
+  | ThrottleStrategy
+  | BatchStrategy
+
+/**
+ * Extract the options type from a strategy
+ */
+export type StrategyOptions<T extends Strategy> = T extends DebounceStrategy
+  ? DebounceStrategyOptions
+  : T extends QueueStrategy
+    ? QueueStrategyOptions
+    : T extends ThrottleStrategy
+      ? ThrottleStrategyOptions
+      : T extends BatchStrategy
+        ? BatchStrategyOptions
+        : never