VirtualRowProps

Defined in: packages/db/src/virtual-props.ts:78

Virtual properties recognized on TanStack DB rows.

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)

Structured whole-row selections and spreads retain source metadata. A functional selection retains it only when returning a source row directly. New functional objects and other projections receive the output Collection's metadata. Selected virtual names cannot change that attribution.

Examples#

// Accessing virtual properties on a row
const user = collection.get('user-1')
if (!user.$hasPendingWrites) {
  console.log('No pending local optimistic writes for this row')
}
if (user.$origin === 'local') {
  console.log('Row has local attribution')
}

// Using virtual properties in queries
const ordersWithoutLocalWrites = createLiveQueryCollection({
  query: (q) => q
    .from({ order: orders })
    .where(({ order }) => eq(order.$hasPendingWrites, false))
})

Type Parameters#

TKey#

TKey extends string | number = string | number

The type of the row's key (string or number)

Properties#

$collectionId#

readonly $collectionId: string;

Defined in: packages/db/src/virtual-props.ts:116

The ID of the source collection this row originated from.

In joins, this can help identify which collection each row came from. Whole-row live queries preserve the upstream Collection's ID. Projected row roots otherwise use the live-query Collection's ID.

$hasPendingWrites#

readonly $hasPendingWrites: boolean;

Defined in: packages/db/src/virtual-props.ts:87

Whether this row currently has pending local optimistic writes.

This describes the row's local optimistic state, not backend upload or acknowledgement. It is always false for local-only collections.

$key#

readonly $key: TKey;

Defined in: packages/db/src/virtual-props.ts:107

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.

$origin#

readonly $origin: VirtualOrigin;

Defined in: packages/db/src/virtual-props.ts:99

Collection attribution for this row's current value. 'local' covers optimistic rows and attributed source writes; 'remote' covers source writes without local attribution. See VirtualOrigin for the key-and-timing rules, including truncate and overlapping mutations.

For local-only collections, this is always 'local'. Whole-row live queries preserve source attribution. Projected row roots otherwise use the live-query Collection's attribution.