@syncular/client 0.62.1 → 0.64.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.
package/dist/client.js CHANGED
@@ -20,7 +20,7 @@ import { EncodeError } from '@syncular/core';
20
20
  import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, localScopePredicate, ownsLocalRow, evictScopedRows, yieldToHost, upsertLocalRow, } from './apply.js';
21
21
  import { clearPendingUpload, computeBlobId, deleteUnreferencedCachedBlobs, enforceBlobCacheCap, ensureBlobSchema, getCachedBlob, listPendingUploads, parseBlobRef, putCachedBlob, recordPendingUpload, schemaHasBlobs, serializeBlobRef, } from './blob.js';
22
22
  import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_QUERY_FAILURES, } from './diagnostics.js';
23
- import { ClientSyncError, invalidRequest, classifySqliteFailure, REALTIME_LOST_CODE, RealtimeUnavailableError, transportFailed, } from './errors.js';
23
+ import { ClientSyncError, invalidRequest, classifySqliteFailure, isStableCode, REALTIME_LOST_CODE, RealtimeUnavailableError, transportFailed, } from './errors.js';
24
24
  import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
25
25
  import { singleOwnerLock, } from './leader-lock.js';
26
26
  import { compileLocalDataPurge, localDataPurgeMetaKey, localDataPurgeTargetMatches, } from './local-purge.js';
@@ -2942,9 +2942,7 @@ export class SyncClient {
2942
2942
  };
2943
2943
  }
2944
2944
  #diagnosticCode(code) {
2945
- return code.length <= 96 && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/.test(code)
2946
- ? code
2947
- : 'client.unknown_failure';
2945
+ return isStableCode(code) ? code : 'client.unknown_failure';
2948
2946
  }
2949
2947
  async #runSync(signal) {
2950
2948
  this.#requireTransport();
