@syncular/client 0.15.47 → 0.16.1

package/src/sync-scheduler.ts

@@ -0,0 +1,154 @@
+import type { WakeReason } from '@syncular/core';
+import type { SecurityLifecycle } from './client';
+import type { SyncIntent } from './invalidation';
+
+export interface SyncSchedulerClient {
+  readonly syncNeeded: boolean;
+  readonly securityLifecycle: SecurityLifecycle;
+  syncUntilIdle(maxRounds?: number): Promise<unknown>;
+  onSyncNeeded(
+    listener: (reason: 'startup' | 'hello' | WakeReason) => void,
+  ): () => void;
+  onSyncIntent(listener: (intent: SyncIntent) => void): () => void;
+}
+
+export interface SyncSchedulerOptions {
+  readonly maxRounds?: number;
+  readonly onError?: (error: unknown) => void;
+  readonly now?: () => number;
+  readonly queueMicrotask?: (callback: () => void) => void;
+  readonly schedule?: (callback: () => void, delayMs: number) => () => void;
+}
+
+export interface SyncScheduler {
+  readonly stopped: boolean;
+  stop(): void;
+}
+
+/** Install the event-driven single-flight host loop for a direct client. */
+export function installSyncScheduler(
+  client: SyncSchedulerClient,
+  options: SyncSchedulerOptions = {},
+): SyncScheduler {
+  const now = options.now ?? Date.now;
+  const enqueue = options.queueMicrotask ?? globalThis.queueMicrotask;
+  const schedule =
+    options.schedule ??
+    ((callback: () => void, delayMs: number): (() => void) => {
+      const timer = globalThis.setTimeout(callback, delayMs);
+      return () => globalThis.clearTimeout(timer);
+    });
+  let stopped = false;
+  let running = false;
+  let immediatePending = false;
+  let immediateQueued = false;
+  let backgroundReady = false;
+  let backgroundDue = Number.POSITIVE_INFINITY;
+  let cancelBackground: (() => void) | undefined;
+
+  const report = (error: unknown): void => {
+    if (options.onError !== undefined) {
+      options.onError(error);
+      return;
+    }
+    const root: typeof globalThis & {
+      reportError?: (error: unknown) => void;
+    } = globalThis;
+    if (root.reportError !== undefined) root.reportError(error);
+    else console.error(error);
+  };
+
+  const clearBackground = (): void => {
+    cancelBackground?.();
+    cancelBackground = undefined;
+    backgroundReady = false;
+    backgroundDue = Number.POSITIVE_INFINITY;
+  };
+
+  const queueImmediate = (): void => {
+    immediatePending = true;
+    if (stopped || running || immediateQueued) return;
+    immediateQueued = true;
+    enqueue(() => {
+      immediateQueued = false;
+      if (stopped || !immediatePending) return;
+      immediatePending = false;
+      run();
+    });
+  };
+
+  const run = (): void => {
+    if (stopped || running) return;
+    if (client.securityLifecycle === 'preflight') {
+      immediatePending = false;
+      return;
+    }
+    running = true;
+    backgroundReady = false;
+    void client
+      .syncUntilIdle(options.maxRounds)
+      .catch((error: unknown) => {
+        if (!stopped) report(error);
+      })
+      .finally(() => {
+        running = false;
+        if (stopped) return;
+        if (immediatePending || backgroundReady) {
+          queueImmediate();
+          return;
+        }
+        if (cancelBackground !== undefined && backgroundDue <= now()) {
+          clearBackground();
+          queueImmediate();
+        }
+      });
+  };
+
+  const consume = (intent: SyncIntent): void => {
+    if (stopped) return;
+    if (intent.kind === 'none') {
+      clearBackground();
+      immediatePending = false;
+      return;
+    }
+    if (intent.kind === 'interactive') {
+      clearBackground();
+      queueImmediate();
+      return;
+    }
+    if (immediatePending || immediateQueued) return;
+    clearBackground();
+    backgroundDue = now() + Math.max(0, intent.delayMs);
+    cancelBackground = schedule(
+      () => {
+        cancelBackground = undefined;
+        backgroundDue = Number.POSITIVE_INFINITY;
+        backgroundReady = true;
+        if (!running) queueImmediate();
+      },
+      Math.max(0, intent.delayMs),
+    );
+  };
+
+  const unsubscribeNeeded = client.onSyncNeeded(() => {
+    consume({ kind: 'interactive' });
+  });
+  const unsubscribeIntent = client.onSyncIntent(consume);
+  if (client.syncNeeded && client.securityLifecycle === 'active') {
+    consume({ kind: 'interactive' });
+  }
+
+  return {
+    get stopped() {
+      return stopped;
+    },
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      clearBackground();
+      immediatePending = false;
+      unsubscribeNeeded();
+      unsubscribeIntent();
+    },
+  };
+}

