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