@syncular/client 0.58.0 → 0.60.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/README.md +34 -34
  2. package/dist/apply.d.ts +24 -14
  3. package/dist/apply.js +119 -70
  4. package/dist/authority.js +21 -16
  5. package/dist/blob.d.ts +17 -9
  6. package/dist/blob.js +5 -6
  7. package/dist/bun-database.d.ts +1 -0
  8. package/dist/bun-database.js +15 -0
  9. package/dist/client.d.ts +83 -75
  10. package/dist/client.js +982 -910
  11. package/dist/database.d.ts +5 -0
  12. package/dist/devtools.d.ts +2 -2
  13. package/dist/devtools.js +3 -3
  14. package/dist/diagnostics.d.ts +17 -28
  15. package/dist/diagnostics.js +1 -2
  16. package/dist/encryption.d.ts +2 -2
  17. package/dist/encryption.js +8 -2
  18. package/dist/errors.d.ts +3 -1
  19. package/dist/errors.js +5 -1
  20. package/dist/failed-overlay.d.ts +0 -1
  21. package/dist/failed-overlay.js +6 -6
  22. package/dist/http.d.ts +4 -1
  23. package/dist/http.js +67 -39
  24. package/dist/index.d.ts +1 -1
  25. package/dist/index.js +1 -1
  26. package/dist/invalidation.d.ts +14 -14
  27. package/dist/invalidation.js +24 -48
  28. package/dist/local-purge.js +9 -12
  29. package/dist/local-rebootstrap.js +2 -2
  30. package/dist/multi-tab.d.ts +89 -1
  31. package/dist/multi-tab.js +70 -31
  32. package/dist/native-bridge.d.ts +226 -0
  33. package/dist/native-bridge.js +764 -0
  34. package/dist/node-database.d.ts +1 -0
  35. package/dist/node-database.js +21 -1
  36. package/dist/outbox.d.ts +9 -12
  37. package/dist/outbox.js +20 -36
  38. package/dist/outcomes.js +3 -3
  39. package/dist/previous-version.js +96 -114
  40. package/dist/progress.d.ts +2 -2
  41. package/dist/query-guard.d.ts +34 -24
  42. package/dist/query-guard.js +61 -186
  43. package/dist/reactive-store.js +55 -13
  44. package/dist/realtime-supervisor.d.ts +9 -2
  45. package/dist/realtime-supervisor.js +31 -7
  46. package/dist/remote.js +19 -23
  47. package/dist/schema.d.ts +3 -2
  48. package/dist/schema.js +43 -22
  49. package/dist/state.d.ts +69 -36
  50. package/dist/state.js +178 -89
  51. package/dist/sync-scheduler.js +28 -2
  52. package/dist/transport.d.ts +19 -4
  53. package/dist/wasm-database.js +58 -21
  54. package/dist/window.d.ts +30 -52
  55. package/dist/window.js +33 -77
  56. package/dist/worker-core.d.ts +5 -0
  57. package/dist/worker-core.js +83 -75
  58. package/dist/worker-host.d.ts +19 -13
  59. package/dist/worker-host.js +75 -18
  60. package/dist/worker-local-authority.js +2 -2
  61. package/dist/worker-protocol.d.ts +15 -10
  62. package/package.json +11 -3
  63. package/src/apply.ts +176 -86
  64. package/src/authority.ts +31 -17
  65. package/src/blob.ts +28 -15
  66. package/src/bun-database.ts +24 -0
  67. package/src/client.ts +1282 -1217
  68. package/src/database.ts +5 -0
  69. package/src/devtools.ts +5 -5
  70. package/src/diagnostics.ts +17 -37
  71. package/src/encryption.ts +10 -5
  72. package/src/errors.ts +9 -1
  73. package/src/failed-overlay.ts +8 -7
  74. package/src/http.ts +95 -79
  75. package/src/index.ts +1 -1
  76. package/src/invalidation.ts +26 -61
  77. package/src/local-purge.ts +11 -13
  78. package/src/local-rebootstrap.ts +2 -3
  79. package/src/multi-tab.ts +88 -30
  80. package/src/native-bridge.ts +1153 -0
  81. package/src/node-database.ts +32 -1
  82. package/src/outbox.ts +20 -41
  83. package/src/outcomes.ts +3 -5
  84. package/src/previous-version.ts +103 -114
  85. package/src/progress.ts +2 -2
  86. package/src/query-guard.ts +77 -177
  87. package/src/reactive-store.ts +52 -12
  88. package/src/realtime-supervisor.ts +37 -12
  89. package/src/remote.ts +23 -31
  90. package/src/schema.ts +67 -25
  91. package/src/state.ts +246 -125
  92. package/src/sync-scheduler.ts +31 -1
  93. package/src/transport.ts +21 -2
  94. package/src/wasm-database.ts +76 -27
  95. package/src/window.ts +55 -134
  96. package/src/worker-core.ts +97 -77
  97. package/src/worker-host.ts +76 -32
  98. package/src/worker-local-authority.ts +2 -5
  99. package/src/worker-protocol.ts +14 -10
