@syncular/client 0.15.13 → 0.15.14

package/src/client.ts

@@ -835,6 +835,7 @@ export class SyncClient {
 
   #statusSnapshot(): SyncStatusSnapshot {
     return {
+      currentSchemaVersion: this.#config.schema.version,
       outbox: listOutbox(this.#db).length,
       upgrading: this.#upgrading,
       leaseState: this.#leaseState,

package/src/index.ts

@@ -9,6 +9,7 @@
  * import no SQLite.
  */
 export * from './apply';
+export * from './availability';
 export * from './blob';
 export * from './client';
 export * from './content-type';

package/src/invalidation.ts

@@ -24,6 +24,7 @@ export interface WindowChange {
 }
 
 export interface SyncStatusSnapshot {
+  readonly currentSchemaVersion: number;
   readonly outbox: number;
   readonly upgrading: boolean;
   readonly leaseState: LeaseState | undefined;

package/src/multi-tab.ts

@@ -46,6 +46,24 @@ export const DEFAULT_FOLLOWER_CALL_TIMEOUT_MS = 10_000;
 /** Max follower calls queued across a handover before we fail loudly. */
 export const DEFAULT_FOLLOWER_QUEUE_LIMIT = 256;
 
+export type LeadershipState =
+  | { readonly state: 'leader'; readonly clientId: string }
+  | {
+      readonly state: 'follower';
+      readonly leaderClientId: string;
+      readonly epoch: number;
+    }
+  | {
+      readonly state: 'waiting';
+      readonly reason: 'handover' | 'leader-announcement';
+    }
+  | {
+      readonly state: 'blocked';
+      readonly reason: 'leader-unreachable';
+      readonly code: typeof FOLLOWER_TIMEOUT_CODE;
+      readonly retryable: true;
+    };
+
 // ---------------------------------------------------------------------------
 // Wire messages
 // ---------------------------------------------------------------------------
@@ -63,6 +81,11 @@ interface ByeMessage {
   readonly fromId: string;
 }
 
+interface BoundMessage {
+  readonly t: 'bound';
+  readonly fromId: string;
+}
+
 interface ReqMessage {
   readonly t: 'req';
   readonly epoch: number;
@@ -96,6 +119,7 @@ interface EventMessage {
 export type MultiTabMessage =
   | HelloMessage
   | ByeMessage
+  | BoundMessage
   | ReqMessage
   | AnnounceMessage
   | ResMessage
@@ -157,6 +181,9 @@ export class LeaderBridge {
     args: readonly unknown[],
   ) => Promise<unknown>;
   readonly #onMessage: (event: { data: MultiTabMessage }) => void;
+  readonly #heartbeatMs: number;
+  readonly #followers = new Set<string>();
+  #heartbeat: ReturnType<typeof setInterval> | undefined;
   #closed = false;
 
   constructor(options: {
@@ -164,11 +191,15 @@ export class LeaderBridge {
     epoch: number;
     clientId: string;
     invoke: (method: string, args: readonly unknown[]) => Promise<unknown>;
+    heartbeatMs?: number;
   }) {
     this.#channel = options.channel;
     this.#epoch = options.epoch;
     this.#clientId = options.clientId;
     this.#invoke = options.invoke;
+    this.#heartbeatMs =
+      options.heartbeatMs ??
+      Math.max(50, Math.floor(DEFAULT_FOLLOWER_CALL_TIMEOUT_MS / 3));
     this.#onMessage = (event) => this.#handle(event.data);
     this.#channel.addEventListener('message', this.#onMessage);
     this.announce();
@@ -194,9 +225,22 @@ export class LeaderBridge {
     if (this.#closed) return;
     if (message.t === 'hello') {
       // A follower joined (or is contesting) — tell it who leads.
+      this.#trackFollower(message.fromId);
       this.announce();
       return;
     }
+    if (message.t === 'bound') {
+      this.#trackFollower(message.fromId);
+      return;
+    }
+    if (message.t === 'bye') {
+      this.#followers.delete(message.fromId);
+      if (this.#followers.size === 0 && this.#heartbeat !== undefined) {
+        clearInterval(this.#heartbeat);
+        this.#heartbeat = undefined;
+      }
+      return;
+    }
     if (message.t !== 'req') return;
     // Ignore requests stamped for a different (dead/older) leader; that
     // follower will re-stamp once it sees our announce.
@@ -237,10 +281,19 @@ export class LeaderBridge {
     );
   }
 
+  #trackFollower(fromId: string): void {
+    this.#followers.add(fromId);
+    if (this.#heartbeat !== undefined) return;
+    this.#heartbeat = setInterval(() => this.announce(), this.#heartbeatMs);
+  }
+
   close(): void {
     if (this.#closed) return;
     this.#closed = true;
+    if (this.#heartbeat !== undefined) clearInterval(this.#heartbeat);
+    this.#heartbeat = undefined;
     this.#channel.removeEventListener('message', this.#onMessage);
+    this.#channel.close();
   }
 }
 
@@ -274,6 +327,7 @@ export class FollowerLink {
   readonly #fromId: string;
   readonly #onEvent: (event: SyncWorkerEvent) => void;
   readonly #onLeaderChange: (clientId: string) => void;
+  readonly #onStateChange: (state: LeadershipState) => void;
   readonly #callTimeoutMs: number;
   readonly #queueLimit: number;
   readonly #onMessage: (event: { data: MultiTabMessage }) => void;
@@ -287,6 +341,12 @@ export class FollowerLink {
   readonly #inFlight = new Map<number, InFlight>();
   #queue: QueuedCall[] = [];
   #closed = false;
+  #state: LeadershipState = {
+    state: 'waiting',
+    reason: 'leader-announcement',
+  };
+  #waitingTimer: ReturnType<typeof setTimeout> | undefined;
+  #blockedTimer: ReturnType<typeof setTimeout> | undefined;
   /** Resolvers waiting for the first `announce` to bind a leader. */
   #bindWaiters: Array<() => void> = [];
 
@@ -295,6 +355,7 @@ export class FollowerLink {
     fromId: string;
     onEvent: (event: SyncWorkerEvent) => void;
     onLeaderChange: (clientId: string) => void;
+    onStateChange?: (state: LeadershipState) => void;
     callTimeoutMs?: number;
     queueLimit?: number;
   }) {
@@ -302,6 +363,7 @@ export class FollowerLink {
     this.#fromId = options.fromId;
     this.#onEvent = options.onEvent;
     this.#onLeaderChange = options.onLeaderChange;
+    this.#onStateChange = options.onStateChange ?? (() => {});
     this.#callTimeoutMs =
       options.callTimeoutMs ?? DEFAULT_FOLLOWER_CALL_TIMEOUT_MS;
     this.#queueLimit = options.queueLimit ?? DEFAULT_FOLLOWER_QUEUE_LIMIT;
@@ -309,6 +371,7 @@ export class FollowerLink {
     this.#channel.addEventListener('message', this.#onMessage);
     // Ask the current leader to announce itself.
     this.#channel.postMessage({ t: 'hello', fromId: this.#fromId });
+    this.#armUnboundDeadline();
   }
 
   get epoch(): number {
@@ -323,6 +386,10 @@ export class FollowerLink {
     return this.#leaderClientId;
   }
 
+  get leadershipState(): LeadershipState {
+    return this.#state;
+  }
+
   /** Whether a leader is currently bound (an announce has been heard). */
   get bound(): boolean {
     return this.#epoch >= 0;
@@ -348,10 +415,12 @@ export class FollowerLink {
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this.#dropBindWaiter(settle);
+        this.#setBlocked();
         reject(
           new ClientSyncError(
             FOLLOWER_TIMEOUT_CODE,
             'no leader announced within the follower bind timeout',
+            true,
           ),
         );
       }, timeoutMs);
@@ -382,6 +451,15 @@ export class FollowerLink {
         new ClientSyncError(WORKER_FAILED_CODE, 'the follower link is closed'),
       );
     }
+    if (this.#state.state === 'blocked') {
+      return Promise.reject(
+        new ClientSyncError(
+          FOLLOWER_TIMEOUT_CODE,
+          'the follower cannot reach the tab that owns the database',
+          true,
+        ),
+      );
+    }
     return new Promise((resolve, reject) => {
       const queued: QueuedCall = {
         method,
@@ -393,20 +471,24 @@ export class FollowerLink {
       if (this.#epoch < 0) {
         // No leader bound yet — queue with a deadline so we never hang.
         if (this.#queue.length >= this.#queueLimit) {
+          this.#setBlocked();
           reject(
             new ClientSyncError(
               FOLLOWER_TIMEOUT_CODE,
               'follower call queue overflow while awaiting a leader',
+              true,
             ),
           );
           return;
         }
         queued.timer = setTimeout(() => {
           this.#dropQueued(queued);
+          this.#setBlocked();
           reject(
             new ClientSyncError(
               FOLLOWER_TIMEOUT_CODE,
               'no leader answered within the follower call timeout',
+              true,
             ),
           );
         }, this.#callTimeoutMs);
@@ -424,10 +506,12 @@ export class FollowerLink {
       reject: queued.reject,
       timer: setTimeout(() => {
         this.#inFlight.delete(reqId);
+        this.#setBlocked();
         queued.reject(
           new ClientSyncError(
             FOLLOWER_TIMEOUT_CODE,
             'the leader did not answer within the follower call timeout',
+            true,
           ),
         );
       }, this.#callTimeoutMs),
@@ -462,6 +546,15 @@ export class FollowerLink {
       this.#epoch = message.epoch;
       this.#leaderClientId = message.clientId;
       if (changed) this.#onLeaderChange(message.clientId);
+      this.#setState({
+        state: 'follower',
+        leaderClientId: message.clientId,
+        epoch: message.epoch,
+      });
+      this.#armBoundDeadline();
+      if (changed) {
+        this.#channel.postMessage({ t: 'bound', fromId: this.#fromId });
+      }
       this.#resolveBindWaiters();
       this.#flushQueue();
       return;
@@ -516,6 +609,8 @@ export class FollowerLink {
     if (this.#closed) return;
     this.#epoch = -1;
     this.#leaderClientId = '';
+    this.#setState({ state: 'waiting', reason: 'handover' });
+    this.#armUnboundDeadline();
     this.#channel.postMessage({
       t: 'hello',
       fromId: this.#fromId,
@@ -526,6 +621,7 @@ export class FollowerLink {
   close(): void {
     if (this.#closed) return;
     this.#closed = true;
+    this.#clearReachabilityTimers();
     this.#channel.removeEventListener('message', this.#onMessage);
     this.#channel.postMessage({ t: 'bye', fromId: this.#fromId });
     const closedError = new ClientSyncError(
@@ -547,4 +643,66 @@ export class FollowerLink {
     this.#resolveBindWaiters();
     this.#channel.close();
   }
+
+  #setState(state: LeadershipState): void {
+    const previous = this.#state;
+    if (
+      previous.state === state.state &&
+      (state.state === 'blocked' ||
+        (state.state === 'waiting' &&
+          previous.state === 'waiting' &&
+          previous.reason === state.reason) ||
+        (state.state === 'follower' &&
+          previous.state === 'follower' &&
+          previous.epoch === state.epoch &&
+          previous.leaderClientId === state.leaderClientId))
+    ) {
+      return;
+    }
+    this.#state = state;
+    try {
+      this.#onStateChange(state);
+    } catch {
+      // A status listener must never break cross-tab coordination.
+    }
+  }
+
+  #setBlocked(): void {
+    this.#clearReachabilityTimers();
+    this.#setState({
+      state: 'blocked',
+      reason: 'leader-unreachable',
+      code: FOLLOWER_TIMEOUT_CODE,
+      retryable: true,
+    });
+  }
+
+  #armUnboundDeadline(): void {
+    this.#clearReachabilityTimers();
+    this.#blockedTimer = setTimeout(
+      () => this.#setBlocked(),
+      this.#callTimeoutMs,
+    );
+  }
+
+  #armBoundDeadline(): void {
+    this.#clearReachabilityTimers();
+    this.#waitingTimer = setTimeout(
+      () => {
+        this.#setState({ state: 'waiting', reason: 'leader-announcement' });
+      },
+      Math.max(1, Math.floor((this.#callTimeoutMs * 2) / 3)),
+    );
+    this.#blockedTimer = setTimeout(
+      () => this.#setBlocked(),
+      this.#callTimeoutMs,
+    );
+  }
+
+  #clearReachabilityTimers(): void {
+    if (this.#waitingTimer !== undefined) clearTimeout(this.#waitingTimer);
+    if (this.#blockedTimer !== undefined) clearTimeout(this.#blockedTimer);
+    this.#waitingTimer = undefined;
+    this.#blockedTimer = undefined;
+  }
 }

package/src/reactive-store.ts

@@ -1,3 +1,7 @@
+import {
+  classifySyncAvailability,
+  type SyncAvailability,
+} from './availability';
 import type {
   CommitOutcome,
   QueryReadSpec,
@@ -11,6 +15,7 @@ import type {
   ClientChangeListener,
   SyncStatusSnapshot,
 } from './invalidation';
+import type { LeadershipState } from './multi-tab';
 import { type WindowBase, windowBaseKey } from './window';
 
 export interface QueryDependency {
@@ -24,11 +29,17 @@ export interface ReactiveQuerySpec<Row> {
   readonly params?: readonly SqlValue[];
   readonly dependencies: readonly QueryDependency[];
   readonly coverage?: readonly WindowCoverage[];
+  readonly mapRow?: (row: Readonly<Record<string, SqlValue>>) => Row;
   readonly rowKey?: (row: Row) => readonly SqlValue[];
   readonly claimCoverage?: boolean;
 }
 
-export type LiveQueryPhase = 'loading' | 'partial' | 'ready' | 'error';
+export type LiveQueryPhase =
+  | 'loading'
+  | 'partial'
+  | 'ready'
+  | 'blocked'
+  | 'error';
 
 export interface LiveQueryResult<Row> {
   readonly rows: readonly Row[];
@@ -36,14 +47,18 @@ export interface LiveQueryResult<Row> {
   readonly revision: bigint | undefined;
   readonly error: Error | undefined;
   readonly isRefreshing: boolean;
+  readonly availability: SyncAvailability;
 }
 
 export interface ReactiveQueryClient {
+  readonly currentSchemaVersion?: number;
   onChange(listener: ClientChangeListener): () => void;
   querySnapshot<Row = Record<string, SqlValue>>(
     spec: QueryReadSpec,
   ): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
   statusSnapshot(): SyncStatusSnapshot | Promise<SyncStatusSnapshot>;
+  leadershipSnapshot?(): LeadershipState | undefined;
+  onLeadershipChange?(listener: (state: LeadershipState) => void): () => void;
   readonly conflicts:
     | readonly unknown[]
     | (() => readonly unknown[] | Promise<readonly unknown[]>);
@@ -72,6 +87,7 @@ export interface WindowRetention {
 
 export interface StatusStoreSnapshot {
   readonly status: SyncStatusSnapshot | undefined;
+  readonly leadership: LeadershipState | undefined;
   readonly error: Error | undefined;
   readonly isLoading: boolean;
 }
@@ -162,6 +178,25 @@ export function canonicalValue(value: unknown): string {
   return encodeCanonical(value, new Set());
 }
 
+const reactiveFunctionIds = new WeakMap<
+  (...args: never[]) => unknown,
+  number
+>();
+let nextReactiveFunctionId = 1;
+
+function reactiveFunctionId(
+  fn: ((...args: never[]) => unknown) | undefined,
+): number | undefined {
+  if (fn === undefined) return undefined;
+  let id = reactiveFunctionIds.get(fn);
+  if (id === undefined) {
+    id = nextReactiveFunctionId;
+    nextReactiveFunctionId += 1;
+    reactiveFunctionIds.set(fn, id);
+  }
+  return id;
+}
+
 function scheduleMicrotask(task: () => void): void {
   if (typeof queueMicrotask === 'function') queueMicrotask(task);
   else void Promise.resolve().then(task);
@@ -277,6 +312,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
     revision: undefined,
     error: undefined,
     isRefreshing: false,
+    availability: { state: 'ready' },
   };
   #subscribers = 0;
   #scheduled = false;
@@ -284,6 +320,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
   #requested = false;
   #desiredRevision = 0n;
   #claimReady: Promise<void> = Promise.resolve();
+  #offStatus: (() => void) | undefined;
 
   constructor(
     readonly store: ReactiveClientStore,
@@ -296,6 +333,10 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
     this.#listeners.add(listener);
     this.#subscribers += 1;
     if (this.#subscribers === 1) {
+      this.#offStatus = this.store.status.subscribe(() =>
+        this.#onAvailabilityChange(),
+      );
+      this.#onAvailabilityChange();
       if (this.spec.claimCoverage !== false) {
         const claims: Promise<void>[] = [];
         for (const coverage of this.spec.coverage ?? []) {
@@ -314,7 +355,11 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
     return () => {
       if (!this.#listeners.delete(listener)) return;
       this.#subscribers -= 1;
-      if (this.#subscribers === 0) this.store.releaseWindowClaims(this.#owner);
+      if (this.#subscribers === 0) {
+        this.#offStatus?.();
+        this.#offStatus = undefined;
+        this.store.releaseWindowClaims(this.#owner);
+      }
     };
   };
 
@@ -333,7 +378,9 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
       next.rows === this.#state.rows &&
       next.phase === this.#state.phase &&
       next.error === this.#state.error &&
-      next.isRefreshing === this.#state.isRefreshing
+      next.isRefreshing === this.#state.isRefreshing &&
+      canonicalValue(next.availability) ===
+        canonicalValue(this.#state.availability)
     ) {
       return;
     }
@@ -358,14 +405,41 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
     });
   }
 
+  #onAvailabilityChange(): void {
+    const availability = this.store.availabilitySnapshot();
+    if (availability.state === 'blocked') {
+      this.#publish({
+        ...this.#state,
+        phase: 'blocked',
+        availability,
+        isRefreshing: false,
+      });
+      return;
+    }
+    const wasBlocked = this.#state.phase === 'blocked';
+    this.#publish({
+      ...this.#state,
+      phase: wasBlocked
+        ? this.#state.rows.length > 0
+          ? 'partial'
+          : 'loading'
+        : this.#state.phase,
+      availability,
+    });
+    if (wasBlocked) this.#requestRead();
+  }
+
   async #readLoop(): Promise<void> {
     if (this.#running || this.#subscribers === 0) return;
     this.#running = true;
     try {
       do {
         this.#requested = false;
+        if (this.store.availabilitySnapshot().state === 'blocked') break;
         await this.#claimReady;
-        const snapshot = await this.store.client.querySnapshot<Row>({
+        const snapshot = await this.store.client.querySnapshot<
+          Record<string, SqlValue>
+        >({
           sql: this.spec.sql,
           ...(this.spec.params !== undefined
             ? { params: this.spec.params }
@@ -374,13 +448,27 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
             ? { coverage: this.spec.coverage }
             : {}),
         });
+        const availability = this.store.availabilitySnapshot();
+        if (availability.state === 'blocked') {
+          this.#publish({
+            ...this.#state,
+            phase: 'blocked',
+            availability,
+            isRefreshing: false,
+          });
+          break;
+        }
         if (snapshot.revision < this.#desiredRevision) {
           this.#requested = true;
           continue;
         }
+        const mappedRows =
+          this.spec.mapRow === undefined
+            ? (snapshot.rows as readonly Row[])
+            : snapshot.rows.map(this.spec.mapRow);
         const rows = reconcileRows(
           this.#state.rows,
-          snapshot.rows,
+          mappedRows,
           this.spec.rowKey,
         );
         const phase: LiveQueryPhase = snapshot.coverage.complete
@@ -394,6 +482,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
           revision: snapshot.revision,
           error: undefined,
           isRefreshing: false,
+          availability,
         });
       } while (this.#requested && this.#subscribers > 0);
     } catch (error) {
@@ -403,6 +492,7 @@ class QueryEntry<Row> implements ExternalStoreEntry<LiveQueryResult<Row>> {
         phase: this.#state.revision === undefined ? 'error' : this.#state.phase,
         error: wrapped,
         isRefreshing: false,
+        availability: this.store.availabilitySnapshot(),
       });
     } finally {
       this.#running = false;
@@ -505,22 +595,34 @@ export class ReactiveClientStore {
   readonly #windows = new Map<string, WindowEntry>();
   readonly #windowClaims = new Map<string, WindowClaimGroup>();
   #offChange: (() => void) | undefined;
+  #offLeadership: (() => void) | undefined;
   readonly status: ExternalStoreEntry<StatusStoreSnapshot>;
   readonly conflicts: ExternalStoreEntry<ConflictStoreSnapshot>;
   readonly outcomes: ExternalStoreEntry<OutcomeStoreSnapshot>;
 
   constructor(readonly client: ReactiveQueryClient) {
     const status = new ValueEntry<StatusStoreSnapshot>(
-      { status: undefined, error: undefined, isLoading: true },
+      {
+        status: undefined,
+        leadership: client.leadershipSnapshot?.(),
+        error: undefined,
+        isLoading: true,
+      },
       async () => {
         try {
           return {
             status: await client.statusSnapshot(),
+            leadership: client.leadershipSnapshot?.(),
             error: undefined,
             isLoading: false,
           };
         } catch (error) {
-          return { status: undefined, error: errorOf(error), isLoading: false };
+          return {
+            status: undefined,
+            leadership: client.leadershipSnapshot?.(),
+            error: errorOf(error),
+            isLoading: false,
+          };
         }
       },
     );
@@ -584,6 +686,9 @@ export class ReactiveClientStore {
       baseKey: windowBaseKey(item.base),
       units: [...new Set(item.units)].sort(),
     }));
+    const mapRowId = reactiveFunctionId(
+      spec.mapRow as ((...args: never[]) => unknown) | undefined,
+    );
     const key = canonicalValue({
       id: spec.id,
       sql: spec.sql,
@@ -591,6 +696,7 @@ export class ReactiveClientStore {
       dependencies,
       coverage,
       claimCoverage: spec.claimCoverage !== false,
+      ...(mapRowId === undefined ? {} : { mapRow: mapRowId }),
     });
     let entry = this.#queries.get(key) as QueryEntry<Row> | undefined;
     if (entry === undefined) {
@@ -600,6 +706,21 @@ export class ReactiveClientStore {
     return entry;
   }
 
+  availabilitySnapshot(): SyncAvailability {
+    const snapshot = this.status.getSnapshot();
+    if (snapshot.status === undefined) {
+      return snapshot.leadership?.state === 'blocked'
+        ? {
+            state: 'blocked',
+            reason: 'leader-unreachable',
+            currentSchemaVersion: this.client.currentSchemaVersion ?? 0,
+            retryable: true,
+          }
+        : { state: 'ready' };
+    }
+    return classifySyncAvailability(snapshot.status, snapshot.leadership);
+  }
+
   /** Retain a composable window working set outside React. The returned
    * handle exposes registration completion and releases only this owner. */
   retainWindow(base: WindowBase, units: readonly string[]): WindowRetention {
@@ -701,6 +822,7 @@ export class ReactiveClientStore {
       if (batch.status !== undefined) {
         (this.status as ValueEntry<StatusStoreSnapshot>).set({
           status: batch.status,
+          leadership: this.client.leadershipSnapshot?.(),
           error: undefined,
           isLoading: false,
         });
@@ -710,11 +832,20 @@ export class ReactiveClientStore {
       }
       if (batch.outcomesChanged) this.outcomes.refresh();
     });
+    this.#offLeadership = this.client.onLeadershipChange?.((leadership) => {
+      const previous = this.status.getSnapshot();
+      (this.status as ValueEntry<StatusStoreSnapshot>).set({
+        ...previous,
+        leadership,
+      });
+    });
   }
 
   dispose(): void {
     this.#offChange?.();
     this.#offChange = undefined;
+    this.#offLeadership?.();
+    this.#offLeadership = undefined;
     for (const group of this.#windowClaims.values()) {
       void Promise.resolve(this.client.setWindow(group.base, []));
     }