@tanstack/db 0.5.16 → 0.5.18

package/dist/esm/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["/**\n * Generic utility functions\n */\n\nimport type { CompareOptions } from './query/builder/types'\n\ninterface TypedArray {\n  length: number\n  [index: number]: number\n}\n\n/**\n * Deep equality function that compares two values recursively\n * Handles primitives, objects, arrays, Date, RegExp, Map, Set, TypedArrays, and Temporal objects\n *\n * @param a - First value to compare\n * @param b - Second value to compare\n * @returns True if the values are deeply equal, false otherwise\n *\n * @example\n * ```typescript\n * deepEquals({ a: 1, b: 2 }, { b: 2, a: 1 }) // true (property order doesn't matter)\n * deepEquals([1, { x: 2 }], [1, { x: 2 }]) // true\n * deepEquals({ a: 1 }, { a: 2 }) // false\n * deepEquals(new Date('2023-01-01'), new Date('2023-01-01')) // true\n * deepEquals(new Map([['a', 1]]), new Map([['a', 1]])) // true\n * ```\n */\nexport function deepEquals(a: any, b: any): boolean {\n  return deepEqualsInternal(a, b, new Map())\n}\n\n/**\n * Internal implementation with cycle detection to prevent infinite recursion\n */\nfunction deepEqualsInternal(\n  a: any,\n  b: any,\n  visited: Map<object, object>,\n): boolean {\n  // Handle strict equality (primitives, same reference)\n  if (a === b) return true\n\n  // Handle null/undefined\n  if (a == null || b == null) return false\n\n  // Handle different types\n  if (typeof a !== typeof b) return false\n\n  // Handle Date objects\n  if (a instanceof Date) {\n    if (!(b instanceof Date)) return false\n    return a.getTime() === b.getTime()\n  }\n\n  // Handle RegExp objects\n  if (a instanceof RegExp) {\n    if (!(b instanceof RegExp)) return false\n    return a.source === b.source && a.flags === b.flags\n  }\n\n  // Handle Map objects - only if both are Maps\n  if (a instanceof Map) {\n    if (!(b instanceof Map)) return false\n    if (a.size !== b.size) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    const entries = Array.from(a.entries())\n    const result = entries.every(([key, val]) => {\n      return b.has(key) && deepEqualsInternal(val, b.get(key), visited)\n    })\n\n    visited.delete(a)\n    return result\n  }\n\n  // Handle Set objects - only if both are Sets\n  if (a instanceof Set) {\n    if (!(b instanceof Set)) return false\n    if (a.size !== b.size) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    // Convert to arrays for comparison\n    const aValues = Array.from(a)\n    const bValues = Array.from(b)\n\n    // Simple comparison for primitive values\n    if (aValues.every((val) => typeof val !== `object`)) {\n      visited.delete(a)\n      return aValues.every((val) => b.has(val))\n    }\n\n    // For objects in sets, we need to do a more complex comparison\n    // This is a simplified approach and may not work for all cases\n    const result = aValues.length === bValues.length\n    visited.delete(a)\n    return result\n  }\n\n  // Handle TypedArrays\n  if (\n    ArrayBuffer.isView(a) &&\n    ArrayBuffer.isView(b) &&\n    !(a instanceof DataView) &&\n    !(b instanceof DataView)\n  ) {\n    const typedA = a as unknown as TypedArray\n    const typedB = b as unknown as TypedArray\n    if (typedA.length !== typedB.length) return false\n\n    for (let i = 0; i < typedA.length; i++) {\n      if (typedA[i] !== typedB[i]) return false\n    }\n\n    return true\n  }\n\n  // Handle Temporal objects\n  // Check if both are Temporal objects of the same type\n  if (isTemporal(a) && isTemporal(b)) {\n    const aTag = getStringTag(a)\n    const bTag = getStringTag(b)\n\n    // If they're different Temporal types, they're not equal\n    if (aTag !== bTag) return false\n\n    // Use Temporal's built-in equals method if available\n    if (typeof a.equals === `function`) {\n      return a.equals(b)\n    }\n\n    // Fallback to toString comparison for other types\n    return a.toString() === b.toString()\n  }\n\n  // Handle arrays\n  if (Array.isArray(a)) {\n    if (!Array.isArray(b) || a.length !== b.length) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    const result = a.every((item, index) =>\n      deepEqualsInternal(item, b[index], visited),\n    )\n    visited.delete(a)\n    return result\n  }\n\n  // Handle objects\n  if (typeof a === `object`) {\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    // Get all keys from both objects\n    const keysA = Object.keys(a)\n    const keysB = Object.keys(b)\n\n    // Check if they have the same number of keys\n    if (keysA.length !== keysB.length) {\n      visited.delete(a)\n      return false\n    }\n\n    // Check if all keys exist in both objects and their values are equal\n    const result = keysA.every(\n      (key) => key in b && deepEqualsInternal(a[key], b[key], visited),\n    )\n\n    visited.delete(a)\n    return result\n  }\n\n  // For primitives that aren't strictly equal\n  return false\n}\n\nconst temporalTypes = [\n  `Temporal.Duration`,\n  `Temporal.Instant`,\n  `Temporal.PlainDate`,\n  `Temporal.PlainDateTime`,\n  `Temporal.PlainMonthDay`,\n  `Temporal.PlainTime`,\n  `Temporal.PlainYearMonth`,\n  `Temporal.ZonedDateTime`,\n]\n\nfunction getStringTag(a: any): any {\n  return a[Symbol.toStringTag]\n}\n\n/** Checks if the value is a Temporal object by checking for the Temporal brand */\nexport function isTemporal(a: any): boolean {\n  const tag = getStringTag(a)\n  return typeof tag === `string` && temporalTypes.includes(tag)\n}\n\nexport const DEFAULT_COMPARE_OPTIONS: CompareOptions = {\n  direction: `asc`,\n  nulls: `first`,\n  stringSort: `locale`,\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["/**\n * Generic utility functions\n */\n\nimport type { CompareOptions } from './query/builder/types'\n\ninterface TypedArray {\n  length: number\n  [index: number]: number\n}\n\n/**\n * Deep equality function that compares two values recursively\n * Handles primitives, objects, arrays, Date, RegExp, Map, Set, TypedArrays, and Temporal objects\n *\n * @param a - First value to compare\n * @param b - Second value to compare\n * @returns True if the values are deeply equal, false otherwise\n *\n * @example\n * ```typescript\n * deepEquals({ a: 1, b: 2 }, { b: 2, a: 1 }) // true (property order doesn't matter)\n * deepEquals([1, { x: 2 }], [1, { x: 2 }]) // true\n * deepEquals({ a: 1 }, { a: 2 }) // false\n * deepEquals(new Date('2023-01-01'), new Date('2023-01-01')) // true\n * deepEquals(new Map([['a', 1]]), new Map([['a', 1]])) // true\n * ```\n */\nexport function deepEquals(a: any, b: any): boolean {\n  return deepEqualsInternal(a, b, new Map())\n}\n\n/**\n * Internal implementation with cycle detection to prevent infinite recursion\n */\nfunction deepEqualsInternal(\n  a: any,\n  b: any,\n  visited: Map<object, object>,\n): boolean {\n  // Handle strict equality (primitives, same reference)\n  if (a === b) return true\n\n  // Handle null/undefined\n  if (a == null || b == null) return false\n\n  // Handle different types\n  if (typeof a !== typeof b) return false\n\n  // Handle Date objects\n  if (a instanceof Date) {\n    if (!(b instanceof Date)) return false\n    return a.getTime() === b.getTime()\n  }\n  // Symmetric check: if b is Date but a is not, they're not equal\n  if (b instanceof Date) return false\n\n  // Handle RegExp objects\n  if (a instanceof RegExp) {\n    if (!(b instanceof RegExp)) return false\n    return a.source === b.source && a.flags === b.flags\n  }\n  // Symmetric check: if b is RegExp but a is not, they're not equal\n  if (b instanceof RegExp) return false\n\n  // Handle Map objects - only if both are Maps\n  if (a instanceof Map) {\n    if (!(b instanceof Map)) return false\n    if (a.size !== b.size) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    const entries = Array.from(a.entries())\n    const result = entries.every(([key, val]) => {\n      return b.has(key) && deepEqualsInternal(val, b.get(key), visited)\n    })\n\n    visited.delete(a)\n    return result\n  }\n  // Symmetric check: if b is Map but a is not, they're not equal\n  if (b instanceof Map) return false\n\n  // Handle Set objects - only if both are Sets\n  if (a instanceof Set) {\n    if (!(b instanceof Set)) return false\n    if (a.size !== b.size) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    // Convert to arrays for comparison\n    const aValues = Array.from(a)\n    const bValues = Array.from(b)\n\n    // Simple comparison for primitive values\n    if (aValues.every((val) => typeof val !== `object`)) {\n      visited.delete(a)\n      return aValues.every((val) => b.has(val))\n    }\n\n    // For objects in sets, we need to do a more complex comparison\n    // This is a simplified approach and may not work for all cases\n    const result = aValues.length === bValues.length\n    visited.delete(a)\n    return result\n  }\n  // Symmetric check: if b is Set but a is not, they're not equal\n  if (b instanceof Set) return false\n\n  // Handle TypedArrays\n  if (\n    ArrayBuffer.isView(a) &&\n    ArrayBuffer.isView(b) &&\n    !(a instanceof DataView) &&\n    !(b instanceof DataView)\n  ) {\n    const typedA = a as unknown as TypedArray\n    const typedB = b as unknown as TypedArray\n    if (typedA.length !== typedB.length) return false\n\n    for (let i = 0; i < typedA.length; i++) {\n      if (typedA[i] !== typedB[i]) return false\n    }\n\n    return true\n  }\n  // Symmetric check: if b is TypedArray but a is not, they're not equal\n  if (\n    ArrayBuffer.isView(b) &&\n    !(b instanceof DataView) &&\n    !ArrayBuffer.isView(a)\n  ) {\n    return false\n  }\n\n  // Handle Temporal objects\n  // Check if both are Temporal objects of the same type\n  if (isTemporal(a) && isTemporal(b)) {\n    const aTag = getStringTag(a)\n    const bTag = getStringTag(b)\n\n    // If they're different Temporal types, they're not equal\n    if (aTag !== bTag) return false\n\n    // Use Temporal's built-in equals method if available\n    if (typeof a.equals === `function`) {\n      return a.equals(b)\n    }\n\n    // Fallback to toString comparison for other types\n    return a.toString() === b.toString()\n  }\n  // Symmetric check: if b is Temporal but a is not, they're not equal\n  if (isTemporal(b)) return false\n\n  // Handle arrays\n  if (Array.isArray(a)) {\n    if (!Array.isArray(b) || a.length !== b.length) return false\n\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    const result = a.every((item, index) =>\n      deepEqualsInternal(item, b[index], visited),\n    )\n    visited.delete(a)\n    return result\n  }\n  // Symmetric check: if b is array but a is not, they're not equal\n  if (Array.isArray(b)) return false\n\n  // Handle objects\n  if (typeof a === `object`) {\n    // Check for circular references\n    if (visited.has(a)) {\n      return visited.get(a) === b\n    }\n    visited.set(a, b)\n\n    // Get all keys from both objects\n    const keysA = Object.keys(a)\n    const keysB = Object.keys(b)\n\n    // Check if they have the same number of keys\n    if (keysA.length !== keysB.length) {\n      visited.delete(a)\n      return false\n    }\n\n    // Check if all keys exist in both objects and their values are equal\n    const result = keysA.every(\n      (key) => key in b && deepEqualsInternal(a[key], b[key], visited),\n    )\n\n    visited.delete(a)\n    return result\n  }\n\n  // For primitives that aren't strictly equal\n  return false\n}\n\nconst temporalTypes = [\n  `Temporal.Duration`,\n  `Temporal.Instant`,\n  `Temporal.PlainDate`,\n  `Temporal.PlainDateTime`,\n  `Temporal.PlainMonthDay`,\n  `Temporal.PlainTime`,\n  `Temporal.PlainYearMonth`,\n  `Temporal.ZonedDateTime`,\n]\n\nfunction getStringTag(a: any): any {\n  return a[Symbol.toStringTag]\n}\n\n/** Checks if the value is a Temporal object by checking for the Temporal brand */\nexport function isTemporal(a: any): boolean {\n  const tag = getStringTag(a)\n  return typeof tag === `string` && temporalTypes.includes(tag)\n}\n\nexport const DEFAULT_COMPARE_OPTIONS: CompareOptions = {\n  direction: `asc`,\n  nulls: `first`,\n  stringSort: `locale`,\n}\n"],"names":[],"mappings":"AA4BO,SAAS,WAAW,GAAQ,GAAiB;AAClD,SAAO,mBAAmB,GAAG,GAAG,oBAAI,KAAK;AAC3C;AAKA,SAAS,mBACP,GACA,GACA,SACS;AAET,MAAI,MAAM,EAAG,QAAO;AAGpB,MAAI,KAAK,QAAQ,KAAK,KAAM,QAAO;AAGnC,MAAI,OAAO,MAAM,OAAO,EAAG,QAAO;AAGlC,MAAI,aAAa,MAAM;AACrB,QAAI,EAAE,aAAa,MAAO,QAAO;AACjC,WAAO,EAAE,cAAc,EAAE,QAAA;AAAA,EAC3B;AAEA,MAAI,aAAa,KAAM,QAAO;AAG9B,MAAI,aAAa,QAAQ;AACvB,QAAI,EAAE,aAAa,QAAS,QAAO;AACnC,WAAO,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE;AAAA,EAChD;AAEA,MAAI,aAAa,OAAQ,QAAO;AAGhC,MAAI,aAAa,KAAK;AACpB,QAAI,EAAE,aAAa,KAAM,QAAO;AAChC,QAAI,EAAE,SAAS,EAAE,KAAM,QAAO;AAG9B,QAAI,QAAQ,IAAI,CAAC,GAAG;AAClB,aAAO,QAAQ,IAAI,CAAC,MAAM;AAAA,IAC5B;AACA,YAAQ,IAAI,GAAG,CAAC;AAEhB,UAAM,UAAU,MAAM,KAAK,EAAE,SAAS;AACtC,UAAM,SAAS,QAAQ,MAAM,CAAC,CAAC,KAAK,GAAG,MAAM;AAC3C,aAAO,EAAE,IAAI,GAAG,KAAK,mBAAmB,KAAK,EAAE,IAAI,GAAG,GAAG,OAAO;AAAA,IAClE,CAAC;AAED,YAAQ,OAAO,CAAC;AAChB,WAAO;AAAA,EACT;AAEA,MAAI,aAAa,IAAK,QAAO;AAG7B,MAAI,aAAa,KAAK;AACpB,QAAI,EAAE,aAAa,KAAM,QAAO;AAChC,QAAI,EAAE,SAAS,EAAE,KAAM,QAAO;AAG9B,QAAI,QAAQ,IAAI,CAAC,GAAG;AAClB,aAAO,QAAQ,IAAI,CAAC,MAAM;AAAA,IAC5B;AACA,YAAQ,IAAI,GAAG,CAAC;AAGhB,UAAM,UAAU,MAAM,KAAK,CAAC;AAC5B,UAAM,UAAU,MAAM,KAAK,CAAC;AAG5B,QAAI,QAAQ,MAAM,CAAC,QAAQ,OAAO,QAAQ,QAAQ,GAAG;AACnD,cAAQ,OAAO,CAAC;AAChB,aAAO,QAAQ,MAAM,CAAC,QAAQ,EAAE,IAAI,GAAG,CAAC;AAAA,IAC1C;AAIA,UAAM,SAAS,QAAQ,WAAW,QAAQ;AAC1C,YAAQ,OAAO,CAAC;AAChB,WAAO;AAAA,EACT;AAEA,MAAI,aAAa,IAAK,QAAO;AAG7B,MACE,YAAY,OAAO,CAAC,KACpB,YAAY,OAAO,CAAC,KACpB,EAAE,aAAa,aACf,EAAE,aAAa,WACf;AACA,UAAM,SAAS;AACf,UAAM,SAAS;AACf,QAAI,OAAO,WAAW,OAAO,OAAQ,QAAO;AAE5C,aAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;AACtC,UAAI,OAAO,CAAC,MAAM,OAAO,CAAC,EAAG,QAAO;AAAA,IACtC;AAEA,WAAO;AAAA,EACT;AAEA,MACE,YAAY,OAAO,CAAC,KACpB,EAAE,aAAa,aACf,CAAC,YAAY,OAAO,CAAC,GACrB;AACA,WAAO;AAAA,EACT;AAIA,MAAI,WAAW,CAAC,KAAK,WAAW,CAAC,GAAG;AAClC,UAAM,OAAO,aAAa,CAAC;AAC3B,UAAM,OAAO,aAAa,CAAC;AAG3B,QAAI,SAAS,KAAM,QAAO;AAG1B,QAAI,OAAO,EAAE,WAAW,YAAY;AAClC,aAAO,EAAE,OAAO,CAAC;AAAA,IACnB;AAGA,WAAO,EAAE,eAAe,EAAE,SAAA;AAAA,EAC5B;AAEA,MAAI,WAAW,CAAC,EAAG,QAAO;AAG1B,MAAI,MAAM,QAAQ,CAAC,GAAG;AACpB,QAAI,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,OAAQ,QAAO;AAGvD,QAAI,QAAQ,IAAI,CAAC,GAAG;AAClB,aAAO,QAAQ,IAAI,CAAC,MAAM;AAAA,IAC5B;AACA,YAAQ,IAAI,GAAG,CAAC;AAEhB,UAAM,SAAS,EAAE;AAAA,MAAM,CAAC,MAAM,UAC5B,mBAAmB,MAAM,EAAE,KAAK,GAAG,OAAO;AAAA,IAAA;AAE5C,YAAQ,OAAO,CAAC;AAChB,WAAO;AAAA,EACT;AAEA,MAAI,MAAM,QAAQ,CAAC,EAAG,QAAO;AAG7B,MAAI,OAAO,MAAM,UAAU;AAEzB,QAAI,QAAQ,IAAI,CAAC,GAAG;AAClB,aAAO,QAAQ,IAAI,CAAC,MAAM;AAAA,IAC5B;AACA,YAAQ,IAAI,GAAG,CAAC;AAGhB,UAAM,QAAQ,OAAO,KAAK,CAAC;AAC3B,UAAM,QAAQ,OAAO,KAAK,CAAC;AAG3B,QAAI,MAAM,WAAW,MAAM,QAAQ;AACjC,cAAQ,OAAO,CAAC;AAChB,aAAO;AAAA,IACT;AAGA,UAAM,SAAS,MAAM;AAAA,MACnB,CAAC,QAAQ,OAAO,KAAK,mBAAmB,EAAE,GAAG,GAAG,EAAE,GAAG,GAAG,OAAO;AAAA,IAAA;AAGjE,YAAQ,OAAO,CAAC;AAChB,WAAO;AAAA,EACT;AAGA,SAAO;AACT;AAEA,MAAM,gBAAgB;AAAA,EACpB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,SAAS,aAAa,GAAa;AACjC,SAAO,EAAE,OAAO,WAAW;AAC7B;AAGO,SAAS,WAAW,GAAiB;AAC1C,QAAM,MAAM,aAAa,CAAC;AAC1B,SAAO,OAAO,QAAQ,YAAY,cAAc,SAAS,GAAG;AAC9D;AAEO,MAAM,0BAA0C;AAAA,EACrD,WAAW;AAAA,EACX,OAAO;AAAA,EACP,YAAY;AACd;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/db",
-  "version": "0.5.16",
+  "version": "0.5.18",
   "description": "A reactive client store for building super fast apps on sync",
   "author": "Kyle Mathews",
   "license": "MIT",
@@ -37,8 +37,8 @@
     "src"
   ],
   "dependencies": {
-    "@standard-schema/spec": "^1.0.0",
-    "@tanstack/pacer-lite": "^0.1.1",
+    "@standard-schema/spec": "^1.1.0",
+    "@tanstack/pacer-lite": "^0.2.0",
     "@tanstack/db-ivm": "0.1.14"
   },
   "peerDependencies": {
@@ -47,7 +47,7 @@
   "devDependencies": {
     "@tanstack/config": "^0.22.2",
     "@vitest/coverage-istanbul": "^3.2.4",
-    "arktype": "^2.1.28",
+    "arktype": "^2.1.29",
     "mitt": "^3.0.1",
     "superjson": "^2.2.6",
     "temporal-polyfill": "^0.3.0"

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,19 +98,42 @@ 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)
       },
     })
 
