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

localOnlyCollectionOptions.md

228 lines6.2 KB

1---
2id: localOnlyCollectionOptions
3title: localOnlyCollectionOptions
4---
5​
6## Call Signature
7​
8```ts
9function localOnlyCollectionOptions<T, TKey>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, LocalOnlyCollectionUtils> & object & object;
10```
11​
12Defined in: [packages/db/src/local-only.ts:151](https://github.com/TanStack/db/blob/main/packages/db/src/local-only.ts#L151)
13​
14Creates Local-only collection options for use with a standard Collection
15​
16This is an in-memory collection that doesn't sync with external sources but uses a loopback sync config
17that immediately "syncs" all optimistic changes to the collection, making them permanent.
18Perfect for local-only data that doesn't need persistence or external synchronization.
19​
20**Using with Manual Transactions:**
21​
22For manual transactions, you must call `utils.acceptMutations()` in your transaction's `mutationFn`
23to persist changes made during `tx.mutate()`. This is necessary because local-only collections
24don't participate in the standard mutation handler flow for manual transactions.
25​
26### Type Parameters
27​
28#### T
29​
30`T` *extends* `StandardSchemaV1`\<`unknown`, `unknown`\>
31​
32The schema type if a schema is provided, otherwise the type of items in the collection
33​
34#### TKey
35​
36`TKey` *extends* `string` \| `number` = `string` \| `number`
37​
38The type of the key returned by getKey
39​
40### Parameters
41​
42#### config
43​
44[`LocalOnlyCollectionConfig`](../interfaces/LocalOnlyCollectionConfig.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `T`, `TKey`\> & `object`
45​
46Configuration options for the Local-only collection
47​
48### Returns
49​
50[`CollectionConfig`](../interfaces/CollectionConfig.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `T`, [`LocalOnlyCollectionUtils`](../interfaces/LocalOnlyCollectionUtils.md)\> & `object` & `object`
51​
52Collection options with utilities including acceptMutations
53​
54### Examples
55​
56```ts
57// Basic local-only collection
58const collection = createCollection(
59 localOnlyCollectionOptions({
60 getKey: (item) => item.id,
61 })
63```
64​
65```ts
66// Local-only collection with initial data
67const collection = createCollection(
68 localOnlyCollectionOptions({
69 getKey: (item) => item.id,
70 initialData: [
71 { id: 1, name: 'Item 1' },
72 { id: 2, name: 'Item 2' },
73 ],
74 })
76```
77​
78```ts
79// Local-only collection with mutation handlers
80const collection = createCollection(
81 localOnlyCollectionOptions({
82 getKey: (item) => item.id,
83 onInsert: async ({ transaction }) => {
84 console.log('Item inserted:', transaction.mutations[0].modified)
85 // Custom logic after insert
86 },
87 })
89```
90​
91```ts
92// Using with manual transactions
93const localData = createCollection(
94 localOnlyCollectionOptions({
95 getKey: (item) => item.id,
96 })
98​
99const tx = createTransaction({
100 mutationFn: async ({ transaction }) => {
101 // Use local data in API call
102 const localMutations = transaction.mutations.filter(m => m.collection === localData)
103 await api.save({ metadata: localMutations[0]?.modified })
104​
105 // Persist local-only mutations after API success
106 localData.utils.acceptMutations(transaction)
107 }
108})
109​
110tx.mutate(() => {
111 localData.insert({ id: 1, data: 'metadata' })
112 apiCollection.insert({ id: 2, data: 'main data' })
113})
114​
115await tx.commit()
116```
117​
118## Call Signature
119​
120```ts
121function localOnlyCollectionOptions<T, TKey>(config): CollectionConfig<T, TKey, never, LocalOnlyCollectionUtils> & object & object;
122```
123​
124Defined in: [packages/db/src/local-only.ts:164](https://github.com/TanStack/db/blob/main/packages/db/src/local-only.ts#L164)
125​
126Creates Local-only collection options for use with a standard Collection
127​
128This is an in-memory collection that doesn't sync with external sources but uses a loopback sync config
129that immediately "syncs" all optimistic changes to the collection, making them permanent.
130Perfect for local-only data that doesn't need persistence or external synchronization.
131​
132**Using with Manual Transactions:**
133​
134For manual transactions, you must call `utils.acceptMutations()` in your transaction's `mutationFn`
135to persist changes made during `tx.mutate()`. This is necessary because local-only collections
136don't participate in the standard mutation handler flow for manual transactions.
137​
138### Type Parameters
139​
140#### T
141​
142`T` *extends* `object`
143​
144The schema type if a schema is provided, otherwise the type of items in the collection
145​
146#### TKey
147​
148`TKey` *extends* `string` \| `number` = `string` \| `number`
149​
150The type of the key returned by getKey
151​
152### Parameters
153​
154#### config
155​
156[`LocalOnlyCollectionConfig`](../interfaces/LocalOnlyCollectionConfig.md)\<`T`, `never`, `TKey`\> & `object`
157​
158Configuration options for the Local-only collection
159​
160### Returns
161​
162[`CollectionConfig`](../interfaces/CollectionConfig.md)\<`T`, `TKey`, `never`, [`LocalOnlyCollectionUtils`](../interfaces/LocalOnlyCollectionUtils.md)\> & `object` & `object`
163​
164Collection options with utilities including acceptMutations
165​
166### Examples
167​
168```ts
169// Basic local-only collection
170const collection = createCollection(
171 localOnlyCollectionOptions({
172 getKey: (item) => item.id,
173 })
175```
176​
177```ts
178// Local-only collection with initial data
179const collection = createCollection(
180 localOnlyCollectionOptions({
181 getKey: (item) => item.id,
182 initialData: [
183 { id: 1, name: 'Item 1' },
184 { id: 2, name: 'Item 2' },
185 ],
186 })
188```
189​
190```ts
191// Local-only collection with mutation handlers
192const collection = createCollection(
193 localOnlyCollectionOptions({
194 getKey: (item) => item.id,
195 onInsert: async ({ transaction }) => {
196 console.log('Item inserted:', transaction.mutations[0].modified)
197 // Custom logic after insert
198 },
199 })
201```
202​
203```ts
204// Using with manual transactions
205const localData = createCollection(
206 localOnlyCollectionOptions({
207 getKey: (item) => item.id,
208 })
210​
211const tx = createTransaction({
212 mutationFn: async ({ transaction }) => {
213 // Use local data in API call
214 const localMutations = transaction.mutations.filter(m => m.collection === localData)
215 await api.save({ metadata: localMutations[0]?.modified })
216​
217 // Persist local-only mutations after API success
218 localData.utils.acceptMutations(transaction)
219 }
220})
221​
222tx.mutate(() => {
223 localData.insert({ id: 1, data: 'metadata' })
224 apiCollection.insert({ id: 2, data: 'main data' })
225})
226​
227await tx.commit()
228```