Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

VirtualRowProps.md

140 lines3.9 KB

1---
2id: VirtualRowProps
3title: VirtualRowProps
4---
5​
6Defined in: [packages/db/src/virtual-props.ts:60](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L60)
7​
8Virtual properties recognized on TanStack DB rows. The new
9`$hasPendingWrites` field is optional here so legacy four-field rows accepted
10by `hasVirtualProps` remain assignable. Rows returned by collections use
11`WithVirtualProps`, which requires it.
12​
13These properties are:
14- Computed (not stored in the data model)
15- Read-only (cannot be mutated directly)
16- Available in queries (WHERE, ORDER BY, SELECT)
17- Included when spreading rows (`...user`)
18​
19## Examples
20​
21```typescript
22// Accessing virtual properties on a row
23const user = collection.get('user-1')
24if (!user.$hasPendingWrites) {
25 console.log('No pending local optimistic writes for this row')
27if (user.$origin === 'local') {
28 console.log('Created/modified locally')
30```
31​
32```typescript
33// Using virtual properties in queries
34const ordersWithoutLocalWrites = createLiveQueryCollection({
35 query: (q) => q
36 .from({ order: orders })
37 .where(({ order }) => eq(order.$hasPendingWrites, false))
38})
39```
40​
41## Type Parameters
42​
43### TKey
44​
45`TKey` *extends* `string` \| `number` = `string` \| `number`
46​
47The type of the row's key (string or number)
48​
49## Properties
50​
51### $collectionId
52​
53```ts
54readonly $collectionId: string;
55```
56​
57Defined in: [packages/db/src/virtual-props.ts:117](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L117)
58​
59The ID of the source collection this row originated from.
60​
61In joins, this can help identify which collection each row came from.
62For live query collections, this is the ID of the upstream collection.
63​
64***
65​
66### $hasPendingWrites?
67​
68```ts
69readonly optional $hasPendingWrites: boolean;
70```
71​
72Defined in: [packages/db/src/virtual-props.ts:71](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L71)
73​
74Whether this row currently has pending local optimistic writes.
75​
76This describes the row's local optimistic state, not backend upload or
77acknowledgement. It is always `false` for local-only collections. It is
78optional only for compatibility with legacy rows; collection-published
79rows always provide it.
80​
81***
82​
83### $key
84​
85```ts
86readonly $key: TKey;
87```
88​
89Defined in: [packages/db/src/virtual-props.ts:109](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L109)
90​
91The row's key (primary identifier).
92​
93This is the same value returned by `collection.config.getKey(row)`.
94Useful when you need the key in projections or computations.
95​
96***
97​
98### $origin
99​
100```ts
101readonly $origin: VirtualOrigin;
102```
103​
104Defined in: [packages/db/src/virtual-props.ts:101](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L101)
105​
106Origin of the last confirmed change to this row, from the current client's perspective.
107​
108- `'local'`: The change originated from this client
109- `'remote'`: The change was received via sync
110​
111For local-only collections, this is always `'local'`.
112For live query collections, this is passed through from the source collection.
113​
114***
115​
116### ~~$synced~~
117​
118```ts
119readonly $synced: boolean;
120```
121​
122Defined in: [packages/db/src/virtual-props.ts:90](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L90)
123​
124Whether this row currently has no pending local optimistic writes.
125​
126- `true`: No pending local optimistic mutation currently affects this row
127- `false`: One or more pending local optimistic mutations currently affect this row
128​
129This is local mutation status. It does not prove that a backend has uploaded,
130confirmed, or read back the row. If you need backend-confirmed status, keep
131your mutation function pending until that backend observation has happened,
132or expose adapter-specific status.
133​
134For local-only collections (no sync), this is always `true`.
135For live query collections, this is passed through from the source collection.
136​
137#### Deprecated
138​
139Use `!row.$hasPendingWrites` instead. This alias will be
140removed in the 1.0 RC.