@rebasepro/client 0.17.3-canary.gdd23447 → 0.18.0

package/src/realtime-error-surfacing.test.ts

@@ -1,105 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, jest } from "@jest/globals";
-
-/**
- * Server errors about channel frames used to be discarded by the client.
- *
- * Channel messages are fire-and-forget by design: the SDK deliberately
- * registers no `pendingRequests` waiter for them, because their answers come
- * back addressed by channel rather than in a response envelope. The consequence
- * was that an `ERROR` frame — `RATE_LIMITED`, `CHANNEL_FORBIDDEN`,
- * `CHANNEL_HISTORY_WRITE_FAILED` — matched no waiter, no channel and no
- * subscription, fell through every branch of `handleWebSocketMessage`, and was
- * dropped. `await channel.broadcast(...)` resolved as if it had been sent.
- */
-function fakeSocket() {
-    const sockets: FakeWS[] = [];
-
-    class FakeWS {
-        static readonly OPEN = 1;
-        readyState = 1;
-        onopen: (() => void) | null = null;
-        onclose: (() => void) | null = null;
-        onerror: (() => void) | null = null;
-        onmessage: ((event: { data: string }) => void) | null = null;
-
-        constructor(public url: string) {
-            sockets.push(this);
-            setTimeout(() => this.onopen?.(), 0);
-        }
-
-        send() { /* nothing here needs the outgoing frames */ }
-        close() { /* noop */ }
-    }
-
-    const instance = () => sockets[sockets.length - 1];
-
-    return {
-        FakeWS: FakeWS as unknown as typeof WebSocket,
-        deliver: (frame: unknown) => instance()?.onmessage?.({ data: JSON.stringify(frame) })
-    };
-}
-
-describe("unmatched realtime error frames", () => {
-    let warn: any;
-
-    beforeEach(() => {
-        jest.useFakeTimers();
-        warn = jest.spyOn(console, "warn").mockImplementation(() => {});
-    });
-
-    afterEach(() => {
-        warn.mockRestore();
-        jest.useRealTimers();
-    });
-
-    const connect = async () => {
-        const { RebaseWebSocketClient } = await import("./websocket");
-        const { FakeWS, deliver } = fakeSocket();
-        const client = new RebaseWebSocketClient({
-            websocketUrl: "ws://localhost:3000",
-            WebSocket: FakeWS
-        });
-        client.ensureConnected();
-        await jest.advanceTimersByTimeAsync(1);
-        return { client, deliver };
-    };
-
-    it("surfaces a channel rate-limit refusal that matches no waiter", async () => {
-        const { deliver } = await connect();
-
-        deliver({
-            type: "ERROR",
-            requestId: "req-the-client-never-registered",
-            payload: { error: { message: "Too many channel messages. Please slow down.", code: "RATE_LIMITED" } }
-        });
-
-        expect(warn).toHaveBeenCalledTimes(1);
-        expect(String(warn.mock.calls[0][0])).toContain("RATE_LIMITED");
-        expect(String(warn.mock.calls[0][0])).toContain("Too many channel messages");
-    });
-
-    it("surfaces a refused channel action", async () => {
-        const { deliver } = await connect();
-
-        // What the server now sends for a broadcast into a channel the sender
-        // never joined — `sendError` addresses it by neither requestId nor
-        // channel, so nothing else in the client will ever see it.
-        deliver({
-            type: "error",
-            payload: { error: { message: "Refused broadcast on channel \"doc:42\"", code: "CHANNEL_FORBIDDEN" } },
-            error: "Refused broadcast on channel \"doc:42\""
-        });
-
-        expect(warn).toHaveBeenCalledTimes(1);
-        expect(String(warn.mock.calls[0][0])).toContain("CHANNEL_FORBIDDEN");
-    });
-
-    it("stays quiet for frames that are not errors", async () => {
-        const { deliver } = await connect();
-
-        deliver({ type: "broadcast", channel: "doc:42", event: "op", payload: { n: 1 } });
-        deliver({ type: "presence_state", channel: "doc:42", presences: {} });
-
-        expect(warn).not.toHaveBeenCalled();
-    });
-});

package/src/realtime-optout.test.ts

