@baukit/sync-client 0.7.2 → 0.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baukit/sync-client",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Client-side scheduling, transport, status reporting, and ordering for offline-capable sync loops.",
   "license": "MIT",
   "author": "Patrick Koss",
@@ -50,6 +50,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],

package/src/browser.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  createBrowserSyncEnvironment,
+  type BrowserSyncDocument,
+  type BrowserSyncWindow,
+} from '@baukit/sync-client/browser';
+
+interface MutableBrowserSyncDocument extends BrowserSyncDocument {
+  visibilityState: string;
+  dispatchVisibilityChange(): void;
+  readonly removeVisibility: ReturnType<typeof vi.fn>;
+}
+
+interface TestBrowserSyncWindow extends BrowserSyncWindow {
+  dispatchOnline(): void;
+  readonly removeOnline: ReturnType<typeof vi.fn>;
+}
+
+function documentSource(initialState: string): MutableBrowserSyncDocument {
+  const listeners = new Set<() => void>();
+  const removeVisibility = vi.fn((_type: 'visibilitychange', listener: () => void) => {
+    listeners.delete(listener);
+  });
+  return {
+    visibilityState: initialState,
+    addEventListener: (_type, listener) => {
+      listeners.add(listener);
+    },
+    removeEventListener: removeVisibility,
+    dispatchVisibilityChange: () => {
+      listeners.forEach((listener) => {
+        listener();
+      });
+    },
+    removeVisibility,
+  };
+}
+
+function windowSource(): TestBrowserSyncWindow {
+  const listeners = new Set<() => void>();
+  const removeOnline = vi.fn((_type: 'online', listener: () => void) => {
+    listeners.delete(listener);
+  });
+  return {
+    addEventListener: (_type, listener) => {
+      listeners.add(listener);
+    },
+    removeEventListener: removeOnline,
+    setInterval: vi.fn(() => 1),
+    clearInterval: vi.fn(),
+    dispatchOnline: () => {
+      listeners.forEach((listener) => {
+        listener();
+      });
+    },
+    removeOnline,
+  };
+}
+
+describe('createBrowserSyncEnvironment', () => {
+  it.each([
+    ['hidden', false],
+    ['visible', true],
+  ])('reports %s startup state', (visibilityState, expected) => {
+    const environment = createBrowserSyncEnvironment({
+      document: documentSource(visibilityState),
+      window: windowSource(),
+    });
+
+    expect(environment.isActive()).toBe(expected);
+  });
+
+  it('publishes hidden and visible transitions', () => {
+    const document = documentSource('visible');
+    const active = vi.fn();
+    const environment = createBrowserSyncEnvironment({ document, window: windowSource() });
+    environment.subscribeActive(active);
+
+    document.visibilityState = 'hidden';
+    document.dispatchVisibilityChange();
+    document.visibilityState = 'visible';
+    document.dispatchVisibilityChange();
+
+    expect(active.mock.calls).toEqual([[false], [true]]);
+  });
+
+  it('publishes browser online events', () => {
+    const window = windowSource();
+    const online = vi.fn();
+    const environment = createBrowserSyncEnvironment({
+      document: documentSource('visible'),
+      window,
+    });
+    environment.subscribeOnline(online);
+
+    window.dispatchOnline();
+
+    expect(online).toHaveBeenCalledOnce();
+  });
+
+  it('delegates timers to injected functions', () => {
+    const handle = {};
+    const timers = {
+      setInterval: vi.fn(() => handle),
+      clearInterval: vi.fn(),
+    };
+    const environment = createBrowserSyncEnvironment({
+      document: documentSource('visible'),
+      window: windowSource(),
+      timers,
+    });
+    const callback = vi.fn();
+
+    expect(environment.setInterval(callback, 1234)).toBe(handle);
+    environment.clearInterval(handle);
+
+    expect(timers.setInterval).toHaveBeenCalledWith(callback, 1234);
+    expect(timers.clearInterval).toHaveBeenCalledWith(handle);
+  });
+
+  it('removes both subscriptions once when cleanup repeats', () => {
+    const document = documentSource('visible');
+    const window = windowSource();
+    const environment = createBrowserSyncEnvironment({
+      document,
+      window,
+    });
+    const active = vi.fn();
+    const online = vi.fn();
+    const unsubscribeActive = environment.subscribeActive(active);
+    const unsubscribeOnline = environment.subscribeOnline(online);
+
+    unsubscribeActive();
+    unsubscribeActive();
+    unsubscribeOnline();
+    unsubscribeOnline();
+    document.dispatchVisibilityChange();
+    window.dispatchOnline();
+
+    expect(document.removeVisibility).toHaveBeenCalledOnce();
+    expect(window.removeOnline).toHaveBeenCalledOnce();
+    expect(active).not.toHaveBeenCalled();
+    expect(online).not.toHaveBeenCalled();
+  });
+
+  it('uses browser globals when they are present', () => {
+    const originalDocument = Object.getOwnPropertyDescriptor(globalThis, 'document');
+    const originalWindow = Object.getOwnPropertyDescriptor(globalThis, 'window');
+    const document = documentSource('visible');
+    const window = windowSource();
+    Object.defineProperty(globalThis, 'document', { configurable: true, value: document });
+    Object.defineProperty(globalThis, 'window', { configurable: true, value: window });
+
+    try {
+      expect(createBrowserSyncEnvironment().isActive()).toBe(true);
+    } finally {
+      if (originalDocument) Object.defineProperty(globalThis, 'document', originalDocument);
+      else Reflect.deleteProperty(globalThis, 'document');
+      if (originalWindow) Object.defineProperty(globalThis, 'window', originalWindow);
+      else Reflect.deleteProperty(globalThis, 'window');
+    }
+  });
+
+  it('throws a specific error when browser globals are absent', () => {
+    expect(() => createBrowserSyncEnvironment()).toThrow(
+      'Browser sync environment requires a document',
+    );
+    expect(() => createBrowserSyncEnvironment({ document: documentSource('visible') })).toThrow(
+      'Browser sync environment requires a window',
+    );
+  });
+});

