@syncular/client 0.1.3 → 0.2.0

package/dist/worker-host.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Main-thread side of the worker mode (Direction decision 2) and the
+ * multi-tab topology (TODO 3.2, REVISE B3).
+ *
+ * `createSyncClientHandle` acquires the Web Locks leader lock and, when it
+ * wins, spawns the worker running the WHOLE core — so exactly one core runs
+ * per origin (the lock IS the invariant: a worker is NEVER spawned without
+ * holding the lock). The returned {@link SyncClientHandle} is a thin, fully
+ * async proxy over the `worker-protocol` RPC.
+ *
+ * With `multiTab: true`, a tab that LOSES the election does not resolve to a
+ * dead not-leader handle: it becomes a FOLLOWER (`role === 'follower'`) that
+ * proxies every call to the leader tab over a BroadcastChannel (see
+ * `multi-tab.ts`). When the leader tab closes, its lock releases; the
+ * followers contest, the winner PROMOTES in place — spawns the worker over
+ * the persisted OPFS database and re-announces — and the handle's `role`
+ * flips to `'leader'` with `onRoleChange` firing. The same handle object is
+ * kept across the transition so React bindings hold a stable reference.
+ *
+ * With `multiTab` off (default), behavior is unchanged: the loser is an
+ * `isLeader === false` handle whose calls reject with `client.not_leader`.
+ */
+import type { WakeReason } from '@syncular/core';
+import type { BlobRef, CachedBlob } from './blob.js';
+import type { ConflictRecord, LeaseState, MutationInput, PresencePeer, RejectionRecord, SchemaFloor, SubscribeInput, SyncClientLimits, SyncSummary, WindowState } from './client.js';
+import type { SqlRow, SqlValue } from './database.js';
+import { InvalidationEmitter, type InvalidationListener } from './invalidation.js';
+import { type LeaderLease, type LeaderLock } from './leader-lock.js';
+import { type CrossTabChannel, FollowerLink, LeaderBridge } from './multi-tab.js';
+import type { OutboxCommit } from './outbox.js';
+import type { ClientSchema } from './schema.js';
+import type { SubscriptionRecord } from './state.js';
+import type { WindowBase } from './window.js';
+import { type SyncWorkerEvent, type WorkerDatabaseInit, type WorkerEndpoints, type WorkerErrorShape } from './worker-protocol.js';
+export type HandleRole = 'leader' | 'follower';
+export interface SyncClientHandleConfig {
+    /**
+     * Spawns the worker running `startSyncWorker()` (a factory so bundlers
+     * see `new Worker(new URL(...))` at the call site, and so no worker is
+     * spawned when this tab loses the leader election). Called again on a
+     * follower's promotion.
+     */
+    readonly worker: () => Worker;
+    readonly schema: ClientSchema;
+    readonly database: WorkerDatabaseInit;
+    readonly endpoints: WorkerEndpoints;
+    readonly clientId?: string;
+    readonly limits?: SyncClientLimits;
+    /** Worker-side host loop (§8.4); default true. */
+    readonly autoSync?: boolean;
+    readonly wakeJitterMs?: number;
+    /** Default: Web Locks when available, else single-owner. */
+    readonly leaderLock?: LeaderLock;
+    readonly lockName?: string;
+    /**
+     * Multi-tab followers (TODO 3.2). When true, a tab that loses the leader
+     * election becomes a FOLLOWER that proxies to the leader over a
+     * BroadcastChannel, and contests + promotes when the leader closes. When
+     * false (default), the loser is a dead `isLeader === false` handle.
+     */
+    readonly multiTab?: boolean;
+    /** Cross-tab channel factory (default `BroadcastChannel`); injectable for tests. */
+    readonly channelFactory?: (name: string) => CrossTabChannel;
+    /** Deadline for a follower call (covers the leader-handover gap). */
+    readonly followerCallTimeoutMs?: number;
+    /** Fires when this handle's role changes (follower → leader on promotion). */
+    readonly onRoleChange?: (role: HandleRole) => void;
+    readonly onSyncNeeded?: (reason: 'hello' | WakeReason) => void;
+    readonly onConflict?: (conflict: ConflictRecord) => void;
+    /** A worker-side autoSync round finished (or failed). */
+    readonly onSynced?: (result: {
+        readonly summary?: SyncSummary;
+        readonly error?: WorkerErrorShape;
+    }) => void;
+    /** §7.4.5: schema-bump `upgrading` state changed (reset began/completed). */
+    readonly onUpgrading?: (upgrading: boolean) => void;
+    /** §8.6: presence on a scope key changed. */
+    readonly onPresence?: (scopeKey: string) => void;
+}
+/**
+ * A running worker core owned by THIS tab (the leader). Wraps the worker,
+ * the RPC pending map, and (in multi-tab mode) the `LeaderBridge` relaying
+ * follower requests. Torn down on `close()` or on a graceful demotion.
+ */
+interface LeaderCore {
+    readonly clientId: string;
+    readonly invoke: (method: string, args: readonly unknown[]) => Promise<unknown>;
+    readonly bridge: LeaderBridge | undefined;
+    readonly lease: LeaderLease;
+    close(terminate: boolean): Promise<void>;
+}
+/**
+ * The main-thread proxy: the same logical API as `SyncClient`, every method a
+ * promise. `role` is `'leader'` (owns the worker) or `'follower'` (proxies to
+ * the leader over the channel). Constructed via {@link createSyncClientHandle}.
+ */
+export declare class SyncClientHandle {
+    #private;
+    /** True only for a leader handle. Kept for the pre-multiTab contract. */
+    get isLeader(): boolean;
+    get role(): HandleRole;
+    /** Resolved client id — the leader's; shared by all tabs on this origin. */
+    get clientId(): string;
+    /** @internal — use {@link createSyncClientHandle}. */
+    constructor(internals: {
+        role: HandleRole;
+        clientId: string;
+        core?: LeaderCore;
+        follower?: FollowerLink;
+        invalidation: InvalidationEmitter;
+        presence: Set<(scopeKey: string) => void>;
+        roleListeners?: Set<(role: HandleRole) => void>;
+    });
+    /** @internal — swap this handle from follower to leader (promotion). */
+    __becomeLeader(core: LeaderCore): void;
+    /** @internal — dispatch a worker/relayed event to handle-local listeners. */
+    __dispatchEvent(event: SyncWorkerEvent): void;
+    /**
+     * TODO 3.1 / I1: subscribe to fine-grained invalidation — the identical
+     * surface as `SyncClient.onInvalidate`, so React bindings target one
+     * interface across direct, worker-leader, and follower modes. Returns an
+     * unsubscribe function.
+     */
+    onInvalidate(listener: InvalidationListener): () => void;
+    /**
+     * §8.6: subscribe to presence changes — the identical surface as
+     * `SyncClient.onPresence`. Returns an unsubscribe function.
+     */
+    onPresence(listener: (scopeKey: string) => void): () => void;
+    /** Subscribe to role transitions (follower → leader on promotion). */
+    onRoleChange(listener: (role: HandleRole) => void): () => void;
+    subscribe(input: SubscribeInput): Promise<void>;
+    unsubscribe(id: string): Promise<void>;
+    setWindow(base: WindowBase, units: readonly string[]): Promise<void>;
+    windowState(base: WindowBase): Promise<WindowState>;
+    mutate(mutations: readonly MutationInput[]): Promise<string>;
+    sync(): Promise<SyncSummary>;
+    syncUntilIdle(maxRounds?: number): Promise<SyncSummary>;
+    query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
+    conflicts(): Promise<readonly ConflictRecord[]>;
+    rejections(): Promise<readonly RejectionRecord[]>;
+    schemaFloor(): Promise<SchemaFloor | undefined>;
+    leaseState(): Promise<LeaseState | undefined>;
+    /** §7.4.5: true while a schema-bump reset + first re-bootstrap runs. */
+    upgrading(): Promise<boolean>;
+    syncNeeded(): Promise<boolean>;
+    pendingCommits(): Promise<OutboxCommit[]>;
+    subscriptions(): Promise<SubscriptionRecord[]>;
+    subscription(id: string): Promise<SubscriptionRecord | undefined>;
+    connectRealtime(): Promise<void>;
+    disconnectRealtime(): Promise<void>;
+    /** §8.6: publish/clear a scope-keyed presence document. */
+    setPresence(scopeKey: string, doc: Record<string, unknown> | null): Promise<void>;
+    /** §8.6: the peers currently present on a scope key. */
+    presence(scopeKey: string): Promise<readonly PresencePeer[]>;
+    uploadBlob(bytes: Uint8Array, options?: {
+        readonly mediaType?: string;
+        readonly name?: string;
+    }): Promise<BlobRef>;
+    fetchBlob(blobIdOrRef: string): Promise<CachedBlob>;
+    /** Sever/restore transport + realtime inside the worker (demos). */
+    setOffline(offline: boolean): Promise<void>;
+    /** Close the core (leader) or unbind the link (follower), release leadership. */
+    close(): Promise<void>;
+}
+/**
+ * Acquire leadership, spawn the worker, initialize the core inside it.
+ *
+ * With `multiTab` off: a losing tab resolves to a dead not-leader handle.
+ * With `multiTab` on: a losing tab becomes a FOLLOWER proxying to the leader,
+ * and promotes itself if the leader later closes.
+ */
+export declare function createSyncClientHandle(config: SyncClientHandleConfig): Promise<SyncClientHandle>;
+export {};