TanStack
diff --git a/‎.changeset/shiny-planes-laugh.md‎
Lines changed: 6 additions & 0 deletions b/‎.changeset/shiny-planes-laugh.md‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎docs/guides/live-queries.md‎
Lines changed: 12 additions & 0 deletions b/‎docs/guides/live-queries.md‎
Lines changed: 12 additions & 0 deletions
diff --git a/‎packages/angular-db/tests/inject-live-query.test-d.ts‎
Lines changed: 8 additions & 10 deletions b/‎packages/angular-db/tests/inject-live-query.test-d.ts‎
Lines changed: 8 additions & 10 deletions
diff --git a/‎packages/db/src/collection/change-events.ts‎
Lines changed: 13 additions & 9 deletions b/‎packages/db/src/collection/change-events.ts‎
Lines changed: 13 additions & 9 deletions
diff --git a/‎packages/db/src/collection/changes.ts‎
Lines changed: 30 additions & 7 deletions b/‎packages/db/src/collection/changes.ts‎
Lines changed: 30 additions & 7 deletions
@@ -0,0 +1,6 @@
+---
+'@tanstack/db': patch
+---
+
+Implement virtual properties end-to-end, including live query behavior and
+typing support for virtual metadata on rows.
@@ -29,6 +29,18 @@ const activeUsers = createCollection(liveQueryCollectionOptions({
 
 The result types are automatically inferred from your query structure, providing full TypeScript support. When you use a `select` clause, the result type matches your projection. Without `select`, you get the full schema with proper join optionality.
 
+## Virtual properties
+
+Live query results include computed, read-only virtual properties on every row:
+
+- `$synced`: `true` when the row is confirmed by sync; `false` when it is still optimistic.
+- `$origin`: `"local"` if the last confirmed change came from this client, otherwise `"remote"`.
+- `$key`: the row key for the result.
+- `$collectionId`: the source collection ID.
+
+These props can be used in `where`, `select`, and `orderBy` clauses. They are added to
+query outputs automatically and should not be persisted back to storage.
+
 ## Table of Contents
 
 - [Creating Live Query Collections](#creating-live-query-collections)
 
@@ -7,6 +7,7 @@ import {
   liveQueryCollectionOptions,
 } from '../../db/src/query/index'
 import { injectLiveQuery } from '../src/index'
+import type { OutputWithVirtual } from '../../db/tests/utils'
 import type { SingleResult } from '../../db/src/types'
 
 type Person = {
@@ -35,8 +36,7 @@ describe(`injectLiveQuery type assertions`, () => {
         .findOne(),
     )
 
-    // findOne returns a single result or undefined
-    expectTypeOf(data()).toEqualTypeOf<Person | undefined>()
+    expectTypeOf(data()).toMatchTypeOf<OutputWithVirtual<Person> | undefined>()
   })
 
   it(`should type findOne config object to return a single row`, () => {
@@ -57,8 +57,7 @@ describe(`injectLiveQuery type assertions`, () => {
           .findOne(),
     })
 
-    // findOne returns a single result or undefined
-    expectTypeOf(data()).toEqualTypeOf<Person | undefined>()
+    expectTypeOf(data()).toMatchTypeOf<OutputWithVirtual<Person> | undefined>()
   })
 
   it(`should type findOne collection using liveQueryCollectionOptions to return a single row`, () => {
@@ -84,8 +83,7 @@ describe(`injectLiveQuery type assertions`, () => {
 
     const { data } = injectLiveQuery(liveQueryCollection)
 
-    // findOne returns a single result or undefined
-    expectTypeOf(data()).toEqualTypeOf<Person | undefined>()
+    expectTypeOf(data()).toMatchTypeOf<OutputWithVirtual<Person> | undefined>()
   })
 
   it(`should type findOne collection using createLiveQueryCollection to return a single row`, () => {
@@ -109,8 +107,7 @@ describe(`injectLiveQuery type assertions`, () => {
 
     const { data } = injectLiveQuery(liveQueryCollection)
 
-    // findOne returns a single result or undefined
-    expectTypeOf(data()).toEqualTypeOf<Person | undefined>()
+    expectTypeOf(data()).toMatchTypeOf<OutputWithVirtual<Person> | undefined>()
   })
 
   it(`should type regular query to return an array`, () => {
@@ -132,7 +129,8 @@ describe(`injectLiveQuery type assertions`, () => {
         })),
     )
 
-    // Regular queries should return an array
-    expectTypeOf(data()).toEqualTypeOf<Array<{ id: string; name: string }>>()
+    expectTypeOf(data()).toMatchTypeOf<
+      Array<OutputWithVirtual<{ id: string; name: string }>>
+    >()
   })
 })
@@ -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!)
 
 
@@ -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,35 +85,43 @@ 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)
     }
   }
 
   /**
    * 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)
     }