@syncular/client 0.58.0 → 0.59.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 (82) hide show
  1. package/README.md +7 -7
  2. package/dist/apply.d.ts +20 -11
  3. package/dist/apply.js +67 -45
  4. package/dist/blob.d.ts +17 -9
  5. package/dist/blob.js +5 -6
  6. package/dist/bun-database.d.ts +1 -0
  7. package/dist/bun-database.js +28 -0
  8. package/dist/client.d.ts +27 -10
  9. package/dist/client.js +357 -190
  10. package/dist/database.d.ts +5 -0
  11. package/dist/encryption.d.ts +2 -2
  12. package/dist/encryption.js +8 -2
  13. package/dist/errors.d.ts +2 -0
  14. package/dist/errors.js +4 -0
  15. package/dist/failed-overlay.d.ts +0 -1
  16. package/dist/failed-overlay.js +3 -6
  17. package/dist/http.d.ts +4 -1
  18. package/dist/http.js +61 -39
  19. package/dist/index.d.ts +1 -1
  20. package/dist/index.js +1 -1
  21. package/dist/invalidation.d.ts +11 -10
  22. package/dist/invalidation.js +15 -26
  23. package/dist/local-purge.js +9 -12
  24. package/dist/local-rebootstrap.js +2 -2
  25. package/dist/multi-tab.d.ts +89 -1
  26. package/dist/multi-tab.js +70 -31
  27. package/dist/native-bridge.d.ts +235 -0
  28. package/dist/native-bridge.js +789 -0
  29. package/dist/node-database.d.ts +1 -0
  30. package/dist/node-database.js +29 -0
  31. package/dist/outbox.d.ts +9 -12
  32. package/dist/outbox.js +19 -36
  33. package/dist/outcomes.js +3 -3
  34. package/dist/previous-version.js +96 -114
  35. package/dist/query-guard.d.ts +25 -24
  36. package/dist/query-guard.js +34 -191
  37. package/dist/reactive-store.js +53 -11
  38. package/dist/realtime-supervisor.d.ts +9 -2
  39. package/dist/realtime-supervisor.js +31 -7
  40. package/dist/remote.js +11 -15
  41. package/dist/schema.js +15 -10
  42. package/dist/sync-scheduler.js +28 -2
  43. package/dist/transport.d.ts +19 -4
  44. package/dist/wasm-database.js +58 -21
  45. package/dist/worker-core.d.ts +5 -0
  46. package/dist/worker-core.js +80 -72
  47. package/dist/worker-host.d.ts +10 -5
  48. package/dist/worker-host.js +64 -7
  49. package/dist/worker-local-authority.js +2 -2
  50. package/dist/worker-protocol.d.ts +6 -2
  51. package/package.json +11 -3
  52. package/src/apply.ts +91 -55
  53. package/src/blob.ts +27 -15
  54. package/src/bun-database.ts +29 -0
  55. package/src/client.ts +477 -261
  56. package/src/database.ts +5 -0
  57. package/src/encryption.ts +10 -5
  58. package/src/errors.ts +8 -0
  59. package/src/failed-overlay.ts +3 -7
  60. package/src/http.ts +90 -79
  61. package/src/index.ts +1 -1
  62. package/src/invalidation.ts +17 -32
  63. package/src/local-purge.ts +11 -13
  64. package/src/local-rebootstrap.ts +2 -3
  65. package/src/multi-tab.ts +88 -30
  66. package/src/native-bridge.ts +1189 -0
  67. package/src/node-database.ts +32 -0
  68. package/src/outbox.ts +19 -41
  69. package/src/outcomes.ts +3 -5
  70. package/src/previous-version.ts +103 -114
  71. package/src/query-guard.ts +43 -180
  72. package/src/reactive-store.ts +50 -10
  73. package/src/realtime-supervisor.ts +37 -12
  74. package/src/remote.ts +12 -16
  75. package/src/schema.ts +19 -12
  76. package/src/sync-scheduler.ts +31 -1
  77. package/src/transport.ts +21 -2
  78. package/src/wasm-database.ts +76 -27
  79. package/src/worker-core.ts +94 -74
  80. package/src/worker-host.ts +63 -16
  81. package/src/worker-local-authority.ts +2 -5
  82. package/src/worker-protocol.ts +6 -2
