@syncular/client 0.48.0 → 0.49.2

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.
@@ -37,6 +37,10 @@ export declare const NOT_LEADER_CODE = "client.not_leader";
37
37
  export declare const WORKER_FAILED_CODE = "client.worker_failed";
38
38
  /** A page/worker bundle identity changed and a full host reload is required. */
39
39
  export declare const WORKER_RESTART_REQUIRED_CODE = "client.worker_restart_required";
40
+ /** SPEC §12: local-authority use without `startSyncWorker({ openLocalAuthority })`. */
41
+ export declare const LOCAL_AUTHORITY_UNCONFIGURED_CODE = "client.local_authority_unconfigured";
42
+ /** SPEC §12.3 local-authority state. */
43
+ export type LocalAuthorityState = 'local' | 'attaching' | 'attached';
40
44
  export type WorkerDatabaseInit = {
41
45
  /** Reload-persistent OPFS mode; origin eviction policy stays page-owned. */
42
46
  readonly mode: 'persistent';
@@ -76,10 +80,22 @@ export interface WorkerInitConfig {
76
80
  readonly headers?: Readonly<Record<string, string>>;
77
81
  /** Portable raw keyring installed inside the worker-owned client core. */
78
82
  readonly encryption?: EncryptionKeyringConfig;
83
+ /**
84
+ * This tab took the lock from an unreachable leader: take the storage lock
85
+ * from that leader's worker, which fences its database, and retry the open
86
+ * while its OPFS handles drain.
87
+ */
88
+ readonly takeOverStorage?: boolean;
79
89
  /** Open the worker-owned replica behind the fail-closed security gate. */
80
90
  readonly authorityReads?: readonly import('./authority.js').AuthorityReadDeclaration[];
81
91
  readonly securityPreflight?: boolean;
82
92
  readonly transportEnabled?: boolean;
93
+ /**
94
+ * SPEC §12: sync against a local authority in a sibling file until
95
+ * `attachLocalAuthority` moves its rows to `endpoints.syncUrl`. Requires
96
+ * `startSyncWorker({ openLocalAuthority })`.
97
+ */
98
+ readonly localAuthority?: boolean;
83
99
  readonly clientId?: string;
84
100
  readonly limits?: SyncClientLimits;
85
101
  readonly retainFailedCommits?: boolean;
@@ -163,6 +179,12 @@ export interface WorkerApi extends Omit<ClientSnapshotMethods, 'querySnapshot'>
163
179
  setHeaders(headers: Readonly<Record<string, string>>): void;
164
180
  /** Sever/restore the transport + realtime (offline simulation, demos). */
165
181
  setOffline(offline: boolean): void;
182
+ /** SPEC §12.3 state; `undefined` when init did not enable the local authority. */
183
+ localAuthorityState(): LocalAuthorityState | undefined;
184
+ /** SPEC §12.3: upload the local authority's rows to `endpoints.syncUrl`. */
185
+ attachLocalAuthority(): Promise<void>;
186
+ /** SPEC §12.3: roll back a stopped attach and sync locally again. */
187
+ abandonLocalAuthorityAttach(): Promise<void>;
166
188
  close(): Promise<void>;
167
189
  }
168
190
  export type WorkerMethod = keyof WorkerApi;
@@ -7,3 +7,5 @@ export const NOT_LEADER_CODE = 'client.not_leader';
7
7
  export const WORKER_FAILED_CODE = 'client.worker_failed';
8
8
  /** A page/worker bundle identity changed and a full host reload is required. */
9
9
  export const WORKER_RESTART_REQUIRED_CODE = 'client.worker_restart_required';
10
+ /** SPEC §12: local-authority use without `startSyncWorker({ openLocalAuthority })`. */
11
+ export const LOCAL_AUTHORITY_UNCONFIGURED_CODE = 'client.local_authority_unconfigured';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/client",
3
- "version": "0.48.0",
3
+ "version": "0.49.2",
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",
@@ -97,10 +97,10 @@
97
97
  },
98
98
  "dependencies": {
99
99
  "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
100
- "@syncular/core": "0.48.0"
100
+ "@syncular/core": "0.49.2"
101
101
  },
102
102
  "devDependencies": {
103
- "@syncular/server": "0.48.0",
103
+ "@syncular/server": "0.49.2",
104
104
  "playwright": "1.63.0",
105
105
  "@electric-sql/pglite": "^0.5.4"
106
106
  }
@@ -11,7 +11,8 @@ export type SyncAvailability =
11
11
  | 'server-behind'
12
12
  | 'incompatible-schema'
13
13
  | 'leader-unreachable'
14
- | 'leader-incompatible';
14
+ | 'leader-incompatible'
15
+ | 'leadership-taken';
15
16
  readonly currentSchemaVersion: number;
