@rebasepro/client 0.8.0 → 0.9.1-canary.09aaf62

package/src/realtime-channel.ts

@@ -0,0 +1,238 @@
+/**
+ * Broadcast channels and presence, as an SDK surface.
+ *
+ * The realtime engine has supported `join_channel`, `broadcast`,
+ * `presence_track`, `presence_untrack` and `presence_state` for a while, but
+ * the client only recognised those types well enough to send them
+ * fire-and-forget: there were no methods to call and no way to receive channel
+ * or broadcast events, since `on()` handles only connect / disconnect /
+ * reconnect / error. Anything wanting presence therefore opened a *second*
+ * socket and reimplemented the AUTHENTICATE → AUTH_SUCCESS handshake, the
+ * reconnect backoff, and the presence heartbeat — a couple of hundred lines
+ * per app, all of it duplicating this package.
+ *
+ * Two protocol details this hides, because both are easy to get wrong and
+ * neither is discoverable from the message list:
+ *
+ *  - **A joining client is told only about its own join.** The `presence_diff`
+ *    it receives after `presence_track` contains just itself. The existing
+ *    roster arrives only in response to an explicit `presence_state` request,
+ *    so `join()` sends one.
+ *  - **Presence expires after 30s** (`PRESENCE_TIMEOUT_MS` server-side). A
+ *    client that tracks once and goes quiet silently vanishes from everyone
+ *    else's roster while still sitting in the document, so `track()` starts a
+ *    heartbeat and `leave()` stops it.
+ */
+
+/** Presence state keyed by the server's client id. */
+export type PresenceState = Record<string, Record<string, unknown>>;
+
+export interface PresenceDiff {
+    joins: PresenceState;
+    leaves: PresenceState;
+}
+
+export interface BroadcastEvent {
+    event: string;
+    payload: unknown;
+}
+
+/** The socket operations a channel needs; satisfied by RebaseWebSocketClient. */
+export interface ChannelTransport {
+    sendMessage(message: Record<string, unknown>): Promise<unknown>;
+    onChannelMessage(channel: string, handler: (message: Record<string, unknown>) => void): () => void;
+    onReconnect(handler: () => void): () => void;
+}
+
+/**
+ * Re-send presence comfortably inside the server's 30s expiry.
+ *
+ * Two-thirds of the window: one lost heartbeat still leaves time for the next
+ * before the entry is reaped, so a single dropped frame is not a disappearance.
+ */
+const PRESENCE_HEARTBEAT_MS = 20_000;
+
+export class RebaseRealtimeChannel {
+    private presenceHandlers = new Set<(state: PresenceState, diff?: PresenceDiff) => void>();
+    private broadcastHandlers = new Set<(event: BroadcastEvent) => void>();
+    private unsubscribers: (() => void)[] = [];
+
+    /** Last known roster, kept so handlers always get a full picture. */
+    private presences: PresenceState = {};
+    /** What this client last tracked, replayed on reconnect and heartbeat. */
+    private trackedState: Record<string, unknown> | null = null;
+    private heartbeat: ReturnType<typeof setInterval> | null = null;
+    private joined = false;
+
+    constructor(
+        public readonly name: string,
+        private transport: ChannelTransport
+    ) {}
+
+    /**
+     * Join the channel and ask for the current roster.
+     *
+     * Called automatically by `track`, `broadcast`, `onPresence` and
+     * `onBroadcast`; calling it directly is only needed to start receiving
+     * before there is anything to send.
+     */
+    async join(): Promise<void> {
+        if (this.joined) return;
+        this.joined = true;
+
+        this.unsubscribers.push(
+            this.transport.onChannelMessage(this.name, (message) => this.handle(message))
+        );
+
+        // A reconnect drops server-side channel membership and presence, so
+        // both have to be re-established. Nothing else notices this: the
+        // socket comes back, and the client just stops receiving.
+        this.unsubscribers.push(
+            this.transport.onReconnect(() => {
+                void this.rejoin();
+            })
+        );
+
+        await this.transport.sendMessage({ type: "join_channel", channel: this.name });
+        // Not optional. Joining does not push the roster — without this the
+        // channel believes it is alone until somebody else happens to move.
+        await this.transport.sendMessage({ type: "presence_state", channel: this.name });
+    }
+
+    private async rejoin(): Promise<void> {
+        try {
+            await this.transport.sendMessage({ type: "join_channel", channel: this.name });
+            await this.transport.sendMessage({ type: "presence_state", channel: this.name });
+            if (this.trackedState) {
+                await this.transport.sendMessage({
+                    type: "presence_track",
+                    channel: this.name,
+                    state: this.trackedState
+                });
+            }
+        } catch {
+            // The socket is down again; the next reconnect will retry.
+        }
+    }
+
+    /**
+     * Publish this client's presence state, and keep publishing it.
+     *
+     * Calling `track` again replaces the state (and restarts the heartbeat),
+     * which is how you update e.g. a cursor position.
+     */
+    async track(state: Record<string, unknown>): Promise<void> {
+        await this.join();
+        this.trackedState = state;
+
+        await this.transport.sendMessage({ type: "presence_track", channel: this.name, state });
+
+        if (!this.heartbeat) {
+            this.heartbeat = setInterval(() => {
+                if (!this.trackedState) return;
+                void this.transport
+                    .sendMessage({ type: "presence_track", channel: this.name, state: this.trackedState })
+                    .catch(() => { /* a dropped beat is recoverable; the next one carries the same state */ });
+            }, PRESENCE_HEARTBEAT_MS);
+            // Do not hold a Node process open just to say "still here".
+            (this.heartbeat as unknown as { unref?: () => void }).unref?.();
+        }
+    }
+
+    /** Stop publishing presence, without leaving the channel. */
+    async untrack(): Promise<void> {
+        this.stopHeartbeat();
+        this.trackedState = null;
+        if (this.joined) {
+            await this.transport.sendMessage({ type: "presence_untrack", channel: this.name });
+        }
+    }
+
+    /**
+     * Observe the roster. The handler fires immediately with what is already
+     * known, then on every change.
+     */
+    onPresence(handler: (state: PresenceState, diff?: PresenceDiff) => void): () => void {
+        this.presenceHandlers.add(handler);
+        void this.join();
+        if (Object.keys(this.presences).length > 0) handler({ ...this.presences });
+        return () => this.presenceHandlers.delete(handler);
+    }
+
+    /** Send a broadcast. The sender does not receive its own message. */
+    async broadcast(event: string, payload: unknown): Promise<void> {
+        await this.join();
+        await this.transport.sendMessage({ type: "broadcast", channel: this.name, event, payload });
+    }
+
+    /** Observe broadcasts. Pass an event name to filter. */
+    onBroadcast(handler: (event: BroadcastEvent) => void): () => void;
+    onBroadcast(event: string, handler: (payload: unknown) => void): () => void;
+    onBroadcast(
+        eventOrHandler: string | ((event: BroadcastEvent) => void),
+        maybeHandler?: (payload: unknown) => void
+    ): () => void {
+        const wrapped: (event: BroadcastEvent) => void = typeof eventOrHandler === "string"
+            ? (e) => { if (e.event === eventOrHandler) maybeHandler!(e.payload); }
+            : eventOrHandler;
+
+        this.broadcastHandlers.add(wrapped);
+        void this.join();
+        return () => this.broadcastHandlers.delete(wrapped);
+    }
+
+    /** Leave the channel and release every listener and timer. */
+    async leave(): Promise<void> {
+        this.stopHeartbeat();
+        this.trackedState = null;
+        this.presences = {};
+        this.presenceHandlers.clear();
+        this.broadcastHandlers.clear();
+
+        for (const off of this.unsubscribers) off();
+        this.unsubscribers = [];
+
+        if (this.joined) {
+            this.joined = false;
+            await this.transport.sendMessage({ type: "leave_channel", channel: this.name });
+        }
+    }
+
+    private stopHeartbeat(): void {
+        if (this.heartbeat) {
+            clearInterval(this.heartbeat);
+            this.heartbeat = null;
+        }
+    }
+
+    /** Fold an incoming frame into the roster and fan it out. */
+    private handle(message: Record<string, unknown>): void {
+        switch (message.type) {
+            case "presence_state": {
+                this.presences = (message.presences as PresenceState) ?? {};
+                this.emitPresence();
+                break;
+            }
+            case "presence_diff": {
+                const joins = (message.joins as PresenceState) ?? {};
+                const leaves = (message.leaves as PresenceState) ?? {};
+                // A diff carries only what moved, so the roster is maintained
+                // here rather than handed to callers to reassemble.
+                for (const [id, state] of Object.entries(joins)) this.presences[id] = state;
+                for (const id of Object.keys(leaves)) delete this.presences[id];
+                this.emitPresence({ joins, leaves });
+                break;
+            }
+            case "broadcast": {
+                const event = { event: message.event as string, payload: message.payload };
+                for (const handler of this.broadcastHandlers) handler(event);
+                break;
+            }
+        }
+    }
+
+    private emitPresence(diff?: PresenceDiff): void {
+        const snapshot = { ...this.presences };
+        for (const handler of this.presenceHandlers) handler(snapshot, diff);
+    }
+}

