@baukit/sync-client 0.7.2 → 0.7.4

package/src/hlc.ts

@@ -0,0 +1,244 @@
+/** Number of logical counter values available in one physical millisecond. */
+export const HLC_COUNTERS_PER_MILLISECOND = 1_000;
+
+/** Largest encoded timestamp JavaScript can represent exactly. */
+export const MAX_HLC_TIMESTAMP = Number.MAX_SAFE_INTEGER;
+
+/** Key passed to an injected HLC store. */
+export const HLC_STORAGE_KEY = 'hlc-state';
+
+/** Serializable state needed to restore a hybrid logical clock. */
+export type HybridLogicalClockState = Readonly<
+  {
+    wallTimeMs: number;
+    counter: number;
+    deviceId: string;
+  } & Record<string, string | number>
+>;
+
+/** Async persistence supplied by a product storage adapter. */
+export interface HlcStorage {
+  get(key: string): Promise<unknown>;
+  set(key: string, value: HybridLogicalClockState): Promise<void>;
+}
+
+/** Physical clock supplied by the host, usually `Date.now`. */
+export type HlcPhysicalClock = () => number;
+
+/** Stable validation and exhaustion error codes. */
+export type HybridLogicalClockErrorCode =
+  | 'invalid_component'
+  | 'invalid_timestamp'
+  | 'exceeds_safe_integer'
+  | 'invalid_physical_clock'
+  | 'empty_device_id';
+
+/** Invalid HLC input or exhausted JavaScript-safe timestamp space. */
+export class HybridLogicalClockError extends Error {
+  public constructor(
+    readonly code: HybridLogicalClockErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'HybridLogicalClockError';
+  }
+}
+
+/** Encodes physical milliseconds and a logical counter into one timestamp. */
+export function encodeHybridLogicalTimestamp(wallTimeMs: number, counter: number): number {
+  if (
+    !Number.isSafeInteger(wallTimeMs) ||
+    wallTimeMs < 0 ||
+    !Number.isInteger(counter) ||
+    counter < 0 ||
+    counter >= HLC_COUNTERS_PER_MILLISECOND
+  ) {
+    throw new HybridLogicalClockError(
+      'invalid_component',
+      'Invalid hybrid logical timestamp component',
+    );
+  }
+
+  const encoded = wallTimeMs * HLC_COUNTERS_PER_MILLISECOND + counter + 1;
+  if (!Number.isSafeInteger(encoded) || encoded < 1) {
+    throw new HybridLogicalClockError(
+      'exceeds_safe_integer',
+      'Hybrid logical timestamp exceeds safe integer range',
+    );
+  }
+  return encoded;
+}
+
+/** Decodes a positive JavaScript-safe timestamp into physical and logical parts. */
+export function decodeHybridLogicalTimestamp(timestamp: number): Readonly<{
+  wallTimeMs: number;
+  counter: number;
+}> {
+  if (!isEncodedTimestamp(timestamp)) {
+    throw new HybridLogicalClockError(
+      'invalid_timestamp',
+      'Invalid encoded hybrid logical timestamp',
+    );
+  }
+
+  const zeroBased = timestamp - 1;
+  return Object.freeze({
+    wallTimeMs: Math.floor(zeroBased / HLC_COUNTERS_PER_MILLISECOND),
+    counter: zeroBased % HLC_COUNTERS_PER_MILLISECOND,
+  });
+}
+
+/** Compares two valid encoded timestamps, or returns `null` for invalid input. */
+export function compareHybridLogicalTimestamps(left: number, right: number): -1 | 0 | 1 | null {
+  if (!isEncodedTimestamp(left) || !isEncodedTimestamp(right)) return null;
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+/** Hybrid logical clock with injected time and optional persistence. */
+export class HybridLogicalClock {
+  readonly #deviceId: string;
+  readonly #physicalClock: HlcPhysicalClock;
+  readonly #storage: HlcStorage | undefined;
+  #state: HybridLogicalClockState;
+  #queue: Promise<void> = Promise.resolve();
+
+  private constructor(
+    deviceId: string,
+    physicalClock: HlcPhysicalClock,
+    storage: HlcStorage | undefined,
+    state: HybridLogicalClockState,
+  ) {
+    this.#deviceId = deviceId;
+    this.#physicalClock = physicalClock;
+    this.#storage = storage;
+    this.#state = state;
+  }
+
+  /** Opens a clock from optional injected storage. Invalid stored state resets to zero. */
+  public static async open(
+    deviceId: string,
+    storage?: HlcStorage,
+    physicalClock: HlcPhysicalClock = Date.now,
+  ): Promise<HybridLogicalClock> {
+    validateDeviceId(deviceId);
+    const persisted = storage ? parseState(await storage.get(HLC_STORAGE_KEY), deviceId) : null;
+    const state = persisted ?? freezeState({ wallTimeMs: 0, counter: 0, deviceId });
+    return new HybridLogicalClock(deviceId, physicalClock, storage, state);
+  }
+
+  /** Returns the next local timestamp after committing its state. */
+  public now(): Promise<number> {
+    return this.#serialized(async () => {
+      const physical = readPhysicalTime(this.#physicalClock);
+      const wallTimeMs = Math.max(physical, this.#state.wallTimeMs);
+      const counter = physical > this.#state.wallTimeMs ? 0 : this.#state.counter + 1;
+      return this.#advance(wallTimeMs, counter);
+    });
+  }
+
+  /** Observes a remote timestamp and returns a committed timestamp ordered after it. */
+  public observe(remoteTimestamp: number): Promise<number> {
+    return this.#serialized(async () => {
+      const remote = decodeHybridLogicalTimestamp(remoteTimestamp);
+      const physical = readPhysicalTime(this.#physicalClock);
+      const wallTimeMs = Math.max(physical, this.#state.wallTimeMs, remote.wallTimeMs);
+      let counter: number;
+      if (wallTimeMs === this.#state.wallTimeMs && wallTimeMs === remote.wallTimeMs) {
+        counter = Math.max(this.#state.counter, remote.counter) + 1;
+      } else if (wallTimeMs === this.#state.wallTimeMs) {
+        counter = this.#state.counter + 1;
+      } else if (wallTimeMs === remote.wallTimeMs) {
+        counter = remote.counter + 1;
+      } else {
+        counter = 0;
+      }
+      return this.#advance(wallTimeMs, counter);
+    });
+  }
+
+  /** Returns an immutable copy of the last committed state. */
+  public snapshot(): HybridLogicalClockState {
+    return freezeState(this.#state);
+  }
+
+  async #advance(wallTimeMs: number, counter: number): Promise<number> {
+    if (counter >= HLC_COUNTERS_PER_MILLISECOND) {
+      wallTimeMs += 1;
+      counter = 0;
+    }
+
+    const timestamp = encodeHybridLogicalTimestamp(wallTimeMs, counter);
+    const nextState = freezeState({ wallTimeMs, counter, deviceId: this.#deviceId });
+    if (this.#storage) await this.#storage.set(HLC_STORAGE_KEY, nextState);
+    this.#state = nextState;
+    return timestamp;
+  }
+
+  #serialized<TResult>(operation: () => Promise<TResult>): Promise<TResult> {
+    if (!this.#storage) return operation();
+
+    const result = this.#queue.then(operation, operation);
+    this.#queue = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }
+}
+
+function isEncodedTimestamp(timestamp: number): boolean {
+  return Number.isSafeInteger(timestamp) && timestamp >= 1;
+}
+
+function parseState(value: unknown, deviceId: string): HybridLogicalClockState | null {
+  if (typeof value !== 'object' || value === null) return null;
+  if (!('wallTimeMs' in value) || !('counter' in value) || !('deviceId' in value)) return null;
+
+  const candidate = value as {
+    readonly wallTimeMs: unknown;
+    readonly counter: unknown;
+    readonly deviceId: unknown;
+  };
+  if (
+    typeof candidate.wallTimeMs !== 'number' ||
+    typeof candidate.counter !== 'number' ||
+    candidate.deviceId !== deviceId
+  ) {
+    return null;
+  }
+
+  try {
+    encodeHybridLogicalTimestamp(candidate.wallTimeMs, candidate.counter);
+  } catch (error) {
+    if (error instanceof HybridLogicalClockError) return null;
+    throw error;
+  }
+  return freezeState({
+    wallTimeMs: candidate.wallTimeMs,
+    counter: candidate.counter,
+    deviceId,
+  });
+}
+
+function readPhysicalTime(clock: HlcPhysicalClock): number {
+  const value = Math.floor(clock());
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new HybridLogicalClockError(
+      'invalid_physical_clock',
+      'Physical clock must return a non-negative safe integer',
+    );
+  }
+  return value;
+}
+
+function validateDeviceId(deviceId: string): void {
+  if (deviceId.trim().length === 0) {
+    throw new HybridLogicalClockError('empty_device_id', 'HLC device id must not be empty');
+  }
+}
+
+function freezeState(state: HybridLogicalClockState): HybridLogicalClockState {
+  return Object.freeze({ ...state });
+}

package/src/index.ts

@@ -0,0 +1,80 @@
+export {
+  SyncAuthError,
+  SyncLocalApplyError,
+  SyncNetworkError,
+  SyncPartitionMismatchError,
+  SyncPayloadCompatibilityError,
+  SyncRateLimitError,
+  SyncServerError,
+  SyncTransportError,
+  syncFailureFromError,
+} from './error.js';
+export type { SyncFailure } from './error.js';
+export {
+  compareHybridLogicalTimestamps,
+  decodeHybridLogicalTimestamp,
+  encodeHybridLogicalTimestamp,
+  HybridLogicalClock,
+  HybridLogicalClockError,
+  HLC_COUNTERS_PER_MILLISECOND,
+  HLC_STORAGE_KEY,
+  MAX_HLC_TIMESTAMP,
+} from './hlc.js';
+export type {
+  HlcPhysicalClock,
+  HlcStorage,
+  HybridLogicalClockErrorCode,
+  HybridLogicalClockState,
+} from './hlc.js';
+export { dependencyRankByOrder, rankPushBatch, validatePushOutcomeCoverage } from './push-batch.js';
+export type {
+  PushCandidate,
+  PushOutcomeCoverageOptions,
+  RankedPushItem,
+  RankPushBatchOptions,
+} from './push-batch.js';
+export { SyncScheduler } from './scheduler.js';
+export type {
+  SyncSchedulerEnvironment,
+  SyncSchedulerOptions,
+  SyncSchedulerRecoverySignal,
+  SyncSchedulerRetry,
+  SyncSchedulerRetryOptions,
+  SyncSchedulerTimer,
+} from './scheduler.js';
+export { deriveInitialSyncState, deriveLocalStoreReadiness, SyncStatusStore } from './store.js';
+export type {
+  InitialPullStatus,
+  InitialSyncState,
+  LocalStoreReadiness,
+  LocalStoreReadinessInput,
+  SyncAttentionItem,
+  SyncFailureUpdate,
+  SyncStatus,
+  SyncStatusHydration,
+  SyncStatusSink,
+  SyncStatusSnapshot,
+  SyncStatusStoreOptions,
+} from './store.js';
+export {
+  commitCursorAfterLocalTransaction,
+  DEFAULT_RETRY_AFTER_FALLBACK_MS,
+  parseRetryAfter,
+  SyncTransport,
+  validatePullPage,
+} from './transport.js';
+export type {
+  CursorCommitOptions,
+  ParseRetryAfterOptions,
+  PullPagePosition,
+  SyncCursorComparator,
+  SyncFetch,
+  SyncFetchResponse,
+  SyncResponseHeaders,
+  SyncPrebuiltRequest,
+  SyncPrebuiltRequestTransportOptions,
+  SyncRequestOptions,
+  SyncRequestInit,
+  SyncFetchTransportOptions,
+  SyncTransportOptions,
+} from './transport.js';

package/src/push-batch.test.ts

@@ -0,0 +1,207 @@
+import { describe, expect, it } from 'vitest';
+
+import { SyncPayloadCompatibilityError } from './error.js';
+import {
+  dependencyRankByOrder,
+  rankPushBatch,
+  validatePushOutcomeCoverage,
+  type PushCandidate,
+} from './push-batch.js';
+
+// A three-level graph: a container owns groups, a group owns leaves.
+const rank = dependencyRankByOrder(['container', 'group', 'leaf']);
+
+function change(
+  entityType: string,
+  entityId: string,
+  changeId = `${entityType}-${entityId}`,
+): PushCandidate {
+  return { changeId, entityType, entityId };
+}
+
+function entityIds(items: readonly { change: PushCandidate }[]): string[] {
+  return items.map(({ change: candidate }) => `${candidate.entityType}:${candidate.entityId}`);
+}
+
+describe('dependencyRankByOrder', () => {
+  it('ranks listed types by position and unknown types last', () => {
+    expect(rank('container')).toBe(0);
+    expect(rank('leaf')).toBe(2);
+    expect(rank('unlisted')).toBe(3);
+  });
+});
+
+describe('rankPushBatch', () => {
+  it('orders a batch parent before child', () => {
+    const pending = [change('leaf', 'l1'), change('container', 'c1'), change('group', 'g1')];
+
+    const batch = rankPushBatch(pending, { rank, batchSize: 10 });
+
+    expect(entityIds(batch)).toEqual(['container:c1', 'group:g1', 'leaf:l1']);
+  });
+
+  it('keeps queue order within one entity type', () => {
+    const pending = [change('leaf', 'l2'), change('leaf', 'l1'), change('leaf', 'l3')];
+
+    const batch = rankPushBatch(pending, { rank, batchSize: 10 });
+
+    expect(entityIds(batch)).toEqual(['leaf:l2', 'leaf:l1', 'leaf:l3']);
+  });
+
+  it('sorts unknown entity types after every listed type', () => {
+    const pending = [change('unlisted', 'u1'), change('leaf', 'l1')];
+
+    const batch = rankPushBatch(pending, { rank, batchSize: 10 });
+
+    expect(entityIds(batch)).toEqual(['leaf:l1', 'unlisted:u1']);
+  });
+
+  it('coalesces repeated changes to one entity, sending the newest', () => {
+    const pending = [
+      change('leaf', 'l1', 'change-1'),
+      change('leaf', 'l1', 'change-2'),
+      change('leaf', 'l1', 'change-3'),
+    ];
+
+    const batch = rankPushBatch(pending, { rank, batchSize: 10 });
+
+    expect(batch).toHaveLength(1);
+    expect(batch[0]?.change.changeId).toBe('change-3');
+    expect(batch[0]?.coveredChangeIds).toEqual(['change-1', 'change-2', 'change-3']);
+  });
+
+  it('keeps the first occurrence position when coalescing, so parents stay ahead', () => {
+    const pending = [
+      change('container', 'c1', 'change-1'),
+      change('leaf', 'l1', 'change-2'),
+      change('container', 'c1', 'change-3'),
+    ];
+
+    const batch = rankPushBatch(pending, { rank, batchSize: 10 });
+
+    expect(entityIds(batch)).toEqual(['container:c1', 'leaf:l1']);
+    expect(batch[0]?.change.changeId).toBe('change-3');
+  });
+
+  it('truncates to the batch size after ordering, keeping parents', () => {
+    const pending = [
+      change('leaf', 'l1'),
+      change('leaf', 'l2'),
+      change('container', 'c1'),
+      change('group', 'g1'),
+    ];
+
+    const batch = rankPushBatch(pending, { rank, batchSize: 2 });
+
+    expect(entityIds(batch)).toEqual(['container:c1', 'group:g1']);
+  });
+
+  it('holds back a parent whose children are unsent, and sends the children', () => {
+    const pending = [
+      change('container', 'c1'),
+      change('group', 'g1'),
+      change('leaf', 'l1'),
+      change('leaf', 'l2'),
+    ];
+    const unsentChildren = new Set(['c1']);
+
+    const batch = rankPushBatch(pending, {
+      rank,
+      batchSize: 10,
+      isHeldBack: (candidate) =>
+        candidate.entityType === 'container' && unsentChildren.has(candidate.entityId),
+    });
+
+    expect(entityIds(batch)).toEqual(['group:g1', 'leaf:l1', 'leaf:l2']);
+  });
+
+  it('sends a held-back parent on the next run once its children settled', () => {
+    const pending = [change('container', 'c1'), change('leaf', 'l1')];
+    const held = new Set(['c1']);
+    const isHeldBack = (candidate: PushCandidate): boolean => held.has(candidate.entityId);
+
+    const first = rankPushBatch(pending, { rank, batchSize: 10, isHeldBack });
+    expect(entityIds(first)).toEqual(['leaf:l1']);
+
+    held.clear();
+    const second = rankPushBatch(pending, { rank, batchSize: 10, isHeldBack });
+    expect(entityIds(second)).toEqual(['container:c1', 'leaf:l1']);
+  });
+
+  it('holds back every coalesced change for the held entity', () => {
+    const pending = [change('container', 'c1', 'change-1'), change('container', 'c1', 'change-2')];
+
+    const batch = rankPushBatch(pending, {
+      rank,
+      batchSize: 10,
+      isHeldBack: (candidate) => candidate.entityId === 'c1',
+    });
+
+    expect(batch).toEqual([]);
+  });
+
+  it('counts held-back entities against neither the batch size nor the order', () => {
+    const pending = [change('container', 'c1'), change('group', 'g1'), change('leaf', 'l1')];
+
+    const batch = rankPushBatch(pending, {
+      rank,
+      batchSize: 2,
+      isHeldBack: (candidate) => candidate.entityType === 'container',
+    });
+
+    expect(entityIds(batch)).toEqual(['group:g1', 'leaf:l1']);
+  });
+
+  it('returns an empty batch for an empty queue', () => {
+    expect(rankPushBatch([], { rank, batchSize: 10 })).toEqual([]);
+  });
+
+  it('carries product-defined change fields through the batch', () => {
+    interface ProductChange extends PushCandidate {
+      payload: string;
+    }
+    const pending: ProductChange[] = [
+      { changeId: 'change-1', entityType: 'leaf', entityId: 'l1', payload: 'first' },
+      { changeId: 'change-2', entityType: 'leaf', entityId: 'l1', payload: 'second' },
+    ];
+
+    const batch = rankPushBatch(pending, { rank, batchSize: 10 });
+
+    expect(batch[0]?.change.payload).toBe('second');
+  });
+});
+
+describe('validatePushOutcomeCoverage', () => {
+  const key = ({ entityType, entityId }: { entityType: string; entityId: string }): string =>
+    `${entityType}:${entityId}`;
+
+  it('returns a complete mix of accepted and rejected outcomes', () => {
+    const submitted = [change('container', 'c1'), change('leaf', 'l1')];
+    const outcomes = [
+      { entityType: 'container', entityId: 'c1', result: 'accepted' },
+      { entityType: 'leaf', entityId: 'l1', result: 'rejected' },
+    ];
+
+    expect(
+      validatePushOutcomeCoverage(submitted, outcomes, {
+        submittedKey: key,
+        outcomeKey: key,
+      }),
+    ).toBe(outcomes);
+  });
+
+  it('rejects a partial outcome set before a caller acknowledges changes', () => {
+    const acknowledged: string[] = [];
+    const submitted = [change('container', 'c1'), change('leaf', 'l1')];
+    const outcomes = [{ entityType: 'container', entityId: 'c1', result: 'accepted' }];
+
+    expect(() => {
+      const validated = validatePushOutcomeCoverage(submitted, outcomes, {
+        submittedKey: key,
+        outcomeKey: key,
+      });
+      acknowledged.push(...validated.map(key));
+    }).toThrow(SyncPayloadCompatibilityError);
+    expect(acknowledged).toEqual([]);
+  });
+});

package/src/push-batch.ts

@@ -0,0 +1,115 @@
+import { SyncPayloadCompatibilityError } from './error.js';
+
+/**
+ * One unsent local change, as baukit sees it.
+ *
+ * `entityType` and `entityId` identify the row the change targets. Baukit never
+ * interprets either: entity names, payloads, and operations stay product-owned.
+ */
+export interface PushCandidate {
+  /** Stable identity of this queued change, unique across the outbox. */
+  changeId: string;
+  entityType: string;
+  entityId: string;
+}
+
+/** One entity's place in the batch, after coalescing and ordering. */
+export interface RankedPushItem<T extends PushCandidate> {
+  /** The newest queued change for this entity; its payload is the one to send. */
+  change: T;
+  /**
+   * Every queued change this item settles, oldest first. One server outcome
+   * clears all of them, because outcomes are keyed by entity, not by change.
+   */
+  coveredChangeIds: string[];
+}
+
+export interface RankPushBatchOptions<T extends PushCandidate> {
+  /**
+   * Dependency rank of an entity type. Lower ranks are sent first, so a parent
+   * type must rank below every type that references it. Unknown types sort last.
+   */
+  rank: (entityType: string) => number;
+  /** Largest number of entities one request may carry. */
+  batchSize: number;
+  /**
+   * Entities whose required children are still unsent, or otherwise not yet
+   * safe to send. Held-back entities are dropped from the batch and retried on
+   * a later run, once their children have been accepted.
+   */
+  isHeldBack?: (change: T) => boolean;
+}
+
+export interface PushOutcomeCoverageOptions<TSubmitted, TOutcome> {
+  submittedKey: (submitted: TSubmitted) => string;
+  outcomeKey: (outcome: TOutcome) => string;
+}
+
+/**
+ * Rejects a response that omits an outcome for any submitted entity.
+ *
+ * Call this before acknowledging accepted or rejected changes. Products supply
+ * key readers because their wire field names remain product-owned.
+ */
+export function validatePushOutcomeCoverage<TSubmitted, TOutcome>(
+  submitted: readonly TSubmitted[],
+  outcomes: readonly TOutcome[],
+  { submittedKey, outcomeKey }: PushOutcomeCoverageOptions<TSubmitted, TOutcome>,
+): readonly TOutcome[] {
+  const outcomeKeys = new Set(outcomes.map(outcomeKey));
+  const missing = new Set(submitted.map(submittedKey).filter((key) => !outcomeKeys.has(key)));
+  if (missing.size > 0) {
+    throw new SyncPayloadCompatibilityError(
+      `The push response omitted outcomes for ${String(missing.size)} submitted entities.`,
+    );
+  }
+  return outcomes;
+}
+
+/**
+ * Orders a push batch parent-before-child and coalesces per entity.
+ *
+ * Queued changes are grouped by `entityType:entityId`. Each group keeps the
+ * position of its first occurrence, so foreign-key order survives coalescing,
+ * and carries the newest change so the request sends current data. Groups are
+ * then sorted by dependency rank, ties broken by that first position, and the
+ * batch is truncated to `batchSize`.
+ *
+ * A parent whose children are unsent is held back rather than reordered: the
+ * server would otherwise see a complete parent while a required child is still
+ * missing.
+ */
+export function rankPushBatch<T extends PushCandidate>(
+  pending: readonly T[],
+  { rank, batchSize, isHeldBack }: RankPushBatchOptions<T>,
+): RankedPushItem<T>[] {
+  const grouped = new Map<string, { change: T; coveredChangeIds: string[]; order: number }>();
+
+  pending.forEach((change, order) => {
+    const key = `${change.entityType}:${change.entityId}`;
+    const existing = grouped.get(key);
+    grouped.set(key, {
+      change,
+      coveredChangeIds: [...(existing?.coveredChangeIds ?? []), change.changeId],
+      order: existing?.order ?? order,
+    });
+  });
+
+  return [...grouped.values()]
+    .filter(({ change }) => !isHeldBack?.(change))
+    .sort(
+      (left, right) =>
+        rank(left.change.entityType) - rank(right.change.entityType) || left.order - right.order,
+    )
+    .slice(0, batchSize)
+    .map(({ change, coveredChangeIds }) => ({ change, coveredChangeIds }));
+}
+
+/**
+ * Builds a {@link RankPushBatchOptions.rank} function from an ordered list of
+ * entity types. Types absent from the list sort after every listed type.
+ */
+export function dependencyRankByOrder(order: readonly string[]): (entityType: string) => number {
+  const ranks = new Map(order.map((entityType, index) => [entityType, index]));
+  return (entityType) => ranks.get(entityType) ?? order.length;
+}