@powersync/common 0.0.0-dev-20260120150240 → 0.0.0-dev-20260128165909

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/README.md +5 -1
  2. package/dist/bundle.cjs +1433 -386
  3. package/dist/bundle.cjs.map +1 -1
  4. package/dist/bundle.mjs +1425 -387
  5. package/dist/bundle.mjs.map +1 -1
  6. package/dist/bundle.node.cjs +1433 -386
  7. package/dist/bundle.node.cjs.map +1 -1
  8. package/dist/bundle.node.mjs +1425 -387
  9. package/dist/bundle.node.mjs.map +1 -1
  10. package/dist/index.d.cts +617 -44
  11. package/lib/attachments/AttachmentContext.d.ts +86 -0
  12. package/lib/attachments/AttachmentContext.js +229 -0
  13. package/lib/attachments/AttachmentContext.js.map +1 -0
  14. package/lib/attachments/AttachmentErrorHandler.d.ts +31 -0
  15. package/lib/attachments/AttachmentErrorHandler.js +2 -0
  16. package/lib/attachments/AttachmentErrorHandler.js.map +1 -0
  17. package/lib/attachments/AttachmentQueue.d.ts +149 -0
  18. package/lib/attachments/AttachmentQueue.js +362 -0
  19. package/lib/attachments/AttachmentQueue.js.map +1 -0
  20. package/lib/attachments/AttachmentService.d.ts +29 -0
  21. package/lib/attachments/AttachmentService.js +56 -0
  22. package/lib/attachments/AttachmentService.js.map +1 -0
  23. package/lib/attachments/LocalStorageAdapter.d.ts +62 -0
  24. package/lib/attachments/LocalStorageAdapter.js +6 -0
  25. package/lib/attachments/LocalStorageAdapter.js.map +1 -0
  26. package/lib/attachments/RemoteStorageAdapter.d.ts +27 -0
  27. package/lib/attachments/RemoteStorageAdapter.js +2 -0
  28. package/lib/attachments/RemoteStorageAdapter.js.map +1 -0
  29. package/lib/attachments/Schema.d.ts +50 -0
  30. package/lib/attachments/Schema.js +62 -0
  31. package/lib/attachments/Schema.js.map +1 -0
  32. package/lib/attachments/SyncingService.d.ts +62 -0
  33. package/lib/attachments/SyncingService.js +168 -0
  34. package/lib/attachments/SyncingService.js.map +1 -0
  35. package/lib/attachments/WatchedAttachmentItem.d.ts +17 -0
  36. package/lib/attachments/WatchedAttachmentItem.js +2 -0
  37. package/lib/attachments/WatchedAttachmentItem.js.map +1 -0
  38. package/lib/client/AbstractPowerSyncDatabase.d.ts +8 -1
  39. package/lib/client/AbstractPowerSyncDatabase.js +16 -3
  40. package/lib/client/AbstractPowerSyncDatabase.js.map +1 -1
  41. package/lib/client/sync/stream/AbstractStreamingSyncImplementation.d.ts +7 -12
  42. package/lib/client/sync/stream/AbstractStreamingSyncImplementation.js +10 -12
  43. package/lib/client/sync/stream/AbstractStreamingSyncImplementation.js.map +1 -1
  44. package/lib/client/triggers/MemoryTriggerClaimManager.d.ts +6 -0
  45. package/lib/client/triggers/MemoryTriggerClaimManager.js +21 -0
  46. package/lib/client/triggers/MemoryTriggerClaimManager.js.map +1 -0
  47. package/lib/client/triggers/TriggerManager.d.ts +37 -0
  48. package/lib/client/triggers/TriggerManagerImpl.d.ts +24 -3
  49. package/lib/client/triggers/TriggerManagerImpl.js +133 -11
  50. package/lib/client/triggers/TriggerManagerImpl.js.map +1 -1
  51. package/lib/index.d.ts +12 -1
  52. package/lib/index.js +12 -1
  53. package/lib/index.js.map +1 -1
  54. package/package.json +1 -1
  55. package/src/attachments/AttachmentContext.ts +279 -0
  56. package/src/attachments/AttachmentErrorHandler.ts +34 -0
  57. package/src/attachments/AttachmentQueue.ts +472 -0
  58. package/src/attachments/AttachmentService.ts +62 -0
  59. package/src/attachments/LocalStorageAdapter.ts +72 -0
  60. package/src/attachments/README.md +718 -0
  61. package/src/attachments/RemoteStorageAdapter.ts +30 -0
  62. package/src/attachments/Schema.ts +87 -0
  63. package/src/attachments/SyncingService.ts +193 -0
  64. package/src/attachments/WatchedAttachmentItem.ts +19 -0
  65. package/src/client/AbstractPowerSyncDatabase.ts +19 -4
  66. package/src/client/sync/stream/AbstractStreamingSyncImplementation.ts +10 -12
  67. package/src/client/triggers/MemoryTriggerClaimManager.ts +25 -0
  68. package/src/client/triggers/TriggerManager.ts +50 -6
  69. package/src/client/triggers/TriggerManagerImpl.ts +177 -13
  70. package/src/index.ts +13 -1
@@ -2,6 +2,1211 @@ import { Mutex } from 'async-mutex';
2
2
  import { EventIterator } from 'event-iterator';
3
3
  import { Buffer } from 'node:buffer';
4
4
 