package/src/realtime-optout.test.ts

@@ -0,0 +1,119 @@
+import { jest } from "@jest/globals";
+import { createRebaseClient } from "./index";
+
+/**
+ * A WebSocket stand-in that records construction. The real socket keeps the Node
+ * event loop alive, which is what makes a one-shot script hang; here we only
+ * need to know whether one would have been opened at all.
+ */
+function trackingWebSocket() {
+    const opened: string[] = [];
+    const closed: string[] = [];
+
+    class FakeWebSocket {
+        static readonly OPEN = 1;
+        readyState = 0;
+        onopen: (() => void) | null = null;
+        onclose: (() => void) | null = null;
+        onerror: (() => void) | null = null;
+        onmessage: (() => void) | null = null;
+
+        constructor(public url: string) {
+            opened.push(url);
+        }
+
+        close() {
+            closed.push(this.url);
+        }
+
+        send() { /* no-op */ }
+    }
+
+    return { FakeWebSocket: FakeWebSocket as unknown as typeof WebSocket, opened, closed };
+}
+
+describe("realtime opt-out", () => {
+    const original = globalThis.WebSocket;
+
+    afterEach(() => {
+        globalThis.WebSocket = original;
+        jest.restoreAllMocks();
+    });
+
+    it("opens the socket by default", () => {
+        const { FakeWebSocket, opened } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+
+        expect(opened).toHaveLength(1);
+    });
+
+    it("opens no socket when realtime is disabled", () => {
+        const { FakeWebSocket, opened } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        const client = createRebaseClient({
+            baseUrl: "http://localhost:3000/api",
+            realtime: false
+        });
+
+        // The socket is what keeps a CLI / cron / ETL process alive past its work.
+        expect(opened).toHaveLength(0);
+        expect(client.ws).toBeUndefined();
+    });
+
+    it("opens no socket when realtime is disabled even if a websocketUrl is given", () => {
+        const { FakeWebSocket, opened } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        createRebaseClient({
+            baseUrl: "http://localhost:3000/api",
+            websocketUrl: "ws://localhost:3000",
+            realtime: false
+        });
+
+        expect(opened).toHaveLength(0);
+    });
+
+    it("close() releases the socket", () => {
+        const { FakeWebSocket, opened, closed } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        expect(opened).toHaveLength(1);
+
+        client.close();
+
+        expect(closed).toHaveLength(1);
+    });
+
+    it("close() is safe when realtime was never started, and when called twice", () => {
+        const { FakeWebSocket } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        const offline = createRebaseClient({ baseUrl: "http://localhost:3000/api", realtime: false });
+        expect(() => offline.close()).not.toThrow();
+
+        const live = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        live.close();
+        expect(() => live.close()).not.toThrow();
+    });
+
+    it("leaves listen() absent so callers can feature-detect, and says why via the query builder", () => {
+        const { FakeWebSocket } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        const client = createRebaseClient({
+            baseUrl: "http://localhost:3000/api",
+            realtime: false
+        });
+
+        // `listen` stays undefined rather than becoming a throwing stub: the
+        // optional type is what makes `if (client.listen)` work and what makes
+        // TypeScript reject a bare call.
+        expect(client.collection("posts").listen).toBeUndefined();
+        expect(() => client.data.posts.include("author").listen(() => { /* noop */ }))
+            .toThrow(/realtime: false/);
+    });
+});