@@ -1,279 +0,0 @@
-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 NO socket on construction, even with realtime enabled", () => {
-        // Changed deliberately. Constructing a client is not a statement that
-        // the app wants a socket — `createRebaseClient` builds one whenever
-        // realtime is not explicitly disabled, so dialling here cost a
-        // connection on every page load of every app that merely *might*
-        // subscribe later. Anonymous-first apps paid it on every visit to
-        // authenticate with nothing.
-        const { FakeWebSocket, opened } = trackingWebSocket();
-        globalThis.WebSocket = FakeWebSocket;
-
-        createRebaseClient({ baseUrl: "http://localhost:3000" });
-
-        expect(opened).toHaveLength(0);
-    });
-
-    it("opens the socket on the first channel operation", () => {
-        const { FakeWebSocket, opened } = trackingWebSocket();
-        globalThis.WebSocket = FakeWebSocket;
-
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
-
-        // Asking for the channel is not using it.
-        const channel = client.realtime.channel("doc:1");
-        expect(opened).toHaveLength(0);
-
-        void channel.join();
-        expect(opened).toHaveLength(1);
-    });
-
-    it("opens the socket on the first collection subscription", () => {
-        const { FakeWebSocket, opened } = trackingWebSocket();
-        globalThis.WebSocket = FakeWebSocket;
-
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
-        expect(opened).toHaveLength(0);
-
-        client.collection("posts").listen!(undefined, () => { /* noop */ });
-
-        expect(opened).toHaveLength(1);
-    });
-
-    it("opens exactly one socket however many things subscribe", () => {
-        const { FakeWebSocket, opened } = trackingWebSocket();
-        globalThis.WebSocket = FakeWebSocket;
-
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
-
-        client.collection("posts").listen!(undefined, () => { /* noop */ });
-        client.collection("authors").listen!(undefined, () => { /* noop */ });
-        void client.realtime.channel("doc:1").join();
-
-        expect(opened).toHaveLength(1);
-    });
-
-    it("stays silent for an anonymous client that never subscribes", () => {
-        // The motivating case: most page loads of an anonymous-first app.
-        // No socket, and no console noise either.
-        const { FakeWebSocket, opened } = trackingWebSocket();
-        globalThis.WebSocket = FakeWebSocket;
-        const warn = jest.spyOn(console, "warn").mockImplementation(() => { /* capture */ });
-        const debug = jest.spyOn(console, "debug").mockImplementation(() => { /* capture */ });
-
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
-        void client.realtime.channel("doc:1"); // obtained, never used
-
-        expect(opened).toHaveLength(0);
-        expect(warn).not.toHaveBeenCalled();
-        expect(debug).not.toHaveBeenCalled();
-    });
-
-    it("says nothing about a missing WebSocket until something needs one", () => {
-        // The environment warning used to fire on construction, so a Node
-        // process that never subscribed was told off for a socket it did not
-        // want.
-        // @ts-expect-error deliberately removing the global
-        delete globalThis.WebSocket;
-        const warn = jest.spyOn(console, "warn").mockImplementation(() => { /* capture */ });
-
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
-        expect(warn).not.toHaveBeenCalled();
-
-        void client.realtime.channel("doc:1").join();
-        expect(warn).toHaveBeenCalledWith(expect.stringMatching(/WebSocket is not defined/));
-
-        // ...and only once, however many times it is asked.
-        void client.realtime.channel("doc:2").join();
-        expect(warn).toHaveBeenCalledTimes(1);
-    });
-
-    it("opens no socket when realtime is disabled", () => {
-        const { FakeWebSocket, opened } = trackingWebSocket();
-        globalThis.WebSocket = FakeWebSocket;
-
-        const client = createRebaseClient({
-            baseUrl: "http://localhost:3000",
-            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",
-            websocketUrl: "ws://localhost:3000",
-            realtime: false
-        });
-
-        expect(opened).toHaveLength(0);
-    });
-
-    it("close() releases a socket that was opened", () => {
-        const { FakeWebSocket, opened, closed } = trackingWebSocket();
-        globalThis.WebSocket = FakeWebSocket;
-
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
-        client.collection("posts").listen!(undefined, () => { /* noop */ });
-        expect(opened).toHaveLength(1);
-
-        client.close();
-
-        expect(closed).toHaveLength(1);
-    });
-
-    it("close() is final — a later subscribe does not redial", () => {
-        // Otherwise one queued frame could reopen the socket that close() just
-        // released, and the Node process this method exists to let exit would
-        // stay alive anyway.
-        const { FakeWebSocket, opened } = trackingWebSocket();
-        globalThis.WebSocket = FakeWebSocket;
-
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
-        client.collection("posts").listen!(undefined, () => { /* noop */ });
-        expect(opened).toHaveLength(1);
-
-        client.close();
-        client.collection("authors").listen!(undefined, () => { /* noop */ });
-
-        expect(opened).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", realtime: false });
-        expect(() => offline.close()).not.toThrow();
-
-        const live = createRebaseClient({ baseUrl: "http://localhost:3000" });
-        live.close();
-        expect(() => live.close()).not.toThrow();
-    });
-
-    it("still refuses channels when realtime is disabled", () => {
-        // `realtime: false` remains a hard opt-out. Only the *default* changed
-        // — from "connected eagerly" to "connected on use".
-        const { FakeWebSocket, opened } = trackingWebSocket();
-        globalThis.WebSocket = FakeWebSocket;
-
-        const client = createRebaseClient({
-            baseUrl: "http://localhost:3000",
-            realtime: false
-        });
-
-        expect(() => client.realtime.channel("doc:1")).toThrow(/realtime: false/);
-        expect(opened).toHaveLength(0);
-    });
-
-    it("signing in does not by itself open a socket", async () => {
-        // Authenticating is not a request for realtime. If it dialled, every
-        // app with a login would lose lazy connect at the moment of login.
-        // Merely registering a listener does not show that: the SIGNED_IN
-        // branch that could dial is only reached by an actual sign-in.
-        const { FakeWebSocket, opened } = trackingWebSocket();
-        globalThis.WebSocket = FakeWebSocket;
-
-        const loginBody = {
-            tokens: {
-                accessToken: "jwt",
-                refreshToken: "refresh",
-                accessTokenExpiresAt: Date.now() + 3600_000
-            },
-            user: { uid: "usr_1",
-email: "u@example.com",
-displayName: "U",
-photoURL: null,
-roles: ["user"],
-providerId: "local",
-isAnonymous: false }
-        };
-        const fetchMock = jest.fn(async () => ({
-            ok: true,
-            status: 200,
-            text: async () => JSON.stringify(loginBody),
-            json: async () => loginBody,
-            headers: new Headers()
-        })) as unknown as typeof globalThis.fetch;
-
-        const client = createRebaseClient({
-            baseUrl: "http://localhost:3000",
-            fetch: fetchMock
-        });
-
-        const events: string[] = [];
-        client.auth.onAuthStateChange((event) => { events.push(event); });
-
-        const result = await client.auth.signInWithEmail("u@example.com", "pw");
-
-        expect(result.user.uid).toBe("usr_1");
-        expect(events).toEqual(["SIGNED_IN"]);
-        expect(opened).toHaveLength(0);
-
-        client.close();
-    });
-
-    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",
-            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

@@ -1,254 +0,0 @@
-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" }
-        ]);
-    });
-});