5
+ // https://www.sqlite.org/lang_expr.html#castexpr
6
+ var ColumnType;
7
+ (function (ColumnType) {
8
+ ColumnType["TEXT"] = "TEXT";
9
+ ColumnType["INTEGER"] = "INTEGER";
10
+ ColumnType["REAL"] = "REAL";
11
+ })(ColumnType || (ColumnType = {}));
12
+ const text = {
13
+ type: ColumnType.TEXT
14
+ };
15
+ const integer = {
16
+ type: ColumnType.INTEGER
17
+ };
18
+ const real = {
19
+ type: ColumnType.REAL
20
+ };
21
+ // powersync-sqlite-core limits the number of column per table to 1999, due to internal SQLite limits.
22
+ // In earlier versions this was limited to 63.
23
+ const MAX_AMOUNT_OF_COLUMNS = 1999;
24
+ const column = {
25
+ text,
26
+ integer,
27
+ real
28
+ };
29
+ class Column {
30
+ options;
31
+ constructor(options) {
32
+ this.options = options;
33
+ }
34
+ get name() {
35
+ return this.options.name;
36
+ }
37
+ get type() {
38
+ return this.options.type;
39
+ }
40
+ toJSON() {
41
+ return {
42
+ name: this.name,
43
+ type: this.type
44
+ };
45
+ }
46
+ }
47
+
48
+ const DEFAULT_INDEX_COLUMN_OPTIONS = {
49
+ ascending: true
50
+ };
51
+ class IndexedColumn {
52
+ options;
53
+ static createAscending(column) {
54
+ return new IndexedColumn({
55
+ name: column,
56
+ ascending: true
57
+ });
58
+ }
59
+ constructor(options) {
60
+ this.options = { ...DEFAULT_INDEX_COLUMN_OPTIONS, ...options };
61
+ }
62
+ get name() {
63
+ return this.options.name;
64
+ }
65
+ get ascending() {
66
+ return this.options.ascending;
67
+ }
68
+ toJSON(table) {
69
+ return {
70
+ name: this.name,
71
+ ascending: this.ascending,
72
+ type: table.columns.find((column) => column.name === this.name)?.type ?? ColumnType.TEXT
73
+ };
74
+ }
75
+ }
76
+
77
+ const DEFAULT_INDEX_OPTIONS = {
78
+ columns: []
79
+ };
80
+ class Index {
81
+ options;
82
+ static createAscending(options, columnNames) {
83
+ return new Index({
84
+ ...options,
85
+ columns: columnNames.map((name) => IndexedColumn.createAscending(name))
86
+ });
87
+ }
88
+ constructor(options) {
89
+ this.options = options;
90
+ this.options = { ...DEFAULT_INDEX_OPTIONS, ...options };
91
+ }
92
+ get name() {
93
+ return this.options.name;
94
+ }
95
+ get columns() {
96
+ return this.options.columns ?? [];
97
+ }
98
+ toJSON(table) {
99
+ return {
100
+ name: this.name,
101
+ columns: this.columns.map((c) => c.toJSON(table))
102
+ };
103
+ }
104
+ }
105
+
106
+ const DEFAULT_TABLE_OPTIONS = {
107
+ indexes: [],
108
+ insertOnly: false,
109
+ localOnly: false,
110
+ trackPrevious: false,
111
+ trackMetadata: false,
112
+ ignoreEmptyUpdates: false
113
+ };
114
+ const InvalidSQLCharacters = /["'%,.#\s[\]]/;
115
+ class Table {
116
+ options;
117
+ _mappedColumns;
118
+ static createLocalOnly(options) {
119
+ return new Table({ ...options, localOnly: true, insertOnly: false });
120
+ }
121
+ static createInsertOnly(options) {
122
+ return new Table({ ...options, localOnly: false, insertOnly: true });
123
+ }
124
+ /**
125
+ * Create a table.
126
+ * @deprecated This was only only included for TableV2 and is no longer necessary.
127
+ * Prefer to use new Table() directly.
128
+ *
129
+ * TODO remove in the next major release.
130
+ */
131
+ static createTable(name, table) {
132
+ return new Table({
133
+ name,
134
+ columns: table.columns,
135
+ indexes: table.indexes,
136
+ localOnly: table.options.localOnly,
137
+ insertOnly: table.options.insertOnly,
138
+ viewName: table.options.viewName
139
+ });
140
+ }
141
+ constructor(optionsOrColumns, v2Options) {
142
+ if (this.isTableV1(optionsOrColumns)) {
143
+ this.initTableV1(optionsOrColumns);
144
+ }
145
+ else {
146
+ this.initTableV2(optionsOrColumns, v2Options);
147
+ }
148
+ }
149
+ copyWithName(name) {
150
+ return new Table({
151
+ ...this.options,
152
+ name
153
+ });
154
+ }
155
+ isTableV1(arg) {
156
+ return 'columns' in arg && Array.isArray(arg.columns);
157
+ }
158
+ initTableV1(options) {
159
+ this.options = {
160
+ ...options,
161
+ indexes: options.indexes || []
162
+ };
163
+ this.applyDefaultOptions();
164
+ }
165
+ initTableV2(columns, options) {
166
+ const convertedColumns = Object.entries(columns).map(([name, columnInfo]) => new Column({ name, type: columnInfo.type }));
167
+ const convertedIndexes = Object.entries(options?.indexes ?? {}).map(([name, columnNames]) => new Index({
168
+ name,
169
+ columns: columnNames.map((name) => new IndexedColumn({
170
+ name: name.replace(/^-/, ''),
171
+ ascending: !name.startsWith('-')
172
+ }))
173
+ }));
174
+ this.options = {
175
+ name: '',
176
+ columns: convertedColumns,
177
+ indexes: convertedIndexes,
178
+ viewName: options?.viewName,
179
+ insertOnly: options?.insertOnly,
180
+ localOnly: options?.localOnly,
181
+ trackPrevious: options?.trackPrevious,
182
+ trackMetadata: options?.trackMetadata,
183
+ ignoreEmptyUpdates: options?.ignoreEmptyUpdates
184
+ };
185
+ this.applyDefaultOptions();
186
+ this._mappedColumns = columns;
187
+ }
188
+ applyDefaultOptions() {
189
+ this.options.insertOnly ??= DEFAULT_TABLE_OPTIONS.insertOnly;
190
+ this.options.localOnly ??= DEFAULT_TABLE_OPTIONS.localOnly;
191
+ this.options.trackPrevious ??= DEFAULT_TABLE_OPTIONS.trackPrevious;
192
+ this.options.trackMetadata ??= DEFAULT_TABLE_OPTIONS.trackMetadata;
193
+ this.options.ignoreEmptyUpdates ??= DEFAULT_TABLE_OPTIONS.ignoreEmptyUpdates;
194
+ }
195
+ get name() {
196
+ return this.options.name;
197
+ }
198
+ get viewNameOverride() {
199
+ return this.options.viewName;
200
+ }
201
+ get viewName() {
202
+ return this.viewNameOverride ?? this.name;
203
+ }
204
+ get columns() {
205
+ return this.options.columns;
206
+ }
207
+ get columnMap() {
208
+ return (this._mappedColumns ??
209
+ this.columns.reduce((hash, column) => {
210
+ hash[column.name] = { type: column.type ?? ColumnType.TEXT };
211
+ return hash;
212
+ }, {}));
213
+ }
214
+ get indexes() {
215
+ return this.options.indexes ?? [];
216
+ }
217
+ get localOnly() {
218
+ return this.options.localOnly;
219
+ }
220
+ get insertOnly() {
221
+ return this.options.insertOnly;
222
+ }
223
+ get trackPrevious() {
224
+ return this.options.trackPrevious;
225
+ }
226
+ get trackMetadata() {
227
+ return this.options.trackMetadata;
228
+ }
229
+ get ignoreEmptyUpdates() {
230
+ return this.options.ignoreEmptyUpdates;
231
+ }
232
+ get internalName() {
233
+ if (this.options.localOnly) {
234
+ return `ps_data_local__${this.name}`;
235
+ }
236
+ return `ps_data__${this.name}`;
237
+ }
238
+ get validName() {
239
+ if (InvalidSQLCharacters.test(this.name)) {
240
+ return false;
241
+ }
242
+ if (this.viewNameOverride != null && InvalidSQLCharacters.test(this.viewNameOverride)) {
243
+ return false;
244
+ }
245
+ return true;
246
+ }
247
+ validate() {
248
+ if (InvalidSQLCharacters.test(this.name)) {
249
+ throw new Error(`Invalid characters in table name: ${this.name}`);
250
+ }
251
+ if (this.viewNameOverride && InvalidSQLCharacters.test(this.viewNameOverride)) {
252
+ throw new Error(`Invalid characters in view name: ${this.viewNameOverride}`);
253
+ }
254
+ if (this.columns.length > MAX_AMOUNT_OF_COLUMNS) {
255
+ throw new Error(`Table has too many columns. The maximum number of columns is ${MAX_AMOUNT_OF_COLUMNS}.`);
256
+ }
257
+ if (this.trackMetadata && this.localOnly) {
258
+ throw new Error(`Can't include metadata for local-only tables.`);
259
+ }
260
+ if (this.trackPrevious != false && this.localOnly) {
261
+ throw new Error(`Can't include old values for local-only tables.`);
262
+ }
263
+ const columnNames = new Set();
264
+ columnNames.add('id');
265
+ for (const column of this.columns) {
266
+ const { name: columnName } = column;
267
+ if (column.name === 'id') {
268
+ throw new Error(`An id column is automatically added, custom id columns are not supported`);
269
+ }
270
+ if (columnNames.has(columnName)) {
271
+ throw new Error(`Duplicate column ${columnName}`);
272
+ }
273
+ if (InvalidSQLCharacters.test(columnName)) {
274
+ throw new Error(`Invalid characters in column name: ${column.name}`);
275
+ }
276
+ columnNames.add(columnName);
277
+ }
278
+ const indexNames = new Set();
279
+ for (const index of this.indexes) {
280
+ if (indexNames.has(index.name)) {
281
+ throw new Error(`Duplicate index ${index.name}`);
282
+ }
283
+ if (InvalidSQLCharacters.test(index.name)) {
284
+ throw new Error(`Invalid characters in index name: ${index.name}`);
285
+ }
286
+ for (const column of index.columns) {
287
+ if (!columnNames.has(column.name)) {
288
+ throw new Error(`Column ${column.name} not found for index ${index.name}`);
289
+ }
290
+ }
291
+ indexNames.add(index.name);
292
+ }
293
+ }
294
+ toJSON() {
295
+ const trackPrevious = this.trackPrevious;
296
+ return {
297
+ name: this.name,
298
+ view_name: this.viewName,
299
+ local_only: this.localOnly,
300
+ insert_only: this.insertOnly,
301
+ include_old: trackPrevious && (trackPrevious.columns ?? true),
302
+ include_old_only_when_changed: typeof trackPrevious == 'object' && trackPrevious.onlyWhenChanged == true,
303
+ include_metadata: this.trackMetadata,
304
+ ignore_empty_update: this.ignoreEmptyUpdates,
305
+ columns: this.columns.map((c) => c.toJSON()),
306
+ indexes: this.indexes.map((e) => e.toJSON(this))
307
+ };
308
+ }
309
+ }
310
+
311
+ const ATTACHMENT_TABLE = 'attachments';
312
+ /**
313
+ * Maps a database row to an AttachmentRecord.
314
+ *
315
+ * @param row - The database row object
316
+ * @returns The corresponding AttachmentRecord
317
+ *
318
+ * @experimental
319
+ */
320
+ function attachmentFromSql(row) {
321
+ return {
322
+ id: row.id,
323
+ filename: row.filename,
324
+ localUri: row.local_uri,
325
+ size: row.size,
326
+ mediaType: row.media_type,
327
+ timestamp: row.timestamp,
328
+ metaData: row.meta_data,
329
+ hasSynced: row.has_synced === 1,
330
+ state: row.state
331
+ };
332
+ }
333
+ /**
334
+ * AttachmentState represents the current synchronization state of an attachment.
335
+ *
336
+ * @experimental
337
+ */
338
+ var AttachmentState;
339
+ (function (AttachmentState) {
340
+ AttachmentState[AttachmentState["QUEUED_UPLOAD"] = 0] = "QUEUED_UPLOAD";
341
+ AttachmentState[AttachmentState["QUEUED_DOWNLOAD"] = 1] = "QUEUED_DOWNLOAD";
342
+ AttachmentState[AttachmentState["QUEUED_DELETE"] = 2] = "QUEUED_DELETE";
343
+ AttachmentState[AttachmentState["SYNCED"] = 3] = "SYNCED";
344
+ AttachmentState[AttachmentState["ARCHIVED"] = 4] = "ARCHIVED"; // Attachment has been orphaned, i.e. the associated record has been deleted
345
+ })(AttachmentState || (AttachmentState = {}));
346
+ /**
347
+ * AttachmentTable defines the schema for the attachment queue table.
348
+ *
349
+ * @internal
350
+ */
351
+ class AttachmentTable extends Table {
352
+ constructor(options) {
353
+ super({
354
+ filename: column.text,
355
+ local_uri: column.text,
356
+ timestamp: column.integer,
357
+ size: column.integer,
358
+ media_type: column.text,
359
+ state: column.integer, // Corresponds to AttachmentState
360
+ has_synced: column.integer,
361
+ meta_data: column.text
362
+ }, {
363
+ ...options,
364
+ viewName: options?.viewName ?? ATTACHMENT_TABLE,
365
+ localOnly: true,
366
+ insertOnly: false
367
+ });
368
+ }
369
+ }
370
+
371
+ /**
372
+ * AttachmentContext provides database operations for managing attachment records.
373
+ *
374
+ * Provides methods to query, insert, update, and delete attachment records with
375
+ * proper transaction management through PowerSync.
376
+ *
377
+ * @internal
378
+ */
379
+ class AttachmentContext {
380
+ /** PowerSync database instance for executing queries */
381
+ db;
382
+ /** Name of the database table storing attachment records */
383
+ tableName;
384
+ /** Logger instance for diagnostic information */
385
+ logger;
386
+ /** Maximum number of archived attachments to keep before cleanup */
387
+ archivedCacheLimit = 100;
388
+ /**
389
+ * Creates a new AttachmentContext instance.
390
+ *
391
+ * @param db - PowerSync database instance
392
+ * @param tableName - Name of the table storing attachment records. Default: 'attachments'
393
+ * @param logger - Logger instance for diagnostic output
394
+ */
395
+ constructor(db, tableName = 'attachments', logger, archivedCacheLimit) {
396
+ this.db = db;
397
+ this.tableName = tableName;
398
+ this.logger = logger;
399
+ this.archivedCacheLimit = archivedCacheLimit;
400
+ }
401
+ /**
402
+ * Retrieves all active attachments that require synchronization.
403
+ * Active attachments include those queued for upload, download, or delete.
404
+ * Results are ordered by timestamp in ascending order.
405
+ *
406
+ * @returns Promise resolving to an array of active attachment records
407
+ */
408
+ async getActiveAttachments() {
409
+ const attachments = await this.db.getAll(
410
+ /* sql */
411
+ `
412
+ SELECT
413
+ *
414
+ FROM
415
+ ${this.tableName}
416
+ WHERE
417
+ state = ?
418
+ OR state = ?
419
+ OR state = ?
420
+ ORDER BY
421
+ timestamp ASC
422
+ `, [AttachmentState.QUEUED_UPLOAD, AttachmentState.QUEUED_DOWNLOAD, AttachmentState.QUEUED_DELETE]);
423
+ return attachments.map(attachmentFromSql);
424
+ }
425
+ /**
426
+ * Retrieves all archived attachments.
427
+ *
428
+ * Archived attachments are no longer referenced but haven't been permanently deleted.
429
+ * These are candidates for cleanup operations to free up storage space.
430
+ *
431
+ * @returns Promise resolving to an array of archived attachment records
432
+ */
433
+ async getArchivedAttachments() {
434
+ const attachments = await this.db.getAll(
435
+ /* sql */
436
+ `
437
+ SELECT
438
+ *
439
+ FROM
440
+ ${this.tableName}
441
+ WHERE
442
+ state = ?
443
+ ORDER BY
444
+ timestamp ASC
445
+ `, [AttachmentState.ARCHIVED]);
446
+ return attachments.map(attachmentFromSql);
447
+ }
448
+ /**
449
+ * Retrieves all attachment records regardless of state.
450
+ * Results are ordered by timestamp in ascending order.
451
+ *
452
+ * @returns Promise resolving to an array of all attachment records
453
+ */
454
+ async getAttachments() {
455
+ const attachments = await this.db.getAll(
456
+ /* sql */
457
+ `
458
+ SELECT
459
+ *
460
+ FROM
461
+ ${this.tableName}
462
+ ORDER BY
463
+ timestamp ASC
464
+ `, []);
465
+ return attachments.map(attachmentFromSql);
466
+ }
467
+ /**
468
+ * Inserts or updates an attachment record within an existing transaction.
469
+ *
470
+ * Performs an upsert operation (INSERT OR REPLACE). Must be called within
471
+ * an active database transaction context.
472
+ *
473
+ * @param attachment - The attachment record to upsert
474
+ * @param context - Active database transaction context
475
+ */
476
+ async upsertAttachment(attachment, context) {
477
+ await context.execute(
478
+ /* sql */
479
+ `
480
+ INSERT
481
+ OR REPLACE INTO ${this.tableName} (
482
+ id,
483
+ filename,
484
+ local_uri,
485
+ size,
486
+ media_type,
487
+ timestamp,
488
+ state,
489
+ has_synced,
490
+ meta_data
491
+ )
492
+ VALUES
493
+ (?, ?, ?, ?, ?, ?, ?, ?, ?)
494
+ `, [
495
+ attachment.id,
496
+ attachment.filename,
497
+ attachment.localUri || null,
498
+ attachment.size || null,
499
+ attachment.mediaType || null,
500
+ attachment.timestamp,
501
+ attachment.state,
502
+ attachment.hasSynced ? 1 : 0,
503
+ attachment.metaData || null
504
+ ]);
505
+ }
506
+ async getAttachment(id) {
507
+ const attachment = await this.db.get(
508
+ /* sql */
509
+ `
510
+ SELECT
511
+ *
512
+ FROM
513
+ ${this.tableName}
514
+ WHERE
515
+ id = ?
516
+ `, [id]);
517
+ return attachment ? attachmentFromSql(attachment) : undefined;
518
+ }
519
+ /**
520
+ * Permanently deletes an attachment record from the database.
521
+ *
522
+ * This operation removes the attachment record but does not delete
523
+ * the associated local or remote files. File deletion should be handled
524
+ * separately through the appropriate storage adapters.
525
+ *
526
+ * @param attachmentId - Unique identifier of the attachment to delete
527
+ */
528
+ async deleteAttachment(attachmentId) {
529
+ await this.db.writeTransaction((tx) => tx.execute(
530
+ /* sql */
531
+ `
532
+ DELETE FROM ${this.tableName}
533
+ WHERE
534
+ id = ?
535
+ `, [attachmentId]));
536
+ }
537
+ async clearQueue() {
538
+ await this.db.writeTransaction((tx) => tx.execute(/* sql */ ` DELETE FROM ${this.tableName} `));
539
+ }
540
+ async deleteArchivedAttachments(callback) {
541
+ const limit = 1000;
542
+ const results = await this.db.getAll(
543
+ /* sql */
544
+ `
545
+ SELECT
546
+ *
547
+ FROM
548
+ ${this.tableName}
549
+ WHERE
550
+ state = ?
551
+ ORDER BY
552
+ timestamp DESC
553
+ LIMIT
554
+ ?
555
+ OFFSET
556
+ ?
557
+ `, [AttachmentState.ARCHIVED, limit, this.archivedCacheLimit]);
558
+ const archivedAttachments = results.map(attachmentFromSql);
559
+ if (archivedAttachments.length === 0)
560
+ return false;
561
+ await callback?.(archivedAttachments);
562
+ this.logger.info(`Deleting ${archivedAttachments.length} archived attachments. Archived attachment exceeds cache archiveCacheLimit of ${this.archivedCacheLimit}.`);
563
+ const ids = archivedAttachments.map((attachment) => attachment.id);
564
+ await this.db.execute(
565
+ /* sql */
566
+ `
567
+ DELETE FROM ${this.tableName}
568
+ WHERE
569
+ id IN (
570
+ SELECT
571
+ json_each.value
572
+ FROM
573
+ json_each (?)
574
+ );
575
+ `, [JSON.stringify(ids)]);
576
+ this.logger.info(`Deleted ${archivedAttachments.length} archived attachments`);
577
+ return archivedAttachments.length < limit;
578
+ }
579
+ /**
580
+ * Saves multiple attachment records in a single transaction.
581
+ *
582
+ * All updates are saved in a single batch after processing.
583
+ * If the attachments array is empty, no database operations are performed.
584
+ *
585
+ * @param attachments - Array of attachment records to save
586
+ */
587
+ async saveAttachments(attachments) {
588
+ if (attachments.length === 0) {
589
+ return;
590
+ }
591
+ await this.db.writeTransaction(async (tx) => {
592
+ for (const attachment of attachments) {
593
+ await this.upsertAttachment(attachment, tx);
594
+ }
595
+ });
596
+ }
597
+ }
598
+
599
+ var WatchedQueryListenerEvent;
600
+ (function (WatchedQueryListenerEvent) {
601
+ WatchedQueryListenerEvent["ON_DATA"] = "onData";
602
+ WatchedQueryListenerEvent["ON_ERROR"] = "onError";
603
+ WatchedQueryListenerEvent["ON_STATE_CHANGE"] = "onStateChange";
604
+ WatchedQueryListenerEvent["SETTINGS_WILL_UPDATE"] = "settingsWillUpdate";
605
+ WatchedQueryListenerEvent["CLOSED"] = "closed";
606
+ })(WatchedQueryListenerEvent || (WatchedQueryListenerEvent = {}));
607
+ const DEFAULT_WATCH_THROTTLE_MS = 30;
608
+ const DEFAULT_WATCH_QUERY_OPTIONS = {
609
+ throttleMs: DEFAULT_WATCH_THROTTLE_MS,
610
+ reportFetching: true
611
+ };
612
+
613
+ /**
614
+ * Orchestrates attachment synchronization between local and remote storage.
615
+ * Handles uploads, downloads, deletions, and state transitions.
616
+ *
617
+ * @internal
618
+ */
619
+ class SyncingService {
620
+ attachmentService;
621
+ localStorage;
622
+ remoteStorage;
623
+ logger;
624
+ errorHandler;
625
+ constructor(attachmentService, localStorage, remoteStorage, logger, errorHandler) {
626
+ this.attachmentService = attachmentService;
627
+ this.localStorage = localStorage;
628
+ this.remoteStorage = remoteStorage;
629
+ this.logger = logger;
630
+ this.errorHandler = errorHandler;
631
+ }
632
+ /**
633
+ * Processes attachments based on their state (upload, download, or delete).
634
+ * All updates are saved in a single batch after processing.
635
+ *
636
+ * @param attachments - Array of attachment records to process
637
+ * @param context - Attachment context for database operations
638
+ * @returns Promise that resolves when all attachments have been processed and saved
639
+ */
640
+ async processAttachments(attachments, context) {
641
+ const updatedAttachments = [];
642
+ for (const attachment of attachments) {
643
+ switch (attachment.state) {
644
+ case AttachmentState.QUEUED_UPLOAD:
645
+ const uploaded = await this.uploadAttachment(attachment);
646
+ updatedAttachments.push(uploaded);
647
+ break;
648
+ case AttachmentState.QUEUED_DOWNLOAD:
649
+ const downloaded = await this.downloadAttachment(attachment);
650
+ updatedAttachments.push(downloaded);
651
+ break;
652
+ case AttachmentState.QUEUED_DELETE:
653
+ const deleted = await this.deleteAttachment(attachment);
654
+ updatedAttachments.push(deleted);
655
+ break;
656
+ }
657
+ }
658
+ await context.saveAttachments(updatedAttachments);
659
+ }
660
+ /**
661
+ * Uploads an attachment from local storage to remote storage.
662
+ * On success, marks as SYNCED. On failure, defers to error handler or archives.
663
+ *
664
+ * @param attachment - The attachment record to upload
665
+ * @returns Updated attachment record with new state
666
+ * @throws Error if the attachment has no localUri
667
+ */
668
+ async uploadAttachment(attachment) {
669
+ this.logger.info(`Uploading attachment ${attachment.filename}`);
670
+ try {
671
+ if (attachment.localUri == null) {
672
+ throw new Error(`No localUri for attachment ${attachment.id}`);
673
+ }
674
+ const fileBlob = await this.localStorage.readFile(attachment.localUri);
675
+ await this.remoteStorage.uploadFile(fileBlob, attachment);
676
+ return {
677
+ ...attachment,
678
+ state: AttachmentState.SYNCED,
679
+ hasSynced: true
680
+ };
681
+ }
682
+ catch (error) {
683
+ const shouldRetry = (await this.errorHandler?.onUploadError(attachment, error)) ?? true;
684
+ if (!shouldRetry) {
685
+ return {
686
+ ...attachment,
687
+ state: AttachmentState.ARCHIVED
688
+ };
689
+ }
690
+ return attachment;
691
+ }
692
+ }
693
+ /**
694
+ * Downloads an attachment from remote storage to local storage.
695
+ * Retrieves the file, converts to base64, and saves locally.
696
+ * On success, marks as SYNCED. On failure, defers to error handler or archives.
697
+ *
698
+ * @param attachment - The attachment record to download
699
+ * @returns Updated attachment record with local URI and new state
700
+ */
701
+ async downloadAttachment(attachment) {
702
+ this.logger.info(`Downloading attachment ${attachment.filename}`);
703
+ try {
704
+ const fileData = await this.remoteStorage.downloadFile(attachment);
705
+ const localUri = this.localStorage.getLocalUri(attachment.filename);
706
+ await this.localStorage.saveFile(localUri, fileData);
707
+ return {
708
+ ...attachment,
709
+ state: AttachmentState.SYNCED,
710
+ localUri: localUri,
711
+ hasSynced: true
712
+ };
713
+ }
714
+ catch (error) {
715
+ const shouldRetry = (await this.errorHandler?.onDownloadError(attachment, error)) ?? true;
716
+ if (!shouldRetry) {
717
+ return {
718
+ ...attachment,
719
+ state: AttachmentState.ARCHIVED
720
+ };
721
+ }
722
+ return attachment;
723
+ }
724
+ }
725
+ /**
726
+ * Deletes an attachment from both remote and local storage.
727
+ * Removes the remote file, local file (if exists), and the attachment record.
728
+ * On failure, defers to error handler or archives.
729
+ *
730
+ * @param attachment - The attachment record to delete
731
+ * @returns Updated attachment record
732
+ */
733
+ async deleteAttachment(attachment) {
734
+ try {
735
+ await this.remoteStorage.deleteFile(attachment);
736
+ if (attachment.localUri) {
737
+ await this.localStorage.deleteFile(attachment.localUri);
738
+ }
739
+ await this.attachmentService.withContext(async (ctx) => {
740
+ await ctx.deleteAttachment(attachment.id);
741
+ });
742
+ return {
743
+ ...attachment,
744
+ state: AttachmentState.ARCHIVED
745
+ };
746
+ }
747
+ catch (error) {
748
+ const shouldRetry = (await this.errorHandler?.onDeleteError(attachment, error)) ?? true;
749
+ if (!shouldRetry) {
750
+ return {
751
+ ...attachment,
752
+ state: AttachmentState.ARCHIVED
753
+ };
754
+ }
755
+ return attachment;
756
+ }
757
+ }
758
+ /**
759
+ * Performs cleanup of archived attachments by removing their local files and records.
760
+ * Errors during local file deletion are logged but do not prevent record deletion.
761
+ */
762
+ async deleteArchivedAttachments(context) {
763
+ return await context.deleteArchivedAttachments(async (archivedAttachments) => {
764
+ for (const attachment of archivedAttachments) {
765
+ if (attachment.localUri) {
766
+ try {
767
+ await this.localStorage.deleteFile(attachment.localUri);
768
+ }
769
+ catch (error) {
770
+ this.logger.error('Error deleting local file for archived attachment', error);
771
+ }
772
+ }
773
+ }
774
+ });
775
+ }
776
+ }
777
+
778
+ /**
779
+ * Wrapper for async-mutex runExclusive, which allows for a timeout on each exclusive lock.
780
+ */
781
+ async function mutexRunExclusive(mutex, callback, options) {
782
+ return new Promise((resolve, reject) => {
783
+ mutex.runExclusive(async () => {
784
+ try {
785
+ resolve(await callback());
786
+ }
787
+ catch (ex) {
788
+ reject(ex);
789
+ }
790
+ });
791
+ });
792
+ }
793
+
794
+ /**
795
+ * Service for querying and watching attachment records in the database.
796
+ *
797
+ * @internal
798
+ */
799
+ class AttachmentService {
800
+ db;
801
+ logger;
802
+ tableName;
803
+ mutex = new Mutex();
804
+ context;
805
+ constructor(db, logger, tableName = 'attachments', archivedCacheLimit = 100) {
806
+ this.db = db;
807
+ this.logger = logger;
808
+ this.tableName = tableName;
809
+ this.context = new AttachmentContext(db, tableName, logger, archivedCacheLimit);
810
+ }
811
+ /**
812
+ * Creates a differential watch query for active attachments requiring synchronization.
813
+ * @returns Watch query that emits changes for queued uploads, downloads, and deletes
814
+ */
815
+ watchActiveAttachments({ throttleMs } = {}) {
816
+ this.logger.info('Watching active attachments...');
817
+ const watch = this.db
818
+ .query({
819
+ sql: /* sql */ `
820
+ SELECT
821
+ *
822
+ FROM
823
+ ${this.tableName}
824
+ WHERE
825
+ state = ?
826
+ OR state = ?
827
+ OR state = ?
828
+ ORDER BY
829
+ timestamp ASC
830
+ `,
831
+ parameters: [AttachmentState.QUEUED_UPLOAD, AttachmentState.QUEUED_DOWNLOAD, AttachmentState.QUEUED_DELETE]
832
+ })
833
+ .differentialWatch({ throttleMs });
834
+ return watch;
835
+ }
836
+ /**
837
+ * Executes a callback with exclusive access to the attachment context.
838
+ */
839
+ async withContext(callback) {
840
+ return mutexRunExclusive(this.mutex, async () => {
841
+ return callback(this.context);
842
+ });
843
+ }
844
+ }
845
+
846
+ /**
847
+ * AttachmentQueue manages the lifecycle and synchronization of attachments
848
+ * between local and remote storage.
849
+ * Provides automatic synchronization, upload/download queuing, attachment monitoring,
850
+ * verification and repair of local files, and cleanup of archived attachments.
851
+ *
852
+ * @experimental
853
+ * @alpha This is currently experimental and may change without a major version bump.
854
+ */
855
+ class AttachmentQueue {
856
+ /** Timer for periodic synchronization operations */
857
+ periodicSyncTimer;
858
+ /** Service for synchronizing attachments between local and remote storage */
859
+ syncingService;
860
+ /** Adapter for local file storage operations */
861
+ localStorage;
862
+ /** Adapter for remote file storage operations */
863
+ remoteStorage;
864
+ /**
865
+ * Callback function to watch for changes in attachment references in your data model.
866
+ *
867
+ * This should be implemented by the user of AttachmentQueue to monitor changes in your application's
868
+ * data that reference attachments. When attachments are added, removed, or modified,
869
+ * this callback should trigger the onUpdate function with the current set of attachments.
870
+ */
871
+ watchAttachments;
872
+ /** Name of the database table storing attachment records */
873
+ tableName;
874
+ /** Logger instance for diagnostic information */
875
+ logger;
876
+ /** Interval in milliseconds between periodic sync operations. Default: 30000 (30 seconds) */
877
+ syncIntervalMs = 30 * 1000;
878
+ /** Duration in milliseconds to throttle sync operations */
879
+ syncThrottleDuration;
880
+ /** Whether to automatically download remote attachments. Default: true */
881
+ downloadAttachments = true;
882
+ /** Maximum number of archived attachments to keep before cleanup. Default: 100 */
883
+ archivedCacheLimit;
884
+ /** Service for managing attachment-related database operations */
885
+ attachmentService;
886
+ /** PowerSync database instance */
887
+ db;
888
+ /** Cleanup function for status change listener */
889
+ statusListenerDispose;
890
+ watchActiveAttachments;
891
+ watchAttachmentsAbortController;
892
+ /**
893
+ * Creates a new AttachmentQueue instance.
894
+ *
895
+ * @param options - Configuration options
896
+ * @param options.db - PowerSync database instance
897
+ * @param options.remoteStorage - Remote storage adapter for upload/download operations
898
+ * @param options.localStorage - Local storage adapter for file persistence
899
+ * @param options.watchAttachments - Callback for monitoring attachment changes in your data model
900
+ * @param options.tableName - Name of the table to store attachment records. Default: 'ps_attachment_queue'
901
+ * @param options.logger - Logger instance. Defaults to db.logger
902
+ * @param options.syncIntervalMs - Interval between automatic syncs in milliseconds. Default: 30000
903
+ * @param options.syncThrottleDuration - Throttle duration for sync operations in milliseconds. Default: 1000
904
+ * @param options.downloadAttachments - Whether to automatically download remote attachments. Default: true
905
+ * @param options.archivedCacheLimit - Maximum archived attachments before cleanup. Default: 100
906
+ */
907
+ constructor({ db, localStorage, remoteStorage, watchAttachments, logger, tableName = ATTACHMENT_TABLE, syncIntervalMs = 30 * 1000, syncThrottleDuration = DEFAULT_WATCH_THROTTLE_MS, downloadAttachments = true, archivedCacheLimit = 100, errorHandler }) {
908
+ this.db = db;
909
+ this.remoteStorage = remoteStorage;
910
+ this.localStorage = localStorage;
911
+ this.watchAttachments = watchAttachments;
912
+ this.tableName = tableName;
913
+ this.syncIntervalMs = syncIntervalMs;
914
+ this.syncThrottleDuration = syncThrottleDuration;
915
+ this.archivedCacheLimit = archivedCacheLimit;
916
+ this.downloadAttachments = downloadAttachments;
917
+ this.logger = logger ?? db.logger;
918
+ this.attachmentService = new AttachmentService(db, this.logger, tableName, archivedCacheLimit);
919
+ this.syncingService = new SyncingService(this.attachmentService, localStorage, remoteStorage, this.logger, errorHandler);
920
+ }
921
+ /**
922
+ * Generates a new attachment ID using a SQLite UUID function.
923
+ *
924
+ * @returns Promise resolving to the new attachment ID
925
+ */
926
+ async generateAttachmentId() {
927
+ return this.db.get('SELECT uuid() as id').then((row) => row.id);
928
+ }
929
+ /**
930
+ * Starts the attachment synchronization process.
931
+ *
932
+ * This method:
933
+ * - Stops any existing sync operations
934
+ * - Sets up periodic synchronization based on syncIntervalMs
935
+ * - Registers listeners for active attachment changes
936
+ * - Processes watched attachments to queue uploads/downloads
937
+ * - Handles state transitions for archived and new attachments
938
+ */
939
+ async startSync() {
940
+ await this.stopSync();
941
+ this.watchActiveAttachments = this.attachmentService.watchActiveAttachments({
942
+ throttleMs: this.syncThrottleDuration
943
+ });
944
+ // immediately invoke the sync storage to initialize local storage
945
+ await this.localStorage.initialize();
946
+ await this.verifyAttachments();
947
+ // Sync storage periodically
948
+ this.periodicSyncTimer = setInterval(async () => {
949
+ await this.syncStorage();
950
+ }, this.syncIntervalMs);
951
+ // Sync storage when there is a change in active attachments
952
+ this.watchActiveAttachments.registerListener({
953
+ onDiff: async () => {
954
+ await this.syncStorage();
955
+ }
956
+ });
957
+ this.statusListenerDispose = this.db.registerListener({
958
+ statusChanged: (status) => {
959
+ if (status.connected) {
960
+ // Device came online, process attachments immediately
961
+ this.syncStorage().catch((error) => {
962
+ this.logger.error('Error syncing storage on connection:', error);
963
+ });
964
+ }
965
+ }
966
+ });
967
+ this.watchAttachmentsAbortController = new AbortController();
968
+ const signal = this.watchAttachmentsAbortController.signal;
969
+ // Process attachments when there is a change in watched attachments
970
+ this.watchAttachments(async (watchedAttachments) => {
971
+ // Skip processing if sync has been stopped
972
+ if (signal.aborted) {
973
+ return;
974
+ }
975
+ await this.attachmentService.withContext(async (ctx) => {
976
+ // Need to get all the attachments which are tracked in the DB.
977
+ // We might need to restore an archived attachment.
978
+ const currentAttachments = await ctx.getAttachments();
979
+ const attachmentUpdates = [];
980
+ for (const watchedAttachment of watchedAttachments) {
981
+ const existingQueueItem = currentAttachments.find((a) => a.id === watchedAttachment.id);
982
+ if (!existingQueueItem) {
983
+ // Item is watched but not in the queue yet. Need to add it.
984
+ if (!this.downloadAttachments) {
985
+ continue;
986
+ }
987
+ const filename = watchedAttachment.filename ?? `${watchedAttachment.id}.${watchedAttachment.fileExtension}`;
988
+ attachmentUpdates.push({
989
+ id: watchedAttachment.id,
990
+ filename,
991
+ state: AttachmentState.QUEUED_DOWNLOAD,
992
+ hasSynced: false,
993
+ metaData: watchedAttachment.metaData,
994
+ timestamp: new Date().getTime()
995
+ });
996
+ continue;
997
+ }
998
+ if (existingQueueItem.state === AttachmentState.ARCHIVED) {
999
+ // The attachment is present again. Need to queue it for sync.
1000
+ // We might be able to optimize this in future
1001
+ if (existingQueueItem.hasSynced === true) {
1002
+ // No remote action required, we can restore the record (avoids deletion)
1003
+ attachmentUpdates.push({
1004
+ ...existingQueueItem,
1005
+ state: AttachmentState.SYNCED
1006
+ });
1007
+ }
1008
+ else {
1009
+ // The localURI should be set if the record was meant to be uploaded
1010
+ // and hasSynced is false then
1011
+ // it must be an upload operation
1012
+ const newState = existingQueueItem.localUri == null ? AttachmentState.QUEUED_DOWNLOAD : AttachmentState.QUEUED_UPLOAD;
1013
+ attachmentUpdates.push({
1014
+ ...existingQueueItem,
1015
+ state: newState
1016
+ });
1017
+ }
1018
+ }
1019
+ }
1020
+ for (const attachment of currentAttachments) {
1021
+ const notInWatchedItems = watchedAttachments.find((i) => i.id === attachment.id) == null;
1022
+ if (notInWatchedItems) {
1023
+ switch (attachment.state) {
1024
+ case AttachmentState.QUEUED_DELETE:
1025
+ case AttachmentState.QUEUED_UPLOAD:
1026
+ // Only archive if it has synced
1027
+ if (attachment.hasSynced === true) {
1028
+ attachmentUpdates.push({
1029
+ ...attachment,
1030
+ state: AttachmentState.ARCHIVED
1031
+ });
1032
+ }
1033
+ break;
1034
+ default:
1035
+ // Archive other states such as QUEUED_DOWNLOAD
1036
+ attachmentUpdates.push({
1037
+ ...attachment,
1038
+ state: AttachmentState.ARCHIVED
1039
+ });
1040
+ }
1041
+ }
1042
+ }
1043
+ if (attachmentUpdates.length > 0) {
1044
+ await ctx.saveAttachments(attachmentUpdates);
1045
+ }
1046
+ });
1047
+ }, signal);
1048
+ }
1049
+ /**
1050
+ * Synchronizes all active attachments between local and remote storage.
1051
+ *
1052
+ * This is called automatically at regular intervals when sync is started,
1053
+ * but can also be called manually to trigger an immediate sync.
1054
+ */
1055
+ async syncStorage() {
1056
+ await this.attachmentService.withContext(async (ctx) => {
1057
+ const activeAttachments = await ctx.getActiveAttachments();
1058
+ await this.localStorage.initialize();
1059
+ await this.syncingService.processAttachments(activeAttachments, ctx);
1060
+ await this.syncingService.deleteArchivedAttachments(ctx);
1061
+ });
1062
+ }
1063
+ /**
1064
+ * Stops the attachment synchronization process.
1065
+ *
1066
+ * Clears the periodic sync timer and closes all active attachment watchers.
1067
+ */
1068
+ async stopSync() {
1069
+ clearInterval(this.periodicSyncTimer);
1070
+ this.periodicSyncTimer = undefined;
1071
+ if (this.watchActiveAttachments)
1072
+ await this.watchActiveAttachments.close();
1073
+ if (this.watchAttachmentsAbortController) {
1074
+ this.watchAttachmentsAbortController.abort();
1075
+ }
1076
+ if (this.statusListenerDispose) {
1077
+ this.statusListenerDispose();
1078
+ this.statusListenerDispose = undefined;
1079
+ }
1080
+ }
1081
+ /**
1082
+ * Saves a file to local storage and queues it for upload to remote storage.
1083
+ *
1084
+ * @param options - File save options
1085
+ * @param options.data - The file data as ArrayBuffer, Blob, or base64 string
1086
+ * @param options.fileExtension - File extension (e.g., 'jpg', 'pdf')
1087
+ * @param options.mediaType - MIME type of the file (e.g., 'image/jpeg')
1088
+ * @param options.metaData - Optional metadata to associate with the attachment
1089
+ * @param options.id - Optional custom ID. If not provided, a UUID will be generated
1090
+ * @param options.updateHook - Optional callback to execute additional database operations
1091
+ * within the same transaction as the attachment creation
1092
+ * @returns Promise resolving to the created attachment record
1093
+ */
1094
+ async saveFile({ data, fileExtension, mediaType, metaData, id, updateHook }) {
1095
+ const resolvedId = id ?? (await this.generateAttachmentId());
1096
+ const filename = `${resolvedId}.${fileExtension}`;
1097
+ const localUri = this.localStorage.getLocalUri(filename);
1098
+ const size = await this.localStorage.saveFile(localUri, data);
1099
+ const attachment = {
1100
+ id: resolvedId,
1101
+ filename,
1102
+ mediaType,
1103
+ localUri,
1104
+ state: AttachmentState.QUEUED_UPLOAD,
1105
+ hasSynced: false,
1106
+ size,
1107
+ timestamp: new Date().getTime(),
1108
+ metaData
1109
+ };
1110
+ await this.attachmentService.withContext(async (ctx) => {
1111
+ await ctx.db.writeTransaction(async (tx) => {
1112
+ await updateHook?.(tx, attachment);
1113
+ await ctx.upsertAttachment(attachment, tx);
1114
+ });
1115
+ });
1116
+ return attachment;
1117
+ }
1118
+ async deleteFile({ id, updateHook }) {
1119
+ await this.attachmentService.withContext(async (ctx) => {
1120
+ const attachment = await ctx.getAttachment(id);
1121
+ if (!attachment) {
1122
+ throw new Error(`Attachment with id ${id} not found`);
1123
+ }
1124
+ await ctx.db.writeTransaction(async (tx) => {
1125
+ await updateHook?.(tx, attachment);
1126
+ await ctx.upsertAttachment({
1127
+ ...attachment,
1128
+ state: AttachmentState.QUEUED_DELETE,
1129
+ hasSynced: false
1130
+ }, tx);
1131
+ });
1132
+ });
1133
+ }
1134
+ async expireCache() {
1135
+ let isDone = false;
1136
+ while (!isDone) {
1137
+ await this.attachmentService.withContext(async (ctx) => {
1138
+ isDone = await this.syncingService.deleteArchivedAttachments(ctx);
1139
+ });
1140
+ }
1141
+ }
1142
+ async clearQueue() {
1143
+ await this.attachmentService.withContext(async (ctx) => {
1144
+ await ctx.clearQueue();
1145
+ });
1146
+ await this.localStorage.clear();
1147
+ }
1148
+ /**
1149
+ * Verifies the integrity of all attachment records and repairs inconsistencies.
1150
+ *
1151
+ * This method checks each attachment record against the local filesystem and:
1152
+ * - Updates localUri if the file exists at a different path
1153
+ * - Archives attachments with missing local files that haven't been uploaded
1154
+ * - Requeues synced attachments for download if their local files are missing
1155
+ */
1156
+ async verifyAttachments() {
1157
+ await this.attachmentService.withContext(async (ctx) => {
1158
+ const attachments = await ctx.getAttachments();
1159
+ const updates = [];
1160
+ for (const attachment of attachments) {
1161
+ if (attachment.localUri == null) {
1162
+ continue;
1163
+ }
1164
+ const exists = await this.localStorage.fileExists(attachment.localUri);
1165
+ if (exists) {
1166
+ // The file exists, this is correct
1167
+ continue;
1168
+ }
1169
+ const newLocalUri = this.localStorage.getLocalUri(attachment.filename);
1170
+ const newExists = await this.localStorage.fileExists(newLocalUri);
1171
+ if (newExists) {
1172
+ // The file exists locally but the localUri is broken, we update it.
1173
+ updates.push({
1174
+ ...attachment,
1175
+ localUri: newLocalUri
1176
+ });
1177
+ }
1178
+ else {
1179
+ // the file doesn't exist locally.
1180
+ if (attachment.state === AttachmentState.SYNCED) {
1181
+ // the file has been successfully synced to remote storage but is missing
1182
+ // we download it again
1183
+ updates.push({
1184
+ ...attachment,
1185
+ state: AttachmentState.QUEUED_DOWNLOAD,
1186
+ localUri: undefined
1187
+ });
1188
+ }
1189
+ else {
1190
+ // the file wasn't successfully synced to remote storage, we archive it
1191
+ updates.push({
1192
+ ...attachment,
1193
+ state: AttachmentState.ARCHIVED,
1194
+ localUri: undefined // Clears the value
1195
+ });
1196
+ }
1197
+ }
1198
+ }
1199
+ await ctx.saveAttachments(updates);
1200
+ });
1201
+ }
1202
+ }
1203
+
1204
+ var EncodingType;
1205
+ (function (EncodingType) {
1206
+ EncodingType["UTF8"] = "utf8";
1207
+ EncodingType["Base64"] = "base64";
1208
+ })(EncodingType || (EncodingType = {}));
1209
+
5
1210
  function getDefaultExportFromCjs (x) {
6
1211
  return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
7
1212
  }
@@ -1165,20 +2370,6 @@ class MetaBaseObserver extends BaseObserver {
1165
2370
  }
1166
2371
  }
