@tanstack/db 0.5.15 → 0.5.17

package/src/collection/changes.ts

@@ -1,4 +1,8 @@
 import { NegativeActiveSubscribersError } from '../errors'
+import {
+  createSingleRowRefProxy,
+  toExpression,
+} from '../query/builder/ref-proxy.js'
 import { CollectionSubscription } from './subscription.js'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { ChangeMessage, SubscribeChangesOptions } from '../types'
@@ -94,13 +98,29 @@ export class CollectionChangesManager<
    */
   public subscribeChanges(
     callback: (changes: Array<ChangeMessage<TOutput>>) => void,
-    options: SubscribeChangesOptions = {},
+    options: SubscribeChangesOptions<TOutput> = {},
   ): CollectionSubscription {
     // Start sync and track subscriber
     this.addSubscriber()
 
+    // Compile where callback to whereExpression if provided
+    if (options.where && options.whereExpression) {
+      throw new Error(
+        `Cannot specify both 'where' and 'whereExpression' options. Use one or the other.`,
+      )
+    }
+
+    const { where, ...opts } = options
+    let whereExpression = opts.whereExpression
+    if (where) {
+      const proxy = createSingleRowRefProxy<TOutput>()
+      const result = where(proxy)
+      whereExpression = toExpression(result)
+    }
+
     const subscription = new CollectionSubscription(this.collection, callback, {
-      ...options,
+      ...opts,
+      whereExpression,
       onUnsubscribe: () => {
         this.removeSubscriber()
         this.changeSubscriptions.delete(subscription)

package/src/collection/index.ts

@@ -849,26 +849,29 @@ export class CollectionImpl<
    * }, { includeInitialState: true })
    *
    * @example
-   * // Subscribe only to changes matching a condition
+   * // Subscribe only to changes matching a condition using where callback
+   * import { eq } from "@tanstack/db"
+   *
    * const subscription = collection.subscribeChanges((changes) => {
    *   updateUI(changes)
    * }, {
    *   includeInitialState: true,
-   *   where: (row) => row.status === 'active'
+   *   where: (row) => eq(row.status, "active")
    * })
    *
    * @example
-   * // Subscribe using a pre-compiled expression
+   * // Using multiple conditions with and()
+   * import { and, eq, gt } from "@tanstack/db"
+   *
    * const subscription = collection.subscribeChanges((changes) => {
    *   updateUI(changes)
    * }, {
-   *   includeInitialState: true,
-   *   whereExpression: eq(row.status, 'active')
+   *   where: (row) => and(eq(row.status, "active"), gt(row.priority, 5))
    * })
    */
   public subscribeChanges(
     callback: (changes: Array<ChangeMessage<TOutput>>) => void,
-    options: SubscribeChangesOptions = {},
+    options: SubscribeChangesOptions<TOutput> = {},
   ): CollectionSubscription {
     return this._changes.subscribeChanges(callback, options)
   }

package/src/collection/subscription.ts

@@ -1,7 +1,8 @@
 import { ensureIndexForExpression } from '../indexes/auto-index.js'
 import { and, eq, gte, lt } from '../query/builder/functions.js'
-import { Value } from '../query/ir.js'
+import { PropRef, Value } from '../query/ir.js'
 import { EventEmitter } from '../event-emitter.js'
+import { compileExpression } from '../query/compiler/evaluators.js'
 import { buildCursor } from '../utils/cursor.js'
 import {
   createFilterFunctionFromExpression,
@@ -494,6 +495,13 @@ export class CollectionSubscription
     const valuesNeeded = () => Math.max(limit - changes.length, 0)
     const collectionExhausted = () => keys.length === 0
 
+    // Create a value extractor for the orderBy field to properly track the biggest indexed value
+    const orderByExpression = orderBy[0]!.expression
+    const valueExtractor =
+      orderByExpression.type === `ref`
+        ? compileExpression(new PropRef(orderByExpression.path), true)
+        : null
+
     while (valuesNeeded() > 0 && !collectionExhausted()) {
       const insertedKeys = new Set<string | number>() // Track keys we add to `changes` in this iteration
 
@@ -504,7 +512,9 @@ export class CollectionSubscription
           key,
           value,
         })
-        biggestObservedValue = value
+        // Extract the indexed value (e.g., salary) from the row, not the full row
+        // This is needed for index.take() to work correctly with the BTree comparator
+        biggestObservedValue = valueExtractor ? valueExtractor(value) : value
         insertedKeys.add(key) // Track this key
       }
 

package/src/errors.ts

@@ -390,6 +390,19 @@ export class QueryMustHaveFromClauseError extends QueryBuilderError {
   }
 }
 
