@syncular/client 0.58.0 → 0.60.0

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 (99) hide show
  1. package/README.md +34 -34
  2. package/dist/apply.d.ts +24 -14
  3. package/dist/apply.js +119 -70
  4. package/dist/authority.js +21 -16
  5. package/dist/blob.d.ts +17 -9
  6. package/dist/blob.js +5 -6
  7. package/dist/bun-database.d.ts +1 -0
  8. package/dist/bun-database.js +15 -0
  9. package/dist/client.d.ts +83 -75
  10. package/dist/client.js +982 -910
  11. package/dist/database.d.ts +5 -0
  12. package/dist/devtools.d.ts +2 -2
  13. package/dist/devtools.js +3 -3
  14. package/dist/diagnostics.d.ts +17 -28
  15. package/dist/diagnostics.js +1 -2
  16. package/dist/encryption.d.ts +2 -2
  17. package/dist/encryption.js +8 -2
  18. package/dist/errors.d.ts +3 -1
  19. package/dist/errors.js +5 -1
  20. package/dist/failed-overlay.d.ts +0 -1
  21. package/dist/failed-overlay.js +6 -6
  22. package/dist/http.d.ts +4 -1
  23. package/dist/http.js +67 -39
  24. package/dist/index.d.ts +1 -1
  25. package/dist/index.js +1 -1
  26. package/dist/invalidation.d.ts +14 -14
  27. package/dist/invalidation.js +24 -48
  28. package/dist/local-purge.js +9 -12
  29. package/dist/local-rebootstrap.js +2 -2
  30. package/dist/multi-tab.d.ts +89 -1
  31. package/dist/multi-tab.js +70 -31
  32. package/dist/native-bridge.d.ts +226 -0
  33. package/dist/native-bridge.js +764 -0
  34. package/dist/node-database.d.ts +1 -0
  35. package/dist/node-database.js +21 -1
  36. package/dist/outbox.d.ts +9 -12
  37. package/dist/outbox.js +20 -36
  38. package/dist/outcomes.js +3 -3
  39. package/dist/previous-version.js +96 -114
  40. package/dist/progress.d.ts +2 -2
  41. package/dist/query-guard.d.ts +34 -24
  42. package/dist/query-guard.js +61 -186
  43. package/dist/reactive-store.js +55 -13
  44. package/dist/realtime-supervisor.d.ts +9 -2
  45. package/dist/realtime-supervisor.js +31 -7
  46. package/dist/remote.js +19 -23
  47. package/dist/schema.d.ts +3 -2
  48. package/dist/schema.js +43 -22
  49. package/dist/state.d.ts +69 -36
  50. package/dist/state.js +178 -89
  51. package/dist/sync-scheduler.js +28 -2
  52. package/dist/transport.d.ts +19 -4
  53. package/dist/wasm-database.js +58 -21
  54. package/dist/window.d.ts +30 -52
  55. package/dist/window.js +33 -77
  56. package/dist/worker-core.d.ts +5 -0
  57. package/dist/worker-core.js +83 -75
  58. package/dist/worker-host.d.ts +19 -13
  59. package/dist/worker-host.js +75 -18
  60. package/dist/worker-local-authority.js +2 -2
  61. package/dist/worker-protocol.d.ts +15 -10
  62. package/package.json +11 -3
  63. package/src/apply.ts +176 -86
  64. package/src/authority.ts +31 -17
  65. package/src/blob.ts +28 -15
  66. package/src/bun-database.ts +24 -0
  67. package/src/client.ts +1282 -1217
  68. package/src/database.ts +5 -0
  69. package/src/devtools.ts +5 -5
  70. package/src/diagnostics.ts +17 -37
  71. package/src/encryption.ts +10 -5
  72. package/src/errors.ts +9 -1
  73. package/src/failed-overlay.ts +8 -7
  74. package/src/http.ts +95 -79
  75. package/src/index.ts +1 -1
  76. package/src/invalidation.ts +26 -61
  77. package/src/local-purge.ts +11 -13
  78. package/src/local-rebootstrap.ts +2 -3
  79. package/src/multi-tab.ts +88 -30
  80. package/src/native-bridge.ts +1153 -0
  81. package/src/node-database.ts +32 -1
  82. package/src/outbox.ts +20 -41
  83. package/src/outcomes.ts +3 -5
  84. package/src/previous-version.ts +103 -114
  85. package/src/progress.ts +2 -2
  86. package/src/query-guard.ts +77 -177
  87. package/src/reactive-store.ts +52 -12
  88. package/src/realtime-supervisor.ts +37 -12
  89. package/src/remote.ts +23 -31
  90. package/src/schema.ts +67 -25
  91. package/src/state.ts +246 -125
  92. package/src/sync-scheduler.ts +31 -1
  93. package/src/transport.ts +21 -2
  94. package/src/wasm-database.ts +76 -27
  95. package/src/window.ts +55 -134
  96. package/src/worker-core.ts +97 -77
  97. package/src/worker-host.ts +76 -32
  98. package/src/worker-local-authority.ts +2 -5
  99. package/src/worker-protocol.ts +14 -10