package/src/browser.ts

@@ -0,0 +1,91 @@
+import type { SyncSchedulerEnvironment, SyncSchedulerTimer } from './scheduler.js';
+
+export interface BrowserSyncDocument {
+  readonly visibilityState: string;
+  addEventListener(type: 'visibilitychange', listener: () => void): void;
+  removeEventListener(type: 'visibilitychange', listener: () => void): void;
+}
+
+export interface BrowserSyncWindow {
+  addEventListener(type: 'online', listener: () => void): void;
+  removeEventListener(type: 'online', listener: () => void): void;
+  setInterval(callback: () => void, milliseconds: number): number;
+  clearInterval(handle: number): void;
+}
+
+export interface BrowserSyncTimers {
+  setInterval(callback: () => void, milliseconds: number): SyncSchedulerTimer;
+  clearInterval(handle: SyncSchedulerTimer): void;
+}
+
+export interface BrowserSyncEnvironmentOptions {
+  document?: BrowserSyncDocument;
+  window?: BrowserSyncWindow;
+  timers?: BrowserSyncTimers;
+}
+
+function resolveDocument(document: BrowserSyncDocument | undefined): BrowserSyncDocument {
+  const globalDocument = globalThis.document as BrowserSyncDocument | undefined;
+  const resolved = document ?? globalDocument;
+  if (resolved === undefined) {
+    throw new Error('Browser sync environment requires a document');
+  }
+  return resolved;
+}
+
+function resolveWindow(window: BrowserSyncWindow | undefined): BrowserSyncWindow {
+  const globalWindow = globalThis.window as unknown as BrowserSyncWindow | undefined;
+  const resolved = window ?? globalWindow;
+  if (resolved === undefined) {
+    throw new Error('Browser sync environment requires a window');
+  }
+  return resolved;
+}
+
+function once(cleanup: () => void): () => void {
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    cleanup();
+  };
+}
+
+export function createBrowserSyncEnvironment(
+  options: BrowserSyncEnvironmentOptions = {},
+): SyncSchedulerEnvironment {
+  const browserDocument = resolveDocument(options.document);
+  const browserWindow = resolveWindow(options.window);
+  const timers: BrowserSyncTimers = options.timers ?? {
+    setInterval: (callback, milliseconds) =>
+      browserWindow.setInterval(callback, milliseconds) as unknown as SyncSchedulerTimer,
+    clearInterval: (handle) => {
+      browserWindow.clearInterval(handle as unknown as number);
+    },
+  };
+
+  return {
+    isActive: () => browserDocument.visibilityState === 'visible',
+    subscribeActive(listener) {
+      const onVisibilityChange = () => {
+        listener(browserDocument.visibilityState === 'visible');
+      };
+      browserDocument.addEventListener('visibilitychange', onVisibilityChange);
+      return once(() => {
+        browserDocument.removeEventListener('visibilitychange', onVisibilityChange);
+      });
+    },
+    subscribeOnline(listener) {
+      browserWindow.addEventListener('online', listener);
+      return once(() => {
+        browserWindow.removeEventListener('online', listener);
+      });
+    },
+    setInterval(callback, milliseconds) {
+      return timers.setInterval(callback, milliseconds);
+    },
+    clearInterval(handle) {
+      timers.clearInterval(handle);
+    },
+  };
+}