1167
2372
 
1168
- var WatchedQueryListenerEvent;
1169
- (function (WatchedQueryListenerEvent) {
1170
- WatchedQueryListenerEvent["ON_DATA"] = "onData";
1171
- WatchedQueryListenerEvent["ON_ERROR"] = "onError";
1172
- WatchedQueryListenerEvent["ON_STATE_CHANGE"] = "onStateChange";
1173
- WatchedQueryListenerEvent["SETTINGS_WILL_UPDATE"] = "settingsWillUpdate";
1174
- WatchedQueryListenerEvent["CLOSED"] = "closed";
1175
- })(WatchedQueryListenerEvent || (WatchedQueryListenerEvent = {}));
1176
- const DEFAULT_WATCH_THROTTLE_MS = 30;
1177
- const DEFAULT_WATCH_QUERY_OPTIONS = {
1178
- throttleMs: DEFAULT_WATCH_THROTTLE_MS,
1179
- reportFetching: true
1180
- };
1181
-
1182
2373
  /**
1183
2374
  * Performs underlying watching and yields a stream of results.
1184
2375
  * @internal
@@ -6720,7 +7911,7 @@ function requireDist () {
6720
7911
 
6721
7912
  var distExports = requireDist();
6722
7913
 
6723
- var version = "1.45.0";
7914
+ var version = "1.46.0";
6724
7915
  var PACKAGE = {
6725
7916
  version: version};
6726
7917
 
@@ -7622,18 +8813,17 @@ var SyncClientImplementation;
7622
8813
  *
7623
8814
  * This is the default option.
7624
8815
  *
7625
- * @deprecated Don't use {@link SyncClientImplementation.JAVASCRIPT} directly. Instead, use
7626
- * {@link DEFAULT_SYNC_CLIENT_IMPLEMENTATION} or omit the option. The explicit choice to use
7627
- * the JavaScript-based sync implementation will be removed from a future version of the SDK.
8816
+ * @deprecated We recommend the {@link RUST} client implementation for all apps. If you have issues with
8817
+ * the Rust client, please file an issue or reach out to us. The JavaScript client will be removed in a future
8818
+ * version of the PowerSync SDK.
7628
8819
  */
