@rebasepro/client 0.12.0 → 0.12.1-canary.g06f263c

package/dist/websocket.d.ts

@@ -27,6 +27,17 @@ export declare class RebaseWebSocketClient {
     private channelHandlers;
     /** Set by `close()`. Blocks any later operation from silently redialling. */
     private closedByCaller;
+    /**
+     * Set when the backoff budget ran out, cleared by anything that earns a
+     * fresh one.
+     *
+     * Unlike {@link closedByCaller} this is not final — nobody *asked* for the
+     * socket to stay down. Five attempts with exponential backoff is about a
+     * minute, which a laptop lid, a wifi handover or a backend rollout all
+     * exceed routinely; treating that as permanent meant realtime silently
+     * stopped for the rest of the page's life, with a reload the only cure.
+     */
+    private gaveUp;
     /**
      * Whether a socket exists at all (open or still opening).
      *
@@ -68,6 +79,13 @@ export declare class RebaseWebSocketClient {
      * re-entrant, since the reconnect path has always called it.
      */
     ensureConnected(): void;
+    /**
+     * The browser says the network is back — the usual reason the budget ran
+     * out in the first place. Registered lazily so a Node client, or a page
+     * that never subscribes, adds no listener.
+     */
+    private installOnlineListener;
+    private onlineListener;
     /**
      * Authenticate the WebSocket connection
      */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/client",
   "type": "module",
-  "version": "0.12.0",
+  "version": "0.12.1-canary.g06f263c",
   "description": "HTTP SDK client for the Rebase custom backend",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -29,23 +29,23 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@rebasepro/common": "0.12.0",
-    "@rebasepro/types": "0.12.0",
-    "@rebasepro/utils": "0.12.0"
+    "@rebasepro/common": "0.12.1-canary.g06f263c",
+    "@rebasepro/utils": "0.12.1-canary.g06f263c",
+    "@rebasepro/types": "0.12.1-canary.g06f263c"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.1.2",
     "@types/ws": "^8.18.1",
     "cross-env": "^10.1.0",
     "fake-indexeddb": "^6.2.5",
     "jest": "^30.4.2",
-    "ts-jest": "^29.4.11",
+    "ts-jest": "^29.4.12",
     "tsd": "^0.33.0",
     "typescript": "^6.0.3",
-    "vite": "^8.0.16",
-    "ws": "^8.21.0"
+    "vite": "^8.1.5",
+    "ws": "^8.21.1"
   },
   "files": [
     "dist",

package/src/auth.ts

@@ -268,6 +268,30 @@ export function createAuth(transport: Transport, options?: CreateAuthOptions) {
         refreshTimeout = setTimeout(() => { void attemptScheduledRefresh(0); }, delay);
     }
 
+    /**
+     * Stop the scheduled token refresh, leaving the session itself alone.
+     *
+     * This is teardown, not sign-out. `scheduleRefresh` arms an ordinary
+     * `setTimeout` up to a token lifetime away, and it is not `unref`'d — so on
+     * Node it holds the event loop open by itself. `client.close()` promised
+     * that "a script that does not call this will not exit on its own", which
+     * was true, while the converse it plainly implies was not: a signed-in
+     * client that closed its socket still hung, because this timer outlived it.
+     * Any script, cron handler or job that signs in hit that.
+     *
+     * Deliberately does NOT clear the session, touch storage, or emit
+     * SIGNED_OUT. Closing a client is not the user signing out — `signOut()`
+     * POSTs /logout and revokes the whole sign-in, which is the wrong hammer
+     * (see `abandonSessionLocally`) — and a persisted session must still be
+     * there for the next client to restore.
+     */
+    function stopAutoRefresh() {
+        if (refreshTimeout) {
+            clearTimeout(refreshTimeout);
+            refreshTimeout = null;
+        }
+    }
+
     function handleAuthResponse(data: { tokens: AuthTokens, user: Record<string, unknown> }, event?: AuthChangeEvent): RebaseSession {
         const user: User = mapRawUser(data.user);
         const session: RebaseSession = {
@@ -796,6 +820,7 @@ refreshToken: session.refreshToken };
         signInWithSlack,
         signInWithSpotify,
         signOut,
+        stopAutoRefresh,
         refreshSession,
         handleUnauthorized,
         getUser,
@@ -815,6 +840,11 @@ refreshToken: session.refreshToken };
         getAuthConfig,
         getSession,
         onAuthStateChange,
+        // A client that neither persists sessions nor uses cookie auth has
+        // nowhere to restore one from, so "no session in memory" is the final
+        // answer rather than a reason to ask the server. See the docblock on
+        // `AuthClient.canRestoreSession`.
+        canRestoreSession: () => persistSession || authFlowMode === "cookie",
         isInitialized: () => isInitialized
     };
 }

