@tanstack/db 0.4.15 → 0.4.17

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,48 @@
+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 = usePacedMutations({
+ *   onMutate: (value) => {
+ *     collection.update(id, draft => { draft.value = value })
+ *   },
+ *   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,68 @@
+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 = usePacedMutations({
+ *   onMutate: (volume) => {
+ *     settingsCollection.update('volume', draft => { draft.value = volume })
+ *   },
+ *   mutationFn: async ({ transaction }) => {
+ *     await api.updateVolume(transaction.mutations)
+ *   },
+ *   strategy: throttleStrategy({ wait: 200 })
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Throttle with leading and trailing execution
+ * const mutate = usePacedMutations({
+ *   onMutate: (data) => {
+ *     collection.update(id, draft => { Object.assign(draft, data) })
+ *   },
+ *   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

package/src/transactions.ts

@@ -1,4 +1,5 @@
 import { createDeferred } from "./deferred"
+import "./duplicate-instance-check"
 import {
   MissingMutationFunctionError,
   TransactionAlreadyCompletedRollbackError,
@@ -244,7 +245,9 @@ class Transaction<T extends object = Record<string, unknown>> {
 
   /**
    * Execute collection operations within this transaction
-   * @param callback - Function containing collection operations to group together
+   * @param callback - Function containing collection operations to group together. If the
+   * callback returns a Promise, the transaction context will remain active until the promise
+   * settles, allowing optimistic writes after `await` boundaries.
    * @returns This transaction for chaining
    * @example
    * // Group multiple operations
@@ -287,6 +290,7 @@ class Transaction<T extends object = Record<string, unknown>> {
     }
 
     registerTransaction(this)
+
     try {
       callback()
     } finally {

package/src/utils/type-guards.ts

@@ -0,0 +1,12 @@
+/**
+ * Type guard to check if a value is promise-like (has a `.then` method)
+ * @param value - The value to check
+ * @returns True if the value is promise-like, false otherwise
+ */
+export function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    !!value &&
+    (typeof value === `object` || typeof value === `function`) &&
+    typeof (value as { then?: unknown }).then === `function`
+  )
+}