+    // Register status listener BEFORE requesting snapshot to avoid race condition.
+    // This ensures the listener catches all status transitions, even if the
+    // loadSubset promise resolves synchronously or very quickly.
+    if (options.onStatusChange) {
+      subscription.on(`status:change`, options.onStatusChange)
+    }
+
     if (options.includeInitialState) {
       subscription.requestSnapshot({ trackLoadSubsetPromise: false })
     } else if (options.includeInitialState === false) {

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/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/query/live/collection-config-builder.ts

@@ -566,6 +566,21 @@ export class CollectionConfigBuilder<
       },
     )
 
+    // Listen for loadingSubset changes on the live query collection BEFORE subscribing.
+    // This ensures we don't miss the event if subset loading completes synchronously.
+    // When isLoadingSubset becomes false, we may need to mark the collection as ready
+    // (if all source collections are already ready but we were waiting for subset load to complete)
+    const loadingSubsetUnsubscribe = config.collection.on(
+      `loadingSubset:change`,
+      (event) => {
+        if (!event.isLoadingSubset) {
+          // Subset loading finished, check if we can now mark ready
+          this.updateLiveQueryStatus(config)
+        }
+      },
+    )
+    syncState.unsubscribeCallbacks.add(loadingSubsetUnsubscribe)
+
     const loadSubsetDataCallbacks = this.subscribeToAllCollections(
       config,
       fullSyncState,
@@ -793,8 +808,14 @@ export class CollectionConfigBuilder<
       return
     }
 
