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

VirtualRowProps.md

112 lines2.8 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('Confirmed by backend')
26if (user.$origin === 'local') {
27 console.log('Created/modified locally')
29```
30​
31```typescript
32// Using virtual properties in queries
33const confirmedOrders = 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:96](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L96)
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:88](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L88)
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:80](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L80)
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:69](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L69)
105​
106Whether this row reflects confirmed state from the backend.
107​
108- `true`: Row is confirmed by the backend (no pending optimistic mutations)
109- `false`: Row has pending optimistic mutations that haven't been confirmed
110​
111For local-only collections (no sync), this is always `true`.
112For live query collections, this is passed through from the source collection.