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

SubscribeChangesOptions.md

212 lines3.9 KB

1---
2id: SubscribeChangesOptions
3title: SubscribeChangesOptions
4---
5​
6Defined in: [packages/db/src/types.ts:1072](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L1072)
7​
8Options for subscribing to collection changes
9​
10## Type Parameters
11​
12### T
13​
14`T` *extends* `object` = `Record`\<`string`, `unknown`\>
15​
16### TKey
17​
18`TKey` *extends* `string` \| `number` = `string` \| `number`
19​
20## Properties
21​
22### includeInitialState?
23​
24```ts
25optional includeInitialState: boolean;
26```
27​
28Defined in: [packages/db/src/types.ts:1077](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L1077)
29​
30Whether to include the current state as initial changes
31​
32***
33​
34### limit?
35​
36```ts
37optional limit: number;
38```
39​
40Defined in: [packages/db/src/types.ts:1110](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L1110)
41​
42**`Internal`**
43​
44Optional limit to include in loadSubset for query-specific cache keys.
45​
46***
47​
48### onLoadSubsetError()?
49​
50```ts
51optional onLoadSubsetError: (event) => void;
52```
53​
54Defined in: [packages/db/src/types.ts:1118](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L1118)
55​
56**`Internal`**
57​
58Receives subset-load failures scoped to this subscription.
59​
60#### Parameters
61​
62##### event
63​
64[`SubscriptionLoadSubsetErrorEvent`](SubscriptionLoadSubsetErrorEvent.md)
65​
66#### Returns
67​
68`void`
69​
70***
71​
72### onLoadSubsetResult()?
73​
74```ts
75optional onLoadSubsetResult: (result) => void;
76```
77​
78Defined in: [packages/db/src/types.ts:1116](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L1116)
79​
80**`Internal`**
81​
82Callback that receives the loadSubset result (Promise or true) from requestSnapshot.
83Allows the caller to directly track the loading promise for isReady status.
84​
85#### Parameters
86​
87##### result
88​
89[`LoadSubsetRequestResult`](../type-aliases/LoadSubsetRequestResult.md)
90​
91#### Returns
92​
93`void`
94​
95***
96​
97### onStatusChange()?
98​
99```ts
100optional onStatusChange: (event) => void;
101```
102​
103Defined in: [packages/db/src/types.ts:1100](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L1100)
104​
105**`Internal`**
106​
107Listener for subscription status changes.
108Registered BEFORE any snapshot is requested, ensuring no status transitions are missed.
109​
110#### Parameters
111​
112##### event
113​
114[`SubscriptionStatusChangeEvent`](SubscriptionStatusChangeEvent.md)
115​
116#### Returns
117​
118`void`
119​
120***
121​
122### orderBy?
123​
124```ts
125optional orderBy: OrderBy;
126```
127​
128Defined in: [packages/db/src/types.ts:1105](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L1105)
129​
130**`Internal`**
131​
132Optional orderBy to include in loadSubset for query-specific cache keys.
133​
134***
135​
136### truncateReplayPublication?
137​
138```ts
139optional truncateReplayPublication: object;
140```
141​
142Defined in: [packages/db/src/types.ts:1120](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L1120)
143​
144**`Internal`**
145​
146Lets a live-query graph retain its last publication during replay.
147​
148#### start()
149​
150```ts
151readonly start: () => void;
152```
153​
154##### Returns
155​
156`void`
157​
158#### succeed()
159​
160```ts
161readonly succeed: () => void;
162```
163​
164##### Returns
165​
166`void`
167​
168***
169​
170### where()?
171​
172```ts
173optional where: (row) => any;
174```
175​
176Defined in: [packages/db/src/types.ts:1092](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L1092)
177​
178Callback function for filtering changes using a row proxy.
179The callback receives a proxy object that records property access,
180allowing you to use query builder functions like `eq`, `gt`, etc.
181​
182#### Parameters
183​
184##### row
185​
186`SingleRowRefProxy`\<[`WithVirtualProps`](../type-aliases/WithVirtualProps.md)\<`T`, `TKey`\>, `TKey`, `true`\>
187​
188#### Returns
189​
190`any`
191​
192#### Example
193​
194```ts
195import { eq } from "@tanstack/db"
196​
197collection.subscribeChanges(callback, {
198 where: (row) => eq(row.status, "active")
199})
200```
201​
202***
203​
204### whereExpression?
205​
206```ts
207optional whereExpression: BasicExpression<boolean>;
208```
209​
210Defined in: [packages/db/src/types.ts:1094](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L1094)
211​
212Pre-compiled expression for filtering changes