7629
8820
  SyncClientImplementation["JAVASCRIPT"] = "js";
7630
8821
  /**
7631
8822
  * This implementation offloads the sync line decoding and handling into the PowerSync
7632
8823
  * core extension.
7633
8824
  *
7634
- * @experimental
7635
- * While this implementation is more performant than {@link SyncClientImplementation.JAVASCRIPT},
7636
- * it has seen less real-world testing and is marked as __experimental__ at the moment.
8825
+ * This option is more performant than the {@link JAVASCRIPT} client, enabled by default and the
8826
+ * recommended client implementation for all apps.
7637
8827
  *
7638
8828
  * ## Compatibility warning
7639
8829
  *
@@ -7651,13 +8841,9 @@ var SyncClientImplementation;
7651
8841
  SyncClientImplementation["RUST"] = "rust";
7652
8842
  })(SyncClientImplementation || (SyncClientImplementation = {}));
7653
8843
  /**
7654
- * The default {@link SyncClientImplementation} to use.
7655
- *
7656
- * Please use this field instead of {@link SyncClientImplementation.JAVASCRIPT} directly. A future version
7657
- * of the PowerSync SDK will enable {@link SyncClientImplementation.RUST} by default and remove the JavaScript
7658
- * option.
8844
+ * The default {@link SyncClientImplementation} to use, {@link SyncClientImplementation.RUST}.
7659
8845
  */