@@ -29,6 +29,11 @@ export interface ClientDatabase {
29
29
  exec(sql: string, params?: readonly SqlValue[]): void;
30
30
  /** Execute a single statement and return its rows as objects. */
31
31
  query(sql: string, params?: readonly SqlValue[]): SqlRow[];
32
+ /**
33
+ * The raw-SQL tier behind `client.query()`: prepare `sql` through
34
+ * `prepareReadOnly`, then return the statement's rows.
35
+ */
36
+ queryReadOnly(sql: string, params?: readonly SqlValue[]): SqlRow[];
32
37
  /**
33
38
  * Run `fn` atomically. Nested calls are savepoints: an inner failure
34
39
  * rolls back only the inner scope.
@@ -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 {
@@ -57,7 +57,7 @@ export declare function encryptionConfigFromKeyring(keyring: EncryptionKeyringCo
57
57
  * value becomes the §5.11 ciphertext-envelope `bytes`. NULLs pass through
58
58
  * unencrypted (§5.11).
59
59
  */
60
- export declare function encryptRowValues<T extends RowValue | undefined>(config: EncryptionConfig, table: CompiledClientTable, rowId: string, values: readonly T[], storedKeyId?: string): Promise<T[]>;
60
+ export declare function encryptRowValues<T extends RowValue | undefined>(config: EncryptionConfig | undefined, table: CompiledClientTable, rowId: string, values: readonly T[], storedKeyId?: string): Promise<T[]>;
61
61
  /**
62
62
  * Decrypt the encrypted columns of a decoded positional row value array
63
63
  * (returns a new array). Called at the apply seam (§4.5 COMMIT, §5.6 rows
@@ -66,4 +66,4 @@ export declare function encryptRowValues<T extends RowValue | undefined>(config:
66
66
  * mirror. A wrong/missing key or malformed envelope throws
67
67
  * {@link DecryptError} (`client.decrypt_failed`, §5.11).
68
68
  */
69
- export declare function decryptRowValues(config: EncryptionConfig, table: CompiledClientTable, values: readonly RowValue[]): Promise<RowValue[]>;
69
+ export declare function decryptRowValues(config: EncryptionConfig | undefined, table: CompiledClientTable, values: readonly RowValue[]): Promise<RowValue[]>;
@@ -9,7 +9,7 @@
9
9
  * envelope primitives.
10
10
  */
11
11
  import { DecryptError, decryptValue, EncryptError, encryptValue, KEY_LENGTH, } from '@syncular/core';
12
- import { ClientSyncError } from './errors.js';
12
+ import { invalidRequest } from './errors.js';
13
13
  /**
14
14
  * Convert a portable keyring into the direct-client encryption contract.
15
15
  * Key lengths are validated here, at install time: every side of the wire
@@ -19,7 +19,7 @@ import { ClientSyncError } from './errors.js';
19
19
  export function encryptionConfigFromKeyring(keyring) {
20
20
  for (const [keyId, key] of Object.entries(keyring.keys)) {
21
21
  if (key.length !== KEY_LENGTH) {
22
- throw new ClientSyncError('sync.invalid_request', `encryption key ${JSON.stringify(keyId)} must be ${KEY_LENGTH} bytes (AES-256), got ${key.length}`);
22
+ throw invalidRequest(`encryption key ${JSON.stringify(keyId)} must be ${KEY_LENGTH} bytes (AES-256), got ${key.length}`);
23
23
  }
24
24
  }
25
25
  return {
@@ -86,6 +86,9 @@ export async function encryptRowValues(config, table, rowId, values, storedKeyId
86
86
  }
87
87
  if (!hasPresentEncrypted)
88
88
  return out;
89
+ if (config === undefined) {
90
+ throw new EncryptError('encrypted columns need an encryption config');
91
+ }
89
92
  // Key selection reads the presence set first, then the stored local row.
90
93
  // Absent slots densify to null for selection only; the loop below still
91
94
  // leaves them untouched. Absent ≠ NULL (§6.1): only an ABSENT selector
@@ -137,6 +140,9 @@ export async function decryptRowValues(config, table, values) {
137
140
  if (!(value instanceof Uint8Array)) {
138
141
  throw new DecryptError(`encrypted column ${column.name} decoded to a non-bytes value`);
139
142
  }
143
+ if (config === undefined) {
144
+ throw new DecryptError('encrypted columns need an encryption config');
145
+ }
140
146
  out[i] = deserializeGuard(await decryptValue(declaredTypeOf(column), value, config.keyProvider));
141
147
  }
142
148
  return out;
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";
@@ -34,6 +34,8 @@ export declare class ClientSyncError extends Error {
34
34
  }
35
35
  /** Shared invalid-request construction for client validators and transport guards. */
36
36
  export declare function invalidRequest(message: string, retryable?: boolean): ClientSyncError;
37
+ /** Shared retryable `sync.transport_failed` construction for client transports. */
38
+ export declare function transportFailed(message: string, details?: Readonly<Record<string, unknown>>): ClientSyncError;
37
39
  /**
38
40
  * SPEC §7.5: the latest sync attempt failed while a live query still waited
39
41
  * for its required coverage. `code` is the attempt's static progress error
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';
@@ -41,6 +41,10 @@ export class ClientSyncError extends Error {
41
41
  export function invalidRequest(message, retryable = false) {
42
42
  return new ClientSyncError('sync.invalid_request', message, retryable);
43
43
  }
44
+ /** Shared retryable `sync.transport_failed` construction for client transports. */
45
+ export function transportFailed(message, details) {
46
+ return new ClientSyncError('sync.transport_failed', message, true, details);
47
+ }
44
48
  /**
45
49
  * SPEC §7.5: the latest sync attempt failed while a live query still waited
46
50
  * for its required coverage. `code` is the attempt's static progress error
@@ -12,7 +12,6 @@ export declare function retainFailedRows(db: ClientDatabase, commit: OutboxCommi
12
12
  export declare function uniqueConflicts(db: ClientDatabase, table: CompiledClientTable, values: Readonly<Record<string, RowValue>>): NonNullable<RetainedCommitRow['uniqueConflicts']>;
13
13
  /** Exact row keys are JSON [table,id]; table scopes include unique-key peers. */
14
14
  export type OverlayScope = readonly string[];
15
- export declare function overlayScopePredicate(table: string, id: string): string;
16
15
  export declare function restoreFailedBases(db: ClientDatabase, schema: CompiledClientSchema, scope?: OverlayScope): boolean;
17
16
  export declare function failedOverlayCommits(db: ClientDatabase, acknowledged?: boolean, scope?: OverlayScope, schema?: CompiledClientSchema): OutboxCommit[];
18
17
  export declare function dropFailedRows(db: ClientDatabase, schema: CompiledClientSchema, matches: (table: string, values: Readonly<Record<string, JsonRowValue>>) => boolean): OutboxCommit[];
@@ -1,6 +1,6 @@
1
1
  import { hasUniqueIndex } from './schema.js';
2
2
  import { OUTCOMES_TABLE } from './outcomes.js';
3
- import { OUTBOX_TABLE } from './outbox.js';
3
+ import { OUTBOX_IMAGES } from './outbox.js';
4
4
  export const RETAINED_ROWS = '_syncular_failed_rows';
5
5
  import { ClientSyncError } from './errors.js';
6
6
  import { mapRowValues, fromSqlValue, jsonToRowValue, pkSqlValue, quoteIdent, rowValueToJson, SYNC_VERSION_COLUMN, toSqlValue, } from './schema.js';
@@ -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=?`, [
@@ -90,11 +91,10 @@ export function uniqueConflicts(db, table, values) {
90
91
  serverVersion: Number(row[SYNC_VERSION_COLUMN]),
91
92
  })));
92
93
  }
93
- export function overlayScopePredicate(table, id) {
94
- 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))`;
95
- }
96
94
  function retainedRows(db, scope, acknowledged) {
97
- return db.query(`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`, [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]);
98
98
  }