package/src/client-close.test.ts

@@ -0,0 +1,80 @@
+import { jest } from "@jest/globals";
+import { createRebaseClient } from "./index";
+
+/**
+ * `close()` has one job: leave nothing behind that can keep a process alive.
+ *
+ * The realtime socket is the obvious such handle and was the only one this
+ * method released. The scheduled token refresh is the other, and it is easy to
+ * miss because it only exists once somebody signs in: `scheduleRefresh` arms a
+ * plain `setTimeout` for roughly the access token's lifetime, and it is not
+ * `unref`'d. So a signed-in Node client — a seed script, a cron handler, a job,
+ * an SSR request — released its socket, called `close()` exactly as documented,
+ * and still hung until the token would have expired.
+ *
+ * Found by `e2e/tests/client-sdk-e2e.ts`, which reported every check green and
+ * then never exited. Pinned here rather than only there because that suite needs
+ * Docker and a real Postgres, and this costs nothing.
+ *
+ * The assertion is the pending timer count, not a spy on `stopAutoRefresh`:
+ * what matters is that no handle survives, not which internal call removed it.
+ */
+describe("client.close()", () => {
+    const realFetch = globalThis.fetch;
+
+    afterEach(() => {
+        globalThis.fetch = realFetch;
+        jest.useRealTimers();
+        jest.restoreAllMocks();
+    });
+
+    /** A login response shaped exactly as `handleAuthResponse` reads it. */
+    function loginResponse(accessTokenExpiresAt: number) {
+        return new Response(
+            JSON.stringify({
+                tokens: { accessToken: "access-token",
+refreshToken: "refresh-token",
+accessTokenExpiresAt },
+                user: { uid: "user-1",
+email: "user@example.test" }
+            }),
+            { status: 200,
+headers: { "content-type": "application/json" } }
+        );
+    }
+
+    it("clears the scheduled token refresh, so a signed-in script can exit", async () => {
+        jest.useFakeTimers();
+
+        // An hour out, so the refresh is scheduled rather than fired
+        // immediately — `scheduleRefresh` runs the refresh inline when the
+        // delay has already elapsed, which would arm no timer and let a broken
+        // `close()` pass this test.
+        const expiresAt = Date.now() + 60 * 60 * 1000;
+        globalThis.fetch = jest.fn(async () => loginResponse(expiresAt)) as unknown as typeof fetch;
+
+        // `realtime: false` so the socket cannot account for a pending handle:
+        // the only thing this test may observe is the refresh timer.
+        const client = createRebaseClient({ baseUrl: "http://localhost:9999",
+realtime: false });
+
+        await client.auth.signInWithEmail("user@example.test", "password");
+        expect(jest.getTimerCount()).toBeGreaterThan(0);
+
+        client.close();
+        expect(jest.getTimerCount()).toBe(0);
+    });
+
+    it("is safe on a client that never signed in, and safe to call twice", () => {
+        jest.useFakeTimers();
+
+        const client = createRebaseClient({ baseUrl: "http://localhost:9999",
+realtime: false });
+
+        expect(() => {
+            client.close();
+            client.close();
+        }).not.toThrow();
+        expect(jest.getTimerCount()).toBe(0);
+    });
+});

package/src/functions.ts