16
17
  /** `leader-incompatible`: whether the tab holding the database runs an
17
18
  * older or a newer build than this one. */
@@ -36,7 +37,7 @@ export function blockedLeadershipAvailability(
36
37
  }
37
38
  : {
38
39
  state: 'blocked',
39
- reason: 'leader-unreachable',
40
+ reason: leadership.reason,
40
41
  currentSchemaVersion,
41
42
  retryable: true,
42
43
  };
package/src/client.ts CHANGED
@@ -3333,12 +3333,21 @@ export class SyncClient {
3333
3333
  legacyCause: `sync.invalid_request: table ${table.name}: ${refusal}`,
3334
3334
  },
3335
3335
  );
3336
+ // §7.1 insert intent: a full-row write of a row the replica does not
3337
+ // show replays and encodes as a full row under every later schema.
3338
+ const insert =
3339
+ mutation.op !== 'patch' &&
3340
+ this.#db.query(
3341
+ `SELECT 1 FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=? LIMIT 1`,
3342
+ [pkSqlValue(table, pkValue)],
3343
+ ).length === 0;
3336
3344
  return definedObject({
3337
3345
  table: mutation.table,
3338
3346
  rowId: pkValue,
3339
3347
  op: 'upsert',
3340
3348
  baseVersion: mutation.baseVersion,
3341
3349
  values: json,
3350
+ insert: insert ? true : undefined,
3342
3351
  });
3343
3352
  });
3344
3353
  this.#applyBatch((batch) => {
