@syncular/client 0.59.0 → 0.60.1
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 +27 -27
- package/dist/apply.d.ts +6 -5
- package/dist/apply.js +52 -25
- package/dist/authority.js +21 -16
- package/dist/blob.d.ts +4 -4
- package/dist/bun-database.js +3 -16
- package/dist/client.d.ts +57 -66
- package/dist/client.js +701 -796
- package/dist/devtools.d.ts +2 -2
- package/dist/devtools.js +3 -3
- package/dist/diagnostics.d.ts +17 -28
- package/dist/diagnostics.js +1 -2
- package/dist/errors.d.ts +1 -1
- package/dist/errors.js +1 -1
- package/dist/failed-overlay.js +4 -1
- package/dist/http.js +19 -5
- package/dist/invalidation.d.ts +3 -4
- package/dist/invalidation.js +9 -22
- package/dist/native-bridge.d.ts +7 -16
- package/dist/native-bridge.js +16 -41
- package/dist/node-database.js +16 -25
- package/dist/outbox.js +1 -0
- package/dist/progress.d.ts +2 -2
- package/dist/query-guard.d.ts +15 -6
- package/dist/query-guard.js +38 -6
- package/dist/reactive-store.js +2 -2
- package/dist/remote.js +9 -9
- package/dist/schema.d.ts +3 -2
- package/dist/schema.js +28 -12
- package/dist/state.d.ts +69 -36
- package/dist/state.js +178 -89
- package/dist/sync-scheduler.js +2 -2
- package/dist/transport.d.ts +2 -2
- package/dist/window.d.ts +30 -52
- package/dist/window.js +33 -77
- package/dist/worker-core.js +6 -6
- package/dist/worker-host.d.ts +9 -8
- package/dist/worker-host.js +23 -14
- package/dist/worker-protocol.d.ts +9 -8
- package/package.json +3 -3
- package/src/apply.ts +87 -33
- package/src/authority.ts +31 -17
- package/src/blob.ts +4 -3
- package/src/bun-database.ts +9 -14
- package/src/client.ts +886 -1037
- package/src/devtools.ts +5 -5
- package/src/diagnostics.ts +17 -37
- package/src/errors.ts +1 -1
- package/src/failed-overlay.ts +6 -1
- package/src/http.ts +22 -9
- package/src/invalidation.ts +9 -29
- package/src/native-bridge.ts +22 -58
- package/src/node-database.ts +26 -27
- package/src/outbox.ts +1 -0
- package/src/progress.ts +2 -2
- package/src/query-guard.ts +45 -8
- package/src/reactive-store.ts +2 -2
- package/src/remote.ts +12 -16
- package/src/schema.ts +48 -13
- package/src/state.ts +246 -125
- package/src/sync-scheduler.ts +2 -2
- package/src/transport.ts +2 -2
- package/src/window.ts +55 -134
- package/src/worker-core.ts +6 -6
- package/src/worker-host.ts +27 -19
- package/src/worker-protocol.ts +8 -8
package/dist/client.d.ts
CHANGED
|
@@ -9,11 +9,11 @@ import { type SyncProgress, type SyncProgressListener } from './progress.js';
|
|
|
9
9
|
* ownership behind `LeaderLock`. One combined push+pull request per
|
|
10
10
|
* `sync()` round (§7.2); local reads go straight to the database.
|
|
11
11
|
*/
|
|
12
|
-
import { type PresenceErrorCode, type
|
|
12
|
+
import { type PresenceErrorCode, type UnitScopes, 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
15
|
import type { DevtoolsRegistrar } from './devtools.js';
|
|
16
|
-
import { type ClientDiagnosticsListener, type
|
|
16
|
+
import { type ClientDiagnosticsListener, type ClientDiagnosticsSnapshot, type RealtimePolicy } from './diagnostics.js';
|
|
17
17
|
import type { EncryptionConfig } from './encryption.js';
|
|
18
18
|
import { type ClientChangeListener, type CommandResult, type InvalidationListener, type LocalRevision, type SyncIntent, type SyncStatusSnapshot } from './invalidation.js';
|
|
19
19
|
import { type LeaderLock } from './leader-lock.js';
|
|
@@ -23,7 +23,7 @@ import { type OutboxCommit } from './outbox.js';
|
|
|
23
23
|
import { type CommitOutcome, type CommitOutcomeQuery, type ConflictRecord, type RejectionRecord, type RetainedCommitRow, type ResolveCommitOutcomeInput } from './outcomes.js';
|
|
24
24
|
import { type PreviousVersionAudit, type PreviousVersionReadSpec, type PreviousVersionSnapshot } from './previous-version.js';
|
|
25
25
|
import { type ClientSchema } from './schema.js';
|
|
26
|
-
import { type
|
|
26
|
+
import { type UnitRecord } from './state.js';
|
|
27
27
|
import type { RealtimeConnector, SegmentDownloader, SyncTransport } from './transport.js';
|
|
28
28
|
import { type WindowBase } from './window.js';
|
|
29
29
|
export type MutationInput = {
|
|
@@ -72,14 +72,14 @@ export interface SyncSummary {
|
|
|
72
72
|
readonly commitsApplied: number;
|
|
73
73
|
/** Snapshot rows applied from segments. */
|
|
74
74
|
readonly segmentRowsApplied: number;
|
|
75
|
-
/**
|
|
75
|
+
/** Ids of the units still catching up after the round (§4.1). */
|
|
76
76
|
readonly bootstrapping: readonly string[];
|
|
77
|
-
/**
|
|
77
|
+
/** Units reset via `sync.cursor_expired` (§4.6). */
|
|
78
78
|
readonly resets: readonly string[];
|
|
79
|
-
/**
|
|
79
|
+
/** Units revoked this round (§3.3 purge ran). */
|
|
80
80
|
readonly revoked: readonly string[];
|
|
81
|
-
/**
|
|
82
|
-
*
|
|
81
|
+
/** Units stopped by a fatal configuration error (§3.3/§5.6 fail-closed:
|
|
82
|
+
* no local scope-column mapping). */
|
|
83
83
|
readonly failed: readonly string[];
|
|
84
84
|
/** Present when the server declared a schema floor — syncing stopped. */
|
|
85
85
|
readonly schemaFloor?: SchemaFloor;
|
|
@@ -97,7 +97,7 @@ export interface SyncIdleResult extends SyncSummary {
|
|
|
97
97
|
readonly budgetExhausted: boolean;
|
|
98
98
|
}
|
|
99
99
|
export interface SyncIdleOptions {
|
|
100
|
-
/** §7.
|
|
100
|
+
/** §7.8: a strict positive round count. Default: 20. */
|
|
101
101
|
readonly maxRounds?: number;
|
|
102
102
|
/**
|
|
103
103
|
* Total wall-clock budget for one drive, across every round. When it
|
|
@@ -120,7 +120,7 @@ export interface SyncClientLimits {
|
|
|
120
120
|
/**
|
|
121
121
|
* §4.2 accept bitmask; defaults to inline + external rows (0b0011)
|
|
122
122
|
* plus SQLite images and signed URLs when supported. Both image chunks
|
|
123
|
-
* and rows blocks commit before yielding to local reads (§7.
|
|
123
|
+
* and rows blocks commit before yielding to local reads (§7.8).
|
|
124
124
|
*/
|
|
125
125
|
readonly accept?: number;
|
|
126
126
|
/**
|
|
@@ -139,7 +139,8 @@ export interface SyncClientLimits {
|
|
|
139
139
|
readonly maxPushOperationsPerRequest?: number;
|
|
140
140
|
/**
|
|
141
141
|
* §7.1: maximum bytes of the complete encoded SSP2 request (8-byte
|
|
142
|
-
* envelope, request header, push commits, pull header,
|
|
142
|
+
* envelope, request header, push commits, pull header, unit and progress
|
|
143
|
+
* frames,
|
|
143
144
|
* framing, and any §5.11 ciphertext). Default: unbounded. A request whose
|
|
144
145
|
* fixed frames alone exceed it, or whose first commit alone does not fit,
|
|
145
146
|
* raises `client.push_request_too_large` and stays queued.
|
|
@@ -271,12 +272,6 @@ export interface PresencePeer {
|
|
|
271
272
|
readonly clientId: string;
|
|
272
273
|
readonly doc: Record<string, unknown>;
|
|
273
274
|
}
|
|
274
|
-
export interface SubscribeInput {
|
|
275
|
-
readonly id: string;
|
|
276
|
-
readonly table: string;
|
|
277
|
-
readonly scopes: ScopeMap;
|
|
278
|
-
readonly params?: string;
|
|
279
|
-
}
|
|
280
275
|
/**
|
|
281
276
|
* The live state of a window base (§4.8) — the completeness oracle (I3),
|
|
282
277
|
* as plain serializable data so it crosses the worker/follower boundary
|
|
@@ -289,11 +284,10 @@ export interface WindowState {
|
|
|
289
284
|
/** Windowed-in units for this base, ordered by value. */
|
|
290
285
|
readonly units: readonly string[];
|
|
291
286
|
/**
|
|
292
|
-
*
|
|
293
|
-
*
|
|
294
|
-
*
|
|
295
|
-
*
|
|
296
|
-
* it MUST NOT be rendered as complete.
|
|
287
|
+
* Windowed-in values whose unit is not complete (§4.8): bootstrapping
|
|
288
|
+
* (cursor `-1` or a resume token), revoked or failed. Between `setWindow`
|
|
289
|
+
* and the bootstrap landing, the local replica for a pending value may be
|
|
290
|
+
* empty or partial; it MUST NOT be rendered as complete.
|
|
297
291
|
*/
|
|
298
292
|
readonly pending: readonly string[];
|
|
299
293
|
}
|
|
@@ -337,26 +331,25 @@ export interface SnapshotStatement {
|
|
|
337
331
|
readonly params?: readonly SqlValue[];
|
|
338
332
|
}
|
|
339
333
|
/**
|
|
340
|
-
* §7.5: the catch-up state of one
|
|
341
|
-
*
|
|
342
|
-
*
|
|
343
|
-
* no fabricated table or cursor.
|
|
334
|
+
* §7.5: the catch-up state of one unit as persisted in the snapshot, never
|
|
335
|
+
* the mutable owner cache. `unknown` means the client does not currently hold
|
|
336
|
+
* the unit (never registered, released, or removed).
|
|
344
337
|
*/
|
|
345
|
-
export type
|
|
338
|
+
export type UnitCatchup = {
|
|
346
339
|
readonly state: 'unknown';
|
|
347
340
|
readonly id: string;
|
|
348
341
|
} | {
|
|
349
342
|
readonly state: 'known';
|
|
350
343
|
readonly id: string;
|
|
351
|
-
readonly table: string;
|
|
352
344
|
readonly status: 'active' | 'revoked' | 'failed';
|
|
345
|
+
readonly live: boolean;
|
|
346
|
+
/** The unit's cursor while it catches up, the replica cursor while live. */
|
|
353
347
|
readonly cursor: number;
|
|
354
348
|
readonly hasResumeToken: boolean;
|
|
355
|
-
/** True only for `active`
|
|
349
|
+
/** True only for an `active` unit that is live or post-bootstrap. */
|
|
356
350
|
readonly bootstrapComplete: boolean;
|
|
357
|
-
/** True only for `active`
|
|
351
|
+
/** True only for an `active` unit with cursor `-1` or a resume token. */
|
|
358
352
|
readonly knownPendingPages: boolean;
|
|
359
|
-
readonly effectiveScopes?: unknown;
|
|
360
353
|
readonly reasonCode?: string;
|
|
361
354
|
};
|
|
362
355
|
/**
|
|
@@ -380,7 +373,8 @@ export type CommitDelivery = {
|
|
|
380
373
|
export interface SnapshotReadRequest {
|
|
381
374
|
readonly statements: readonly SnapshotStatement[];
|
|
382
375
|
readonly coverage?: readonly WindowCoverage[];
|
|
383
|
-
|
|
376
|
+
/** Unit ids whose catch-up state the read reports. */
|
|
377
|
+
readonly units?: readonly string[];
|
|
384
378
|
readonly commitIds?: readonly string[];
|
|
385
379
|
/** §7.5 owner: a failed owned read is reported in `queryFailures`. */
|
|
386
380
|
readonly owner?: QueryOwner;
|
|
@@ -391,7 +385,7 @@ export interface SnapshotRead<Row = SqlRow> {
|
|
|
391
385
|
readonly revision: LocalRevision;
|
|
392
386
|
readonly queries: readonly (readonly Row[])[];
|
|
393
387
|
readonly coverage: CoverageSnapshot;
|
|
394
|
-
readonly
|
|
388
|
+
readonly units: readonly UnitCatchup[];
|
|
395
389
|
readonly deliveries: readonly CommitDelivery[];
|
|
396
390
|
}
|
|
397
391
|
/**
|
|
@@ -463,15 +457,15 @@ export declare class SyncClient {
|
|
|
463
457
|
*/
|
|
464
458
|
querySnapshot<Row = SqlRow>(spec: QueryReadSpec): QuerySnapshot<Row>;
|
|
465
459
|
/**
|
|
466
|
-
* §7.5: resolve several read-only statements, window coverage,
|
|
460
|
+
* §7.5: resolve several read-only statements, window coverage, unit
|
|
467
461
|
* catch-up states, and commit deliveries from one SQLite read transaction
|
|
468
462
|
* and one revision. A host that needs those together reads them together;
|
|
469
463
|
* every statement passes the read-only guard and any failure rolls the whole
|
|
470
464
|
* read back.
|
|
471
465
|
*/
|
|
472
466
|
snapshotRead<Row = SqlRow>(spec: SnapshotReadRequest): SnapshotRead<Row>;
|
|
473
|
-
/** §7.5: one
|
|
474
|
-
|
|
467
|
+
/** §7.5: one unit's persisted catch-up state (never the owner cache). */
|
|
468
|
+
unitCatchup(id: string): UnitCatchup;
|
|
475
469
|
/** §7.5: one client commit's delivery status: pending, its retained outcome,
|
|
476
470
|
* or an explicit unknown (never held, or pruned by retention). */
|
|
477
471
|
commitDelivery(id: string): CommitDelivery;
|
|
@@ -522,7 +516,7 @@ export declare class SyncClient {
|
|
|
522
516
|
* One atomic support/product-health view. It never returns scope values,
|
|
523
517
|
* rows, SQL, paths, auth material, lease ids, keys, or mutation bodies.
|
|
524
518
|
*/
|
|
525
|
-
diagnosticsSnapshot(
|
|
519
|
+
diagnosticsSnapshot(): ClientDiagnosticsSnapshot;
|
|
526
520
|
/** One call for the complete status domain used by reactive hosts. */
|
|
527
521
|
statusSnapshot(): SyncStatusSnapshot;
|
|
528
522
|
/**
|
|
@@ -596,44 +590,41 @@ export declare class SyncClient {
|
|
|
596
590
|
* by the server with `presence.forbidden`.
|
|
597
591
|
*/
|
|
598
592
|
setPresence(scopeKey: string, doc: Record<string, unknown> | null): void;
|
|
599
|
-
|
|
600
|
-
|
|
593
|
+
/** Every unit in registration order (§4.1), including revoked and failed. */
|
|
594
|
+
units(): UnitRecord[];
|
|
595
|
+
unit(id: string): UnitRecord | undefined;
|
|
601
596
|
pendingCommits(): OutboxCommit[];
|
|
602
|
-
|
|
597
|
+
/** Register one unit (§4.1) and return its id. */
|
|
598
|
+
subscribe(scopes: UnitScopes): string;
|
|
603
599
|
/**
|
|
604
|
-
* Register several
|
|
605
|
-
*
|
|
606
|
-
*
|
|
607
|
-
*
|
|
608
|
-
*
|
|
600
|
+
* Register several units in one local transaction and return their ids:
|
|
601
|
+
* one commit for all of them (on OPFS a commit costs milliseconds, so a
|
|
602
|
+
* cold start with hundreds of units pays it once). An error rolls back every
|
|
603
|
+
* registration of the call. Registering an active unit again changes
|
|
604
|
+
* nothing; a revoked unit re-arms (§3.3).
|
|
605
|
+
*/
|
|
606
|
+
subscribeMany(units: readonly UnitScopes[]): string[];
|
|
607
|
+
/**
|
|
608
|
+
* Release the explicit reference to a unit. The unit leaves the
|
|
609
|
+
* registration list when no window base holds it (§4.1); its rows stay.
|
|
609
610
|
*/
|
|
610
|
-
subscribeMany(inputs: readonly SubscribeInput[]): void;
|
|
611
611
|
unsubscribe(id: string): void;
|
|
612
612
|
/**
|
|
613
|
-
* Set the
|
|
614
|
-
*
|
|
615
|
-
*
|
|
616
|
-
*
|
|
617
|
-
*
|
|
618
|
-
*
|
|
619
|
-
* eviction and fresh-bootstraps.
|
|
620
|
-
*
|
|
621
|
-
* The change takes effect on the next `sync()`/socket round — the pull's
|
|
622
|
-
* subscription list (now with the added unit, without the removed one)
|
|
623
|
-
* re-registers realtime at round end (§8.7). No socket cycle needed.
|
|
613
|
+
* Set the windowed-in values of a base (§4.8): one unit per value. Added
|
|
614
|
+
* values take a reference on their unit (a new unit bootstraps on the next
|
|
615
|
+
* sync); removed values release theirs, and a unit no reference holds leaves
|
|
616
|
+
* the registration list fused with its first eviction chunk (E1–E4).
|
|
617
|
+
* Idempotent; re-entry cancels a deferred eviction and fresh-bootstraps.
|
|
618
|
+
* The change reaches the server with the next round's list (§8.7).
|
|
624
619
|
*/
|
|
625
620
|
setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
|
|
626
621
|
/** Exact core command result consumed by automatic host loops (§7.5). */
|
|
627
622
|
setWindowCommand(base: WindowBase, units: readonly string[]): Promise<CommandResult<void>>;
|
|
628
623
|
/**
|
|
629
|
-
* The completeness oracle (§4.8
|
|
630
|
-
*
|
|
631
|
-
*
|
|
632
|
-
*
|
|
633
|
-
* NOT answerable in full — the host widens or shows partial, never
|
|
634
|
-
* silently-complete. Registration alone is not completeness: a unit is
|
|
635
|
-
* pending until its subscription completes a bootstrap round (cursor
|
|
636
|
-
* advances past -1 with no resume token held).
|
|
624
|
+
* The completeness oracle (§4.8): which values of a base are windowed-in
|
|
625
|
+
* and which of those are pending. A value is complete once its unit is
|
|
626
|
+
* active and no longer bootstrapping; registration alone is not
|
|
627
|
+
* completeness.
|
|
637
628
|
*/
|
|
638
629
|
windowState(base: WindowBase): WindowState;
|
|
639
630
|
/**
|
|
@@ -703,7 +694,7 @@ export declare class SyncClient {
|
|
|
703
694
|
* Callers that arrive during the same drive with the same budget share that
|
|
704
695
|
* single follow-up. `sync()` keeps rejecting a concurrent `sync()`.
|
|
705
696
|
*
|
|
706
|
-
* §7.
|
|
697
|
+
* §7.8: one drive is bounded by a total deadline (`timeoutMs`, default
|
|
707
698
|
* 60 s). A drive that reaches it rejects with `sync.idle_timeout` and
|
|
708
699
|
* aborts a socket round in flight; the round budget does not bound elapsed
|
|
709
700
|
* time, and a transport that never answers must not hang the caller.
|