@@ -55,7 +55,15 @@ export function createFunctionsClient(transport: Transport): FunctionsClient {
             options?: FunctionInvokeOptions
         ): Promise<T> {
             const method = options?.method ?? "POST";
-            const subPath = options?.path ? `/${options.path.replace(/^\//, "")}` : "";
+            // A `path` that starts the query or fragment is appended as-is. Only a
+            // real sub-path gets a separator: inserting one before `?days=30` asks
+            // for `/functions/dashboard-stats/?days=30`, and the trailing slash
+            // misses the route, so a function that exists answers 404 — and the
+            // caller sees it as the backend being down rather than as a bad URL.
+            const rawPath = options?.path;
+            const subPath = rawPath
+                ? (/^[?#]/.test(rawPath) ? rawPath : `/${rawPath.replace(/^\//, "")}`)
+                : "";
             const routePath = `/functions/${encodeURIComponent(name)}${subPath}`;
 
             const init: RequestInit = { method };

package/src/index.ts

@@ -208,11 +208,17 @@ export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<Rebase
         channel: (name: string, options?: ChannelOptions) => RebaseRealtimeChannel;
     };
     /**
-     * Release the realtime socket and its reconnect timer.
+     * Release everything this client holds that can keep a process alive: the
+     * realtime socket and its reconnect timer, channel presence heartbeats, the
+     * offline manager, and the scheduled token refresh.
      *
-     * An open socket keeps the Node event loop alive, so a script that does not
-     * call this will not exit on its own. Safe when realtime was never started
-     * (`realtime: false`), and safe to call twice.
+     * Each of those keeps the Node event loop alive on its own, so a script
+     * that does not call this will not exit — and, until the refresh timer was
+     * included, one that *did* call it still would not if it had signed in.
+     *
+     * Safe when realtime was never started (`realtime: false`), safe when
+     * signed out, and safe to call twice. It does not sign the user out: a
+     * persisted session survives for the next client to restore.
      */
     close: () => void;
     storage: StorageSource;
@@ -547,11 +553,11 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
             }
         },
         /**
-         * Release the realtime socket and its reconnect timer.
+         * Release every handle that can keep a process alive — see the
+         * `close` docblock on the client interface.
          *
-         * Until this returns, the open socket keeps the Node event loop alive
-         * and the process will not exit on its own. Safe to call when realtime
-         * was never started, and safe to call twice.
+         * Safe to call when realtime was never started, safe when signed out,
+         * and safe to call twice.
          */
         close: () => {
             // Channels hold presence heartbeat timers, which would otherwise
@@ -565,12 +571,19 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
             // The offline retry timer is unref'd but the `online` listener is
             // not, and neither should outlive the client.
             offlineManager?.dispose();
+            // The scheduled token refresh is a plain setTimeout up to a token
+            // lifetime away, and not unref'd — so on Node it holds the event
+            // loop open all by itself. Without this, closing a SIGNED-IN client
+            // released the socket and the process still never exited, which is
+            // the opposite of what this method exists to guarantee.
+            auth.stopAutoRefresh();
         },
         setToken: transport.setToken,
         setAuthTokenGetter: transport.setAuthTokenGetter,
         setOnUnauthorized: transport.setOnUnauthorized,
         resolveToken: transport.resolveToken,
         baseUrl: transport.baseUrl,
