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

localOnlyCollectionOptions.md

230 lines6.2 KB

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