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

collection.test.ts

492 lines16.1 KB

1import { describe, expect, it, vi } from "vitest"
2import "fake-indexeddb/auto"
3import mitt from "mitt"
4import { z } from "zod"
5import { Collection, SchemaValidationError } from "../src/collection"
6import type { ChangeMessage, PendingMutation } from "../src/types"
7​
8describe(`Collection`, () => {
9 it(`should throw if there's no sync config`, () => {
10 expect(() => new Collection()).toThrow(`Collection requires a sync config`)
11 })
12​
13 it(`should throw if there's no mutationFn`, () => {
14 expect(
15 () =>
16 // @ts-expect-error mutationFn is supposed to be missing.
17 new Collection({
18 id: `foo`,
19 sync: { sync: async () => {} },
20 })
21 ).toThrow(`Collection requires a mutationFn`)
22 })
23​
24 it(`It shouldn't expose any state until the initial sync is finished`, () => {
25 // Create a collection with a mock sync plugin
26 new Collection<{ name: string }>({
27 id: `foo`,
28 sync: {
29 sync: ({ collection, begin, write, commit }) => {
30 // Initial state should be empty
31 expect(collection.state).toEqual(new Map())
32​
33 // Start a batch of operations
34 begin()
35​
36 // Write some test data
37 const operations: Array<ChangeMessage<{ name: string }>> = [
38 { key: `user1`, value: { name: `Alice` }, type: `insert` },
39 { key: `user2`, value: { name: `Bob` }, type: `insert` },
40 ]
41​
42 for (const op of operations) {
43 write(op)
44 // Data should still be empty during writes
45 expect(collection.state).toEqual(new Map())
46 }
47​
48 // Commit the changes
49 commit()
50​
51 // Now the data should be visible
52 const expectedData = new Map([
53 [`user1`, { name: `Alice` }],
54 [`user2`, { name: `Bob` }],
55 ])
56 expect(collection.state).toEqual(expectedData)
57 },
58 },
59 mutationFn: {
60 persist: async () => {},
61 },
62 })
63 })
64​
65 it(`Calling mutation operators should trigger creating & persisting a new transaction`, async () => {
66 const emitter = mitt()
67 // Create mock functions that will capture the data for later assertions
68 const persistMock = vi.fn()
69 const syncMock = vi.fn()
70​
71 // new collection w/ mock sync/mutation
72 const collection = new Collection<{ value: string; newProp?: string }>({
73 id: `mock`,
74 sync: {
75 sync: ({ begin, write, commit }) => {
76 // @ts-expect-error don't trust mitt's typing
77 emitter.on(`*`, (_, changes: Array<PendingMutation>) => {
78 begin()
79 changes.forEach((change) => {
80 write({
81 key: change.key,
82 type: change.type,
83 // @ts-expect-error TODO type changes
84 value: change.changes,
85 })
86 })
87 commit()
88 })
89 },
90 },
91 mutationFn: {
92 persist({ transaction }) {
93 // Redact time-based and random fields
94 const redactedTransaction = {
95 ...transaction.toObject(),
96 mutations: {
97 ...transaction.mutations.map((mutation) => {
98 return {
99 ...mutation,
100 createdAt: `[REDACTED]`,
101 updatedAt: `[REDACTED]`,
102 mutationId: `[REDACTED]`,
103 }
104 }),
105 },
106 }
107​
108 // Call the mock function with the redacted transaction
109 persistMock({ transaction: redactedTransaction })
110 return Promise.resolve()
111 },
112 awaitSync({ transaction }) {
113 // Call the mock function with the transaction
114 syncMock({ transaction })
115​
116 emitter.emit(`sync`, transaction.mutations)
117 return Promise.resolve()
118 },
119 },
120 })
121​
122 // Test insert with auto-generated key
123 const data = { value: `bar` }
124 const transaction = collection.insert(data)
125 // @ts-expect-error possibly undefined is ok in test
126 const insertedKey = transaction.mutations[0].key
127​
128 // The merged value should immediately contain the new insert
129 expect(collection.state).toEqual(new Map([[insertedKey, { value: `bar` }]]))
130​
131 // check there's a transaction in peristing state
132 expect(
133 // @ts-expect-error possibly undefined is ok in test
134 Array.from(collection.transactions.values())[0].mutations[0].changes
135 ).toEqual({
136 value: `bar`,
137 })
138​
139 // Check the optimistic operation is there
140 const insertOperation: ChangeMessage = {
141 key: insertedKey,
142 value: { value: `bar` },
143 type: `insert`,
144 }
145 expect(collection.optimisticOperations.state[0]).toEqual(insertOperation)
146​
147 // Check persist data (moved outside the persist callback)
148 // @ts-expect-error possibly undefined is ok in test
149 const persistData = persistMock.mock.calls[0][0]
150 // Check that the transaction is in the right state during persist
151 expect(persistData.transaction.state).toBe(`persisting`)
152 // Check mutation type is correct
153 expect(persistData.transaction.mutations[0].type).toBe(`insert`)
154 // Check changes are correct
155 expect(persistData.transaction.mutations[0].changes).toEqual({
156 value: `bar`,
157 })
158​
159 await transaction.isSynced?.promise
160​
161 // Check sync data (moved outside the awaitSync callback)
162 // @ts-expect-error possibly undefined is ok in test
163 const syncData = syncMock.mock.calls[0][0]
164 // Check that the transaction is in the right state during sync waiting
165 expect(syncData.transaction.state).toBe(`completed`)
166 // Check mutation type is correct
167 expect(syncData.transaction.mutations[0].type).toBe(`insert`)
168 // Check changes are correct
169 expect(syncData.transaction.mutations[0].changes).toEqual({ value: `bar` })
170​
171 // after mutationFn returns, check that the transaction is updated &
172 // optimistic update is gone & synced data & comibned state are all updated.
173 expect(
174 // @ts-expect-error possibly undefined is ok in test
175 Array.from(collection.transactions.values())[0].state
176 ).toMatchInlineSnapshot(`"completed"`)
177 expect(collection.optimisticOperations.state).toEqual([])
178 expect(collection.state).toEqual(new Map([[insertedKey, { value: `bar` }]]))
179​
180 // Test insert with provided key
181 collection.insert({ value: `baz` }, { key: `custom-key` })
182 expect(collection.state.get(`custom-key`)).toEqual({ value: `baz` })
183​
184 // Test bulk insert
185 const bulkData = [{ value: `item1` }, { value: `item2` }]
186 collection.insert(bulkData)
187 const keys = Array.from(collection.state.keys())
188 // @ts-expect-error possibly undefined is ok in test
189 expect(collection.state.get(keys[2])).toEqual(bulkData[0])
190 // @ts-expect-error possibly undefined is ok in test
191 expect(collection.state.get(keys[3])).toEqual(bulkData[1])
192​
193 // Test update with callback
194 collection.update([collection.state.get(insertedKey)!], (item) => {
195 // @ts-expect-error possibly undefined is ok in test
196 item[0].value = `bar2`
197 })
198​
199 // The merged value should contain the update.
200 expect(collection.state.get(insertedKey)).toEqual({ value: `bar2` })
201​
202 // Test update with config and callback
203 collection.update(
204 collection.state.get(insertedKey),
205 { metadata: { updated: true } },
206 (item) => {
207 item.value = `bar3`
208 item.newProp = `new value`
209 }
210 )
211​
212 // The merged value should contain the update
213 expect(collection.state.get(insertedKey)).toEqual({
214 value: `bar3`,
215 newProp: `new value`,
216 })
217​
218 // Test bulk update
219 const items = [
220 // @ts-expect-error possibly undefined is ok in test
221 collection.state.get(keys[2])!,
222 // @ts-expect-error possibly undefined is ok in test
223 collection.state.get(keys[3])!,
224 ]
225 collection.update(items, { metadata: { bulkUpdate: true } }, (drafts) => {
226 drafts.forEach((draft) => {
227 draft.value += `-updated`
228 })
229 })
230​
231 // Check bulk updates
232 // @ts-expect-error possibly undefined is ok in test
233 expect(collection.state.get(keys[2])).toEqual({ value: `item1-updated` })
234 // @ts-expect-error possibly undefined is ok in test
235 expect(collection.state.get(keys[3])).toEqual({ value: `item2-updated` })
236​
237 const toBeDeleted = collection.state.get(insertedKey)!
238 // Test delete single item
239 collection.delete(toBeDeleted)
240 expect(collection.state.has(insertedKey)).toBe(false)
241 expect(collection.objectKeyMap.has(toBeDeleted)).toBe(false)
242​
243 // Test delete with metadata
244 collection.delete(collection.state.get(`custom-key`), {
245 metadata: { reason: `test` },
246 })
247 expect(collection.state.has(`custom-key`)).toBe(false)
248​
249 // Test bulk delete
250 collection.delete([
251 // @ts-expect-error possibly undefined is ok in test
252 collection.state.get(keys[2])!,
253 // @ts-expect-error possibly undefined is ok in test
254 collection.state.get(keys[3])!,
255 ])
256 // @ts-expect-error possibly undefined is ok in test
257 expect(collection.state.has(keys[2])).toBe(false)
258 // @ts-expect-error possibly undefined is ok in test
259 expect(collection.state.has(keys[3])).toBe(false)
260 })
261​
262 it(`synced updates shouldn't be applied while there's an ongoing transaction`, async () => {
263 const emitter = mitt()
264​
265 // new collection w/ mock sync/mutation
266 const collection = new Collection<{ value: string }>({
267 id: `mock`,
268 sync: {
269 sync: ({ begin, write, commit }) => {
270 // @ts-expect-error don't trust Mitt's typing and this works.
271 emitter.on(`*`, (_, changes: Array<PendingMutation>) => {
272 begin()
273 changes.forEach((change) => {
274 write({
275 key: change.key,
276 type: change.type,
277 // @ts-expect-error TODO type changes
278 value: change.changes,
279 })
280 })
281 commit()
282 })
283 },
284 },
285 mutationFn: {
286 persist() {
287 // Sync something and check that that it isn't applied because
288 // we're still in the middle of persisting a transaction.
289 emitter.emit(`update`, [
290 { key: `the-key`, type: `insert`, changes: { bar: `value` } },
291 ])
292 expect(collection.state).toEqual(new Map([[`foo`, { value: `bar` }]]))
293 // Remove it so we don't have to assert against it below
294 emitter.emit(`update`, [{ key: `the-key`, type: `delete` }])
295 return Promise.resolve()
296 },
297 awaitSync({ transaction }) {
298 emitter.emit(`update`, transaction.mutations)
299 return Promise.resolve()
300 },
301 },
302 })
303​
304 // insert
305 const transaction = collection.insert(
306 {
307 value: `bar`,
308 },
309 { key: `foo` }
310 )
311​
312 // The merged value should immediately contain the new insert
313 expect(collection.state).toEqual(new Map([[`foo`, { value: `bar` }]]))
314​
315 // check there's a transaction in peristing state
316 expect(
317 // @ts-expect-error possibly undefined is ok in test
318 Array.from(collection.transactions.values())[0].mutations[0].changes
319 ).toEqual({
320 value: `bar`,
321 })
322​
323 // Check the optimistic operation is there
324 const insertOperation: ChangeMessage = {
325 key: `foo`,
326 value: { value: `bar` },
327 type: `insert`,
328 }
329 expect(collection.optimisticOperations.state[0]).toEqual(insertOperation)
330​
331 await transaction.isSynced?.promise
332​
333 expect(collection.state).toEqual(new Map([[`foo`, { value: `bar` }]]))
334 })
335​
336 // Skip until e2e working
337 it(`If the mutationFn throws error, it get retried`, () => {
338 // new collection w/ mock sync/mutation
339 // insert
340 // mutationFn fails the first time and then succeeds
341 })
342​
343 // Skip until e2e working
344 it(`If the mutationFn throws NonRetriableError, it doesn't get retried and optimistic state is rolled back`, () => {
345 // new collection w/ mock sync/mutation
346 // insert
347 // mutationFn fails w/ NonRetriableError and the check that optimistic state is rolledback.
348 })
349​
350 it(`should handle sparse key arrays for bulk inserts`, () => {
351 const collection = new Collection<{ value: string }>({
352 id: `test`,
353 sync: {
354 sync: ({ begin, commit }) => {
355 begin()
356 commit()
357 },
358 },
359 mutationFn: {
360 persist: async () => {},
361 },
362 })
363​
364 // Insert multiple items with a sparse key array
365 const items = [
366 { value: `item1` },
367 { value: `item2` },
368 { value: `item3` },
369 { value: `item4` },
370 ]
371​
372 // Only provide keys for first and third items
373 const transaction = collection.insert(items, {
374 key: [`key1`, undefined, `key3`],
375 })
376​
377 // Get all keys from the transaction
378 const keys = transaction.mutations.map((m) => m.key)
379​
380 // Verify explicit keys were used
381 expect(keys[0]).toBe(`key1`)
382 expect(keys[2]).toBe(`key3`)
383​
384 // Verify auto-generated keys for undefined positions
385 expect(keys[1]).toHaveLength(6)
386 expect(keys[3]).toHaveLength(6)
387​
388 // Verify all items were inserted with correct values
389 // @ts-expect-error possibly undefined is ok in test
390 expect(collection.state.get(keys[0])).toEqual({ value: `item1` })
391 // @ts-expect-error possibly undefined is ok in test
392 expect(collection.state.get(keys[1])).toEqual({ value: `item2` })
393 // @ts-expect-error possibly undefined is ok in test
394 expect(collection.state.get(keys[2])).toEqual({ value: `item3` })
395 // @ts-expect-error possibly undefined is ok in test
396 expect(collection.state.get(keys[3])).toEqual({ value: `item4` })
397​
398 // Test error case: more keys than items
399 expect(() => {
400 collection.insert([{ value: `test` }], {
401 key: [`key1`, `key2`],
402 })
403 }).toThrow(`More keys provided than items to insert`)
404 })
405})
406​
407describe(`Collection with schema validation`, () => {
408 it(`should validate data against schema on insert`, () => {
409 // Create a Zod schema for a user
410 const userSchema = z.object({
411 name: z.string().min(1),
412 age: z.number().int().positive(),
413 email: z.string().email().optional(),
414 })
415​
416 // Create a collection with the schema
417 const collection = new Collection<z.infer<typeof userSchema>>({
418 id: `test`,
419 sync: {
420 sync: ({ begin, commit }) => {
421 begin()
422 commit()
423 },
424 },
425 mutationFn: {
426 persist: async () => {},
427 },
428 schema: userSchema,
429 })
430​
431 // Valid data should work
432 const validUser = {
433 name: `Alice`,
434 age: 30,
435 email: `alice@example.com`,
436 }
437​
438 collection.insert(validUser, { key: `user1` })
439​
440 // Invalid data should throw SchemaValidationError
441 const invalidUser = {
442 name: ``, // Empty name (fails min length)
443 age: -5, // Negative age (fails positive)
444 email: `not-an-email`, // Invalid email
445 }
446​
447 try {
448 collection.insert(invalidUser, { key: `user2` })
449 // Should not reach here
450 expect(true).toBe(false)
451 } catch (error) {
452 expect(error).toBeInstanceOf(SchemaValidationError)
453 if (error instanceof SchemaValidationError) {
454 expect(error.type).toBe(`insert`)
455 expect(error.issues.length).toBeGreaterThan(0)
456 // Check that we have validation errors for each invalid field
457 expect(error.issues.some((issue) => issue.path?.includes(`name`))).toBe(
458 true
459 )
460 expect(error.issues.some((issue) => issue.path?.includes(`age`))).toBe(
461 true
462 )
463 expect(
464 error.issues.some((issue) => issue.path?.includes(`email`))
465 ).toBe(true)
466 }
467 }
468​
469 // Partial updates should work with valid data
470 collection.update(collection.state.get(`user1`), (draft) => {
471 draft.age = 31
472 })
473​
474 // Partial updates should fail with invalid data
475 try {
476 collection.update(collection.state.get(`user1`), (draft) => {
477 draft.age = -1
478 })
479 // Should not reach here
480 expect(true).toBe(false)
481 } catch (error) {
482 expect(error).toBeInstanceOf(SchemaValidationError)
483 if (error instanceof SchemaValidationError) {
484 expect(error.type).toBe(`update`)
485 expect(error.issues.length).toBeGreaterThan(0)
486 expect(error.issues.some((issue) => issue.path?.includes(`age`))).toBe(
487 true
488 )
489 }
490 }
491 })
492})