package/src/database.ts CHANGED
@@ -34,6 +34,11 @@ export interface ClientDatabase {
34
34
  exec(sql: string, params?: readonly SqlValue[]): void;
35
35
  /** Execute a single statement and return its rows as objects. */
36
36
  query(sql: string, params?: readonly SqlValue[]): SqlRow[];
37
+ /**
38
+ * The raw-SQL tier behind `client.query()`: prepare `sql` through
39
+ * `prepareReadOnly`, then return the statement's rows.
40
+ */
41
+ queryReadOnly(sql: string, params?: readonly SqlValue[]): SqlRow[];
37
42
  /**
38
43
  * Run `fn` atomically. Nested calls are savepoints: an inner failure
39
44
  * rolls back only the inner scope.
package/src/encryption.ts CHANGED
@@ -20,7 +20,7 @@ import {
20
20
  type RowColumn,
21
21
  type RowValue,
22
22
  } from '@syncular/core';
23
- import { ClientSyncError } from './errors';
23
+ import { invalidRequest } from './errors';
24
24
  import type { CompiledClientTable } from './schema';
25
25
 
26
26
  /**
@@ -73,8 +73,7 @@ export function encryptionConfigFromKeyring(
73
73
  ): EncryptionConfig {
74
74
  for (const [keyId, key] of Object.entries(keyring.keys)) {
75
75
  if (key.length !== KEY_LENGTH) {
76
- throw new ClientSyncError(
77
- 'sync.invalid_request',
76
+ throw invalidRequest(
78
77
  `encryption key ${JSON.stringify(keyId)} must be ${KEY_LENGTH} bytes (AES-256), got ${key.length}`,
79
78
  );
80
79
  }
@@ -144,7 +143,7 @@ function declaredTypeOf(column: RowColumn): DeclaredType {
144
143
  * unencrypted (§5.11).
145
144
  */
146
145
  export async function encryptRowValues<T extends RowValue | undefined>(
147
- config: EncryptionConfig,
146
+ config: EncryptionConfig | undefined,
148
147
  table: CompiledClientTable,
149
148
  rowId: string,
150
149
  values: readonly T[],
@@ -164,6 +163,9 @@ export async function encryptRowValues<T extends RowValue | undefined>(
164
163
  }
165
164
  }
166
165
  if (!hasPresentEncrypted) return out;
166
+ if (config === undefined) {
167
+ throw new EncryptError('encrypted columns need an encryption config');
168
+ }
167
169
  // Key selection reads the presence set first, then the stored local row.
168
170
  // Absent slots densify to null for selection only; the loop below still
169
171
  // leaves them untouched. Absent ≠ NULL (§6.1): only an ABSENT selector
@@ -213,7 +215,7 @@ export async function encryptRowValues<T extends RowValue | undefined>(
213
215
  * {@link DecryptError} (`client.decrypt_failed`, §5.11).
214
216
  */
215
217
  export async function decryptRowValues(
216
- config: EncryptionConfig,
218
+ config: EncryptionConfig | undefined,
217
219
  table: CompiledClientTable,
218
220
  values: readonly RowValue[],
219
221
  ): Promise<RowValue[]> {
@@ -229,6 +231,9 @@ export async function decryptRowValues(
229
231
  `encrypted column ${column.name} decoded to a non-bytes value`,
230
232
  );
231
233
  }
234
+ if (config === undefined) {
235
+ throw new DecryptError('encrypted columns need an encryption config');
236
+ }
232
237
  out[i] = deserializeGuard(
233
238
  await decryptValue(declaredTypeOf(column), value, config.keyProvider),
234
239
  );
package/src/errors.ts CHANGED
@@ -63,6 +63,14 @@ export function invalidRequest(
63
63
  return new ClientSyncError('sync.invalid_request', message, retryable);
64
64
  }
65
65
 
66
+ /** Shared retryable `sync.transport_failed` construction for client transports. */
67
+ export function transportFailed(
68
+ message: string,
69
+ details?: Readonly<Record<string, unknown>>,
70
+ ): ClientSyncError {
71
+ return new ClientSyncError('sync.transport_failed', message, true, details);
72
+ }
73
+
66
74
  /**
67
75
  * SPEC §7.5: the latest sync attempt failed while a live query still waited
68
76
  * for its required coverage. `code` is the attempt's static progress error
@@ -1,6 +1,6 @@
1
1
  import { hasUniqueIndex } from './schema';
2
2
  import { OUTCOMES_TABLE } from './outcomes';
3
- import { OUTBOX_TABLE } from './outbox';
3
+ import { OUTBOX_IMAGES } from './outbox';
4
4
  export const RETAINED_ROWS = '_syncular_failed_rows';
5
5
  import { ClientSyncError } from './errors';
6
6
  import type { ClientDatabase } from './database';
@@ -171,17 +171,13 @@ export function uniqueConflicts(
171
171
  /** Exact row keys are JSON [table,id]; table scopes include unique-key peers. */
172
172
  export type OverlayScope = readonly string[];
173
173
 
174
- export function overlayScopePredicate(table: string, id: string): string {
175
- return `?1 IS NULL OR json_array(${table},${id}) IN(SELECT value FROM json_each(?1)) OR json_array(${table}) IN(SELECT value FROM json_each(?1))`;
176
- }
177
-
178
174
  function retainedRows(
179
175
  db: ClientDatabase,
180
176
  scope?: OverlayScope,
181
177
  acknowledged?: boolean,
182
178
  ) {
183
179
  return db.query(
184
- `SELECT * FROM ${RETAINED_ROWS} WHERE (${overlayScopePredicate('tbl', 'id')})${acknowledged === undefined ? '' : ` AND commit_seq IS${acknowledged ? ' NOT' : ''} NULL`} ORDER BY commit_seq,at,commit_id,idx`,
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
181
  [scope ? JSON.stringify(scope) : null],
186
182
  );
187
183
  }
@@ -266,7 +262,7 @@ export function failedOverlayCommits(
266
262
  (conflict) =>
267
263
  conflict.serverVersion >= 0 &&
268
264
  !db.query(
269
- `SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? UNION ALL SELECT 1 FROM ${OUTBOX_TABLE},json_each(operations)WHERE json_extract(json_each.value,'$.table')=? AND json_extract(json_each.value,'$.rowId')=? LIMIT 1`,
265
+ `SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? UNION ALL SELECT 1 FROM ${OUTBOX_IMAGES} WHERE tbl=? AND row_id=? LIMIT 1`,
270
266
  [table.name, conflict.rowId, table.name, conflict.rowId],
271
267
  ).length,
272
268
  );
package/src/http.ts CHANGED
@@ -6,7 +6,7 @@
6
6
  */
7
7
  import type { BlobTransport } from './blob';
8
8
  import { SSP2_CONTENT_TYPE } from './content-type';
9
- import { ClientSyncError } from './errors';
9
+ import { ClientSyncError, transportFailed } from './errors';
10
10
  import type {
11
11
  RealtimeConnector,
12
12
  RemoteOperationTransport,
@@ -35,7 +35,7 @@ async function transfer<T>(
35
35
  : error instanceof TypeError
36
36
  ? 'network'
37
37
  : 'unknown';
38
- throw new ClientSyncError('sync.transport_failed', message, true, {
38
+ throw transportFailed(message, {
39
39
  causeKind,
40
40
  ...(httpStatus !== undefined ? { httpStatus } : {}),
41
41
  });
@@ -117,7 +117,7 @@ export function httpSyncTransport(
117
117
  options?: HttpTransportOptions,
118
118
  ): SyncTransport {
119
119
  const doFetch = options?.fetch ?? fetch;
120
- return async (request) => {
120
+ return async (request, signal) => {
121
121
  const response = await transfer('sync request failed', () =>
122
122
  doFetch(syncUrl, {
123
123
  method: 'POST',
@@ -126,6 +126,7 @@ export function httpSyncTransport(
126
126
  ...hostHeaders(options),
127
127
  },
128
128
  body: request.slice().buffer as ArrayBuffer,
129
+ ...(signal !== undefined ? { signal } : {}),
129
130
  }),
130
131
  );
131
132
  if (!response.ok) await throwHttpError(response);
@@ -171,7 +172,7 @@ function socketOperation<T>(message: string, operation: () => T): T {
171
172
  try {
172
173
  return operation();
173
174
  } catch {
174
- throw new ClientSyncError('sync.transport_failed', message, true, {
175
+ throw transportFailed(message, {
175
176
  causeKind: 'unknown',
176
177
  });
177
178
  }
@@ -208,10 +209,8 @@ export function webSocketRemoteOperationConnector(
208
209
  socket.onerror = () => {
209
210
  if (!opened) {
210
211
  reject(
211
- new ClientSyncError(
212
- 'sync.transport_failed',
212
+ transportFailed(
213
213
  'remote operation realtime socket failed to connect',
214
- true,
215
214
  ),
216
215
  );
217
216
  }
@@ -224,10 +223,8 @@ export function webSocketRemoteOperationConnector(
224
223
  socket.onclose = () => {
225
224
  if (!opened) {
226
225
  reject(
227
- new ClientSyncError(
228
- 'sync.transport_failed',
226
+ transportFailed(
229
227
  'remote operation realtime socket closed while connecting',
230
- true,
231
228
  ),
232
229
  );
233
230
  }
@@ -244,11 +241,12 @@ export function webSocketRemoteOperationConnector(
244
241
  * Resolution (which path a descriptor takes, expiry, no fall-through)
245
242
  * lives in the client core, not here.
246
243
  */
247
- async function readSegmentBody(
244
+ async function readBody(
248
245
  response: Response,
249
246
  onProgress?: (bytesReceived: number) => void,
247
+ maxBytes?: number,
250
248
  ): Promise<Uint8Array> {
251
- const chunks: Uint8Array[] = [];
249
+ const chunks: Uint8Array<ArrayBuffer>[] = [];
252
250
  let received = 0;
253
251
  let reported = 0;
254
252
  const reader = response.body?.getReader();
@@ -259,6 +257,11 @@ async function readSegmentBody(
259
257
  if (done) break;
260
258
  chunks.push(value);
261
259
  received += value.byteLength;
260
+ // The caller rejects a body longer than its declared byteLength.
261
+ if (received > (maxBytes ?? received)) {
262
+ await reader.cancel();
263
+ break;
264
+ }
262
265
  if (received - reported >= 64 * 1024) {
263
266
  onProgress?.(received);
264
267
  reported = received;
@@ -269,13 +272,7 @@ async function readSegmentBody(
269
272
  }
270
273
  }
271
274
  if (received !== reported) onProgress?.(received);
272
- const bytes = new Uint8Array(received);
273
- let offset = 0;
274
- for (const chunk of chunks) {
275
- bytes.set(chunk, offset);
276
- offset += chunk.byteLength;
277
- }
278
- return bytes;
275
+ return new Uint8Array(await new Blob(chunks).arrayBuffer());
279
276
  }
280
277
 
281
278
  export function httpSegmentDownloader(
@@ -288,29 +285,30 @@ export function httpSegmentDownloader(
288
285
  init?: RequestInit,
289
286
  onProgress?: (bytesReceived: number) => void,
290
287
  signed = false,
288
+ maxBytes?: number,
291
289
  ) => {
292
290
  const response = await transfer('segment transfer failed', () =>
293
291
  doFetch(url, init),
294
292
  );
295
293
  if (!response.ok) {
296
294
  if (!signed) await throwHttpError(response);
297
- throw new ClientSyncError(
298
- 'sync.transport_failed',
299
- 'signed segment request failed; invalidate the descriptor and re-pull',
300
- true,
301
- { causeKind: 'status', httpStatus: response.status },
302
- );
295
+ throw transportFailed('signed segment request failed', {
296
+ causeKind: 'status',
297
+ httpStatus: response.status,
298
+ });
303
299
  }
304
300
  return transfer(
305
301
  'segment transfer failed',
306
- () => readSegmentBody(response, onProgress),
302
+ () => readBody(response, onProgress, maxBytes),
307
303
  response.status,
308
304
  );
309
305
  };
310
306
  const direct = (request: {
311
307
  readonly segmentId: string;
312
308
  readonly requestedScopesJson: string;
309
+ readonly byteLength?: number;
313
310
  readonly onProgress?: (bytesReceived: number) => void;
311
+ readonly signal?: AbortSignal;
314
312
  }) =>
315
313
  download(
316
314
  `${segmentsBaseUrl}/${encodeURIComponent(request.segmentId)}`,
@@ -319,14 +317,26 @@ export function httpSegmentDownloader(
319
317
  'X-Syncular-Scopes': request.requestedScopesJson,
320
318
  ...hostHeaders(options),
321
319
  },
320
+ ...(request.signal !== undefined ? { signal: request.signal } : {}),
322
321
  },
323
322
  request.onProgress,
323
+ false,
324
+ request.byteLength,
324
325
  );
325
326
  // Deliberately headerless: the URL is the bearer grant (§5.4).
326
327
  const fetchUrl = (
327
328
  url: string,
328
329
  onProgress?: (bytesReceived: number) => void,
329
- ) => download(url, undefined, onProgress, true);
330
+ signal?: AbortSignal,
331
+ byteLength?: number,
332
+ ) =>
333
+ download(
334
+ url,
335
+ signal !== undefined ? { signal } : undefined,
336
+ onProgress,
337
+ true,
338
+ byteLength,
339
+ );
330
340
  return Object.assign(direct, { fetchUrl });
331
341
  }
332
342
 
@@ -344,7 +354,7 @@ export function httpBlobTransport(
344
354
  const blobUrl = (blobId: string) =>
345
355
  `${blobsBaseUrl}/${encodeURIComponent(blobId)}`;
346
356
  return {
347
- upload: async (blobId, bytes, mediaType) => {
357
+ upload: async (blobId, bytes, mediaType, signal) => {
348
358
  const response = await transfer('blob upload failed', () =>
349
359
  doFetch(blobUrl(blobId), {
350
360
  method: 'PUT',
@@ -353,11 +363,12 @@ export function httpBlobTransport(
353
363
  ...hostHeaders(options),
354
364
  },
355
365
  body: bytes.slice().buffer as ArrayBuffer,
366
+ ...(signal !== undefined ? { signal } : {}),
356
367
  }),
357
368
  );
358
369
  if (!response.ok) await throwHttpError(response);
359
370
  },
360
- download: async (blobId) => {
371
+ download: async (blobId, byteLength) => {
361
372
  const response = await transfer('blob download failed', () =>
362
373
  doFetch(blobUrl(blobId), {
363
374
  headers: { ...hostHeaders(options) },
@@ -375,17 +386,16 @@ export function httpBlobTransport(
375
386
  : 'sync.transport_failed',
376
387
  );
377
388
  // §5.9.5 always-issue: a JSON body with a `url` means presigned delivery;
378
- // any other body is inline bytes. The body is read exactly once as bytes,
379
- // so an inline blob stored as `application/json` stays readable.
380
- const contentType = response.headers.get('content-type') ?? '';
381
- const bytes = new Uint8Array(
382
- await transfer(
383
- 'blob download body read failed',
384
- () => response.arrayBuffer(),
385
- response.status,
386
- ),
389
+ // any other body is inline bytes, capped by the declared byteLength.
390
+ const json = (response.headers.get('content-type') ?? '').includes(
391
+ 'application/json',
387
392
  );
388
- if (contentType.includes('application/json')) {
393
+ const bytes = await transfer(
394
+ 'blob body read failed',
395
+ () => readBody(response, undefined, json ? undefined : byteLength),
396
+ response.status,
397
+ );
398
+ if (json) {
389
399
  let envelope: { url?: unknown; urlExpiresAtMs?: unknown } | null = null;
390
400
  try {
391
401
  envelope = JSON.parse(new TextDecoder().decode(bytes));
@@ -405,28 +415,24 @@ export function httpBlobTransport(
405
415
  return { kind: 'bytes', bytes };
406
416
  },
407
417
  // §5.9.5: bare GET of the signed URL — no host auth (the URL is the grant).
408
- fetchUrl: async (url) => {
418
+ fetchUrl: async (url, byteLength) => {
409
419
  const response = await transfer('signed blob download failed', () =>
410
420
  doFetch(url),
411
421
  );
412
422
  if (!response.ok) {
413
- throw new ClientSyncError(
414
- 'sync.transport_failed',
415
- 'signed blob download failed; re-request to recover',
416
- true,
417
- { causeKind: 'status', httpStatus: response.status },
418
- );
423
+ throw transportFailed('signed blob download failed', {
424
+ causeKind: 'status',
425
+ httpStatus: response.status,
426
+ });
419
427
  }
420
- return new Uint8Array(
421
- await transfer(
422
- 'response body read failed',
423
- () => response.arrayBuffer(),
424
- response.status,
425
- ),
428
+ return transfer(
429
+ 'response body read failed',
430
+ () => readBody(response, undefined, byteLength),
431
+ response.status,
426
432
  );
427
433
  },
428
434
  // §5.9.3: presigned-upload grant.
429
- uploadGrant: async (blobId, byteLength, mediaType) => {
435
+ uploadGrant: async (blobId, byteLength, mediaType, signal) => {
430
436
  const response = await transfer('blob upload grant request failed', () =>
431
437
  doFetch(`${blobUrl(blobId)}/upload-grant`, {
432
438
  method: 'POST',
@@ -438,11 +444,12 @@ export function httpBlobTransport(
438
444
  byteLength,
439
445
  ...(mediaType !== undefined ? { mediaType } : {}),
440
446
  }),
447
+ ...(signal !== undefined ? { signal } : {}),
441
448
  }),
442
449
  );
443
450
  if (!response.ok) await throwHttpError(response);
444
451
  const body = (await transfer(
445
- 'blob upload grant body read failed',
452
+ 'blob grant read failed',
446
453
  () => response.json(),
447
454
  response.status,
448
455
  )) as {
@@ -463,37 +470,53 @@ export function httpBlobTransport(
463
470
  return { kind: 'none' };
464
471
  },
465
472
  // §5.9.3: direct-to-storage PUT — no host auth (the URL is the grant).
466
- uploadToUrl: async (url, bytes, mediaType) => {
473
+ uploadToUrl: async (url, bytes, mediaType, signal) => {
474
+ 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
+ );
467
482
  const response = await transfer('signed blob upload failed', () =>
468
483
  doFetch(url, {
469
484
  method: 'PUT',
470
485
  headers: {
471
486
  'Content-Type': mediaType ?? 'application/octet-stream',
487
+ 'x-amz-checksum-sha256': checksum,
472
488
  },
473
- body: bytes.slice().buffer as ArrayBuffer,
489
+ body,
490
+ ...(signal !== undefined ? { signal } : {}),
474
491
  }),
475
492
  );
476
493
  if (!response.ok) {
477
- throw new ClientSyncError(
478
- 'sync.transport_failed',
479
- 'signed blob upload failed; re-request a grant or stream direct',
480
- true,
481
- { causeKind: 'status', httpStatus: response.status },
482
- );
494
+ throw transportFailed('signed blob upload failed', {
495
+ causeKind: 'status',
496
+ httpStatus: response.status,
497
+ });
483
498
  }
484
499
  },
485
500
  };
486
501
  }
487
502
 
488
- /** WebSocket realtime connector (§8.1): text = control, binary = deltas. */
503
+ /**
504
+ * WebSocket realtime connector (§8.1): text = control, binary = deltas. The
505
+ * client's id replaces a `{clientId}` placeholder in the URL.
506
+ */
489
507
  export function webSocketRealtimeConnector(
490
508
  realtimeUrl: string,
491
509
  ): RealtimeConnector {
492
- return (handlers) =>
510
+ return (handlers, clientId) =>
493
511
  new Promise((resolve, reject) => {
494
512
  const socket = socketOperation(
495
513
  'realtime socket failed to connect',
496
- () => new WebSocket(realtimeUrl),
514
+ () =>
515
+ new WebSocket(
516
+ clientId === undefined
517
+ ? realtimeUrl
518
+ : realtimeUrl.replace('{clientId}', encodeURIComponent(clientId)),
519
+ ),
497
520
  );
498
521
  let opened = false;
499
522
  socket.binaryType = 'arraybuffer';
@@ -517,13 +540,7 @@ export function webSocketRealtimeConnector(
517
540
  };
518
541
  socket.onerror = () => {
519
542
  if (!opened) {
520
- reject(
521
- new ClientSyncError(
522
- 'sync.transport_failed',
523
- 'realtime socket failed to connect',
524
- true,
525
- ),
526
- );
543
+ reject(transportFailed('realtime socket failed to connect'));
527
544
  }
528
545
  try {
529
546
  socket.close();
@@ -533,13 +550,7 @@ export function webSocketRealtimeConnector(
533
550
  };
534
551
  socket.onclose = () => {
535
552
  if (!opened) {
536
- reject(
537
- new ClientSyncError(
538
- 'sync.transport_failed',
539
- 'realtime socket closed while connecting',
540
- true,
541
- ),
542
- );
553
+ reject(transportFailed('realtime socket closed while connecting'));
543
554
  }
544
555
  handlers.onClose?.();
545
556
  };
package/src/index.ts CHANGED
@@ -46,7 +46,7 @@ export {
46
46
  type PreviousVersionReason,
47
47
  type PreviousVersionSnapshot,
48
48
  } from './previous-version';
49
- export * from './query-guard';
49
+ export { prepareReadOnly, RawSqlError } from './query-guard';
50
50
  export * from './reactive-store';
51
51
  export * from './remote';
52
52
  export * from './realtime-supervisor';
@@ -158,8 +158,15 @@ export class ChangeAccumulator {
158
158
  this.#outcomes = true;
159
159
  }
160
160
 
161
- /** Add precise keys for a requested/effective scope map. */
161
+ /**
162
+ * Add precise keys for a bulk scoped delete. A map that leaves a declared
163
+ * scope variable unnamed cannot list the deleted rows' keys for that
164
+ * variable, so the change is table-wide.
165
+ */
162
166
  scopeMap(table: CompiledClientTable, scopes: ScopeMap): void {
167
+ for (const variable of table.scopePrefixByVariable.keys()) {
168
+ if (!Object.hasOwn(scopes, variable)) return this.table(table.name);
169
+ }
163
170
  for (const [variable, values] of Object.entries(scopes)) {
164
171
  const prefix = table.scopePrefixByVariable.get(variable);
165
172
  if (prefix === undefined) continue;
@@ -237,23 +244,24 @@ export class ChangeAccumulator {
237
244
  }
238
245
  }
239
246
 
240
- /** Exception-isolated synchronous change listener set. */
241
- export class ChangeEmitter {
242
- readonly #listeners = new Set<ClientChangeListener>();
247
+ /** Exception-isolated synchronous listener set; observer code must never
248
+ * corrupt the committed core path. */
249
+ export class ChangeEmitter<T = ClientChangeBatch> {
250
+ readonly #listeners = new Set<(value: T) => void>();
243
251
 
244
- on(listener: ClientChangeListener): () => void {
252
+ on(listener: (value: T) => void): () => void {
245
253
  this.#listeners.add(listener);
246
254
  return () => {
247
255
  this.#listeners.delete(listener);
248
256
  };
249
257
  }
250
258
 
251
- emit(batch: ClientChangeBatch): void {
259
+ emit(value: T): void {
252
260
  for (const listener of this.#listeners) {
253
261
  try {
254
- listener(batch);
262
+ listener(value);
255
263
  } catch {
256
- // Observer code must never corrupt the committed core path.
264
+ // Isolated: a throwing observer does not stop the others.
257
265
  }
258
266
  }
259
267
  }
@@ -294,30 +302,7 @@ export function invalidationFromChange(
294
302
  return { tables, scopeKeys };
295
303
  }
296
304
 
297
- export class InvalidationEmitter {
298
- readonly #listeners = new Set<InvalidationListener>();
299
-
300
- on(listener: InvalidationListener): () => void {
301
- this.#listeners.add(listener);
302
- return () => {
303
- this.#listeners.delete(listener);
304
- };
305
- }
306
-
307
- emit(event: InvalidationEvent): void {
308
- for (const listener of this.#listeners) {
309
- try {
310
- listener(event);
311
- } catch {
312
- // Compatibility observers are isolated like exact observers.
313
- }
314
- }
315
- }
316
-
317
- get size(): number {
318
- return this.#listeners.size;
319
- }
320
- }
305
+ export class InvalidationEmitter extends ChangeEmitter<InvalidationEvent> {}
321
306
 
322
307
  /** @deprecated Use {@link ChangeAccumulator}. */
323
308
  export { ChangeAccumulator as Invalidation };
@@ -8,7 +8,7 @@
8
8
  * generated FTS projections, doomed optimistic commits, and blob references.
9
9
  */
10
10
 
11
- import { ClientSyncError } from './errors';
11
+ import { invalidRequest } from './errors';
12
12
  import type { CompiledClientSchema, CompiledClientTable } from './schema';
13
13
 
14
14
  const MAX_TARGETS = 64;
@@ -57,10 +57,6 @@ export interface CompiledLocalDataPurge {
57
57
  readonly canonicalPlan: string;
58
58
  }
59
59
 
60
- function invalid(message: string): never {
61
- throw new ClientSyncError('sync.invalid_request', message);
62
- }
63
-
64
60
  /** Validate and canonicalize before any transaction is entered. */
65
61
  export function compileLocalDataPurge(
66
62
  schema: CompiledClientSchema,
@@ -71,25 +67,27 @@ export function compileLocalDataPurge(
71
67
  input.purgeId.length > 128 ||
72
68
  !CODE_LIKE_VALUE.test(input.purgeId)
73
69
  ) {
74
- invalid(
70
+ throw invalidRequest(
75
71
  'local purge purgeId must be a 1–128 character code-like identifier',
76
72
  );
77
73
  }
78
74
  if (input.targets.length === 0 || input.targets.length > MAX_TARGETS) {
79
- invalid(`local purge needs between 1 and ${MAX_TARGETS} targets`);
75
+ throw invalidRequest(
76
+ `local purge needs between 1 and ${MAX_TARGETS} targets`,
77
+ );
80
78
  }
81
79
 
82
80
  const deduplicated = new Map<string, CompiledLocalDataPurgeTarget>();
83
81
  for (const target of input.targets) {
84
82
  const table = schema.tables.get(target.table);
85
83
  if (table === undefined) {
86
- invalid(
84
+ throw invalidRequest(
87
85
  `local purge names unknown table ${JSON.stringify(target.table)}`,
88
86
  );
89
87
  }
90
88
  const entries = Object.entries(target.selectors);
91
89
  if (entries.length === 0 || entries.length > MAX_SELECTORS_PER_TARGET) {
92
- invalid(
90
+ throw invalidRequest(
93
91
  `local purge target ${JSON.stringify(target.table)} needs between 1 and ${MAX_SELECTORS_PER_TARGET} selectors`,
94
92
  );
95
93
  }
@@ -99,12 +97,12 @@ export function compileLocalDataPurge(
99
97
  (candidate) => candidate.name === columnName,
100
98
  );
101
99
  if (column === undefined) {
102
- invalid(
100
+ throw invalidRequest(
103
101
  `local purge target ${JSON.stringify(target.table)} names unknown column ${JSON.stringify(columnName)}`,
104
102
  );
105
103
  }
106
104
  if (column.type !== 'string' || column.encrypted === true) {
107
- invalid(
105
+ throw invalidRequest(
108
106
  `local purge selector ${JSON.stringify(target.table)}.${JSON.stringify(columnName)} must be a plaintext string column`,
109
107
  );
110
108
  }
@@ -112,7 +110,7 @@ export function compileLocalDataPurge(
112
110
  rawValues.length === 0 ||
113
111
  rawValues.length > MAX_VALUES_PER_SELECTOR
114
112
  ) {
115
- invalid(
113
+ throw invalidRequest(
116
114
  `local purge selector ${JSON.stringify(target.table)}.${JSON.stringify(columnName)} needs between 1 and ${MAX_VALUES_PER_SELECTOR} values`,
117
115
  );
118
116
  }
@@ -124,7 +122,7 @@ export function compileLocalDataPurge(
124
122
  value.length > MAX_ROUTING_VALUE_LENGTH ||
125
123
  !CODE_LIKE_VALUE.test(value)
126
124
  ) {
127
- invalid(
125
+ throw invalidRequest(
128
126
  `local purge selector values must be 1–${MAX_ROUTING_VALUE_LENGTH} character code-like identifiers`,
129
127
  );
130
128
  }
@@ -7,7 +7,7 @@
7
7
  * projection state so the registered subscriptions can bootstrap it again.
8
8
  */
9
9
 
10
- import { ClientSyncError } from './errors';
10
+ import { ClientSyncError, invalidRequest } from './errors';
11
11
 
12
12
  const CODE_LIKE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
13
13
  const RESULT_KEYS = [
@@ -85,8 +85,7 @@ export function compileLocalDataRebootstrap(
85
85
  input.rebootstrapId.length > 128 ||
86
86
  !CODE_LIKE_VALUE.test(input.rebootstrapId)
87
87
  ) {
88
- throw new ClientSyncError(
89
- 'sync.invalid_request',
88
+ throw invalidRequest(
90
89
  'local rebootstrap rebootstrapId must be a 1–128 character code-like identifier',
91
90
  );
92
91
  }