@tanstack/db 0.4.14 → 0.4.16

package/src/indexes/auto-index.ts

@@ -44,14 +44,25 @@ export function ensureIndexForField<
 
   // Create a new index for this field using the collection's createIndex method
   try {
-    collection.createIndex((row) => (row as any)[fieldName], {
-      name: `auto_${fieldName}`,
-      indexType: BTreeIndex,
-      options: compareFn ? { compareFn, compareOptions } : {},
-    })
+    // Use the proxy-based approach to create the proper accessor for nested paths
+    collection.createIndex(
+      (row) => {
+        // Navigate through the field path
+        let current: any = row
+        for (const part of fieldPath) {
+          current = current[part]
+        }
+        return current
+      },
+      {
+        name: `auto:${fieldPath.join(`.`)}`,
+        indexType: BTreeIndex,
+        options: compareFn ? { compareFn, compareOptions } : {},
+      }
+    )
   } catch (error) {
     console.warn(
-      `${collection.id ? `[${collection.id}] ` : ``}Failed to create auto-index for field "${fieldName}":`,
+      `${collection.id ? `[${collection.id}] ` : ``}Failed to create auto-index for field path "${fieldPath.join(`.`)}":`,
       error
     )
   }
@@ -108,7 +119,7 @@ function extractIndexableExpressions(
       return
     }
 
-    // Check if the first argument is a property reference (single field)
+    // Check if the first argument is a property reference
     if (func.args.length < 1 || func.args[0].type !== `ref`) {
       return
     }
@@ -116,12 +127,14 @@ function extractIndexableExpressions(
     const fieldRef = func.args[0]
     const fieldPath = fieldRef.path
 
-    // Skip if it's not a simple field (e.g., nested properties or array access)
-    if (fieldPath.length !== 1) {
+    // Skip if the path is empty
+    if (fieldPath.length === 0) {
       return
     }
 
-    const fieldName = fieldPath[0]
+    // For nested paths, use the full path joined with underscores as the field name
+    // For simple paths, use the first (and only) element
+    const fieldName = fieldPath.join(`_`)
     results.push({ fieldName, fieldPath })
   }
 

package/src/local-storage.ts

@@ -44,6 +44,11 @@ interface StoredItem<T> {
   data: T
 }
 
+export interface Parser {
+  parse: (data: string) => unknown
+  stringify: (data: unknown) => string
+}
+
 /**
  * Configuration interface for localStorage collection options
  * @template T - The type of items in the collection
@@ -71,6 +76,12 @@ export interface LocalStorageCollectionConfig<
    * Can be any object that implements addEventListener/removeEventListener for storage events
    */
   storageEventApi?: StorageEventApi
+
+  /**
+   * Parser to use for serializing and deserializing data to and from storage
+   * Defaults to JSON
+   */
+  parser?: Parser
 }
 
 /**
@@ -113,13 +124,18 @@ export interface LocalStorageCollectionUtils extends UtilsRecord {
 
 /**
  * Validates that a value can be JSON serialized
+ * @param parser - The parser to use for serialization
  * @param value - The value to validate for JSON serialization
  * @param operation - The operation type being performed (for error messages)
  * @throws Error if the value cannot be JSON serialized
  */