7660
- const DEFAULT_SYNC_CLIENT_IMPLEMENTATION = SyncClientImplementation.JAVASCRIPT;
8846
+ const DEFAULT_SYNC_CLIENT_IMPLEMENTATION = SyncClientImplementation.RUST;
7661
8847
  const DEFAULT_CRUD_UPLOAD_THROTTLE_MS = 1000;
7662
8848
  const DEFAULT_RETRY_DELAY_MS = 5000;
7663
8849
  const DEFAULT_STREAMING_SYNC_OPTIONS = {
@@ -8067,6 +9253,9 @@ The next upload iteration will be delayed.`);
8067
9253
  if (rawTables != null && rawTables.length) {
8068
9254
  this.logger.warn('Raw tables require the Rust-based sync client. The JS client will ignore them.');
8069
9255
  }
9256
+ if (this.activeStreams.length) {
9257
+ this.logger.error('Sync streams require `clientImplementation: SyncClientImplementation.RUST` when connecting.');
9258
+ }
8070
9259
  this.logger.debug('Streaming sync iteration started');
8071
9260
  this.options.adapter.startSession();
8072
9261
  let [req, bucketMap] = await this.collectLocalBucketState();
@@ -8582,6 +9771,27 @@ The next upload iteration will be delayed.`);
8582
9771
  }
8583
9772
  }
8584
9773
 
9774
+ const CLAIM_STORE = new Map();
9775
+ /**
9776
+ * @internal
9777
+ * @experimental
9778
+ */
9779
+ const MEMORY_TRIGGER_CLAIM_MANAGER = {
9780
+ async obtainClaim(identifier) {
9781
+ if (CLAIM_STORE.has(identifier)) {
9782
+ throw new Error(`A claim is already present for ${identifier}`);
9783
+ }
9784
+ const release = async () => {
9785
+ CLAIM_STORE.delete(identifier);
9786
+ };
9787
+ CLAIM_STORE.set(identifier, release);
9788
+ return release;
9789
+ },
9790
+ async checkClaim(identifier) {
9791
+ return CLAIM_STORE.has(identifier);
9792
+ }
9793
+ };
9794
+
8585
9795
  /**
8586
9796
  * SQLite operations to track changes for with {@link TriggerManager}
8587
9797
  * @experimental
@@ -8593,9 +9803,20 @@ var DiffTriggerOperation;
8593
9803
  DiffTriggerOperation["DELETE"] = "DELETE";
8594
9804
  })(DiffTriggerOperation || (DiffTriggerOperation = {}));
8595
9805
 
9806
+ const DEFAULT_TRIGGER_MANAGER_CONFIGURATION = {
9807
+ useStorageByDefault: false
9808
+ };
9809
+ const TRIGGER_CLEANUP_INTERVAL_MS = 120_000; // 2 minutes
9810
+ /**
9811
+ * @internal
9812
+ * @experimental
9813
+ */
8596
9814
  class TriggerManagerImpl {
8597
9815
  options;
8598
9816
  schema;
9817
+ defaultConfig;
9818
+ cleanupTimeout;
9819
+ isDisposed;
8599
9820
  constructor(options) {
8600
9821
  this.options = options;
8601
9822
  this.schema = options.schema;
@@ -8604,6 +9825,33 @@ class TriggerManagerImpl {
8604
9825
  this.schema = schema;
8605
9826
  }
8606
9827
  });