package/src/realtime-row-identity.test.ts

@@ -0,0 +1,254 @@
+import { RebaseWebSocketClient } from "./websocket";
+
+/**
+ * Realtime patches name a row by address; the cached rows are columns only.
+ *
+ * The SDK deliberately holds no collection config — a BaaS caller declares
+ * nothing — so it cannot derive an address by itself, and used to just read
+ * `row.id`. For a table keyed on anything else that is `undefined`: deletes
+ * matched no cached row and removed nothing, and updates matched none either,
+ * so every edit was prepended as a duplicate of the row it was editing.
+ *
+ * The server now sends the key columns with the patch, and they are used here.
+ */
+describe("collection_patch — cached rows are matched by derived address", () => {
+    const SKU_PKS = [{ fieldName: "sku",
+type: "string" as const }];
+
+    /**
+     * A client with one collection subscription holding `cached`, wired to the
+     * backend subscription id the patches below use.
+     */
+    const setup = (cached: Record<string, unknown>[]) => {
+        const client = new RebaseWebSocketClient({ url: "ws://localhost:1234" });
+        const updates: Record<string, unknown>[][] = [];
+
+        const internals = client as unknown as {
+            backendToCollectionKey: Map<string, string>;
+            collectionSubscriptions: Map<string, unknown>;
+            handleWebSocketMessage: (m: unknown) => void;
+        };
+
+        internals.backendToCollectionKey.set("backend-1", "sub-key");
+        internals.collectionSubscriptions.set("sub-key", {
+            backendSubscriptionId: "backend-1",
+            callbacks: new Map([["cb", { onUpdate: (rows: Record<string, unknown>[]) => updates.push(rows) }]]),
+            props: { path: "sku_items" },
+            latestData: cached,
+            isInitialDataReceived: true
+        });
+
+        const patch = (message: Record<string, unknown>) =>
+            internals.handleWebSocketMessage({ type: "collection_patch",
+subscriptionId: "backend-1",
+...message });
+
+        const update = (rows: Record<string, unknown>[], pks?: unknown) =>
+            internals.handleWebSocketMessage({ type: "collection_update",
+subscriptionId: "backend-1",
+rows,
+pks });
+
+        return { patch,
+update,
+updates,
+sub: () => internals.collectionSubscriptions.get("sub-key") as { latestData: Record<string, unknown>[] } };
+    };
+
+    it("removes the deleted row a `sku` key names", () => {
+        const { patch, sub } = setup([
+            { sku: "ABC-1",
+label: "Widget" },
+            { sku: "ABC-2",
+label: "Gadget" }
+        ]);
+
+        patch({ id: "ABC-1",
+row: null,
+pks: SKU_PKS });
+
+        expect(sub().latestData).toEqual([{ sku: "ABC-2",
+label: "Gadget" }]);
+    });
+
+    it("replaces the row the patch names, not whichever row is first", () => {
+        // Both sides of the old comparison stringified to "undefined", so it
+        // matched at index 0 every time: editing the second row overwrote the
+        // first one, in place, with the second one's values.
+        const { patch, sub } = setup([
+            { sku: "ABC-1",
+label: "Widget" },
+            { sku: "ABC-2",
+label: "Gadget" }
+        ]);
+
+        patch({ id: "ABC-2",
+row: { sku: "ABC-2",
+label: "Gadget v2" },
+pks: SKU_PKS });
+
+        expect(sub().latestData).toEqual([
+            { sku: "ABC-1",
+label: "Widget" },
+            { sku: "ABC-2",
+label: "Gadget v2" }
+        ]);
+    });
+
+    it("prepends a row that really is new", () => {
+        const { patch, sub } = setup([{ sku: "ABC-2",
+label: "Gadget" }]);
+
+        patch({ id: "ABC-9",
+row: { sku: "ABC-9",
+label: "New" },
+pks: SKU_PKS });
+
+        expect(sub().latestData).toEqual([
+            { sku: "ABC-9",
+label: "New" },
+            { sku: "ABC-2",
+label: "Gadget" }
+        ]);
+    });
+
+    it("matches a composite key by its joined address", () => {
+        const { patch, sub } = setup([
+            { tenant_id: 1,
+user_id: 2,
+role: "admin" },
+            { tenant_id: 1,
+user_id: 3,
+role: "viewer" }
+        ]);
+
+        patch({
+            id: "1:::3",
+            row: { tenant_id: 1,
+user_id: 3,
+role: "owner" },
+            pks: [{ fieldName: "tenant_id",
+type: "number" }, { fieldName: "user_id",
+type: "number" }]
+        });
+
+        expect(sub().latestData).toEqual([
+            { tenant_id: 1,
+user_id: 2,
+role: "admin" },
+            { tenant_id: 1,
+user_id: 3,
+role: "owner" }
+        ]);
+    });
+
+    it("carries the patch's keys into the refetch merge, preserving unchanged references", () => {
+        // Phase 2 of every patch is a full refetch (`collection_update`), whose
+        // merge keeps the cached object for rows that did not change so React
+        // sees the same reference. That matching needs an address too — the
+        // keys learned from the patch are remembered on the subscription.
+        const unchanged = { sku: "ABC-1",
+label: "Widget" };
+        const { patch, update, sub } = setup([unchanged, { sku: "ABC-2",
+label: "Gadget" }]);
+
+        patch({ id: "ABC-2",
+row: { sku: "ABC-2",
+label: "Gadget v2" },
+pks: SKU_PKS });
+        update([{ sku: "ABC-1",
+label: "Widget" }, { sku: "ABC-2",
+label: "Gadget v3" }], SKU_PKS);
+
+        expect(sub().latestData[0]).toBe(unchanged);
+        expect(sub().latestData[1]).toEqual({ sku: "ABC-2",
+label: "Gadget v3" });
+    });
+
+    it("learns the keys from the rows themselves, for a change that sends no patch", () => {
+        // A write from outside the API — psql, a cron job — reaches subscribers
+        // through CDC, which invalidates and refetches without ever sending a
+        // patch. Keys learned only from patches would never arrive, and every
+        // row of the refetch would be a new reference: the whole table
+        // re-renders on any external write.
+        const unchanged = { sku: "ABC-1",
+label: "Widget" };
+        const { update, sub } = setup([unchanged, { sku: "ABC-2",
+label: "Gadget" }]);
+
+        update([{ sku: "ABC-1",
+label: "Widget" }, { sku: "ABC-2",
+label: "Gadget v2" }], SKU_PKS);
+
+        expect(sub().latestData[0]).toBe(unchanged);
+        expect(sub().latestData[1]).toEqual({ sku: "ABC-2",
+label: "Gadget v2" });
+    });
+
+    it("addresses an `id`-keyed collection from the keys like any other", () => {
+        // `id` is not special: the server reports it as the key column, and it
+        // is derived through the same path as a `sku` or a composite.
+        const { patch, sub } = setup([{ id: 1,
+name: "Camera" }, { id: 2,
+name: "Lens" }]);
+
+        patch({ id: "1",
+row: null,
+pks: [{ fieldName: "id",
+type: "number" }] });
+
+        expect(sub().latestData).toEqual([{ id: 2,
+name: "Lens" }]);
+    });
+
+    it("recognises nothing when the server resolved no keys, rather than guessing at `id`", () => {
+        // A table with no primary key and no `id` column has no address. The
+        // server says so by sending no keys, and inventing one from a column
+        // that merely looks like an id would address rows that are not there.
+        const { patch, sub } = setup([
+            { id: "batch-42",
+name: "Camera" },
+            { id: "batch-42",
+name: "Lens" }
+        ]);
+
+        patch({ id: "batch-42",
+row: null });
+
+        // Nothing removed: the patch names a row this client cannot identify.
+        expect(sub().latestData).toHaveLength(2);
+    });
+
+    it("prefers the real key over a column merely named `id`", () => {
+        // `event_id` is the key; `id` is ordinary data, and ordinary data has no
+        // uniqueness to borrow — both rows here carry the same external ref.
+        // Matching on it finds the first, so editing the party rewrote the
+        // launch with the party's values.
+        const { patch, sub } = setup([
+            { event_id: 7,
+id: "batch-42",
+name: "Launch" },
+            { event_id: 8,
+id: "batch-42",
+name: "Party" }
+        ]);
+
+        patch({
+            id: "8",
+            row: { event_id: 8,
+id: "batch-42",
+name: "Party v2" },
+            pks: [{ fieldName: "event_id",
+type: "number" }]
+        });
+
+        expect(sub().latestData).toEqual([
+            { event_id: 7,
+id: "batch-42",
+name: "Launch" },
+            { event_id: 8,
+id: "batch-42",
+name: "Party v2" }
+        ]);
+    });
+});

package/src/reviver.ts

@@ -1,4 +1,4 @@
-import { EntityReference, EntityRelation, GeoPoint, Vector, Entity } from "@rebasepro/types";
+import { EntityReference, EntityRelation, GeoPoint, Vector } from "@rebasepro/types";
 
 export function rebaseReviver(_key: string, value: unknown): unknown {
     if (value && typeof value === "object" && "__type" in value) {
@@ -25,7 +25,7 @@ export function rebaseReviver(_key: string, value: unknown): unknown {
                 return new EntityRelation(
                     record.id as string | number,
                     record.path as string,
-                    record.data as Entity | undefined
+                    record.data as Record<string, unknown> | undefined
                 );
             case "GeoPoint":
                 return new GeoPoint(record.latitude as number, record.longitude as number);