-function validateJsonSerializable(value: any, operation: string): void {
+function validateJsonSerializable(
+  parser: Parser,
+  value: any,
+  operation: string
+): void {
   try {
-    JSON.stringify(value)
+    parser.stringify(value)
   } catch (error) {
     throw new SerializationError(
       operation,
@@ -314,6 +330,9 @@ export function localStorageCollectionOptions(
     (typeof window !== `undefined` ? window : null) ||
     createNoOpStorageEventApi()
 
+  // Default to JSON parser if no parser is provided
+  const parser = config.parser || JSON
+
   // Track the last known state to detect changes
   const lastKnownData = new Map<string | number, StoredItem<any>>()
 
@@ -322,6 +341,7 @@ export function localStorageCollectionOptions(
     config.storageKey,
     storage,
     storageEventApi,
+    parser,
     config.getKey,
     lastKnownData
   )
@@ -349,7 +369,7 @@ export function localStorageCollectionOptions(
       dataMap.forEach((storedItem, key) => {
         objectData[String(key)] = storedItem
       })
-      const serialized = JSON.stringify(objectData)
+      const serialized = parser.stringify(objectData)
       storage.setItem(config.storageKey, serialized)
     } catch (error) {
       console.error(
@@ -383,7 +403,7 @@ export function localStorageCollectionOptions(
   const wrappedOnInsert = async (params: InsertMutationFnParams<any>) => {
     // Validate that all values in the transaction can be JSON serialized
     params.transaction.mutations.forEach((mutation) => {
-      validateJsonSerializable(mutation.modified, `insert`)
+      validateJsonSerializable(parser, mutation.modified, `insert`)
     })
 
     // Call the user handler BEFORE persisting changes (if provided)
@@ -394,7 +414,7 @@ export function localStorageCollectionOptions(
 
     // Always persist to storage
     // Load current data from storage
-    const currentData = loadFromStorage<any>(config.storageKey, storage)
+    const currentData = loadFromStorage<any>(config.storageKey, storage, parser)
 
     // Add new items with version keys
     params.transaction.mutations.forEach((mutation) => {
@@ -418,7 +438,7 @@ export function localStorageCollectionOptions(
   const wrappedOnUpdate = async (params: UpdateMutationFnParams<any>) => {
     // Validate that all values in the transaction can be JSON serialized
     params.transaction.mutations.forEach((mutation) => {
-      validateJsonSerializable(mutation.modified, `update`)
+      validateJsonSerializable(parser, mutation.modified, `update`)
     })
 
     // Call the user handler BEFORE persisting changes (if provided)
@@ -429,7 +449,7 @@ export function localStorageCollectionOptions(
 
     // Always persist to storage
     // Load current data from storage
-    const currentData = loadFromStorage<any>(config.storageKey, storage)
+    const currentData = loadFromStorage<any>(config.storageKey, storage, parser)
 
     // Update items with new version keys
     params.transaction.mutations.forEach((mutation) => {
@@ -459,7 +479,7 @@ export function localStorageCollectionOptions(
 
     // Always persist to storage
     // Load current data from storage
-    const currentData = loadFromStorage<any>(config.storageKey, storage)
+    const currentData = loadFromStorage<any>(config.storageKey, storage, parser)
 
     // Remove items
     params.transaction.mutations.forEach((mutation) => {
@@ -518,10 +538,10 @@ export function localStorageCollectionOptions(
       switch (mutation.type) {
         case `insert`:
         case `update`:
-          validateJsonSerializable(mutation.modified, mutation.type)
+          validateJsonSerializable(parser, mutation.modified, mutation.type)
           break
         case `delete`:
-          validateJsonSerializable(mutation.original, mutation.type)
+          validateJsonSerializable(parser, mutation.original, mutation.type)
           break
       }
     }
@@ -529,7 +549,8 @@ export function localStorageCollectionOptions(
     // Load current data from storage
     const currentData = loadFromStorage<Record<string, unknown>>(
       config.storageKey,
-      storage
+      storage,
+      parser
     )
 
     // Apply each mutation
@@ -579,13 +600,15 @@ export function localStorageCollectionOptions(
 
 /**
  * Load data from storage and return as a Map
+ * @param parser - The parser to use for deserializing the data
  * @param storageKey - The key used to store data in the storage API
  * @param storage - The storage API to load from (localStorage, sessionStorage, etc.)
  * @returns Map of stored items with version tracking, or empty Map if loading fails
  */
 function loadFromStorage<T extends object>(
   storageKey: string,
-  storage: StorageApi
+  storage: StorageApi,
+  parser: Parser
 ): Map<string | number, StoredItem<T>> {
   try {
     const rawData = storage.getItem(storageKey)
@@ -593,7 +616,7 @@ function loadFromStorage<T extends object>(
       return new Map()
     }
 
-    const parsed = JSON.parse(rawData)
+    const parsed = parser.parse(rawData)
     const dataMap = new Map<string | number, StoredItem<T>>()
 
     // Handle object format where keys map to StoredItem values
@@ -644,6 +667,7 @@ function createLocalStorageSync<T extends object>(
   storageKey: string,
   storage: StorageApi,
   storageEventApi: StorageEventApi,
+  parser: Parser,
   _getKey: (item: T) => string | number,
   lastKnownData: Map<string | number, StoredItem<T>>
 ): SyncConfig<T> & {
@@ -704,7 +728,7 @@ function createLocalStorageSync<T extends object>(
     const { begin, write, commit } = syncParams
 
     // Load the new data
-    const newData = loadFromStorage<T>(storageKey, storage)
+    const newData = loadFromStorage<T>(storageKey, storage, parser)
 
     // Find the specific changes
     const changes = findChanges(lastKnownData, newData)
@@ -713,7 +737,7 @@ function createLocalStorageSync<T extends object>(
       begin()
       changes.forEach(({ type, value }) => {
         if (value) {
-          validateJsonSerializable(value, type)
+          validateJsonSerializable(parser, value, type)
           write({ type, value })
         }
       })
@@ -739,11 +763,11 @@ function createLocalStorageSync<T extends object>(
       collection = params.collection
 
       // Initial load
-      const initialData = loadFromStorage<T>(storageKey, storage)
+      const initialData = loadFromStorage<T>(storageKey, storage, parser)
       if (initialData.size > 0) {
         begin()
         initialData.forEach((storedItem) => {
-          validateJsonSerializable(storedItem.data, `load`)
+          validateJsonSerializable(parser, storedItem.data, `load`)
           write({ type: `insert`, value: storedItem.data })
         })
         commit()

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()
+    },
+  }
+}