@syncular/client 0.59.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 (66) hide show
  1. package/README.md +27 -27
  2. package/dist/apply.d.ts +6 -5
  3. package/dist/apply.js +52 -25
  4. package/dist/authority.js +21 -16
  5. package/dist/blob.d.ts +4 -4
  6. package/dist/bun-database.js +3 -16
  7. package/dist/client.d.ts +57 -66
  8. package/dist/client.js +701 -796
  9. package/dist/devtools.d.ts +2 -2
  10. package/dist/devtools.js +3 -3
  11. package/dist/diagnostics.d.ts +17 -28
  12. package/dist/diagnostics.js +1 -2
  13. package/dist/errors.d.ts +1 -1
  14. package/dist/errors.js +1 -1
  15. package/dist/failed-overlay.js +4 -1
  16. package/dist/http.js +10 -4
  17. package/dist/invalidation.d.ts +3 -4
  18. package/dist/invalidation.js +9 -22
  19. package/dist/native-bridge.d.ts +7 -16
  20. package/dist/native-bridge.js +16 -41
  21. package/dist/node-database.js +16 -25
  22. package/dist/outbox.js +1 -0
  23. package/dist/progress.d.ts +2 -2
  24. package/dist/query-guard.d.ts +15 -6
  25. package/dist/query-guard.js +38 -6
  26. package/dist/reactive-store.js +2 -2
  27. package/dist/remote.js +9 -9
  28. package/dist/schema.d.ts +3 -2
  29. package/dist/schema.js +28 -12
  30. package/dist/state.d.ts +69 -36
  31. package/dist/state.js +178 -89
  32. package/dist/sync-scheduler.js +2 -2
  33. package/dist/transport.d.ts +2 -2
  34. package/dist/window.d.ts +30 -52
  35. package/dist/window.js +33 -77
  36. package/dist/worker-core.js +6 -6
  37. package/dist/worker-host.d.ts +9 -8
  38. package/dist/worker-host.js +11 -11
  39. package/dist/worker-protocol.d.ts +9 -8
  40. package/package.json +3 -3
  41. package/src/apply.ts +87 -33
  42. package/src/authority.ts +31 -17
  43. package/src/blob.ts +4 -3
  44. package/src/bun-database.ts +9 -14
  45. package/src/client.ts +886 -1037
  46. package/src/devtools.ts +5 -5
  47. package/src/diagnostics.ts +17 -37
  48. package/src/errors.ts +1 -1
  49. package/src/failed-overlay.ts +6 -1
  50. package/src/http.ts +13 -8
  51. package/src/invalidation.ts +9 -29
  52. package/src/native-bridge.ts +22 -58
  53. package/src/node-database.ts +26 -27
  54. package/src/outbox.ts +1 -0
  55. package/src/progress.ts +2 -2
  56. package/src/query-guard.ts +45 -8
  57. package/src/reactive-store.ts +2 -2
  58. package/src/remote.ts +12 -16
  59. package/src/schema.ts +48 -13
  60. package/src/state.ts +246 -125
  61. package/src/sync-scheduler.ts +2 -2
  62. package/src/transport.ts +2 -2
  63. package/src/window.ts +55 -134
  64. package/src/worker-core.ts +6 -6
  65. package/src/worker-host.ts +13 -16
  66. package/src/worker-protocol.ts +8 -8
package/src/devtools.ts CHANGED
@@ -6,7 +6,7 @@
6
6
  *
7
7
  * __SYNCULAR__.clients // the live entries
8
8
  * await __SYNCULAR__.snapshot() // one plain object per client:
9
- * // outbox depth, subscriptions,
9
+ * // outbox depth, units,
10
10
  * // conflicts, syncNeeded, upgrading,
11
11
  * // last invalidation
12
12
  * __SYNCULAR__.clients[0].ref // the client itself — full API
