@tanstack/db 0.0.27 → 0.0.29

package/src/query/optimizer.ts

@@ -116,11 +116,13 @@
  */
 
 import { deepEquals } from "../utils.js"
+import { CannotCombineEmptyExpressionListError } from "../errors.js"
 import {
   CollectionRef as CollectionRefClass,
   Func,
   QueryRef as QueryRefClass,
 } from "./ir.js"
+import { isConvertibleToCollectionFilter } from "./compiler/expressions.js"
 import type { BasicExpression, From, QueryIR } from "./ir.js"
 
 /**
@@ -143,6 +145,16 @@ export interface GroupedWhereClauses {
   multiSource?: BasicExpression<boolean>
 }
 
+/**
+ * Result of query optimization including both the optimized query and collection-specific WHERE clauses
+ */
+export interface OptimizationResult {
+  /** The optimized query with WHERE clauses potentially moved to subqueries */
+  optimizedQuery: QueryIR
+  /** Map of collection aliases to their extracted WHERE clauses for index optimization */
+  collectionWhereClauses: Map<string, BasicExpression<boolean>>
+}
+
 /**
  * Main query optimizer entry point that lifts WHERE clauses into subqueries.
  *
@@ -151,7 +163,7 @@ export interface GroupedWhereClauses {
  * sources as possible, then removing redundant subqueries.
  *
  * @param query - The QueryIR to optimize
- * @returns A new QueryIR with optimizations applied (or original if no optimization possible)
+ * @returns An OptimizationResult with the optimized query and collection WHERE clause mapping
  *
  * @example
  * ```typescript
@@ -161,11 +173,15 @@ export interface GroupedWhereClauses {
  *   where: [eq(u.dept_id, 1), gt(p.views, 100)]
  * }
  *
- * const optimized = optimizeQuery(originalQuery)
+ * const { optimizedQuery, collectionWhereClauses } = optimizeQuery(originalQuery)
  * // Result: Single-source clauses moved to deepest possible subqueries
+ * // collectionWhereClauses: Map { 'u' => eq(u.dept_id, 1), 'p' => gt(p.views, 100) }
  * ```
  */