+        apiPath: transport.apiPath,
         collection,
         call: async <T = unknown>(endpoint: string, payload?: unknown): Promise<T> => {
             const prefix = endpoint.startsWith("/") ? "" : "/";

package/src/offline-idb-store.test.ts

@@ -189,9 +189,28 @@ async function clearOfflineQueue(): Promise<void> {
 describe("two tabs over one database", () => {
     beforeEach(clearOfflineQueue);
 
-    /** BroadcastChannel delivery is asynchronous; give it a macrotask or two. */
-    const settle = async () => {
-        for (let i = 0; i < 3; i++) await new Promise((resolve) => setTimeout(resolve, 0));
+    /**
+     * Wait until the other tab has caught up.
+     *
+     * BroadcastChannel delivery is asynchronous and the receiving tab then does
+     * its own IndexedDB work, so there is no fixed number of turns that is
+     * both enough and not wasteful. Draining three macrotasks was enough on an
+     * idle machine and not enough when the other package suites run alongside
+     * this one — which is how this file failed under `pnpm -r test` while
+     * passing every time on its own.
+     *
+     * Polling a condition is what the test actually means, and it costs one
+     * turn in the common case rather than three.
+     */
+    const settleUntil = async (done: () => boolean | Promise<boolean>, deadlineMs = 5_000) => {
+        const started = Date.now();
+        for (;;) {
+            if (await done()) return;
+            if (Date.now() - started > deadlineMs) {
+                throw new Error(`condition never held within ${deadlineMs}ms`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, 5));
+        }
     };
 
     function createServer() {
@@ -252,7 +271,7 @@ describe("two tabs over one database", () => {
 
         server.state.online = false;
         await postsA.create({ title: "from tab A" }, "xt1");
-        await settle();
+        await settleUntil(async () => (await postsB.find()).data.some((r) => r.id === "xt1"));
 
         // Without cross-tab propagation this tab would be showing a list that
         // is already wrong, and would keep showing it until a refetch.

package/src/websocket.ts

@@ -97,6 +97,18 @@ export class RebaseWebSocketClient {
     /** Set by `close()`. Blocks any later operation from silently redialling. */
     private closedByCaller = false;
 
+    /**
+     * Set when the backoff budget ran out, cleared by anything that earns a
+     * fresh one.
+     *
+     * Unlike {@link closedByCaller} this is not final — nobody *asked* for the
+     * socket to stay down. Five attempts with exponential backoff is about a
+     * minute, which a laptop lid, a wifi handover or a backend rollout all
+     * exceed routinely; treating that as permanent meant realtime silently
+     * stopped for the rest of the page's life, with a reload the only cure.
+     */
+    private gaveUp = false;
+
     /**
      * Whether a socket exists at all (open or still opening).
      *
@@ -249,10 +261,35 @@ export class RebaseWebSocketClient {
             }
             return;
         }
+        this.installOnlineListener();
         if (this.ws || this.reconnectTimeout) return;
+        // A caller asking for a connection is a fresh reason to try, so it also
+        // buys a fresh backoff budget. Without this, the first `subscribe`
+        // after a give-up would exhaust the counter on attempt one.
+        if (this.gaveUp) {
+            this.gaveUp = false;
+            this.reconnectAttempts = 0;
+        }
         this.initWebSocket();
     }
 
+    /**
+     * The browser says the network is back — the usual reason the budget ran
+     * out in the first place. Registered lazily so a Node client, or a page
+     * that never subscribes, adds no listener.
+     */
+    private installOnlineListener() {
+        if (this.onlineListener || typeof window === "undefined" || typeof window.addEventListener !== "function") return;
+        this.onlineListener = () => {
+            if (this.closedByCaller || !this.gaveUp) return;
+            console.debug("Network is back — retrying the realtime connection");
+            this.ensureConnected();
+        };
+        window.addEventListener("online", this.onlineListener);
+    }
+
+    private onlineListener: (() => void) | null = null;
+
     /**
      * Authenticate the WebSocket connection
      */
@@ -325,6 +362,10 @@ export class RebaseWebSocketClient {
      */
     public disconnect(permanent = false): void {
         if (permanent) this.closedByCaller = true;
+        if (permanent && this.onlineListener && typeof window !== "undefined") {
+            window.removeEventListener("online", this.onlineListener);
+            this.onlineListener = null;
+        }
         this.isAuthenticated = false;
         this.authPromise = null;
         if (this.reconnectTimeout) {
@@ -354,7 +395,10 @@ export class RebaseWebSocketClient {
         }
 
         try {
-            this.ws = new this.WebSocketConstructor(this.websocketUrl);
+            // Captured so each handler can tell "my socket" from a later one:
+            // a close arriving after a redial must not clear the new socket.
+            const socket = new this.WebSocketConstructor(this.websocketUrl);
+            this.ws = socket;
 
             this.ws!.onopen = async () => {
                 console.debug("Connected to PostgreSQL backend");
@@ -403,6 +447,11 @@ export class RebaseWebSocketClient {
 
             this.ws!.onclose = () => {
                 console.debug("Disconnected from PostgreSQL backend");
+                // Release the dead socket. `ensureConnected` returns early
+                // while `this.ws` is set, so holding a closed one made the
+                // "give up after N attempts" state permanent: nothing could
+                // ever redial, not even a fresh `subscribe`.
+                if (this.ws === socket) this.ws = null;
                 this.isConnected = false;
                 this.isAuthenticated = false;
                 this.authPromise = null;
@@ -451,6 +500,7 @@ export class RebaseWebSocketClient {
             console.error("Max reconnection attempts reached");
             // Nothing will re-subscribe now, so stop every subscription that
             // never loaded from spinning forever.
+            this.gaveUp = true;
             this.failAllPendingSubscriptions(
                 new RebaseApiError("Connection lost", { code: "CONNECTION_LOST" })
             );