@@ -26,7 +26,7 @@ export interface DevtoolsRegistration {
26
26
  readonly clientId: () => string;
27
27
  readonly role: () => string;
28
28
  readonly outbox: () => Promise<number>;
29
- readonly subscriptions: () => Promise<readonly unknown[]>;
29
+ readonly units: () => Promise<readonly unknown[]>;
30
30
  readonly conflicts: () => Promise<number>;
31
31
  readonly rejections: () => Promise<number>;
32
32
  readonly syncNeeded: () => Promise<boolean>;
@@ -87,9 +87,9 @@ function registryOn(host: Record<string, unknown>): DevtoolsRegistry {
87
87
  clientId: entry.clientId(),
88
88
  role: entry.role(),
89
89
  outbox: await entry.outbox().catch(() => 'unavailable'),
90
- subscriptions: await entry
91
- .subscriptions()
92
- .then((subs) => subs.length)
90
+ units: await entry
91
+ .units()
92
+ .then((units) => units.length)
93
93
  .catch(() => 'unavailable'),
94
94
  conflicts: await entry.conflicts().catch(() => 'unavailable'),
95
95
  rejections: await entry.rejections().catch(() => 'unavailable'),
@@ -7,8 +7,7 @@
7
7
  */
8
8
  import type { SecurityLifecycle } from './client';
9
9
 
10
- export const CLIENT_DIAGNOSTICS_VERSION = 1 as const;
11
- export const MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS = 256;
10
+ export const CLIENT_DIAGNOSTICS_VERSION = 2 as const;
12
11
  export const MAX_DIAGNOSTIC_DOMAINS = 256;
13
12
  export const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
14
13
 
@@ -66,38 +65,15 @@ export interface ClientDiagnosticsHost {
66
65
  readonly realtimeRetryDelayMs?: number;
67
66
  }
68
67
 
69
- export interface ExpectedDiagnosticSubscription {
70
- /** Application-owned stable identifier. It must never contain PHI. */
71
- readonly id: string;
72
- /** Generated schema table name. */
73
- readonly table: string;
74
- }
75
-
76
- export interface ClientDiagnosticsRequest {
77
- /**
78
- * Optional bounded intent list. Missing registrations are returned as
79
- * `unregistered`, allowing a zero-row security scope to fail closed without
80
- * reading private Syncular tables. Values/scopes are intentionally absent.
81
- */
82
- readonly expectedSubscriptions?: readonly ExpectedDiagnosticSubscription[];
83
- }
84
-
85
- export type DiagnosticSubscriptionState =
86
- | 'unregistered'
87
- | 'bootstrapping'
88
- | 'complete'
89
- | 'reset'
90
- | 'revoked'
91
- | 'failed';
92
-
93
- export interface DiagnosticSubscription {
94
- readonly id: string;
95
- readonly table: string;
96
- readonly state: DiagnosticSubscriptionState;
97
- readonly complete: boolean;
98
- /** Last fully applied local commit sequence; absent when unregistered. */
99
- readonly cursor?: number;
100
- readonly reasonCode?: string;
68
+ /** §7.6: registered units per state; a unit id never enters diagnostics. */
69
+ export interface DiagnosticUnits {
70
+ readonly bootstrapping: number;
71
+ readonly complete: number;
72
+ readonly reset: number;
73
+ readonly revoked: number;
74
+ readonly failed: number;
75
+ /** Distinct stable reason codes of registered units, ascending. */
76
+ readonly reasonCodes: readonly string[];
101
77
  }
102
78
 
103
79
  export interface DiagnosticRoundCounters {
@@ -140,7 +116,8 @@ export interface DiagnosticLastChange {
140
116
  readonly recordedAtMs: number;
141
117
  /** Generated table names only; no scope keys or row ids. */
142
118
  readonly tables: readonly string[];
143
- /** Generated table names for changed window registrations/completeness. */
119
+ /** Selected variables of window bases whose registration or completeness
120
+ * changed. */
144
121
  readonly windows: readonly string[];
145
122
  readonly domainsTruncated: boolean;
146
123
  readonly statusChanged: boolean;
@@ -201,8 +178,11 @@ export interface ClientDiagnosticsSnapshot {
201
178
  readonly expiresAtMs?: number;
202
179
  readonly errorCode?: string;
203
180
  };
204
- readonly subscriptions: readonly DiagnosticSubscription[];
205
- readonly subscriptionsTruncated: boolean;
181
+ readonly units: DiagnosticUnits;
182
+ /** Units the next registration list carries; the server limit counts these (SPEC §4.1). */
183
+ readonly activeUnits: number;
184
+ /** §4.5 replica cursor; `-1` while no unit is live. */
185
+ readonly replicaCursor: number;
206
186
  readonly lastRound?: DiagnosticLastRound;
207
187
  readonly lastChange?: DiagnosticLastChange;
208
188
  readonly storage: ClientDiagnosticsStorage;
package/src/errors.ts CHANGED
@@ -9,7 +9,7 @@ export const STORAGE_BUSY_CODE = 'client.storage_busy';
9
9
  */
10
10
  export const STORAGE_FENCED_CODE = 'client.storage_fenced';
11
11
 
12
- /** The browser cannot provide the persistent storage APIs Syncular requires. */
12
+ /** The runtime cannot provide the storage APIs Syncular requires. */
13
13
  export const STORAGE_UNAVAILABLE_CODE = 'client.storage_unavailable';
14
14
 
15
15
  /** A local read hit SQLITE_CORRUPT or SQLITE_NOTADB (SPEC §7.5). */
@@ -37,6 +37,9 @@ export function ensureFailedOverlaySchema(db: ClientDatabase): void {
37
37
  for (const column of ['unique_conflicts TEXT', 'commit_seq INTEGER'])
38
38
  if (!columns.some((row) => row.name === column.split(' ')[0]))
39
39
  db.exec(`ALTER TABLE ${RETAINED_ROWS} ADD COLUMN ${column}`);
40
+ db.exec(
41
+ `CREATE INDEX IF NOT EXISTS ${RETAINED_ROWS}_row ON ${RETAINED_ROWS}(tbl,id)`,
42
+ );
40
43
  }
41
44
 
42
45
  export function retainedBaseWrite(
@@ -176,8 +179,10 @@ function retainedRows(
176
179
  scope?: OverlayScope,
177
180
  acknowledged?: boolean,
178
181
  ) {
182
+ // A scope joins through the (tbl, id) index; a scan per applied commit
183
+ // would make a drained batch quadratic.
179
184
  return db.query(
180
- `SELECT * FROM ${RETAINED_ROWS} WHERE (?1 IS NULL OR json_array(tbl,id) IN(SELECT value FROM json_each(?1)) OR json_array(tbl) IN(SELECT value FROM json_each(?1)))${acknowledged === undefined ? '' : ` AND commit_seq IS${acknowledged ? ' NOT' : ''} NULL`} ORDER BY commit_seq,at,commit_id,idx`,
185
+ `SELECT * FROM ${RETAINED_ROWS} WHERE (?1 IS NULL OR rowid IN(SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON r.tbl=json_extract(k.value,'$[0]') AND r.id=json_extract(k.value,'$[1]') UNION SELECT r.rowid FROM json_each(?1) k JOIN ${RETAINED_ROWS} r ON json_array_length(k.value)=1 AND r.tbl=json_extract(k.value,'$[0]')))${acknowledged === undefined ? '' : ` AND commit_seq IS${acknowledged ? ' NOT' : ''} NULL`} ORDER BY commit_seq,at,commit_id,idx`,
181
186
  [scope ? JSON.stringify(scope) : null],
182
187
  );
183
188
  }
package/src/http.ts CHANGED
@@ -7,6 +7,7 @@
7
7
  import type { BlobTransport } from './blob';
8
8
  import { SSP2_CONTENT_TYPE } from './content-type';
9
9
  import { ClientSyncError, transportFailed } from './errors';
10
+ import { hexToBytes } from './schema';
10
11
  import type {
11
12
  RealtimeConnector,
12
13
  RemoteOperationTransport,
@@ -470,15 +471,19 @@ export function httpBlobTransport(
470
471
  return { kind: 'none' };
471
472
  },
472
473
  // §5.9.3: direct-to-storage PUT — no host auth (the URL is the grant).
473
- uploadToUrl: async (url, bytes, mediaType, signal) => {
474
+ uploadToUrl: async (blobId, url, bytes, mediaType, signal) => {
475
+ // The grant signs content-length (set by fetch from the body) and the
476
+ // checksum, the blob id's digest, so the object store rejects any other
477
+ // bytes without the client hashing the body again (§5.9.3).
478
+ const hex = /^sha256:([0-9a-f]{64})$/.exec(blobId)?.[1];
479
+ if (hex === undefined) {
480
+ throw new ClientSyncError(
481
+ 'sync.invalid_request',
482
+ 'the blob id is not a sha256 blob id (§5.9.1)',
483
+ );
484
+ }
485
+ const checksum = btoa(String.fromCharCode(...hexToBytes(hex)));
474
486
  const body = bytes.slice().buffer as ArrayBuffer;
475
- // The grant signs content-length (set by fetch from the body) and this
476
- // checksum, so the object store rejects any other bytes (§5.9.3).
477
- const checksum = btoa(
478
- String.fromCharCode(
479
- ...new Uint8Array(await crypto.subtle.digest('SHA-256', body)),
480
- ),
481
- );
482
487
  const response = await transfer('signed blob upload failed', () =>
483
488
  doFetch(url, {
484
489
  method: 'PUT',
@@ -19,7 +19,7 @@ export interface TableChange {
19
19
 
20
20
  export interface WindowChange {
21
21
  readonly baseKey: string;
22
- readonly table: string;
22
+ /** Changed values of the base. */
23
23
  readonly units: ReadonlySet<string>;
24
24
  }
25
25
 
@@ -51,7 +51,6 @@ export interface ClientChangeBatch {
51
51
  readonly outcomesChanged: boolean;
52
52
  /** Server COMMIT frames applied by this transaction, when present. */
53
53
  readonly appliedCommits?: readonly {
54
- readonly subscriptionId: string;
55
54
  readonly table: string;
56
55
  readonly commitSeq: number;
57
56
  readonly source: 'delta' | 'pull';
@@ -84,18 +83,13 @@ interface MutableTableChange {
84
83
  scopeKeys: Set<string> | undefined;
85
84
  }
86
85
 
87
- interface MutableWindowChange {
88
- table: string;
89
- units: Set<string>;
90
- }
91
-
92
86
  /**
93
87
  * Per-observer-transaction accumulator. It contains no revision itself: the
94
88
  * transaction wrapper assigns the revision only after all writes succeeded.
95
89
  */
96
90
  export class ChangeAccumulator {
97
91
  readonly #tables = new Map<string, MutableTableChange>();
98
- readonly #windows = new Map<string, MutableWindowChange>();
92
+ readonly #windows = new Map<string, Set<string>>();
99
93
  #status = false;
100
94
  #conflicts = false;
101
95
  #rejections = false;
@@ -129,17 +123,11 @@ export class ChangeAccumulator {
129
123
  current.scopeKeys?.add(key);
130
124
  }
131
125
 
132
- /** Record registration/completeness change for one window unit. */
133
- window(baseKey: string, table: string, unit: string): void {
126
+ /** Record registration/completeness change for one window value. */
127
+ window(baseKey: string, value: string): void {
134
128
  const current = this.#windows.get(baseKey);
135
- if (current === undefined) {
136
- this.#windows.set(baseKey, { table, units: new Set([unit]) });
137
- return;
138
- }
139
- if (current.table !== table) {
140
- throw new Error(`window base ${JSON.stringify(baseKey)} changed tables`);
141
- }
142
- current.units.add(unit);
129
+ if (current === undefined) this.#windows.set(baseKey, new Set([value]));
130
+ else current.add(value);
143
131
  }
144
132
 
145
133
  status(): void {
@@ -222,13 +210,8 @@ export class ChangeAccumulator {
222
210
  );
223
211
  }
224
212
  const windows: WindowChange[] = [];
225
- for (const [baseKey, change] of this.#windows) {
226
- windows.push({
227
- baseKey,
228
- table: change.table,
229
- units: change.units,
230
- });
231
- }
213
+ for (const [baseKey, units] of this.#windows)
214
+ windows.push({ baseKey, units });
232
215
  return {
233
216
  revision,
234
217
  tables,
@@ -289,16 +272,13 @@ export type InvalidationListener = (event: InvalidationEvent) => void;
289
272
  export function invalidationFromChange(
290
273
  batch: ClientChangeBatch,
291
274
  ): InvalidationEvent | undefined {
292
- if (batch.tables.length === 0 && batch.windows.length === 0) return undefined;
275
+ if (batch.tables.length === 0) return undefined;
293
276
  const tables = new Set<string>();
294
277
  const scopeKeys = new Set<string>();
295
278
  for (const change of batch.tables) {
296
279
  tables.add(change.table);
297
280
  for (const key of change.scopeKeys ?? []) scopeKeys.add(key);
298
281
  }
299
- // Window-only changes project the table for old completeness consumers.
300
- // The exact API still keeps this distinct, so new table-only reads do not run.
301
- for (const change of batch.windows) tables.add(change.table);
302
282
  return { tables, scopeKeys };
303
283
  }
304
284
 
@@ -27,10 +27,10 @@ import {
27
27
  type WindowState,
28
28
  } from './client';
29
29
  import type { SqlRow, SqlValue } from './database';
30
- import type { PresenceErrorCode } from '@syncular/core';
30
+ import type { PresenceErrorCode, UnitScopes } from '@syncular/core';
31
31
  import {
32
+ CLIENT_DIAGNOSTICS_VERSION,
32
33
  type ClientDiagnosticsListener,
33
- type ClientDiagnosticsRequest,
34
34
  type ClientDiagnosticsSnapshot,
35
35
  withClientDiagnosticsHost,
36
36
  } from './diagnostics';
@@ -206,19 +206,8 @@ function decodeChangeBatch(value: unknown): ClientChangeBatch | undefined {
206
206
  ? raw.windows.flatMap((entry) => {
207
207
  if (entry === null || typeof entry !== 'object') return [];
208
208
  const item = entry as Record<string, unknown>;
209
- if (
210
- typeof item.baseKey !== 'string' ||
211
- typeof item.table !== 'string'
212
- ) {
213
- return [];
214
- }
215
- return [
216
- {
217
- baseKey: item.baseKey,
218
- table: item.table,
219
- units: toStringSet(item.units),
220
- },
221
- ];
209
+ if (typeof item.baseKey !== 'string') return [];
210
+ return [{ baseKey: item.baseKey, units: toStringSet(item.units) }];
222
211
  })
223
212
  : [];
224
213
  const appliedCommits: NonNullable<
@@ -230,7 +219,6 @@ function decodeChangeBatch(value: unknown): ClientChangeBatch | undefined {
230
219
  if (entry === null || typeof entry !== 'object') return undefined;
231
220
  const item = entry as Record<string, unknown>;
232
221
  if (
233
- typeof item.subscriptionId !== 'string' ||
234
222
  typeof item.table !== 'string' ||
235
223
  typeof item.commitSeq !== 'number' ||
236
224
  !Number.isSafeInteger(item.commitSeq) ||
@@ -239,7 +227,6 @@ function decodeChangeBatch(value: unknown): ClientChangeBatch | undefined {
239
227
  )
240
228
  return undefined;
241
229
  appliedCommits.push({
242
- subscriptionId: item.subscriptionId,
243
230
  table: item.table,
244
231
  commitSeq: item.commitSeq,
245
232
  source: item.source,
@@ -558,14 +545,13 @@ export abstract class NativeBridgeClient implements PromiseMethods<ClientSnapsho
558
545
  const batch = decodeChangeBatch(event.batch);
559
546
  if (batch === undefined) break;
560
547
  fanOut(this.#changeListeners, batch);
561
- if (batch.tables.length === 0 && batch.windows.length === 0) break;
548
+ if (batch.tables.length === 0) break;
562
549
  const tables = new Set<string>();
563
550
  const scopeKeys = new Set<string>();
564
551
  for (const table of batch.tables) {
565
552
  tables.add(table.table);
566
553
  for (const key of table.scopeKeys ?? []) scopeKeys.add(key);
567
554
  }
568
- for (const window of batch.windows) tables.add(window.table);
569
555
  fanOut(this.#invalidationListeners, { tables, scopeKeys });
570
556
  break;
571
557
  }
@@ -581,7 +567,7 @@ export abstract class NativeBridgeClient implements PromiseMethods<ClientSnapsho
581
567
  if (
582
568
  snapshot === null ||
583
569
  typeof snapshot !== 'object' ||
584
- snapshot.version !== 1 ||
570
+ snapshot.version !== CLIENT_DIAGNOSTICS_VERSION ||
585
571
  snapshot.host === undefined
586
572
  )
587
573
  break;
@@ -738,14 +724,14 @@ export abstract class NativeBridgeClient implements PromiseMethods<ClientSnapsho
738
724
  params: encodeValue(statement.params ?? []),
739
725
  })),
740
726
  coverage: request.coverage ?? [],
741
- subscriptions: request.subscriptions ?? [],
727
+ units: request.units ?? [],
742
728
  commitIds: request.commitIds ?? [],
743
729
  ...(request.owner !== undefined ? { owner: request.owner } : {}),
744
730
  })) as {
745
731
  revision: string;
746
732
  queries: readonly (readonly Record<string, unknown>[])[];
747
733
  coverage: SnapshotRead['coverage'];
748
- subscriptions: SnapshotRead['subscriptions'];
734
+ units: SnapshotRead['units'];
749
735
  deliveries: SnapshotRead['deliveries'];
750
736
  };
751
737
  return {
@@ -754,7 +740,7 @@ export abstract class NativeBridgeClient implements PromiseMethods<ClientSnapsho
754
740
  rows.map((row) => this.decodeRow(row)),
755
741
  ),
756
742
  coverage: result.coverage,
757
- subscriptions: result.subscriptions,
743
+ units: result.units,
758
744
  deliveries: result.deliveries.map((delivery) =>
759
745
  delivery.status === 'known'
760
746
  ? { ...delivery, outcome: this.#commitOutcome(delivery.outcome) }
@@ -774,12 +760,11 @@ export abstract class NativeBridgeClient implements PromiseMethods<ClientSnapsho
774
760
  return (await this.command('statusSnapshot', {})) as SyncStatusSnapshot;
775
761
  }
776
762
 
777
- async diagnosticsSnapshot(
778
- request: ClientDiagnosticsRequest = {},
779
- ): Promise<ClientDiagnosticsSnapshot> {
780
- const snapshot = (await this.command('diagnosticsSnapshot', {
781
- expectedSubscriptions: request.expectedSubscriptions ?? [],
782
- })) as ClientDiagnosticsSnapshot;
763
+ async diagnosticsSnapshot(): Promise<ClientDiagnosticsSnapshot> {
764
+ const snapshot = (await this.command(
765
+ 'diagnosticsSnapshot',
766
+ {},
767
+ )) as ClientDiagnosticsSnapshot;
783
768
  return withClientDiagnosticsHost(snapshot, {
784
769
  ...snapshot.host,
785
770
  kind: this.#kind,
@@ -1007,37 +992,16 @@ export abstract class NativeBridgeClient implements PromiseMethods<ClientSnapsho
1007
992
  };
1008
993
  }
1009
994
 
1010
- async subscribe(input: {
1011
- readonly id: string;
1012
- readonly table: string;
1013
- readonly scopes?: Record<string, readonly string[]>;
1014
- readonly params?: string;
1015
- }): Promise<void> {
1016
- await this.command('subscribe', {
1017
- id: input.id,
1018
- table: input.table,
1019
- scopes: input.scopes ?? {},
1020
- ...(input.params !== undefined ? { params: input.params } : {}),
1021
- });
995
+ /** §4.1: register one unit; returns its id. */
996
+ async subscribe(scopes: UnitScopes): Promise<string> {
997
+ return ((await this.command('subscribe', { scopes })) as { id: string }).id;
1022
998
  }
1023
999
 
1024
- /** Register several subscriptions in one local transaction. */
1025
- async subscribeMany(
1026
- inputs: readonly {
1027
- readonly id: string;
1028
- readonly table: string;
1029
- readonly scopes?: Record<string, readonly string[]>;
1030
- readonly params?: string;
1031
- }[],
1032
- ): Promise<void> {
1033
- await this.command('subscribeMany', {
1034
- subscriptions: inputs.map((input) => ({
1035
- id: input.id,
1036
- table: input.table,
1037
- scopes: input.scopes ?? {},
1038
- ...(input.params !== undefined ? { params: input.params } : {}),
1039
- })),
1040
- });
1000
+ /** Register several units in one local transaction; returns their ids. */
1001
+ async subscribeMany(units: readonly UnitScopes[]): Promise<string[]> {
1002
+ return (
1003
+ (await this.command('subscribeMany', { units })) as { ids: string[] }
1004
+ ).ids;
1041
1005
  }
1042
1006
 
1043
1007
  async unsubscribe(id: string): Promise<void> {
@@ -2,7 +2,7 @@
2
2
  * `ClientDatabase` on Node's built-in `node:sqlite`. Semantics mirror the Bun
3
3
  * adapter: synchronous queries, nested transactions, and SQLite image attach.
4
4
  */
5
- import { DatabaseSync, type SQLInputValue } from 'node:sqlite';
5
+ import { DatabaseSync, type SQLInputValue, StatementSync } from 'node:sqlite';
6
6
  import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
7
7
  import { tmpdir } from 'node:os';
8
8
  import { join } from 'node:path';
@@ -14,7 +14,8 @@ import {
14
14
  type SqlRow,
15
15
  type SqlValue,
16
16
  } from './database';
17
- import { prepareReadOnly, SQL_BLANK } from './query-guard';
17
+ import { ClientSyncError, STORAGE_UNAVAILABLE_CODE } from './errors';
18
+ import { prepareReadOnly, runReadOnly } from './query-guard';
18
19
 
19
20
  function coerceParams(params: readonly SqlValue[]): SQLInputValue[] {
20
21
  return params.map((value): SQLInputValue => {
@@ -39,9 +40,19 @@ function normalizeRow(row: Record<string, unknown>): SqlRow {
39
40
  export class NodeClientDatabase implements ClientDatabase {
40
41
  readonly db: DatabaseSync;
41
42
  readonly #path: string;
43
+ readonly #proven = new Set<string>();
42
44
  #tx = { depth: 0 };
43
45
 
44
46
  constructor(path = ':memory:') {
47
+ // The raw-SQL tier reads result columns through `columns()` (Node 22.16).
48
+ if (typeof StatementSync.prototype.columns !== 'function') {
49
+ throw new ClientSyncError(
50
+ STORAGE_UNAVAILABLE_CODE,
51
+ 'The node:sqlite adapter needs Node 22.16 or newer.',
52
+ false,
53
+ { runtime: 'node', version: process.versions.node, minimum: '22.16.0' },
54
+ );
55
+ }
45
56
  this.#path = path;
46
57
  this.db = new DatabaseSync(path);
47
58
  try {
@@ -65,32 +76,20 @@ export class NodeClientDatabase implements ClientDatabase {
65
76
  queryReadOnly(sql: string, params: readonly SqlValue[] = []): SqlRow[] {
66
77
  const statement = prepareReadOnly(sql, () => {
67
78
  const prepared = this.db.prepare(sql);
68
- // node:sqlite exposes no `sqlite3_stmt_readonly` (and no column count
69
- // before Node 22.16), so the verb decides: SELECT, VALUES, EXPLAIN, or
70
- // a WITH clause whose first keyword outside parentheses is SELECT or
71
- // VALUES.
72
- const body = prepared.sourceSQL.replace(SQL_BLANK, '');
73
- const verb = /^[a-z]+/i.exec(body)?.[0].toLowerCase();
74
- let reads = verb === 'select' || verb === 'values' || verb === 'explain';
75
- if (verb === 'with') {
76
- let depth = 0;
77
- for (const [token] of body.matchAll(
78
- /'[^']*'|"[^"]*"|`[^`]*`|\[[^\]]*\]|--[^\n]*|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$)|[\w$\u0080-\uffff]+|[\s\S]/g,
79
- )) {
80
- if (token === '(') depth += 1;
81
- else if (token === ')') depth -= 1;
82
- else if (
83
- depth === 0 &&
84
- /^(?:select|values|insert|update|delete|replace)$/i.test(token)
85
- ) {
86
- reads = /^(?:select|values)$/i.test(token);
87
- break;
88
- }
89
- }
90
- }
91
- return [prepared, prepared.sourceSQL, reads] as const;
79
+ return [
80
+ prepared,
81
+ prepared.sourceSQL,
82
+ prepared.columns().length > 0,
83
+ ] as const;
92
84
  });
93
- return statement.all(...coerceParams(params)).map(normalizeRow);
85
+ return runReadOnly(
86
+ this.#proven,
87
+ sql,
88
+ (pragma) => this.db.exec(pragma),
89
+ // SQLITE_READONLY
90
+ (error) => (error as { errcode?: unknown }).errcode === 8,
91
+ () => statement.all(...coerceParams(params)).map(normalizeRow),
92
+ );
94
93
  }
95
94
 
96
95
  /** RFC 0005: a sibling file beside the replica, e.g. `<path>.prev-context`. */
package/src/outbox.ts CHANGED
@@ -307,6 +307,7 @@ export async function encodeOutboxCommit(
307
307
  return {
308
308
  type: 'PUSH_COMMIT',
309
309
  clientCommitId: commit.clientCommitId,
310
+ clientSeq: commit.seq,
310
311
  operations,
311
312
  };
312
313
  }
package/src/progress.ts CHANGED
@@ -1,11 +1,11 @@
1
1
  import type { TransportCauseKind } from './diagnostics';
2
2
 
3
- /** Ephemeral sync work, independent of committed change notifications (SPEC §7.6). */
3
+ /** Ephemeral sync work, independent of committed change notifications (SPEC §7.7). */
4
4
  export interface SyncProgress {
5
5
  readonly attempt: number;
6
6
  readonly state: 'running' | 'complete' | 'failed';
7
7
  readonly phase: 'request' | 'download' | 'import';
8
- readonly subscriptionId?: string;
8
+ readonly unitId?: string;
9
9
  readonly table?: string;
10
10
  readonly segmentId?: string | undefined;
11
11
  readonly bytesReceived: number;
@@ -3,8 +3,9 @@
3
3
  * `snapshotRead()`, the untrusted raw-SQL tier. Each `ClientDatabase` adapter
4
4
  * prepares only the first statement and reports what SQLite knows about it:
5
5
  *
6
- * 1. READ-ONLY. SQLite decides (`sqlite3_stmt_readonly`) and the statement
7
- * returns columns, which refuses `BEGIN`, `ATTACH` and the other
6
+ * 1. READ-ONLY. SQLite decides (`sqlite3_stmt_readonly`, or `query_only`
7
+ * on the first run of a text, `runReadOnly`) and the statement returns
8
+ * columns, which refuses `BEGIN`, `ATTACH` and the other
8
9
  * read-only statements that change the connection. A write against the
9
10
  * local mirror bypasses the outbox (SPEC §7.1); writes go through
10
11
  * `client.mutate([...])`.
@@ -25,12 +26,8 @@ export class RawSqlError extends Error {
25
26
  override readonly name = 'RawSqlError';
26
27
  }
27
28
 
28
- /** Leading whitespace, comments and empty statements. */
29
- export const SQL_BLANK =
30
- /^(?:[\s;]|--[^\n]*(?:\n|$)|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$))*/;
31
-
32
29
  /** Refuse a statement the raw-SQL tier does not run. */
33
- export function refuseRawSql(): never {
30
+ function refuseRawSql(): never {
34
31
  throw new RawSqlError(
35
32
  'client.query() runs read-only statements and no PRAGMA; write through client.mutate() so the outbox records it (SPEC §7.1).',
36
33
  );
@@ -53,9 +50,49 @@ export function prepareReadOnly<S>(
53
50
  refuseRawSql();
54
51
  }
55
52
  const [statement, first, reads] = prepare();
56
- if (sql.slice(first.length).replace(SQL_BLANK, '') !== '') {
53
+ if (
54
+ sql
55
+ .slice(first.length)
56
+ .replace(
57
+ /^(?:[\s;]|--[^\n]*(?:\n|$)|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$))*/,
58
+ '',
59
+ ) !== ''
60
+ ) {
57
61
  throw new RawSqlError('client.query() runs one statement per call.');
58
62
  }
59
63
  if (!reads) refuseRawSql();
60
64
  return statement;
61
65
  }
66
+
67
+ /**
68
+ * Run a statement `prepareReadOnly` accepted on an adapter without
69
+ * `sqlite3_stmt_readonly` (bun:sqlite before 1.4.4, node:sqlite). SQLite
70
+ * refuses a write when it runs: under `query_only` a write transaction fails
71
+ * before it changes anything, and `refused` recognizes that error. The
72
+ * verdict depends on the text alone, since a write fails at its write
73
+ * transaction whether or not it touches a row, so a text that completed
74
+ * under `query_only` joins `proven` and later runs skip the pragma: a flag
75
+ * pragma expires every prepared statement of the connection. `proven` is per
76
+ * connection and cleared at 512 texts, so dynamic SQL cannot grow it.
77
+ */
78
+ export function runReadOnly<R>(
79
+ proven: Set<string>,
80
+ sql: string,
81
+ pragma: (sql: string) => void,
82
+ refused: (error: unknown) => boolean,
83
+ run: () => R,
84
+ ): R {
85
+ if (proven.has(sql)) return run();
86
+ pragma('PRAGMA query_only = ON');
87
+ try {
88
+ const result = run();
89
+ if (proven.size >= 512) proven.clear();
90
+ proven.add(sql);
91
+ return result;
92
+ } catch (error) {
93
+ if (refused(error)) refuseRawSql();
94
+ throw error;
95
+ } finally {
96
+ pragma('PRAGMA query_only = OFF');
97
+ }
98
+ }
@@ -545,7 +545,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
545
545
  this.reset();
546
546
  }
547
547
 
548
- /** SPEC §7.7: a rejected claim is claimed again; its stored error would
548
+ /** SPEC §7.8: a rejected claim is claimed again; its stored error would
549
549
  * fail every read until the last subscriber leaves. */
550
550
  reclaim(): void {
551
551
  if (this.#delegate !== undefined || this.#claimError === undefined) return;
@@ -1231,7 +1231,7 @@ export class ReactiveClientStore {
1231
1231
  >;
1232
1232
  let claimedAttempt: number | undefined;
1233
1233
  this.#offProgress = this.client.onProgress((progress) => {
1234
- // A new sync attempt is the client's retry schedule (§7.6): window
1234
+ // A new sync attempt is the client's retry schedule (§7.7): window
1235
1235
  // claims that failed are claimed again once per attempt.
1236
1236
  if (progress.state === 'running' && progress.attempt !== claimedAttempt) {
1237
1237
  claimedAttempt = progress.attempt;