Open History to see the last commit
1import { randomUUID } from 'node:crypto'
2import { tmpdir } from 'node:os'
3import {
4 CrudEntry,
5 PowerSyncDatabase,
6 Schema,
7 Table,
8 column,
9} from '@powersync/node'
10import {
11 createCollection,
12 createTransaction,
13 eq,
14 liveQueryCollectionOptions,
15} from '@tanstack/db'
16import { describe, expect, it, onTestFinished, vi } from 'vitest'
17import { powerSyncCollectionOptions } from '../src'
18import { PowerSyncTransactor } from '../src/PowerSyncTransactor'
19import { TEST_DATABASE_IMPLEMENTATION } from './test-db-implementation'
20import type { AbstractPowerSyncDatabase } from '@powersync/node'
21
22const APP_SCHEMA = new Schema({
23 users: new Table({
24 name: column.text,
25 active: column.integer, // Will be mapped to Boolean
26 }),
27 documents: new Table(
28 {
29 name: column.text,
30 author: column.text,
31 created_at: column.text, // Will be mapped to Date
32 },
33 {
34 trackMetadata: true,
35 },
36 ),
37})
38
39const describePowerSync = TEST_DATABASE_IMPLEMENTATION
40 ? describe
41 : describe.skip
42
43describePowerSync(`PowerSync Integration`, () => {
44 async function createDatabase() {
45 const db = new PowerSyncDatabase({
46 database: {
47 dbFilename: `test-${randomUUID()}.sqlite`,
48 dbLocation: tmpdir(),
49 implementation: TEST_DATABASE_IMPLEMENTATION,
50 },
51 schema: APP_SCHEMA,
52 })
53 onTestFinished(async () => {
54 await db.disconnectAndClear()
55 await db.close()
56 })
57 // Initial clear in case a test might have failed
58 await db.disconnectAndClear()
59 return db
60 }
61
62 function createDocumentsCollection(db: PowerSyncDatabase) {
63 const collection = createCollection(
64 powerSyncCollectionOptions({
65 database: db,
66 // We get typing and a default validator from this
67 table: APP_SCHEMA.props.documents,
68 }),
69 )
70 onTestFinished(() => collection.cleanup())
71 return collection
72 }
73
74 async function createTestData(db: AbstractPowerSyncDatabase) {
75 await db.execute(`
76 INSERT into documents (id, name)
77 VALUES
78 (uuid(), 'one'),
79 (uuid(), 'two'),
80 (uuid(), 'three')
81 `)
82 }
83
84 describe(`sync`, () => {
85 it(`should initialize and fetch initial data`, async () => {
86 const db = await createDatabase()
87 await createTestData(db)
88 const collection = createDocumentsCollection(db)
89
90 await collection.stateWhenReady()
91
92 // Verify the collection state contains our items
93 expect(collection.size).toBe(3)
94 // Sort by name since keys are random UUIDs
95 expect(collection.toArray.map((entry) => entry.name).sort()).deep.equals([
96 `one`,
97 `three`,
98 `two`,
99 ])
100 })
101
102 it(`should update when data syncs`, async () => {
103 const db = await createDatabase()
104 await createTestData(db)
105
106 const collection = createDocumentsCollection(db)
107
108 await collection.stateWhenReady()
109
110 // Verify the collection state contains our items
111 expect(collection.size).toBe(3)
112
113 // Make an update, simulates a sync from another client
114 await db.execute(`
115 INSERT into documents (id, name)
116 VALUES
117 (uuid(), 'four')
118 `)
119
120 // The collection should update
121 await vi.waitFor(
122 () => {
123 expect(collection.size).toBe(4)
124 // Sort by name since keys are random UUIDs
125 expect(
126 collection.toArray.map((entry) => entry.name).sort(),
127 ).deep.equals([`four`, `one`, `three`, `two`])
128 },
129 { timeout: 1000 },
130 )
131
132 await db.execute(`
133 DELETE from documents
134 WHERE name = 'two'
135 `)
136
137 // The collection should update
138 await vi.waitFor(
139 () => {
140 expect(collection.size).toBe(3)
141 // Sort by name since keys are random UUIDs
142 expect(
143 collection.toArray.map((entry) => entry.name).sort(),
144 ).deep.equals([`four`, `one`, `three`])
145 },
146 { timeout: 1000 },
147 )
148
149 await db.execute(`
150 UPDATE documents
151 SET name = 'updated'
152 WHERE name = 'one'
153 `)
154
155 // The collection should update
156 await vi.waitFor(
157 () => {
158 expect(collection.size).toBe(3)
159 // Sort by name since keys are random UUIDs
160 expect(
161 collection.toArray.map((entry) => entry.name).sort(),
162 ).deep.equals([`four`, `three`, `updated`])
163 },
164 { timeout: 1000 },
165 )
166 })
167
168 it(`should propagate collection mutations to PowerSync`, async () => {
169 const db = await createDatabase()
170 await createTestData(db)
171
172 const collection = createDocumentsCollection(db)
173 await collection.stateWhenReady()
174
175 // Verify the collection state contains our items
176 expect(collection.size).toBe(3)
177
178 const id = randomUUID()
179 const tx = collection.insert({
180 id,
181 name: `new`,
182 author: `somebody`,
183 })
184
185 // The insert should optimistically update the collection
186 const newDoc = collection.get(id)
187 expect(newDoc).toBeDefined()
188 expect(newDoc!.name).toBe(`new`)
189 expect(newDoc!.author).toBe(`somebody`)
190
191 await tx.isPersisted.promise
192 // The item should now be present in PowerSync
193 // We should also have patched it back in to Tanstack DB (removing the optimistic state)
194
195 // Now do an update
196 await collection.update(id, (d) => (d.name = `updatedNew`)).isPersisted
197 .promise
198
199 const updatedDoc = collection.get(id)
200 expect(updatedDoc).toBeDefined()
201 expect(updatedDoc!.name).toBe(`updatedNew`)
202 // Only the updated field should be updated
203 expect(updatedDoc!.author).toBe(`somebody`)
204
205 await collection.delete(id).isPersisted.promise
206
207 // There should be a crud entries for this
208 const _crudEntries = await db.getAll(`
209 SELECT * FROM ps_crud ORDER BY id`)
210
211 const crudEntries = _crudEntries.map((r) =>
212 CrudEntry.fromRow(r as Parameters<typeof CrudEntry.fromRow>[0]),
213 )
214
215 expect(crudEntries.length).toBe(6)
216 // We can only group transactions for similar operations
217 expect(crudEntries.map((e) => e.op)).toEqual([
218 `PUT`,
219 `PUT`,
220 `PUT`,
221 `PUT`,
222 `PATCH`,
223 `DELETE`,
224 ])
225 })
226
227 it(`should handle transactions`, async () => {
228 const db = await createDatabase()
229 await createTestData(db)
230
231 const collection = createDocumentsCollection(db)
232 await collection.stateWhenReady()
233
234 expect(collection.size).toBe(3)
235
236 const addTx = createTransaction({
237 autoCommit: false,
238 mutationFn: async ({ transaction }) => {
239 await new PowerSyncTransactor({ database: db }).applyTransaction(
240 transaction,
241 )
242 },
243 })
244
245 addTx.mutate(() => {
246 for (let i = 0; i < 5; i++) {
247 collection.insert({ id: randomUUID(), name: `tx-${i}` })
248 }
249 })
250
251 await addTx.commit()
252 await addTx.isPersisted.promise
253
254 expect(collection.size).toBe(8)
255
256 // fetch the ps_crud items
257 // There should be a crud entries for this
258 const _crudEntries = await db.getAll(`
259 SELECT * FROM ps_crud ORDER BY id`)
260 const crudEntries = _crudEntries.map((r) =>
261 CrudEntry.fromRow(r as Parameters<typeof CrudEntry.fromRow>[0]),
262 )
263
264 const lastTransactionId =
265 crudEntries[crudEntries.length - 1]?.transactionId
266 /**
267 * The last items, created in the same transaction, should be in the same
268 * PowerSync transaction.
269 */
270 expect(
271 crudEntries
272 .reverse()
273 .slice(0, 5)
274 .every((crudEntry) => crudEntry.transactionId == lastTransactionId),
275 ).true
276 })
277
278 it(`should handle transactions with multiple collections`, async () => {
279 const db = await createDatabase()
280 await createTestData(db)
281
282 const documentsCollection = createDocumentsCollection(db)
283
284 const usersCollection = createCollection(
285 powerSyncCollectionOptions({
286 database: db,
287 table: APP_SCHEMA.props.users,
288 }),
289 )
290 onTestFinished(() => usersCollection.cleanup())
291
292 await documentsCollection.stateWhenReady()
293 await usersCollection.stateWhenReady()
294
295 expect(documentsCollection.size).toBe(3)
296 expect(usersCollection.size).toBe(0)
297
298 const addTx = createTransaction({
299 autoCommit: false,
300 mutationFn: async ({ transaction }) => {
301 await new PowerSyncTransactor({ database: db }).applyTransaction(
302 transaction,
303 )
304 },
305 })
306
307 addTx.mutate(() => {
308 for (let i = 0; i < 5; i++) {
309 documentsCollection.insert({ id: randomUUID(), name: `tx-${i}` })
310 usersCollection.insert({ id: randomUUID(), name: `user` })
311 }
312 })
313
314 await addTx.commit()
315 await addTx.isPersisted.promise
316
317 expect(documentsCollection.size).toBe(8)
318 expect(usersCollection.size).toBe(5)
319
320 // fetch the ps_crud items
321 // There should be a crud entries for this
322 const _crudEntries = await db.getAll(`
323 SELECT * FROM ps_crud ORDER BY id`)
324 const crudEntries = _crudEntries.map((r) =>
325 CrudEntry.fromRow(r as Parameters<typeof CrudEntry.fromRow>[0]),
326 )
327
328 const lastTransactionId =
329 crudEntries[crudEntries.length - 1]?.transactionId
330 /**
331 * The last items, created in the same transaction, should be in the same
332 * PowerSync transaction.
333 */
334 expect(
335 crudEntries
336 .reverse()
337 .slice(0, 10)
338 .every((crudEntry) => crudEntry.transactionId == lastTransactionId),
339 ).true
340 })
341
342 /**
343 * Metadata provided by the collection operation should be persisted to the database if supported by the SQLite table.
344 */
345 it(`should persist collection operation metadata`, async () => {
346 const db = await createDatabase()
347
348 const collection = createDocumentsCollection(db)
349 await collection.stateWhenReady()
350
351 const metadata = {
352 text: `some text`,
353 number: 123,
354 boolean: true,
355 }
356 const id = randomUUID()
357 await collection.insert(
358 {
359 id,
360 name: `new`,
361 author: `somebody`,
362 },
363 {
364 metadata,
365 },
366 ).isPersisted.promise
367
368 // Now do an update
369 await collection.update(
370 id,
371 { metadata: metadata },
372 (d) => (d.name = `updatedNew`),
373 ).isPersisted.promise
374
375 await collection.delete(id, { metadata }).isPersisted.promise
376
377 // There should be a crud entries for this
378 const crudBatch = await db.getCrudBatch(100)
379 expect(crudBatch).toBeDefined()
380 const crudEntries = crudBatch!.crud
381
382 // The metadata should be available in the CRUD entries for upload
383 const stringifiedMetadata = JSON.stringify(metadata)
384 expect(crudEntries.length).toBe(3)
385 expect(crudEntries[0]!.metadata).toEqual(stringifiedMetadata)
386 expect(crudEntries[1]!.metadata).toEqual(stringifiedMetadata)
387 expect(crudEntries[2]!.metadata).toEqual(stringifiedMetadata)
388
389 // Verify the item is deleted from SQLite
390 const documents = await db.getAll(`
391 SELECT * FROM documents`)
392 expect(documents.length).toBe(0)
393 })
394 })
395
396 describe(`General use`, () => {
397 it(`should rollback transactions on error`, async () => {
398 const db = await createDatabase()
399
400 const options = powerSyncCollectionOptions({
401 database: db,
402 table: APP_SCHEMA.props.documents,
403 })
404
405 // This will cause the transactor to fail when writing to SQLite
406 vi.spyOn(options.utils, `getMeta`).mockImplementation(() => ({
407 tableName: `fakeTable`,
408 trackedTableName: `error`,
409 metadataIsTracked: true,
410 serializeValue: () => ({}) as any,
411 }))
412 // Create two collections for the same table
413 const collection = createCollection(options)
414
415 onTestFinished(() => collection.cleanup())
416 const addTx = createTransaction({
417 autoCommit: false,
418 mutationFn: async ({ transaction }) => {
419 await new PowerSyncTransactor({ database: db }).applyTransaction(
420 transaction,
421 )
422 },
423 })
424
425 expect(collection.size).eq(0)
426 await collection.stateWhenReady()
427
428 const id = randomUUID()
429 addTx.mutate(() => {
430 collection.insert({
431 id,
432 name: `aname`,
433 })
434 })
435
436 // This should be present in the optimistic state, but should be reverted when attempting to persist
437 expect(collection.size).eq(1)
438
439 try {
440 await addTx.commit()
441 await addTx.isPersisted.promise
442 expect.fail(`Should have thrown an error`)
443 } catch (error) {
444 expect(error).toBeDefined()
445 // The collection should be in a clean state
446 expect(collection.size).toBe(0)
447 }
448 })
449
450 it(`should work with live queries`, async () => {
451 const db = await createDatabase()
452
453 // Create two collections for the same table
454 const collection = createDocumentsCollection(db)
455
456 await collection.stateWhenReady()
457
458 const liveDocuments = createCollection(
459 liveQueryCollectionOptions({
460 query: (q) =>
461 q
462 .from({ document: collection })
463 .where(({ document }) => eq(document.name, `book`))
464 .select(({ document }) => ({
465 id: document.id,
466 name: document.name,
467 })),
468 }),
469 )
470
471 expect(liveDocuments.size).eq(0)
472
473 const bookNames = new Set<string>()
474
475 liveDocuments.subscribeChanges((changes) => {
476 changes
477 .map((change) => change.value.name)
478 .filter((name): name is string => name !== undefined)
479 .forEach((change) => bookNames.add(change))
480 })
481
482 await collection.insert({
483 id: randomUUID(),
484 name: `notabook`,
485 }).isPersisted.promise
486 await collection.insert({
487 id: randomUUID(),
488 name: `book`,
489 }).isPersisted.promise
490
491 expect(collection.size).eq(2)
492 await vi.waitFor(
493 () => {
494 expect(Array.from(bookNames)).deep.equals([`book`])
495 },
496 { timeout: 1000 },
497 )
498 })
499 })
500
501 describe(`Multiple Clients`, () => {
502 it(`should sync updates between multiple clients`, async () => {
503 const db = await createDatabase()
504
505 // Create two collections for the same table
506 const collectionA = createDocumentsCollection(db)
507 await collectionA.stateWhenReady()
508
509 const collectionB = createDocumentsCollection(db)
510 await collectionB.stateWhenReady()
511
512 await createTestData(db)
513
514 // Both collections should have the data present after insertion
515 await vi.waitFor(
516 () => {
517 expect(collectionA.size).eq(3)
518 expect(collectionB.size).eq(3)
519 },
520 { timeout: 1000 },
521 )
522 })
523 })
524
525 describe(`Lifecycle`, () => {
526 it(`should cleanup resources`, async () => {
527 const db = await createDatabase()
528 const collectionOptions = powerSyncCollectionOptions({
529 database: db,
530 table: APP_SCHEMA.props.documents,
531 })
532
533 const meta = collectionOptions.utils.getMeta()
534
535 const tableExists = async (): Promise<boolean> => {
536 const result = await db.writeLock(async (tx) => {
537 return tx.get<{ count: number }>(
538 `
539 SELECT COUNT(*) as count
540 FROM sqlite_temp_master
541 WHERE type='table' AND name = ?
542 `,
543 [meta.trackedTableName],
544 )
545 })
546 return result.count > 0
547 }
548
549 const collection = createCollection(collectionOptions)
550 await collection.stateWhenReady()
551 expect(await tableExists()).true
552
553 await collection.cleanup()
554
555 // It seems that even though `cleanup` is async, the sync disposer cannot be async
556 // We wait for the table to be deleted
557 await vi.waitFor(
558 async () => {
559 expect(await tableExists()).false
560 },
561 { timeout: 1000 },
562 )
563 })
564 })
565})