package/src/window.ts

@@ -14,6 +14,71 @@
  */
 import { canonicalScopeJson, type ScopeMap } from '@syncular/core';
 import type { ClientDatabase } from './database';
+import { ClientSyncError } from './errors';
+
+export type TimeBucketUnit = 'month';
+
+const MAX_TIME_BUCKET_MS = 253_402_300_799_999;
+
+function monthBucket(year: number, month: number): string {
+  return `${year.toString().padStart(4, '0')}-${month.toString().padStart(2, '0')}`;
+}
+
+/** Derive the immutable UTC scope value stored when a row is created. */
+export function creationTimeBucket(
+  createdAtMs: number,
+  unit: TimeBucketUnit,
+): string {
+  if (
+    unit !== 'month' ||
+    !Number.isSafeInteger(createdAtMs) ||
+    createdAtMs < 0 ||
+    createdAtMs > MAX_TIME_BUCKET_MS
+  ) {
+    throw new ClientSyncError(
+      'sync.invalid_request',
+      'creationTimeBucket requires a supported unit and a UTC timestamp from 1970 through 9999',
+    );
+  }
+  const date = new Date(createdAtMs);
+  return monthBucket(date.getUTCFullYear(), date.getUTCMonth() + 1);
+}
+
+/** Return a rolling UTC month window ordered from oldest to newest. */
+export function last(
+  count: number,
+  unit: TimeBucketUnit,
+  nowMs = Date.now(),
+): string[] {
+  if (
+    unit !== 'month' ||
+    !Number.isSafeInteger(count) ||
+    count < 1 ||
+    count > 1_200 ||
+    !Number.isSafeInteger(nowMs) ||
+    nowMs < 0 ||
+    nowMs > MAX_TIME_BUCKET_MS
+  ) {
+    throw new ClientSyncError(
+      'sync.invalid_request',
+      'last requires a supported unit, a count from 1 through 1200, and a UTC timestamp from 1970 through 9999',
+    );
+  }
+  const date = new Date(nowMs);
+  const current = date.getUTCFullYear() * 12 + date.getUTCMonth();
+  if (current - (count - 1) < 1970 * 12) {
+    throw new ClientSyncError(
+      'sync.invalid_request',
+      'last requires every returned UTC month to fall from 1970 through 9999',
+    );
+  }
+  const units: string[] = [];
+  for (let offset = count - 1; offset >= 0; offset -= 1) {
+    const value = current - offset;
+    units.push(monthBucket(Math.floor(value / 12), (value % 12) + 1));
+  }
+  return units;
+}
 
 /**
  * A window base: one table, one variable whose values are the window

package/src/worker-entry.ts

@@ -27,7 +27,7 @@ import {
   httpSyncTransport,
   webSocketRealtimeConnector,
 } from './http';
-import type { CommandEffects, SyncIntent } from './invalidation';
+import type { SyncIntent } from './invalidation';
 import type {
   RealtimeConnector,
   SegmentDownloader,
@@ -151,7 +151,7 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     if (
       closed ||
       client === undefined ||
-      client.securityLifecycle === 'preflight'
+      client.securityLifecycle() === 'preflight'
     ) {
       return;
     }
@@ -175,7 +175,7 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
       !autoSync ||
       closed ||
       client === undefined ||
-      client.securityLifecycle === 'preflight' ||
+      client.securityLifecycle() === 'preflight' ||
       intent.kind === 'none'
     ) {
       return;
@@ -211,10 +211,6 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     queueMicrotask(runAutoSync);
   }
 
-  function consumeEffects(effects: CommandEffects): void {
-    consumeSyncIntent(effects.sync);
-  }
-
   function requireClient(): SyncClient {
     if (client === undefined) {
       throw new ClientSyncError(
@@ -375,12 +371,13 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     // `start()` may discover persisted subscriptions/outbox work. Its callback
     // fires before this worker publishes the initialized client, so consume
     // the durable state once here as well; coalescing makes this a single task.
-    if (started.syncNeeded) consumeSyncIntent({ kind: 'interactive' });
+    if (started.statusSnapshot().syncNeeded)
+      consumeSyncIntent({ kind: 'interactive' });
     return { clientId: started.clientId };
   }
 
   const api: WorkerApi = {
-    securityLifecycle: () => requireClient().securityLifecycle,
+    securityLifecycle: () => requireClient().securityLifecycle(),
     beginSecurityPreflight: async () => {
       if (backgroundTimer !== undefined) clearTimeout(backgroundTimer);
       backgroundTimer = undefined;
@@ -398,14 +395,11 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     subscribe: (input) => requireClient().subscribe(input),
     unsubscribe: (id) => requireClient().unsubscribe(id),
     setWindow: async (base, units) => {
-      const result = await requireClient().setWindowCommand(base, units);
-      consumeEffects(result.effects);
+      await requireClient().setWindowCommand(base, units);
     },
     windowState: (base) => requireClient().windowState(base),
     mutate: (mutations) => {
-      const result = requireClient().mutateCommand(mutations);
-      consumeEffects(result.effects);
-      return result.value;
+      return requireClient().mutateCommand(mutations).value;
     },
     patch: (table, rowId, partial, options) => {
       // Same §8.4 rule as `mutate`: a local write must push without the app
@@ -416,7 +410,6 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
         partial,
         options,
       );
-      consumeEffects(result.effects);
       return result.value;
     },
     purgeLocalData: (input) => requireClient().purgeLocalData(input),
@@ -443,17 +436,13 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
         realtime: snapshot.host.realtime,
       });
     },
-    conflicts: () => requireClient().conflicts,
-    rejections: () => requireClient().rejections,
+    conflicts: () => requireClient().conflicts(),
+    rejections: () => requireClient().rejections(),
     commitOutcome: (clientCommitId) =>
       requireClient().commitOutcome(clientCommitId),
     commitOutcomes: (query) => requireClient().commitOutcomes(query),
     resolveCommitOutcome: (input) =>
       requireClient().resolveCommitOutcome(input),
-    schemaFloor: () => requireClient().schemaFloor,
-    leaseState: () => requireClient().leaseState,
-    upgrading: () => requireClient().upgrading,
-    syncNeeded: () => requireClient().syncNeeded,
     pendingCommits: () => requireClient().pendingCommits(),
     subscriptions: () => requireClient().subscriptions(),
     subscription: (id) => requireClient().subscription(id),

package/src/worker-host.ts

@@ -1,3 +1,4 @@
+import type { PromiseMethods } from './client';
 /**
  * Main-thread side of the worker mode and the
  * multi-tab topology.
@@ -25,13 +26,11 @@ import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob';
 import type {
   ConflictRecord,
-  LeaseState,
   MutationInput,
   PresencePeer,
   QueryReadSpec,
   QuerySnapshot,
   RejectionRecord,
-  SchemaFloor,
   SecurityLifecycle,
   SubscribeInput,
   SyncClientLimits,
@@ -244,7 +243,7 @@ interface LeaderCore {
  * promise. `role` is `'leader'` (owns the worker) or `'follower'` (proxies to
  * the leader over the channel). Constructed via {@link createSyncClientHandle}.
  */