-    // Mark ready when all source collections are ready
-    if (this.allCollectionsReady()) {
+    // Mark ready when all source collections are ready AND
+    // the live query collection is not loading subset data.
+    // This prevents marking the live query ready before its data is loaded
+    // (fixes issue where useLiveQuery returns isReady=true with empty data)
+    if (
+      this.allCollectionsReady() &&
+      !this.liveQueryCollection?.isLoadingSubset
+    ) {
       markReady()
     }
   }

package/src/query/live/collection-subscriber.ts

@@ -5,7 +5,10 @@ import {
 } from '../compiler/expressions.js'
 import type { MultiSetArray, RootStreamBuilder } from '@tanstack/db-ivm'
 import type { Collection } from '../../collection/index.js'
-import type { ChangeMessage } from '../../types.js'
+import type {
+  ChangeMessage,
+  SubscriptionStatusChangeEvent,
+} from '../../types.js'
 import type { Context, GetResult } from '../builder/types.js'
 import type { BasicExpression } from '../ir.js'
 import type { OrderByOptimizationInfo } from '../compiler/order-by.js'
@@ -53,26 +56,10 @@ export class CollectionSubscriber<
   }
 
   private subscribeToChanges(whereExpression?: BasicExpression<boolean>) {
-    let subscription: CollectionSubscription
     const orderByInfo = this.getOrderByInfo()
-    if (orderByInfo) {
-      subscription = this.subscribeToOrderedChanges(
-        whereExpression,
-        orderByInfo,
-      )
-    } else {
-      // If the source alias is lazy then we should not include the initial state
-      const includeInitialState = !this.collectionConfigBuilder.isLazyAlias(
-        this.alias,
-      )
-
-      subscription = this.subscribeToMatchingChanges(
-        whereExpression,
-        includeInitialState,
-      )
-    }
 
-    const trackLoadPromise = () => {
+    // Track load promises using subscription from the event (avoids circular dependency)
+    const trackLoadPromise = (subscription: CollectionSubscription) => {
       // Guard against duplicate transitions
       if (!this.subscriptionLoadingPromises.has(subscription)) {
         let resolve: () => void
@@ -89,16 +76,12 @@ export class CollectionSubscriber<
       }
     }
 
-    // It can be that we are not yet subscribed when the first `loadSubset` call happens (i.e. the initial query).
-    // So we also check the status here and if it's `loadingSubset` then we track the load promise
-    if (subscription.status === `loadingSubset`) {
-      trackLoadPromise()
-    }
-
-    // Subscribe to subscription status changes to propagate loading state
-    const statusUnsubscribe = subscription.on(`status:change`, (event) => {
+    // Status change handler - passed to subscribeChanges so it's registered
+    // BEFORE any snapshot is requested, preventing race conditions
+    const onStatusChange = (event: SubscriptionStatusChangeEvent) => {
+      const subscription = event.subscription as CollectionSubscription
       if (event.status === `loadingSubset`) {
-        trackLoadPromise()
+        trackLoadPromise(subscription)
       } else {
         // status is 'ready'
         const deferred = this.subscriptionLoadingPromises.get(subscription)
@@ -108,7 +91,34 @@ export class CollectionSubscriber<
           deferred.resolve()
         }
       }
-    })
+    }
+
+    // Create subscription with onStatusChange - listener is registered before any async work
+    let subscription: CollectionSubscription
+    if (orderByInfo) {
+      subscription = this.subscribeToOrderedChanges(
+        whereExpression,
+        orderByInfo,
+        onStatusChange,
+      )
+    } else {
+      // If the source alias is lazy then we should not include the initial state
+      const includeInitialState = !this.collectionConfigBuilder.isLazyAlias(
+        this.alias,
+      )
+
+      subscription = this.subscribeToMatchingChanges(
+        whereExpression,
+        includeInitialState,
+        onStatusChange,
+      )
+    }
+
+    // Check current status after subscribing - if status is 'loadingSubset', track it.
+    // The onStatusChange listener will catch the transition to 'ready'.
+    if (subscription.status === `loadingSubset`) {
+      trackLoadPromise(subscription)
+    }
 
     const unsubscribe = () => {
       // If subscription has a pending promise, resolve it before unsubscribing
@@ -119,7 +129,6 @@ export class CollectionSubscriber<
         deferred.resolve()
       }
 
-      statusUnsubscribe()
       subscription.unsubscribe()
     }
     // currentSyncState is always defined when subscribe() is called
