@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
package/README.md
CHANGED
|
@@ -48,6 +48,15 @@ import { startSyncWorker } from '@syncular/client/worker';
|
|
|
48
48
|
startSyncWorker();
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
+
Use `@syncular/client/worker/remote` for a worker that only connects to a
|
|
52
|
+
remote authority. It omits the local-authority lifecycle from the worker
|
|
53
|
+
bundle while preserving the normal client and multi-tab APIs. It refuses an
|
|
54
|
+
initialization with `localAuthority: true` before opening storage using
|
|
55
|
+
`client.local_authority_unconfigured`. The shared handle still declares its
|
|
56
|
+
local-authority methods; those calls fail with
|
|
57
|
+
`client.worker_method_unavailable` on a remote-only worker. Use
|
|
58
|
+
`@syncular/client/worker` to run a local authority.
|
|
59
|
+
|
|
51
60
|
```ts
|
|
52
61
|
// main thread
|
|
53
62
|
import { createSyncClientHandle } from '@syncular/client';
|
|
@@ -741,6 +750,7 @@ they own their buffer.
|
|
|
741
750
|
|---|---|
|
|
742
751
|
| `.` | protocol core, transports, handle + RPC protocol (browser-safe, no SQLite) |
|
|
743
752
|
| `./worker` | `startSyncWorker` — worker-side bootstrap (pulls sqlite-wasm) |
|
|
753
|
+
| `./worker/remote` | remote-only worker bootstrap without the local-authority lifecycle |
|
|
744
754
|
| `./wasm` | sqlite-wasm bindings: `openPersistentWasmDatabase`, `openWasmDatabase` |
|
|
745
755
|
| `./sqlite` | Runtime-selected SQLite: `openSqliteDatabase` on Node or Bun |
|
|
746
756
|
| `./bun` | Explicit `bun:sqlite` binding: `openBunDatabase` |
|
package/dist/client.d.ts
CHANGED
|
@@ -12,6 +12,7 @@ import { type SyncProgress, type SyncProgressListener } from './progress.js';
|
|
|
12
12
|
import { type ScopeMap, type WakeReason } from '@syncular/core';
|
|
13
13
|
import { type BlobRef, type BlobTransport, type CachedBlob } from './blob.js';
|
|
14
14
|
import type { ClientDatabase, SqlRow, SqlValue } from './database.js';
|
|
15
|
+
import type { DevtoolsRegistrar } from './devtools.js';
|
|
15
16
|
import { type ClientDiagnosticsListener, type ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot, type RealtimePolicy } from './diagnostics.js';
|
|
16
17
|
import type { EncryptionConfig } from './encryption.js';
|
|
17
18
|
import { type ClientChangeListener, type CommandResult, type InvalidationListener, type LocalRevision, type SyncIntent, type SyncStatusSnapshot } from './invalidation.js';
|
|
@@ -146,6 +147,8 @@ export interface SyncClientLimits {
|
|
|
146
147
|
readonly maxPushRequestBytes?: number;
|
|
147
148
|
}
|
|
148
149
|
export interface SyncClientConfig {
|
|
150
|
+
/** Explicit development console registry; absent means no registration. */
|
|
151
|
+
readonly devtools?: DevtoolsRegistrar;
|
|
149
152
|
readonly transportEnabled?: boolean;
|
|
150
153
|
/** Keep rejected/conflicting local intent visible until explicit resolution. */
|
|
151
154
|
readonly retainFailedCommits?: boolean;
|
package/dist/client.js
CHANGED
|
@@ -19,7 +19,6 @@ import { EncryptError } from '@syncular/core';
|
|
|
19
19
|
import { EncodeError } from '@syncular/core';
|
|
20
20
|
import { applyCommitFrame, applyRowsSegment, applySqliteSegment, deleteLocalRow, deleteScopedRows, localScopePredicate, 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
|
-
import { registerDevtools } from './devtools.js';
|
|
23
22
|
import { CLIENT_DIAGNOSTICS_VERSION, ClientDiagnosticsEmitter, MAX_DIAGNOSTIC_DOMAINS, MAX_DIAGNOSTIC_EXPECTED_SUBSCRIPTIONS, MAX_DIAGNOSTIC_QUERY_FAILURES, } from './diagnostics.js';
|
|
24
23
|
import { ClientSyncError, invalidRequest, classifySqliteFailure, REALTIME_LOST_CODE, RealtimeUnavailableError, } from './errors.js';
|
|
25
24
|
import { ChangeAccumulator, ChangeEmitter, InvalidationEmitter, invalidationFromChange, } from './invalidation.js';
|
|
@@ -450,7 +449,7 @@ export class SyncClient {
|
|
|
450
449
|
this.#emitSyncIntent({ kind: 'interactive' });
|
|
451
450
|
}
|
|
452
451
|
// Console introspection is a no-op outside a dev page.
|
|
453
|
-
this.#devtoolsUnregister =
|
|
452
|
+
this.#devtoolsUnregister = this.#config.devtools?.({
|
|
454
453
|
kind: 'client',
|
|
455
454
|
ref: this,
|
|
456
455
|
clientId: () => this.#clientId,
|
package/dist/devtools.d.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 { InvalidationListener } from './invalidation.js';
|
|
21
19
|
/** What a registrant supplies — plain lambdas over its own surface. */
|
|
@@ -34,6 +32,8 @@ export interface DevtoolsRegistration {
|
|
|
34
32
|
readonly upgrading: () => Promise<boolean>;
|
|
35
33
|
readonly onInvalidate: (listener: InvalidationListener) => () => void;
|
|
36
34
|
}
|
|
35
|
+
/** Explicit development registry supplied to a client or worker handle. */
|
|
36
|
+
export type DevtoolsRegistrar = (registration: DevtoolsRegistration) => () => void;
|
|
37
37
|
/** One live entry on the registry (a registration plus tracked state). */
|
|
38
38
|
export interface DevtoolsEntry extends DevtoolsRegistration {
|
|
39
39
|
/** The most recent invalidation event, timestamped (epoch ms). */
|
package/dist/devtools.js
CHANGED
|
@@ -4,7 +4,13 @@ function registryHost() {
|
|
|
4
4
|
const g = globalThis;
|
|
5
5
|
if (g.window === undefined)
|
|
6
6
|
return undefined;
|
|
7
|
-
if (
|
|
7
|
+
if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production')
|
|
8
|
+
return undefined;
|
|
9
|
+
if (!((typeof import.meta.env !== 'undefined' &&
|
|
10
|
+
import.meta.env.DEV === true) ||
|
|
11
|
+
(typeof process !== 'undefined' &&
|
|
12
|
+
(process.env.NODE_ENV === 'development' ||
|
|
13
|
+
process.env.NODE_ENV === 'test'))))
|
|
8
14
|
return undefined;
|
|
9
15
|
return g;
|
|
10
16
|
}
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Worker-side bootstrap: constructs the WHOLE
|
|
3
|
+
* client core — SyncClient + transports + realtime + SQLite — inside the
|
|
4
|
+
* worker and serves the `worker-protocol` RPC over postMessage.
|
|
5
|
+
*
|
|
6
|
+
* Browsers get the defaults: opfs-sahpool persistence and the fetch/WS
|
|
7
|
+
* transports from `./http`, wired from `WorkerInitConfig.endpoints`.
|
|
8
|
+
* Tests inject a database factory (bun:sqlite) through `overrides` — the
|
|
9
|
+
* same bootstrap, the same RPC, a different SQLite.
|
|
10
|
+
*
|
|
11
|
+
* The §8.4 host loop lives HERE: wake-ups (hello/`sync` events, delta
|
|
12
|
+
* drops) coalesce into one intent-driven `syncUntilIdle` round in the worker;
|
|
13
|
+
* RPC-driven and auto-driven sync rounds serialize on one queue because
|
|
14
|
+
* the core owns exactly one loop.
|
|
15
|
+
*/
|
|
16
|
+
import type { defineAuthorityReads } from './authority.js';
|
|
17
|
+
import { SyncClient } from './client.js';
|
|
18
|
+
import type { ClientDatabase } from './database.js';
|
|
19
|
+
import type { RealtimeConnector, SegmentDownloader, SyncTransport } from './transport.js';
|
|
20
|
+
import type { ClientSchema } from './schema.js';
|
|
21
|
+
import { type LocalAuthorityState, type WorkerApi, type WorkerInitConfig } from './worker-protocol.js';
|
|
22
|
+
export interface SyncWorkerOverrides {
|
|
23
|
+
/** Explicit authority reader factory. Required when init declares authorityReads. */
|
|
24
|
+
readonly createAuthorityReads?: typeof defineAuthorityReads;
|
|
25
|
+
/** Database factory indirection: tests inject bun:sqlite here. */
|
|
26
|
+
readonly openDatabase?: (config: WorkerInitConfig) => Promise<ClientDatabase> | ClientDatabase;
|
|
27
|
+
/** Retry deadline indirection for deterministic worker-host tests. */
|
|
28
|
+
readonly waitForStorageRetry?: (delayMs: number) => Promise<void>;
|
|
29
|
+
readonly createTransport?: (config: WorkerInitConfig) => SyncTransport;
|
|
30
|
+
readonly createSegments?: (config: WorkerInitConfig) => SegmentDownloader | undefined;
|
|
31
|
+
/**
|
|
32
|
+
* Custom realtime connector, e.g. one that mints a fresh ticket per
|
|
33
|
+
* connection attempt. `headers` reads the current host auth set.
|
|
34
|
+
*/
|
|
35
|
+
readonly createRealtime?: (config: WorkerInitConfig, clientId: string, headers: () => Readonly<Record<string, string>>) => RealtimeConnector | undefined;
|
|
36
|
+
/**
|
|
37
|
+
* SPEC §12 local authority, required by init's `localAuthority: true`:
|
|
38
|
+
* `(database, schema) => openLocalAuthority({ database:
|
|
39
|
+
* clientSqliteDatabase(database), schema })` from `@syncular/server`. Only
|
|
40
|
+
* a worker entry that passes it bundles the server code.
|
|
41
|
+
*/
|
|
42
|
+
readonly openLocalAuthority?: (database: ClientDatabase, schema: ClientSchema) => Promise<WorkerLocalAuthority>;
|
|
43
|
+
}
|
|
44
|
+
/** The `LocalAuthority` surface of `@syncular/server` the worker drives (§12). */
|
|
45
|
+
export interface WorkerLocalAuthority {
|
|
46
|
+
readonly state: LocalAuthorityState;
|
|
47
|
+
readonly sync: SyncTransport;
|
|
48
|
+
readonly downloadSegment: SegmentDownloader;
|
|
49
|
+
readonly attach: (transport: SyncTransport) => Promise<void>;
|
|
50
|
+
readonly abandonAttach: (transport?: SyncTransport) => Promise<void>;
|
|
51
|
+
}
|
|
52
|
+
type LocalAuthorityMethod = 'localAuthorityState' | 'attachLocalAuthority' | 'abandonLocalAuthorityAttach';
|
|
53
|
+
/** @internal Optional §12 behavior supplied by the authority-enabled entry. */
|
|
54
|
+
interface WorkerLocalAuthorityExtension {
|
|
55
|
+
readonly methods: Pick<WorkerApi, LocalAuthorityMethod>;
|
|
56
|
+
open(config: WorkerInitConfig, database: ClientDatabase, remote: SyncTransport, segments: SegmentDownloader | undefined): Promise<{
|
|
57
|
+
readonly transport: SyncTransport;
|
|
58
|
+
readonly segments: SegmentDownloader | undefined;
|
|
59
|
+
}>;
|
|
60
|
+
active(): boolean;
|
|
61
|
+
close(): void;
|
|
62
|
+
}
|
|
63
|
+
/** @internal Dependencies shared with the worker's single sync loop. */
|
|
64
|
+
export type WorkerLocalAuthorityFactory = (context: {
|
|
65
|
+
readonly overrides: SyncWorkerOverrides;
|
|
66
|
+
readonly requireClient: () => SyncClient;
|
|
67
|
+
readonly serializedSync: <T>(run: () => Promise<T>) => Promise<T>;
|
|
68
|
+
readonly isOffline: () => boolean;
|
|
69
|
+
readonly wake: () => void;
|
|
70
|
+
}) => WorkerLocalAuthorityExtension;
|
|
71
|
+
/**
|
|
72
|
+
* Register the RPC server on the current worker scope. Call this once
|
|
73
|
+
* from a worker entry script; the main-thread handle drives everything
|
|
74
|
+
* else through `init`/`call` messages.
|
|
75
|
+
*/
|
|
76
|
+
export declare function startSyncWorkerCore(overrides: SyncWorkerOverrides, createLocalAuthority?: WorkerLocalAuthorityFactory): void;
|
|
77
|
+
export {};
|