@syncular/client 0.59.0 → 0.60.1

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 +19 -5
  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 +23 -14
  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 +22 -9
  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 +27 -19
  66. package/src/worker-protocol.ts +8 -8
@@ -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
@@ -25,7 +25,7 @@ export interface DevtoolsRegistration {
25
25
  readonly clientId: () => string;
26
26
  readonly role: () => string;
27
27
  readonly outbox: () => Promise<number>;
28
- readonly subscriptions: () => Promise<readonly unknown[]>;
28
+ readonly units: () => Promise<readonly unknown[]>;
29
29
  readonly conflicts: () => Promise<number>;
30
30
  readonly rejections: () => Promise<number>;
31
31
  readonly syncNeeded: () => Promise<boolean>;
package/dist/devtools.js CHANGED
@@ -25,9 +25,9 @@ function registryOn(host) {
25
25
  clientId: entry.clientId(),
26
26
  role: entry.role(),
27
27
  outbox: await entry.outbox().catch(() => 'unavailable'),
28
- subscriptions: await entry
29
- .subscriptions()
30
- .then((subs) => subs.length)
28
+ units: await entry
29
+ .units()
30
+ .then((units) => units.length)
31
31
  .catch(() => 'unavailable'),
32
32
  conflicts: await entry.conflicts().catch(() => 'unavailable'),
33
33
  rejections: await entry.rejections().catch(() => 'unavailable'),
@@ -6,8 +6,7 @@
6
6
  * diagnostic prose.
7
7
  */
8
8
  import type { SecurityLifecycle } from './client.js';
9
- export declare const CLIENT_DIAGNOSTICS_VERSION: 1;
10
- export declare const MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS = 256;
9
+ export declare const CLIENT_DIAGNOSTICS_VERSION: 2;
11
10
  export declare const MAX_DIAGNOSTIC_DOMAINS = 256;
12
11
  export declare const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
13
12
  export type ClientDiagnosticsHostKind = 'direct' | 'worker' | 'tauri' | 'react-native';
@@ -33,29 +32,15 @@ export interface ClientDiagnosticsHost {
33
32
  /** Next retry delay in ms while the socket is not connected. */
34
33
  readonly realtimeRetryDelayMs?: number;
35
34
  }
36
- export interface ExpectedDiagnosticSubscription {
37
- /** Application-owned stable identifier. It must never contain PHI. */
38
- readonly id: string;
39
- /** Generated schema table name. */
40
- readonly table: string;
41
- }
42
- export interface ClientDiagnosticsRequest {
43
- /**
44
- * Optional bounded intent list. Missing registrations are returned as
45
- * `unregistered`, allowing a zero-row security scope to fail closed without
46
- * reading private Syncular tables. Values/scopes are intentionally absent.
47
- */
48
- readonly expectedSubscriptions?: readonly ExpectedDiagnosticSubscription[];
49
- }
50
- export type DiagnosticSubscriptionState = 'unregistered' | 'bootstrapping' | 'complete' | 'reset' | 'revoked' | 'failed';
51
- export interface DiagnosticSubscription {
52
- readonly id: string;
53
- readonly table: string;
54
- readonly state: DiagnosticSubscriptionState;
55
- readonly complete: boolean;
56
- /** Last fully applied local commit sequence; absent when unregistered. */
57
- readonly cursor?: number;
58
- readonly reasonCode?: string;
35
+ /** §7.6: registered units per state; a unit id never enters diagnostics. */
36
+ export interface DiagnosticUnits {
37
+ readonly bootstrapping: number;
38
+ readonly complete: number;
39
+ readonly reset: number;
40
+ readonly revoked: number;
41
+ readonly failed: number;
42
+ /** Distinct stable reason codes of registered units, ascending. */
43
+ readonly reasonCodes: readonly string[];
59
44
  }
60
45
  export interface DiagnosticRoundCounters {
61
46
  readonly pushed: number;
@@ -93,7 +78,8 @@ export interface DiagnosticLastChange {
93
78
  readonly recordedAtMs: number;
94
79
  /** Generated table names only; no scope keys or row ids. */
95
80
  readonly tables: readonly string[];
96
- /** Generated table names for changed window registrations/completeness. */
81
+ /** Selected variables of window bases whose registration or completeness
82
+ * changed. */
97
83
  readonly windows: readonly string[];
98
84
  readonly domainsTruncated: boolean;
99
85
  readonly statusChanged: boolean;
@@ -145,8 +131,11 @@ export interface ClientDiagnosticsSnapshot {
145
131
  readonly expiresAtMs?: number;
146
132
  readonly errorCode?: string;
147
133
  };
148
- readonly subscriptions: readonly DiagnosticSubscription[];
149
- readonly subscriptionsTruncated: boolean;
134
+ readonly units: DiagnosticUnits;
135
+ /** Units the next registration list carries; the server limit counts these (SPEC §4.1). */
136
+ readonly activeUnits: number;
137
+ /** §4.5 replica cursor; `-1` while no unit is live. */
138
+ readonly replicaCursor: number;
150
139
  readonly lastRound?: DiagnosticLastRound;
151
140
  readonly lastChange?: DiagnosticLastChange;
152
141
  readonly storage: ClientDiagnosticsStorage;
@@ -1,5 +1,4 @@
1
- export const CLIENT_DIAGNOSTICS_VERSION = 1;
2
- export const MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS = 256;
1
+ export const CLIENT_DIAGNOSTICS_VERSION = 2;
3
2
  export const MAX_DIAGNOSTIC_DOMAINS = 256;
4
3
  export const MAX_DIAGNOSTIC_QUERY_FAILURES = 256;
5
4
  export class ClientDiagnosticsEmitter {
package/dist/errors.d.ts CHANGED
@@ -6,7 +6,7 @@ export declare const STORAGE_BUSY_CODE = "client.storage_busy";
6
6
  * engine closed the store and refuses every further statement.
7
7
  */
8
8
  export declare const STORAGE_FENCED_CODE = "client.storage_fenced";
9
- /** The browser cannot provide the persistent storage APIs Syncular requires. */
9
+ /** The runtime cannot provide the storage APIs Syncular requires. */
10
10
  export declare const STORAGE_UNAVAILABLE_CODE = "client.storage_unavailable";
11
11
  /** A local read hit SQLITE_CORRUPT or SQLITE_NOTADB (SPEC §7.5). */
12
12
  export declare const STORAGE_CORRUPT_CODE = "client.storage_corrupt";
package/dist/errors.js CHANGED
@@ -5,7 +5,7 @@ export const STORAGE_BUSY_CODE = 'client.storage_busy';
5
5
  * engine closed the store and refuses every further statement.
6
6
  */
7
7
  export const STORAGE_FENCED_CODE = 'client.storage_fenced';
8
- /** The browser cannot provide the persistent storage APIs Syncular requires. */
8
+ /** The runtime cannot provide the storage APIs Syncular requires. */
9
9
  export const STORAGE_UNAVAILABLE_CODE = 'client.storage_unavailable';
10
10
  /** A local read hit SQLITE_CORRUPT or SQLITE_NOTADB (SPEC §7.5). */
11
11
  export const STORAGE_CORRUPT_CODE = 'client.storage_corrupt';
@@ -12,6 +12,7 @@ export function ensureFailedOverlaySchema(db) {
12
12
  for (const column of ['unique_conflicts TEXT', 'commit_seq INTEGER'])
13
13
  if (!columns.some((row) => row.name === column.split(' ')[0]))
14
14
  db.exec(`ALTER TABLE ${RETAINED_ROWS} ADD COLUMN ${column}`);
15
+ db.exec(`CREATE INDEX IF NOT EXISTS ${RETAINED_ROWS}_row ON ${RETAINED_ROWS}(tbl,id)`);
15
16
  }
16
17
  export function retainedBaseWrite(db, table, rowId, values, version) {
17
18
  db.exec(`UPDATE ${RETAINED_ROWS} SET base=?,version=? WHERE tbl=? AND id=?`, [
@@ -91,7 +92,9 @@ export function uniqueConflicts(db, table, values) {
91
92
  })));
92
93
  }
93
94
  function retainedRows(db, scope, acknowledged) {
94
- return db.query(`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`, [scope ? JSON.stringify(scope) : null]);
95
+ // A scope joins through the (tbl, id) index; a scan per applied commit
96
+ // would make a drained batch quadratic.
97
+ return db.query(`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`, [scope ? JSON.stringify(scope) : null]);
95
98
  }
96
99
  export function restoreFailedBases(db, schema, scope) {
97
100
  const seen = new Set();
package/dist/http.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { SSP2_CONTENT_TYPE } from './content-type.js';
2
2
  import { ClientSyncError, transportFailed } from './errors.js';
3
+ import { hexToBytes } from './schema.js';
3
4
  async function transfer(message, operation, httpStatus) {
4
5
  try {
5
6
  return await operation();
@@ -181,7 +182,15 @@ async function readBody(response, onProgress, maxBytes) {
181
182
  }
182
183
  if (received !== reported)
183
184
  onProgress?.(received);
184
- return new Uint8Array(await new Blob(chunks).arrayBuffer());
185
+ // One allocation of the body's size. A Blob of the chunks and its
186
+ // arrayBuffer() kept one more full copy resident until garbage collection.
187
+ const bytes = new Uint8Array(received);
188
+ let offset = 0;
189
+ for (const chunk of chunks) {
190
+ bytes.set(chunk, offset);
191
+ offset += chunk.byteLength;
192
+ }
193
+ return bytes;
185
194
  }
186
195
  export function httpSegmentDownloader(segmentsBaseUrl, options) {
187
196
  const doFetch = options?.fetch ?? fetch;
@@ -309,11 +318,16 @@ export function httpBlobTransport(blobsBaseUrl, options) {
309
318
  return { kind: 'none' };
310
319
  },
311
320
  // §5.9.3: direct-to-storage PUT — no host auth (the URL is the grant).
312
- uploadToUrl: async (url, bytes, mediaType, signal) => {
321
+ uploadToUrl: async (blobId, url, bytes, mediaType, signal) => {
322
+ // The grant signs content-length (set by fetch from the body) and the
323
+ // checksum, the blob id's digest, so the object store rejects any other
324
+ // bytes without the client hashing the body again (§5.9.3).
325
+ const hex = /^sha256:([0-9a-f]{64})$/.exec(blobId)?.[1];
326
+ if (hex === undefined) {
327
+ throw new ClientSyncError('sync.invalid_request', 'the blob id is not a sha256 blob id (§5.9.1)');
328
+ }
329
+ const checksum = btoa(String.fromCharCode(...hexToBytes(hex)));
313
330
  const body = bytes.slice().buffer;
314
- // The grant signs content-length (set by fetch from the body) and this
315
- // checksum, so the object store rejects any other bytes (§5.9.3).
316
- const checksum = btoa(String.fromCharCode(...new Uint8Array(await crypto.subtle.digest('SHA-256', body))));
317
331
  const response = await transfer('signed blob upload failed', () => doFetch(url, {
318
332
  method: 'PUT',
319
333
  headers: {
@@ -16,7 +16,7 @@ export interface TableChange {
16
16
  }
17
17
  export interface WindowChange {
18
18
  readonly baseKey: string;
19
- readonly table: string;
19
+ /** Changed values of the base. */
20
20
  readonly units: ReadonlySet<string>;
21
21
  }
22
22
  export interface SyncStatusSnapshot {
@@ -46,7 +46,6 @@ export interface ClientChangeBatch {
46
46
  readonly outcomesChanged: boolean;
47
47
  /** Server COMMIT frames applied by this transaction, when present. */
48
48
  readonly appliedCommits?: readonly {
49
- readonly subscriptionId: string;
50
49
  readonly table: string;
51
50
  readonly commitSeq: number;
52
51
  readonly source: 'delta' | 'pull';
@@ -81,8 +80,8 @@ export declare class ChangeAccumulator {
81
80
  table(name: string): void;
82
81
  /** Associate a precise `prefix:value` key with its table. */
83
82
  scope(table: string, key: string): void;
84
- /** Record registration/completeness change for one window unit. */
85
- window(baseKey: string, table: string, unit: string): void;
83
+ /** Record registration/completeness change for one window value. */
84
+ window(baseKey: string, value: string): void;
86
85
  status(): void;
87
86
  conflicts(): void;
88
87
  rejections(): void;
@@ -34,17 +34,13 @@ export class ChangeAccumulator {
34
34
  }
35
35
  current.scopeKeys?.add(key);
36
36
  }
37
- /** Record registration/completeness change for one window unit. */
38
- window(baseKey, table, unit) {
37
+ /** Record registration/completeness change for one window value. */
38
+ window(baseKey, value) {
39
39
  const current = this.#windows.get(baseKey);
40
- if (current === undefined) {
41
- this.#windows.set(baseKey, { table, units: new Set([unit]) });
42
- return;
43
- }
44
- if (current.table !== table) {
45
- throw new Error(`window base ${JSON.stringify(baseKey)} changed tables`);
46
- }
47
- current.units.add(unit);
40
+ if (current === undefined)
41
+ this.#windows.set(baseKey, new Set([value]));
42
+ else
43
+ current.add(value);
48
44
  }
49
45
  status() {
50
46
  this.#status = true;
@@ -110,13 +106,8 @@ export class ChangeAccumulator {
110
106
  : { table, scopeKeys: change.scopeKeys });
111
107
  }
112
108
  const windows = [];
113
- for (const [baseKey, change] of this.#windows) {
114
- windows.push({
115
- baseKey,
116
- table: change.table,
117
- units: change.units,
118
- });
119
- }
109
+ for (const [baseKey, units] of this.#windows)
110
+ windows.push({ baseKey, units });
120
111
  return {
121
112
  revision,
122
113
  tables,
@@ -156,7 +147,7 @@ export class ChangeEmitter {
156
147
  }
157
148
  }
158
149
  export function invalidationFromChange(batch) {
159
- if (batch.tables.length === 0 && batch.windows.length === 0)
150
+ if (batch.tables.length === 0)
160
151
  return undefined;
161
152
  const tables = new Set();
162
153
  const scopeKeys = new Set();
@@ -165,10 +156,6 @@ export function invalidationFromChange(batch) {
165
156
  for (const key of change.scopeKeys ?? [])
166
157
  scopeKeys.add(key);
167
158
  }
168
- // Window-only changes project the table for old completeness consumers.
169
- // The exact API still keeps this distinct, so new table-only reads do not run.
170
- for (const change of batch.windows)
171
- tables.add(change.table);
172
159
  return { tables, scopeKeys };
173
160
  }
174
161
  export class InvalidationEmitter extends ChangeEmitter {
@@ -13,8 +13,8 @@
13
13
  */
14
14
  import { type ClientSnapshotMethods, type CurrentBaseProof, type MutationInput, type PresencePeer, type PromiseMethods, type QueryReadSpec, type QuerySnapshot, type SecurityLifecycle, type SnapshotRead, type SnapshotReadRequest, type SyncClientConfig, type WindowState } from './client.js';
15
15
  import type { SqlRow, SqlValue } from './database.js';
16
- import type { PresenceErrorCode } from '@syncular/core';
17
- import { type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot } from './diagnostics.js';
16
+ import type { PresenceErrorCode, UnitScopes } from '@syncular/core';
17
+ import { type ClientDiagnosticsListener, type ClientDiagnosticsSnapshot } from './diagnostics.js';
18
18
  import type { EncryptionKeyringConfig } from './encryption.js';
19
19
  import type { ClientChangeListener, InvalidationListener, SyncStatusSnapshot } from './invalidation.js';
20
20
  import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge.js';
@@ -146,7 +146,7 @@ export declare abstract class NativeBridgeClient implements PromiseMethods<Clien
146
146
  snapshotRead(request: SnapshotReadRequest): Promise<SnapshotRead>;
147
147
  localRevision(): Promise<bigint>;
148
148
  statusSnapshot(): Promise<SyncStatusSnapshot>;
149
- diagnosticsSnapshot(request?: ClientDiagnosticsRequest): Promise<ClientDiagnosticsSnapshot>;
149
+ diagnosticsSnapshot(): Promise<ClientDiagnosticsSnapshot>;
150
150
  mutate(mutations: readonly MutationInput[]): Promise<string>;
151
151
  patch(table: string, rowId: string, partial: Readonly<Record<string, unknown>>, options?: {
152
152
  readonly baseVersion?: number;
@@ -197,19 +197,10 @@ export declare abstract class NativeBridgeClient implements PromiseMethods<Clien
197
197
  readonly bytes: Uint8Array;
198
198
  readonly mediaType?: string;
199
199
  }>;
200
- subscribe(input: {
201
- readonly id: string;
202
- readonly table: string;
203
- readonly scopes?: Record<string, readonly string[]>;
204
- readonly params?: string;
205
- }): Promise<void>;
206
- /** Register several subscriptions in one local transaction. */
207
- subscribeMany(inputs: readonly {
208
- readonly id: string;
209
- readonly table: string;
210
- readonly scopes?: Record<string, readonly string[]>;
211
- readonly params?: string;
212
- }[]): Promise<void>;
200
+ /** §4.1: register one unit; returns its id. */
201
+ subscribe(scopes: UnitScopes): Promise<string>;
202
+ /** Register several units in one local transaction; returns their ids. */
203
+ subscribeMany(units: readonly UnitScopes[]): Promise<string[]>;
213
204
  unsubscribe(id: string): Promise<void>;
214
205
  setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
215
206
  windowState(base: WindowBase): Promise<WindowState>;
@@ -12,7 +12,7 @@
12
12
  * client and worker entries never import this module.
13
13
  */
14
14
  import { SECURITY_PREFLIGHT_REQUIRED_CODE, } from './client.js';
15
- import { withClientDiagnosticsHost, } from './diagnostics.js';
15
+ import { CLIENT_DIAGNOSTICS_VERSION, withClientDiagnosticsHost, } from './diagnostics.js';
16
16
  import { decodeLocalDataRebootstrapResult, } from './local-rebootstrap.js';
17
17
  import { decodePreviousVersionAuditResult, decodePreviousVersionDiscardResult, decodePreviousVersionSnapshot, } from './previous-version.js';
18
18
  import { ProgressEmitter, } from './progress.js';
@@ -99,17 +99,9 @@ function decodeChangeBatch(value) {
99
99
  if (entry === null || typeof entry !== 'object')
100
100
  return [];
101
101
  const item = entry;
102
- if (typeof item.baseKey !== 'string' ||
103
- typeof item.table !== 'string') {
102
+ if (typeof item.baseKey !== 'string')
104
103
  return [];
105
- }
106
- return [
107
- {
108
- baseKey: item.baseKey,
109
- table: item.table,
110
- units: toStringSet(item.units),
111
- },
112
- ];
104
+ return [{ baseKey: item.baseKey, units: toStringSet(item.units) }];
113
105
  })
114
106
  : [];
115
107
  const appliedCommits = [];
@@ -120,15 +112,13 @@ function decodeChangeBatch(value) {
120
112
  if (entry === null || typeof entry !== 'object')
121
113
  return undefined;
122
114
  const item = entry;
123
- if (typeof item.subscriptionId !== 'string' ||
124
- typeof item.table !== 'string' ||
115
+ if (typeof item.table !== 'string' ||
125
116
  typeof item.commitSeq !== 'number' ||
126
117
  !Number.isSafeInteger(item.commitSeq) ||
127
118
  item.commitSeq < 1 ||
128
119
  (item.source !== 'delta' && item.source !== 'pull'))
129
120
  return undefined;
130
121
  appliedCommits.push({
131
- subscriptionId: item.subscriptionId,
132
122
  table: item.table,
133
123
  commitSeq: item.commitSeq,
134
124
  source: item.source,
@@ -362,7 +352,7 @@ export class NativeBridgeClient {
362
352
  if (batch === undefined)
363
353
  break;
364
354
  fanOut(this.#changeListeners, batch);
365
- if (batch.tables.length === 0 && batch.windows.length === 0)
355
+ if (batch.tables.length === 0)
366
356
  break;
367
357
  const tables = new Set();
368
358
  const scopeKeys = new Set();
@@ -371,8 +361,6 @@ export class NativeBridgeClient {
371
361
  for (const key of table.scopeKeys ?? [])
372
362
  scopeKeys.add(key);
373
363
  }
374
- for (const window of batch.windows)
375
- tables.add(window.table);
376
364
  fanOut(this.#invalidationListeners, { tables, scopeKeys });
377
365
  break;
378
366
  }
@@ -383,7 +371,7 @@ export class NativeBridgeClient {
383
371
  const snapshot = event.snapshot;
384
372
  if (snapshot === null ||
385
373
  typeof snapshot !== 'object' ||
386
- snapshot.version !== 1 ||
374
+ snapshot.version !== CLIENT_DIAGNOSTICS_VERSION ||
387
375
  snapshot.host === undefined)
388
376
  break;
389
377
  fanOut(this.#diagnosticsListeners, withClientDiagnosticsHost(snapshot, {
@@ -500,7 +488,7 @@ export class NativeBridgeClient {
500
488
  params: encodeValue(statement.params ?? []),
501
489
  })),
502
490
  coverage: request.coverage ?? [],
503
- subscriptions: request.subscriptions ?? [],
491
+ units: request.units ?? [],
504
492
  commitIds: request.commitIds ?? [],
505
493
  ...(request.owner !== undefined ? { owner: request.owner } : {}),
506
494
  }));
@@ -508,7 +496,7 @@ export class NativeBridgeClient {
508
496
  revision: BigInt(result.revision),
509
497
  queries: result.queries.map((rows) => rows.map((row) => this.decodeRow(row))),
510
498
  coverage: result.coverage,
511
- subscriptions: result.subscriptions,
499
+ units: result.units,
512
500
  deliveries: result.deliveries.map((delivery) => delivery.status === 'known'
513
501
  ? { ...delivery, outcome: this.#commitOutcome(delivery.outcome) }
514
502
  : delivery),
@@ -521,10 +509,8 @@ export class NativeBridgeClient {
521
509
  async statusSnapshot() {
522
510
  return (await this.command('statusSnapshot', {}));
523
511
  }
524
- async diagnosticsSnapshot(request = {}) {
525
- const snapshot = (await this.command('diagnosticsSnapshot', {
526
- expectedSubscriptions: request.expectedSubscriptions ?? [],
527
- }));
512
+ async diagnosticsSnapshot() {
513
+ const snapshot = (await this.command('diagnosticsSnapshot', {}));
528
514
  return withClientDiagnosticsHost(snapshot, {
529
515
  ...snapshot.host,
530
516
  kind: this.#kind,
@@ -670,24 +656,13 @@ export class NativeBridgeClient {
670
656
  : {}),
671
657
  };
672
658
  }
673
- async subscribe(input) {
674
- await this.command('subscribe', {
675
- id: input.id,
676
- table: input.table,
677
- scopes: input.scopes ?? {},
678
- ...(input.params !== undefined ? { params: input.params } : {}),
679
- });
659
+ /** §4.1: register one unit; returns its id. */
660
+ async subscribe(scopes) {
661
+ return (await this.command('subscribe', { scopes })).id;
680
662
  }
681
- /** Register several subscriptions in one local transaction. */
682
- async subscribeMany(inputs) {
683
- await this.command('subscribeMany', {
684
- subscriptions: inputs.map((input) => ({
685
- id: input.id,
686
- table: input.table,
687
- scopes: input.scopes ?? {},
688
- ...(input.params !== undefined ? { params: input.params } : {}),
689
- })),
690
- });
663
+ /** Register several units in one local transaction; returns their ids. */
664
+ async subscribeMany(units) {
665
+ return (await this.command('subscribeMany', { units })).ids;
691
666
  }
692
667
  async unsubscribe(id) {
693
668
  await this.command('unsubscribe', { id });
@@ -2,12 +2,13 @@
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 } from 'node:sqlite';
5
+ import { DatabaseSync, 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';
9
9
  import { assertImageAlias, runTransaction, } from './database.js';
10
- import { prepareReadOnly, SQL_BLANK } from './query-guard.js';
10
+ import { ClientSyncError, STORAGE_UNAVAILABLE_CODE } from './errors.js';
11
+ import { prepareReadOnly, runReadOnly } from './query-guard.js';
11
12
  function coerceParams(params) {
12
13
  return params.map((value) => {
13
14
  if (typeof value === 'boolean')
@@ -31,8 +32,13 @@ function normalizeRow(row) {
31
32
  export class NodeClientDatabase {
32
33
  db;
33
34
  #path;
35
+ #proven = new Set();
34
36
  #tx = { depth: 0 };
35
37
  constructor(path = ':memory:') {
38
+ // The raw-SQL tier reads result columns through `columns()` (Node 22.16).
39
+ if (typeof StatementSync.prototype.columns !== 'function') {
40
+ throw new ClientSyncError(STORAGE_UNAVAILABLE_CODE, 'The node:sqlite adapter needs Node 22.16 or newer.', false, { runtime: 'node', version: process.versions.node, minimum: '22.16.0' });
41
+ }
36
42
  this.#path = path;
37
43
  this.db = new DatabaseSync(path);
38
44
  try {
@@ -54,30 +60,15 @@ export class NodeClientDatabase {
54
60
  queryReadOnly(sql, params = []) {
55
61
  const statement = prepareReadOnly(sql, () => {
56
62
  const prepared = this.db.prepare(sql);
57
- // node:sqlite exposes no `sqlite3_stmt_readonly` (and no column count
58
- // before Node 22.16), so the verb decides: SELECT, VALUES, EXPLAIN, or
59
- // a WITH clause whose first keyword outside parentheses is SELECT or
60
- // VALUES.
61
- const body = prepared.sourceSQL.replace(SQL_BLANK, '');
62
- const verb = /^[a-z]+/i.exec(body)?.[0].toLowerCase();
63
- let reads = verb === 'select' || verb === 'values' || verb === 'explain';
64
- if (verb === 'with') {
65
- let depth = 0;
66
- for (const [token] of body.matchAll(/'[^']*'|"[^"]*"|`[^`]*`|\[[^\]]*\]|--[^\n]*|\/\*(?:[^*]|\*(?!\/))*(?:\*\/|$)|[\w$\u0080-\uffff]+|[\s\S]/g)) {
67
- if (token === '(')
68
- depth += 1;
69
- else if (token === ')')
70
- depth -= 1;
71
- else if (depth === 0 &&
72
- /^(?:select|values|insert|update|delete|replace)$/i.test(token)) {
73
- reads = /^(?:select|values)$/i.test(token);
74
- break;
75
- }
76
- }
77
- }
78
- return [prepared, prepared.sourceSQL, reads];
63
+ return [
64
+ prepared,
65
+ prepared.sourceSQL,
66
+ prepared.columns().length > 0,
67
+ ];
79
68
  });
80
- return statement.all(...coerceParams(params)).map(normalizeRow);
69
+ return runReadOnly(this.#proven, sql, (pragma) => this.db.exec(pragma),
70
+ // SQLITE_READONLY
71
+ (error) => error.errcode === 8, () => statement.all(...coerceParams(params)).map(normalizeRow));
81
72
  }
82
73
  /** RFC 0005: a sibling file beside the replica, e.g. `<path>.prev-context`. */
83
74
  openSibling(name) {
package/dist/outbox.js CHANGED
@@ -182,6 +182,7 @@ export async function encodeOutboxCommit(schema, commit, encryption, storedKeyId
182
182
  return {
183
183
  type: 'PUSH_COMMIT',
184
184
  clientCommitId: commit.clientCommitId,
185
+ clientSeq: commit.seq,
185
186
  operations,
186
187
  };
187
188
  }
@@ -1,10 +1,10 @@
1
1
  import type { TransportCauseKind } from './diagnostics.js';
2
- /** Ephemeral sync work, independent of committed change notifications (SPEC §7.6). */
2
+ /** Ephemeral sync work, independent of committed change notifications (SPEC §7.7). */
3
3
  export interface SyncProgress {
4
4
  readonly attempt: number;
5
5
  readonly state: 'running' | 'complete' | 'failed';
6
6
  readonly phase: 'request' | 'download' | 'import';
7
- readonly subscriptionId?: string;
7
+ readonly unitId?: string;
8
8
  readonly table?: string;
9
9
  readonly segmentId?: string | undefined;
10
10
  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([...])`.
@@ -23,13 +24,21 @@
23
24
  export declare class RawSqlError extends Error {
24
25
  readonly name = "RawSqlError";
25
26
  }
26
- /** Leading whitespace, comments and empty statements. */
27
- export declare const SQL_BLANK: RegExp;
28
- /** Refuse a statement the raw-SQL tier does not run. */
29
- export declare function refuseRawSql(): never;
30
27
  /**
31
28
  * Prepare `sql` for the raw-SQL tier or throw `RawSqlError`. `prepare`
32
29
  * compiles the first statement only and returns it, the text SQLite compiled
33
30
  * for it, and whether SQLite reports it read-only with result columns.
34
31
  */
35
32
  export declare function prepareReadOnly<S>(sql: string, prepare: () => readonly [statement: S, first: string, reads: boolean]): S;
33
+ /**
34
+ * Run a statement `prepareReadOnly` accepted on an adapter without
35
+ * `sqlite3_stmt_readonly` (bun:sqlite before 1.4.4, node:sqlite). SQLite
36
+ * refuses a write when it runs: under `query_only` a write transaction fails
37
+ * before it changes anything, and `refused` recognizes that error. The
38
+ * verdict depends on the text alone, since a write fails at its write
39
+ * transaction whether or not it touches a row, so a text that completed
40
+ * under `query_only` joins `proven` and later runs skip the pragma: a flag
41
+ * pragma expires every prepared statement of the connection. `proven` is per
42
+ * connection and cleared at 512 texts, so dynamic SQL cannot grow it.
43
+ */
44
+ export declare function runReadOnly<R>(proven: Set<string>, sql: string, pragma: (sql: string) => void, refused: (error: unknown) => boolean, run: () => R): R;