@@ -179,22 +188,22 @@ export class CollectionSubscriber<
 
   private subscribeToMatchingChanges(
     whereExpression: BasicExpression<boolean> | undefined,
-    includeInitialState: boolean = false,
-  ) {
+    includeInitialState: boolean,
+    onStatusChange: (event: SubscriptionStatusChangeEvent) => void,
+  ): CollectionSubscription {
     const sendChanges = (
       changes: Array<ChangeMessage<any, string | number>>,
     ) => {
       this.sendChangesToPipeline(changes)
     }
 
-    // Only pass includeInitialState when true. When it's false, we leave it
-    // undefined so that user subscriptions with explicit `includeInitialState: false`
-    // can be distinguished from internal lazy-loading subscriptions.
-    // If we pass `false`, changes.ts would call markAllStateAsSeen() which
-    // disables filtering - but internal subscriptions still need filtering.
+    // Create subscription with onStatusChange - listener is registered before snapshot
+    // Note: For non-ordered queries (no limit/offset), we use trackLoadSubsetPromise: false
+    // which is the default behavior in subscribeChanges
     const subscription = this.collection.subscribeChanges(sendChanges, {
       ...(includeInitialState && { includeInitialState }),
       whereExpression,
+      onStatusChange,
     })
 
     return subscription
@@ -203,22 +212,31 @@ export class CollectionSubscriber<
   private subscribeToOrderedChanges(
     whereExpression: BasicExpression<boolean> | undefined,
     orderByInfo: OrderByOptimizationInfo,
-  ) {
+    onStatusChange: (event: SubscriptionStatusChangeEvent) => void,
+  ): CollectionSubscription {
     const { orderBy, offset, limit, index } = orderByInfo
 
+    // Use a holder to forward-reference subscription in the callback
+    const subscriptionHolder: { current?: CollectionSubscription } = {}
+
     const sendChangesInRange = (
       changes: Iterable<ChangeMessage<any, string | number>>,
     ) => {
       // Split live updates into a delete of the old value and an insert of the new value
       const splittedChanges = splitUpdates(changes)
-      this.sendChangesToPipelineWithTracking(splittedChanges, subscription)
+      this.sendChangesToPipelineWithTracking(
+        splittedChanges,
+        subscriptionHolder.current!,
+      )
     }
 
-    // Subscribe to changes and only send changes that are smaller than the biggest value we've sent so far
-    // values that are bigger don't need to be sent because they can't affect the topK
+    // Subscribe to changes with onStatusChange - listener is registered before any snapshot
+    // values bigger than what we've sent don't need to be sent because they can't affect the topK
     const subscription = this.collection.subscribeChanges(sendChangesInRange, {
       whereExpression,
+      onStatusChange,
     })
+    subscriptionHolder.current = subscription
 
     // Listen for truncate events to reset cursor tracking state and sentToD2Keys
     // This ensures that after a must-refetch/truncate, we don't use stale cursor data
@@ -236,6 +254,7 @@ export class CollectionSubscriber<
     // Normalize the orderBy clauses such that the references are relative to the collection
     const normalizedOrderBy = normalizeOrderByPaths(orderBy, this.alias)
 
+    // Trigger the snapshot request - onStatusChange listener is already registered
     if (index) {
       // We have an index on the first orderBy column - use lazy loading optimization
       // This works for both single-column and multi-column orderBy:

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,39 @@ 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>
+  /**
+   * Listener for subscription status changes.
+   * Registered BEFORE any snapshot is requested, ensuring no status transitions are missed.
+   * @internal
+   */
+  onStatusChange?: (event: SubscriptionStatusChangeEvent) => void
 }
 
-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`) {