@procedures/store 0.17.3 → 0.18.0

package/dist/storage/tab-coordinator.d.ts

@@ -0,0 +1,284 @@
+/**
+ * The coordinator of the tabs of a browser (roadmap CLI-25, server stack D9).
+ *
+ * Each tab of a page has a local copy of a collection. Without a coordinator, each tab runs its own
+ * `HybridStorage`: each tab pulls, each tab pushes, and the tabs share one queue store. A
+ * `TabCoordinator` lets one leader tab run the sync, and the other tabs copy its changes.
+ *
+ * - The election uses the Web Locks API: the tab that holds the lock of the coordinator is the
+ *   leader. When the leader closes, or the browser closes its tab, the lock goes to the next tab.
+ * - Only the leader makes a `HybridStorage`, with `capture: "observe"` on the local copy. The
+ *   followers make no remote call, and they run no timer of a sync.
+ * - The tabs send the change batches of their local copies on a `BroadcastChannel`. A tab gives the
+ *   batches of the other tabs to its observers, with their origins.
+ * - The leader captures the batches of the followers: its `HybridStorage` queues them and pushes
+ *   them. Only the leader writes to the queue store, so the tabs can share it by its name.
+ * - A follower keeps each own batch until the leader acknowledges it. The leader acknowledges a
+ *   batch when its queue store holds it. A new leader gets the batches that no leader
+ *   acknowledged.
+ * - Without the Web Locks API or `BroadcastChannel`, the coordinator is in the single mode: the tab
+ *   is the leader at once, and it opens no channel.
+ *
+ * The limits:
+ * - When the leader stops during a push, the next leader sends the operation again: the delivery to
+ *   the remote is at least once.
+ * - With a shared local copy, a pull of the leader can come between the write of a follower and its
+ *   capture. The tabs agree again after the push and the next pull.
+ * - The load of the queue in a new leader writes the queued operations to the local copy again, and
+ *   the observers get them again with the origin `syncOrigin`.
+ *
+ * Nothing in this module reads a global value when it loads: Node can import it. The coordinator
+ * reads `navigator.locks` and `BroadcastChannel` when it starts, and a test gives its own.
+ */
+import type { CollectionStorage, StorageObserver } from "@procedures/collections";
+import { type ListenerErrorHandler } from "@procedures/collections";
+import { HybridStorage, type HybridStorageOptions, type LocalCopyStorage } from "./hybrid.js";
+/** The signal that stops a lock request that waits. The `AbortSignal` of a browser fits it. */
+export interface TabAbortSignalLike {
+    readonly aborted: boolean;
+}
+/**
+ * The part of the Web Locks API that the coordinator uses: `navigator.locks` of a browser. The
+ * lock is exclusive. The manager calls `callback` when the tab gets the lock, and it holds the lock
+ * until the promise of `callback` settles. A test gives a lock manager in memory.
+ */
+export interface TabLockManagerLike {
+    request(name: string, options: {
+        readonly signal?: TabAbortSignalLike;
+    }, callback: (lock: unknown) => Promise<void>): Promise<unknown>;
+}
+/**
+ * A channel to the other tabs of the same origin: a `BroadcastChannel` of a browser. A message goes
+ * to each other channel of the same name, as a structured clone. The channel does not get its own
+ * messages.
+ */
+export interface TabChannelLike {
+    postMessage(message: unknown): void;
+    onmessage: ((event: any) => void) | null;
+    close(): void;
+}
+/** The function that opens a channel with a name. The default opens a `BroadcastChannel`. */
+export type TabChannelFactory = (name: string) => TabChannelLike;
+/**
+ * The role of a tab.
+ *
+ * - `follower`: the tab waits for the lock. It copies the changes of the other tabs, and it sends
+ *   its own changes to the leader.
+ * - `leader`: the tab holds the lock, and its `HybridStorage` runs the sync.
+ * - `single`: the browser has no Web Locks API or no `BroadcastChannel`. The tab runs the sync
+ *   alone, and it opens no channel.
+ * - `closed`: after `close()`.
+ */
+export type TabRole = "follower" | "leader" | "single" | "closed";
+/** The options of a `TabCoordinator`. */
+export interface TabCoordinatorOptions<T> {
+    /**
+     * The name of the coordinator: one name for each collection, the same in each tab. The lock and
+     * the channel get it. Give a name for each tenant too.
+     */
+    name: string;
+    /** The local copy of this tab. It must have `observe()`. The application reads it and writes to it. */
+    local: LocalCopyStorage<T>;
+    /**
+     * The kind of the local copy.
+     *
+     * - `"shared"`: the tabs open the same durable local copy, for example an `IndexedDbStorage` of
+     *   one database. A tab does not write the batches of another tab, because they are in the copy.
+     * - `"tab"`: each tab has its own local copy, for example a SignalDB collection or an
+     *   `InMemoryStorage`. A tab writes the batches of the other tabs to its copy.
+     */
+    copy: "shared" | "tab";
+    /** The function that makes the remote of the `HybridStorage`. Only the leader calls it. */
+    remote: () => CollectionStorage<T>;
+    /**
+     * The options of the `HybridStorage` of the leader. The coordinator sets `local` and
+     * `capture: "observe"`. Give the same `queueStore` and `syncState` in each tab, for example an
+     * `IndexedDbQueueStore` of one database: a new leader loads the queue of the last leader.
+     */
+    hybrid?: Omit<HybridStorageOptions, "local" | "capture">;
+    /**
+     * The lock manager. `null` sets the single mode.
+     * @default `navigator.locks`, when the browser has it
+     */
+    locks?: TabLockManagerLike | null;
+    /**
+     * The function that opens the channel. `null` sets the single mode.
+     * @default a function that opens a `BroadcastChannel`, when the browser has it
+     */
+    channel?: TabChannelFactory | null;
+    /**
+     * The function that gets the errors: of the lock, of the channel, of a write to the local copy,
+     * of the `HybridStorage` and of the observers. The default throws the error again in a microtask.
+     */
+    onError?: ListenerErrorHandler;
+}
+/**
+ * One leader tab runs the sync of a `HybridStorage`, and the other tabs copy its changes.
+ *
+ * @example
+ * ```typescript
+ * import { ApiStorage, IndexedDbQueueStore, IndexedDbStorage, IndexedDbSyncStateStore, TabCoordinator } from "@procedures/store/browser";
+ *
+ * const local = new IndexedDbStorage<User>("users");
+ * const users = new TabCoordinator<User>({
+ *   name: "users",
+ *   local,
+ *   copy: "shared",
+ *   remote: () => new ApiStorage(client, { collection: "users" }),
+ *   hybrid: {
+ *     mode: "write-back",
+ *     queueStore: new IndexedDbQueueStore("users-queue"),
+ *     syncState: new IndexedDbSyncStateStore("users-sync"),
+ *   },
+ * });
+ *
+ * users.observe((batch) => render(batch)); // The changes of this tab and of the other tabs
+ * await local.set("1", { name: "Ada" }); // The leader pushes the write
+ * ```
+ */
+export declare class TabCoordinator<T> {
+    /** The id of this tab: a new random id for each coordinator. */
+    readonly id: string;
+    /** The name of the lock and of the channel. */
+    readonly lockName: string;
+    private readonly local;
+    private readonly shared;
+    private readonly makeRemote;
+    private readonly hybridOptions;
+    /** The origin of the `HybridStorage` and of the writes of the coordinator to the local copy. */
+    private readonly tag;
+    private readonly writeOptions;
+    private readonly onError;
+    private readonly observers;
+    private readonly roleListeners;
+    /** The observers that the `HybridStorage` of the leader adds to its local copy: the capture */
+    private readonly captures;
+    private currentRole;
+    private channel;
+    private hybrid;
+    /** The stop of the observer of the changes of this tab: on the local copy, or on the `HybridStorage` of the leader */
+    private stopTap;
+    /** True while the leader gives a batch of another tab to the capture of its `HybridStorage` */
+    private capturing;
+    /** The number of the last batch of this tab */
+    private seq;
+    /** The batches of this tab that no leader acknowledged, the oldest first */
+    private outbox;
+    /** The number of the last batch of each other tab that this tab copied */
+    private readonly seen;
+    /** In the leader: the number of the last batch of each tab that the leader captured. A tab without a hello is not here. */
+    private readonly captured;
+    /** The batches of the other tabs: they reach the local copy and the observers in their order */
+    private incoming;
+    private closed;
+    private closing;
+    /** The abort of the lock request that waits */
+    private abortRequest;
+    /** The release of the lock */
+    private releaseLock;
+    constructor(options: TabCoordinatorOptions<T>);
+    /** The role of this tab now. */
+    get role(): TabRole;
+    /** True when this tab runs the sync: the leader, or a tab in the single mode. */
+    get isLeader(): boolean;
+    /**
+     * The `HybridStorage` of the sync while this tab runs it, or else undefined. Its `getStatus()`
+     * gives the state of the sync. Write to the local copy, not to this storage: each tab then writes
+     * in the same way.
+     */
+    get syncStorage(): HybridStorage<T> | undefined;
+    /**
+     * This method starts to send the change batches to an observer: the batches of the local copy of
+     * this tab, and the batches of the other tabs. Each batch comes one time, with the origin of each
+     * change. In the leader, the batches of the sync have the origin `syncOrigin` of the
+     * `HybridStorage`. A batch of another tab comes after the local copy of this tab has it.
+     *
+     * @returns The function that stops the batches. A second use of it does nothing.
+     * @throws Error after `close()`
+     */
+    observe(observer: StorageObserver<T>): () => void;
+    /**
+     * This method starts to send the role of this tab to a listener at each change.
+     *
+     * @returns The function that stops the roles. A second use of it does nothing.
+     * @throws Error after `close()`
+     */
+    onRole(listener: (role: TabRole) => void): () => void;
+    /**
+     * This method closes the coordinator.
+     *
+     * - A follower stops its lock request. It does not become the leader.
+     * - The leader closes its `HybridStorage`: it sends the queue, and the queue store keeps the
+     *   operations that the remote did not take. Then the leader releases the lock, and the next
+     *   tab becomes the leader.
+     * - The coordinator closes its channel. It does not close the local copy: the application owns it.
+     * - After it, the coordinator sends and copies nothing. A second `close()` gives the promise of
+     *   the first one.
+     */
+    close(): Promise<void>;
+    private shutDown;
+    /** This method asks for the lock. The tab becomes the leader when it gets the lock. */
+    private elect;
+    /**
+     * This method makes the `HybridStorage` of the sync: the tab becomes the leader, or the single
+     * tab. The capture of the storage gets the batches of this tab that no leader acknowledged.
+     *
+     * @returns False when the storage could not start
+     */
+    private lead;
+    /**
+     * The local copy for the `HybridStorage` of the leader. Its `observe()` gives the changes of the
+     * local copy and the batches of the other tabs, so the capture queues both. Its `close()` does
+     * nothing: the application owns the local copy.
+     */
+    private captureCopy;
+    /**
+     * This method gives a batch of another tab to the capture of the `HybridStorage` of the leader.
+     * The storage queues it. Its observers get it at once, and the coordinator ignores it there: the
+     * observers of the coordinator get it from the channel.
+     */
+    private capture;
+    private setRole;
+    /**
+     * A batch of the local copy of a follower. The writes of the coordinator itself (the batches of
+     * the other tabs in a copy of each tab) have the tag of the coordinator, and do not go out again.
+     */
+    private onFollowerBatch;
+    /**
+     * A batch of the `HybridStorage` of the leader: a write of the application to the local copy,
+     * a write to the storage, or a change of the sync.
+     */
+    private onLeaderBatch;
+    /** This method gives a batch of this tab to its observers and to the other tabs. A follower keeps it for the leader. */
+    private share;
+    /** This method tells the leader the batches of this tab that no leader acknowledged. */
+    private hello;
+    /** @returns False when the message did not go out: no channel, or a value that the channel cannot clone */
+    private post;
+    private stopChannel;
+    private receive;
+    /**
+     * A batch of another tab. The leader captures it when the tab said hello to it. Each tab copies
+     * it one time.
+     */
+    private onChanges;
+    /**
+     * The hello of another tab. The leader captures the batches that it did not capture, and then each
+     * batch of the tab after `seq`. Each tab copies the batches that it did not see.
+     */
+    private onHello;
+    /**
+     * This method copies a batch of another tab that this tab did not see: to the local copy of a
+     * tab, and then to the observers. The batches go in their order.
+     */
+    private copy;
+    /**
+     * This method writes a batch of another tab to the local copy of this tab, with the tag of the
+     * coordinator: the observer of this tab and the capture of the leader ignore the writes. The sets
+     * in a row go in one `setBatch`, and the deletes in a row in one `deleteBatch`.
+     */
+    private write;
+    /** This method tells a tab that the queue store of the leader holds its batches up to `seq`. */
+    private acknowledge;
+}
+//# sourceMappingURL=tab-coordinator.d.ts.map

package/dist/storage/tab-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tab-coordinator.d.ts","sourceRoot":"","sources":["../../src/storage/tab-coordinator.ts"],"names":[],"mappings":"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"}