99
99
  export function restoreFailedBases(db, schema, scope) {
100
100
  const seen = new Set();
@@ -141,7 +141,7 @@ export function failedOverlayCommits(db, acknowledged = false, scope, schema) {
141
141
  // Hydrate legacy failure evidence from authoritative unique-key peers.
142
142
  const values = JSON.parse(row.intent);
143
143
  const authorized = uniqueConflicts(db, table, mapRowValues(values, jsonToRowValue)).filter((conflict) => conflict.serverVersion >= 0 &&
144
- !db.query(`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`, [table.name, conflict.rowId, table.name, conflict.rowId]).length);
144
+ !db.query(`SELECT 1 FROM ${RETAINED_ROWS} WHERE tbl=? AND id=? UNION ALL SELECT 1 FROM ${OUTBOX_IMAGES} WHERE tbl=? AND row_id=? LIMIT 1`, [table.name, conflict.rowId, table.name, conflict.rowId]).length);
145
145
  if (authorized.length)
146
146
  db.exec(`UPDATE ${RETAINED_ROWS} SET unique_conflicts=? WHERE commit_id=? AND idx=?`, [
147
147
  JSON.stringify(authorized.map((conflict) => ({
package/dist/http.d.ts CHANGED
@@ -29,5 +29,8 @@ export declare function httpSegmentDownloader(segmentsBaseUrl: string, options?:
29
29
  * rows). Content-address verification is the client core's job (§5.9.7).
30
30
  */
31
31
  export declare function httpBlobTransport(blobsBaseUrl: string, options?: HttpTransportOptions): BlobTransport;
32
- /** WebSocket realtime connector (§8.1): text = control, binary = deltas. */
32
+ /**
33
+ * WebSocket realtime connector (§8.1): text = control, binary = deltas. The
34
+ * client's id replaces a `{clientId}` placeholder in the URL.
35
+ */
33
36
  export declare function webSocketRealtimeConnector(realtimeUrl: string): RealtimeConnector;
package/dist/http.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { SSP2_CONTENT_TYPE } from './content-type.js';
2
- import { ClientSyncError } from './errors.js';
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();
@@ -16,7 +17,7 @@ async function transfer(message, operation, httpStatus) {
16
17
  : error instanceof TypeError
17
18
  ? 'network'
18
19
  : 'unknown';
19
- throw new ClientSyncError('sync.transport_failed', message, true, {
20
+ throw transportFailed(message, {
20
21
  causeKind,
21
22
  ...(httpStatus !== undefined ? { httpStatus } : {}),
22
23
  });
@@ -64,7 +65,7 @@ function hostHeaders(options) {
64
65
  /** POST `<mount>/sync` with SSP2 bodies (§1.1). */
65
66
  export function httpSyncTransport(syncUrl, options) {
66
67
  const doFetch = options?.fetch ?? fetch;
67
- return async (request) => {
68
+ return async (request, signal) => {
68
69
  const response = await transfer('sync request failed', () => doFetch(syncUrl, {
69
70
  method: 'POST',
70
71
  headers: {
@@ -72,6 +73,7 @@ export function httpSyncTransport(syncUrl, options) {
72
73
  ...hostHeaders(options),
73
74
  },
74
75
  body: request.slice().buffer,
76
+ ...(signal !== undefined ? { signal } : {}),
75
77
  }));
76
78
  if (!response.ok)
77
79
  await throwHttpError(response);
@@ -100,7 +102,7 @@ function socketOperation(message, operation) {
100
102
  return operation();
101
103
  }
102
104
  catch {
103
- throw new ClientSyncError('sync.transport_failed', message, true, {
105
+ throw transportFailed(message, {
104
106
  causeKind: 'unknown',
105
107
  });
106
108
  }
@@ -125,7 +127,7 @@ export function webSocketRemoteOperationConnector(realtimeUrl) {
125
127
  };
126
128
  socket.onerror = () => {
127
129
  if (!opened) {
128
- reject(new ClientSyncError('sync.transport_failed', 'remote operation realtime socket failed to connect', true));
130
+ reject(transportFailed('remote operation realtime socket failed to connect'));
129
131
  }
130
132
  try {
131
133
  socket.close();
@@ -136,7 +138,7 @@ export function webSocketRemoteOperationConnector(realtimeUrl) {
136
138
  };
137
139
  socket.onclose = () => {
138
140
  if (!opened) {
139
- reject(new ClientSyncError('sync.transport_failed', 'remote operation realtime socket closed while connecting', true));
141
+ reject(transportFailed('remote operation realtime socket closed while connecting'));
140
142
  }
141
143
  handlers.onClose?.();
142
144
  };
@@ -150,7 +152,7 @@ export function webSocketRemoteOperationConnector(realtimeUrl) {
150
152
  * Resolution (which path a descriptor takes, expiry, no fall-through)
151
153
  * lives in the client core, not here.
152
154
  */
153
- async function readSegmentBody(response, onProgress) {
155
+ async function readBody(response, onProgress, maxBytes) {
154
156
  const chunks = [];
155
157
  let received = 0;
156
158
  let reported = 0;
@@ -163,6 +165,11 @@ async function readSegmentBody(response, onProgress) {
163
165
  break;
164
166
  chunks.push(value);
165
167
  received += value.byteLength;
168
+ // The caller rejects a body longer than its declared byteLength.
169
+ if (received > (maxBytes ?? received)) {
170
+ await reader.cancel();
171
+ break;
172
+ }
166
173
  if (received - reported >= 64 * 1024) {
167
174
  onProgress?.(received);
168
175
  reported = received;
@@ -175,33 +182,31 @@ async function readSegmentBody(response, onProgress) {
175
182
  }
176
183
  if (received !== reported)
177
184
  onProgress?.(received);
178
- const bytes = new Uint8Array(received);
179
- let offset = 0;
180
- for (const chunk of chunks) {
181
- bytes.set(chunk, offset);
182
- offset += chunk.byteLength;
183
- }
184
- return bytes;
185
+ return new Uint8Array(await new Blob(chunks).arrayBuffer());
185
186
  }
186
187
  export function httpSegmentDownloader(segmentsBaseUrl, options) {
187
188
  const doFetch = options?.fetch ?? fetch;
188
- const download = async (url, init, onProgress, signed = false) => {
189
+ const download = async (url, init, onProgress, signed = false, maxBytes) => {
189
190
  const response = await transfer('segment transfer failed', () => doFetch(url, init));
190
191
  if (!response.ok) {
191
192
  if (!signed)
192
193
  await throwHttpError(response);
193
- throw new ClientSyncError('sync.transport_failed', 'signed segment request failed; invalidate the descriptor and re-pull', true, { causeKind: 'status', httpStatus: response.status });
194
+ throw transportFailed('signed segment request failed', {
195
+ causeKind: 'status',
196
+ httpStatus: response.status,
197
+ });
194
198
  }
195
- return transfer('segment transfer failed', () => readSegmentBody(response, onProgress), response.status);
199
+ return transfer('segment transfer failed', () => readBody(response, onProgress, maxBytes), response.status);
196
200
  };
197
201
  const direct = (request) => download(`${segmentsBaseUrl}/${encodeURIComponent(request.segmentId)}`, {
198
202
  headers: {
199
203
  'X-Syncular-Scopes': request.requestedScopesJson,
200
204
  ...hostHeaders(options),
201
205
  },
202
- }, request.onProgress);
206
+ ...(request.signal !== undefined ? { signal: request.signal } : {}),
207
+ }, request.onProgress, false, request.byteLength);
203
208
  // Deliberately headerless: the URL is the bearer grant (§5.4).
204
- const fetchUrl = (url, onProgress) => download(url, undefined, onProgress, true);
209
+ const fetchUrl = (url, onProgress, signal, byteLength) => download(url, signal !== undefined ? { signal } : undefined, onProgress, true, byteLength);
205
210
  return Object.assign(direct, { fetchUrl });
206
211
  }
207
212
  /**
@@ -214,7 +219,7 @@ export function httpBlobTransport(blobsBaseUrl, options) {
214
219
  const doFetch = options?.fetch ?? fetch;
215
220
  const blobUrl = (blobId) => `${blobsBaseUrl}/${encodeURIComponent(blobId)}`;
216
221
  return {
217
- upload: async (blobId, bytes, mediaType) => {
222
+ upload: async (blobId, bytes, mediaType, signal) => {
218
223
  const response = await transfer('blob upload failed', () => doFetch(blobUrl(blobId), {
219
224
  method: 'PUT',
220
225
  headers: {
@@ -222,11 +227,12 @@ export function httpBlobTransport(blobsBaseUrl, options) {
222
227
  ...hostHeaders(options),
223
228
  },
224
229
  body: bytes.slice().buffer,
230
+ ...(signal !== undefined ? { signal } : {}),
225
231
  }));
226
232
  if (!response.ok)
227
233
  await throwHttpError(response);
228
234
  },
229
- download: async (blobId) => {
235
+ download: async (blobId, byteLength) => {
230
236
  const response = await transfer('blob download failed', () => doFetch(blobUrl(blobId), {
231
237
  headers: { ...hostHeaders(options) },
232
238
  }));
@@ -239,11 +245,10 @@ export function httpBlobTransport(blobsBaseUrl, options) {
239
245
  ? 'sync.auth_required'
240
246
  : 'sync.transport_failed');
241
247
  // §5.9.5 always-issue: a JSON body with a `url` means presigned delivery;
242
- // any other body is inline bytes. The body is read exactly once as bytes,
243
- // so an inline blob stored as `application/json` stays readable.
244
- const contentType = response.headers.get('content-type') ?? '';
245
- const bytes = new Uint8Array(await transfer('blob download body read failed', () => response.arrayBuffer(), response.status));
246
- if (contentType.includes('application/json')) {
248
+ // any other body is inline bytes, capped by the declared byteLength.
249
+ const json = (response.headers.get('content-type') ?? '').includes('application/json');
250
+ const bytes = await transfer('blob body read failed', () => readBody(response, undefined, json ? undefined : byteLength), response.status);
251
+ if (json) {
247
252
  let envelope = null;
248
253
  try {
249
254
  envelope = JSON.parse(new TextDecoder().decode(bytes));
@@ -264,15 +269,18 @@ export function httpBlobTransport(blobsBaseUrl, options) {
264
269
  return { kind: 'bytes', bytes };
265
270
  },
266
271
  // §5.9.5: bare GET of the signed URL — no host auth (the URL is the grant).
267
- fetchUrl: async (url) => {
272
+ fetchUrl: async (url, byteLength) => {
268
273
  const response = await transfer('signed blob download failed', () => doFetch(url));
269
274
  if (!response.ok) {
270
- throw new ClientSyncError('sync.transport_failed', 'signed blob download failed; re-request to recover', true, { causeKind: 'status', httpStatus: response.status });
275
+ throw transportFailed('signed blob download failed', {
276
+ causeKind: 'status',
277
+ httpStatus: response.status,
278
+ });
271
279
  }
272
- return new Uint8Array(await transfer('response body read failed', () => response.arrayBuffer(), response.status));
280
+ return transfer('response body read failed', () => readBody(response, undefined, byteLength), response.status);
273
281
  },
274
282
  // §5.9.3: presigned-upload grant.
275
- uploadGrant: async (blobId, byteLength, mediaType) => {
283
+ uploadGrant: async (blobId, byteLength, mediaType, signal) => {
276
284
  const response = await transfer('blob upload grant request failed', () => doFetch(`${blobUrl(blobId)}/upload-grant`, {
277
285
  method: 'POST',
278
286
  headers: {
@@ -283,10 +291,11 @@ export function httpBlobTransport(blobsBaseUrl, options) {
283
291
  byteLength,
284
292
  ...(mediaType !== undefined ? { mediaType } : {}),
285
293
  }),
294
+ ...(signal !== undefined ? { signal } : {}),
286
295
  }));
287
296
  if (!response.ok)
288
297
  await throwHttpError(response);
289
- const body = (await transfer('blob upload grant body read failed', () => response.json(), response.status));
298
+ const body = (await transfer('blob grant read failed', () => response.json(), response.status));
290
299
  if (typeof body.url === 'string') {
291
300
  return {
292
301
  kind: 'url',
@@ -301,24 +310,43 @@ export function httpBlobTransport(blobsBaseUrl, options) {
301
310
  return { kind: 'none' };
302
311
  },
303
312
  // §5.9.3: direct-to-storage PUT — no host auth (the URL is the grant).
304
- uploadToUrl: async (url, bytes, mediaType) => {
313
+ uploadToUrl: async (blobId, url, bytes, mediaType, signal) => {
314
+ // The grant signs content-length (set by fetch from the body) and the
315
+ // checksum, the blob id's digest, so the object store rejects any other
316
+ // bytes without the client hashing the body again (§5.9.3).
317
+ const hex = /^sha256:([0-9a-f]{64})$/.exec(blobId)?.[1];
318
+ if (hex === undefined) {
319
+ throw new ClientSyncError('sync.invalid_request', 'the blob id is not a sha256 blob id (§5.9.1)');
320
+ }
321
+ const checksum = btoa(String.fromCharCode(...hexToBytes(hex)));
322
+ const body = bytes.slice().buffer;
305
323
  const response = await transfer('signed blob upload failed', () => doFetch(url, {
306
324
  method: 'PUT',
307
325
  headers: {
308
326
  'Content-Type': mediaType ?? 'application/octet-stream',
327
+ 'x-amz-checksum-sha256': checksum,
309
328
  },
310
- body: bytes.slice().buffer,
329
+ body,
330
+ ...(signal !== undefined ? { signal } : {}),
311
331
  }));
312
332
  if (!response.ok) {
313
- throw new ClientSyncError('sync.transport_failed', 'signed blob upload failed; re-request a grant or stream direct', true, { causeKind: 'status', httpStatus: response.status });
333
+ throw transportFailed('signed blob upload failed', {
334
+ causeKind: 'status',
335
+ httpStatus: response.status,
336
+ });
314
337
  }
315
338
  },
316
339
  };
317
340
  }
318
- /** WebSocket realtime connector (§8.1): text = control, binary = deltas. */
341
+ /**
342
+ * WebSocket realtime connector (§8.1): text = control, binary = deltas. The
343
+ * client's id replaces a `{clientId}` placeholder in the URL.
344
+ */
319
345
  export function webSocketRealtimeConnector(realtimeUrl) {
320
- return (handlers) => new Promise((resolve, reject) => {
321
- const socket = socketOperation('realtime socket failed to connect', () => new WebSocket(realtimeUrl));
346
+ return (handlers, clientId) => new Promise((resolve, reject) => {
347
+ const socket = socketOperation('realtime socket failed to connect', () => new WebSocket(clientId === undefined
348
+ ? realtimeUrl
349
+ : realtimeUrl.replace('{clientId}', encodeURIComponent(clientId))));
322
350
  let opened = false;
323
351
  socket.binaryType = 'arraybuffer';
324
352
  socket.onopen = () => {
@@ -339,7 +367,7 @@ export function webSocketRealtimeConnector(realtimeUrl) {
339
367
  };
340
368
  socket.onerror = () => {
341
369
  if (!opened) {
342
- reject(new ClientSyncError('sync.transport_failed', 'realtime socket failed to connect', true));
370
+ reject(transportFailed('realtime socket failed to connect'));
343
371
  }
344
372
  try {
345
373
  socket.close();
@@ -350,7 +378,7 @@ export function webSocketRealtimeConnector(realtimeUrl) {
350
378
  };
351
379
  socket.onclose = () => {
352
380
  if (!opened) {
353
- reject(new ClientSyncError('sync.transport_failed', 'realtime socket closed while connecting', true));
381
+ reject(transportFailed('realtime socket closed while connecting'));
354
382
  }
355
383
  handlers.onClose?.();
356
384
  };
package/dist/index.d.ts CHANGED
@@ -30,7 +30,7 @@ export * from './naming.js';
30
30
  export * from './outbox.js';
31
31
  export * from './outcomes.js';
32
32
  export { decodePreviousVersionAuditResult, decodePreviousVersionDiscardResult, decodePreviousVersionSnapshot, type PreviousVersionAudit, type PreviousVersionReadSpec, type PreviousVersionReason, type PreviousVersionSnapshot, } from './previous-version.js';
33
- export * from './query-guard.js';
33
+ export { prepareReadOnly, RawSqlError } from './query-guard.js';
34
34
  export * from './reactive-store.js';
35
35
  export * from './remote.js';
36
36
  export * from './realtime-supervisor.js';
package/dist/index.js CHANGED
@@ -23,7 +23,7 @@ export * from './outcomes.js';
23
23
  // refusal/audit codecs), not package API. The feature is opt-in and its
24
24
  // consumer-facing contract is exactly the read spec and the two result types.
25
25
  export { decodePreviousVersionAuditResult, decodePreviousVersionDiscardResult, decodePreviousVersionSnapshot, } from './previous-version.js';
26
- export * from './query-guard.js';
26
+ export { prepareReadOnly, RawSqlError } from './query-guard.js';
27
27
  export * from './reactive-store.js';
28
28
  export * from './remote.js';
29
29
  export * from './realtime-supervisor.js';
@@ -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,13 +80,17 @@ 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;
89
88
  outcomes(): void;
90
- /** Add precise keys for a requested/effective scope map. */
89
+ /**
90
+ * Add precise keys for a bulk scoped delete. A map that leaves a declared
91
+ * scope variable unnamed cannot list the deleted rows' keys for that
92
+ * variable, so the change is table-wide.
93
+ */
91
94
  scopeMap(table: CompiledClientTable, scopes: ScopeMap): void;
92
95
  /** Add precise keys for a COMMIT change's stored scope values. */
93
96
  changeScopes(table: CompiledClientTable, scopes: Readonly<Record<string, string>>): void;
@@ -96,11 +99,12 @@ export declare class ChangeAccumulator {
96
99
  get statusChanged(): boolean;
97
100
  finish(revision: LocalRevision, status: SyncStatusSnapshot | undefined): ClientChangeBatch;
98
101
  }
99
- /** Exception-isolated synchronous change listener set. */
100
- export declare class ChangeEmitter {
102
+ /** Exception-isolated synchronous listener set; observer code must never
103
+ * corrupt the committed core path. */
104
+ export declare class ChangeEmitter<T = ClientChangeBatch> {
101
105
  #private;
102
- on(listener: ClientChangeListener): () => void;
103
- emit(batch: ClientChangeBatch): void;
106
+ on(listener: (value: T) => void): () => void;
107
+ emit(value: T): void;
104
108
  get size(): number;
105
109
  }
106
110
  /**
@@ -113,11 +117,7 @@ export interface InvalidationEvent {
113
117
  }
114
118
  export type InvalidationListener = (event: InvalidationEvent) => void;
115
119
  export declare function invalidationFromChange(batch: ClientChangeBatch): InvalidationEvent | undefined;
116
- export declare class InvalidationEmitter {
117
- #private;
118
- on(listener: InvalidationListener): () => void;
119
- emit(event: InvalidationEvent): void;
120
- get size(): number;
120
+ export declare class InvalidationEmitter extends ChangeEmitter<InvalidationEvent> {
121
121
  }
122
122
  /** @deprecated Use {@link ChangeAccumulator}. */
123
123
  export { ChangeAccumulator as Invalidation };