@baukit/sync-client 0.7.2 → 0.7.3

package/src/scheduler.ts

@@ -0,0 +1,260 @@
+/**
+ * Host capabilities the scheduler needs. Products supply timers, foreground
+ * state, and connectivity; baukit never reaches for a global.
+ */
+export interface SyncSchedulerEnvironment {
+  isActive(): boolean;
+  subscribeActive(listener: (active: boolean) => void): () => void;
+  subscribeOnline(listener: () => void): () => void;
+  setInterval(callback: () => void, milliseconds: number): SyncSchedulerTimer;
+  clearInterval(handle: SyncSchedulerTimer): void;
+}
+
+/**
+ * Opaque timer handle returned by the host's `setInterval`. Baukit only stores
+ * it and hands it back to `clearInterval`; its runtime shape is host-defined.
+ */
+export type SyncSchedulerTimer = { readonly __syncSchedulerTimer?: never } & object;
+
+/** A retry the scheduler is about to wait for. */
+export interface SyncSchedulerRetry {
+  readonly error: unknown;
+  /** Counts retries since the last success or wake-up, from 0. */
+  readonly retryIndex: number;
+  readonly delayMs: number;
+}
+
+/** Retries a failed run after a delay the product chooses. */
+export interface SyncSchedulerRetryOptions {
+  /** Retries after a failed run before the scheduler waits for the next trigger. */
+  readonly maxRetries: number;
+  /**
+   * The delay before retry `retryIndex`, or `null` when the failure must not be retried.
+   * `fullJitterBackoffMs` from `@baukit/api-runtime/backoff` gives bounded, jittered delays.
+   */
+  readonly delayMs: (error: unknown, retryIndex: number) => number | null;
+  /** Runs before each wait, for example to show when the next attempt starts. */
+  readonly onRetryScheduled?: (retry: SyncSchedulerRetry) => void;
+}
+
+export interface SyncSchedulerOptions {
+  intervalMs?: number;
+  onError?: (error: unknown) => void;
+  onRecoverySignal?: (signal: SyncSchedulerRecoverySignal) => void;
+  retry?: SyncSchedulerRetryOptions;
+}
+
+export type SyncSchedulerRecoverySignal = 'active' | 'online';
+
+type RetryWake = 'elapsed' | 'triggered' | 'stopped';
+
+const DEFAULT_INTERVAL_MS = 5 * 60 * 1000;
+
+function noop(): void {
+  return;
+}
+
+function validateRetry(retry: SyncSchedulerRetryOptions | undefined): void {
+  if (retry === undefined) {
+    return;
+  }
+  if (!Number.isInteger(retry.maxRetries) || retry.maxRetries < 0) {
+    throw new RangeError('retry.maxRetries must be a non-negative integer');
+  }
+}
+
+/**
+ * Runs one opaque sync callback at most once at a time.
+ *
+ * A trigger that arrives while a run is active joins that run. A follow-up
+ * requested during a run replays the callback once after it settles, so writes
+ * made mid-run are never left unsent without starting a parallel run. With
+ * `retry`, a failed run is retried after the chosen delay; a trigger during
+ * that delay ends it and restarts the retry count.
+ */
+export class SyncScheduler {
+  private readonly intervalMs: number;
+  private readonly onError: (error: unknown) => void;
+  private readonly onRecoverySignal: (signal: SyncSchedulerRecoverySignal) => void;
+  private readonly retry: SyncSchedulerRetryOptions | undefined;
+  private active = false;
+  private started = false;
+  private inFlight: Promise<void> | null = null;
+  private rerunRequested = false;
+  private interval: SyncSchedulerTimer | null = null;
+  private subscriptions: (() => void)[] = [];
+  private wakeRetry: ((reason: RetryWake) => void) | null = null;
+  private stops = 0;
+
+  constructor(
+    private readonly run: () => Promise<unknown>,
+    private readonly environment: SyncSchedulerEnvironment,
+    options: SyncSchedulerOptions = {},
+  ) {
+    validateRetry(options.retry);
+    this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+    this.onError = options.onError ?? noop;
+    this.onRecoverySignal = options.onRecoverySignal ?? noop;
+    this.retry = options.retry;
+  }
+
+  start(): void {
+    if (this.started) {
+      return;
+    }
+    this.started = true;
+    this.active = this.environment.isActive();
+    this.subscriptions = [
+      this.environment.subscribeActive((active) => {
+        this.active = active;
+        this.refreshInterval();
+        if (active) {
+          this.onRecoverySignal('active');
+          void this.trigger();
+        }
+      }),
+      this.environment.subscribeOnline(() => {
+        this.onRecoverySignal('online');
+        if (this.active) {
+          void this.trigger();
+        }
+      }),
+    ];
+    this.refreshInterval();
+    if (this.active) {
+      void this.trigger();
+    }
+  }
+
+  stop(): void {
+    this.started = false;
+    this.stops += 1;
+    this.rerunRequested = false;
+    this.wakeRetry?.('stopped');
+    this.stopInterval();
+    this.subscriptions.forEach((unsubscribe) => {
+      unsubscribe();
+    });
+    this.subscriptions = [];
+  }
+
+  /** Starts a run, or joins the active one and ends its retry delay. */
+  trigger(): Promise<void> {
+    if (this.inFlight) {
+      this.wakeRetry?.('triggered');
+      return this.inFlight;
+    }
+    const task: Promise<void> = Promise.resolve()
+      .then(() => this.runUntilSettled())
+      .finally(() => {
+        if (this.inFlight === task) {
+          this.inFlight = null;
+        }
+      });
+    this.inFlight = task;
+    return task;
+  }
+
+  /** Queues exactly one more run when a run is already active. */
+  requestFollowUp(): Promise<void> {
+    if (this.inFlight) {
+      this.rerunRequested = true;
+      return this.inFlight;
+    }
+    return this.trigger();
+  }
+
+  private async runUntilSettled(): Promise<void> {
+    const stopsAtStart = this.stops;
+    let retryIndex = 0;
+    for (;;) {
+      this.rerunRequested = false;
+      const failure = await this.runOnce();
+      if (failure === null) {
+        retryIndex = 0;
+        if (!this.followUpRequested()) return;
+        continue;
+      }
+      const delayMs = this.retryDelay(failure.error, retryIndex);
+      if (delayMs === null) {
+        if (!this.followUpRequested()) return;
+        continue;
+      }
+      this.retry?.onRetryScheduled?.({ error: failure.error, retryIndex, delayMs });
+      const wake = await this.waitForRetry(delayMs);
+      const stopped = this.stops !== stopsAtStart;
+      if (stopped || (wake === 'elapsed' && this.started && !this.active)) {
+        return;
+      }
+      retryIndex = wake === 'triggered' ? 0 : retryIndex + 1;
+    }
+  }
+
+  /** Read through a method: a follow-up can arrive while `run` is awaited. */
+  private followUpRequested(): boolean {
+    return this.rerunRequested;
+  }
+
+  private async runOnce(): Promise<{ readonly error: unknown } | null> {
+    try {
+      await this.run();
+      return null;
+    } catch (error) {
+      this.onError(error);
+      return { error };
+    }
+  }
+
+  private retryDelay(error: unknown, retryIndex: number): number | null {
+    if (this.retry === undefined || retryIndex >= this.retry.maxRetries) {
+      return null;
+    }
+    let delayMs: number | null;
+    try {
+      delayMs = this.retry.delayMs(error, retryIndex);
+    } catch (delayError) {
+      this.onError(delayError);
+      return null;
+    }
+    if (delayMs !== null && (!Number.isFinite(delayMs) || delayMs < 0)) {
+      this.onError(new RangeError('retry.delayMs must return a finite non-negative number'));
+      return null;
+    }
+    return delayMs;
+  }
+
+  /** The environment has interval timers only, so the delay clears its interval on the first tick. */
+  private waitForRetry(delayMs: number): Promise<RetryWake> {
+    return new Promise((resolve) => {
+      const wake = (reason: RetryWake) => {
+        this.environment.clearInterval(timer);
+        if (this.wakeRetry === wake) {
+          this.wakeRetry = null;
+        }
+        resolve(reason);
+      };
+      const timer = this.environment.setInterval(() => {
+        wake('elapsed');
+      }, delayMs);
+      this.wakeRetry = wake;
+    });
+  }
+
+  private refreshInterval(): void {
+    this.stopInterval();
+    if (!this.started || !this.active) {
+      return;
+    }
+    this.interval = this.environment.setInterval(() => {
+      void this.trigger();
+    }, this.intervalMs);
+  }
+
+  private stopInterval(): void {
+    if (this.interval === null) {
+      return;
+    }
+    this.environment.clearInterval(this.interval);
+    this.interval = null;
+  }
+}

