@syncular/client 0.59.0 → 0.60.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.
Files changed (66) hide show
  1. package/README.md +27 -27
  2. package/dist/apply.d.ts +6 -5
  3. package/dist/apply.js +52 -25
  4. package/dist/authority.js +21 -16
  5. package/dist/blob.d.ts +4 -4
  6. package/dist/bun-database.js +3 -16
  7. package/dist/client.d.ts +57 -66
  8. package/dist/client.js +701 -796
  9. package/dist/devtools.d.ts +2 -2
  10. package/dist/devtools.js +3 -3
  11. package/dist/diagnostics.d.ts +17 -28
  12. package/dist/diagnostics.js +1 -2
  13. package/dist/errors.d.ts +1 -1
  14. package/dist/errors.js +1 -1
  15. package/dist/failed-overlay.js +4 -1
  16. package/dist/http.js +10 -4
  17. package/dist/invalidation.d.ts +3 -4
  18. package/dist/invalidation.js +9 -22
  19. package/dist/native-bridge.d.ts +7 -16
  20. package/dist/native-bridge.js +16 -41
  21. package/dist/node-database.js +16 -25
  22. package/dist/outbox.js +1 -0
  23. package/dist/progress.d.ts +2 -2
  24. package/dist/query-guard.d.ts +15 -6
  25. package/dist/query-guard.js +38 -6
  26. package/dist/reactive-store.js +2 -2
  27. package/dist/remote.js +9 -9
  28. package/dist/schema.d.ts +3 -2
  29. package/dist/schema.js +28 -12
  30. package/dist/state.d.ts +69 -36
  31. package/dist/state.js +178 -89
  32. package/dist/sync-scheduler.js +2 -2
  33. package/dist/transport.d.ts +2 -2
  34. package/dist/window.d.ts +30 -52
  35. package/dist/window.js +33 -77
  36. package/dist/worker-core.js +6 -6
  37. package/dist/worker-host.d.ts +9 -8
  38. package/dist/worker-host.js +11 -11
  39. package/dist/worker-protocol.d.ts +9 -8
  40. package/package.json +3 -3
  41. package/src/apply.ts +87 -33
  42. package/src/authority.ts +31 -17
  43. package/src/blob.ts +4 -3
  44. package/src/bun-database.ts +9 -14
  45. package/src/client.ts +886 -1037
  46. package/src/devtools.ts +5 -5
  47. package/src/diagnostics.ts +17 -37
  48. package/src/errors.ts +1 -1
  49. package/src/failed-overlay.ts +6 -1
  50. package/src/http.ts +13 -8
  51. package/src/invalidation.ts +9 -29
  52. package/src/native-bridge.ts +22 -58
  53. package/src/node-database.ts +26 -27
  54. package/src/outbox.ts +1 -0
  55. package/src/progress.ts +2 -2
  56. package/src/query-guard.ts +45 -8
  57. package/src/reactive-store.ts +2 -2
  58. package/src/remote.ts +12 -16
  59. package/src/schema.ts +48 -13
  60. package/src/state.ts +246 -125
  61. package/src/sync-scheduler.ts +2 -2
  62. package/src/transport.ts +2 -2
  63. package/src/window.ts +55 -134
  64. package/src/worker-core.ts +6 -6
  65. package/src/worker-host.ts +13 -16
  66. 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 ScopeMap, type WakeReason } from '@syncular/core';
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 ClientDiagnosticsRequest, type ClientDiagnosticsSnapshot, type RealtimePolicy } from './diagnostics.js';
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 SubscriptionRecord } from './state.js';
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
- /** Subscriptions still mid-bootstrap (resume token pending). */
75
+ /** Ids of the units still catching up after the round (§4.1). */
76
76
  readonly bootstrapping: readonly string[];
77
- /** Subscriptions reset via `sync.cursor_expired` (re-pull needed). */
77
+ /** Units reset via `sync.cursor_expired` (§4.6). */
78
78
  readonly resets: readonly string[];
79
- /** Subscriptions revoked this round (§3.3 purge ran). */
79
+ /** Units revoked this round (§3.3 purge ran). */
80
80
  readonly revoked: readonly string[];
81
- /** Subscriptions stopped by a fatal configuration error (§3.3/§5.6
82
- * fail-closed: no local scope-column mapping). */
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.7: a strict positive round count. Default: 20. */
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.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, subscriptions,
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
- * Registered units whose bootstrap has not yet completed (§4.8): the
293
- * unit's subscription still has `cursor: -1` (never synced) or holds a
294
- * resume token (mid-bootstrap). Between `setWindow` and the bootstrap
295
- * landing, the local replica for a pending unit may be empty or partial —
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 subscription as persisted in the snapshot,
341
- * never the mutable owner cache. `unknown` means the client does not currently
342
- * hold the subscription (never registered, forgotten, or removed) and carries
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 SubscriptionCatchup = {
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` with `cursor >= 0` and no resume token. */
349
+ /** True only for an `active` unit that is live or post-bootstrap. */
356
350
  readonly bootstrapComplete: boolean;
357
- /** True only for `active` while a resume token remains or `cursor < 0`. */
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
- readonly subscriptions?: readonly string[];
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 subscriptions: readonly SubscriptionCatchup[];
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, subscription
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 subscription's persisted catch-up state (never the owner cache). */
474
- subscriptionCatchup(id: string): SubscriptionCatchup;
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(request?: ClientDiagnosticsRequest): ClientDiagnosticsSnapshot;
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
- subscriptions(): SubscriptionRecord[];
600
- subscription(id: string): SubscriptionRecord | undefined;
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
- subscribe(input: SubscribeInput): void;
597
+ /** Register one unit (§4.1) and return its id. */
598
+ subscribe(scopes: UnitScopes): string;
603
599
  /**
604
- * Register several subscriptions in one local transaction: the same rules
605
- * as `subscribe` for each input, and one commit for all of them (on OPFS a
606
- * commit costs milliseconds, so a cold start with hundreds of
607
- * registrations pays it once). An error rolls back every registration of
608
- * the call.
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 live window units for a base (§4.8): a value-sharded family of
614
- * subscriptions, one per unit. Computes the diff against the registry —
615
- * added units get fresh subscriptions (image-lane bootstrap on the next
616
- * sync); removed units are unsubscribed with their first eviction chunk
617
- * in one local transaction (E1–E4). Idempotent: calling with the same units is a
618
- * no-op. Re-entry (a unit removed then re-added) cancels any deferred
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 I3): which units of a base are windowed-in
630
- * locally, which of those are still bootstrap-pending, and thereby the
631
- * per-unit verdict a live query renders "may be partial" from. A query
632
- * whose scope footprint includes an un-windowed OR still-pending unit is
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.7: one drive is bounded by a total deadline (`timeoutMs`, default
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.