package/src/remote.ts CHANGED
@@ -3,10 +3,10 @@
3
3
  * through the existing push path without creating a local replica or outbox.
4
4
  */
5
5
  import {
6
- decodeMessage,
6
+ decodeResponse,
7
7
  decodeRemoteOperationResponse,
8
8
  decodeRemoteOperationRealtimeMessage,
9
- encodeMessage,
9
+ encodeRequest,
10
10
  encodeRemoteOperationRequest,
11
11
  encodeRemoteOperationRealtimeMessage,
12
12
  encodeSparseRow,
@@ -18,11 +18,12 @@ import {
18
18
  type PushResultFrame,
19
19
  type RowValue,
20
20
  type RemoteOperationResponse,
21
+ registrationDigest,
21
22
  } from '@syncular/core';
22
23
  import type { MutationInput } from './client';
23
24
  import type { EncryptionConfig } from './encryption';
24
25
  import { encryptRowValues } from './encryption';
25
- import { ClientSyncError } from './errors';
26
+ import { ClientSyncError, invalidRequest } from './errors';
26
27
  import {
27
28
  compileClientSchema,
28
29
  type ClientSchema,
@@ -97,7 +98,8 @@ export interface RemoteCommandDescriptor<Input = undefined> {
97
98
  export function remoteCommand<Input = undefined>(
98
99
  id: string,
99
100
  ): RemoteCommandDescriptor<Input> {
100
- if (id.length === 0) throw invalid('remote command id must be non-empty');
101
+ if (id.length === 0)
102
+ throw invalidRequest('remote command id must be non-empty');
101
103
  return { id };
102
104
  }
103
105
 
@@ -108,10 +110,6 @@ export interface RemoteCommandResult {
108
110
  readonly results: readonly unknown[];
109
111
  }
110
112
 
111
- function invalid(message: string): ClientSyncError {
112
- return new ClientSyncError('sync.invalid_request', message);
113
- }
114
-
115
113
  function operationResponse(bytes: Uint8Array): RemoteOperationResponse {
116
114
  let response: RemoteOperationResponse;
117
115
  try {
@@ -239,10 +237,10 @@ export class SyncRemoteClient {
239
237
 
240
238
  constructor(config: SyncRemoteClientConfig) {
241
239
  if (config.clientId.length === 0) {
242
- throw invalid('SyncRemoteClient clientId must be non-empty');
240
+ throw invalidRequest('SyncRemoteClient clientId must be non-empty');
243
241
  }
244
242
  if (config.logEpoch !== undefined && config.logEpoch.length === 0) {
245
- throw invalid('SyncRemoteClient logEpoch must be non-empty');
243
+ throw invalidRequest('SyncRemoteClient logEpoch must be non-empty');
246
244
  }
247
245
  this.#schema =
248
246
  config.schema === undefined
@@ -265,7 +263,7 @@ export class SyncRemoteClient {
265
263
  );
266
264
  }
267
265
  if (input.requestId.length === 0) {
268
- throw invalid('remote commit requestId must be non-empty');
266
+ throw invalidRequest('remote commit requestId must be non-empty');
269
267
  }
270
268
  if (input.mutations.length === 0) {
271
269
  throw new ClientSyncError(
@@ -283,9 +281,9 @@ export class SyncRemoteClient {
283
281
  'SyncRemoteClient has no sync transport for ordinary commits',
284
282
  );
285
283
  }
286
- const acquisition = decodeMessage(
284
+ const acquisition = decodeResponse(
287
285
  await this.#transport(
288
- encodeMessage({
286
+ encodeRequest({
289
287
  wireVersion: PROTOCOL_WIRE_VERSION,
290
288
  msgKind: 'request',
291
289
  frames: [
@@ -301,17 +299,16 @@ export class SyncRemoteClient {
301
299
  limitSnapshotRows: 0,
302
300
  maxSnapshotPages: 0,
303
301
  accept: 0b0011,
302
+ cursor: -1,
303
+ registrationDigest: registrationDigest([]),
304
+ echoDigest: new Uint8Array(),
304
305
  },
305
306
  ],
306
307
  }),
307
308
  ),
308
309
  );
309
310
  const acquisitionHeader = acquisition.frames[0];
310
- if (
311
- acquisition.msgKind !== 'response' ||
312
- acquisitionHeader?.type !== 'RESP_HEADER' ||
313
- acquisitionHeader.logEpoch === undefined
314
- ) {
311
+ if (acquisitionHeader?.type !== 'RESP_HEADER') {
315
312
  throw new ClientSyncError(
316
313
  'client.invalid_host_response',
317
314
  'remote epoch acquisition returned an invalid response',
@@ -324,11 +321,11 @@ export class SyncRemoteClient {
324
321
  for (const mutation of input.mutations) {
325
322
  const table = schema.tables.get(mutation.table);
326
323
  if (table === undefined) {
327
- throw invalid('remote commit targets an unknown table');
324
+ throw invalidRequest('remote commit targets an unknown table');
328
325
  }
329
326
  if (mutation.op === 'delete') {
330
327
  if (mutation.rowId.length === 0) {
331
- throw invalid('remote delete rowId must be non-empty');
328
+ throw invalidRequest('remote delete rowId must be non-empty');
332
329
  }
333
330
  operations.push({
334
331
  table: mutation.table,
@@ -361,9 +358,9 @@ export class SyncRemoteClient {
361
358
  ? String(rawRowId)
362
359
  : undefined;
363
360
  if (rowId === undefined) {
364
- throw invalid('remote upsert requires a non-empty primary key');
361
+ throw invalidRequest('remote upsert requires a non-empty primary key');
365
362
  }
366
- if (this.#encryption !== undefined && table.hasEncryptedColumns) {
363
+ if (table.hasEncryptedColumns) {
367
364
  values = await encryptRowValues(this.#encryption, table, rowId, values);
368
365
  }
369
366
  operations.push({
@@ -378,7 +375,7 @@ export class SyncRemoteClient {
378
375
  }
379
376
  return {
380
377
  requestId: input.requestId,
381
- bytes: encodeMessage({
378
+ bytes: encodeRequest({
382
379
  wireVersion: PROTOCOL_WIRE_VERSION,
383
380
  msgKind: 'request',
384
381
  frames: [
@@ -391,6 +388,7 @@ export class SyncRemoteClient {
391
388
  {
392
389
  type: 'PUSH_COMMIT',
393
390
  clientCommitId: input.requestId,
391
+ clientSeq: 0,
394
392
  operations,
395
393
  },
396
394
  ],
@@ -407,13 +405,7 @@ export class SyncRemoteClient {
407
405
  'SyncRemoteClient has no sync transport for ordinary commits',
408
406
  );
409
407
  }
410
- const response = decodeMessage(await this.#transport(prepared.bytes));
411
- if (response.msgKind !== 'response') {
412
- throw new ClientSyncError(
413
- 'client.invalid_host_response',
414
- 'remote commit transport returned a non-response SSP2 message',
415
- );
416
- }
408
+ const response = decodeResponse(await this.#transport(prepared.bytes));
417
409
  const error = response.frames.find((frame) => frame.type === 'ERROR');
418
410
  if (error?.type === 'ERROR') {
419
411
  throw new ClientSyncError(error.code, error.message, error.retryable);
@@ -510,7 +502,7 @@ export class SyncRemoteClient {
510
502
  );
511
503
  }
512
504
  if (requestId.length === 0) {
513
- throw invalid('remote command requestId must be non-empty');
505
+ throw invalidRequest('remote command requestId must be non-empty');
514
506
  }
515
507
  const response = operationResponse(
516
508
  await this.#operations(
package/src/schema.ts CHANGED
@@ -3,7 +3,7 @@ import { PENDING_EVICTIONS } from './window';
3
3
  import { WINDOWS_TABLE } from './window';
4
4
  import { OUTBOX_TABLE, OUTBOX_IMAGES } from './outbox';
5
5
  import { OUTCOMES_TABLE } from './outcomes';
6
- import { SUBSCRIPTIONS_TABLE, META_TABLE } from './state';
6
+ import { META_TABLE, resetUnits, UNITS_TABLE } from './state';
7
7
  import { ensureFailedOverlaySchema } from './failed-overlay';
8
8
  /**
9
9
  * Client schema IR (SPEC.md §2.4, §3.1) — the same shape the server
@@ -13,7 +13,7 @@ import { ensureFailedOverlaySchema } from './failed-overlay';
13
13
  */
14
14
  import type { RowColumn, RowValue } from '@syncular/core';
15
15
  import type { ClientDatabase, SqlRow, SqlValue } from './database';
16
- import { invalidRequest } from './errors';
16
+ import { ClientSyncError, invalidRequest } from './errors';
17
17
  import { snakeToCamel } from './naming';
18
18
 
19
19
  /** `'prefix:{variable}'` shorthand (column name = variable) or explicit. */
@@ -166,18 +166,19 @@ export function compileClientSchema(
166
166
  const scopePrefixByVariable = new Map<string, string>();
167
167
  for (const spec of table.scopes) {
168
168
  const pattern = typeof spec === 'string' ? spec : spec.pattern;
169
- const match = PATTERN_RE.exec(pattern);
170
- if (match === null || match[1] === undefined || match[2] === undefined) {
169
+ const [, prefix, variable] = PATTERN_RE.exec(pattern) ?? [];
170
+ if (!prefix || !variable) {
171
171
  invalidSchema(
172
172
  `${tableLabel}: scope pattern ${JSON.stringify(pattern)} must be 'prefix:{variable}'`,
173
173
  );
174
174
  }
175
- const prefix = match[1];
176
- const variable = match[2];
177
175
  const column = typeof spec === 'string' ? variable : spec.column;
178
- if (!columnIndex.has(column)) {
176
+ // §3.1: a scope value is an authorization key; only these two types
177
+ // render identically in every implementation.
178
+ const type = table.columns[columnIndex.get(column) ?? -1]?.type;
179
+ if (type !== 'string' && type !== 'integer') {
179
180
  invalidSchema(
180
- `${tableLabel}: scope pattern ${JSON.stringify(pattern)} names unknown column ${JSON.stringify(column)}`,
181
+ `${tableLabel}: scope column ${JSON.stringify(column)} must be string or integer (§3.1)`,
181
182
  );
182
183
  }
183
184
  const existing = scopeColumnByVariable.get(variable);
@@ -591,20 +592,36 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
591
592
  db.exec(
592
593
  `INSERT OR IGNORE INTO ${META_TABLE}(key,value)VALUES('localRevision','0')`,
593
594
  );
595
+ const outboxExisted =
596
+ db.query(
597
+ `SELECT 1 FROM sqlite_master WHERE type='table' AND name='${OUTBOX_TABLE}'`,
598
+ ).length > 0;
594
599
  createTable(
595
600
  OUTBOX_TABLE,
596
601
  'seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,created_at_ms INTEGER NOT NULL,operations TEXT NOT NULL',
597
602
  );
603
+ // §7.1: `outboxId` names the outbox sequence. A new outbox table starts
604
+ // a new sequence, so it replaces the id in the same transaction.
605
+ db.exec(
606
+ `INSERT OR ${outboxExisted ? 'IGNORE' : 'REPLACE'} INTO ${META_TABLE}(key,value)VALUES('outboxId',?)`,
607
+ [crypto.randomUUID()],
608
+ );
598
609
  createTable(
599
610
  OUTBOX_IMAGES,
600
611
  'client_commit_id TEXT NOT NULL,op_index INTEGER NOT NULL,existed INTEGER NOT NULL CHECK(existed IN (0,1)),sync_version INTEGER,values_json TEXT,PRIMARY KEY(client_commit_id,op_index)',
601
612
  );
602
- if (
603
- !db
604
- .query(`PRAGMA table_info(${OUTBOX_IMAGES})`)
605
- .some((row) => row.name === 'delivery_seq')
606
- )
607
- db.exec(`ALTER TABLE ${OUTBOX_IMAGES} ADD COLUMN delivery_seq INTEGER`);
613
+ const imageColumns = db.query(`PRAGMA table_info(${OUTBOX_IMAGES})`);
614
+ for (const column of ['delivery_seq INTEGER', 'tbl TEXT', 'row_id TEXT'])
615
+ if (!imageColumns.some((row) => row.name === column.split(' ')[0]))
616
+ db.exec(`ALTER TABLE ${OUTBOX_IMAGES} ADD COLUMN ${column}`);
617
+ // Images written before the row key existed take it from their operation.
618
+ if (!imageColumns.some((row) => row.name === 'row_id'))
619
+ db.exec(
620
+ `UPDATE ${OUTBOX_IMAGES} SET (tbl,row_id)=(SELECT json_extract(operations,'$['||op_index||'].table'),json_extract(operations,'$['||op_index||'].rowId') FROM ${OUTBOX_TABLE} WHERE client_commit_id=${OUTBOX_IMAGES}.client_commit_id)`,
621
+ );
622
+ db.exec(
623
+ `CREATE INDEX IF NOT EXISTS ${OUTBOX_IMAGES}_row ON ${OUTBOX_IMAGES}(tbl,row_id)`,
624
+ );
608
625
  createTable(
609
626
  OUTCOMES_TABLE,
610
627
  "seq INTEGER PRIMARY KEY AUTOINCREMENT,client_commit_id TEXT NOT NULL UNIQUE,status TEXT NOT NULL CHECK(status IN ('applied','cached','conflict','rejected')),recorded_at_ms INTEGER NOT NULL,results TEXT NOT NULL,operations TEXT,resolution TEXT NOT NULL DEFAULT 'active' CHECK(resolution IN ('active','resolved_keep_server','superseded','dismissed')),resolved_at_ms INTEGER,replacement_client_commit_id TEXT",
@@ -620,22 +637,47 @@ export function ensureLocalBookkeepingSchema(db: ClientDatabase): void {
620
637
  `CREATE INDEX IF NOT EXISTS ${OUTCOMES_TABLE}_resolution_seq ON ${OUTCOMES_TABLE}(resolution,seq)`,
621
638
  );
622
639
  createTable(
623
- SUBSCRIPTIONS_TABLE,
624
- "id TEXT PRIMARY KEY,tbl TEXT NOT NULL,requested_scopes TEXT NOT NULL,params TEXT,cursor INTEGER NOT NULL DEFAULT -1,bootstrap_state TEXT,effective_scopes TEXT,status TEXT NOT NULL DEFAULT 'active',reason_code TEXT",
640
+ UNITS_TABLE,
641
+ "id TEXT PRIMARY KEY,scopes TEXT NOT NULL,explicit INTEGER NOT NULL DEFAULT 0,status TEXT NOT NULL DEFAULT 'active',reason_code TEXT,cursor INTEGER DEFAULT -1,bootstrap_state TEXT,seeded TEXT NOT NULL DEFAULT '[]',echo TEXT",
625
642
  );
626
- // §4.8 window registry: which units (scope values) of a window base are
627
- // live locally — the completeness oracle (I3) and the shrink driver
628
- // (a unit's omission from the next pull unregisters it, §4.1).
643
+ // §4.8 window registry: base + value → the unit it holds, the
644
+ // completeness oracle and one of a unit's references (§4.1).
629
645
  createTable(
630
646
  WINDOWS_TABLE,
631
647
  'base TEXT NOT NULL,unit TEXT NOT NULL,sub_id TEXT NOT NULL,PRIMARY KEY(base,unit)',
632
648
  );
633
- // §4.8 E1: units that left the window but still had outbox-pinned rows.
634
- // Retried when the outbox drains; cancelled if the unit re-enters.
649
+ // §4.8 E1: per-table scopes of units that left with pinned or unevicted
650
+ // rows. Retried when the outbox drains; cancelled when the unit re-enters.
635
651
  createTable(
636
652
  PENDING_EVICTIONS,
637
- 'sub_id TEXT PRIMARY KEY,tbl TEXT NOT NULL,effective_scopes TEXT NOT NULL',
653
+ 'unit_id TEXT NOT NULL,tbl TEXT NOT NULL,effective_scopes TEXT NOT NULL,PRIMARY KEY(unit_id,tbl)',
638
654
  );
655
+ // §9: a replica written under wire version 3 keeps its outbox, journal,
656
+ // rows and pending evictions and registers its units fresh. Its
657
+ // subscriptions, cursors, echoes, resume tokens and window entries go.
658
+ const legacyEvictions = '_syncular_window_pending_evict';
659
+ if (
660
+ db.query(
661
+ `SELECT 1 FROM sqlite_master WHERE type='table' AND name='${legacyEvictions}'`,
662
+ ).length > 0
663
+ ) {
664
+ if (
665
+ db.query(
666
+ `SELECT 1 FROM ${legacyEvictions} WHERE NOT json_valid(effective_scopes) OR json_type(effective_scopes)<>'object' OR EXISTS(SELECT 1 FROM json_each(effective_scopes) WHERE json_type(value)<>'array' OR EXISTS(SELECT 1 FROM json_each(value) v WHERE v.type<>'text'))`,
667
+ ).length > 0
668
+ )
669
+ throw new ClientSyncError(
670
+ 'sync.local_corrupt',
671
+ 'a version 3 pending eviction cannot be upgraded',
672
+ );
673
+ db.exec(
674
+ `INSERT OR REPLACE INTO ${PENDING_EVICTIONS} SELECT sub_id,tbl,effective_scopes FROM ${legacyEvictions}`,
675
+ );
676
+ db.exec(`DROP TABLE ${legacyEvictions}`);
677
+ db.exec('DROP TABLE IF EXISTS _syncular_subscriptions');
678
+ db.exec(`DELETE FROM ${WINDOWS_TABLE}`);
679
+ resetUnits(db);
680
+ }
639
681
  });
640
682
  }
641
683
 
@@ -656,10 +698,10 @@ const RESERVED_TABLE_PREFIX = '_syncular_';
656
698
  * generated schema created — discovered from `sqlite_master`, since a
657
699
  * bump may add/remove tables) and recreate the synced tables from the
658
700
  * NEW schema. Bookkeeping tables (`_syncular_*`: outbox, meta,
659
- * subscriptions, blob cache) are preserved. RFC 0005's container is not
701
+ * units, blob cache) are preserved. RFC 0005's container is not
660
702
  * reachable from here: it lives in its own database file, so this reset cannot
661
703
  * see or destroy it. Caller owns the surrounding transaction and the
662
- * subscription-state reset (state.ts).
704
+ * unit-state reset (state.ts).
663
705
  */
664
706
  export function dropAndRecreateSyncedTables(
665
707
  db: ClientDatabase,
@@ -814,7 +856,7 @@ export type JsonRowValue =
814
856
  | null
815
857
  | { readonly $bytes: string };
816
858
 
817
- function bytesToHex(bytes: Uint8Array): string {
859
+ export function bytesToHex(bytes: Uint8Array): string {
818
860
  let out = '';
819
861
  for (const byte of bytes) out += byte.toString(16).padStart(2, '0');
820
862
  return out;