9828
+ this.isDisposed = false;
9829
+ /**
9830
+ * Configure a cleanup to run on an interval.
9831
+ * The interval is configured using setTimeout to take the async
9832
+ * execution time of the callback into account.
9833
+ */
9834
+ this.defaultConfig = DEFAULT_TRIGGER_MANAGER_CONFIGURATION;
9835
+ const cleanupCallback = async () => {
9836
+ this.cleanupTimeout = null;
9837
+ if (this.isDisposed) {
9838
+ return;
9839
+ }
9840
+ try {
9841
+ await this.cleanupResources();
9842
+ }
9843
+ catch (ex) {
9844
+ this.db.logger.error(`Caught error while attempting to cleanup triggers`, ex);
9845
+ }
9846
+ finally {
9847
+ // if not closed, set another timeout
9848
+ if (this.isDisposed) {
9849
+ return;
9850
+ }
9851
+ this.cleanupTimeout = setTimeout(cleanupCallback, TRIGGER_CLEANUP_INTERVAL_MS);
9852
+ }
9853
+ };
9854
+ this.cleanupTimeout = setTimeout(cleanupCallback, TRIGGER_CLEANUP_INTERVAL_MS);
8607
9855
  }
8608
9856
  get db() {
8609
9857
  return this.options.db;
@@ -8621,13 +9869,95 @@ class TriggerManagerImpl {
8621
9869
  await tx.execute(/* sql */ `DROP TRIGGER IF EXISTS ${triggerId}; `);
8622
9870
  }
8623
9871
  }
