Open History to see the last commit
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 })
62)
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 })
75)
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 })
88)
89```
90
91```ts
92// Using with manual transactions
93const localData = createCollection(
94 localOnlyCollectionOptions({
95 getKey: (item) => item.id,
96 })
97)
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 })
174)
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 })
187)
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 })
200)
201```
202
203```ts
204// Using with manual transactions
205const localData = createCollection(
206 localOnlyCollectionOptions({
207 getKey: (item) => item.id,
208 })
209)
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```