@syncular/client 0.63.0 → 0.65.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/README.md CHANGED
@@ -755,6 +755,7 @@ they own their buffer.
755
755
  | `./sqlite` | Runtime-selected SQLite: `openSqliteDatabase` on Node or Bun |
756
756
  | `./bun` | Explicit `bun:sqlite` binding: `openBunDatabase` |
757
757
  | `./node` | Explicit built-in `node:sqlite` binding: `openNodeDatabase` |
758
+ | `./dev` | Development profiler: `createSyncProfiler`, `assertBudgets` |
758
759
 
759
760
  Tests drive the real worker entry in a bun `Worker` with bun:sqlite
760
761
  injected through the bootstrap's database-factory override
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();
@@ -0,0 +1,127 @@
1
+ /**
2
+ * `@syncular/client/dev`: a development profiler. It wraps the database,
3
+ * the sync transport, the realtime connector and the client (or a worker or
4
+ * native handle) an app already constructs, and reports per live query, per
5
+ * statement, per round, per unit and per write burst. It keeps SQL text in
6
+ * memory, so `createSyncProfiler` refuses a build without a development or
7
+ * test signal. No production entry imports this module.
8
+ */
9
+ import type { MutationInput, QueryReadSpec, QuerySnapshot } from './client.js';
10
+ import type { ClientDatabase } from './database.js';
11
+ import type { ClientDiagnosticsListener } from './diagnostics.js';
12
+ import type { ClientChangeListener } from './invalidation.js';
13
+ import type { SyncProgressListener } from './progress.js';
14
+ import type { RealtimeConnector, SyncTransport } from './transport.js';
15
+ /** The surface `profiler.client()` wraps: a `SyncClient`, a worker handle or a native handle. */
16
+ export interface ProfiledClient {
17
+ querySnapshot(spec: QueryReadSpec): QuerySnapshot | Promise<QuerySnapshot>;
18
+ mutate(mutations: readonly MutationInput[]): unknown;
19
+ onChange(listener: ClientChangeListener): () => void;
20
+ onProgress(listener: SyncProgressListener): () => void;
21
+ onDiagnostics(listener: ClientDiagnosticsListener): () => void;
22
+ }
23
+ export interface SyncProfilerOptions {
24
+ /** Milliseconds clock; tests pass a virtual one. Default `performance.now`. */
25
+ readonly now?: () => number;
26
+ /** The server's `maxSubscriptionsPerRequest`. Default 500. */
27
+ readonly unitLimit?: number;
28
+ /**
29
+ * Single-operation commits that start within this many milliseconds of the
30
+ * previous one join its write burst. Default 16.
31
+ */
32
+ readonly burstWindowMs?: number;
33
+ /**
34
+ * Shared between a worker's profiler and the page's: the worker posts its
35
+ * statements and rounds, the page merges them into its report. Pass
36
+ * `new BroadcastChannel(name)` with the same name on both sides.
37
+ */
38
+ readonly channel?: Pick<BroadcastChannel, 'postMessage' | 'onmessage'>;
39
+ }
40
+ export interface QueryProfile {
41
+ /** The owner id of a live query, or the SQL of an unowned read. */
42
+ readonly id: string;
43
+ readonly sql: string;
44
+ readonly tables: readonly string[];
45
+ readonly runs: number;
46
+ /** Runs whose rows equal the previous run's rows. */
47
+ readonly identicalRuns: number;
48
+ readonly totalMs: number;
49
+ readonly maxMs: number;
50
+ /** Rows of the last run. */
51
+ readonly rows: number;
52
+ /** Runs per changed table, plus `mount` (first run) and `refresh` (no table changed). */
53
+ readonly triggers: Readonly<Record<string, number>>;
54
+ }
55
+ export interface StatementProfile {
56
+ readonly sql: string;
57
+ readonly runs: number;
58
+ readonly totalMs: number;
59
+ readonly maxMs: number;
60
+ readonly rows: number;
61
+ }
62
+ export interface RoundProfile {
63
+ readonly via: 'http' | 'socket';
64
+ readonly requestBytes: number;
65
+ readonly responseBytes: number;
66
+ /** From sending the request to the last response byte. */
67
+ readonly ms: number;
68
+ }
69
+ export interface UnitProfile {
70
+ readonly unitId: string;
71
+ readonly table: string | undefined;
72
+ /** Segment bytes downloaded or received inline. */
73
+ readonly bytes: number;
74
+ readonly rows: number;
75
+ /** From the unit's first progress event to its last. */
76
+ readonly ms: number;
77
+ }
78
+ export interface ProfileReport {
79
+ readonly queries: readonly QueryProfile[];
80
+ readonly statements: readonly StatementProfile[];
81
+ /** The last 256 rounds. */
82
+ readonly rounds: readonly RoundProfile[];
83
+ readonly deltas: {
84
+ readonly count: number;
85
+ readonly bytes: number;
86
+ };
87
+ readonly units: {
88
+ /** `activeUnits` of the last diagnostics snapshot: the units the next pull sends. */
89
+ readonly active: number;
90
+ readonly peak: number;
91
+ readonly limit: number;
92
+ readonly bootstraps: readonly UnitProfile[];
93
+ };
94
+ readonly writes: {
95
+ readonly mutateCalls: number;
96
+ readonly operations: number;
97
+ /** Runs of more than one single-operation commit (`burstWindowMs`). */
98
+ readonly bursts: readonly {
99
+ readonly commits: number;
100
+ readonly tables: readonly string[];
101
+ }[];
102
+ };
103
+ }
104
+ export interface SyncProfiler {
105
+ database<D extends ClientDatabase>(database: D): D;
106
+ transport(transport: SyncTransport): SyncTransport;
107
+ realtime(connector: RealtimeConnector): RealtimeConnector;
108
+ client<C extends ProfiledClient>(client: C): C;
109
+ report(): ProfileReport;
110
+ reset(): void;
111
+ }
112
+ export interface ProfileBudgets {
113
+ readonly maxActiveUnits?: number;
114
+ /** Request plus response bytes of one round. */
115
+ readonly maxRoundBytes?: number;
116
+ readonly maxRunsPerQuery?: number;
117
+ /** Identical runs summed over all queries. */
118
+ readonly maxIdenticalRuns?: number;
119
+ /** Commits of the largest write burst. */
120
+ readonly maxWriteBurst?: number;
121
+ }
122
+ export declare function createSyncProfiler(options?: SyncProfilerOptions): SyncProfiler;
123
+ /**
124
+ * Throws `client.profile_budget_exceeded` listing every budget the report
125
+ * exceeds, with `budget`, `limit` and `measured` per entry in `details.exceeded`.
126
+ */
127
+ export declare function assertBudgets(report: ProfileReport, budgets: ProfileBudgets): void;
@@ -0,0 +1,338 @@
1
+ import { developmentBuild } from './devtools.js';
2
+ import { ClientSyncError } from './errors.js';
3
+ import { canonicalValue } from './reactive-store.js';
4
+ /** A proxy that replaces `overrides` and binds every other method to `target`. */
5
+ function wrap(target, overrides) {
6
+ return new Proxy(target, {
7
+ get(object, key) {
8
+ if (Object.hasOwn(overrides, key))
9
+ return overrides[key];
10
+ const value = Reflect.get(object, key, object);
11
+ return typeof value === 'function' ? value.bind(object) : value;
12
+ },
13
+ });
14
+ }
15
+ export function createSyncProfiler(options = {}) {
16
+ if (!developmentBuild())
17
+ throw new ClientSyncError('client.profiler_in_production', 'createSyncProfiler requires a development or test build');
18
+ const now = options.now ?? (() => performance.now());
19
+ const burstWindowMs = options.burstWindowMs ?? 16;
20
+ const channel = options.channel;
21
+ const source = Math.random().toString(36).slice(2);
22
+ let queries = new Map();
23
+ // Per query: the canonical rows of its last run and the change sequence it saw.
24
+ let queryState = new Map();
25
+ let statements = new Map();
26
+ let rounds = [];
27
+ let deltas = { count: 0, bytes: 0 };
28
+ let units = { active: 0, peak: 0 };
29
+ let bootstraps = new Map();
30
+ let writes = {
31
+ mutateCalls: 0,
32
+ operations: 0,
33
+ bursts: [],
34
+ };
35
+ let burst;
36
+ let changeSeq = 0;
37
+ const changedAt = new Map();
38
+ const remote = new Map();
39
+ let posting = false;
40
+ const clear = () => {
41
+ queries = new Map();
42
+ queryState = new Map();
43
+ statements = new Map();
44
+ rounds = [];
45
+ deltas = { count: 0, bytes: 0 };
46
+ units = { active: units.active, peak: units.active };
47
+ bootstraps = new Map();
48
+ writes = { mutateCalls: 0, operations: 0, bursts: [] };
49
+ burst = undefined;
50
+ remote.clear();
51
+ };
52
+ const post = () => {
53
+ if (channel === undefined || posting)
54
+ return;
55
+ posting = true;
56
+ queueMicrotask(() => {
57
+ posting = false;
58
+ channel.postMessage({
59
+ syncularProfile: source,
60
+ statements: [...statements.values()],
61
+ rounds,
62
+ });
63
+ });
64
+ };
65
+ if (channel !== undefined)
66
+ channel.onmessage = (event) => {
67
+ const data = event.data;
68
+ if (data?.syncularProfileReset === true)
69
+ clear();
70
+ else if (typeof data?.syncularProfile === 'string')
71
+ remote.set(data.syncularProfile, {
72
+ statements: data.statements,
73
+ rounds: data.rounds,
74
+ });
75
+ };
76
+ const round = (entry) => {
77
+ rounds.push(entry);
78
+ if (rounds.length > 256)
79
+ rounds.shift();
80
+ post();
81
+ return entry;
82
+ };
83
+ const statement = (run) => (sql, params) => {
84
+ const startedAt = now();
85
+ const result = run(sql, params);
86
+ const ms = now() - startedAt;
87
+ const entry = statements.get(sql) ??
88
+ statements
89
+ .set(sql, { sql, runs: 0, totalMs: 0, maxMs: 0, rows: 0 })
90
+ .get(sql);
91
+ entry.runs += 1;
92
+ entry.totalMs += ms;
93
+ entry.maxMs = Math.max(entry.maxMs, ms);
94
+ if (Array.isArray(result))
95
+ entry.rows += result.length;
96
+ post();
97
+ return result;
98
+ };
99
+ return {
100
+ database: (database) => wrap(database, {
101
+ exec: statement((sql, params) => database.exec(sql, params)),
102
+ query: statement((sql, params) => database.query(sql, params)),
103
+ queryReadOnly: statement((sql, params) => database.queryReadOnly(sql, params)),
104
+ }),
105
+ transport: (transport) => async (request, signal) => {
106
+ const startedAt = now();
107
+ const response = await transport(request, signal);
108
+ round({
109
+ via: 'http',
110
+ requestBytes: request.length,
111
+ responseBytes: response.length,
112
+ ms: now() - startedAt,
113
+ });
114
+ return response;
115
+ },
116
+ realtime: (connector) => (handlers, clientId) => {
117
+ let open;
118
+ const socket = connector({
119
+ ...handlers,
120
+ onBinary: (bytes) => {
121
+ // §8.7: tag 0x00 is a delta, tag 0x01 a chunk of the open round.
122
+ if (bytes[0] === 0) {
123
+ deltas.count += 1;
124
+ deltas.bytes += bytes.length - 1;
125
+ }
126
+ else if (open !== undefined) {
127
+ open.responseBytes += bytes.length - 1;
128
+ open.ms = now() - open.startedAt;
129
+ post();
130
+ }
131
+ handlers.onBinary(bytes);
132
+ },
133
+ }, clientId);
134
+ const profiled = (opened) => wrap(opened, {
135
+ sendBytes: (bytes) => {
136
+ if (bytes[0] === 1) {
137
+ const startedAt = now();
138
+ open = Object.assign(round({
139
+ via: 'socket',
140
+ requestBytes: bytes.length - 1,
141
+ responseBytes: 0,
142
+ ms: 0,
143
+ }), { startedAt });
144
+ }
145
+ opened.sendBytes(bytes);
146
+ },
147
+ });
148
+ return socket instanceof Promise
149
+ ? socket.then(profiled)
150
+ : profiled(socket);
151
+ },
152
+ client: (client) => {
153
+ client.onChange((batch) => {
154
+ changeSeq += 1;
155
+ for (const change of batch.tables)
156
+ changedAt.set(change.table, changeSeq);
157
+ });
158
+ client.onDiagnostics((snapshot) => {
159
+ units.active = snapshot.activeUnits;
160
+ units.peak = Math.max(units.peak, snapshot.activeUnits);
161
+ });
162
+ client.onProgress((progress) => {
163
+ if (progress.unitId === undefined || progress.phase === 'request')
164
+ return;
165
+ let unit = bootstraps.get(progress.unitId);
166
+ if (unit === undefined) {
167
+ unit = {
168
+ unitId: progress.unitId,
169
+ table: progress.table,
170
+ bytes: 0,
171
+ rows: 0,
172
+ ms: 0,
173
+ startedAt: now(),
174
+ segment: undefined,
175
+ segmentBytes: 0,
176
+ segmentRows: 0,
177
+ };
178
+ bootstraps.set(progress.unitId, unit);
179
+ }
180
+ // A progress event repeats its segment's running totals; a new
181
+ // segment, or totals that went down, starts the next one.
182
+ if (progress.segmentId !== unit.segment ||
183
+ progress.bytesReceived < unit.segmentBytes ||
184
+ progress.rowsProcessed < unit.segmentRows) {
185
+ unit.bytes += unit.segmentBytes;
186
+ unit.rows += unit.segmentRows;
187
+ }
188
+ unit.segment = progress.segmentId;
189
+ unit.segmentBytes = progress.bytesReceived;
190
+ unit.segmentRows = progress.rowsProcessed;
191
+ unit.ms = now() - unit.startedAt;
192
+ });
193
+ const record = (spec, startedAt, seq, snapshot) => {
194
+ const id = spec.owner?.id ?? spec.sql;
195
+ const ms = now() - startedAt;
196
+ const query = queries.get(id) ??
197
+ queries
198
+ .set(id, {
199
+ id,
200
+ sql: spec.sql,
201
+ tables: spec.owner?.tables ?? [],
202
+ runs: 0,
203
+ identicalRuns: 0,
204
+ totalMs: 0,
205
+ maxMs: 0,
206
+ rows: 0,
207
+ triggers: {},
208
+ })
209
+ .get(id);
210
+ const previous = queryState.get(id);
211
+ const rows = canonicalValue(snapshot.rows);
212
+ const changed = query.tables.filter((table) => (changedAt.get(table) ?? 0) > (previous?.seq ?? 0));
213
+ const triggers = query.triggers;
214
+ for (const trigger of previous === undefined
215
+ ? ['mount']
216
+ : changed.length > 0
217
+ ? changed
218
+ : ['refresh'])
219
+ triggers[trigger] = (triggers[trigger] ?? 0) + 1;
220
+ if (previous?.rows === rows)
221
+ query.identicalRuns += 1;
222
+ queryState.set(id, { rows, seq });
223
+ query.runs += 1;
224
+ query.totalMs += ms;
225
+ query.maxMs = Math.max(query.maxMs, ms);
226
+ query.rows = snapshot.rows.length;
227
+ return snapshot;
228
+ };
229
+ return wrap(client, {
230
+ querySnapshot: (spec) => {
231
+ const startedAt = now();
232
+ const seq = changeSeq;
233
+ const snapshot = client.querySnapshot(spec);
234
+ return snapshot instanceof Promise
235
+ ? snapshot.then((value) => record(spec, startedAt, seq, value))
236
+ : record(spec, startedAt, seq, snapshot);
237
+ },
238
+ mutate: (mutations) => {
239
+ writes.mutateCalls += 1;
240
+ writes.operations += mutations.length;
241
+ const at = now();
242
+ if (mutations.length !== 1)
243
+ burst = undefined;
244
+ else if (burst !== undefined && at - burst.at <= burstWindowMs) {
245
+ burst.at = at;
246
+ burst.commits += 1;
247
+ if (!burst.tables.includes(mutations[0].table))
248
+ burst.tables.push(mutations[0].table);
249
+ if (burst.commits === 2)
250
+ writes.bursts.push(burst);
251
+ }
252
+ else
253
+ burst = { commits: 1, tables: [mutations[0].table], at };
254
+ return client.mutate(mutations);
255
+ },
256
+ });
257
+ },
258
+ report: () => {
259
+ const merged = new Map();
260
+ for (const list of [
261
+ [...statements.values()],
262
+ ...[...remote.values()].map((entry) => entry.statements),
263
+ ])
264
+ for (const entry of list) {
265
+ const into = merged.get(entry.sql);
266
+ if (into === undefined)
267
+ merged.set(entry.sql, { ...entry });
268
+ else {
269
+ into.runs += entry.runs;
270
+ into.totalMs += entry.totalMs;
271
+ into.maxMs = Math.max(into.maxMs, entry.maxMs);
272
+ into.rows += entry.rows;
273
+ }
274
+ }
275
+ return {
276
+ queries: [...queries.values()].map((query) => ({
277
+ ...query,
278
+ triggers: { ...query.triggers },
279
+ })),
280
+ statements: [...merged.values()],
281
+ rounds: [
282
+ ...[...remote.values()].flatMap((entry) => entry.rounds),
283
+ ...rounds,
284
+ ].map((entry) => ({
285
+ via: entry.via,
286
+ requestBytes: entry.requestBytes,
287
+ responseBytes: entry.responseBytes,
288
+ ms: entry.ms,
289
+ })),
290
+ deltas: { ...deltas },
291
+ units: {
292
+ ...units,
293
+ limit: options.unitLimit ?? 500,
294
+ bootstraps: [...bootstraps.values()].map((unit) => ({
295
+ unitId: unit.unitId,
296
+ table: unit.table,
297
+ bytes: unit.bytes + unit.segmentBytes,
298
+ rows: unit.rows + unit.segmentRows,
299
+ ms: unit.ms,
300
+ })),
301
+ },
302
+ writes: {
303
+ ...writes,
304
+ bursts: writes.bursts.map((entry) => ({
305
+ commits: entry.commits,
306
+ tables: [...entry.tables],
307
+ })),
308
+ },
309
+ };
310
+ },
311
+ reset: () => {
312
+ clear();
313
+ channel?.postMessage({ syncularProfileReset: true });
314
+ },
315
+ };
316
+ }
317
+ /**
318
+ * Throws `client.profile_budget_exceeded` listing every budget the report
319
+ * exceeds, with `budget`, `limit` and `measured` per entry in `details.exceeded`.
320
+ */
321
+ export function assertBudgets(report, budgets) {
322
+ const measured = {
323
+ maxActiveUnits: report.units.peak,
324
+ maxRoundBytes: Math.max(0, ...report.rounds.map((entry) => entry.requestBytes + entry.responseBytes)),
325
+ maxRunsPerQuery: Math.max(0, ...report.queries.map((query) => query.runs)),
326
+ maxIdenticalRuns: report.queries.reduce((sum, query) => sum + query.identicalRuns, 0),
327
+ maxWriteBurst: Math.max(0, ...report.writes.bursts.map((entry) => entry.commits)),
328
+ };
329
+ const exceeded = Object.entries(budgets)
330
+ .filter(([budget, limit]) => measured[budget] > limit)
331
+ .map(([budget, limit]) => ({
332
+ budget,
333
+ limit,
334
+ measured: measured[budget],
335
+ }));
336
+ if (exceeded.length > 0)
337
+ throw new ClientSyncError('client.profile_budget_exceeded', 'the profile report exceeds its budgets', false, { exceeded });
338
+ }
@@ -43,6 +43,11 @@ export interface DevtoolsEntry extends DevtoolsRegistration {
43
43
  readonly scopeKeys: readonly string[];
44
44
  };