package/src/store.test.ts

@@ -0,0 +1,402 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  deriveInitialSyncState,
+  deriveLocalStoreReadiness,
+  SyncStatusStore,
+  type SyncAttentionItem,
+} from './store.js';
+
+const conflict: SyncAttentionItem = { entityType: 'parent', entityId: 'parent-1' };
+const firstAttemptAt = '2026-08-22T09:59:00Z';
+const firstSuccessAt = '2026-08-22T10:00:00Z';
+const failedAttemptAt = '2026-08-22T10:05:00Z';
+
+describe('SyncStatusStore', () => {
+  it('starts uninitialized and idle', () => {
+    expect(new SyncStatusStore().getSnapshot()).toEqual({
+      status: 'idle',
+      lastAttemptAt: null,
+      lastSuccessAt: null,
+      lastSyncAt: null,
+      error: null,
+      failure: null,
+      retrying: false,
+      retryAt: null,
+      attention: [],
+      pendingCount: 0,
+      initialPullStatus: 'uninitialized',
+      refreshRevision: 0,
+      securityBlock: null,
+    });
+  });
+
+  it('treats the first run as the initial pull and later runs as settled', () => {
+    const store = new SyncStatusStore();
+
+    store.setSyncing(firstAttemptAt);
+    expect(store.getSnapshot()).toMatchObject({ status: 'syncing', initialPullStatus: 'pulling' });
+
+    store.setIdle(firstSuccessAt);
+    store.setSyncing(failedAttemptAt);
+    expect(store.getSnapshot()).toMatchObject({ status: 'syncing', initialPullStatus: 'settled' });
+  });
+
+  it('clears attention and pending work on a successful run', () => {
+    const store = new SyncStatusStore();
+    store.setAttention([conflict], 3);
+
+    store.setIdle(firstSuccessAt);
+
+    expect(store.getSnapshot()).toMatchObject({
+      status: 'idle',
+      lastAttemptAt: firstSuccessAt,
+      lastSuccessAt: firstSuccessAt,
+      lastSyncAt: firstSuccessAt,
+      attention: [],
+      pendingCount: 0,
+      error: null,
+    });
+  });
+
+  it('reports pending when work remains but nothing is actionable', () => {
+    const store = new SyncStatusStore();
+
+    store.setAttention([], 2);
+
+    expect(store.getSnapshot()).toMatchObject({ status: 'pending', pendingCount: 2 });
+  });
+
+  it('reports attention when an actionable rejection exists', () => {
+    const store = new SyncStatusStore();
+
+    store.setAttention([conflict], 1);
+
+    expect(store.getSnapshot()).toMatchObject({ status: 'attention', attention: [conflict] });
+  });
+
+  it('keeps a product-defined attention item intact', () => {
+    type ProductAttention = SyncAttentionItem<{
+      object_entity_type: string;
+      object_entity_id: string;
+      reasons: readonly string[];
+    }>;
+    const item: ProductAttention = {
+      object_entity_type: 'workout_sessions',
+      object_entity_id: 'session-1',
+      reasons: ['future_server_rule'],
+    };
+    const store = new SyncStatusStore<ProductAttention>();
+
+    store.setAttention([item], 1);
+
+    expect(store.getSnapshot().attention).toEqual([item]);
+  });
+
+  it('keeps attention ahead of a transport failure', () => {
+    const store = new SyncStatusStore();
+    store.setAttention([conflict], 1);
+
+    store.setFailure({ kind: 'network' }, 'network down');
+
+    expect(store.getSnapshot()).toMatchObject({ status: 'attention', error: 'network down' });
+  });
+
+  it('reports pending rather than error while unsent work remains', () => {
+    const store = new SyncStatusStore();
+
+    store.setFailure({ kind: 'network' }, 'network down', { pendingCount: 4 });
+
+    expect(store.getSnapshot()).toMatchObject({ status: 'pending', pendingCount: 4 });
+  });
+
+  it('reports error only when nothing is pending or actionable', () => {
+    const store = new SyncStatusStore();
+
+    store.setFailure({ kind: 'network' }, 'network down', { pendingCount: 0 });
+
+    expect(store.getSnapshot()).toMatchObject({ status: 'error', pendingCount: 0 });
+  });
+
+  it('keeps the previous pending count when setFailure omits one', () => {
+    const store = new SyncStatusStore();
+    store.setAttention([], 5);
+
+    store.setFailure({ kind: 'network' }, 'network down');
+
+    expect(store.getSnapshot()).toMatchObject({ status: 'pending', pendingCount: 5 });
+  });
+
+  it('advances only the attempt timestamp when a retry fails', () => {
+    const store = new SyncStatusStore();
+    store.setIdle(firstSuccessAt);
+    store.setSyncing(failedAttemptAt);
+
+    store.setFailure({ kind: 'network' }, 'offline', { attemptAt: failedAttemptAt });
+
+    expect(store.getSnapshot()).toMatchObject({
+      lastAttemptAt: failedAttemptAt,
+      lastSuccessAt: firstSuccessAt,
+      lastSyncAt: firstSuccessAt,
+      failure: { kind: 'network' },
+    });
+  });
+
+  it.each(['network', 'server', 'local_apply'] as const)(
+    'keeps pending work visible after a %s failure',
+    (kind) => {
+      const store = new SyncStatusStore();
+      store.setAttention([], 4);
+
+      store.setFailure({ kind }, 'run failed', { attemptAt: failedAttemptAt });
+
+      expect(store.getSnapshot()).toMatchObject({
+        status: 'pending',
+        pendingCount: 4,
+        failure: { kind },
+        lastSuccessAt: null,
+      });
+    },
+  );
+
+  it('exposes a rate limit and its scheduled retry without reporting offline', () => {
+    const store = new SyncStatusStore();
+    const retryAt = '2026-08-22T10:06:00Z';
+    store.setSyncing(firstAttemptAt);
+
+    store.setFailure({ kind: 'rate_limited', retryAt }, 'too many requests', {
+      attemptAt: failedAttemptAt,
+    });
+
+    expect(store.getSnapshot()).toMatchObject({
+      failure: { kind: 'rate_limited', retryAt },
+      retrying: true,
+      retryAt,
+    });
+    expect(deriveInitialSyncState(store.getSnapshot())).toBe('sync-error-cached');
+  });
+
+  it('records a scheduled network retry separately from its failure', () => {
+    const store = new SyncStatusStore();
+    store.setFailure({ kind: 'network' }, 'offline', {
+      pendingCount: 2,
+      attemptAt: failedAttemptAt,
+    });
+
+    store.setRetrying('2026-08-22T10:06:00Z');
+
+    expect(store.getSnapshot()).toMatchObject({
+      status: 'pending',
+      failure: { kind: 'network' },
+      retrying: true,
+      retryAt: '2026-08-22T10:06:00Z',
+      pendingCount: 2,
+    });
+  });
+
+  it('resumes the settled status after re-authentication', () => {
+    const store = new SyncStatusStore();
+    store.setAttention([], 2);
+    store.setAuth('sign in again');
+    expect(store.getSnapshot()).toMatchObject({
+      status: 'auth',
+      error: 'sign in again',
+      failure: { kind: 'auth' },
+    });
+
+    store.resumeAfterAuth();
+
+    expect(store.getSnapshot()).toMatchObject({ status: 'pending', error: null });
+  });
+
+  it('hydrates a cold start from persisted status', () => {
+    const store = new SyncStatusStore();
+
+    store.hydrate({
+      lastAttemptAt: '2026-08-22T09:01:00Z',
+      lastSuccessAt: '2026-08-22T09:00:00Z',
+      attention: [conflict],
+      pendingCount: 1,
+    });
+
+    expect(store.getSnapshot()).toMatchObject({
+      status: 'attention',
+      lastAttemptAt: '2026-08-22T09:01:00Z',
+      lastSuccessAt: '2026-08-22T09:00:00Z',
+      lastSyncAt: '2026-08-22T09:00:00Z',
+      initialPullStatus: 'settled',
+    });
+  });
+
+  it('stays uninitialized when hydrating a store that never synced', () => {
+    const store = new SyncStatusStore();
+
+    store.hydrate({ lastAttemptAt: null, lastSuccessAt: null });
+
+    expect(store.getSnapshot()).toMatchObject({
+      status: 'idle',
+      initialPullStatus: 'uninitialized',
+    });
+  });
+
+  it('records a security block without losing the message', () => {
+    const store = new SyncStatusStore();
+
+    store.setSecurityBlock('database belongs to another account', {
+      kind: 'partition_mismatch',
+    });
+
+    expect(store.getSnapshot()).toMatchObject({
+      status: 'error',
+      failure: { kind: 'partition_mismatch' },
+      securityBlock: 'database belongs to another account',
+    });
+  });
+
+  it('reset returns the initial snapshot', () => {
+    const store = new SyncStatusStore();
+    store.setAttention([conflict], 3);
+
+    store.reset();
+
+    expect(store.getSnapshot()).toMatchObject({
+      status: 'idle',
+      attention: [],
+      refreshRevision: 0,
+    });
+  });
+
+  it('bumps refreshRevision on every delivered snapshot', () => {
+    const store = new SyncStatusStore();
+
+    store.setIdle(firstSuccessAt);
+    store.setAttention([], 1);
+
+    expect(store.getSnapshot().refreshRevision).toBe(2);
+  });
+
+  it('does not bump refreshRevision when a run merely starts', () => {
+    const store = new SyncStatusStore();
+
+    store.setSyncing();
+
+    expect(store.getSnapshot().refreshRevision).toBe(0);
+  });
+
+  it('notifies subscribers until they unsubscribe', () => {
+    const store = new SyncStatusStore();
+    const listener = vi.fn();
+    const unsubscribe = store.subscribe(listener);
+
+    store.setSyncing();
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(listener).toHaveBeenCalledWith(store.getSnapshot());
+
+    unsubscribe();
+    store.setIdle(firstSuccessAt);
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('deriveLocalStoreReadiness', () => {
+  it('stays uninitialized before the first pull starts', () => {
+    expect(
+      deriveLocalStoreReadiness({
+        initialPullStatus: 'uninitialized',
+        refreshRevision: 0,
+        deliveredRevision: 0,
+        hasData: true,
+      }),
+    ).toBe('uninitialized');
+  });
+
+  it('stays pulling while the initial pull runs', () => {
+    expect(
+      deriveLocalStoreReadiness({
+        initialPullStatus: 'pulling',
+        refreshRevision: 1,
+        deliveredRevision: 1,
+        hasData: false,
+      }),
+    ).toBe('pulling');
+  });
+
+  it('stays pulling while the consumer still holds a stale snapshot', () => {
+    expect(
+      deriveLocalStoreReadiness({
+        initialPullStatus: 'settled',
+        refreshRevision: 2,
+        deliveredRevision: 1,
+        hasData: false,
+      }),
+    ).toBe('pulling');
+  });
+
+  it('reports an empty state only once the newest snapshot is delivered', () => {
+    expect(
+      deriveLocalStoreReadiness({
+        initialPullStatus: 'settled',
+        refreshRevision: 2,
+        deliveredRevision: 2,
+        hasData: false,
+      }),
+    ).toBe('hydrated-empty');
+  });
+
+  it('reports a populated store', () => {
+    expect(
+      deriveLocalStoreReadiness({
+        initialPullStatus: 'settled',
+        refreshRevision: 2,
+        deliveredRevision: 2,
+        hasData: true,
+      }),
+    ).toBe('hydrated-populated');
+  });
+});
+
+describe('deriveInitialSyncState', () => {
+  it('maps an unstarted pull to unknown', () => {
+    expect(
+      deriveInitialSyncState({
+        initialPullStatus: 'uninitialized',
+        lastSuccessAt: null,
+        failure: null,
+        status: 'idle',
+      }),
+    ).toBe('unknown');
+  });
+
+  it('maps a running initial pull to syncing', () => {
+    expect(
+      deriveInitialSyncState({
+        initialPullStatus: 'pulling',
+        lastSuccessAt: null,
+        failure: null,
+        status: 'syncing',
+      }),
+    ).toBe('syncing');
+  });
+
+  it('maps a first-run failure to offline-cached', () => {
+    expect(
+      deriveInitialSyncState({
+        initialPullStatus: 'settled',
+        lastSuccessAt: null,
+        failure: { kind: 'network' },
+        status: 'error',
+      }),
+    ).toBe('offline-cached');
+  });
+
+  it('maps a failure after a past success to settled', () => {
+    expect(
+      deriveInitialSyncState({
+        initialPullStatus: 'settled',
+        lastSuccessAt: '2026-08-22T09:00:00Z',
+        failure: { kind: 'server' },
+        status: 'error',
+      }),
+    ).toBe('settled');
+  });
+});