@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.
- package/README.md +50 -1
- package/dist/availability.d.ts +1 -1
- package/dist/availability.js +1 -1
- package/dist/client.js +18 -3
- package/dist/errors.d.ts +5 -0
- package/dist/errors.js +5 -0
- package/dist/leader-lock.d.ts +18 -7
- package/dist/leader-lock.js +40 -22
- package/dist/multi-tab.d.ts +158 -22
- package/dist/multi-tab.js +361 -10
- package/dist/outbox.d.ts +5 -0
- package/dist/outbox.js +11 -3
- package/dist/outcomes.js +6 -2
- package/dist/previous-version.d.ts +3 -1
- package/dist/previous-version.js +24 -5
- package/dist/reactive-store.js +2 -1
- package/dist/wasm-database.d.ts +6 -0
- package/dist/wasm-database.js +36 -6
- package/dist/worker-entry.d.ts +17 -1
- package/dist/worker-entry.js +74 -4
- package/dist/worker-host.d.ts +45 -26
- package/dist/worker-host.js +172 -310
- package/dist/worker-protocol.d.ts +22 -0
- package/dist/worker-protocol.js +2 -0
- package/package.json +3 -3
- package/src/availability.ts +3 -2
- package/src/client.ts +26 -3
- package/src/errors.ts +6 -0
- package/src/leader-lock.ts +64 -34
- package/src/multi-tab.ts +576 -34
- package/src/outbox.ts +16 -2
- package/src/outcomes.ts +6 -2
- package/src/previous-version.ts +32 -5
- package/src/reactive-store.ts +2 -1
- package/src/wasm-database.ts +64 -6
- package/src/worker-entry.ts +124 -4
- package/src/worker-host.ts +219 -379
- package/src/worker-protocol.ts +24 -0
|
@@ -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;
|
package/dist/worker-protocol.js
CHANGED
|
@@ -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.
|
|
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.
|
|
100
|
+
"@syncular/core": "0.49.2"
|
|
101
101
|
},
|
|
102
102
|
"devDependencies": {
|
|
103
|
-
"@syncular/server": "0.
|
|
103
|
+
"@syncular/server": "0.49.2",
|
|
104
104
|
"playwright": "1.63.0",
|
|
105
105
|
"@electric-sql/pglite": "^0.5.4"
|
|
106
106
|
}
|
package/src/availability.ts
CHANGED
|
@@ -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:
|
|
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 =
|
|
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
|
|
package/src/leader-lock.ts
CHANGED
|
@@ -1,11 +1,16 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Multi-tab ownership seam: exactly one core instance owns the
|
|
3
|
-
* local database.
|
|
4
|
-
*
|
|
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
|
-
|
|
54
|
-
|
|
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
|
}
|