@syncular/client 0.53.0 → 0.54.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 +10 -0
- package/dist/client.d.ts +3 -0
- package/dist/client.js +1 -2
- package/dist/devtools.d.ts +7 -7
- package/dist/devtools.js +7 -1
- package/dist/worker-core.d.ts +77 -0
- package/dist/worker-core.js +505 -0
- package/dist/worker-entry.d.ts +3 -55
- package/dist/worker-entry.js +4 -553
- package/dist/worker-host.d.ts +4 -0
- package/dist/worker-host.js +5 -3
- package/dist/worker-local-authority.d.ts +3 -0
- package/dist/worker-local-authority.js +70 -0
- package/dist/worker-protocol.d.ts +2 -0
- package/dist/worker-protocol.js +2 -0
- package/dist/worker-remote.d.ts +5 -0
- package/dist/worker-remote.js +5 -0
- package/package.json +13 -4
- package/src/client.ts +4 -2
- package/src/devtools.ts +23 -12
- package/src/worker-core.ts +713 -0
- package/src/worker-entry.ts +5 -743
- package/src/worker-host.ts +10 -4
- package/src/worker-local-authority.ts +106 -0
- package/src/worker-protocol.ts +3 -0
- package/src/worker-remote.ts +14 -0
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
import { ClientSyncError } from './errors.js';
|
|
2
|
+
import { LOCAL_AUTHORITY_UNCONFIGURED_CODE } from './worker-protocol.js';
|
|
3
|
+
/** §12 behavior loaded by the authority-enabled worker entry. */
|
|
4
|
+
export const createWorkerLocalAuthority = (context) => {
|
|
5
|
+
let authority;
|
|
6
|
+
let sibling;
|
|
7
|
+
let remoteTransport;
|
|
8
|
+
const active = () => authority !== undefined && authority.state !== 'attached';
|
|
9
|
+
async function drive(run) {
|
|
10
|
+
const running = context.requireClient();
|
|
11
|
+
const local = authority;
|
|
12
|
+
const remote = remoteTransport;
|
|
13
|
+
if (local === undefined || remote === undefined) {
|
|
14
|
+
throw new ClientSyncError(LOCAL_AUTHORITY_UNCONFIGURED_CODE, 'init did not enable the local authority');
|
|
15
|
+
}
|
|
16
|
+
running.setTransportEnabled(false);
|
|
17
|
+
try {
|
|
18
|
+
await context.serializedSync(() => run(local, remote));
|
|
19
|
+
}
|
|
20
|
+
catch (error) {
|
|
21
|
+
if (error instanceof Error &&
|
|
22
|
+
!(error instanceof ClientSyncError) &&
|
|
23
|
+
'code' in error &&
|
|
24
|
+
typeof error.code === 'string') {
|
|
25
|
+
throw new ClientSyncError(error.code, error.message, false, 'details' in error &&
|
|
26
|
+
typeof error.details === 'object' &&
|
|
27
|
+
error.details !== null
|
|
28
|
+
? { ...error.details }
|
|
29
|
+
: undefined);
|
|
30
|
+
}
|
|
31
|
+
throw error;
|
|
32
|
+
}
|
|
33
|
+
finally {
|
|
34
|
+
running.setTransportEnabled(!context.isOffline());
|
|
35
|
+
}
|
|
36
|
+
context.wake();
|
|
37
|
+
}
|
|
38
|
+
return {
|
|
39
|
+
methods: {
|
|
40
|
+
localAuthorityState: () => authority?.state,
|
|
41
|
+
attachLocalAuthority: () => drive((local, remote) => local.attach(remote)),
|
|
42
|
+
abandonLocalAuthorityAttach: () => drive((local, remote) => local.abandonAttach(remote)),
|
|
43
|
+
},
|
|
44
|
+
async open(config, database, remote, segments) {
|
|
45
|
+
remoteTransport = remote;
|
|
46
|
+
if (context.overrides.openLocalAuthority === undefined) {
|
|
47
|
+
throw new ClientSyncError(LOCAL_AUTHORITY_UNCONFIGURED_CODE, 'localAuthority requires startSyncWorker({ openLocalAuthority })');
|
|
48
|
+
}
|
|
49
|
+
sibling = database.openSibling?.('local-authority');
|
|
50
|
+
if (sibling === undefined) {
|
|
51
|
+
throw new ClientSyncError(LOCAL_AUTHORITY_UNCONFIGURED_CODE, 'localAuthority requires a database with sibling files');
|
|
52
|
+
}
|
|
53
|
+
const local = await context.overrides.openLocalAuthority(sibling.database, config.schema);
|
|
54
|
+
authority = local;
|
|
55
|
+
return {
|
|
56
|
+
transport: (request) => active() ? local.sync(request) : remote(request),
|
|
57
|
+
segments: (request) => {
|
|
58
|
+
if (active())
|
|
59
|
+
return local.downloadSegment(request);
|
|
60
|
+
if (segments === undefined) {
|
|
61
|
+
throw new ClientSyncError('sync.invalid_request', 'no segment endpoint configured');
|
|
62
|
+
}
|
|
63
|
+
return segments(request);
|
|
64
|
+
},
|
|
65
|
+
};
|
|
66
|
+
},
|
|
67
|
+
active,
|
|
68
|
+
close: () => sibling?.close(),
|
|
69
|
+
};
|
|
70
|
+
};
|
|
@@ -38,6 +38,8 @@ export declare const NOT_LEADER_CODE = "client.not_leader";
|
|
|
38
38
|
export declare const WORKER_FAILED_CODE = "client.worker_failed";
|
|
39
39
|
/** A page/worker bundle identity changed and a full host reload is required. */
|
|
40
40
|
export declare const WORKER_RESTART_REQUIRED_CODE = "client.worker_restart_required";
|
|
41
|
+
/** The selected worker entry does not provide the requested method. */
|
|
42
|
+
export declare const WORKER_METHOD_UNAVAILABLE_CODE = "client.worker_method_unavailable";
|
|
41
43
|
/** SPEC §12: local-authority use without `startSyncWorker({ openLocalAuthority })`. */
|
|
42
44
|
export declare const LOCAL_AUTHORITY_UNCONFIGURED_CODE = "client.local_authority_unconfigured";
|
|
43
45
|
/** SPEC §12.3 local-authority state. */
|
package/dist/worker-protocol.js
CHANGED
|
@@ -7,5 +7,7 @@ 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
|
+
/** The selected worker entry does not provide the requested method. */
|
|
11
|
+
export const WORKER_METHOD_UNAVAILABLE_CODE = 'client.worker_method_unavailable';
|
|
10
12
|
/** SPEC §12: local-authority use without `startSyncWorker({ openLocalAuthority })`. */
|
|
11
13
|
export const LOCAL_AUTHORITY_UNCONFIGURED_CODE = 'client.local_authority_unconfigured';
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import { type SyncWorkerOverrides } from './worker-core.js';
|
|
2
|
+
/** Worker overrides for a host that uses only a remote sync authority. */
|
|
3
|
+
export type RemoteSyncWorkerOverrides = Omit<SyncWorkerOverrides, 'openLocalAuthority'>;
|
|
4
|
+
/** Start a worker without the optional local-authority lifecycle (§12). */
|
|
5
|
+
export declare function startSyncWorker(overrides?: RemoteSyncWorkerOverrides): void;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/client",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.54.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",
|
|
@@ -74,6 +74,14 @@
|
|
|
74
74
|
"default": "./dist/worker-entry.js"
|
|
75
75
|
}
|
|
76
76
|
},
|
|
77
|
+
"./worker/remote": {
|
|
78
|
+
"bun": "./src/worker-remote.ts",
|
|
79
|
+
"browser": "./dist/worker-remote.js",
|
|
80
|
+
"import": {
|
|
81
|
+
"types": "./dist/worker-remote.d.ts",
|
|
82
|
+
"default": "./dist/worker-remote.js"
|
|
83
|
+
}
|
|
84
|
+
},
|
|
77
85
|
"./authority": {
|
|
78
86
|
"bun": "./src/authority.ts",
|
|
79
87
|
"browser": "./dist/authority.js",
|
|
@@ -97,11 +105,12 @@
|
|
|
97
105
|
},
|
|
98
106
|
"dependencies": {
|
|
99
107
|
"@sqlite.org/sqlite-wasm": "^3.53.0-build1",
|
|
100
|
-
"@syncular/core": "0.
|
|
108
|
+
"@syncular/core": "0.54.0"
|
|
101
109
|
},
|
|
102
110
|
"devDependencies": {
|
|
103
|
-
"@
|
|
111
|
+
"@electric-sql/pglite": "^0.5.4",
|
|
112
|
+
"@syncular/server": "0.54.0",
|
|
104
113
|
"playwright": "1.63.0",
|
|
105
|
-
"
|
|
114
|
+
"vite": "8.3.4"
|
|
106
115
|
}
|
|
107
116
|
}
|
package/src/client.ts
CHANGED
|
@@ -86,7 +86,7 @@ import {
|
|
|
86
86
|
serializeBlobRef,
|
|
87
87
|
} from './blob';
|
|
88
88
|
import type { ClientDatabase, SqlRow, SqlValue } from './database';
|
|
89
|
-
import {
|
|
89
|
+
import type { DevtoolsRegistrar } from './devtools';
|
|
90
90
|
import {
|
|
91
91
|
CLIENT_DIAGNOSTICS_VERSION,
|
|
92
92
|
ClientDiagnosticsEmitter,
|
|
@@ -417,6 +417,8 @@ export interface SyncClientLimits {
|
|
|
417
417
|
}
|
|
418
418
|
|
|
419
419
|
export interface SyncClientConfig {
|
|
420
|
+
/** Explicit development console registry; absent means no registration. */
|
|
421
|
+
readonly devtools?: DevtoolsRegistrar;
|
|
420
422
|
readonly transportEnabled?: boolean;
|
|
421
423
|
/** Keep rejected/conflicting local intent visible until explicit resolution. */
|
|
422
424
|
readonly retainFailedCommits?: boolean;
|
|
@@ -1252,7 +1254,7 @@ export class SyncClient {
|
|
|
1252
1254
|
this.#emitSyncIntent({ kind: 'interactive' });
|
|
1253
1255
|
}
|
|
1254
1256
|
// Console introspection is a no-op outside a dev page.
|
|
1255
|
-
this.#devtoolsUnregister =
|
|
1257
|
+
this.#devtoolsUnregister = this.#config.devtools?.({
|
|
1256
1258
|
kind: 'client',
|
|
1257
1259
|
ref: this,
|
|
1258
1260
|
clientId: () => this.#clientId,
|
package/src/devtools.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The client-side introspection registry:
|
|
3
|
-
* `SyncClient` / `SyncClientHandle` on a page registers itself on
|
|
2
|
+
* The optional client-side introspection registry: a configured
|
|
3
|
+
* `SyncClient` / `SyncClientHandle` on a development page registers itself on
|
|
4
4
|
* `globalThis.__SYNCULAR__`, so a first integration debugs from the console
|
|
5
5
|
* instead of hand-exposing the client:
|
|
6
6
|
*
|
|
@@ -11,11 +11,9 @@
|
|
|
11
11
|
* // last invalidation
|
|
12
12
|
* __SYNCULAR__.clients[0].ref // the client itself — full API
|
|
13
13
|
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
* production builds skip installation; environments without `process` are
|
|
18
|
-
* treated as dev). Cost when gated off: one function call per client.
|
|
14
|
+
* The host explicitly supplies `registerDevtools` in its client config. The
|
|
15
|
+
* registry also requires a development or test environment signal and a
|
|
16
|
+
* `window`. A browser without a development signal leaves it disabled.
|
|
19
17
|
*/
|
|
20
18
|
import type { InvalidationEvent, InvalidationListener } from './invalidation';
|
|
21
19
|
|
|
@@ -36,6 +34,11 @@ export interface DevtoolsRegistration {
|
|
|
36
34
|
readonly onInvalidate: (listener: InvalidationListener) => () => void;
|
|
37
35
|
}
|
|
38
36
|
|
|
37
|
+
/** Explicit development registry supplied to a client or worker handle. */
|
|
38
|
+
export type DevtoolsRegistrar = (
|
|
39
|
+
registration: DevtoolsRegistration,
|
|
40
|
+
) => () => void;
|
|
41
|
+
|
|
39
42
|
/** One live entry on the registry (a registration plus tracked state). */
|
|
40
43
|
export interface DevtoolsEntry extends DevtoolsRegistration {
|
|
41
44
|
/** The most recent invalidation event, timestamped (epoch ms). */
|
|
@@ -55,12 +58,20 @@ const KEY = '__SYNCULAR__';
|
|
|
55
58
|
|
|
56
59
|
/** The page global to install on, or undefined when gated off. */
|
|
57
60
|
function registryHost(): Record<string, unknown> | undefined {
|
|
58
|
-
const g = globalThis as Record<string, unknown> & {
|
|
59
|
-
window?: unknown;
|
|
60
|
-
process?: { env?: { NODE_ENV?: string } };
|
|
61
|
-
};
|
|
61
|
+
const g = globalThis as Record<string, unknown> & { window?: unknown };
|
|
62
62
|
if (g.window === undefined) return undefined;
|
|
63
|
-
if (
|
|
63
|
+
if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production')
|
|
64
|
+
return undefined;
|
|
65
|
+
if (
|
|
66
|
+
!(
|
|
67
|
+
(typeof import.meta.env !== 'undefined' &&
|
|
68
|
+
(import.meta.env.DEV as boolean | string | undefined) === true) ||
|
|
69
|
+
(typeof process !== 'undefined' &&
|
|
70
|
+
(process.env.NODE_ENV === 'development' ||
|
|
71
|
+
process.env.NODE_ENV === 'test'))
|
|
72
|
+
)
|
|
73
|
+
)
|
|
74
|
+
return undefined;
|
|
64
75
|
return g;
|
|
65
76
|
}
|
|
66
77
|
|