Open History to see the last commit
1---
2id: createCollection
3title: createCollection
4---
5
6## Call Signature
7
8```ts
9function createCollection<T, TKey, TUtils>(options): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> & NonSingleResult;
10```
11
12Defined in: [packages/db/src/collection/index.ts:234](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L234)
13
14Creates a new Collection instance with the given configuration
15
16### Type Parameters
17
18#### T
19
20`T` *extends* `StandardSchemaV1`\<`unknown`, `unknown`\>
21
22The schema type if a schema is provided, otherwise the type of items in the collection
23
24#### TKey
25
26`TKey` *extends* `string` \| `number`
27
28The type of the key for the collection
29
30#### TUtils
31
32`TUtils` *extends* [`UtilsRecord`](../type-aliases/UtilsRecord.md)
33
34The utilities record type
35
36### Parameters
37
38#### options
39
40`Omit`\<[`CollectionConfig`](../interfaces/CollectionConfig.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `T`, `TUtils`\>, `"utils"`\> & `object` & [`NonSingleResult`](../type-aliases/NonSingleResult.md)
41
42Collection options with optional utilities
43
44### Returns
45
46[`Collection`](../interfaces/Collection.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `TUtils`, `T`, [`InferSchemaInput`](../type-aliases/InferSchemaInput.md)\<`T`\>\> & [`NonSingleResult`](../type-aliases/NonSingleResult.md)
47
48A new Collection with utilities exposed both at top level and under .utils
49
50### Examples
51
52```ts
53// Pattern 1: With operation handlers (direct collection calls)
54const todos = createCollection({
55 id: "todos",
56 getKey: (todo) => todo.id,
57 schema,
58 onInsert: async ({ transaction, collection }) => {
59 // Send to API
60 await api.createTodo(transaction.mutations[0].modified)
61 },
62 onUpdate: async ({ transaction, collection }) => {
63 await api.updateTodo(transaction.mutations[0].modified)
64 },
65 onDelete: async ({ transaction, collection }) => {
66 await api.deleteTodo(transaction.mutations[0].key)
67 },
68 sync: { sync: () => {} }
69})
70
71// Direct usage (handlers manage transactions)
72const tx = todos.insert({ id: "1", text: "Buy milk", completed: false })
73await tx.when('settled')
74```
75
76```ts
77// Pattern 2: Manual transaction management
78const todos = createCollection({
79 getKey: (todo) => todo.id,
80 schema: todoSchema,
81 sync: { sync: () => {} }
82})
83
84// Explicit transaction usage
85const tx = createTransaction({
86 mutationFn: async ({ transaction }) => {
87 // Handle all mutations in transaction
88 await api.saveChanges(transaction.mutations)
89 }
90})
91
92tx.mutate(() => {
93 todos.insert({ id: "1", text: "Buy milk" })
94 todos.update("2", draft => { draft.completed = true })
95})
96
97await tx.when('settled')
98```
99
100```ts
101// Using schema for type inference (preferred as it also gives you client side validation)
102const todoSchema = z.object({
103 id: z.string(),
104 title: z.string(),
105 completed: z.boolean()
106})
107
108const todos = createCollection({
109 schema: todoSchema,
110 getKey: (todo) => todo.id,
111 sync: { sync: () => {} }
112})
113```
114
115## Call Signature
116
117```ts
118function createCollection<T, TKey, TUtils>(options): Collection<InferSchemaOutput<T>, TKey, Exclude<TUtils, undefined>, T, InferSchemaInput<T>> & NonSingleResult;
119```
120
121Defined in: [packages/db/src/collection/index.ts:251](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L251)
122
123Creates a new Collection instance with the given configuration
124
125### Type Parameters
126
127#### T
128
129`T` *extends* `StandardSchemaV1`\<`unknown`, `unknown`\>
130
131The schema type if a schema is provided, otherwise the type of items in the collection
132
133#### TKey
134
135`TKey` *extends* `string` \| `number`
136
137The type of the key for the collection
138
139#### TUtils
140
141`TUtils` *extends* [`UtilsRecord`](../type-aliases/UtilsRecord.md)
142
143The utilities record type
144
145### Parameters
146
147#### options
148
149[`CollectionConfig`](../interfaces/CollectionConfig.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `T`, `TUtils`\> & `object` & [`NonSingleResult`](../type-aliases/NonSingleResult.md)
150
151Collection options with optional utilities
152
153### Returns
154
155[`Collection`](../interfaces/Collection.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `Exclude`\<`TUtils`, `undefined`\>, `T`, [`InferSchemaInput`](../type-aliases/InferSchemaInput.md)\<`T`\>\> & [`NonSingleResult`](../type-aliases/NonSingleResult.md)
156
157A new Collection with utilities exposed both at top level and under .utils
158
159### Examples
160
161```ts
162// Pattern 1: With operation handlers (direct collection calls)
163const todos = createCollection({
164 id: "todos",
165 getKey: (todo) => todo.id,
166 schema,
167 onInsert: async ({ transaction, collection }) => {
168 // Send to API
169 await api.createTodo(transaction.mutations[0].modified)
170 },
171 onUpdate: async ({ transaction, collection }) => {
172 await api.updateTodo(transaction.mutations[0].modified)
173 },
174 onDelete: async ({ transaction, collection }) => {
175 await api.deleteTodo(transaction.mutations[0].key)
176 },
177 sync: { sync: () => {} }
178})
179
180// Direct usage (handlers manage transactions)
181const tx = todos.insert({ id: "1", text: "Buy milk", completed: false })
182await tx.when('settled')
183```
184
185```ts
186// Pattern 2: Manual transaction management
187const todos = createCollection({
188 getKey: (todo) => todo.id,
189 schema: todoSchema,
190 sync: { sync: () => {} }
191})
192
193// Explicit transaction usage
194const tx = createTransaction({
195 mutationFn: async ({ transaction }) => {
196 // Handle all mutations in transaction
197 await api.saveChanges(transaction.mutations)
198 }
199})
200
201tx.mutate(() => {
202 todos.insert({ id: "1", text: "Buy milk" })
203 todos.update("2", draft => { draft.completed = true })
204})
205
206await tx.when('settled')
207```
208
209```ts
210// Using schema for type inference (preferred as it also gives you client side validation)
211const todoSchema = z.object({
212 id: z.string(),
213 title: z.string(),
214 completed: z.boolean()
215})
216
217const todos = createCollection({
218 schema: todoSchema,
219 getKey: (todo) => todo.id,
220 sync: { sync: () => {} }
221})
222```
223
224## Call Signature
225
226```ts
227function createCollection<T, TKey, TUtils>(options): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> & SingleResult;
228```
229
230Defined in: [packages/db/src/collection/index.ts:269](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L269)
231
232Creates a new Collection instance with the given configuration
233
234### Type Parameters
235
236#### T
237
238`T` *extends* `StandardSchemaV1`\<`unknown`, `unknown`\>
239
240The schema type if a schema is provided, otherwise the type of items in the collection
241
242#### TKey
243
244`TKey` *extends* `string` \| `number`
245
246The type of the key for the collection
247
248#### TUtils
249
250`TUtils` *extends* [`UtilsRecord`](../type-aliases/UtilsRecord.md)
251
252The utilities record type
253
254### Parameters
255
256#### options
257
258`Omit`\<[`CollectionConfig`](../interfaces/CollectionConfig.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `T`, `TUtils`\>, `"utils"`\> & `object` & [`SingleResult`](../type-aliases/SingleResult.md)
259
260Collection options with optional utilities
261
262### Returns
263
264[`Collection`](../interfaces/Collection.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `TUtils`, `T`, [`InferSchemaInput`](../type-aliases/InferSchemaInput.md)\<`T`\>\> & [`SingleResult`](../type-aliases/SingleResult.md)
265
266A new Collection with utilities exposed both at top level and under .utils
267
268### Examples
269
270```ts
271// Pattern 1: With operation handlers (direct collection calls)
272const todos = createCollection({
273 id: "todos",
274 getKey: (todo) => todo.id,
275 schema,
276 onInsert: async ({ transaction, collection }) => {
277 // Send to API
278 await api.createTodo(transaction.mutations[0].modified)
279 },
280 onUpdate: async ({ transaction, collection }) => {
281 await api.updateTodo(transaction.mutations[0].modified)
282 },
283 onDelete: async ({ transaction, collection }) => {
284 await api.deleteTodo(transaction.mutations[0].key)
285 },
286 sync: { sync: () => {} }
287})
288
289// Direct usage (handlers manage transactions)
290const tx = todos.insert({ id: "1", text: "Buy milk", completed: false })
291await tx.when('settled')
292```
293
294```ts
295// Pattern 2: Manual transaction management
296const todos = createCollection({
297 getKey: (todo) => todo.id,
298 schema: todoSchema,
299 sync: { sync: () => {} }
300})
301
302// Explicit transaction usage
303const tx = createTransaction({
304 mutationFn: async ({ transaction }) => {
305 // Handle all mutations in transaction
306 await api.saveChanges(transaction.mutations)
307 }
308})
309
310tx.mutate(() => {
311 todos.insert({ id: "1", text: "Buy milk" })
312 todos.update("2", draft => { draft.completed = true })
313})
314
315await tx.when('settled')
316```
317
318```ts
319// Using schema for type inference (preferred as it also gives you client side validation)
320const todoSchema = z.object({
321 id: z.string(),
322 title: z.string(),
323 completed: z.boolean()
324})
325
326const todos = createCollection({
327 schema: todoSchema,
328 getKey: (todo) => todo.id,
329 sync: { sync: () => {} }
330})
331```
332
333## Call Signature
334
335```ts
336function createCollection<T, TKey, TUtils>(options): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> & SingleResult;
337```
338
339Defined in: [packages/db/src/collection/index.ts:285](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L285)
340
341Creates a new Collection instance with the given configuration
342
343### Type Parameters
344
345#### T
346
347`T` *extends* `StandardSchemaV1`\<`unknown`, `unknown`\>
348
349The schema type if a schema is provided, otherwise the type of items in the collection
350
351#### TKey
352
353`TKey` *extends* `string` \| `number`
354
355The type of the key for the collection
356
357#### TUtils
358
359`TUtils` *extends* [`UtilsRecord`](../type-aliases/UtilsRecord.md)
360
361The utilities record type
362
363### Parameters
364
365#### options
366
367[`CollectionConfig`](../interfaces/CollectionConfig.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `T`, `TUtils`\> & `object` & [`SingleResult`](../type-aliases/SingleResult.md)
368
369Collection options with optional utilities
370
371### Returns
372
373[`Collection`](../interfaces/Collection.md)\<[`InferSchemaOutput`](../type-aliases/InferSchemaOutput.md)\<`T`\>, `TKey`, `TUtils`, `T`, [`InferSchemaInput`](../type-aliases/InferSchemaInput.md)\<`T`\>\> & [`SingleResult`](../type-aliases/SingleResult.md)
374
375A new Collection with utilities exposed both at top level and under .utils
376
377### Examples
378
379```ts
380// Pattern 1: With operation handlers (direct collection calls)
381const todos = createCollection({
382 id: "todos",
383 getKey: (todo) => todo.id,
384 schema,
385 onInsert: async ({ transaction, collection }) => {
386 // Send to API
387 await api.createTodo(transaction.mutations[0].modified)
388 },
389 onUpdate: async ({ transaction, collection }) => {
390 await api.updateTodo(transaction.mutations[0].modified)
391 },
392 onDelete: async ({ transaction, collection }) => {
393 await api.deleteTodo(transaction.mutations[0].key)
394 },
395 sync: { sync: () => {} }
396})
397
398// Direct usage (handlers manage transactions)
399const tx = todos.insert({ id: "1", text: "Buy milk", completed: false })
400await tx.when('settled')
401```
402
403```ts
404// Pattern 2: Manual transaction management
405const todos = createCollection({
406 getKey: (todo) => todo.id,
407 schema: todoSchema,
408 sync: { sync: () => {} }
409})
410
411// Explicit transaction usage
412const tx = createTransaction({
413 mutationFn: async ({ transaction }) => {
414 // Handle all mutations in transaction
415 await api.saveChanges(transaction.mutations)
416 }
417})
418
419tx.mutate(() => {
420 todos.insert({ id: "1", text: "Buy milk" })
421 todos.update("2", draft => { draft.completed = true })
422})
423
424await tx.when('settled')
425```
426
427```ts
428// Using schema for type inference (preferred as it also gives you client side validation)
429const todoSchema = z.object({
430 id: z.string(),
431 title: z.string(),
432 completed: z.boolean()
433})
434
435const todos = createCollection({
436 schema: todoSchema,
437 getKey: (todo) => todo.id,
438 sync: { sync: () => {} }
439})
440```
441
442## Call Signature
443
444```ts
445function createCollection<T, TKey, TUtils>(options): Collection<T, TKey, TUtils, never, T> & NonSingleResult;
446```
447
448Defined in: [packages/db/src/collection/index.ts:298](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L298)
449
450Creates a new Collection instance with the given configuration
451
452### Type Parameters
453
454#### T
455
456`T` *extends* `object`
457
458The schema type if a schema is provided, otherwise the type of items in the collection
459
460#### TKey
461
462`TKey` *extends* `string` \| `number`
463
464The type of the key for the collection
465
466#### TUtils
467
468`TUtils` *extends* [`UtilsRecord`](../type-aliases/UtilsRecord.md)
469
470The utilities record type
471
472### Parameters
473
474#### options
475
476`Omit`\<[`CollectionConfig`](../interfaces/CollectionConfig.md)\<`T`, `TKey`, `never`, `TUtils`\>, `"utils"`\> & `object` & [`NonSingleResult`](../type-aliases/NonSingleResult.md)
477
478Collection options with optional utilities
479
480### Returns
481
482[`Collection`](../interfaces/Collection.md)\<`T`, `TKey`, `TUtils`, `never`, `T`\> & [`NonSingleResult`](../type-aliases/NonSingleResult.md)
483
484A new Collection with utilities exposed both at top level and under .utils
485
486### Examples
487
488```ts
489// Pattern 1: With operation handlers (direct collection calls)
490const todos = createCollection({
491 id: "todos",
492 getKey: (todo) => todo.id,
493 schema,
494 onInsert: async ({ transaction, collection }) => {
495 // Send to API
496 await api.createTodo(transaction.mutations[0].modified)
497 },
498 onUpdate: async ({ transaction, collection }) => {
499 await api.updateTodo(transaction.mutations[0].modified)
500 },
501 onDelete: async ({ transaction, collection }) => {
502 await api.deleteTodo(transaction.mutations[0].key)
503 },
504 sync: { sync: () => {} }
505})
506
507// Direct usage (handlers manage transactions)
508const tx = todos.insert({ id: "1", text: "Buy milk", completed: false })
509await tx.when('settled')
510```
511
512```ts
513// Pattern 2: Manual transaction management
514const todos = createCollection({
515 getKey: (todo) => todo.id,
516 schema: todoSchema,
517 sync: { sync: () => {} }
518})
519
520// Explicit transaction usage
521const tx = createTransaction({
522 mutationFn: async ({ transaction }) => {
523 // Handle all mutations in transaction
524 await api.saveChanges(transaction.mutations)
525 }
526})
527
528tx.mutate(() => {
529 todos.insert({ id: "1", text: "Buy milk" })
530 todos.update("2", draft => { draft.completed = true })
531})
532
533await tx.when('settled')
534```
535
536```ts
537// Using schema for type inference (preferred as it also gives you client side validation)
538const todoSchema = z.object({
539 id: z.string(),
540 title: z.string(),
541 completed: z.boolean()
542})
543
544const todos = createCollection({
545 schema: todoSchema,
546 getKey: (todo) => todo.id,
547 sync: { sync: () => {} }
548})
549```
550
551## Call Signature
552
553```ts
554function createCollection<T, TKey, TUtils>(options): Collection<T, TKey, TUtils, never, T> & NonSingleResult;
555```
556
557Defined in: [packages/db/src/collection/index.ts:311](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L311)
558
559Creates a new Collection instance with the given configuration
560
561### Type Parameters
562
563#### T
564
565`T` *extends* `object`
566
567The schema type if a schema is provided, otherwise the type of items in the collection
568
569#### TKey
570
571`TKey` *extends* `string` \| `number` = `string` \| `number`
572
573The type of the key for the collection
574
575#### TUtils
576
577`TUtils` *extends* [`UtilsRecord`](../type-aliases/UtilsRecord.md) = [`UtilsRecord`](../type-aliases/UtilsRecord.md)
578
579The utilities record type
580
581### Parameters
582
583#### options
584
585[`CollectionConfig`](../interfaces/CollectionConfig.md)\<`T`, `TKey`, `never`, `TUtils`\> & `object` & [`NonSingleResult`](../type-aliases/NonSingleResult.md)
586
587Collection options with optional utilities
588
589### Returns
590
591[`Collection`](../interfaces/Collection.md)\<`T`, `TKey`, `TUtils`, `never`, `T`\> & [`NonSingleResult`](../type-aliases/NonSingleResult.md)
592
593A new Collection with utilities exposed both at top level and under .utils
594
595### Examples
596
597```ts
598// Pattern 1: With operation handlers (direct collection calls)
599const todos = createCollection({
600 id: "todos",
601 getKey: (todo) => todo.id,
602 schema,
603 onInsert: async ({ transaction, collection }) => {
604 // Send to API
605 await api.createTodo(transaction.mutations[0].modified)
606 },
607 onUpdate: async ({ transaction, collection }) => {
608 await api.updateTodo(transaction.mutations[0].modified)
609 },
610 onDelete: async ({ transaction, collection }) => {
611 await api.deleteTodo(transaction.mutations[0].key)
612 },
613 sync: { sync: () => {} }
614})
615
616// Direct usage (handlers manage transactions)
617const tx = todos.insert({ id: "1", text: "Buy milk", completed: false })
618await tx.when('settled')
619```
620
621```ts
622// Pattern 2: Manual transaction management
623const todos = createCollection({
624 getKey: (todo) => todo.id,
625 schema: todoSchema,
626 sync: { sync: () => {} }
627})
628
629// Explicit transaction usage
630const tx = createTransaction({
631 mutationFn: async ({ transaction }) => {
632 // Handle all mutations in transaction
633 await api.saveChanges(transaction.mutations)
634 }
635})
636
637tx.mutate(() => {
638 todos.insert({ id: "1", text: "Buy milk" })
639 todos.update("2", draft => { draft.completed = true })
640})
641
642await tx.when('settled')
643```
644
645```ts
646// Using schema for type inference (preferred as it also gives you client side validation)
647const todoSchema = z.object({
648 id: z.string(),
649 title: z.string(),
650 completed: z.boolean()
651})
652
653const todos = createCollection({
654 schema: todoSchema,
655 getKey: (todo) => todo.id,
656 sync: { sync: () => {} }
657})
658```
659
660## Call Signature
661
662```ts
663function createCollection<T, TKey, TUtils>(options): Collection<T, TKey, TUtils, never, T> & SingleResult;
664```
665
666Defined in: [packages/db/src/collection/index.ts:323](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L323)
667
668Creates a new Collection instance with the given configuration
669
670### Type Parameters
671
672#### T
673
674`T` *extends* `object`
675
676The schema type if a schema is provided, otherwise the type of items in the collection
677
678#### TKey
679
680`TKey` *extends* `string` \| `number` = `string` \| `number`
681
682The type of the key for the collection
683
684#### TUtils
685
686`TUtils` *extends* [`UtilsRecord`](../type-aliases/UtilsRecord.md) = [`UtilsRecord`](../type-aliases/UtilsRecord.md)
687
688The utilities record type
689
690### Parameters
691
692#### options
693
694`Omit`\<[`CollectionConfig`](../interfaces/CollectionConfig.md)\<`T`, `TKey`, `never`, `TUtils`\>, `"utils"`\> & `object` & [`SingleResult`](../type-aliases/SingleResult.md)
695
696Collection options with optional utilities
697
698### Returns
699
700[`Collection`](../interfaces/Collection.md)\<`T`, `TKey`, `TUtils`, `never`, `T`\> & [`SingleResult`](../type-aliases/SingleResult.md)
701
702A new Collection with utilities exposed both at top level and under .utils
703
704### Examples
705
706```ts
707// Pattern 1: With operation handlers (direct collection calls)
708const todos = createCollection({
709 id: "todos",
710 getKey: (todo) => todo.id,
711 schema,
712 onInsert: async ({ transaction, collection }) => {
713 // Send to API
714 await api.createTodo(transaction.mutations[0].modified)
715 },
716 onUpdate: async ({ transaction, collection }) => {
717 await api.updateTodo(transaction.mutations[0].modified)
718 },
719 onDelete: async ({ transaction, collection }) => {
720 await api.deleteTodo(transaction.mutations[0].key)
721 },
722 sync: { sync: () => {} }
723})
724
725// Direct usage (handlers manage transactions)
726const tx = todos.insert({ id: "1", text: "Buy milk", completed: false })
727await tx.when('settled')
728```
729
730```ts
731// Pattern 2: Manual transaction management
732const todos = createCollection({
733 getKey: (todo) => todo.id,
734 schema: todoSchema,
735 sync: { sync: () => {} }
736})
737
738// Explicit transaction usage
739const tx = createTransaction({
740 mutationFn: async ({ transaction }) => {
741 // Handle all mutations in transaction
742 await api.saveChanges(transaction.mutations)
743 }
744})
745
746tx.mutate(() => {
747 todos.insert({ id: "1", text: "Buy milk" })
748 todos.update("2", draft => { draft.completed = true })
749})
750
751await tx.when('settled')
752```
753
754```ts
755// Using schema for type inference (preferred as it also gives you client side validation)
756const todoSchema = z.object({
757 id: z.string(),
758 title: z.string(),
759 completed: z.boolean()
760})
761
762const todos = createCollection({
763 schema: todoSchema,
764 getKey: (todo) => todo.id,
765 sync: { sync: () => {} }
766})
767```
768
769## Call Signature
770
771```ts
772function createCollection<T, TKey, TUtils>(options): Collection<T, TKey, TUtils, never, T> & SingleResult;
773```
774
775Defined in: [packages/db/src/collection/index.ts:336](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts#L336)
776
777Creates a new Collection instance with the given configuration
778
779### Type Parameters
780
781#### T
782
783`T` *extends* `object`
784
785The schema type if a schema is provided, otherwise the type of items in the collection
786
787#### TKey
788
789`TKey` *extends* `string` \| `number` = `string` \| `number`
790
791The type of the key for the collection
792
793#### TUtils
794
795`TUtils` *extends* [`UtilsRecord`](../type-aliases/UtilsRecord.md) = [`UtilsRecord`](../type-aliases/UtilsRecord.md)
796
797The utilities record type
798
799### Parameters
800
801#### options
802
803[`CollectionConfig`](../interfaces/CollectionConfig.md)\<`T`, `TKey`, `never`, `TUtils`\> & `object` & [`SingleResult`](../type-aliases/SingleResult.md)
804
805Collection options with optional utilities
806
807### Returns
808
809[`Collection`](../interfaces/Collection.md)\<`T`, `TKey`, `TUtils`, `never`, `T`\> & [`SingleResult`](../type-aliases/SingleResult.md)
810
811A new Collection with utilities exposed both at top level and under .utils
812
813### Examples
814
815```ts
816// Pattern 1: With operation handlers (direct collection calls)
817const todos = createCollection({
818 id: "todos",
819 getKey: (todo) => todo.id,
820 schema,
821 onInsert: async ({ transaction, collection }) => {
822 // Send to API
823 await api.createTodo(transaction.mutations[0].modified)
824 },
825 onUpdate: async ({ transaction, collection }) => {
826 await api.updateTodo(transaction.mutations[0].modified)
827 },
828 onDelete: async ({ transaction, collection }) => {
829 await api.deleteTodo(transaction.mutations[0].key)
830 },
831 sync: { sync: () => {} }
832})
833
834// Direct usage (handlers manage transactions)
835const tx = todos.insert({ id: "1", text: "Buy milk", completed: false })
836await tx.when('settled')
837```
838
839```ts
840// Pattern 2: Manual transaction management
841const todos = createCollection({
842 getKey: (todo) => todo.id,
843 schema: todoSchema,
844 sync: { sync: () => {} }
845})
846
847// Explicit transaction usage
848const tx = createTransaction({
849 mutationFn: async ({ transaction }) => {
850 // Handle all mutations in transaction
851 await api.saveChanges(transaction.mutations)
852 }
853})
854
855tx.mutate(() => {
856 todos.insert({ id: "1", text: "Buy milk" })
857 todos.update("2", draft => { draft.completed = true })
858})
859
860await tx.when('settled')
861```
862
863```ts
864// Using schema for type inference (preferred as it also gives you client side validation)
865const todoSchema = z.object({
866 id: z.string(),
867 title: z.string(),
868 completed: z.boolean()
869})
870
871const todos = createCollection({
872 schema: todoSchema,
873 getKey: (todo) => todo.id,
874 sync: { sync: () => {} }
875})
876```