-export function optimizeQuery(query: QueryIR): QueryIR {
+export function optimizeQuery(query: QueryIR): OptimizationResult {
+  // First, extract collection WHERE clauses before optimization
+  const collectionWhereClauses = extractCollectionWhereClauses(query)
+
   // Apply multi-level predicate pushdown with iterative convergence
   let optimized = query
   let previousOptimized: QueryIR | undefined
@@ -185,7 +201,80 @@ export function optimizeQuery(query: QueryIR): QueryIR {
   // Remove redundant subqueries
   const cleaned = removeRedundantSubqueries(optimized)
 
-  return cleaned
+  return {
+    optimizedQuery: cleaned,
+    collectionWhereClauses,
+  }
+}
+
+/**
+ * Extracts collection-specific WHERE clauses from a query for index optimization.
+ * This analyzes the original query to identify WHERE clauses that can be pushed down
+ * to specific collections, but only for simple queries without joins.
+ *
+ * @param query - The original QueryIR to analyze
+ * @returns Map of collection aliases to their WHERE clauses
+ */
+function extractCollectionWhereClauses(
+  query: QueryIR
+): Map<string, BasicExpression<boolean>> {
+  const collectionWhereClauses = new Map<string, BasicExpression<boolean>>()
+
+  // Only analyze queries that have WHERE clauses
+  if (!query.where || query.where.length === 0) {
+    return collectionWhereClauses
+  }
+
+  // Split all AND clauses at the root level for granular analysis
+  const splitWhereClauses = splitAndClauses(query.where)
+
+  // Analyze each WHERE clause to determine which sources it touches
+  const analyzedClauses = splitWhereClauses.map((clause) =>
+    analyzeWhereClause(clause)
+  )
+
+  // Group clauses by single-source vs multi-source
+  const groupedClauses = groupWhereClauses(analyzedClauses)
+
+  // Only include single-source clauses that reference collections directly
+  // and can be converted to BasicExpression format for collection indexes
+  for (const [sourceAlias, whereClause] of groupedClauses.singleSource) {
+    // Check if this source alias corresponds to a collection reference
+    if (isCollectionReference(query, sourceAlias)) {
+      // Check if the WHERE clause can be converted to collection-compatible format
+      if (isConvertibleToCollectionFilter(whereClause)) {
+        collectionWhereClauses.set(sourceAlias, whereClause)
+      }
+    }
+  }
+
+  return collectionWhereClauses
+}
+
+/**
+ * Determines if a source alias refers to a collection reference (not a subquery).
+ * This is used to identify WHERE clauses that can be pushed down to collection subscriptions.
+ *
+ * @param query - The query to analyze
+ * @param sourceAlias - The source alias to check
+ * @returns True if the alias refers to a collection reference
+ */
+function isCollectionReference(query: QueryIR, sourceAlias: string): boolean {
+  // Check the FROM clause
+  if (query.from.alias === sourceAlias) {
+    return query.from.type === `collectionRef`
+  }
+
+  // Check JOIN clauses
+  if (query.join) {
+    for (const joinClause of query.join) {
+      if (joinClause.from.alias === sourceAlias) {
+        return joinClause.from.type === `collectionRef`
+      }
+    }
+  }
+
+  return false
 }
 
 /**
@@ -726,7 +815,7 @@ function combineWithAnd(
   expressions: Array<BasicExpression<boolean>>
 ): BasicExpression<boolean> {
   if (expressions.length === 0) {
-    throw new Error(`Cannot combine empty expression list`)
+    throw new CannotCombineEmptyExpressionListError()
   }
 
   if (expressions.length === 1) {

package/src/transactions.ts

@@ -1,4 +1,10 @@
 import { createDeferred } from "./deferred"
+import {
+  MissingMutationFunctionError,
+  TransactionAlreadyCompletedRollbackError,
+  TransactionNotPendingCommitError,
+  TransactionNotPendingMutateError,
+} from "./errors"
 import type { Deferred } from "./deferred"
 import type {
   MutationFn,
@@ -124,7 +130,7 @@ class Transaction<T extends object = Record<string, unknown>> {
 
   constructor(config: TransactionConfig<T>) {
     if (typeof config.mutationFn === `undefined`) {
-      throw `mutationFn is required when creating a transaction`
+      throw new MissingMutationFunctionError()
     }
     this.id = config.id ?? crypto.randomUUID()
     this.mutationFn = config.mutationFn
@@ -186,7 +192,7 @@ class Transaction<T extends object = Record<string, unknown>> {
    */
   mutate(callback: () => void): Transaction<T> {
     if (this.state !== `pending`) {
-      throw `You can no longer call .mutate() as the transaction is no longer pending`
+      throw new TransactionNotPendingMutateError()
     }
 
     registerTransaction(this)
@@ -260,7 +266,7 @@ class Transaction<T extends object = Record<string, unknown>> {
   rollback(config?: { isSecondaryRollback?: boolean }): Transaction<T> {
     const isSecondaryRollback = config?.isSecondaryRollback ?? false
     if (this.state === `completed`) {
-      throw `You can no longer call .rollback() as the transaction is already completed`
+      throw new TransactionAlreadyCompletedRollbackError()
     }
 
     this.setState(`failed`)
@@ -342,7 +348,7 @@ class Transaction<T extends object = Record<string, unknown>> {
    */
   async commit(): Promise<Transaction<T>> {
     if (this.state !== `pending`) {
-      throw `You can no longer call .commit() as the transaction is no longer pending`
+      throw new TransactionNotPendingCommitError()
     }
 
     this.setState(`persisting`)

package/src/types.ts

@@ -3,6 +3,9 @@ import type { Collection } from "./collection"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
 import type { Transaction } from "./transactions"
 
+import type { SingleRowRefProxy } from "./query/builder/ref-proxy"
+import type { BasicExpression } from "./query/ir.js"
+
 /**
  * Helper type to extract the output type from a standard schema
  *
@@ -374,6 +377,15 @@ export interface CollectionConfig<
    * Defaults to false for lazy loading. Set to true to immediately sync.
    */
   startSync?: boolean
+  /**
+   * Auto-indexing mode for the collection.
+   * When enabled, indexes will be automatically created for simple where expressions.
+   * @default "eager"
+   * @description
+   * - "off": No automatic indexing
+   * - "eager": Automatically create indexes for simple where expressions in subscribeChanges (default)
+   */
+  autoIndex?: `off` | `eager`
   /**
    * Optional function to compare two items.
    * This is used to order the items in the collection.
@@ -555,6 +567,32 @@ export type KeyedNamespacedRow = [unknown, NamespacedRow]
  */
 export type NamespacedAndKeyedStream = IStreamBuilder<KeyedNamespacedRow>
 
+/**
+ * Options for subscribing to collection changes
+ */
+export interface SubscribeChangesOptions<
+  T extends object = Record<string, unknown>,
+> {
+  /** Whether to include the current state as initial changes */
+  includeInitialState?: boolean
+  /** Filter changes using a where expression */
+  where?: (row: SingleRowRefProxy<T>) => any
+  /** Pre-compiled expression for filtering changes */
+  whereExpression?: BasicExpression<boolean>
+}
+
+/**
+ * Options for getting current state as changes
+ */
+export interface CurrentStateAsChangesOptions<
+  T extends object = Record<string, unknown>,
+> {
+  /** Filter the current state using a where expression */
+  where?: (row: SingleRowRefProxy<T>) => any
+  /** Pre-compiled expression for filtering the current state */
+  whereExpression?: BasicExpression<boolean>
+}
+
 /**
  * Function type for listening to collection changes
  * @param changes - Array of change messages describing what happened

package/src/utils/array-utils.ts

@@ -0,0 +1,28 @@
+/**
+ * Finds the correct insert position for a value in a sorted array using binary search
+ * @param sortedArray The sorted array to search in
+ * @param value The value to find the position for
+ * @param compareFn Comparison function to use for ordering
+ * @returns The index where the value should be inserted to maintain order
+ */
+export function findInsertPosition<T>(
+  sortedArray: Array<[T, any]>,
+  value: T,
+  compareFn: (a: T, b: T) => number
+): number {
+  let left = 0
+  let right = sortedArray.length
+
+  while (left < right) {
+    const mid = Math.floor((left + right) / 2)
+    const comparison = compareFn(sortedArray[mid]![0], value)
+
+    if (comparison < 0) {
+      left = mid + 1
+    } else {
+      right = mid
+    }
+  }
+
+  return left
+}

package/src/utils/comparison.ts

@@ -0,0 +1,79 @@
+// WeakMap to store stable IDs for objects
+const objectIds = new WeakMap<object, number>()
+let nextObjectId = 1
+
+/**
+ * Get or create a stable ID for an object
+ */
+function getObjectId(obj: object): number {
+  if (objectIds.has(obj)) {
+    return objectIds.get(obj)!
+  }
+  const id = nextObjectId++
+  objectIds.set(obj, id)
+  return id
+}
+
+/**
+ * Universal comparison function for all data types
+ * Handles null/undefined, strings, arrays, dates, objects, and primitives
+ * Always sorts null/undefined values first
+ */
+export const ascComparator = (a: any, b: any): number => {
+  // Handle null/undefined
+  if (a == null && b == null) return 0
+  if (a == null) return -1
+  if (b == null) return 1
+
+  // if a and b are both strings, compare them based on locale
+  if (typeof a === `string` && typeof b === `string`) {
+    return a.localeCompare(b)
+  }
+
+  // if a and b are both arrays, compare them element by element
+  if (Array.isArray(a) && Array.isArray(b)) {
+    for (let i = 0; i < Math.min(a.length, b.length); i++) {
+      const result = ascComparator(a[i], b[i])
+      if (result !== 0) {
+        return result
+      }
+    }
+    // All elements are equal up to the minimum length
+    return a.length - b.length
+  }
+
+  // If both are dates, compare them
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() - b.getTime()
+  }
+
+  // If at least one of the values is an object, use stable IDs for comparison
+  const aIsObject = typeof a === `object`
+  const bIsObject = typeof b === `object`
+
+  if (aIsObject || bIsObject) {
+    // If both are objects, compare their stable IDs
+    if (aIsObject && bIsObject) {
+      const aId = getObjectId(a)
+      const bId = getObjectId(b)
+      return aId - bId
+    }
+
+    // If only one is an object, objects come after primitives
+    if (aIsObject) return 1
+    if (bIsObject) return -1
+  }
+
+  // For primitive values, use direct comparison
+  if (a < b) return -1
+  if (a > b) return 1
+  return 0
+}
+
+/**
+ * Descending comparator function for ordering values
+ * Handles null/undefined as largest values (opposite of ascending)
+ */
+export const descComparator = (a: unknown, b: unknown): number => {
+  return ascComparator(b, a)
+}