45
45
  }
46
+ /**
47
+ * @internal True when the build carries a development or test signal and no
48
+ * production one. The registry and `@syncular/client/dev` read it.
49
+ */
50
+ export declare function developmentBuild(): boolean;
46
51
  /**
47
52
  * Register a client on the page registry. Returns the unregister function
48
53
  * (a no-op when the registry is gated off) — call it from `close()`.
package/dist/devtools.js CHANGED
@@ -1,18 +1,21 @@
1
1
  const KEY = '__SYNCULAR__';
2
- /** The page global to install on, or undefined when gated off. */
3
- function registryHost() {
4
- const g = globalThis;
5
- if (g.window === undefined)
6
- return undefined;
2
+ /**
3
+ * @internal True when the build carries a development or test signal and no
4
+ * production one. The registry and `@syncular/client/dev` read it.
5
+ */
6
+ export function developmentBuild() {
7
7
  if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production')
8
- return undefined;
9
- if (!((typeof import.meta.env !== 'undefined' &&
8
+ return false;
9
+ return ((typeof import.meta.env !== 'undefined' &&
10
10
  import.meta.env.DEV === true) ||
11
11
  (typeof process !== 'undefined' &&
12
12
  (process.env.NODE_ENV === 'development' ||
13
- process.env.NODE_ENV === 'test'))))
14
- return undefined;
15
- return g;
13
+ process.env.NODE_ENV === 'test')));
14
+ }
15
+ /** The page global to install on, or undefined when gated off. */
16
+ function registryHost() {
17
+ const g = globalThis;
18
+ return g.window !== undefined && developmentBuild() ? g : undefined;
16
19
  }
17
20
  function registryOn(host) {
18
21
  const existing = host[KEY];
@@ -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,