@@ -6207,9 +6216,23 @@ export class SyncClient {
6207
6216
  // §7.1 overlay: apply the operation's PRESENT columns over the current
6208
6217
  // local row. A partial operation over an absent local row leaves it
6209
6218
  // absent — the server answers it with sync.row_deleted or
6210
- // sync.row_missing, and the local mirror never invents a base.
6219
+ // sync.row_missing, and the local mirror never invents a base. An
6220
+ // insert-intent operation is a full row: a column it lacks is NULL.
6211
6221
  const opValues = op.values ?? {};
6212
- const full = table.columns.every((column) => column.name in opValues);
6222
+ const full =
6223
+ op.insert === true ||
6224
+ table.columns.every((column) => column.name in opValues);
6225
+ // An insert lacking a non-nullable column cannot encode (§7.4.4); it
6226
+ // stays hidden until the send-time drop classifies it.
6227
+ if (
6228
+ op.insert === true &&
6229
+ table.columns.some(
6230
+ (column) => !column.nullable && opValues[column.name] === undefined,
6231
+ )
6232
+ ) {
6233
+ if (batch !== undefined && !precise) batch.table(op.table);
6234
+ continue;
6235
+ }
6213
6236
  const local = this.#db.query(
6214
6237
  `SELECT * FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(table.primaryKey)}=?`,
6215
6238
  [pkSqlValue(table, op.rowId)],
@@ -6221,7 +6244,7 @@ export class SyncClient {
6221
6244
  const values = table.columns.map((column) => {
6222
6245
  const value = opValues[column.name];
6223
6246
  if (value !== undefined) return jsonToRowValue(value);
6224
- return local === undefined
6247
+ return local === undefined || op.insert === true
6225
6248
  ? null
6226
6249
  : replay
6227
6250
  ? (coerceSqlRepresentation(
package/src/errors.ts CHANGED
@@ -3,6 +3,12 @@ import type { RealtimeState } from './diagnostics';
3
3
  /** A persistent local store is temporarily owned by another live engine. */
4
4
  export const STORAGE_BUSY_CODE = 'client.storage_busy';
5
5
 
6
+ /**
7
+ * Another tab took this engine's persistent store with `takeOver()`; the
8
+ * engine closed the store and refuses every further statement.
9
+ */
10
+ export const STORAGE_FENCED_CODE = 'client.storage_fenced';
11
+
6
12
  /** The browser cannot provide the persistent storage APIs Syncular requires. */
7
13
  export const STORAGE_UNAVAILABLE_CODE = 'client.storage_unavailable';
8
14
 
@@ -1,11 +1,16 @@
1
1
  /**
2
2
  * Multi-tab ownership seam: exactly one core instance owns the
3
- * local database. The interface is the whole B3 deliverable — cross-tab
4
- * follower fanout is post-gate. Browsers use Web Locks; tests use the
5
- * no-op single-owner lock.
3
+ * local database. Browsers use Web Locks; tests use the no-op single-owner
4
+ * lock or an injected exclusive lock.
6
5
  */
7
6
  export interface LeaderLease {
8
7
  release(): void | Promise<void>;
8
+ /**
9
+ * Resolves when another context took this lease with
10
+ * {@link LeaderLock.steal}. The holder no longer owns the lock and must stop
11
+ * writing. Absent for locks that cannot be stolen.
12
+ */
13
+ readonly lost?: Promise<void>;
9
14
  }
10
15
 
11
16
  export interface LeaderLock {
@@ -14,10 +19,14 @@ export interface LeaderLock {
14
19
  /**
15
20
  * Resolves immediately: the lease when leadership was free, `undefined`
16
21
  * when another owner holds it. The worker handle uses this so a second
17
- * tab gets a clear not-leader state instead of blocking forever
18
- * (followers are post-gate).
22
+ * tab gets a clear not-leader state instead of blocking forever.
19
23
  */
20
24
  tryAcquire?(name: string): Promise<LeaderLease | undefined>;
25
+ /**
26
+ * Takes `name` from its current holder at once; the holder's lease reports
27
+ * `lost`. Waiting requests stay queued behind the new holder.
28
+ */
29
+ steal?(name: string): Promise<LeaderLease>;
21
30
  }
22
31
 
23
32
  /** Single-owner environments (tests, dedicated workers): always leader. */
@@ -31,38 +40,59 @@ export function singleOwnerLock(): LeaderLock {
31
40
  /**
32
41
  * Web Locks leader election: resolves once the exclusive lock is granted
33
42
  * and holds it until the lease is released (tab close releases it
34
- * implicitly, letting the next tab take over).
43
+ * implicitly, letting the next tab take over). A `steal` from another
44
+ * context rejects the holder's request with `AbortError`, which resolves the
45
+ * holder's `lost`.
35
46
  */
36
- export function webLocksLeaderLock(locks?: LockManager): LeaderLock {
47
+ export function webLocksLeaderLock(locks?: LockManager): Required<LeaderLock> {
37
48
  const manager = locks ?? navigator.locks;
49
+ const request = (
50
+ name: string,
51
+ options: LockOptions,
52
+ ): Promise<LeaderLease | undefined> =>
53
+ new Promise((resolveRequest, rejectRequest) => {
54
+ let granted = false;
55
+ let markLost = (): void => {};
56
+ const lost = new Promise<void>((resolve) => {
57
+ markLost = resolve;
58
+ });
59
+ manager
60
+ .request(name, options, (lock) => {
61
+ // `ifAvailable` grants `null` instead of waiting (Web Locks).
62
+ if (lock === null) {
63
+ resolveRequest(undefined);
64
+ return undefined;
65
+ }
66
+ granted = true;
67
+ return new Promise<void>((resolveHold) => {
68
+ resolveRequest({ release: () => resolveHold(), lost });
69
+ });
70
+ })
71
+ .catch((error: unknown) => {
72
+ if (
73
+ granted &&
74
+ error instanceof DOMException &&
75
+ error.name === 'AbortError'
76
+ ) {
77
+ markLost();
78
+ return;
79
+ }
80
+ rejectRequest(error);
81
+ });
82
+ });
83
+ const held = async (
84
+ name: string,
85
+ options: LockOptions,
86
+ ): Promise<LeaderLease> => {
87
+ const lease = await request(name, options);
88
+ if (lease === undefined)
89
+ throw new Error('a waiting lock request returned no lock');
90
+ return lease;
91
+ };
38
92
  return {
39
- acquire: (name) =>
40
- new Promise<LeaderLease>((resolveAcquire, rejectAcquire) => {
41
- manager
42
- .request(
43
- name,
44
- { mode: 'exclusive' },
45
- () =>
46
- new Promise<void>((resolveHold) => {
47
- resolveAcquire({ release: () => resolveHold() });
48
- }),
49
- )
50
- .catch((error: unknown) => rejectAcquire(error));
51
- }),
93
+ acquire: (name) => held(name, { mode: 'exclusive' }),
52
94
  tryAcquire: (name) =>
53
- new Promise<LeaderLease | undefined>((resolveTry, rejectTry) => {
54
- manager
55
- .request(name, { mode: 'exclusive', ifAvailable: true }, (lock) => {
56
- // `ifAvailable` grants `null` instead of waiting (Web Locks).
57
- if (lock === null) {
58
- resolveTry(undefined);
59
- return undefined;
60
- }
61
- return new Promise<void>((resolveHold) => {
62
- resolveTry({ release: () => resolveHold() });
63
- });
64
- })
65
- .catch((error: unknown) => rejectTry(error));
66
- }),
95
+ request(name, { mode: 'exclusive', ifAvailable: true }),
96
+ steal: (name) => held(name, { mode: 'exclusive', steal: true }),
67
97
  };
68
98
  }