9872
+ dispose() {
9873
+ this.isDisposed = true;
9874
+ if (this.cleanupTimeout) {
9875
+ clearTimeout(this.cleanupTimeout);
9876
+ }
9877
+ }
9878
+ /**
9879
+ * Updates default config settings for platform specific use-cases.
9880
+ */
9881
+ updateDefaults(config) {
9882
+ this.defaultConfig = {
9883
+ ...this.defaultConfig,
9884
+ ...config
9885
+ };
9886
+ }
9887
+ generateTriggerName(operation, destinationTable, triggerId) {
9888
+ return `__ps_temp_trigger_${operation.toLowerCase()}__${destinationTable}__${triggerId}`;
9889
+ }
9890
+ /**
9891
+ * Cleanup any SQLite triggers or tables that are no longer in use.
9892
+ */
9893
+ async cleanupResources() {
9894
+ // we use the database here since cleanupResources is called during the PowerSyncDatabase initialization
9895
+ await this.db.database.writeLock(async (ctx) => {
9896
+ /**
9897
+ * Note: We only cleanup persisted triggers. These are tracked in the sqlite_master table.
9898
+ * temporary triggers will not be affected by this.
9899
+ * Query all triggers that match our naming pattern
9900
+ */
9901
+ const triggers = await ctx.getAll(/* sql */ `
9902
+ SELECT
9903
+ name
9904
+ FROM
9905
+ sqlite_master
9906
+ WHERE
9907
+ type = 'trigger'
9908
+ AND name LIKE '__ps_temp_trigger_%'
9909
+ `);
9910
+ /** Use regex to extract table names and IDs from trigger names
9911
+ * Trigger naming convention: __ps_temp_trigger_<operation>__<destination_table>__<id>
9912
+ */
9913
+ const triggerPattern = /^__ps_temp_trigger_(?:insert|update|delete)__(.+)__([a-f0-9_]{36})$/i;
9914
+ const trackedItems = new Map();
9915
+ for (const trigger of triggers) {
9916
+ const match = trigger.name.match(triggerPattern);
9917
+ if (match) {
9918
+ const [, table, id] = match;
9919
+ // Collect all trigger names for each id combo
9920
+ const existing = trackedItems.get(id);
9921
+ if (existing) {
9922
+ existing.triggerNames.push(trigger.name);
9923
+ }
9924
+ else {
9925
+ trackedItems.set(id, { table, id, triggerNames: [trigger.name] });
9926
+ }
9927
+ }
9928
+ }
9929
+ for (const trackedItem of trackedItems.values()) {
9930
+ // check if there is anything holding on to this item
9931
+ const hasClaim = await this.options.claimManager.checkClaim(trackedItem.id);
9932
+ if (hasClaim) {
9933
+ // This does not require cleanup
9934
+ continue;
9935
+ }
9936
+ this.db.logger.debug(`Clearing resources for trigger ${trackedItem.id} with table ${trackedItem.table}`);
9937
+ // We need to delete the triggers and table
9938
+ for (const triggerName of trackedItem.triggerNames) {
9939
+ await ctx.execute(`DROP TRIGGER IF EXISTS ${triggerName}`);
9940
+ }
9941
+ await ctx.execute(`DROP TABLE IF EXISTS ${trackedItem.table}`);
9942
+ }
9943
+ });
9944
+ }
8624
9945
  async createDiffTrigger(options) {
8625
9946
  await this.db.waitForReady();
8626
- const { source, destination, columns, when, hooks } = options;
9947
+ const { source, destination, columns, when, hooks,
9948
+ // Fall back to the provided default if not given on this level
9949
+ useStorage = this.defaultConfig.useStorageByDefault } = options;
8627
9950
  const operations = Object.keys(when);
8628
9951
  if (operations.length == 0) {
8629
9952
  throw new Error('At least one WHEN operation must be specified for the trigger.');
8630
9953
  }
9954
+ /**
9955
+ * The clause to use when executing
9956
+ * CREATE ${tableTriggerTypeClause} TABLE
9957
+ * OR
9958
+ * CREATE ${tableTriggerTypeClause} TRIGGER
9959
+ */
9960
+ const tableTriggerTypeClause = !useStorage ? 'TEMP' : '';
8631
9961
  const whenClauses = Object.fromEntries(Object.entries(when).map(([operation, filter]) => [operation, `WHEN ${filter}`]));
8632
9962
  /**
8633
9963
  * Allow specifying the View name as the source.
@@ -8641,6 +9971,7 @@ class TriggerManagerImpl {
8641
9971
  const internalSource = sourceDefinition.internalName;
8642
9972
  const triggerIds = [];
8643
9973
  const id = await this.getUUID();
9974
+ const releaseStorageClaim = useStorage ? await this.options.claimManager.obtainClaim(id) : null;
8644
9975
  /**
8645
9976
  * We default to replicating all columns if no columns array is provided.
8646
9977
  */
@@ -8673,26 +10004,27 @@ class TriggerManagerImpl {
8673
10004
  return this.db.writeLock(async (tx) => {
8674
10005
  await this.removeTriggers(tx, triggerIds);
8675
10006
  await tx.execute(/* sql */ `DROP TABLE IF EXISTS ${destination};`);
10007
+ await releaseStorageClaim?.();
8676
10008
  });
8677
10009
  };
8678
10010
  const setup = async (tx) => {
8679
10011
  // Allow user code to execute in this lock context before the trigger is created.
8680
10012
  await hooks?.beforeCreate?.(tx);
8681
10013
  await tx.execute(/* sql */ `
8682
- CREATE TEMP TABLE ${destination} (
10014
+ CREATE ${tableTriggerTypeClause} TABLE ${destination} (
8683
10015
  operation_id INTEGER PRIMARY KEY AUTOINCREMENT,
8684
10016
  id TEXT,
8685
10017
  operation TEXT,
8686
10018
  timestamp TEXT,
8687
10019
  value TEXT,
8688
10020
  previous_value TEXT
8689
- );
10021
+ )
8690
10022
  `);
8691
10023
  if (operations.includes(DiffTriggerOperation.INSERT)) {
8692
- const insertTriggerId = `ps_temp_trigger_insert_${id}`;
10024
+ const insertTriggerId = this.generateTriggerName(DiffTriggerOperation.INSERT, destination, id);
8693
10025
  triggerIds.push(insertTriggerId);
8694
10026
  await tx.execute(/* sql */ `
8695
- CREATE TEMP TRIGGER ${insertTriggerId} AFTER INSERT ON ${internalSource} ${whenClauses[DiffTriggerOperation.INSERT]} BEGIN
10027
+ CREATE ${tableTriggerTypeClause} TRIGGER ${insertTriggerId} AFTER INSERT ON ${internalSource} ${whenClauses[DiffTriggerOperation.INSERT]} BEGIN
8696
10028
  INSERT INTO
8697
10029
  ${destination} (id, operation, timestamp, value)
8698
10030
  VALUES
@@ -8703,14 +10035,14 @@ class TriggerManagerImpl {
8703
10035
  ${jsonFragment('NEW')}
8704
10036
  );
8705
10037
 
8706
- END;
10038
+ END
8707
10039
  `);
8708
10040
  }
8709
10041
  if (operations.includes(DiffTriggerOperation.UPDATE)) {
8710
- const updateTriggerId = `ps_temp_trigger_update_${id}`;
10042
+ const updateTriggerId = this.generateTriggerName(DiffTriggerOperation.UPDATE, destination, id);
8711
10043
  triggerIds.push(updateTriggerId);
8712
10044
  await tx.execute(/* sql */ `
8713
- CREATE TEMP TRIGGER ${updateTriggerId} AFTER
10045
+ CREATE ${tableTriggerTypeClause} TRIGGER ${updateTriggerId} AFTER
8714
10046
  UPDATE ON ${internalSource} ${whenClauses[DiffTriggerOperation.UPDATE]} BEGIN
8715
10047
  INSERT INTO
8716
10048
  ${destination} (id, operation, timestamp, value, previous_value)
@@ -8727,11 +10059,11 @@ class TriggerManagerImpl {
8727
10059
  `);
8728
10060
  }
8729
10061
  if (operations.includes(DiffTriggerOperation.DELETE)) {
8730
- const deleteTriggerId = `ps_temp_trigger_delete_${id}`;
10062
+ const deleteTriggerId = this.generateTriggerName(DiffTriggerOperation.DELETE, destination, id);
8731
10063
  triggerIds.push(deleteTriggerId);
8732
10064
  // Create delete trigger for basic JSON
8733
10065
  await tx.execute(/* sql */ `
8734
- CREATE TEMP TRIGGER ${deleteTriggerId} AFTER DELETE ON ${internalSource} ${whenClauses[DiffTriggerOperation.DELETE]} BEGIN
10066
+ CREATE ${tableTriggerTypeClause} TRIGGER ${deleteTriggerId} AFTER DELETE ON ${internalSource} ${whenClauses[DiffTriggerOperation.DELETE]} BEGIN
8735
10067
  INSERT INTO
8736
10068
  ${destination} (id, operation, timestamp, value)
8737
10069
  VALUES
@@ -8775,7 +10107,7 @@ class TriggerManagerImpl {
8775
10107
  // If no array is provided, we use all columns from the source table.
8776
10108
  const contextColumns = columns ?? sourceDefinition.columns.map((col) => col.name);
8777
10109
  const id = await this.getUUID();
8778
- const destination = `ps_temp_track_${source}_${id}`;
10110
+ const destination = `__ps_temp_track_${source}_${id}`;
8779
10111
  // register an onChange before the trigger is created
8780
10112
  const abortController = new AbortController();
8781
10113
  const abortOnChange = () => abortController.abort();
@@ -8930,6 +10262,7 @@ class AbstractPowerSyncDatabase extends BaseObserver {
8930
10262
  * Allows creating SQLite triggers which can be used to track various operations on SQLite tables.
8931
10263
  */
8932
10264
  triggers;
10265
+ triggersImpl;
8933
10266
  logger;
8934
10267
  constructor(options) {
8935
10268
  super();
@@ -8993,9 +10326,10 @@ class AbstractPowerSyncDatabase extends BaseObserver {
8993
10326
  logger: this.logger
8994
10327
  });
8995
10328
  this._isReadyPromise = this.initialize();
8996
- this.triggers = new TriggerManagerImpl({
10329
+ this.triggers = this.triggersImpl = new TriggerManagerImpl({
8997
10330
  db: this,
8998
- schema: this.schema
10331
+ schema: this.schema,
10332
+ ...this.generateTriggerManagerConfig()
8999
10333
  });
9000
10334
  }
9001
10335
  /**
@@ -9021,6 +10355,15 @@ class AbstractPowerSyncDatabase extends BaseObserver {
9021
10355
  get connecting() {
9022
10356
  return this.currentStatus?.connecting || false;
9023
10357
  }
10358
+ /**
10359
+ * Generates a base configuration for {@link TriggerManagerImpl}.
10360
+ * Implementations should override this if necessary.
10361
+ */
10362
+ generateTriggerManagerConfig() {
10363
+ return {
10364
+ claimManager: MEMORY_TRIGGER_CLAIM_MANAGER
10365
+ };
10366
+ }
9024
10367
  /**
9025
10368
  * @returns A promise which will resolve once initialization is completed.
9026
10369
  */
@@ -9085,6 +10428,7 @@ class AbstractPowerSyncDatabase extends BaseObserver {
9085
10428
  await this.updateSchema(this.options.schema);
9086
10429
  await this.resolveOfflineSyncStatus();
9087
10430
  await this.database.execute('PRAGMA RECURSIVE_TRIGGERS=TRUE');
10431
+ await this.triggersImpl.cleanupResources();
9088
10432
  this.ready = true;
9089
10433
  this.iterateListeners((cb) => cb.initialized?.());
9090
10434
  }
@@ -9204,7 +10548,6 @@ class AbstractPowerSyncDatabase extends BaseObserver {
9204
10548
  await this.disconnect();
9205
10549
  await this.waitForReady();
9206
10550
  const { clearLocal } = options;
9207
- // TODO DB name, verify this is necessary with extension
9208
10551
  await this.database.writeTransaction(async (tx) => {
9209
10552
  await tx.execute('SELECT powersync_clear(?)', [clearLocal ? 1 : 0]);
9210
10553
  });
@@ -9236,6 +10579,7 @@ class AbstractPowerSyncDatabase extends BaseObserver {
9236
10579
  if (this.closed) {
9237
10580
  return;
9238
10581
  }
10582
+ this.triggersImpl.dispose();
9239
10583
  await this.iterateAsyncListeners(async (cb) => cb.closing?.());
9240
10584
  const { disconnect } = options;
9241
10585
  if (disconnect) {
@@ -10201,151 +11545,50 @@ class SqliteBucketStorage extends BaseObserver {
10201
11545
  ]);
10202
11546
  return r != 0;
10203
11547
  }
10204
- async migrateToFixedSubkeys() {
10205
- await this.writeTransaction(async (tx) => {
10206
- await tx.execute('UPDATE ps_oplog SET key = powersync_remove_duplicate_key_encoding(key);');
10207
- await tx.execute('INSERT OR REPLACE INTO ps_kv (key, value) VALUES (?, ?);', [
10208
- SqliteBucketStorage._subkeyMigrationKey,
10209
- '1'
10210
- ]);
10211
- });
10212
- }
10213
- static _subkeyMigrationKey = 'powersync_js_migrated_subkeys';
10214
- }
10215
- function hasMatchingPriority(priority, bucket) {
10216
- return bucket.priority != null && bucket.priority <= priority;
10217
- }
10218
-
10219
- // TODO JSON
10220
- class SyncDataBatch {
10221
- buckets;
10222
- static fromJSON(json) {
10223
- return new SyncDataBatch(json.buckets.map((bucket) => SyncDataBucket.fromRow(bucket)));
10224
- }
10225
- constructor(buckets) {
10226
- this.buckets = buckets;
10227
- }
10228
- }
10229
-
10230
- /**
10231
- * Thrown when an underlying database connection is closed.
10232
- * This is particularly relevant when worker connections are marked as closed while
10233
- * operations are still in progress.
10234
- */
10235
- class ConnectionClosedError extends Error {
10236
- static NAME = 'ConnectionClosedError';
10237
- static MATCHES(input) {
10238
- /**
10239
- * If there are weird package issues which cause multiple versions of classes to be present, the instanceof
10240
- * check might fail. This also performs a failsafe check.
10241
- * This might also happen if the Error is serialized and parsed over a bridging channel like a MessagePort.
10242
- */
10243
- return (input instanceof ConnectionClosedError || (input instanceof Error && input.name == ConnectionClosedError.NAME));
10244
- }
10245
- constructor(message) {
10246
- super(message);
10247
- this.name = ConnectionClosedError.NAME;
10248
- }
10249
- }
10250
-
10251
- // https://www.sqlite.org/lang_expr.html#castexpr
10252
- var ColumnType;
10253
- (function (ColumnType) {
10254
- ColumnType["TEXT"] = "TEXT";
10255
- ColumnType["INTEGER"] = "INTEGER";
10256
- ColumnType["REAL"] = "REAL";
10257
- })(ColumnType || (ColumnType = {}));
10258
- const text = {
10259
- type: ColumnType.TEXT
10260
- };
10261
- const integer = {
10262
- type: ColumnType.INTEGER
10263
- };
10264
- const real = {
10265
- type: ColumnType.REAL
10266
- };
10267
- // powersync-sqlite-core limits the number of column per table to 1999, due to internal SQLite limits.
10268
- // In earlier versions this was limited to 63.
10269
- const MAX_AMOUNT_OF_COLUMNS = 1999;
10270
- const column = {
10271
- text,
10272
- integer,
10273
- real
10274
- };
10275
- class Column {
10276
- options;
10277
- constructor(options) {
10278
- this.options = options;
10279
- }
10280
- get name() {
10281
- return this.options.name;
10282
- }
10283
- get type() {
10284
- return this.options.type;
10285
- }
10286
- toJSON() {
10287
- return {
10288
- name: this.name,
10289
- type: this.type
10290
- };
10291
- }
10292
- }
10293
-
10294
- const DEFAULT_INDEX_COLUMN_OPTIONS = {
10295
- ascending: true
10296
- };
10297
- class IndexedColumn {
10298
- options;
10299
- static createAscending(column) {
10300
- return new IndexedColumn({
10301
- name: column,
10302
- ascending: true
10303
- });
10304
- }
10305
- constructor(options) {
10306
- this.options = { ...DEFAULT_INDEX_COLUMN_OPTIONS, ...options };
10307
- }
10308
- get name() {
10309
- return this.options.name;
10310
- }
10311
- get ascending() {
10312
- return this.options.ascending;
10313
- }
10314
- toJSON(table) {
10315
- return {
10316
- name: this.name,
10317
- ascending: this.ascending,
10318
- type: table.columns.find((column) => column.name === this.name)?.type ?? ColumnType.TEXT
10319
- };
10320
- }
10321
- }
10322
-
10323
- const DEFAULT_INDEX_OPTIONS = {
10324
- columns: []
10325
- };
10326
- class Index {
10327
- options;
10328
- static createAscending(options, columnNames) {
10329
- return new Index({
10330
- ...options,
10331
- columns: columnNames.map((name) => IndexedColumn.createAscending(name))
11548
+ async migrateToFixedSubkeys() {
11549
+ await this.writeTransaction(async (tx) => {
11550
+ await tx.execute('UPDATE ps_oplog SET key = powersync_remove_duplicate_key_encoding(key);');
11551
+ await tx.execute('INSERT OR REPLACE INTO ps_kv (key, value) VALUES (?, ?);', [
11552
+ SqliteBucketStorage._subkeyMigrationKey,
11553
+ '1'
11554
+ ]);
10332
11555
  });
10333
11556
  }
10334
- constructor(options) {
10335
- this.options = options;
10336
- this.options = { ...DEFAULT_INDEX_OPTIONS, ...options };
11557
+ static _subkeyMigrationKey = 'powersync_js_migrated_subkeys';
11558
+ }
11559
+ function hasMatchingPriority(priority, bucket) {
11560
+ return bucket.priority != null && bucket.priority <= priority;
11561
+ }
11562
+
11563
+ // TODO JSON
11564
+ class SyncDataBatch {
11565
+ buckets;
11566
+ static fromJSON(json) {
11567
+ return new SyncDataBatch(json.buckets.map((bucket) => SyncDataBucket.fromRow(bucket)));
10337
11568
  }
10338
- get name() {
10339
- return this.options.name;
11569
+ constructor(buckets) {
11570
+ this.buckets = buckets;
10340
11571
  }
10341
- get columns() {
10342
- return this.options.columns ?? [];
11572
+ }
11573
+
11574
+ /**
11575
+ * Thrown when an underlying database connection is closed.
11576
+ * This is particularly relevant when worker connections are marked as closed while
11577
+ * operations are still in progress.
11578
+ */
11579
+ class ConnectionClosedError extends Error {
11580
+ static NAME = 'ConnectionClosedError';
11581
+ static MATCHES(input) {
11582
+ /**
11583
+ * If there are weird package issues which cause multiple versions of classes to be present, the instanceof
11584
+ * check might fail. This also performs a failsafe check.
11585
+ * This might also happen if the Error is serialized and parsed over a bridging channel like a MessagePort.
11586
+ */
11587
+ return (input instanceof ConnectionClosedError || (input instanceof Error && input.name == ConnectionClosedError.NAME));
10343
11588
  }
10344
- toJSON(table) {
10345
- return {
10346
- name: this.name,
10347
- columns: this.columns.map((c) => c.toJSON(table))
10348
- };
11589
+ constructor(message) {
11590
+ super(message);
11591
+ this.name = ConnectionClosedError.NAME;
10349
11592
  }
10350
11593
  }
10351
11594
 
@@ -10442,211 +11685,6 @@ class Schema {
10442
11685
  }
10443
11686
  }
10444
11687
 
10445
- const DEFAULT_TABLE_OPTIONS = {
10446
- indexes: [],
10447
- insertOnly: false,
10448
- localOnly: false,
10449
- trackPrevious: false,
10450
- trackMetadata: false,
10451
- ignoreEmptyUpdates: false
10452
- };
10453
- const InvalidSQLCharacters = /["'%,.#\s[\]]/;
10454
- class Table {
10455
- options;
10456
- _mappedColumns;
10457
- static createLocalOnly(options) {
10458
- return new Table({ ...options, localOnly: true, insertOnly: false });
10459
- }
10460
- static createInsertOnly(options) {
10461
- return new Table({ ...options, localOnly: false, insertOnly: true });
10462
- }
10463
- /**
10464
- * Create a table.
10465
- * @deprecated This was only only included for TableV2 and is no longer necessary.
10466
- * Prefer to use new Table() directly.
10467
- *
10468
- * TODO remove in the next major release.
10469
- */
10470
- static createTable(name, table) {
10471
- return new Table({
10472
- name,
10473
- columns: table.columns,
10474
- indexes: table.indexes,
10475
- localOnly: table.options.localOnly,
10476
- insertOnly: table.options.insertOnly,
10477
- viewName: table.options.viewName
10478
- });
10479
- }
10480
- constructor(optionsOrColumns, v2Options) {
10481
- if (this.isTableV1(optionsOrColumns)) {
10482
- this.initTableV1(optionsOrColumns);
10483
- }
10484
- else {
10485
- this.initTableV2(optionsOrColumns, v2Options);
10486
- }
10487
- }
10488
- copyWithName(name) {
10489
- return new Table({
10490
- ...this.options,
10491
- name
10492
- });
10493
- }
10494
- isTableV1(arg) {
10495
- return 'columns' in arg && Array.isArray(arg.columns);
10496
- }
10497
- initTableV1(options) {
10498
- this.options = {
10499
- ...options,
10500
- indexes: options.indexes || []
10501
- };
10502
- this.applyDefaultOptions();
10503
- }
10504
- initTableV2(columns, options) {
10505
- const convertedColumns = Object.entries(columns).map(([name, columnInfo]) => new Column({ name, type: columnInfo.type }));
10506
- const convertedIndexes = Object.entries(options?.indexes ?? {}).map(([name, columnNames]) => new Index({
10507
- name,
10508
- columns: columnNames.map((name) => new IndexedColumn({
10509
- name: name.replace(/^-/, ''),
10510
- ascending: !name.startsWith('-')
10511
- }))
10512
- }));
10513
- this.options = {
10514
- name: '',
10515
- columns: convertedColumns,
10516
- indexes: convertedIndexes,
10517
- viewName: options?.viewName,
10518
- insertOnly: options?.insertOnly,
10519
- localOnly: options?.localOnly,
10520
- trackPrevious: options?.trackPrevious,
10521
- trackMetadata: options?.trackMetadata,
10522
- ignoreEmptyUpdates: options?.ignoreEmptyUpdates
10523
- };
10524
- this.applyDefaultOptions();
10525
- this._mappedColumns = columns;
10526
- }
10527
- applyDefaultOptions() {
10528
- this.options.insertOnly ??= DEFAULT_TABLE_OPTIONS.insertOnly;
10529
- this.options.localOnly ??= DEFAULT_TABLE_OPTIONS.localOnly;
10530
- this.options.trackPrevious ??= DEFAULT_TABLE_OPTIONS.trackPrevious;
10531
- this.options.trackMetadata ??= DEFAULT_TABLE_OPTIONS.trackMetadata;
10532
- this.options.ignoreEmptyUpdates ??= DEFAULT_TABLE_OPTIONS.ignoreEmptyUpdates;
10533
- }
10534
- get name() {
10535
- return this.options.name;
10536
- }
10537
- get viewNameOverride() {
10538
- return this.options.viewName;
10539
- }
10540
- get viewName() {
10541
- return this.viewNameOverride ?? this.name;
10542
- }
10543
- get columns() {
10544
- return this.options.columns;
10545
- }
10546
- get columnMap() {
10547
- return (this._mappedColumns ??
10548
- this.columns.reduce((hash, column) => {
10549
- hash[column.name] = { type: column.type ?? ColumnType.TEXT };
10550
- return hash;
10551
- }, {}));
10552
- }
10553
- get indexes() {
10554
- return this.options.indexes ?? [];
10555
- }
10556
- get localOnly() {
10557
- return this.options.localOnly;
10558
- }
10559
- get insertOnly() {
10560
- return this.options.insertOnly;
10561
- }
10562
- get trackPrevious() {
10563
- return this.options.trackPrevious;
10564
- }
10565
- get trackMetadata() {
10566
- return this.options.trackMetadata;
10567
- }
10568
- get ignoreEmptyUpdates() {
10569
- return this.options.ignoreEmptyUpdates;
10570
- }
10571
- get internalName() {
10572
- if (this.options.localOnly) {
10573
- return `ps_data_local__${this.name}`;
10574
- }
10575
- return `ps_data__${this.name}`;
10576
- }
10577
- get validName() {
10578
- if (InvalidSQLCharacters.test(this.name)) {
10579
- return false;
10580
- }
10581
- if (this.viewNameOverride != null && InvalidSQLCharacters.test(this.viewNameOverride)) {
10582
- return false;
10583
- }
10584
- return true;
10585
- }
10586
- validate() {
10587
- if (InvalidSQLCharacters.test(this.name)) {
10588
- throw new Error(`Invalid characters in table name: ${this.name}`);
10589
- }
10590
- if (this.viewNameOverride && InvalidSQLCharacters.test(this.viewNameOverride)) {
10591
- throw new Error(`Invalid characters in view name: ${this.viewNameOverride}`);
10592
- }
10593
- if (this.columns.length > MAX_AMOUNT_OF_COLUMNS) {
10594
- throw new Error(`Table has too many columns. The maximum number of columns is ${MAX_AMOUNT_OF_COLUMNS}.`);
10595
- }
10596
- if (this.trackMetadata && this.localOnly) {
10597
- throw new Error(`Can't include metadata for local-only tables.`);
10598
- }
10599
- if (this.trackPrevious != false && this.localOnly) {
10600
- throw new Error(`Can't include old values for local-only tables.`);
10601
- }
10602
- const columnNames = new Set();
10603
- columnNames.add('id');
10604
- for (const column of this.columns) {
10605
- const { name: columnName } = column;
10606
- if (column.name === 'id') {
10607
- throw new Error(`An id column is automatically added, custom id columns are not supported`);
10608
- }
10609
- if (columnNames.has(columnName)) {
10610
- throw new Error(`Duplicate column ${columnName}`);
10611
- }
10612
- if (InvalidSQLCharacters.test(columnName)) {
10613
- throw new Error(`Invalid characters in column name: ${column.name}`);
10614
- }
10615
- columnNames.add(columnName);
10616
- }
10617
- const indexNames = new Set();
10618
- for (const index of this.indexes) {
10619
- if (indexNames.has(index.name)) {
10620
- throw new Error(`Duplicate index ${index.name}`);
10621
- }
10622
- if (InvalidSQLCharacters.test(index.name)) {
10623
- throw new Error(`Invalid characters in index name: ${index.name}`);
10624
- }
10625
- for (const column of index.columns) {
10626
- if (!columnNames.has(column.name)) {
10627
- throw new Error(`Column ${column.name} not found for index ${index.name}`);
10628
- }
10629
- }
10630
- indexNames.add(index.name);
10631
- }
10632
- }
10633
- toJSON() {
10634
- const trackPrevious = this.trackPrevious;
10635
- return {
10636
- name: this.name,
10637
- view_name: this.viewName,
10638
- local_only: this.localOnly,
10639
- insert_only: this.insertOnly,
10640
- include_old: trackPrevious && (trackPrevious.columns ?? true),
10641
- include_old_only_when_changed: typeof trackPrevious == 'object' && trackPrevious.onlyWhenChanged == true,
10642
- include_metadata: this.trackMetadata,
10643
- ignore_empty_update: this.ignoreEmptyUpdates,
10644
- columns: this.columns.map((c) => c.toJSON()),
10645
- indexes: this.indexes.map((e) => e.toJSON(this))
10646
- };
10647
- }
10648
- }
10649
-
10650
11688
  /**
10651
11689
  Generate a new table from the columns and indexes
10652
11690
  @deprecated You should use {@link Table} instead as it now allows TableV2 syntax.
@@ -10802,5 +11840,5 @@ const parseQuery = (query, parameters) => {
10802
11840
  return { sqlStatement, parameters: parameters };
10803
11841
  };
10804
11842
 
10805
- export { AbortOperation, AbstractPowerSyncDatabase, AbstractPowerSyncDatabaseOpenFactory, AbstractQueryProcessor, AbstractRemote, AbstractStreamingSyncImplementation, ArrayComparator, BaseObserver, Column, ColumnType, ConnectionClosedError, ConnectionManager, ControlledExecutor, CrudBatch, CrudEntry, CrudTransaction, DEFAULT_CRUD_BATCH_LIMIT, DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_INDEX_COLUMN_OPTIONS, DEFAULT_INDEX_OPTIONS, DEFAULT_LOCK_TIMEOUT_MS, DEFAULT_POWERSYNC_CLOSE_OPTIONS, DEFAULT_POWERSYNC_DB_OPTIONS, DEFAULT_PRESSURE_LIMITS, DEFAULT_REMOTE_LOGGER, DEFAULT_REMOTE_OPTIONS, DEFAULT_RETRY_DELAY_MS, DEFAULT_ROW_COMPARATOR, DEFAULT_STREAMING_SYNC_OPTIONS, DEFAULT_STREAM_CONNECTION_OPTIONS, DEFAULT_SYNC_CLIENT_IMPLEMENTATION, DEFAULT_TABLE_OPTIONS, DEFAULT_WATCH_QUERY_OPTIONS, DEFAULT_WATCH_THROTTLE_MS, DataStream, DiffTriggerOperation, DifferentialQueryProcessor, EMPTY_DIFFERENTIAL, FalsyComparator, FetchImplementationProvider, FetchStrategy, GetAllQuery, Index, IndexedColumn, InvalidSQLCharacters, LockType, LogLevel, MAX_AMOUNT_OF_COLUMNS, MAX_OP_ID, OnChangeQueryProcessor, OpType, OpTypeEnum, OplogEntry, PSInternalTable, PowerSyncControlCommand, RawTable, RowUpdateType, Schema, SqliteBucketStorage, SyncClientImplementation, SyncDataBatch, SyncDataBucket, SyncProgress, SyncStatus, SyncStreamConnectionMethod, Table, TableV2, UpdateType, UploadQueueStats, WatchedQueryListenerEvent, column, compilableQueryWatch, createBaseLogger, createLogger, extractTableUpdates, isBatchedUpdateNotification, isContinueCheckpointRequest, isDBAdapter, isPowerSyncDatabaseOptionsWithSettings, isSQLOpenFactory, isSQLOpenOptions, isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData, isSyncNewCheckpointRequest, parseQuery, runOnSchemaChange, sanitizeSQL, sanitizeUUID };
11843
+ export { ATTACHMENT_TABLE, AbortOperation, AbstractPowerSyncDatabase, AbstractPowerSyncDatabaseOpenFactory, AbstractQueryProcessor, AbstractRemote, AbstractStreamingSyncImplementation, ArrayComparator, AttachmentContext, AttachmentQueue, AttachmentService, AttachmentState, AttachmentTable, BaseObserver, Column, ColumnType, ConnectionClosedError, ConnectionManager, ControlledExecutor, CrudBatch, CrudEntry, CrudTransaction, DEFAULT_CRUD_BATCH_LIMIT, DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_INDEX_COLUMN_OPTIONS, DEFAULT_INDEX_OPTIONS, DEFAULT_LOCK_TIMEOUT_MS, DEFAULT_POWERSYNC_CLOSE_OPTIONS, DEFAULT_POWERSYNC_DB_OPTIONS, DEFAULT_PRESSURE_LIMITS, DEFAULT_REMOTE_LOGGER, DEFAULT_REMOTE_OPTIONS, DEFAULT_RETRY_DELAY_MS, DEFAULT_ROW_COMPARATOR, DEFAULT_STREAMING_SYNC_OPTIONS, DEFAULT_STREAM_CONNECTION_OPTIONS, DEFAULT_SYNC_CLIENT_IMPLEMENTATION, DEFAULT_TABLE_OPTIONS, DEFAULT_WATCH_QUERY_OPTIONS, DEFAULT_WATCH_THROTTLE_MS, DataStream, DiffTriggerOperation, DifferentialQueryProcessor, EMPTY_DIFFERENTIAL, EncodingType, FalsyComparator, FetchImplementationProvider, FetchStrategy, GetAllQuery, Index, IndexedColumn, InvalidSQLCharacters, LockType, LogLevel, MAX_AMOUNT_OF_COLUMNS, MAX_OP_ID, MEMORY_TRIGGER_CLAIM_MANAGER, OnChangeQueryProcessor, OpType, OpTypeEnum, OplogEntry, PSInternalTable, PowerSyncControlCommand, RawTable, RowUpdateType, Schema, SqliteBucketStorage, SyncClientImplementation, SyncDataBatch, SyncDataBucket, SyncProgress, SyncStatus, SyncStreamConnectionMethod, SyncingService, Table, TableV2, TriggerManagerImpl, UpdateType, UploadQueueStats, WatchedQueryListenerEvent, attachmentFromSql, column, compilableQueryWatch, createBaseLogger, createLogger, extractTableUpdates, isBatchedUpdateNotification, isContinueCheckpointRequest, isDBAdapter, isPowerSyncDatabaseOptionsWithSettings, isSQLOpenFactory, isSQLOpenOptions, isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData, isSyncNewCheckpointRequest, parseQuery, runOnSchemaChange, sanitizeSQL, sanitizeUUID };
10806
11844
  //# sourceMappingURL=bundle.node.mjs.map