@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
@@ -39,6 +39,7 @@ import {
39
39
  STORAGE_FENCED_CODE,
40
40
  STORAGE_UNAVAILABLE_CODE,
41
41
  } from './errors';
42
+ import { prepareReadOnly } from './query-guard';
42
43
 
43
44
  /** Structural view of the sqlite3 oo1 surface this binding uses. */
44
45
  interface Oo1Database {
@@ -50,9 +51,24 @@ interface Oo1Database {
50
51
  rowMode: 'object';
51
52
  resultRows: unknown[];
52
53
  }): unknown;
54
+ prepare(sql: string): Oo1Statement;
53
55
  close(): void;
54
56
  }
55
57
 
58
+ interface Oo1Statement {
59
+ readonly pointer?: number;
60
+ readonly columnCount: number;
61
+ isReadOnly(): boolean;
62
+ finalize(): unknown;
63
+ bind(values: readonly unknown[]): unknown;
64
+ step(): boolean;
65
+ get(target: Record<string, unknown>): Record<string, unknown>;
66
+ reset(clearBindings: boolean): unknown;
67
+ }
68
+
69
+ /** Compiled statements one database keeps; a full cache is finalized and cleared. */
70
+ const STATEMENT_CACHE_LIMIT = 128;
71
+
56
72
  interface SahPoolUtil {
57
73
  OpfsSAHPoolDb: new (filename: string) => Oo1Database;
58
74
  /** RFC 0005: the runtime exposes naming and removal on the pool util. */
@@ -77,6 +93,7 @@ interface Sqlite3Static {
77
93
  SQLITE_DESERIALIZE_FREEONCLOSE: number;
78
94
  SQLITE_DESERIALIZE_READONLY: number;
79
95
  SQLITE_FCNTL_FILE_POINTER: number;
96
+ sqlite3_sql(statement: number | undefined): string;
80
97
  sqlite3_file_control(
81
98
  db: number,
82
99
  schema: string,
@@ -128,7 +145,7 @@ function coerceParams(params: readonly SqlValue[]): unknown[] {
128
145
  */
129
146
  interface StorageFence {
130
147
  fenced: boolean;
131
- readonly siblings: Set<Oo1Database>;
148
+ readonly siblings: Set<WasmClientDatabase>;
132
149
  }
133
150
 
134
151
  class WasmClientDatabase implements ClientDatabase {
@@ -139,6 +156,7 @@ class WasmClientDatabase implements ClientDatabase {
139
156
  | { readonly util: SahPoolUtil; readonly lease: LeaderLease }
140
157
  | undefined;
141
158
  readonly #fence: StorageFence | undefined;
159
+ readonly #statements = new Map<string, Oo1Statement>();
142
160
  #closed = false;
143
161
  #tx = { depth: 0 };
144
162
 
@@ -159,7 +177,6 @@ class WasmClientDatabase implements ClientDatabase {
159
177
  if (fence === undefined || this.#closed) return;
160
178
  fence.fenced = true;
161
179
  for (const sibling of fence.siblings) sibling.close();
162
- fence.siblings.clear();
163
180
  this.close();
164
181
  });
165
182
  }
@@ -174,25 +191,55 @@ class WasmClientDatabase implements ClientDatabase {
174
191
  }
175
192
 
176
193
  exec(sql: string, params: readonly SqlValue[] = []): void {
177
- this.#assertOwned();
178
- this.#db.exec({
179
- sql,
180
- ...(params.length > 0 ? { bind: coerceParams(params) } : {}),
181
- rowMode: 'object',
182
- resultRows: [],
183
- });
194
+ this.query(sql, params);
184
195
  }
185
196
 
197
+ /**
198
+ * Parameterized SQL (one statement per call, the `ClientDatabase` contract)
199
+ * runs through a compiled statement cached by its SQL text. SQL without
200
+ * parameters may hold several statements and compiles through `exec`.
201
+ */
186
202
  query(sql: string, params: readonly SqlValue[] = []): SqlRow[] {
187
203
  this.#assertOwned();
188
- const resultRows: unknown[] = [];
189
- this.#db.exec({
190
- sql,
191
- ...(params.length > 0 ? { bind: coerceParams(params) } : {}),
192
- rowMode: 'object',
193
- resultRows,
204
+ if (params.length === 0) {
205
+ const resultRows: unknown[] = [];
206
+ this.#db.exec({ sql, rowMode: 'object', resultRows });
207
+ return resultRows as SqlRow[];
208
+ }
209
+ let statement = this.#statements.get(sql);
210
+ if (statement === undefined) {
211
+ statement = this.#db.prepare(sql);
212
+ if (this.#statements.size === STATEMENT_CACHE_LIMIT) {
213
+ this.#statements.forEach((evicted) => evicted.finalize());
214
+ this.#statements.clear();
215
+ }
216
+ this.#statements.set(sql, statement);
217
+ }
218
+ const rows: SqlRow[] = [];
219
+ try {
220
+ statement.bind(coerceParams(params));
221
+ while (statement.step()) rows.push(statement.get({}) as SqlRow);
222
+ } finally {
223
+ statement.reset(true);
224
+ }
225
+ return rows;
226
+ }
227
+
228
+ queryReadOnly(sql: string, params: readonly SqlValue[] = []): SqlRow[] {
229
+ this.#assertOwned();
230
+ prepareReadOnly(sql, () => {
231
+ const statement = this.#db.prepare(sql);
232
+ try {
233
+ return [
234
+ undefined,
235
+ this.#sqlite3.capi.sqlite3_sql(statement.pointer),
236
+ statement.isReadOnly() && statement.columnCount > 0,
237
+ ] as const;
238
+ } finally {
239
+ statement.finalize();
240
+ }
194
241
  });
195
- return resultRows as SqlRow[];
242
+ return this.query(sql, params);
196
243
  }
197
244
 
198
245
  transaction<T>(fn: () => T): T {
@@ -218,18 +265,16 @@ class WasmClientDatabase implements ClientDatabase {
218
265
  db.close();
219
266
  throw error;
220
267
  }
221
- this.#fence?.siblings.add(db);
268
+ const database = new WasmClientDatabase(
269
+ db,
270
+ this.#sqlite3,
271
+ undefined,
272
+ this.#fence,
273
+ );
274
+ this.#fence?.siblings.add(database);
222
275
  return {
223
- database: new WasmClientDatabase(
224
- db,
225
- this.#sqlite3,
226
- undefined,
227
- this.#fence,
228
- ),
229
- close: () => {
230
- this.#fence?.siblings.delete(db);
231
- db.close();
232
- },
276
+ database,
277
+ close: () => database.close(),
233
278
  removeFile: () => {
234
279
  sah.util.unlink(fileName);
235
280
  },
@@ -287,6 +332,10 @@ class WasmClientDatabase implements ClientDatabase {
287
332
 
288
333
  close(): void {
289
334
  if (this.#closed) return;
335
+ this.#fence?.siblings.delete(this);
336
+ // oo1 DB.close() does not finalize prepared statements, and an open one
337
+ // keeps the database file open, so pauseVfs() below would throw.
338
+ this.#statements.forEach((statement) => statement.finalize());
290
339
  this.#db.close();
291
340
  // DB.close() leaves the SAH pool live. Close siblings first, then pause the
292
341
  // VFS without deleting files, before releasing this worker's physical lock.
package/src/window.ts CHANGED
@@ -1,20 +1,22 @@
1
- export const PENDING_EVICTIONS = '_syncular_window_pending_evict';
1
+ export const PENDING_EVICTIONS = '_syncular_pending_evictions';
2
2
  export const WINDOWS_TABLE = '_syncular_windows';
3
3
  /**
4
- * Windowed subscriptions (SPEC.md §4.8).
4
+ * Windows (SPEC.md §4.8).
5
5
  *
6
6
  * A window is a partial local replica keyed by scope VALUES: the client
7
- * holds rows for a chosen set of units (one scope value each) of a window
8
- * BASE (a table + one scope variable + the fixed remainder of the scope
9
- * map). Windowing is a set-difference on §4 subscriptions — never a
10
- * mutation of one — so it needs zero wire or server changes.
7
+ * holds the units of a chosen set of values of a window BASE (one scope
8
+ * variable plus fixed values). Windowing is a set difference on §4.1 units,
9
+ * never a mutation of one, so it needs no wire or server change.
11
10
  *
12
- * This module owns the registry bookkeeping and the deterministic
13
- * per-unit subscription-id derivation (§4.1 guidance). The eviction that
14
- * fuses with a shrink (E1–E4) lives on the client, which holds the DB
15
- * transaction and the invalidation choke point.
11
+ * This module owns the registry bookkeeping. The eviction that fuses with a
12
+ * shrink (E1–E4) lives on the client, which holds the DB transaction and the
13
+ * invalidation choke point.
16
14
  */
17
- import { canonicalScopeJson, type ScopeMap } from '@syncular/core';
15
+ import {
16
+ canonicalUnitJson,
17
+ type ScopeMap,
18
+ type UnitScopes,
19
+ } from '@syncular/core';
18
20
  import type { ClientDatabase } from './database';
19
21
  import { invalidRequest } from './errors';
20
22
 
@@ -80,173 +82,92 @@ export function last(
80
82
  }
81
83
 
82
84
  /**
83
- * A window base: one table, one variable whose values are the window
84
- * units, and any FIXED scopes every unit shares (other variables pinned
85
- * to a constant set). `params` is host-opaque, carried onto every unit's
86
- * subscription verbatim.
85
+ * A window base (§4.8): the selected scope variable plus the fixed scope
86
+ * values every unit of its family shares. A base names no table: each unit
87
+ * covers every table declaring its variables (§4.1).
87
88
  */
88
89
  export interface WindowBase {
89
- readonly table: string;
90
90
  /** The scope variable whose values are the window units. */
91
91
  readonly variable: string;
92
- /** Scopes shared by every unit (other variables), if any. */
93
- readonly fixedScopes?: Readonly<Record<string, readonly string[]>>;
94
- readonly params?: string;
95
- }
96
-
97
- /** A live unit in the registry: its value and the subscription it drives. */
98
- export interface WindowUnit {
99
- readonly unit: string;
100
- readonly subId: string;
101
- }
102
-
103
- export interface RegisteredWindowUnit extends WindowUnit {
104
- readonly baseKey: string;
92
+ /** One value per other variable, shared by every unit. */
93
+ readonly fixedScopes?: UnitScopes;
105
94
  }
106
95
 
107
- /**
108
- * A stable, server-opaque key for a window base — table + variable +
109
- * canonical fixed scopes. Two `setWindow` calls with the same base
110
- * address the same registry rows.
111
- */
96
+ /** A stable key for a window base: variable + canonical fixed scopes. */
112
97
  export function windowBaseKey(base: WindowBase): string {
113
- const fixed = canonicalScopeJson(base.fixedScopes ?? {});
114
- return `${base.table}\0${base.variable}\0${fixed}`;
115
- }
116
-
117
- /** The full requested scope map for one unit (fixed scopes + the unit). */
118
- export function unitScopes(base: WindowBase, unit: string): ScopeMap {
119
- const scopes: ScopeMap = {};
120
- for (const [variable, values] of Object.entries(base.fixedScopes ?? {})) {
121
- scopes[variable] = [...values];
122
- }
123
- scopes[base.variable] = [unit];
124
- return scopes;
98
+ return `${base.variable}\0${canonicalUnitJson(base.fixedScopes ?? {})}`;
125
99
  }
126
100
 
127
- /**
128
- * Deterministic per-unit subscription id (§4.1 guidance):
129
- * `w:<table>:<sha256(canonical scope map, §11.2)[0..16]>`. Ids are echoed
130
- * not interpreted by the server (§4.1), so the exact hash is pure client
131
- * convention; SHA-256 matches the SPEC's worked example.
132
- */
133
- export async function deriveSubId(
134
- base: WindowBase,
135
- unit: string,
136
- ): Promise<string> {
137
- const canonical = canonicalScopeJson(unitScopes(base, unit));
138
- const digest = await crypto.subtle.digest(
139
- 'SHA-256',
140
- new TextEncoder().encode(canonical),
141
- );
142
- let hex = '';
143
- for (const byte of new Uint8Array(digest)) {
144
- hex += byte.toString(16).padStart(2, '0');
145
- }
146
- return `w:${base.table}:${hex.slice(0, 16)}`;
101
+ /** The unit of one window value: the fixed scopes plus the value. */
102
+ export function windowUnitScopes(base: WindowBase, value: string): UnitScopes {
103
+ return { ...base.fixedScopes, [base.variable]: value };
147
104
  }
148
105
 
149
- /** Live units for a base, ordered by unit value. */
106
+ /** Registry rows for a base, ordered by value: value → unit id. */
150
107
  export function loadWindowUnits(
151
108
  db: ClientDatabase,
152
109
  baseKey: string,
153
- ): WindowUnit[] {
110
+ ): { readonly value: string; readonly unitId: string }[] {
154
111
  return db
155
112
  .query(
156
113
  `SELECT unit,sub_id FROM ${WINDOWS_TABLE} WHERE base=? ORDER BY unit`,
157
114
  [baseKey],
158
115
  )
159
- .map((row) => ({ unit: row.unit as string, subId: row.sub_id as string }));
160
- }
161
-
162
- /** Registry lookup used to emit exact completion changes for a sub id. */
163
- export function getWindowUnitBySubId(
164
- db: ClientDatabase,
165
- subId: string,
166
- ): RegisteredWindowUnit | undefined {
167
- const row = db.query(
168
- `SELECT base, unit, sub_id FROM ${WINDOWS_TABLE}
169
- WHERE sub_id = ? LIMIT 1`,
170
- [subId],
171
- )[0];
172
- return row === undefined
173
- ? undefined
174
- : {
175
- baseKey: row.base as string,
176
- unit: row.unit as string,
177
- subId: row.sub_id as string,
178
- };
179
- }
180
-
181
- export function insertWindowUnit(
182
- db: ClientDatabase,
183
- baseKey: string,
184
- unit: string,
185
- subId: string,
186
- ): void {
187
- db.exec(
188
- `INSERT OR REPLACE INTO ${WINDOWS_TABLE}(base,unit,sub_id)VALUES(?,?,?)`,
189
- [baseKey, unit, subId],
190
- );
191
- }
192
-
193
- export function deleteWindowUnit(
194
- db: ClientDatabase,
195
- baseKey: string,
196
- unit: string,
197
- ): void {
198
- db.exec(`DELETE FROM ${WINDOWS_TABLE} WHERE base=? AND unit=?`, [
199
- baseKey,
200
- unit,
201
- ]);
116
+ .map((row) => ({
117
+ value: row.unit as string,
118
+ unitId: row.sub_id as string,
119
+ }));
202
120
  }
203
121
 
204
- /** Is a single scope value windowed-in for this base? (the oracle, I3) */
205
- export function isUnitLive(
122
+ /** Every window registry row that references a unit (§4.1 references). */
123
+ export function windowRefs(
206
124
  db: ClientDatabase,
207
- baseKey: string,
208
- unit: string,
209
- ): boolean {
210
- return (
211
- db.query(`SELECT 1 FROM ${WINDOWS_TABLE} WHERE base=? AND unit=? LIMIT 1`, [
212
- baseKey,
213
- unit,
214
- ]).length > 0
215
- );
125
+ unitId: string,
126
+ ): { readonly baseKey: string; readonly value: string }[] {
127
+ return db
128
+ .query(`SELECT base,unit FROM ${WINDOWS_TABLE} WHERE sub_id=?`, [unitId])
129
+ .map((row) => ({
130
+ baseKey: row.base as string,
131
+ value: row.unit as string,
132
+ }));
216
133
  }
217
134
 
218
135
  // ---------------------------------------------------------------------------
219
- // Deferred eviction (E1) — units that left the window with pinned rows
136
+ // Deferred eviction (E1): per-table scopes of units that left with rows left
220
137
  // ---------------------------------------------------------------------------
221
138
 
222
139
  export interface PendingEviction {
223
- readonly subId: string;
140
+ readonly unitId: string;
224
141
  readonly table: string;
225
142
  readonly effective: ScopeMap;
226
143
  }
227
144
 
228
145
  export function savePendingEviction(
229
146
  db: ClientDatabase,
230
- subId: string,
231
- table: string,
232
- effective: ScopeMap,
147
+ entry: PendingEviction,
233
148
  ): void {
234
149
  db.exec(
235
- `INSERT OR REPLACE INTO ${PENDING_EVICTIONS}(sub_id, tbl, effective_scopes)
236
- VALUES (?, ?, ?)`,
237
- [subId, table, JSON.stringify(effective)],
150
+ `INSERT OR REPLACE INTO ${PENDING_EVICTIONS}(unit_id,tbl,effective_scopes)VALUES(?,?,?)`,
151
+ [entry.unitId, entry.table, JSON.stringify(entry.effective)],
238
152
  );
239
153
  }
240
154
 
241
- export function deletePendingEviction(db: ClientDatabase, subId: string): void {
242
- db.exec(`DELETE FROM ${PENDING_EVICTIONS} WHERE sub_id = ?`, [subId]);
155
+ export function deletePendingEviction(
156
+ db: ClientDatabase,
157
+ unitId: string,
158
+ table?: string,
159
+ ): void {
160
+ db.exec(
161
+ `DELETE FROM ${PENDING_EVICTIONS} WHERE unit_id=?${table === undefined ? '' : ' AND tbl=?'}`,
162
+ table === undefined ? [unitId] : [unitId, table],
163
+ );
243
164
  }
244
165
 
245
166
  export function loadPendingEvictions(db: ClientDatabase): PendingEviction[] {
246
167
  return db
247
- .query(`SELECT sub_id, tbl, effective_scopes FROM ${PENDING_EVICTIONS}`)
168
+ .query(`SELECT unit_id,tbl,effective_scopes FROM ${PENDING_EVICTIONS}`)
248
169
  .map((row) => ({
249
- subId: row.sub_id as string,
170
+ unitId: row.unit_id as string,
250
171
  table: row.tbl as string,
251
172
  effective: JSON.parse(row.effective_scopes as string) as ScopeMap,
252
173
  }));