@@ -63,7 +63,8 @@ export declare function encryptRowValues<T extends RowValue | undefined>(config:
63
63
  * (returns a new array). Called at the apply seam (§4.5 COMMIT, §5.6 rows
64
64
  * segment) AFTER the row codec decodes: an encrypted column's ciphertext
65
65
  * envelope `bytes` becomes its plaintext declared-type value for the local
66
- * mirror. A wrong/missing key or malformed envelope throws
67
- * {@link DecryptError} (`client.decrypt_failed`, §5.11).
66
+ * mirror. A missing key throws {@link DecryptError} coded
67
+ * `client.encryption_key_missing` with the table and key id in `details`; a
68
+ * wrong key or malformed envelope throws `client.decrypt_failed` (§5.11).
68
69
  */
69
70
  export declare function decryptRowValues(config: EncryptionConfig | undefined, table: CompiledClientTable, values: readonly RowValue[]): Promise<RowValue[]>;
@@ -123,8 +123,9 @@ export async function encryptRowValues(config, table, rowId, values, storedKeyId
123
123
  * (returns a new array). Called at the apply seam (§4.5 COMMIT, §5.6 rows
124
124
  * segment) AFTER the row codec decodes: an encrypted column's ciphertext
125
125
  * envelope `bytes` becomes its plaintext declared-type value for the local
126
- * mirror. A wrong/missing key or malformed envelope throws
127
- * {@link DecryptError} (`client.decrypt_failed`, §5.11).
126
+ * mirror. A missing key throws {@link DecryptError} coded
127
+ * `client.encryption_key_missing` with the table and key id in `details`; a
128
+ * wrong key or malformed envelope throws `client.decrypt_failed` (§5.11).
128
129
  */
129
130
  export async function decryptRowValues(config, table, values) {
130
131
  if (!table.hasEncryptedColumns)
@@ -143,7 +144,7 @@ export async function decryptRowValues(config, table, values) {
143
144
  if (config === undefined) {
144
145
  throw new DecryptError('encrypted columns need an encryption config');
145
146
  }
146
- out[i] = deserializeGuard(await decryptValue(declaredTypeOf(column), value, config.keyProvider));
147
+ out[i] = deserializeGuard(await decryptValue(declaredTypeOf(column), value, config.keyProvider, table.name));
147
148
  }
148
149
  return out;
149
150
  }
package/dist/errors.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import type { RealtimeState } from './diagnostics.js';
2
+ import { type WorkerErrorShape } from './worker-protocol.js';
2
3
  /** A persistent local store is temporarily owned by another live engine. */
3
4
  export declare const STORAGE_BUSY_CODE = "client.storage_busy";
4
5
  /**
@@ -77,3 +78,13 @@ export declare function classifySqliteFailure(error: unknown): {
77
78
  readonly code: typeof STORAGE_CORRUPT_CODE | typeof STORAGE_FULL_CODE | typeof STORAGE_IO_CODE | typeof STORAGE_BUSY_CODE | undefined;
78
79
  readonly error: unknown;
79
80
  };
81
+ /** A stable error identity: lowercase dotted segments, at most 96 chars. */
82
+ export declare function isStableCode(code: string): boolean;
83
+ /**
84
+ * The structured-clone form of a failure that crosses a Worker or tab
85
+ * boundary. Any error carrying a stable `code` (a `ClientSyncError` or a
86
+ * `@syncular/core` error such as `DecryptError`) keeps its
87
+ * code, `retryable` and details (SPEC §5.11); only an uncoded failure
88
+ * becomes `client.worker_failed`.
89
+ */
90
+ export declare function toErrorShape(caught: unknown): WorkerErrorShape;
package/dist/errors.js CHANGED
@@ -1,3 +1,5 @@
1
+ import { DecryptError } from '@syncular/core';
2
+ import { WORKER_FAILED_CODE } from './worker-protocol.js';
1
3
  /** A persistent local store is temporarily owned by another live engine. */
2
4
  export const STORAGE_BUSY_CODE = 'client.storage_busy';
3
5
  /**
@@ -166,3 +168,36 @@ export function classifySqliteFailure(error) {
166
168
  Object.defineProperty(failure, 'cause', { value: error });
167
169
  return { sqliteCode, code, error: failure };
168
170
  }
171
+ /** A stable error identity: lowercase dotted segments, at most 96 chars. */
172
+ export function isStableCode(code) {
173
+ return code.length <= 96 && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/.test(code);
174
+ }
175
+ /**
176
+ * The structured-clone form of a failure that crosses a Worker or tab
177
+ * boundary. Any error carrying a stable `code` (a `ClientSyncError` or a
178
+ * `@syncular/core` error such as `DecryptError`) keeps its
179
+ * code, `retryable` and details (SPEC §5.11); only an uncoded failure
180
+ * becomes `client.worker_failed`.
181
+ */
182
+ export function toErrorShape(caught) {
183
+ const error = classifySqliteFailure(caught).error;
184
+ if (error instanceof Error &&
185
+ 'code' in error &&
186
+ typeof error.code === 'string' &&
187
+ isStableCode(error.code)) {
188
+ const details = error instanceof ClientSyncError || error instanceof DecryptError
189
+ ? error.details
190
+ : undefined;
191
+ return {
192
+ code: error.code,
193
+ message: error.message,
194
+ retryable: 'retryable' in error && error.retryable === true,
195
+ ...(details !== undefined ? { details } : {}),
196
+ };
197
+ }
198
+ return {
199
+ code: WORKER_FAILED_CODE,
200
+ message: error instanceof Error ? error.message : String(error),
201
+ retryable: false,
202
+ };
203
+ }
package/dist/multi-tab.js CHANGED
@@ -70,7 +70,7 @@
70
70
  * state waits on that lock for each tab that called it; the grant means the
71
71
  * tab is gone.
72
72
  */
73
- import { ClientSyncError } from './errors.js';
73
+ import { ClientSyncError, toErrorShape } from './errors.js';
74
74
  import { webLocksLeaderLock, } from './leader-lock.js';
75
75
  import { WORKER_FAILED_CODE } from './worker-protocol.js';
76
76
  /** Client-local: a follower call could not reach a leader before its deadline. */
@@ -238,20 +238,7 @@ export class LeaderBridge {
238
238
  }, (error) => {
239
239
  if (this.#closed)
240
240
  return;
241
- const shape = error instanceof ClientSyncError
242
- ? {
243
- code: error.code,
244
- message: error.message,
245
- retryable: error.retryable,
246
- ...(error.details !== undefined
247
- ? { details: error.details }
248
- : {}),
249
- }
250
- : {
251
- code: WORKER_FAILED_CODE,
252
- message: error instanceof Error ? error.message : 'unknown error',
253
- retryable: false,
254
- };
241
+ const shape = toErrorShape(error);
255
242
  this.#channel.postMessage({
256
243
  t: 'res',
257
244
  epoch: this.#epoch,
@@ -1,26 +1,10 @@
1
1
  import { SyncClient } from './client.js';
2
2
  import { withClientDiagnosticsHost, } from './diagnostics.js';
3
3
  import { encryptionConfigFromKeyring } from './encryption.js';
4
- import { classifySqliteFailure, ClientSyncError, invalidRequest, STORAGE_BUSY_CODE, } from './errors.js';
4
+ import { ClientSyncError, invalidRequest, STORAGE_BUSY_CODE, toErrorShape, } from './errors.js';
5
5
  import { httpBlobTransport, httpSegmentDownloader, httpSyncTransport, webSocketRealtimeConnector, } from './http.js';
6
6
  import { openPersistentWasmDatabase } from './wasm-database.js';
7
7
  import { LOCAL_AUTHORITY_UNCONFIGURED_CODE, WORKER_FAILED_CODE, WORKER_METHOD_UNAVAILABLE_CODE, } from './worker-protocol.js';
8
- function toErrorShape(caught) {
9
- const error = classifySqliteFailure(caught).error;
10
- if (error instanceof ClientSyncError) {
11
- return {
12
- code: error.code,
13
- message: error.message,
14
- retryable: error.retryable,
15
- ...(error.details !== undefined ? { details: error.details } : {}),
16
- };
17
- }
18
- return {
19
- code: WORKER_FAILED_CODE,
20
- message: error instanceof Error ? error.message : String(error),
21
- retryable: false,
22
- };
23
- }
24
8
  /**
25
9
  * ArrayBuffers safe to transfer out of a query result: whole-buffer
26
10
  * views only (a view into a larger/pooled buffer is cloned instead —
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.62.1",
3
+ "version": "0.64.0",
4
4
  "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -113,11 +113,11 @@
113
113
  },
114
114
  "dependencies": {
115
115
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
116
- "@syncular/core": "0.62.1"
116
+ "@syncular/core": "0.64.0"
117
117
  },
118
118
  "devDependencies": {
119
119
  "@electric-sql/pglite": "^0.5.4",
120
- "@syncular/server": "0.62.1",
120
+ "@syncular/server": "0.64.0",
121
121
  "playwright": "1.63.0",
122
122
  "vite": "8.3.4"
123
123
  }
package/src/client.ts CHANGED
@@ -117,6 +117,7 @@ import {
117
117
  ClientSyncError,
118
118
  invalidRequest,
119
119
  classifySqliteFailure,
120
+ isStableCode,
120
121
  REALTIME_LOST_CODE,
121
122
  RealtimeUnavailableError,
122
123
  transportFailed,
@@ -4305,9 +4306,7 @@ export class SyncClient {
4305
4306
  }
4306
4307
 
4307
4308
  #diagnosticCode(code: string): string {
4308
- return code.length <= 96 && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/.test(code)
4309
- ? code
4310
- : 'client.unknown_failure';
4309
+ return isStableCode(code) ? code : 'client.unknown_failure';
4311
4310
  }
4312
4311
 
4313
4312
  async #runSync(signal: AbortSignal | undefined): Promise<SyncSummary> {
package/src/encryption.ts CHANGED
@@ -211,8 +211,9 @@ export async function encryptRowValues<T extends RowValue | undefined>(
211
211
  * (returns a new array). Called at the apply seam (§4.5 COMMIT, §5.6 rows
212
212
  * segment) AFTER the row codec decodes: an encrypted column's ciphertext
213
213
  * envelope `bytes` becomes its plaintext declared-type value for the local
214
- * mirror. A wrong/missing key or malformed envelope throws
215
- * {@link DecryptError} (`client.decrypt_failed`, §5.11).
214
+ * mirror. A missing key throws {@link DecryptError} coded
215
+ * `client.encryption_key_missing` with the table and key id in `details`; a
216
+ * wrong key or malformed envelope throws `client.decrypt_failed` (§5.11).
216
217
  */
217
218
  export async function decryptRowValues(
218
219
  config: EncryptionConfig | undefined,
@@ -235,7 +236,12 @@ export async function decryptRowValues(
235
236
  throw new DecryptError('encrypted columns need an encryption config');
236
237
  }
237
238
  out[i] = deserializeGuard(
238
- await decryptValue(declaredTypeOf(column), value, config.keyProvider),
239
+ await decryptValue(
240
+ declaredTypeOf(column),
241
+ value,
242
+ config.keyProvider,
243
+ table.name,
244
+ ),
239
245
  );
240
246
  }
241
247
  return out;
package/src/errors.ts CHANGED
@@ -1,4 +1,6 @@
1
+ import { DecryptError } from '@syncular/core';
1
2
  import type { RealtimeState } from './diagnostics';
3
+ import { WORKER_FAILED_CODE, type WorkerErrorShape } from './worker-protocol';
2
4
 
3
5
  /** A persistent local store is temporarily owned by another live engine. */
4
6
  export const STORAGE_BUSY_CODE = 'client.storage_busy';
@@ -235,3 +237,41 @@ export function classifySqliteFailure(error: unknown): {
235
237
  Object.defineProperty(failure, 'cause', { value: error });
236
238
  return { sqliteCode, code, error: failure };
237
239
  }
240
+
241
+ /** A stable error identity: lowercase dotted segments, at most 96 chars. */
242
+ export function isStableCode(code: string): boolean {
243
+ return code.length <= 96 && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/.test(code);
244
+ }
245
+
246
+ /**
247
+ * The structured-clone form of a failure that crosses a Worker or tab
248
+ * boundary. Any error carrying a stable `code` (a `ClientSyncError` or a
249
+ * `@syncular/core` error such as `DecryptError`) keeps its
250
+ * code, `retryable` and details (SPEC §5.11); only an uncoded failure
251
+ * becomes `client.worker_failed`.
252
+ */
253
+ export function toErrorShape(caught: unknown): WorkerErrorShape {
254
+ const error = classifySqliteFailure(caught).error;
255
+ if (
256
+ error instanceof Error &&
257
+ 'code' in error &&
258
+ typeof error.code === 'string' &&
259
+ isStableCode(error.code)
260
+ ) {
261
+ const details =
262
+ error instanceof ClientSyncError || error instanceof DecryptError
263
+ ? error.details
264
+ : undefined;
265
+ return {
266
+ code: error.code,
267
+ message: error.message,
268
+ retryable: 'retryable' in error && error.retryable === true,
269
+ ...(details !== undefined ? { details } : {}),
270
+ };
271
+ }
272
+ return {
273
+ code: WORKER_FAILED_CODE,
274
+ message: error instanceof Error ? error.message : String(error),
275
+ retryable: false,
276
+ };
277
+ }
package/src/multi-tab.ts CHANGED
@@ -70,7 +70,7 @@
70
70
  * state waits on that lock for each tab that called it; the grant means the
71
71
  * tab is gone.
72
72
  */
73
- import { ClientSyncError } from './errors';
73
+ import { ClientSyncError, toErrorShape } from './errors';
74
74
  import {
75
75
  type LeaderLease,
76
76
  type LeaderLock,
@@ -410,22 +410,7 @@ export class LeaderBridge<E = SyncWorkerEvent> {
410
410
  },
411
411
  (error: unknown) => {
412
412
  if (this.#closed) return;
413
- const shape =
414
- error instanceof ClientSyncError
415
- ? {
416
- code: error.code,
417
- message: error.message,
418
- retryable: error.retryable,
419
- ...(error.details !== undefined
420
- ? { details: error.details }
421
- : {}),
422
- }
423
- : {
424
- code: WORKER_FAILED_CODE,
425
- message:
426
- error instanceof Error ? error.message : 'unknown error',
427
- retryable: false,
428
- };
413
+ const shape = toErrorShape(error);
429
414
  this.#channel.postMessage({
430
415
  t: 'res',
431
416
  epoch: this.#epoch,
@@ -22,10 +22,10 @@ import {
22
22
  } from './diagnostics';
23
23
  import { encryptionConfigFromKeyring } from './encryption';
24
24
  import {
25
- classifySqliteFailure,
26
25
  ClientSyncError,
27
26
  invalidRequest,
28
27
  STORAGE_BUSY_CODE,
28
+ toErrorShape,
29
29
  } from './errors';
30
30
  import {
31
31
  httpBlobTransport,
@@ -49,7 +49,6 @@ import {
49
49
  WORKER_METHOD_UNAVAILABLE_CODE,
50
50
  type WorkerApi,
51
51
  type WorkerCallMessage,
52
- type WorkerErrorShape,
53
52
  type WorkerInitConfig,
54
53
  type WorkerInitResult,
55
54
  type WorkerMethod,
@@ -146,23 +145,6 @@ interface WorkerScope {
146
145
  ): void;
147
146
  }
148
147
 
149
- function toErrorShape(caught: unknown): WorkerErrorShape {
150
- const error = classifySqliteFailure(caught).error;
151
- if (error instanceof ClientSyncError) {
152
- return {
153
- code: error.code,
154
- message: error.message,
155
- retryable: error.retryable,
156
- ...(error.details !== undefined ? { details: error.details } : {}),
157
- };
158
- }
159
- return {
160
- code: WORKER_FAILED_CODE,
161
- message: error instanceof Error ? error.message : String(error),
162
- retryable: false,
163
- };
164
- }
165
-
166
148
  /**
167
149
  * ArrayBuffers safe to transfer out of a query result: whole-buffer
168
150
  * views only (a view into a larger/pooled buffer is cloned instead —