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

VirtualRowProps.md

117 lines3.1 KB

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