+export class InvalidWhereExpressionError extends QueryBuilderError {
+  constructor(valueType: string) {
+    super(
+      `Invalid where() expression: Expected a query expression, but received a ${valueType}. ` +
+        `This usually happens when using JavaScript's comparison operators (===, !==, <, >, etc.) directly. ` +
+        `Instead, use the query builder functions:\n\n` +
+        `  ❌ .where(({ user }) => user.id === 'abc')\n` +
+        `  ✅ .where(({ user }) => eq(user.id, 'abc'))\n\n` +
+        `Available comparison functions: eq, gt, gte, lt, lte, and, or, not, like, ilike, isNull, isUndefined`,
+    )
+  }
+}
+
 // Query Compilation Errors
 export class QueryCompilationError extends TanStackDBError {
   constructor(message: string) {

package/src/query/builder/index.ts

@@ -11,6 +11,7 @@ import {
 import {
   InvalidSourceError,
   InvalidSourceTypeError,
+  InvalidWhereExpressionError,
   JoinConditionMustBeEqualityError,
   OnlyOneSourceAllowedError,
   QueryMustHaveFromClauseError,
@@ -29,6 +30,7 @@ import type {
 import type {
   CompareOptions,
   Context,
+  GetResult,
   GroupByCallback,
   JoinOnCallback,
   MergeContextForJoinCallback,
@@ -361,6 +363,13 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
     const refProxy = createRefProxy(aliases) as RefsForContext<TContext>
     const expression = callback(refProxy)
 
+    // Validate that the callback returned a valid expression
+    // This catches common mistakes like using JavaScript comparison operators (===, !==, etc.)
+    // which return boolean primitives instead of expression objects
+    if (!isExpressionLike(expression)) {
+      throw new InvalidWhereExpressionError(getValueTypeName(expression))
+    }
+
     const existingWhere = this.query.where || []
 
     return new BaseQueryBuilder({
@@ -402,6 +411,13 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
     const refProxy = createRefProxy(aliases) as RefsForContext<TContext>
     const expression = callback(refProxy)
 
+    // Validate that the callback returned a valid expression
+    // This catches common mistakes like using JavaScript comparison operators (===, !==, etc.)
+    // which return boolean primitives instead of expression objects
+    if (!isExpressionLike(expression)) {
+      throw new InvalidWhereExpressionError(getValueTypeName(expression))
+    }
+
     const existingHaving = this.query.having || []
 
     return new BaseQueryBuilder({
@@ -789,6 +805,14 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
   }
 }
 
+// Helper to get a descriptive type name for error messages
+function getValueTypeName(value: unknown): string {
+  if (value === null) return `null`
+  if (value === undefined) return `undefined`
+  if (typeof value === `object`) return `object`
+  return typeof value
+}
+
 // Helper to ensure we have a BasicExpression/Aggregate for a value
 function toExpr(value: any): BasicExpression | Aggregate {
   if (value === undefined) return toExpression(null)
@@ -864,6 +888,9 @@ export type ExtractContext<T> =
       ? TContext
       : never
 
+// Helper type to extract the result type from a QueryBuilder (similar to Zod's z.infer)
+export type QueryResult<T> = GetResult<ExtractContext<T>>
+
 // Export the types from types.ts for convenience
 export type {
   Context,

package/src/query/index.ts

@@ -10,6 +10,8 @@ export {
   type Source,
   type GetResult,
   type InferResultType,
+  type ExtractContext,
+  type QueryResult,
 } from './builder/index.js'
 
 // Expression functions exports

package/src/types.ts

@@ -4,6 +4,7 @@ import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { Transaction } from './transactions'
 import type { BasicExpression, OrderBy } from './query/ir.js'
 import type { EventEmitter } from './event-emitter.js'
+import type { SingleRowRefProxy } from './query/builder/ref-proxy.js'
 
 /**
  * Interface for a collection-like object that provides the necessary methods
@@ -775,17 +776,33 @@ export type NamespacedAndKeyedStream = IStreamBuilder<KeyedNamespacedRow>
 /**
  * Options for subscribing to collection changes
  */
-export interface SubscribeChangesOptions {
+export interface SubscribeChangesOptions<
+  T extends object = Record<string, unknown>,
+> {
   /** Whether to include the current state as initial changes */
   includeInitialState?: boolean
+  /**
+   * Callback function for filtering changes using a row proxy.
+   * The callback receives a proxy object that records property access,
+   * allowing you to use query builder functions like `eq`, `gt`, etc.
+   *
+   * @example
+   * ```ts
+   * import { eq } from "@tanstack/db"
+   *
+   * collection.subscribeChanges(callback, {
+   *   where: (row) => eq(row.status, "active")
+   * })
+   * ```
+   */
+  where?: (row: SingleRowRefProxy<T>) => any
   /** Pre-compiled expression for filtering changes */
   whereExpression?: BasicExpression<boolean>
 }
 
-export interface SubscribeChangesSnapshotOptions extends Omit<
-  SubscribeChangesOptions,
-  `includeInitialState`
-> {
+export interface SubscribeChangesSnapshotOptions<
+  T extends object = Record<string, unknown>,
+> extends Omit<SubscribeChangesOptions<T>, `includeInitialState`> {
   orderBy?: OrderBy
   limit?: number
 }

package/src/utils.ts

@@ -52,12 +52,16 @@ function deepEqualsInternal(
     if (!(b instanceof Date)) return false
     return a.getTime() === b.getTime()
   }
+  // Symmetric check: if b is Date but a is not, they're not equal
+  if (b instanceof Date) return false
 
   // Handle RegExp objects
   if (a instanceof RegExp) {
     if (!(b instanceof RegExp)) return false
     return a.source === b.source && a.flags === b.flags
   }
+  // Symmetric check: if b is RegExp but a is not, they're not equal
+  if (b instanceof RegExp) return false
 
   // Handle Map objects - only if both are Maps
   if (a instanceof Map) {
@@ -78,6 +82,8 @@ function deepEqualsInternal(
     visited.delete(a)
     return result
   }
+  // Symmetric check: if b is Map but a is not, they're not equal
+  if (b instanceof Map) return false
 
   // Handle Set objects - only if both are Sets
   if (a instanceof Set) {
@@ -106,6 +112,8 @@ function deepEqualsInternal(
     visited.delete(a)
     return result
   }
+  // Symmetric check: if b is Set but a is not, they're not equal
+  if (b instanceof Set) return false
 
   // Handle TypedArrays
   if (
@@ -124,6 +132,14 @@ function deepEqualsInternal(
 
     return true
   }
+  // Symmetric check: if b is TypedArray but a is not, they're not equal
+  if (
+    ArrayBuffer.isView(b) &&
+    !(b instanceof DataView) &&
+    !ArrayBuffer.isView(a)
+  ) {
+    return false
+  }
 
   // Handle Temporal objects
   // Check if both are Temporal objects of the same type
@@ -142,6 +158,8 @@ function deepEqualsInternal(
     // Fallback to toString comparison for other types
     return a.toString() === b.toString()
   }
+  // Symmetric check: if b is Temporal but a is not, they're not equal
+  if (isTemporal(b)) return false
 
   // Handle arrays
   if (Array.isArray(a)) {
@@ -159,6 +177,8 @@ function deepEqualsInternal(
     visited.delete(a)
     return result
   }
+  // Symmetric check: if b is array but a is not, they're not equal
+  if (Array.isArray(b)) return false
 
   // Handle objects
   if (typeof a === `object`) {