-export class SyncClientHandle {
+export class SyncClientHandle implements PromiseMethods<WorkerApi> {
   /** True only for a leader handle. Kept for the pre-multiTab contract. */
   get isLeader(): boolean {
     return this.#role === 'leader';
@@ -324,12 +323,12 @@ export class SyncClientHandle {
       ref: this,
       clientId: () => this.#clientId,
       role: () => this.#role,
-      outbox: async () => (await this.pendingCommits()).length,
+      outbox: async () => (await this.statusSnapshot()).outbox,
       subscriptions: () => this.subscriptions(),
       conflicts: async () => (await this.conflicts()).length,
       rejections: async () => (await this.rejections()).length,
-      syncNeeded: () => this.syncNeeded(),
-      upgrading: () => this.upgrading(),
+      syncNeeded: async () => (await this.statusSnapshot()).syncNeeded,
+      upgrading: async () => (await this.statusSnapshot()).upgrading,
       onInvalidate: (listener) => this.onInvalidate(listener),
     });
   }
@@ -593,23 +592,7 @@ export class SyncClientHandle {
     return this.#call('resolveCommitOutcome', [input]);
   }
 
-  schemaFloor(): Promise<SchemaFloor | undefined> {
-    return this.#call('schemaFloor', []);
-  }
-
-  leaseState(): Promise<LeaseState | undefined> {
-    return this.#call('leaseState', []);
-  }
-
   /** §7.4.5: true while a schema-bump reset + first re-bootstrap runs. */
-  upgrading(): Promise<boolean> {
-    return this.#call('upgrading', []);
-  }
-
-  syncNeeded(): Promise<boolean> {
-    return this.#call('syncNeeded', []);
-  }
-
   pendingCommits(): Promise<OutboxCommit[]> {
     return this.#call('pendingCommits', []);
   }

package/src/worker-protocol.ts

@@ -20,13 +20,11 @@ import type { WakeReason } from '@syncular/core';
 import type { BlobRef, CachedBlob } from './blob';
 import type {
   ConflictRecord,
-  LeaseState,
+  ClientSnapshotMethods,
   MutationInput,
   PresencePeer,
   QueryReadSpec,
   QuerySnapshot,
-  RejectionRecord,
-  SchemaFloor,
   SecurityLifecycle,
   SubscribeInput,
   SyncClientLimits,
@@ -34,27 +32,15 @@ import type {
   WindowState,
 } from './client';
 import type { SqlRow, SqlValue } from './database';
-import type {
-  ClientDiagnosticsRequest,
-  ClientDiagnosticsSnapshot,
-} from './diagnostics';
+import type { ClientDiagnosticsSnapshot } from './diagnostics';
 import type { EncryptionKeyringConfig } from './encryption';
-import type {
-  ClientChangeBatch,
-  LocalRevision,
-  SyncStatusSnapshot,
-} from './invalidation';
+import type { ClientChangeBatch, LocalRevision } from './invalidation';
 import type { LocalDataPurgeInput, LocalDataPurgeResult } from './local-purge';
 import type {
   LocalDataRebootstrapInput,
   LocalDataRebootstrapResult,
 } from './local-rebootstrap';
 import type { OutboxCommit } from './outbox';
-import type {
-  CommitOutcome,
-  CommitOutcomeQuery,
-  ResolveCommitOutcomeInput,
-} from './outcomes';
 import type { ClientSchema } from './schema';
 import type { SubscriptionRecord } from './state';
 import type { WindowBase } from './window';
@@ -137,7 +123,10 @@ export interface WorkerSecurityActivation {
 // The logical API — the one shared shape (worker implements, handle projects)
 // ---------------------------------------------------------------------------
 
-export interface WorkerApi {
+export interface WorkerApi extends Omit<
+  ClientSnapshotMethods,
+  'querySnapshot'
+> {
   securityLifecycle(): SecurityLifecycle;
   beginSecurityPreflight(): Promise<void>;
   activateSecurity(options?: WorkerSecurityActivation): Promise<void>;
@@ -166,21 +155,6 @@ export interface WorkerApi {
   query(sql: string, params?: readonly SqlValue[]): SqlRow[];
   querySnapshot(spec: QueryReadSpec): QuerySnapshot;
   localRevision(): LocalRevision;
-  statusSnapshot(): SyncStatusSnapshot;
-  diagnosticsSnapshot(
-    request?: ClientDiagnosticsRequest,
-  ): ClientDiagnosticsSnapshot;
-  conflicts(): readonly ConflictRecord[];
-  rejections(): readonly RejectionRecord[];
-  commitOutcome(clientCommitId: string): CommitOutcome | undefined;
-  commitOutcomes(query?: CommitOutcomeQuery): readonly CommitOutcome[];
-  resolveCommitOutcome(input: ResolveCommitOutcomeInput): CommitOutcome;
-  schemaFloor(): SchemaFloor | undefined;
-  /** §7.3.5: the opaque auth-lease state, or undefined. */
-  leaseState(): LeaseState | undefined;
-  /** §7.4.5: true while a schema-bump reset + first re-bootstrap runs. */
-  upgrading(): boolean;
-  syncNeeded(): boolean;
   pendingCommits(): OutboxCommit[];
   subscriptions(): SubscriptionRecord[];
   subscription(id: string): SubscriptionRecord | undefined;

package/dist/realtime-supervisor-observation.d.ts

@@ -1,8 +0,0 @@
-/**
- * Preserve supervisor observation across a facade without transferring
- * transport ownership or exposing the source client. Binding packages use
- * this when they normalize a client into another object identity.
- */
-export declare function linkRealtimeSupervisorObservation<Target extends object>(target: Target, source: object): Target;
-/** @internal Resolve one facade hop for the supervisor attachment lookup. */
-export declare function realtimeSupervisorObservationSource(target: object): object | undefined;

package/dist/realtime-supervisor-observation.js

@@ -1,15 +0,0 @@
-const observationSources = new WeakMap();
-/**
- * Preserve supervisor observation across a facade without transferring
- * transport ownership or exposing the source client. Binding packages use
- * this when they normalize a client into another object identity.
- */
-export function linkRealtimeSupervisorObservation(target, source) {
-    if (target !== source)
-        observationSources.set(target, source);
-    return target;
-}
-/** @internal Resolve one facade hop for the supervisor attachment lookup. */
-export function realtimeSupervisorObservationSource(target) {
-    return observationSources.get(target);
-}

package/src/realtime-supervisor-observation.ts

@@ -1,21 +0,0 @@
-const observationSources = new WeakMap<object, object>();
-
-/**
- * Preserve supervisor observation across a facade without transferring
- * transport ownership or exposing the source client. Binding packages use
- * this when they normalize a client into another object identity.
- */
-export function linkRealtimeSupervisorObservation<Target extends object>(
-  target: Target,
-  source: object,
-): Target {
-  if (target !== source) observationSources.set(target, source);
-  return target;
-}
-
-/** @internal Resolve one facade hop for the supervisor attachment lookup. */
-export function realtimeSupervisorObservationSource(
-  target: object,
-): object | undefined {
-  return observationSources.get(target);
-}