@tanstack/db 0.5.33 → 0.6.0

package/dist/cjs/utils.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"utils.cjs","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":"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"}
+{"version":3,"file":"utils.cjs","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/cjs/utils.d.cts

@@ -17,6 +17,11 @@ import { CompareOptions } from './query/builder/types.cjs';
  * ```
  */
 export declare function deepEquals(a: any, b: any): boolean;
+export interface TemporalLike {
+    [Symbol.toStringTag]: string;
+    toString: () => string;
+    equals?: (other: unknown) => boolean;
+}
 /** Checks if the value is a Temporal object by checking for the Temporal brand */
-export declare function isTemporal(a: any): boolean;
+export declare function isTemporal(a: unknown): a is TemporalLike;
 export declare const DEFAULT_COMPARE_OPTIONS: CompareOptions;

package/dist/cjs/virtual-props.cjs

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+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));
+}
+exports.VIRTUAL_PROP_NAMES = VIRTUAL_PROP_NAMES;
+exports.enrichRowWithVirtualProps = enrichRowWithVirtualProps;
+exports.hasVirtualPropPath = hasVirtualPropPath;
+exports.hasVirtualProps = hasVirtualProps;
+exports.isVirtualPropName = isVirtualPropName;
+//# sourceMappingURL=virtual-props.cjs.map

package/dist/cjs/virtual-props.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-props.cjs","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/dist/cjs/virtual-props.d.cts

@@ -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/collection/change-events.d.ts

@@ -1,6 +1,7 @@
 import { ChangeMessage, CollectionLike, CurrentStateAsChangesOptions, SubscribeChangesOptions } from '../types.js';
 import { SingleRowRefProxy } from '../query/builder/ref-proxy.js';
 import { BasicExpression } from '../query/ir.js';
+import { WithVirtualProps } from '../virtual-props.js';
 /**
  * Returns the current state of the collection as an array of changes
  * @param collection - The collection to get changes from
@@ -32,7 +33,7 @@ import { BasicExpression } from '../query/ir.js';
  *   orderBy: [{ expression: row.score, compareOptions: { direction: 'desc' } }],
  * })
  */
-export declare function currentStateAsChanges<T extends object, TKey extends string | number>(collection: CollectionLike<T, TKey>, options?: CurrentStateAsChangesOptions): Array<ChangeMessage<T>> | void;
+export declare function currentStateAsChanges<T extends object, TKey extends string | number>(collection: CollectionLike<WithVirtualProps<T, TKey>, TKey>, options?: CurrentStateAsChangesOptions): Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> | void;
 /**
  * Creates a filter function from a where callback
  * @param whereCallback - The callback function that defines the filter condition
@@ -51,4 +52,4 @@ export declare function createFilterFunctionFromExpression<T extends object>(exp
  * @param options - The subscription options containing the where clause
  * @returns A filtered callback function
  */
-export declare function createFilteredCallback<T extends object>(originalCallback: (changes: Array<ChangeMessage<T>>) => void, options: SubscribeChangesOptions): (changes: Array<ChangeMessage<T>>) => void;
+export declare function createFilteredCallback<T extends object, TKey extends string | number = string | number>(originalCallback: (changes: Array<ChangeMessage<T>>) => void, options: SubscribeChangesOptions<T, TKey>): (changes: Array<ChangeMessage<T>>) => void;

package/dist/esm/collection/change-events.js.map

@@ -1 +1 @@
-{"version":3,"file":"change-events.js","sources":["../../../src/collection/change-events.ts"],"sourcesContent":["import {\n  createSingleRowRefProxy,\n  toExpression,\n} from '../query/builder/ref-proxy'\nimport {\n  compileSingleRowExpression,\n  toBooleanPredicate,\n} from '../query/compiler/evaluators.js'\nimport {\n  findIndexForField,\n  optimizeExpressionWithIndexes,\n} from '../utils/index-optimization.js'\nimport { ensureIndexForField } from '../indexes/auto-index.js'\nimport { makeComparator } from '../utils/comparison.js'\nimport { buildCompareOptions } from '../query/compiler/order-by'\nimport type {\n  ChangeMessage,\n  CollectionLike,\n  CurrentStateAsChangesOptions,\n  SubscribeChangesOptions,\n} from '../types'\nimport type { CollectionImpl } from './index.js'\nimport type { SingleRowRefProxy } from '../query/builder/ref-proxy'\nimport type { BasicExpression, OrderBy } from '../query/ir.js'\n\n/**\n * Returns the current state of the collection as an array of changes\n * @param collection - The collection to get changes from\n * @param options - Options including optional where filter, orderBy, and limit\n * @returns An array of changes\n * @example\n * // Get all items as changes\n * const allChanges = currentStateAsChanges(collection)\n *\n * // Get only items matching a condition\n * const activeChanges = currentStateAsChanges(collection, {\n *   where: (row) => row.status === 'active'\n * })\n *\n * // Get only items using a pre-compiled expression\n * const activeChanges = currentStateAsChanges(collection, {\n *   where: eq(row.status, 'active')\n * })\n *\n * // Get items ordered by name with limit\n * const topUsers = currentStateAsChanges(collection, {\n *   orderBy: [{ expression: row.name, compareOptions: { direction: 'asc' } }],\n *   limit: 10\n * })\n *\n * // Get active users ordered by score (highest score first)\n * const topActiveUsers = currentStateAsChanges(collection, {\n *   where: eq(row.status, 'active'),\n *   orderBy: [{ expression: row.score, compareOptions: { direction: 'desc' } }],\n * })\n */\nexport function currentStateAsChanges<\n  T extends object,\n  TKey extends string | number,\n>(\n  collection: CollectionLike<T, TKey>,\n  options: CurrentStateAsChangesOptions = {},\n): Array<ChangeMessage<T>> | void {\n  // Helper function to collect filtered results\n  const collectFilteredResults = (\n    filterFn?: (value: T) => boolean,\n  ): Array<ChangeMessage<T>> => {\n    const result: Array<ChangeMessage<T>> = []\n    for (const [key, value] of collection.entries()) {\n      // If no filter function is provided, include all items\n      if (filterFn?.(value) ?? true) {\n        result.push({\n          type: `insert`,\n          key,\n          value,\n        })\n      }\n    }\n    return result\n  }\n\n  // Validate that limit without orderBy doesn't happen\n  if (options.limit !== undefined && !options.orderBy) {\n    throw new Error(`limit cannot be used without orderBy`)\n  }\n\n  // First check if orderBy is present (optionally with limit)\n  if (options.orderBy) {\n    // Create where filter function if present\n    const whereFilter = options.where\n      ? createFilterFunctionFromExpression(options.where)\n      : undefined\n\n    // Get ordered keys using index optimization when possible\n    const orderedKeys = getOrderedKeys(\n      collection,\n      options.orderBy,\n      options.limit,\n      whereFilter,\n      options.optimizedOnly,\n    )\n\n    if (orderedKeys === undefined) {\n      // `getOrderedKeys` returned undefined because we asked for `optimizedOnly` and there was no index to use\n      return\n    }\n\n    // Convert keys to change messages\n    const result: Array<ChangeMessage<T>> = []\n    for (const key of orderedKeys) {\n      const value = collection.get(key)\n      if (value !== undefined) {\n        result.push({\n          type: `insert`,\n          key,\n          value,\n        })\n      }\n    }\n    return result\n  }\n\n  // If no orderBy OR orderBy optimization failed, use where clause optimization\n  if (!options.where) {\n    // No filtering, return all items\n    return collectFilteredResults()\n  }\n\n  // There's a where clause, let's see if we can use an index\n  try {\n    const expression: BasicExpression<boolean> = options.where\n\n    // Try to optimize the query using indexes\n    const optimizationResult = optimizeExpressionWithIndexes(\n      expression,\n      collection,\n    )\n\n    if (optimizationResult.canOptimize) {\n      // Use index optimization\n      const result: Array<ChangeMessage<T>> = []\n      for (const key of optimizationResult.matchingKeys) {\n        const value = collection.get(key)\n        if (value !== undefined) {\n          result.push({\n            type: `insert`,\n            key,\n            value,\n          })\n        }\n      }\n      return result\n    } else {\n      if (options.optimizedOnly) {\n        return\n      }\n\n      const filterFn = createFilterFunctionFromExpression(expression)\n      return collectFilteredResults(filterFn)\n    }\n  } catch (error) {\n    // If anything goes wrong with the where clause, fall back to full scan\n    console.warn(\n      `${collection.id ? `[${collection.id}] ` : ``}Error processing where clause, falling back to full scan:`,\n      error,\n    )\n\n    const filterFn = createFilterFunctionFromExpression(options.where)\n\n    if (options.optimizedOnly) {\n      return\n    }\n\n    return collectFilteredResults(filterFn)\n  }\n}\n\n/**\n * Creates a filter function from a where callback\n * @param whereCallback - The callback function that defines the filter condition\n * @returns A function that takes an item and returns true if it matches the filter\n */\nexport function createFilterFunction<T extends object>(\n  whereCallback: (row: SingleRowRefProxy<T>) => any,\n): (item: T) => boolean {\n  return (item: T): boolean => {\n    try {\n      // First try the RefProxy approach for query builder functions\n      const singleRowRefProxy = createSingleRowRefProxy<T>()\n      const whereExpression = whereCallback(singleRowRefProxy)\n      const expression = toExpression(whereExpression)\n      const evaluator = compileSingleRowExpression(expression)\n      const result = evaluator(item as Record<string, unknown>)\n      // WHERE clauses should always evaluate to boolean predicates (Kevin's feedback)\n      return toBooleanPredicate(result)\n    } catch {\n      // If RefProxy approach fails (e.g., arithmetic operations), fall back to direct evaluation\n      try {\n        // Create a simple proxy that returns actual values for arithmetic operations\n        const simpleProxy = new Proxy(item as any, {\n          get(target, prop) {\n            return target[prop]\n          },\n        }) as SingleRowRefProxy<T>\n\n        const result = whereCallback(simpleProxy)\n        return toBooleanPredicate(result)\n      } catch {\n        // If both approaches fail, exclude the item\n        return false\n      }\n    }\n  }\n}\n\n/**\n * Creates a filter function from a pre-compiled expression\n * @param expression - The pre-compiled expression to evaluate\n * @returns A function that takes an item and returns true if it matches the filter\n */\nexport function createFilterFunctionFromExpression<T extends object>(\n  expression: BasicExpression<boolean>,\n): (item: T) => boolean {\n  // Compile expression once when filter function is created, not on every invocation\n  const evaluator = compileSingleRowExpression(expression)\n\n  return (item: T): boolean => {\n    try {\n      const result = evaluator(item as Record<string, unknown>)\n      return toBooleanPredicate(result)\n    } catch {\n      // If evaluation fails, exclude the item\n      return false\n    }\n  }\n}\n\n/**\n * Creates a filtered callback that only calls the original callback with changes that match the where clause\n * @param originalCallback - The original callback to filter\n * @param options - The subscription options containing the where clause\n * @returns A filtered callback function\n */\nexport function createFilteredCallback<T extends object>(\n  originalCallback: (changes: Array<ChangeMessage<T>>) => void,\n  options: SubscribeChangesOptions,\n): (changes: Array<ChangeMessage<T>>) => void {\n  const filterFn = createFilterFunctionFromExpression(options.whereExpression!)\n\n  return (changes: Array<ChangeMessage<T>>) => {\n    const filteredChanges: Array<ChangeMessage<T>> = []\n\n    for (const change of changes) {\n      if (change.type === `insert`) {\n        // For inserts, check if the new value matches the filter\n        if (filterFn(change.value)) {\n          filteredChanges.push(change)\n        }\n      } else if (change.type === `update`) {\n        // For updates, we need to check both old and new values\n        const newValueMatches = filterFn(change.value)\n        const oldValueMatches = change.previousValue\n          ? filterFn(change.previousValue)\n          : false\n\n        if (newValueMatches && oldValueMatches) {\n          // Both old and new match: emit update\n          filteredChanges.push(change)\n        } else if (newValueMatches && !oldValueMatches) {\n          // New matches but old didn't: emit insert\n          filteredChanges.push({\n            ...change,\n            type: `insert`,\n          })\n        } else if (!newValueMatches && oldValueMatches) {\n          // Old matched but new doesn't: emit delete\n          filteredChanges.push({\n            ...change,\n            type: `delete`,\n            value: change.previousValue!, // Use the previous value for the delete\n          })\n        }\n        // If neither matches, don't emit anything\n      } else {\n        // For deletes, include if the previous value would have matched\n        // (so subscribers know something they were tracking was deleted)\n        if (filterFn(change.value)) {\n          filteredChanges.push(change)\n        }\n      }\n    }\n\n    // Always call the original callback if we have filtered changes OR\n    // if the original changes array was empty (which indicates a ready signal)\n    if (filteredChanges.length > 0 || changes.length === 0) {\n      originalCallback(filteredChanges)\n    }\n  }\n}\n\n/**\n * Gets ordered keys from a collection using index optimization when possible\n * @param collection - The collection to get keys from\n * @param orderBy - The order by clause\n * @param limit - Optional limit on number of keys to return\n * @param whereFilter - Optional filter function to apply while traversing\n * @returns Array of keys in sorted order\n */\nfunction getOrderedKeys<T extends object, TKey extends string | number>(\n  collection: CollectionLike<T, TKey>,\n  orderBy: OrderBy,\n  limit?: number,\n  whereFilter?: (item: T) => boolean,\n  optimizedOnly?: boolean,\n): Array<TKey> | undefined {\n  // For single-column orderBy on a ref expression, try index optimization\n  if (orderBy.length === 1) {\n    const clause = orderBy[0]!\n    const orderByExpression = clause.expression\n\n    if (orderByExpression.type === `ref`) {\n      const propRef = orderByExpression\n      const fieldPath = propRef.path\n      const compareOpts = buildCompareOptions(clause, collection)\n\n      // Ensure index exists for this field\n      ensureIndexForField(\n        fieldPath[0]!,\n        fieldPath,\n        collection as CollectionImpl<T, TKey>,\n        compareOpts,\n      )\n\n      // Find the index\n      const index = findIndexForField(collection, fieldPath, compareOpts)\n\n      if (index && index.supports(`gt`)) {\n        // Use index optimization\n        const filterFn = (key: TKey): boolean => {\n          const value = collection.get(key)\n          if (value === undefined) {\n            return false\n          }\n          return whereFilter?.(value) ?? true\n        }\n\n        // Take the keys that match the filter and limit\n        // if no limit is provided `index.keyCount` is used,\n        // i.e. we will take all keys that match the filter\n        return index.takeFromStart(limit ?? index.keyCount, filterFn)\n      }\n    }\n  }\n\n  if (optimizedOnly) {\n    return\n  }\n\n  // Fallback: collect all items and sort in memory\n  const allItems: Array<{ key: TKey; value: T }> = []\n  for (const [key, value] of collection.entries()) {\n    if (whereFilter?.(value) ?? true) {\n      allItems.push({ key, value })\n    }\n  }\n\n  // Sort using makeComparator\n  const compare = (a: { key: TKey; value: T }, b: { key: TKey; value: T }) => {\n    for (const clause of orderBy) {\n      const compareFn = makeComparator(clause.compareOptions)\n\n      // Extract values for comparison\n      const aValue = extractValueFromItem(a.value, clause.expression)\n      const bValue = extractValueFromItem(b.value, clause.expression)\n\n      const result = compareFn(aValue, bValue)\n      if (result !== 0) {\n        return result\n      }\n    }\n    return 0\n  }\n\n  allItems.sort(compare)\n  const sortedKeys = allItems.map((item) => item.key)\n\n  // Apply limit if provided\n  if (limit !== undefined) {\n    return sortedKeys.slice(0, limit)\n  }\n\n  // if no limit is provided, we will return all keys\n  return sortedKeys\n}\n\n/**\n * Helper function to extract a value from an item based on an expression\n */\nfunction extractValueFromItem(item: any, expression: BasicExpression): any {\n  if (expression.type === `ref`) {\n    const propRef = expression\n    let value = item\n    for (const pathPart of propRef.path) {\n      value = value?.[pathPart]\n    }\n    return value\n  } else if (expression.type === `val`) {\n    return expression.value\n  } else {\n    // It must be a function\n    const evaluator = compileSingleRowExpression(expression)\n    return evaluator(item as Record<string, unknown>)\n  }\n}\n"],"names":[],"mappings":";;;;;AAwDO,SAAS,sBAId,YACA,UAAwC,IACR;AAEhC,QAAM,yBAAyB,CAC7B,aAC4B;AAC5B,UAAM,SAAkC,CAAA;AACxC,eAAW,CAAC,KAAK,KAAK,KAAK,WAAW,WAAW;AAE/C,UAAI,WAAW,KAAK,KAAK,MAAM;AAC7B,eAAO,KAAK;AAAA,UACV,MAAM;AAAA,UACN;AAAA,UACA;AAAA,QAAA,CACD;AAAA,MACH;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAGA,MAAI,QAAQ,UAAU,UAAa,CAAC,QAAQ,SAAS;AACnD,UAAM,IAAI,MAAM,sCAAsC;AAAA,EACxD;AAGA,MAAI,QAAQ,SAAS;AAEnB,UAAM,cAAc,QAAQ,QACxB,mCAAmC,QAAQ,KAAK,IAChD;AAGJ,UAAM,cAAc;AAAA,MAClB;AAAA,MACA,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR;AAAA,MACA,QAAQ;AAAA,IAAA;AAGV,QAAI,gBAAgB,QAAW;AAE7B;AAAA,IACF;AAGA,UAAM,SAAkC,CAAA;AACxC,eAAW,OAAO,aAAa;AAC7B,YAAM,QAAQ,WAAW,IAAI,GAAG;AAChC,UAAI,UAAU,QAAW;AACvB,eAAO,KAAK;AAAA,UACV,MAAM;AAAA,UACN;AAAA,UACA;AAAA,QAAA,CACD;AAAA,MACH;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAGA,MAAI,CAAC,QAAQ,OAAO;AAElB,WAAO,uBAAA;AAAA,EACT;AAGA,MAAI;AACF,UAAM,aAAuC,QAAQ;AAGrD,UAAM,qBAAqB;AAAA,MACzB;AAAA,MACA;AAAA,IAAA;AAGF,QAAI,mBAAmB,aAAa;AAElC,YAAM,SAAkC,CAAA;AACxC,iBAAW,OAAO,mBAAmB,cAAc;AACjD,cAAM,QAAQ,WAAW,IAAI,GAAG;AAChC,YAAI,UAAU,QAAW;AACvB,iBAAO,KAAK;AAAA,YACV,MAAM;AAAA,YACN;AAAA,YACA;AAAA,UAAA,CACD;AAAA,QACH;AAAA,MACF;AACA,aAAO;AAAA,IACT,OAAO;AACL,UAAI,QAAQ,eAAe;AACzB;AAAA,MACF;AAEA,YAAM,WAAW,mCAAmC,UAAU;AAC9D,aAAO,uBAAuB,QAAQ;AAAA,IACxC;AAAA,EACF,SAAS,OAAO;AAEd,YAAQ;AAAA,MACN,GAAG,WAAW,KAAK,IAAI,WAAW,EAAE,OAAO,EAAE;AAAA,MAC7C;AAAA,IAAA;AAGF,UAAM,WAAW,mCAAmC,QAAQ,KAAK;AAEjE,QAAI,QAAQ,eAAe;AACzB;AAAA,IACF;AAEA,WAAO,uBAAuB,QAAQ;AAAA,EACxC;AACF;AA6CO,SAAS,mCACd,YACsB;AAEtB,QAAM,YAAY,2BAA2B,UAAU;AAEvD,SAAO,CAAC,SAAqB;AAC3B,QAAI;AACF,YAAM,SAAS,UAAU,IAA+B;AACxD,aAAO,mBAAmB,MAAM;AAAA,IAClC,QAAQ;AAEN,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAQO,SAAS,uBACd,kBACA,SAC4C;AAC5C,QAAM,WAAW,mCAAmC,QAAQ,eAAgB;AAE5E,SAAO,CAAC,YAAqC;AAC3C,UAAM,kBAA2C,CAAA;AAEjD,eAAW,UAAU,SAAS;AAC5B,UAAI,OAAO,SAAS,UAAU;AAE5B,YAAI,SAAS,OAAO,KAAK,GAAG;AAC1B,0BAAgB,KAAK,MAAM;AAAA,QAC7B;AAAA,MACF,WAAW,OAAO,SAAS,UAAU;AAEnC,cAAM,kBAAkB,SAAS,OAAO,KAAK;AAC7C,cAAM,kBAAkB,OAAO,gBAC3B,SAAS,OAAO,aAAa,IAC7B;AAEJ,YAAI,mBAAmB,iBAAiB;AAEtC,0BAAgB,KAAK,MAAM;AAAA,QAC7B,WAAW,mBAAmB,CAAC,iBAAiB;AAE9C,0BAAgB,KAAK;AAAA,YACnB,GAAG;AAAA,YACH,MAAM;AAAA,UAAA,CACP;AAAA,QACH,WAAW,CAAC,mBAAmB,iBAAiB;AAE9C,0BAAgB,KAAK;AAAA,YACnB,GAAG;AAAA,YACH,MAAM;AAAA,YACN,OAAO,OAAO;AAAA;AAAA,UAAA,CACf;AAAA,QACH;AAAA,MAEF,OAAO;AAGL,YAAI,SAAS,OAAO,KAAK,GAAG;AAC1B,0BAAgB,KAAK,MAAM;AAAA,QAC7B;AAAA,MACF;AAAA,IACF;AAIA,QAAI,gBAAgB,SAAS,KAAK,QAAQ,WAAW,GAAG;AACtD,uBAAiB,eAAe;AAAA,IAClC;AAAA,EACF;AACF;AAUA,SAAS,eACP,YACA,SACA,OACA,aACA,eACyB;AAEzB,MAAI,QAAQ,WAAW,GAAG;AACxB,UAAM,SAAS,QAAQ,CAAC;AACxB,UAAM,oBAAoB,OAAO;AAEjC,QAAI,kBAAkB,SAAS,OAAO;AACpC,YAAM,UAAU;AAChB,YAAM,YAAY,QAAQ;AAC1B,YAAM,cAAc,oBAAoB,QAAQ,UAAU;AAG1D;AAAA,QACE,UAAU,CAAC;AAAA,QACX;AAAA,QACA;AAAA,QACA;AAAA,MAAA;AAIF,YAAM,QAAQ,kBAAkB,YAAY,WAAW,WAAW;AAElE,UAAI,SAAS,MAAM,SAAS,IAAI,GAAG;AAEjC,cAAM,WAAW,CAAC,QAAuB;AACvC,gBAAM,QAAQ,WAAW,IAAI,GAAG;AAChC,cAAI,UAAU,QAAW;AACvB,mBAAO;AAAA,UACT;AACA,iBAAO,cAAc,KAAK,KAAK;AAAA,QACjC;AAKA,eAAO,MAAM,cAAc,SAAS,MAAM,UAAU,QAAQ;AAAA,MAC9D;AAAA,IACF;AAAA,EACF;AAEA,MAAI,eAAe;AACjB;AAAA,EACF;AAGA,QAAM,WAA2C,CAAA;AACjD,aAAW,CAAC,KAAK,KAAK,KAAK,WAAW,WAAW;AAC/C,QAAI,cAAc,KAAK,KAAK,MAAM;AAChC,eAAS,KAAK,EAAE,KAAK,MAAA,CAAO;AAAA,IAC9B;AAAA,EACF;AAGA,QAAM,UAAU,CAAC,GAA4B,MAA+B;AAC1E,eAAW,UAAU,SAAS;AAC5B,YAAM,YAAY,eAAe,OAAO,cAAc;AAGtD,YAAM,SAAS,qBAAqB,EAAE,OAAO,OAAO,UAAU;AAC9D,YAAM,SAAS,qBAAqB,EAAE,OAAO,OAAO,UAAU;AAE9D,YAAM,SAAS,UAAU,QAAQ,MAAM;AACvC,UAAI,WAAW,GAAG;AAChB,eAAO;AAAA,MACT;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAEA,WAAS,KAAK,OAAO;AACrB,QAAM,aAAa,SAAS,IAAI,CAAC,SAAS,KAAK,GAAG;AAGlD,MAAI,UAAU,QAAW;AACvB,WAAO,WAAW,MAAM,GAAG,KAAK;AAAA,EAClC;AAGA,SAAO;AACT;AAKA,SAAS,qBAAqB,MAAW,YAAkC;AACzE,MAAI,WAAW,SAAS,OAAO;AAC7B,UAAM,UAAU;AAChB,QAAI,QAAQ;AACZ,eAAW,YAAY,QAAQ,MAAM;AACnC,cAAQ,QAAQ,QAAQ;AAAA,IAC1B;AACA,WAAO;AAAA,EACT,WAAW,WAAW,SAAS,OAAO;AACpC,WAAO,WAAW;AAAA,EACpB,OAAO;AAEL,UAAM,YAAY,2BAA2B,UAAU;AACvD,WAAO,UAAU,IAA+B;AAAA,EAClD;AACF;"}
+{"version":3,"file":"change-events.js","sources":["../../../src/collection/change-events.ts"],"sourcesContent":["import {\n  createSingleRowRefProxy,\n  toExpression,\n} from '../query/builder/ref-proxy'\nimport {\n  compileSingleRowExpression,\n  toBooleanPredicate,\n} from '../query/compiler/evaluators.js'\nimport {\n  findIndexForField,\n  optimizeExpressionWithIndexes,\n} from '../utils/index-optimization.js'\nimport { ensureIndexForField } from '../indexes/auto-index.js'\nimport { makeComparator } from '../utils/comparison.js'\nimport { buildCompareOptions } from '../query/compiler/order-by'\nimport type {\n  ChangeMessage,\n  CollectionLike,\n  CurrentStateAsChangesOptions,\n  SubscribeChangesOptions,\n} from '../types'\nimport type { CollectionImpl } from './index.js'\nimport type { SingleRowRefProxy } from '../query/builder/ref-proxy'\nimport type { BasicExpression, OrderBy } from '../query/ir.js'\nimport type { WithVirtualProps } from '../virtual-props.js'\n\n/**\n * Returns the current state of the collection as an array of changes\n * @param collection - The collection to get changes from\n * @param options - Options including optional where filter, orderBy, and limit\n * @returns An array of changes\n * @example\n * // Get all items as changes\n * const allChanges = currentStateAsChanges(collection)\n *\n * // Get only items matching a condition\n * const activeChanges = currentStateAsChanges(collection, {\n *   where: (row) => row.status === 'active'\n * })\n *\n * // Get only items using a pre-compiled expression\n * const activeChanges = currentStateAsChanges(collection, {\n *   where: eq(row.status, 'active')\n * })\n *\n * // Get items ordered by name with limit\n * const topUsers = currentStateAsChanges(collection, {\n *   orderBy: [{ expression: row.name, compareOptions: { direction: 'asc' } }],\n *   limit: 10\n * })\n *\n * // Get active users ordered by score (highest score first)\n * const topActiveUsers = currentStateAsChanges(collection, {\n *   where: eq(row.status, 'active'),\n *   orderBy: [{ expression: row.score, compareOptions: { direction: 'desc' } }],\n * })\n */\nexport function currentStateAsChanges<\n  T extends object,\n  TKey extends string | number,\n>(\n  collection: CollectionLike<WithVirtualProps<T, TKey>, TKey>,\n  options: CurrentStateAsChangesOptions = {},\n): Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> | void {\n  // Helper function to collect filtered results\n  const collectFilteredResults = (\n    filterFn?: (value: WithVirtualProps<T, TKey>) => boolean,\n  ): Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> => {\n    const result: Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> = []\n    for (const [key, value] of collection.entries()) {\n      // If no filter function is provided, include all items\n      if (filterFn?.(value) ?? true) {\n        result.push({\n          type: `insert`,\n          key,\n          value,\n        })\n      }\n    }\n    return result\n  }\n\n  // Validate that limit without orderBy doesn't happen\n  if (options.limit !== undefined && !options.orderBy) {\n    throw new Error(`limit cannot be used without orderBy`)\n  }\n\n  // First check if orderBy is present (optionally with limit)\n  if (options.orderBy) {\n    // Create where filter function if present\n    const whereFilter = options.where\n      ? createFilterFunctionFromExpression(options.where)\n      : undefined\n\n    // Get ordered keys using index optimization when possible\n    const orderedKeys = getOrderedKeys(\n      collection,\n      options.orderBy,\n      options.limit,\n      whereFilter,\n      options.optimizedOnly,\n    )\n\n    if (orderedKeys === undefined) {\n      // `getOrderedKeys` returned undefined because we asked for `optimizedOnly` and there was no index to use\n      return\n    }\n\n    // Convert keys to change messages\n    const result: Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> = []\n    for (const key of orderedKeys) {\n      const value = collection.get(key)\n      if (value !== undefined) {\n        result.push({\n          type: `insert`,\n          key,\n          value,\n        })\n      }\n    }\n    return result\n  }\n\n  // If no orderBy OR orderBy optimization failed, use where clause optimization\n  if (!options.where) {\n    // No filtering, return all items\n    return collectFilteredResults()\n  }\n\n  // There's a where clause, let's see if we can use an index\n  try {\n    const expression: BasicExpression<boolean> = options.where\n\n    // Try to optimize the query using indexes\n    const optimizationResult = optimizeExpressionWithIndexes(\n      expression,\n      collection,\n    )\n\n    if (optimizationResult.canOptimize) {\n      // Use index optimization\n      const result: Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> = []\n      for (const key of optimizationResult.matchingKeys) {\n        const value = collection.get(key)\n        if (value !== undefined) {\n          result.push({\n            type: `insert`,\n            key,\n            value,\n          })\n        }\n      }\n      return result\n    } else {\n      if (options.optimizedOnly) {\n        return\n      }\n\n      const filterFn = createFilterFunctionFromExpression(expression)\n      return collectFilteredResults(filterFn)\n    }\n  } catch (error) {\n    // If anything goes wrong with the where clause, fall back to full scan\n    console.warn(\n      `${collection.id ? `[${collection.id}] ` : ``}Error processing where clause, falling back to full scan:`,\n      error,\n    )\n\n    const filterFn = createFilterFunctionFromExpression(options.where)\n\n    if (options.optimizedOnly) {\n      return\n    }\n\n    return collectFilteredResults(filterFn)\n  }\n}\n\n/**\n * Creates a filter function from a where callback\n * @param whereCallback - The callback function that defines the filter condition\n * @returns A function that takes an item and returns true if it matches the filter\n */\nexport function createFilterFunction<T extends object>(\n  whereCallback: (row: SingleRowRefProxy<T>) => any,\n): (item: T) => boolean {\n  return (item: T): boolean => {\n    try {\n      // First try the RefProxy approach for query builder functions\n      const singleRowRefProxy = createSingleRowRefProxy<T>()\n      const whereExpression = whereCallback(singleRowRefProxy)\n      const expression = toExpression(whereExpression)\n      const evaluator = compileSingleRowExpression(expression)\n      const result = evaluator(item as Record<string, unknown>)\n      // WHERE clauses should always evaluate to boolean predicates (Kevin's feedback)\n      return toBooleanPredicate(result)\n    } catch {\n      // If RefProxy approach fails (e.g., arithmetic operations), fall back to direct evaluation\n      try {\n        // Create a simple proxy that returns actual values for arithmetic operations\n        const simpleProxy = new Proxy(item as any, {\n          get(target, prop) {\n            return target[prop]\n          },\n        }) as SingleRowRefProxy<T>\n\n        const result = whereCallback(simpleProxy)\n        return toBooleanPredicate(result)\n      } catch {\n        // If both approaches fail, exclude the item\n        return false\n      }\n    }\n  }\n}\n\n/**\n * Creates a filter function from a pre-compiled expression\n * @param expression - The pre-compiled expression to evaluate\n * @returns A function that takes an item and returns true if it matches the filter\n */\nexport function createFilterFunctionFromExpression<T extends object>(\n  expression: BasicExpression<boolean>,\n): (item: T) => boolean {\n  // Compile expression once when filter function is created, not on every invocation\n  const evaluator = compileSingleRowExpression(expression)\n\n  return (item: T): boolean => {\n    try {\n      const result = evaluator(item as Record<string, unknown>)\n      return toBooleanPredicate(result)\n    } catch {\n      // If evaluation fails, exclude the item\n      return false\n    }\n  }\n}\n\n/**\n * Creates a filtered callback that only calls the original callback with changes that match the where clause\n * @param originalCallback - The original callback to filter\n * @param options - The subscription options containing the where clause\n * @returns A filtered callback function\n */\nexport function createFilteredCallback<\n  T extends object,\n  TKey extends string | number = string | number,\n>(\n  originalCallback: (changes: Array<ChangeMessage<T>>) => void,\n  options: SubscribeChangesOptions<T, TKey>,\n): (changes: Array<ChangeMessage<T>>) => void {\n  const filterFn = createFilterFunctionFromExpression(options.whereExpression!)\n\n  return (changes: Array<ChangeMessage<T>>) => {\n    const filteredChanges: Array<ChangeMessage<T>> = []\n\n    for (const change of changes) {\n      if (change.type === `insert`) {\n        // For inserts, check if the new value matches the filter\n        if (filterFn(change.value)) {\n          filteredChanges.push(change)\n        }\n      } else if (change.type === `update`) {\n        // For updates, we need to check both old and new values\n        const newValueMatches = filterFn(change.value)\n        const oldValueMatches = change.previousValue\n          ? filterFn(change.previousValue)\n          : false\n\n        if (newValueMatches && oldValueMatches) {\n          // Both old and new match: emit update\n          filteredChanges.push(change)\n        } else if (newValueMatches && !oldValueMatches) {\n          // New matches but old didn't: emit insert\n          filteredChanges.push({\n            ...change,\n            type: `insert`,\n          })\n        } else if (!newValueMatches && oldValueMatches) {\n          // Old matched but new doesn't: emit delete\n          filteredChanges.push({\n            ...change,\n            type: `delete`,\n            value: change.previousValue!, // Use the previous value for the delete\n          })\n        }\n        // If neither matches, don't emit anything\n      } else {\n        // For deletes, include if the previous value would have matched\n        // (so subscribers know something they were tracking was deleted)\n        if (filterFn(change.value)) {\n          filteredChanges.push(change)\n        }\n      }\n    }\n\n    // Always call the original callback if we have filtered changes OR\n    // if the original changes array was empty (which indicates a ready signal)\n    if (filteredChanges.length > 0 || changes.length === 0) {\n      originalCallback(filteredChanges)\n    }\n  }\n}\n\n/**\n * Gets ordered keys from a collection using index optimization when possible\n * @param collection - The collection to get keys from\n * @param orderBy - The order by clause\n * @param limit - Optional limit on number of keys to return\n * @param whereFilter - Optional filter function to apply while traversing\n * @returns Array of keys in sorted order\n */\nfunction getOrderedKeys<T extends object, TKey extends string | number>(\n  collection: CollectionLike<T, TKey>,\n  orderBy: OrderBy,\n  limit?: number,\n  whereFilter?: (item: T) => boolean,\n  optimizedOnly?: boolean,\n): Array<TKey> | undefined {\n  // For single-column orderBy on a ref expression, try index optimization\n  if (orderBy.length === 1) {\n    const clause = orderBy[0]!\n    const orderByExpression = clause.expression\n\n    if (orderByExpression.type === `ref`) {\n      const propRef = orderByExpression\n      const fieldPath = propRef.path\n      const compareOpts = buildCompareOptions(clause, collection)\n\n      // Ensure index exists for this field\n      ensureIndexForField(\n        fieldPath[0]!,\n        fieldPath,\n        collection as CollectionImpl<T, TKey>,\n        compareOpts,\n      )\n\n      // Find the index\n      const index = findIndexForField(collection, fieldPath, compareOpts)\n\n      if (index && index.supports(`gt`)) {\n        // Use index optimization\n        const filterFn = (key: TKey): boolean => {\n          const value = collection.get(key)\n          if (value === undefined) {\n            return false\n          }\n          return whereFilter?.(value) ?? true\n        }\n\n        // Take the keys that match the filter and limit\n        // if no limit is provided `index.keyCount` is used,\n        // i.e. we will take all keys that match the filter\n        return index.takeFromStart(limit ?? index.keyCount, filterFn)\n      }\n    }\n  }\n\n  if (optimizedOnly) {\n    return\n  }\n\n  // Fallback: collect all items and sort in memory\n  const allItems: Array<{ key: TKey; value: T }> = []\n  for (const [key, value] of collection.entries()) {\n    if (whereFilter?.(value) ?? true) {\n      allItems.push({ key, value })\n    }\n  }\n\n  // Sort using makeComparator\n  const compare = (a: { key: TKey; value: T }, b: { key: TKey; value: T }) => {\n    for (const clause of orderBy) {\n      const compareFn = makeComparator(clause.compareOptions)\n\n      // Extract values for comparison\n      const aValue = extractValueFromItem(a.value, clause.expression)\n      const bValue = extractValueFromItem(b.value, clause.expression)\n\n      const result = compareFn(aValue, bValue)\n      if (result !== 0) {\n        return result\n      }\n    }\n    return 0\n  }\n\n  allItems.sort(compare)\n  const sortedKeys = allItems.map((item) => item.key)\n\n  // Apply limit if provided\n  if (limit !== undefined) {\n    return sortedKeys.slice(0, limit)\n  }\n\n  // if no limit is provided, we will return all keys\n  return sortedKeys\n}\n\n/**\n * Helper function to extract a value from an item based on an expression\n */\nfunction extractValueFromItem(item: any, expression: BasicExpression): any {\n  if (expression.type === `ref`) {\n    const propRef = expression\n    let value = item\n    for (const pathPart of propRef.path) {\n      value = value?.[pathPart]\n    }\n    return value\n  } else if (expression.type === `val`) {\n    return expression.value\n  } else {\n    // It must be a function\n    const evaluator = compileSingleRowExpression(expression)\n    return evaluator(item as Record<string, unknown>)\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/collection/changes.d.ts

@@ -5,11 +5,14 @@ import { CollectionLifecycleManager } from './lifecycle.js';
 import { CollectionSyncManager } from './sync.js';
 import { CollectionEventsManager } from './events.js';
 import { CollectionImpl } from './index.js';
+import { CollectionStateManager } from './state.js';
+import { WithVirtualProps } from '../virtual-props.js';
 export declare class CollectionChangesManager<TOutput extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = StandardSchemaV1, TInput extends object = TOutput> {
     private lifecycle;
     private sync;
     private events;
     private collection;
+    private state;
     activeSubscribersCount: number;
     changeSubscriptions: Set<CollectionSubscription>;
     batchedEvents: Array<ChangeMessage<TOutput, TKey>>;
@@ -23,12 +26,18 @@ export declare class CollectionChangesManager<TOutput extends object = Record<st
         sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>;
         events: CollectionEventsManager;
         collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>;
+        state: CollectionStateManager<TOutput, TKey, TSchema, TInput>;
     }): void;
     /**
      * Emit an empty ready event to notify subscribers that the collection is ready
      * This bypasses the normal empty array check in emitEvents
      */
     emitEmptyReadyEvent(): void;
+    /**
+     * 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;
     /**
      * Emit events either immediately or batch them for later emission
      */
@@ -36,7 +45,7 @@ export declare class CollectionChangesManager<TOutput extends object = Record<st
     /**
      * Subscribe to changes in the collection
      */
-    subscribeChanges(callback: (changes: Array<ChangeMessage<TOutput>>) => void, options?: SubscribeChangesOptions<TOutput>): CollectionSubscription;
+    subscribeChanges(callback: (changes: Array<ChangeMessage<WithVirtualProps<TOutput, TKey>>>) => void, options?: SubscribeChangesOptions<TOutput, TKey>): CollectionSubscription;
     /**
      * Increment the active subscribers count and start sync if needed
      */

package/dist/esm/collection/changes.js

@@ -16,6 +16,7 @@ class CollectionChangesManager {
     this.sync = deps.sync;
     this.events = deps.events;
     this.collection = deps.collection;
+    this.state = deps.state;
   }
   /**
    * Emit an empty ready event to notify subscribers that the collection is ready
@@ -26,6 +27,13 @@ class CollectionChangesManager {
       subscription.emitEvents([]);
     }
   }
+  /**
+   * Enriches a change message with virtual properties ($synced, $origin, $key, $collectionId).
+   * Uses the "add-if-missing" pattern to preserve virtual properties from upstream collections.
+   */
+  enrichChangeWithVirtualProps(change) {
+    return this.state.enrichChangeMessage(change);
+  }
   /**
    * Emit events either immediately or batch them for later emission
    */
@@ -34,19 +42,20 @@ class CollectionChangesManager {
       this.batchedEvents.push(...changes);
       return;
     }
-    let eventsToEmit = changes;
+    let rawEvents = changes;
     if (forceEmit) {
       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;
     }
+    const enrichedEvents = rawEvents.map((change) => this.enrichChangeWithVirtualProps(change));
     for (const subscription of this.changeSubscriptions) {
-      subscription.emitEvents(eventsToEmit);
+      subscription.emitEvents(enrichedEvents);
     }
   }
   /**

package/dist/esm/collection/changes.js.map

@@ -1 +1 @@
-{"version":3,"file":"changes.js","sources":["../../../src/collection/changes.ts"],"sourcesContent":["import { NegativeActiveSubscribersError } from '../errors'\nimport {\n  createSingleRowRefProxy,\n  toExpression,\n} from '../query/builder/ref-proxy.js'\nimport { CollectionSubscription } from './subscription.js'\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport type { ChangeMessage, SubscribeChangesOptions } from '../types'\nimport type { CollectionLifecycleManager } from './lifecycle.js'\nimport type { CollectionSyncManager } from './sync.js'\nimport type { CollectionEventsManager } from './events.js'\nimport type { CollectionImpl } from './index.js'\n\nexport class CollectionChangesManager<\n  TOutput extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInput extends object = TOutput,\n> {\n  private lifecycle!: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n  private sync!: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n  private events!: CollectionEventsManager\n  private collection!: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n\n  public activeSubscribersCount = 0\n  public changeSubscriptions = new Set<CollectionSubscription>()\n  public batchedEvents: Array<ChangeMessage<TOutput, TKey>> = []\n  public shouldBatchEvents = false\n\n  /**\n   * Creates a new CollectionChangesManager instance\n   */\n  constructor() {}\n\n  public setDeps(deps: {\n    lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n    sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n    events: CollectionEventsManager\n    collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n  }) {\n    this.lifecycle = deps.lifecycle\n    this.sync = deps.sync\n    this.events = deps.events\n    this.collection = deps.collection\n  }\n\n  /**\n   * Emit an empty ready event to notify subscribers that the collection is ready\n   * This bypasses the normal empty array check in emitEvents\n   */\n  public emitEmptyReadyEvent(): void {\n    // Emit empty array directly to all subscribers\n    for (const subscription of this.changeSubscriptions) {\n      subscription.emitEvents([])\n    }\n  }\n\n  /**\n   * Emit events either immediately or batch them for later emission\n   */\n  public emitEvents(\n    changes: Array<ChangeMessage<TOutput, TKey>>,\n    forceEmit = false,\n  ): void {\n    // Skip batching for user actions (forceEmit=true) to keep UI responsive\n    if (this.shouldBatchEvents && !forceEmit) {\n      // Add events to the batch\n      this.batchedEvents.push(...changes)\n      return\n    }\n\n    // Either we're not batching, or we're forcing emission (user action or ending batch cycle)\n    let eventsToEmit = changes\n\n    if (forceEmit) {\n      // Force emit is used to end a batch (e.g. after a sync commit). Combine any\n      // buffered optimistic events with the final changes so subscribers see the\n      // whole picture, even if the sync diff is empty.\n      if (this.batchedEvents.length > 0) {\n        eventsToEmit = [...this.batchedEvents, ...changes]\n      }\n      this.batchedEvents = []\n      this.shouldBatchEvents = false\n    }\n\n    if (eventsToEmit.length === 0) {\n      return\n    }\n\n    // Emit to all listeners\n    for (const subscription of this.changeSubscriptions) {\n      subscription.emitEvents(eventsToEmit)\n    }\n  }\n\n  /**\n   * Subscribe to changes in the collection\n   */\n  public subscribeChanges(\n    callback: (changes: Array<ChangeMessage<TOutput>>) => void,\n    options: SubscribeChangesOptions<TOutput> = {},\n  ): CollectionSubscription {\n    // Start sync and track subscriber\n    this.addSubscriber()\n\n    // Compile where callback to whereExpression if provided\n    if (options.where && options.whereExpression) {\n      throw new Error(\n        `Cannot specify both 'where' and 'whereExpression' options. Use one or the other.`,\n      )\n    }\n\n    const { where, ...opts } = options\n    let whereExpression = opts.whereExpression\n    if (where) {\n      const proxy = createSingleRowRefProxy<TOutput>()\n      const result = where(proxy)\n      whereExpression = toExpression(result)\n    }\n\n    const subscription = new CollectionSubscription(this.collection, callback, {\n      ...opts,\n      whereExpression,\n      onUnsubscribe: () => {\n        this.removeSubscriber()\n        this.changeSubscriptions.delete(subscription)\n      },\n    })\n\n    // Register status listener BEFORE requesting snapshot to avoid race condition.\n    // This ensures the listener catches all status transitions, even if the\n    // loadSubset promise resolves synchronously or very quickly.\n    if (options.onStatusChange) {\n      subscription.on(`status:change`, options.onStatusChange)\n    }\n\n    if (options.includeInitialState) {\n      subscription.requestSnapshot({\n        trackLoadSubsetPromise: false,\n        orderBy: options.orderBy,\n        limit: options.limit,\n        onLoadSubsetResult: options.onLoadSubsetResult,\n      })\n    } else if (options.includeInitialState === false) {\n      // When explicitly set to false (not just undefined), mark all state as \"seen\"\n      // so that all future changes (including deletes) pass through unfiltered.\n      subscription.markAllStateAsSeen()\n    }\n\n    // Add to batched listeners\n    this.changeSubscriptions.add(subscription)\n\n    return subscription\n  }\n\n  /**\n   * Increment the active subscribers count and start sync if needed\n   */\n  private addSubscriber(): void {\n    const previousSubscriberCount = this.activeSubscribersCount\n    this.activeSubscribersCount++\n    this.lifecycle.cancelGCTimer()\n\n    // Start sync if collection was cleaned up\n    if (\n      this.lifecycle.status === `cleaned-up` ||\n      this.lifecycle.status === `idle`\n    ) {\n      this.sync.startSync()\n    }\n\n    this.events.emitSubscribersChange(\n      this.activeSubscribersCount,\n      previousSubscriberCount,\n    )\n  }\n\n  /**\n   * Decrement the active subscribers count and start GC timer if needed\n   */\n  private removeSubscriber(): void {\n    const previousSubscriberCount = this.activeSubscribersCount\n    this.activeSubscribersCount--\n\n    if (this.activeSubscribersCount === 0) {\n      this.lifecycle.startGCTimer()\n    } else if (this.activeSubscribersCount < 0) {\n      throw new NegativeActiveSubscribersError()\n    }\n\n    this.events.emitSubscribersChange(\n      this.activeSubscribersCount,\n      previousSubscriberCount,\n    )\n  }\n\n  /**\n   * Clean up the collection by stopping sync and clearing data\n   * This can be called manually or automatically by garbage collection\n   */\n  public cleanup(): void {\n    this.batchedEvents = []\n    this.shouldBatchEvents = false\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"changes.js","sources":["../../../src/collection/changes.ts"],"sourcesContent":["import { NegativeActiveSubscribersError } from '../errors'\nimport {\n  createSingleRowRefProxy,\n  toExpression,\n} from '../query/builder/ref-proxy.js'\nimport { CollectionSubscription } from './subscription.js'\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport type { ChangeMessage, SubscribeChangesOptions } from '../types'\nimport type { CollectionLifecycleManager } from './lifecycle.js'\nimport type { CollectionSyncManager } from './sync.js'\nimport type { CollectionEventsManager } from './events.js'\nimport type { CollectionImpl } from './index.js'\nimport type { CollectionStateManager } from './state.js'\nimport type { WithVirtualProps } from '../virtual-props.js'\n\nexport class CollectionChangesManager<\n  TOutput extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInput extends object = TOutput,\n> {\n  private lifecycle!: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n  private sync!: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n  private events!: CollectionEventsManager\n  private collection!: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n  private state!: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n\n  public activeSubscribersCount = 0\n  public changeSubscriptions = new Set<CollectionSubscription>()\n  public batchedEvents: Array<ChangeMessage<TOutput, TKey>> = []\n  public shouldBatchEvents = false\n\n  /**\n   * Creates a new CollectionChangesManager instance\n   */\n  constructor() {}\n\n  public setDeps(deps: {\n    lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n    sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n    events: CollectionEventsManager\n    collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n    state: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n  }) {\n    this.lifecycle = deps.lifecycle\n    this.sync = deps.sync\n    this.events = deps.events\n    this.collection = deps.collection\n    this.state = deps.state\n  }\n\n  /**\n   * Emit an empty ready event to notify subscribers that the collection is ready\n   * This bypasses the normal empty array check in emitEvents\n   */\n  public emitEmptyReadyEvent(): void {\n    // Emit empty array directly to all subscribers\n    for (const subscription of this.changeSubscriptions) {\n      subscription.emitEvents([])\n    }\n  }\n\n  /**\n   * Enriches a change message with virtual properties ($synced, $origin, $key, $collectionId).\n   * Uses the \"add-if-missing\" pattern to preserve virtual properties from upstream collections.\n   */\n  private enrichChangeWithVirtualProps(\n    change: ChangeMessage<TOutput, TKey>,\n  ): ChangeMessage<WithVirtualProps<TOutput, TKey>, TKey> {\n    return this.state.enrichChangeMessage(change)\n  }\n\n  /**\n   * Emit events either immediately or batch them for later emission\n   */\n  public emitEvents(\n    changes: Array<ChangeMessage<TOutput, TKey>>,\n    forceEmit = false,\n  ): void {\n    // Skip batching for user actions (forceEmit=true) to keep UI responsive\n    if (this.shouldBatchEvents && !forceEmit) {\n      // Add events to the batch\n      this.batchedEvents.push(...changes)\n      return\n    }\n\n    // Either we're not batching, or we're forcing emission (user action or ending batch cycle)\n    let rawEvents = changes\n\n    if (forceEmit) {\n      // Force emit is used to end a batch (e.g. after a sync commit). Combine any\n      // buffered optimistic events with the final changes so subscribers see the\n      // whole picture, even if the sync diff is empty.\n      if (this.batchedEvents.length > 0) {\n        rawEvents = [...this.batchedEvents, ...changes]\n      }\n      this.batchedEvents = []\n      this.shouldBatchEvents = false\n    }\n\n    if (rawEvents.length === 0) {\n      return\n    }\n\n    // Enrich all change messages with virtual properties\n    // This uses the \"add-if-missing\" pattern to preserve pass-through semantics\n    const enrichedEvents: Array<\n      ChangeMessage<WithVirtualProps<TOutput, TKey>, TKey>\n    > = rawEvents.map((change) => this.enrichChangeWithVirtualProps(change))\n\n    // Emit to all listeners\n    for (const subscription of this.changeSubscriptions) {\n      subscription.emitEvents(enrichedEvents)\n    }\n  }\n\n  /**\n   * Subscribe to changes in the collection\n   */\n  public subscribeChanges(\n    callback: (\n      changes: Array<ChangeMessage<WithVirtualProps<TOutput, TKey>>>,\n    ) => void,\n    options: SubscribeChangesOptions<TOutput, TKey> = {},\n  ): CollectionSubscription {\n    // Start sync and track subscriber\n    this.addSubscriber()\n\n    // Compile where callback to whereExpression if provided\n    if (options.where && options.whereExpression) {\n      throw new Error(\n        `Cannot specify both 'where' and 'whereExpression' options. Use one or the other.`,\n      )\n    }\n\n    const { where, ...opts } = options\n    let whereExpression = opts.whereExpression\n    if (where) {\n      const proxy = createSingleRowRefProxy<WithVirtualProps<TOutput, TKey>>()\n      const result = where(proxy)\n      whereExpression = toExpression(result)\n    }\n\n    const subscription = new CollectionSubscription(this.collection, callback, {\n      ...opts,\n      whereExpression,\n      onUnsubscribe: () => {\n        this.removeSubscriber()\n        this.changeSubscriptions.delete(subscription)\n      },\n    })\n\n    // Register status listener BEFORE requesting snapshot to avoid race condition.\n    // This ensures the listener catches all status transitions, even if the\n    // loadSubset promise resolves synchronously or very quickly.\n    if (options.onStatusChange) {\n      subscription.on(`status:change`, options.onStatusChange)\n    }\n\n    if (options.includeInitialState) {\n      subscription.requestSnapshot({\n        trackLoadSubsetPromise: false,\n        orderBy: options.orderBy,\n        limit: options.limit,\n        onLoadSubsetResult: options.onLoadSubsetResult,\n      })\n    } else if (options.includeInitialState === false) {\n      // When explicitly set to false (not just undefined), mark all state as \"seen\"\n      // so that all future changes (including deletes) pass through unfiltered.\n      subscription.markAllStateAsSeen()\n    }\n\n    // Add to batched listeners\n    this.changeSubscriptions.add(subscription)\n\n    return subscription\n  }\n\n  /**\n   * Increment the active subscribers count and start sync if needed\n   */\n  private addSubscriber(): void {\n    const previousSubscriberCount = this.activeSubscribersCount\n    this.activeSubscribersCount++\n    this.lifecycle.cancelGCTimer()\n\n    // Start sync if collection was cleaned up\n    if (\n      this.lifecycle.status === `cleaned-up` ||\n      this.lifecycle.status === `idle`\n    ) {\n      this.sync.startSync()\n    }\n\n    this.events.emitSubscribersChange(\n      this.activeSubscribersCount,\n      previousSubscriberCount,\n    )\n  }\n\n  /**\n   * Decrement the active subscribers count and start GC timer if needed\n   */\n  private removeSubscriber(): void {\n    const previousSubscriberCount = this.activeSubscribersCount\n    this.activeSubscribersCount--\n\n    if (this.activeSubscribersCount === 0) {\n      this.lifecycle.startGCTimer()\n    } else if (this.activeSubscribersCount < 0) {\n      throw new NegativeActiveSubscribersError()\n    }\n\n    this.events.emitSubscribersChange(\n      this.activeSubscribersCount,\n      previousSubscriberCount,\n    )\n  }\n\n  /**\n   * Clean up the collection by stopping sync and clearing data\n   * This can be called manually or automatically by garbage collection\n   */\n  public cleanup(): void {\n    this.batchedEvents = []\n    this.shouldBatchEvents = false\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/collection/cleanup-queue.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Batches many GC registrations behind a single shared timeout.
+ */
+export declare class CleanupQueue {
+    private static instance;
+    private tasks;
+    private timeoutId;
+    private microtaskScheduled;
+    private constructor();
+    static getInstance(): CleanupQueue;
+    /**
+     * Queues a cleanup task and defers timeout selection to a microtask so
+     * multiple synchronous registrations can share one root timer.
+     */
+    schedule(key: unknown, gcTime: number, callback: () => void): void;
+    cancel(key: unknown): void;
+    /**
+     * Keeps only one active timeout: whichever task is due next.
+     */
+    private updateTimeout;
+    /**
+     * Runs every task whose deadline has passed, then schedules the next wakeup
+     * if there is still pending work.
+     */
+    private process;
+    /**
+     * Resets the singleton instance for tests.
+     */
+    static resetInstance(): void;
+}