@syncular/client 0.15.46 → 0.15.48

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,
@@ -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(
@@ -398,14 +394,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 +409,6 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
         partial,
         options,
       );
-      consumeEffects(result.effects);
       return result.value;
     },
     purgeLocalData: (input) => requireClient().purgeLocalData(input),