@tanstack/db 0.5.33 → 0.6.0

package/dist/esm/utils.js

@@ -61,8 +61,8 @@ function deepEqualsInternal(a, b, visited) {
     return false;
   }
   if (isTemporal(a) && isTemporal(b)) {
-    const aTag = getStringTag(a);
-    const bTag = getStringTag(b);
+    const aTag = a[Symbol.toStringTag];
+    const bTag = b[Symbol.toStringTag];
     if (aTag !== bTag) return false;
     if (typeof a.equals === `function`) {
       return a.equals(b);
@@ -102,7 +102,7 @@ function deepEqualsInternal(a, b, visited) {
   }
   return false;
 }
-const temporalTypes = [
+const temporalTypes = /* @__PURE__ */ new Set([
   `Temporal.Duration`,
   `Temporal.Instant`,
   `Temporal.PlainDate`,
@@ -111,13 +111,11 @@ const temporalTypes = [
   `Temporal.PlainTime`,
   `Temporal.PlainYearMonth`,
   `Temporal.ZonedDateTime`
-];
-function getStringTag(a) {
-  return a[Symbol.toStringTag];
-}
+]);
 function isTemporal(a) {
-  const tag = getStringTag(a);
-  return typeof tag === `string` && temporalTypes.includes(tag);
+  if (a == null || typeof a !== `object`) return false;
+  const tag = a[Symbol.toStringTag];
+  return typeof tag === `string` && temporalTypes.has(tag);
 }
 const DEFAULT_COMPARE_OPTIONS = {
   direction: `asc`,

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  // 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;"}
+{"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 = a[Symbol.toStringTag]\n    const bTag = b[Symbol.toStringTag]\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 = new Set([\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\nexport interface TemporalLike {\n  [Symbol.toStringTag]: string\n  toString: () => string\n  equals?: (other: unknown) => boolean\n}\n\n/** Checks if the value is a Temporal object by checking for the Temporal brand */\nexport function isTemporal(a: unknown): a is TemporalLike {\n  if (a == null || typeof a !== `object`) return false\n  const tag = (a as Record<symbol, unknown>)[Symbol.toStringTag]\n  return typeof tag === `string` && temporalTypes.has(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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"}

package/dist/esm/virtual-props.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Virtual Properties for TanStack DB
+ *
+ * Virtual properties are computed, read-only properties that provide metadata about rows
+ * (sync status, source, selection state) without being part of the persisted data model.
+ *
+ * Virtual properties are prefixed with `$` to distinguish them from user data fields.
+ * User schemas should not include `$`-prefixed fields as they are reserved.
+ */
+/**
+ * Origin of the last confirmed change to a row, from the current client's perspective.
+ *
+ * - `'local'`: The change originated from this client (e.g., a mutation made here)
+ * - `'remote'`: The change was received via sync from another client/server
+ *
+ * Note: This reflects the client's perspective, not the original creator.
+ * User A creates order → $origin = 'local' on User A's client
+ * Order syncs to server
+ * User B receives order → $origin = 'remote' on User B's client
+ */
+export type VirtualOrigin = 'local' | 'remote';
+/**
+ * Virtual properties available on every row in TanStack DB collections.
+ *
+ * These properties are:
+ * - Computed (not stored in the data model)
+ * - Read-only (cannot be mutated directly)
+ * - Available in queries (WHERE, ORDER BY, SELECT)
+ * - Included when spreading rows (`...user`)
+ *
+ * @template TKey - The type of the row's key (string or number)
+ *
+ * @example
+ * ```typescript
+ * // Accessing virtual properties on a row
+ * const user = collection.get('user-1')
+ * if (user.$synced) {
+ *   console.log('Confirmed by backend')
+ * }
+ * if (user.$origin === 'local') {
+ *   console.log('Created/modified locally')
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using virtual properties in queries
+ * const confirmedOrders = createLiveQueryCollection({
+ *   query: (q) => q
+ *     .from({ order: orders })
+ *     .where(({ order }) => eq(order.$synced, true))
+ * })
+ * ```
+ */
+export interface VirtualRowProps<TKey extends string | number = string | number> {
+    /**
+     * Whether this row reflects confirmed state from the backend.
+     *
+     * - `true`: Row is confirmed by the backend (no pending optimistic mutations)
+     * - `false`: Row has pending optimistic mutations that haven't been confirmed
+     *
+     * For local-only collections (no sync), this is always `true`.
+     * For live query collections, this is passed through from the source collection.
+     */
+    readonly $synced: boolean;
+    /**
+     * Origin of the last confirmed change to this row, from the current client's perspective.
+     *
+     * - `'local'`: The change originated from this client
+     * - `'remote'`: The change was received via sync
+     *
+     * For local-only collections, this is always `'local'`.
+     * For live query collections, this is passed through from the source collection.
+     */
+    readonly $origin: VirtualOrigin;
+    /**
+     * The row's key (primary identifier).
+     *
+     * This is the same value returned by `collection.config.getKey(row)`.
+     * Useful when you need the key in projections or computations.
+     */
+    readonly $key: TKey;
+    /**
+     * The ID of the source collection this row originated from.
+     *
+     * In joins, this can help identify which collection each row came from.
+     * For live query collections, this is the ID of the upstream collection.
+     */
+    readonly $collectionId: string;
+}
+/**
+ * Adds virtual properties to a row type.
+ *
+ * @template T - The base row type
+ * @template TKey - The type of the row's key
+ *
+ * @example
+ * ```typescript
+ * type User = { id: string; name: string }
+ * type UserWithVirtual = WithVirtualProps<User, string>
+ * // { id: string; name: string; $synced: boolean; $origin: 'local' | 'remote'; $key: string; $collectionId: string }
+ * ```
+ */
+export type WithVirtualProps<T extends object, TKey extends string | number = string | number> = T & VirtualRowProps<TKey>;
+/**
+ * Extracts the base type from a type that may have virtual properties.
+ * Useful when you need to work with the raw data without virtual properties.
+ *
+ * @template T - The type that may include virtual properties
+ *
+ * @example
+ * ```typescript
+ * type UserWithVirtual = { id: string; name: string; $synced: boolean; $origin: 'local' | 'remote' }
+ * type User = WithoutVirtualProps<UserWithVirtual>
+ * // { id: string; name: string }
+ * ```
+ */
+export type WithoutVirtualProps<T> = Omit<T, keyof VirtualRowProps>;
+/**
+ * Checks if a value has virtual properties attached.
+ *
+ * @param value - The value to check
+ * @returns true if the value has virtual properties
+ *
+ * @example
+ * ```typescript
+ * if (hasVirtualProps(row)) {
+ *   console.log('Synced:', row.$synced)
+ * }
+ * ```
+ */
+export declare function hasVirtualProps(value: unknown): value is VirtualRowProps<string | number>;
+/**
+ * Creates virtual properties for a row in a source collection.
+ *
+ * This is the internal function used by collections to add virtual properties
+ * to rows when emitting change messages.
+ *
+ * @param key - The row's key
+ * @param collectionId - The collection's ID
+ * @param isSynced - Whether the row is synced (not optimistic)
+ * @param origin - Whether the change was local or remote
+ * @returns Virtual properties object to merge with the row
+ *
+ * @internal
+ */
+export declare function createVirtualProps<TKey extends string | number>(key: TKey, collectionId: string, isSynced: boolean, origin: VirtualOrigin): VirtualRowProps<TKey>;
+/**
+ * Enriches a row with virtual properties using the "add-if-missing" pattern.
+ *
+ * If the row already has virtual properties (from an upstream collection),
+ * they are preserved. If not, new virtual properties are computed and added.
+ *
+ * This is the key function that enables pass-through semantics for nested
+ * live query collections.
+ *
+ * @param row - The row to enrich
+ * @param key - The row's key
+ * @param collectionId - The collection's ID
+ * @param computeSynced - Function to compute $synced if missing
+ * @param computeOrigin - Function to compute $origin if missing
+ * @returns The row with virtual properties (possibly the same object if already present)
+ *
+ * @internal
+ */
+export declare function enrichRowWithVirtualProps<T extends object, TKey extends string | number>(row: T, key: TKey, collectionId: string, computeSynced: () => boolean, computeOrigin: () => VirtualOrigin): WithVirtualProps<T, TKey>;
+/**
+ * Computes aggregate virtual properties for a group of rows.
+ *
+ * For aggregates:
+ * - `$synced`: true if ALL rows in the group are synced; false if ANY row is optimistic
+ * - `$origin`: 'local' if ANY row in the group is local; otherwise 'remote'
+ *
+ * @param rows - The rows in the group
+ * @param groupKey - The group key
+ * @param collectionId - The collection ID
+ * @returns Virtual properties for the aggregate row
+ *
+ * @internal
+ */
+export declare function computeAggregateVirtualProps<TKey extends string | number>(rows: Array<Partial<VirtualRowProps<string | number>>>, groupKey: TKey, collectionId: string): VirtualRowProps<TKey>;
+/**
+ * List of virtual property names for iteration and checking.
+ * @internal
+ */
+export declare const VIRTUAL_PROP_NAMES: readonly ["$synced", "$origin", "$key", "$collectionId"];
+/**
+ * Checks if a property name is a virtual property.
+ * @internal
+ */
+export declare function isVirtualPropName(name: string): boolean;
+/**
+ * Checks whether a property path references a virtual property.
+ * @internal
+ */
+export declare function hasVirtualPropPath(path: Array<string>): boolean;

package/dist/esm/virtual-props.js

@@ -0,0 +1,33 @@
+function hasVirtualProps(value) {
+  return typeof value === "object" && value !== null && VIRTUAL_PROP_NAMES.every((name) => name in value);
+}
+function enrichRowWithVirtualProps(row, key, collectionId, computeSynced, computeOrigin) {
+  const existingRow = row;
+  return {
+    ...row,
+    $synced: existingRow.$synced ?? computeSynced(),
+    $origin: existingRow.$origin ?? computeOrigin(),
+    $key: existingRow.$key ?? key,
+    $collectionId: existingRow.$collectionId ?? collectionId
+  };
+}
+const VIRTUAL_PROP_NAMES = [
+  "$synced",
+  "$origin",
+  "$key",
+  "$collectionId"
+];
+function isVirtualPropName(name) {
+  return VIRTUAL_PROP_NAMES.includes(name);
+}
+function hasVirtualPropPath(path) {
+  return path.some((segment) => isVirtualPropName(segment));
+}
+export {
+  VIRTUAL_PROP_NAMES,
+  enrichRowWithVirtualProps,
+  hasVirtualPropPath,
+  hasVirtualProps,
+  isVirtualPropName
+};
+//# sourceMappingURL=virtual-props.js.map

package/dist/esm/virtual-props.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-props.js","sources":["../../src/virtual-props.ts"],"sourcesContent":["/**\n * Virtual Properties for TanStack DB\n *\n * Virtual properties are computed, read-only properties that provide metadata about rows\n * (sync status, source, selection state) without being part of the persisted data model.\n *\n * Virtual properties are prefixed with `$` to distinguish them from user data fields.\n * User schemas should not include `$`-prefixed fields as they are reserved.\n */\n\n/**\n * Origin of the last confirmed change to a row, from the current client's perspective.\n *\n * - `'local'`: The change originated from this client (e.g., a mutation made here)\n * - `'remote'`: The change was received via sync from another client/server\n *\n * Note: This reflects the client's perspective, not the original creator.\n * User A creates order → $origin = 'local' on User A's client\n * Order syncs to server\n * User B receives order → $origin = 'remote' on User B's client\n */\nexport type VirtualOrigin = 'local' | 'remote'\n\n/**\n * Virtual properties available on every row in TanStack DB collections.\n *\n * These properties are:\n * - Computed (not stored in the data model)\n * - Read-only (cannot be mutated directly)\n * - Available in queries (WHERE, ORDER BY, SELECT)\n * - Included when spreading rows (`...user`)\n *\n * @template TKey - The type of the row's key (string or number)\n *\n * @example\n * ```typescript\n * // Accessing virtual properties on a row\n * const user = collection.get('user-1')\n * if (user.$synced) {\n *   console.log('Confirmed by backend')\n * }\n * if (user.$origin === 'local') {\n *   console.log('Created/modified locally')\n * }\n * ```\n *\n * @example\n * ```typescript\n * // Using virtual properties in queries\n * const confirmedOrders = createLiveQueryCollection({\n *   query: (q) => q\n *     .from({ order: orders })\n *     .where(({ order }) => eq(order.$synced, true))\n * })\n * ```\n */\nexport interface VirtualRowProps<\n  TKey extends string | number = string | number,\n> {\n  /**\n   * Whether this row reflects confirmed state from the backend.\n   *\n   * - `true`: Row is confirmed by the backend (no pending optimistic mutations)\n   * - `false`: Row has pending optimistic mutations that haven't been confirmed\n   *\n   * For local-only collections (no sync), this is always `true`.\n   * For live query collections, this is passed through from the source collection.\n   */\n  readonly $synced: boolean\n\n  /**\n   * Origin of the last confirmed change to this row, from the current client's perspective.\n   *\n   * - `'local'`: The change originated from this client\n   * - `'remote'`: The change was received via sync\n   *\n   * For local-only collections, this is always `'local'`.\n   * For live query collections, this is passed through from the source collection.\n   */\n  readonly $origin: VirtualOrigin\n\n  /**\n   * The row's key (primary identifier).\n   *\n   * This is the same value returned by `collection.config.getKey(row)`.\n   * Useful when you need the key in projections or computations.\n   */\n  readonly $key: TKey\n\n  /**\n   * The ID of the source collection this row originated from.\n   *\n   * In joins, this can help identify which collection each row came from.\n   * For live query collections, this is the ID of the upstream collection.\n   */\n  readonly $collectionId: string\n}\n\n/**\n * Adds virtual properties to a row type.\n *\n * @template T - The base row type\n * @template TKey - The type of the row's key\n *\n * @example\n * ```typescript\n * type User = { id: string; name: string }\n * type UserWithVirtual = WithVirtualProps<User, string>\n * // { id: string; name: string; $synced: boolean; $origin: 'local' | 'remote'; $key: string; $collectionId: string }\n * ```\n */\nexport type WithVirtualProps<\n  T extends object,\n  TKey extends string | number = string | number,\n> = T & VirtualRowProps<TKey>\n\n/**\n * Extracts the base type from a type that may have virtual properties.\n * Useful when you need to work with the raw data without virtual properties.\n *\n * @template T - The type that may include virtual properties\n *\n * @example\n * ```typescript\n * type UserWithVirtual = { id: string; name: string; $synced: boolean; $origin: 'local' | 'remote' }\n * type User = WithoutVirtualProps<UserWithVirtual>\n * // { id: string; name: string }\n * ```\n */\nexport type WithoutVirtualProps<T> = Omit<T, keyof VirtualRowProps>\n\n/**\n * Checks if a value has virtual properties attached.\n *\n * @param value - The value to check\n * @returns true if the value has virtual properties\n *\n * @example\n * ```typescript\n * if (hasVirtualProps(row)) {\n *   console.log('Synced:', row.$synced)\n * }\n * ```\n */\nexport function hasVirtualProps(\n  value: unknown,\n): value is VirtualRowProps<string | number> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    VIRTUAL_PROP_NAMES.every((name) => name in value)\n  )\n}\n\n/**\n * Creates virtual properties for a row in a source collection.\n *\n * This is the internal function used by collections to add virtual properties\n * to rows when emitting change messages.\n *\n * @param key - The row's key\n * @param collectionId - The collection's ID\n * @param isSynced - Whether the row is synced (not optimistic)\n * @param origin - Whether the change was local or remote\n * @returns Virtual properties object to merge with the row\n *\n * @internal\n */\nexport function createVirtualProps<TKey extends string | number>(\n  key: TKey,\n  collectionId: string,\n  isSynced: boolean,\n  origin: VirtualOrigin,\n): VirtualRowProps<TKey> {\n  return {\n    $synced: isSynced,\n    $origin: origin,\n    $key: key,\n    $collectionId: collectionId,\n  }\n}\n\n/**\n * Enriches a row with virtual properties using the \"add-if-missing\" pattern.\n *\n * If the row already has virtual properties (from an upstream collection),\n * they are preserved. If not, new virtual properties are computed and added.\n *\n * This is the key function that enables pass-through semantics for nested\n * live query collections.\n *\n * @param row - The row to enrich\n * @param key - The row's key\n * @param collectionId - The collection's ID\n * @param computeSynced - Function to compute $synced if missing\n * @param computeOrigin - Function to compute $origin if missing\n * @returns The row with virtual properties (possibly the same object if already present)\n *\n * @internal\n */\nexport function enrichRowWithVirtualProps<\n  T extends object,\n  TKey extends string | number,\n>(\n  row: T,\n  key: TKey,\n  collectionId: string,\n  computeSynced: () => boolean,\n  computeOrigin: () => VirtualOrigin,\n): WithVirtualProps<T, TKey> {\n  // Use nullish coalescing to preserve existing virtual properties (pass-through)\n  // This is the \"add-if-missing\" pattern described in the RFC\n  const existingRow = row as Partial<VirtualRowProps<TKey>>\n\n  return {\n    ...row,\n    $synced: existingRow.$synced ?? computeSynced(),\n    $origin: existingRow.$origin ?? computeOrigin(),\n    $key: existingRow.$key ?? key,\n    $collectionId: existingRow.$collectionId ?? collectionId,\n  } as WithVirtualProps<T, TKey>\n}\n\n/**\n * Computes aggregate virtual properties for a group of rows.\n *\n * For aggregates:\n * - `$synced`: true if ALL rows in the group are synced; false if ANY row is optimistic\n * - `$origin`: 'local' if ANY row in the group is local; otherwise 'remote'\n *\n * @param rows - The rows in the group\n * @param groupKey - The group key\n * @param collectionId - The collection ID\n * @returns Virtual properties for the aggregate row\n *\n * @internal\n */\nexport function computeAggregateVirtualProps<TKey extends string | number>(\n  rows: Array<Partial<VirtualRowProps<string | number>>>,\n  groupKey: TKey,\n  collectionId: string,\n): VirtualRowProps<TKey> {\n  // $synced = true only if ALL rows are synced (false if ANY is optimistic)\n  const allSynced = rows.every((row) => row.$synced ?? true)\n\n  // $origin = 'local' if ANY row is local (consistent with \"local influence\" semantics)\n  const hasLocal = rows.some((row) => row.$origin === 'local')\n\n  return {\n    $synced: allSynced,\n    $origin: hasLocal ? 'local' : 'remote',\n    $key: groupKey,\n    $collectionId: collectionId,\n  }\n}\n\n/**\n * List of virtual property names for iteration and checking.\n * @internal\n */\nexport const VIRTUAL_PROP_NAMES = [\n  '$synced',\n  '$origin',\n  '$key',\n  '$collectionId',\n] as const\n\n/**\n * Checks if a property name is a virtual property.\n * @internal\n */\nexport function isVirtualPropName(name: string): boolean {\n  return VIRTUAL_PROP_NAMES.includes(name as any)\n}\n\n/**\n * Checks whether a property path references a virtual property.\n * @internal\n */\nexport function hasVirtualPropPath(path: Array<string>): boolean {\n  return path.some((segment) => isVirtualPropName(segment))\n}\n"],"names":[],"mappings":"AAgJO,SAAS,gBACd,OAC2C;AAC3C,SACE,OAAO,UAAU,YACjB,UAAU,QACV,mBAAmB,MAAM,CAAC,SAAS,QAAQ,KAAK;AAEpD;AAgDO,SAAS,0BAId,KACA,KACA,cACA,eACA,eAC2B;AAG3B,QAAM,cAAc;AAEpB,SAAO;AAAA,IACL,GAAG;AAAA,IACH,SAAS,YAAY,WAAW,cAAA;AAAA,IAChC,SAAS,YAAY,WAAW,cAAA;AAAA,IAChC,MAAM,YAAY,QAAQ;AAAA,IAC1B,eAAe,YAAY,iBAAiB;AAAA,EAAA;AAEhD;AAuCO,MAAM,qBAAqB;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAMO,SAAS,kBAAkB,MAAuB;AACvD,SAAO,mBAAmB,SAAS,IAAW;AAChD;AAMO,SAAS,mBAAmB,MAA8B;AAC/D,SAAO,KAAK,KAAK,CAAC,YAAY,kBAAkB,OAAO,CAAC;AAC1D;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/db",
-  "version": "0.5.33",
+  "version": "0.6.0",
   "description": "A reactive client store for building super fast apps on sync",
   "author": "Kyle Mathews",
   "license": "MIT",
@@ -40,7 +40,7 @@
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
     "@tanstack/pacer-lite": "^0.2.1",
-    "@tanstack/db-ivm": "0.1.17"
+    "@tanstack/db-ivm": "0.1.18"
   },
   "peerDependencies": {
     "typescript": ">=4.7"

package/skills/db-core/collection-setup/references/electric-adapter.md

@@ -78,7 +78,7 @@ onInsert: async ({ transaction }) => {
 
 ## Utility Methods (`collection.utils`)
 
-- `awaitTxId(txid, timeout?)` -- wait for txid in Electric stream; default timeout 30s
+- `awaitTxId(txid, timeout?)` -- wait for txid in Electric stream; default timeout 5s
 - `awaitMatch(matchFn, timeout?)` -- wait for message matching predicate; default timeout 3000ms
 
 ### Helper Exports

package/src/collection/change-events.ts

@@ -22,6 +22,7 @@ import type {
 import type { CollectionImpl } from './index.js'
 import type { SingleRowRefProxy } from '../query/builder/ref-proxy'
 import type { BasicExpression, OrderBy } from '../query/ir.js'
+import type { WithVirtualProps } from '../virtual-props.js'
 
 /**
  * Returns the current state of the collection as an array of changes
@@ -58,14 +59,14 @@ export function currentStateAsChanges<
   T extends object,
   TKey extends string | number,
 >(
-  collection: CollectionLike<T, TKey>,
+  collection: CollectionLike<WithVirtualProps<T, TKey>, TKey>,
   options: CurrentStateAsChangesOptions = {},
-): Array<ChangeMessage<T>> | void {
+): Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> | void {
   // Helper function to collect filtered results
   const collectFilteredResults = (
-    filterFn?: (value: T) => boolean,
-  ): Array<ChangeMessage<T>> => {
-    const result: Array<ChangeMessage<T>> = []
+    filterFn?: (value: WithVirtualProps<T, TKey>) => boolean,
+  ): Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> => {
+    const result: Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> = []
     for (const [key, value] of collection.entries()) {
       // If no filter function is provided, include all items
       if (filterFn?.(value) ?? true) {
@@ -106,7 +107,7 @@ export function currentStateAsChanges<
     }
 
     // Convert keys to change messages
-    const result: Array<ChangeMessage<T>> = []
+    const result: Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> = []
     for (const key of orderedKeys) {
       const value = collection.get(key)
       if (value !== undefined) {
@@ -138,7 +139,7 @@ export function currentStateAsChanges<
 
     if (optimizationResult.canOptimize) {
       // Use index optimization
-      const result: Array<ChangeMessage<T>> = []
+      const result: Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> = []
       for (const key of optimizationResult.matchingKeys) {
         const value = collection.get(key)
         if (value !== undefined) {
@@ -241,9 +242,12 @@ export function createFilterFunctionFromExpression<T extends object>(
  * @param options - The subscription options containing the where clause
  * @returns A filtered callback function
  */
-export function createFilteredCallback<T extends object>(
+export function createFilteredCallback<
+  T extends object,
+  TKey extends string | number = string | number,
+>(
   originalCallback: (changes: Array<ChangeMessage<T>>) => void,
-  options: SubscribeChangesOptions,
+  options: SubscribeChangesOptions<T, TKey>,
 ): (changes: Array<ChangeMessage<T>>) => void {
   const filterFn = createFilterFunctionFromExpression(options.whereExpression!)
 

package/src/collection/changes.ts

@@ -10,6 +10,8 @@ import type { CollectionLifecycleManager } from './lifecycle.js'
 import type { CollectionSyncManager } from './sync.js'
 import type { CollectionEventsManager } from './events.js'
 import type { CollectionImpl } from './index.js'
+import type { CollectionStateManager } from './state.js'
+import type { WithVirtualProps } from '../virtual-props.js'
 
 export class CollectionChangesManager<
   TOutput extends object = Record<string, unknown>,
@@ -21,6 +23,7 @@ export class CollectionChangesManager<
   private sync!: CollectionSyncManager<TOutput, TKey, TSchema, TInput>
   private events!: CollectionEventsManager
   private collection!: CollectionImpl<TOutput, TKey, any, TSchema, TInput>
+  private state!: CollectionStateManager<TOutput, TKey, TSchema, TInput>
 
   public activeSubscribersCount = 0
   public changeSubscriptions = new Set<CollectionSubscription>()
@@ -37,11 +40,13 @@ export class CollectionChangesManager<
     sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>
     events: CollectionEventsManager
     collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>
+    state: CollectionStateManager<TOutput, TKey, TSchema, TInput>
   }) {
     this.lifecycle = deps.lifecycle
     this.sync = deps.sync
     this.events = deps.events
     this.collection = deps.collection
+    this.state = deps.state
   }
 
   /**
@@ -55,6 +60,16 @@ export class CollectionChangesManager<
     }
   }
 
+  /**
+   * Enriches a change message with virtual properties ($synced, $origin, $key, $collectionId).
+   * Uses the "add-if-missing" pattern to preserve virtual properties from upstream collections.
+   */
+  private enrichChangeWithVirtualProps(
+    change: ChangeMessage<TOutput, TKey>,
+  ): ChangeMessage<WithVirtualProps<TOutput, TKey>, TKey> {
+    return this.state.enrichChangeMessage(change)
+  }
+
   /**
    * Emit events either immediately or batch them for later emission
    */
@@ -70,26 +85,32 @@ export class CollectionChangesManager<
     }
 
     // Either we're not batching, or we're forcing emission (user action or ending batch cycle)
-    let eventsToEmit = changes
+    let rawEvents = changes
 
     if (forceEmit) {
       // Force emit is used to end a batch (e.g. after a sync commit). Combine any
       // buffered optimistic events with the final changes so subscribers see the
       // whole picture, even if the sync diff is empty.
       if (this.batchedEvents.length > 0) {
-        eventsToEmit = [...this.batchedEvents, ...changes]
+        rawEvents = [...this.batchedEvents, ...changes]
       }
       this.batchedEvents = []
       this.shouldBatchEvents = false
     }
 
-    if (eventsToEmit.length === 0) {
+    if (rawEvents.length === 0) {
       return
     }
 
+    // Enrich all change messages with virtual properties
+    // This uses the "add-if-missing" pattern to preserve pass-through semantics
+    const enrichedEvents: Array<
+      ChangeMessage<WithVirtualProps<TOutput, TKey>, TKey>
+    > = rawEvents.map((change) => this.enrichChangeWithVirtualProps(change))
+
     // Emit to all listeners
     for (const subscription of this.changeSubscriptions) {
-      subscription.emitEvents(eventsToEmit)
+      subscription.emitEvents(enrichedEvents)
     }
   }
 
@@ -97,8 +118,10 @@ export class CollectionChangesManager<
    * Subscribe to changes in the collection
    */
   public subscribeChanges(
-    callback: (changes: Array<ChangeMessage<TOutput>>) => void,
-    options: SubscribeChangesOptions<TOutput> = {},
+    callback: (
+      changes: Array<ChangeMessage<WithVirtualProps<TOutput, TKey>>>,
+    ) => void,
+    options: SubscribeChangesOptions<TOutput, TKey> = {},
   ): CollectionSubscription {
     // Start sync and track subscriber
     this.addSubscriber()
@@ -113,7 +136,7 @@ export class CollectionChangesManager<
     const { where, ...opts } = options
     let whereExpression = opts.whereExpression
     if (where) {
-      const proxy = createSingleRowRefProxy<TOutput>()
+      const proxy = createSingleRowRefProxy<WithVirtualProps<TOutput, TKey>>()
       const result = where(proxy)
       whereExpression = toExpression(result)
     }

package/src/collection/cleanup-queue.ts

@@ -0,0 +1,105 @@
+type CleanupTask = {
+  executeAt: number
+  callback: () => void
+}
+
+/**
+ * Batches many GC registrations behind a single shared timeout.
+ */
+export class CleanupQueue {
+  private static instance: CleanupQueue | null = null
+
+  private tasks: Map<unknown, CleanupTask> = new Map()
+
+  private timeoutId: ReturnType<typeof setTimeout> | null = null
+  private microtaskScheduled = false
+
+  private constructor() {}
+
+  public static getInstance(): CleanupQueue {
+    if (!CleanupQueue.instance) {
+      CleanupQueue.instance = new CleanupQueue()
+    }
+    return CleanupQueue.instance
+  }
+
+  /**
+   * Queues a cleanup task and defers timeout selection to a microtask so
+   * multiple synchronous registrations can share one root timer.
+   */
+  public schedule(key: unknown, gcTime: number, callback: () => void): void {
+    const executeAt = Date.now() + gcTime
+    this.tasks.set(key, { executeAt, callback })
+
+    if (!this.microtaskScheduled) {
+      this.microtaskScheduled = true
+      Promise.resolve().then(() => {
+        this.microtaskScheduled = false
+        this.updateTimeout()
+      })
+    }
+  }
+
+  public cancel(key: unknown): void {
+    this.tasks.delete(key)
+  }
+
+  /**
+   * Keeps only one active timeout: whichever task is due next.
+   */
+  private updateTimeout(): void {
+    if (this.timeoutId !== null) {
+      clearTimeout(this.timeoutId)
+      this.timeoutId = null
+    }
+
+    if (this.tasks.size === 0) {
+      return
+    }
+
+    let earliestTime = Infinity
+    for (const task of this.tasks.values()) {
+      if (task.executeAt < earliestTime) {
+        earliestTime = task.executeAt
+      }
+    }
+
+    const delay = Math.max(0, earliestTime - Date.now())
+    this.timeoutId = setTimeout(() => this.process(), delay)
+  }
+
+  /**
+   * Runs every task whose deadline has passed, then schedules the next wakeup
+   * if there is still pending work.
+   */
+  private process(): void {
+    this.timeoutId = null
+    const now = Date.now()
+    for (const [key, task] of this.tasks.entries()) {
+      if (now >= task.executeAt) {
+        this.tasks.delete(key)
+        try {
+          task.callback()
+        } catch (error) {
+          console.error('Error in CleanupQueue task:', error)
+        }
+      }
+    }
+
+    if (this.tasks.size > 0) {
+      this.updateTimeout()
+    }
+  }
+
+  /**
+   * Resets the singleton instance for tests.
+   */
+  public static resetInstance(): void {
+    if (CleanupQueue.instance) {
+      if (CleanupQueue.instance.timeoutId !== null) {
+        clearTimeout(CleanupQueue.instance.timeoutId)
+      }
+      CleanupQueue.instance = null
+    }
+  }
+}