package/src/conformance.test.ts

@@ -0,0 +1,385 @@
+import { describe, expect, it } from 'vitest';
+import { createSyncConformanceTests } from '@baukit/sync-client/conformance';
+
+import {
+  type SyncConformanceAdapter,
+  type SyncConformanceChange,
+  type SyncConformancePullFault,
+  type SyncConformancePullPage,
+  type SyncConformancePushFailure,
+  type SyncConformanceRejection,
+  type SyncConformanceRow,
+} from './conformance.js';
+import { SyncNetworkError, SyncServerError } from './error.js';
+import { validatePushOutcomeCoverage } from './push-batch.js';
+
+interface FakeClient {
+  cursor: number;
+  outbox: SyncConformanceChange[];
+  rejected: SyncConformanceRejection[];
+  resetCount: number;
+  resetSafe: boolean;
+  rows: Map<string, SyncConformanceRow>;
+}
+
+interface FakeServerRow {
+  row: SyncConformanceRow;
+  revision: number;
+}
+
+interface FakeServer {
+  appliedChangeIds: Set<string>;
+  nextPullFault: SyncConformancePullFault | null;
+  nextPushFailure: SyncConformancePushFailure | null;
+  omitOutcome: boolean;
+  purgeHorizon: number;
+  rejectNextZeroHorizon: number | null;
+  revision: number;
+  rows: Map<string, FakeServerRow>;
+}
+
+interface FakePushRequest {
+  changes: readonly SyncConformanceChange[];
+}
+
+interface FakePushOutcome {
+  entityType: string;
+  entityId: string;
+  status: 'accepted' | 'rejected';
+  reason?: string;
+  serverRow?: SyncConformanceRow;
+}
+
+interface FakePushResponse {
+  outcomes: readonly FakePushOutcome[];
+}
+
+type FakePullResponse = SyncConformancePullPage<SyncConformanceRow, number>;
+
+class FakeStaleCursorError extends Error {
+  constructor(readonly horizon: number) {
+    super('resync_required');
+  }
+}
+
+function key(value: { entityType: string; entityId: string }): string {
+  return `${value.entityType}:${value.entityId}`;
+}
+
+function clone<T>(value: T): T {
+  return structuredClone(value);
+}
+
+function createClient(): FakeClient {
+  return {
+    cursor: 0,
+    outbox: [],
+    rejected: [],
+    resetCount: 0,
+    resetSafe: true,
+    rows: new Map(),
+  };
+}
+
+function createServer(): FakeServer {
+  return {
+    appliedChangeIds: new Set(),
+    nextPullFault: null,
+    nextPushFailure: null,
+    omitOutcome: false,
+    purgeHorizon: 0,
+    rejectNextZeroHorizon: null,
+    revision: 0,
+    rows: new Map(),
+  };
+}
+
+function rowFromChange(change: SyncConformanceChange): SyncConformanceRow {
+  return {
+    entityType: change.entityType,
+    entityId: change.entityId,
+    value: change.value,
+    logicalTime: change.logicalTime,
+    deleted: change.operation === 'delete',
+  };
+}
+
+function applyLocalChange(rows: Map<string, SyncConformanceRow>, row: SyncConformanceRow): void {
+  const existing = rows.get(key(row));
+  if (!existing || row.logicalTime >= existing.logicalTime) {
+    rows.set(key(row), clone(row));
+  }
+}
+
+function dependencyOrder(changes: readonly SyncConformanceChange[]): SyncConformanceChange[] {
+  const remaining = [...changes];
+  const ordered: SyncConformanceChange[] = [];
+  const available = new Set<string>();
+  while (remaining.length > 0) {
+    const index = remaining.findIndex(
+      (candidate) => candidate.dependsOn === undefined || available.has(key(candidate.dependsOn)),
+    );
+    const next = remaining.splice(index < 0 ? 0 : index, 1)[0];
+    if (next === undefined) throw new Error('Expected a pending change');
+    ordered.push(next);
+    available.add(key(next));
+  }
+  return ordered;
+}
+
+function applyServerChange(server: FakeServer, change: SyncConformanceChange): FakePushOutcome {
+  if (server.appliedChangeIds.has(change.changeId)) {
+    return { entityType: change.entityType, entityId: change.entityId, status: 'accepted' };
+  }
+  const existing = server.rows.get(key(change));
+  if (existing && change.logicalTime <= existing.row.logicalTime) {
+    return {
+      entityType: change.entityType,
+      entityId: change.entityId,
+      status: 'rejected',
+      reason: 'superseded',
+      serverRow: clone(existing.row),
+    };
+  }
+  if (change.dependsOn !== undefined && !server.rows.has(key(change.dependsOn))) {
+    return {
+      entityType: change.entityType,
+      entityId: change.entityId,
+      status: 'rejected',
+      reason: 'missing_reference',
+    };
+  }
+  server.revision += 1;
+  server.appliedChangeIds.add(change.changeId);
+  server.rows.set(key(change), { row: rowFromChange(change), revision: server.revision });
+  return { entityType: change.entityType, entityId: change.entityId, status: 'accepted' };
+}
+
+const adapter: SyncConformanceAdapter<
+  FakeClient,
+  FakeServer,
+  SyncConformanceChange,
+  FakePushRequest,
+  FakePushResponse,
+  FakePullResponse,
+  SyncConformanceRow,
+  number
+> = {
+  createScenario: () => ({ clients: [createClient(), createClient()], server: createServer() }),
+  outbox: {
+    enqueue(client, change) {
+      client.outbox.push(clone(change));
+      applyLocalChange(client.rows, rowFromChange(change));
+    },
+    listPending: (client) => clone(client.outbox),
+    pendingId: (pending) => pending.changeId,
+    markAcknowledged(client, pending) {
+      const acknowledged = new Set(pending.map(({ changeId }) => changeId));
+      client.outbox = client.outbox.filter(({ changeId }) => !acknowledged.has(changeId));
+    },
+    recordRejected(client, rejected) {
+      client.rejected.push(...clone(rejected));
+    },
+    listRejected: (client) => clone(client.rejected),
+  },
+  local: {
+    readCursor: (client) => client.cursor,
+    applyPullPage(client, page, options) {
+      const staged = new Map([...client.rows].map(([rowKey, row]) => [rowKey, clone(row)]));
+      let applied = 0;
+      for (const row of page.changes) {
+        const hasPending = client.outbox.some(
+          (pending) => pending.entityType === row.entityType && pending.entityId === row.entityId,
+        );
+        if (!hasPending) applyLocalChange(staged, row);
+        applied += 1;
+        if (applied === options?.failAfterChanges) {
+          throw new Error('injected local transaction failure');
+        }
+      }
+      client.rows = staged;
+      client.cursor = page.nextCursor;
+    },
+    snapshot: (client) => clone([...client.rows.values()]),
+    readPendingState: (client) => ({
+      pending: client.outbox.length > 0,
+      pendingCount: client.outbox.length,
+    }),
+    applySubmittedBatchOutcome(client, outcome) {
+      const acknowledged = new Set(outcome.acknowledged.map(({ changeId }) => changeId));
+      const outbox = client.outbox.filter(({ changeId }) => !acknowledged.has(changeId));
+      const rejected = [...client.rejected, ...clone(outcome.rejected)];
+      const rows = new Map([...client.rows].map(([rowKey, row]) => [rowKey, clone(row)]));
+      for (const row of outcome.rejectedRows ?? []) {
+        const hasPending = outbox.some(
+          (pending) => pending.entityType === row.entityType && pending.entityId === row.entityId,
+        );
+        if (!hasPending) applyLocalChange(rows, row);
+      }
+      client.outbox = outbox;
+      client.rejected = rejected;
+      client.rows = rows;
+    },
+  },
+  wire: {
+    encodePush: (pending) => ({ changes: dependencyOrder(pending) }),
+    decodePush(response, submitted) {
+      validatePushOutcomeCoverage(submitted, response.outcomes, {
+        submittedKey: key,
+        outcomeKey: key,
+      });
+      return {
+        acknowledged: submitted,
+        rejected: response.outcomes
+          .filter((outcome) => outcome.status === 'rejected')
+          .map((outcome) => ({
+            entityType: outcome.entityType,
+            entityId: outcome.entityId,
+            reason: outcome.reason ?? 'rejected',
+          })),
+        rejectedRows: response.outcomes.flatMap((outcome) =>
+          outcome.status === 'rejected' && outcome.serverRow !== undefined
+            ? [clone(outcome.serverRow)]
+            : [],
+        ),
+      };
+    },
+    decodePull: (response) => clone(response),
+    compareCursors: (left, right) => left - right,
+  },
+  server: {
+    acceptPush(server, request) {
+      const failure = server.nextPushFailure;
+      server.nextPushFailure = null;
+      if (failure === 'network') throw new SyncNetworkError('offline');
+      if (failure === 'server') throw new SyncServerError('unavailable', true);
+      const outcomes = request.changes.map((change) => applyServerChange(server, change));
+      if (server.omitOutcome) {
+        server.omitOutcome = false;
+        outcomes.pop();
+      }
+      return Promise.resolve({ outcomes: clone(outcomes) });
+    },
+    servePull(server, cursor, pageSize) {
+      if (cursor === 0 && server.rejectNextZeroHorizon !== null) {
+        const horizon = server.rejectNextZeroHorizon;
+        server.rejectNextZeroHorizon = null;
+        throw new FakeStaleCursorError(horizon);
+      }
+      if (cursor > 0 && cursor < server.purgeHorizon) {
+        throw new FakeStaleCursorError(server.purgeHorizon);
+      }
+      const fault = server.nextPullFault;
+      server.nextPullFault = null;
+      if (fault === 'stall') {
+        return Promise.resolve({ changes: [], nextCursor: cursor, hasMore: true });
+      }
+      if (fault === 'regress') {
+        return Promise.resolve({ changes: [], nextCursor: cursor - 1, hasMore: false });
+      }
+      const available = [...server.rows.values()]
+        .filter(({ revision }) => revision > cursor)
+        .sort((left, right) => left.revision - right.revision);
+      const selected = available.slice(0, pageSize);
+      const hasMore = available.length > selected.length;
+      return Promise.resolve({
+        changes: clone(selected.map(({ row }) => row)),
+        nextCursor: hasMore ? (selected.at(-1)?.revision ?? cursor) : server.revision,
+        hasMore,
+      });
+    },
+    seed(server, change) {
+      const outcome = applyServerChange(server, change);
+      if (outcome.status === 'rejected') throw new Error(outcome.reason);
+    },
+    snapshot: (server) => clone([...server.rows.values()].map(({ row }) => row)),
+    failNextPush(server, failure) {
+      server.nextPushFailure = failure;
+    },
+    omitNextPushOutcome(server) {
+      server.omitOutcome = true;
+    },
+    faultNextPull(server, fault) {
+      server.nextPullFault = fault;
+    },
+  },
+  fullResync: {
+    zeroCursor: 0,
+    decodeStaleCursor(error) {
+      return error instanceof FakeStaleCursorError
+        ? { code: 'resync_required', horizon: error.horizon }
+        : null;
+    },
+    isResetSafe: (client) => client.resetSafe,
+    setResetSafe(client, safe) {
+      client.resetSafe = safe;
+    },
+    reset(client, _stale, options) {
+      client.resetCount += 1;
+      const preserved = new Set([
+        ...client.outbox.map((pending) => key(pending)),
+        ...client.rejected.map((rejected) => key(rejected)),
+      ]);
+      const rows = new Map([...client.rows].map(([rowKey, row]) => [rowKey, clone(row)]));
+      let removed = 0;
+      for (const rowKey of rows.keys()) {
+        if (preserved.has(rowKey)) continue;
+        rows.delete(rowKey);
+        removed += 1;
+        if (removed === options?.failAfterRows) {
+          throw new Error('injected full-resync reset failure');
+        }
+      }
+      client.rows = rows;
+      client.cursor = 0;
+    },
+    readResetCount: (client) => client.resetCount,
+    purgeTombstones(server, rows) {
+      for (const row of rows) {
+        server.revision += 1;
+        server.rows.delete(key(row));
+        server.purgeHorizon = Math.max(server.purgeHorizon, server.revision);
+      }
+      return server.purgeHorizon;
+    },
+    rejectNextZeroCursor(server, horizon) {
+      server.rejectNextZeroHorizon = horizon;
+    },
+  },
+};
+
+describe('sync conformance harness', () => {
+  for (const testCase of createSyncConformanceTests(adapter)) {
+    it(testCase.name, () => testCase.run());
+  }
+
+  it('keeps the full-resync callbacks optional for existing adapters', async () => {
+    const existingAdapter = { ...adapter };
+    delete existingAdapter.fullResync;
+    const existingCases = createSyncConformanceTests(existingAdapter);
+
+    expect(existingCases).toHaveLength(14);
+    for (const testCase of existingCases) await testCase.run();
+  });
+
+  it('keeps the legacy settlement callbacks available during migration', async () => {
+    const scenario = await adapter.createScenario();
+    const [client] = scenario.clients;
+    const pending: SyncConformanceChange = {
+      changeId: 'legacy-change',
+      entityType: 'record',
+      entityId: 'legacy',
+      operation: 'upsert',
+      value: 'legacy',
+      logicalTime: 1,
+    };
+    await adapter.outbox.enqueue(client, pending);
+    await adapter.outbox.markAcknowledged(client, [pending]);
+    await adapter.outbox.recordRejected(client, [
+      { entityType: 'record', entityId: 'legacy', reason: 'legacy' },
+    ]);
+
+    expect(await adapter.outbox.listPending(client)).toEqual([]);
+    expect(await adapter.outbox.listRejected(client)).toHaveLength(1);
+  });
+});