@rebasepro/client 0.22.0 → 0.24.0

package/dist/websocket.d.ts

@@ -1,4 +1,5 @@
-import { DeleteProps, CollectionConfig, FetchCollectionProps, ListenCollectionProps, FetchOneProps, SaveProps, CollectionUpdateMeta, ChannelMessage, TableMetadata, BranchInfo } from "@rebasepro/types";
+import { DeleteProps, CollectionConfig, FetchCollectionProps, ListenCollectionProps, FetchOneProps, SaveProps, CollectionUpdateMeta, ChannelMessage, TableMetadata, BranchInfo, RebaseApiError, type RealtimeConnectionState } from "@rebasepro/types";
+import type { SqlScriptResult } from "@rebasepro/types";
 export interface RebaseWebSocketConfig {
     websocketUrl: string;
     /** Optional auth token getter for WebSocket authentication */
@@ -7,6 +8,11 @@ export interface RebaseWebSocketConfig {
     WebSocket?: typeof WebSocket;
     /** Callback to handle unauthorized requests or token expiration (refreshes auth session) */
     onUnauthorized?: () => Promise<boolean>;
+    /**
+     * Sign in as this user rather than as the token's own — the socket half of
+     * `RebaseClientConfig.impersonate`. Sent with every `AUTHENTICATE`.
+     */
+    impersonate?: string;
 }
 export declare class RebaseWebSocketClient {
     private websocketUrl;
@@ -18,16 +24,41 @@ export declare class RebaseWebSocketClient {
     /** 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.
+     * Set when the backoff budget ran out with nothing registered, 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.
+     * Only reachable with nothing registered: while a subscription or a joined
+     * channel exists the client never stops retrying (see `attemptReconnect`).
+     * And it is not final like {@link closedByCaller} — nobody *asked* for the
+     * socket to stay down, so the next subscribe dials again.
      */
     private gaveUp;
+    /** See {@link state}. */
+    private connectionState;
+    private stateListeners;
+    /**
+     * Whether the current outage has been reported to the registrations as
+     * `CONNECTION_LOST`. Once per outage: cleared when a socket opens.
+     */
+    private outageReported;
+    /**
+     * Where the connection is.
+     *
+     * - `idle` — no socket, and none wanted yet (the connection is lazy), or
+     *   the last one was dropped by a sign-out.
+     * - `connecting` — dialling, with no outage in progress.
+     * - `connected` — the socket is open.
+     * - `reconnecting` — the socket dropped and the client is redialling. A
+     *   blip, so far: nothing has been reported.
+     * - `disconnected` — the outage has outlasted the blip budget. Every
+     *   subscription and joined channel has been told `CONNECTION_LOST` once;
+     *   the client keeps redialling (every 30 s at most) while any exists.
+     * - `closed` — `client.close()`. Final.
+     */
+    get state(): RealtimeConnectionState;
+    /** Called on every change of {@link state}. Returns the unsubscribe. */
+    onStateChange(listener: (state: RealtimeConnectionState) => void): () => void;
+    private setState;
     /**
      * Whether a socket exists at all (open or still opening).
      *
@@ -41,6 +72,13 @@ export declare class RebaseWebSocketClient {
     onChannelMessage(channel: string, handler: (message: ChannelMessage) => void): () => void;
     /** Notified after the socket comes back, so channels can re-join. */
     onReconnect(handler: () => void): () => void;
+    /**
+     * Notified once per outage that outlasted a blip, with the
+     * `CONNECTION_LOST` error — so a joined channel can tell its `onError`
+     * handlers, as subscriptions are told through theirs.
+     */
+    onConnectionLost(handler: (error: RebaseApiError) => void): () => void;
+    private connectionLostHandlers;
     on(event: "connect" | "disconnect" | "reconnect" | "error", cb: (...args: unknown[]) => void): () => boolean;
     private emit;
     private collectionSubscriptions;
@@ -49,7 +87,29 @@ export declare class RebaseWebSocketClient {
     private backendToEntityKey;
     private pendingRequests;
     private reconnectAttempts;
+    /**
+     * With nothing registered, how many failed redials before the client stops
+     * trying until something asks for the connection. With a registration it
+     * never stops.
+     */
     private maxReconnectAttempts;
+    /**
+     * How many failed redials make a blip an outage: the point at which every
+     * registration is told `CONNECTION_LOST` and {@link state} reads
+     * `disconnected`. Three is 2 + 4 + 8 s of backoff, about 14 s down.
+     */
+    private lostAfterAttempts;
+    /**
+     * Whether a socket of this client has ever opened — what makes the next
+     * open a *reconnect*, whose server has forgotten every subscription and
+     * channel membership and must be told them again.
+     *
+     * Not `reconnectAttempts > 0`: that counter is a backoff budget, and a
+     * fresh one (after giving up, or after a sign-out dropped the socket)
+     * starts at zero, so the socket that finally came back looked like a first
+     * connect and nothing was re-sent.
+     */
+    private hadConnection;
     private isConnected;
     private messageQueue;
     private requestTimeoutMs;
@@ -60,6 +120,7 @@ export declare class RebaseWebSocketClient {
     private WebSocketConstructor;
     onUnauthorized?: () => Promise<boolean>;
     private refreshInProgress;
+    private readonly impersonate?;
     constructor(config: RebaseWebSocketConfig);
     /**
      * Open the socket if it is not open (or opening) already.
@@ -70,12 +131,20 @@ export declare class RebaseWebSocketClient {
      */
     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.
+     * Dial now rather than at the next backoff step — the browser says the
+     * network is back, or the tab is in front of the user again. Both are the
+     * usual end of an outage; neither fires for a server restart, which the
+     * backoff covers.
+     */
+    private retryNow;
+    /**
+     * `online` and `visibilitychange`. Registered lazily so a Node client, or a
+     * page that never subscribes, adds no listener.
      */
-    private installOnlineListener;
+    private installNetworkListeners;
+    private removeNetworkListeners;
     private onlineListener;
+    private visibilityListener;
     /**
      * Authenticate the WebSocket connection
      */
@@ -95,7 +164,43 @@ export declare class RebaseWebSocketClient {
     disconnect(permanent?: boolean): void;
     private initWebSocket;
     private processMessageQueue;
+    /**
+     * Whether a frame that waited in the queue should go out on the socket
+     * that just opened. Only a subscribe can be refused, and one is exactly
+     * when sending it would give the server a subscription this side will not
+     * read:
+     *
+     * - Its registration is gone, or has been given a new id, while it waited.
+     *   A listener that unmounted before the socket opened (a StrictMode double
+     *   mount does exactly this) sends no `unsubscribe`, because there was no
+     *   socket to send it on, so the server would keep that one forever.
+     * - This open is a reconnect. `resubscribeAll` sends every registration
+     *   under a fresh id right after the queue drains, so the queued copy would
+     *   be the second of two. It is handed back to that pass instead.
+     */
+    private shouldSendQueued;
     private attemptReconnect;
+    /**
+     * Whether anything depends on the socket coming back: a subscription, a
+     * joined channel, or a request whose caller is still waiting for a socket.
+     */
+    private hasRegistrations;
+    /**
+     * Tell every subscription and joined channel, once per outage, that the
+     * connection is down and their data is not updating.
+     *
+     * Registrations are kept — that is the difference from a subscribe that
+     * failed. When the socket is back they are re-subscribed, and the fresh
+     * `onUpdate` is the recovery.
+     */
+    private reportConnectionLost;
+    private notifyError;
+    /**
+     * A listener attaching while an outage is being reported is told at once:
+     * its subscribe waits for a socket that may be minutes away, and nothing
+     * else would say so.
+     */
+    private reportOutageTo;
     private isAuthError;
     private handleAuthFailure;
     /**
@@ -112,6 +217,15 @@ export declare class RebaseWebSocketClient {
      * Not part of the stable surface — prefer `client.realtime.channel(name)`.
      */
     sendMessage(message: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Frames whose caller has already been answered — timed out, or rejected
+     * by a close. One can still be on its way to the socket (awaiting
+     * authentication), and must not be written after its caller was told it
+     * failed.
+     */
+    private abandonedFrames;
+    /** Whether the server answers this frame with a response envelope. */
+    private expectsResponse;
     private doSendMessage;
     fetchCollection<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<Record<string, unknown>[]>;
     fetchOne<M extends Record<string, unknown>>(props: FetchOneProps<M>): Promise<Record<string, unknown> | undefined>;
@@ -121,6 +235,16 @@ export declare class RebaseWebSocketClient {
         database?: string;
         role?: string;
     }): Promise<Record<string, unknown>[]>;
+    /**
+     * Run a script a person wrote — the Studio console — and get back what its
+     * last statement returned, every value as the database's text, with the
+     * table column each result column was read from. See
+     * `SQLAdmin.runSqlScript`.
+     */
+    runSqlScript(sql: string, options?: {
+        database?: string;
+        role?: string;
+    }): Promise<SqlScriptResult>;
     fetchAvailableDatabases(): Promise<string[]>;
     fetchAvailableRoles(): Promise<string[]>;
     fetchApplicationRoles(): Promise<string[]>;
@@ -191,6 +315,14 @@ export declare class RebaseWebSocketClient {
      * firing mid-reconnect would tear down healthy subscriptions.
      */
     private suspendSubscribeWatchdogs;
+    /**
+     * Drop every registration's cached rows, keeping the registrations.
+     *
+     * A registration without rows counts as not loaded, so the next listener
+     * to attach asks the server (or waits for the resubscribe) instead of
+     * being handed what is cached.
+     */
+    private forgetCachedData;
     /**
      * Arm watchdogs for subscribes that were requested while offline and have
      * just been flushed to the socket. Their timers were deliberately not set at
@@ -199,11 +331,6 @@ export declare class RebaseWebSocketClient {
     private armPendingSubscribeWatchdogs;
     private sendCollectionSubscribeWatchdog;
     private sendEntitySubscribeWatchdog;
-    /**
-     * Fail every subscription that never received data. Called when reconnection
-     * is given up on, so views surface an error instead of spinning forever.
-     */
-    private failAllPendingSubscriptions;
     /**
      * Re-send all active subscriptions to the backend after a reconnect.
      * The server wipes subscription state when a client disconnects, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebasepro/client",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "HTTP SDK client for the Rebase custom backend",
   "keywords": [
     "rebase",
@@ -41,9 +41,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@rebasepro/common": "0.22.0",
-    "@rebasepro/types": "0.22.0",
-    "@rebasepro/utils": "0.22.0"
+    "@rebasepro/common": "0.24.0",
+    "@rebasepro/utils": "0.24.0",
+    "@rebasepro/types": "0.24.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",