@rebasepro/client 0.24.0 → 0.24.1-canary.gcb918fc

package/dist/websocket.d.ts

@@ -1,8 +1,11 @@
-import { DeleteProps, CollectionConfig, FetchCollectionProps, ListenCollectionProps, FetchOneProps, SaveProps, CollectionUpdateMeta, ChannelMessage, TableMetadata, BranchInfo, RebaseApiError, type RealtimeConnectionState } from "@rebasepro/types";
+import { DeleteProps, CollectionConfig, FetchCollectionProps, ListenCollectionProps, FetchOneProps, ListenOneTarget, 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 */
+    /**
+     * Where the token the socket authenticates with comes from, asked each
+     * time it authenticates. A falsy answer leaves it anonymous.
+     */
     getAuthToken?: () => Promise<string | null>;
     /** Optional WebSocket constructor to override globalThis.WebSocket (e.g. for Node environments) */
     WebSocket?: typeof WebSocket;
@@ -17,6 +20,11 @@ export interface RebaseWebSocketConfig {
 export declare class RebaseWebSocketClient {
     private websocketUrl;
     private ws;
+    /**
+     * Where the socket's token comes from. A client built by
+     * `createRebaseClient()` resolves it through the HTTP transport, so
+     * `client.setAuthTokenGetter()` and `client.setToken()` reach both.
+     */
     getAuthToken?: () => Promise<string | null>;
     private listeners;
     /** Channel-name → handlers, for broadcast and presence frames. */
@@ -68,6 +76,26 @@ export declare class RebaseWebSocketClient {
     get hasSocket(): boolean;
     /** So the "no WebSocket in this environment" warning is said once, not per call. */
     private warnedNoWebSocket;
+    /**
+     * What the server said in its `hello` it does for this socket: empty
+     * until then, after a close, and for a server that sends no `hello`.
+     */
+    private serverOptIns;
+    /** This socket's id on the server, from its `hello` (with `channel_seq`). */
+    private serverClientId;
+    /** When the current socket last delivered anything, heartbeats included. */
+    private lastFrameAt;
+    private livenessTimer;
+    /** Give up on the current socket as though it had closed. Set per socket. */
+    private dropSocket;
+    /** Whether the server agreed, in its `hello`, to `name` for this socket. */
+    hasServerOptIn(name: string): boolean;
+    /**
+     * This socket's id on the server, as its broadcasts' `senderId` in a
+     * channel's history. Known once a server that numbers retained channels
+     * for it (`channel_seq`) has said hello.
+     */
+    get socketClientId(): string | undefined;
     /** Subscribe to broadcast/presence frames for one channel. */
     onChannelMessage(channel: string, handler: (message: ChannelMessage) => void): () => void;
     /** Notified after the socket comes back, so channels can re-join. */
@@ -94,11 +122,11 @@ export declare class RebaseWebSocketClient {
      */
     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.
+     * Reports the outage once the connection has been down for
+     * {@link OUTAGE_REPORT_AFTER_MS}. Armed by the first redial after a drop,
+     * cleared when a socket opens or the caller disconnects.
      */
-    private lostAfterAttempts;
+    private outageTimer;
     /**
      * Whether a socket of this client has ever opened — what makes the next
      * open a *reconnect*, whose server has forgotten every subscription and
@@ -150,7 +178,13 @@ export declare class RebaseWebSocketClient {
      */
     authenticate(token: string): Promise<void>;
     /**
-     * Set the auth token getter function
+     * Replace where this socket's token comes from, and authenticate an open,
+     * unauthenticated socket with it.
+     *
+     * @deprecated Use `client.setAuthTokenGetter()` instead — on a client from
+     * `createRebaseClient()` the socket already resolves its token through it,
+     * together with HTTP, and setting one here splits the two. Will be removed
+     * in a future release.
      */
     setAuthTokenGetter(getAuthToken: () => Promise<string | null>): void;
     /**
@@ -163,6 +197,15 @@ export declare class RebaseWebSocketClient {
      */
     disconnect(permanent?: boolean): void;
     private initWebSocket;
+    /** Read the server's `hello`: what it agreed to, and start watching for heartbeats. */
+    private receiveHello;
+    /**
+     * Redial when two heartbeats in a row have not arrived. Anything the
+     * server sends counts as a beat, so a busy socket is never judged on them.
+     */
+    private watchLiveness;
+    private stopLivenessWatch;
+    private forgetServerOptIns;
     private processMessageQueue;
     /**
      * Whether a frame that waited in the queue should go out on the socket
@@ -193,6 +236,7 @@ export declare class RebaseWebSocketClient {
      * failed. When the socket is back they are re-subscribed, and the fresh
      * `onUpdate` is the recovery.
      */
+    private clearOutageTimer;
     private reportConnectionLost;
     private notifyError;
     /**
@@ -231,6 +275,14 @@ export declare class RebaseWebSocketClient {
     fetchOne<M extends Record<string, unknown>>(props: FetchOneProps<M>): Promise<Record<string, unknown> | undefined>;
     save<M extends Record<string, unknown>>(props: SaveProps<M>): Promise<Record<string, unknown>>;
     delete<M extends Record<string, unknown>>(props: DeleteProps<M>): Promise<void>;
+    /**
+     * @deprecated Will leave the public `client.ws` type in the next minor.
+     * Not part of the app-facing client: the admin UI's SQL console reaches it
+     * through `<Rebase>`, and it answers only a caller with `database:write`.
+     * App code has no supported SQL or branch path on the client; run SQL
+     * server-side (`isSQLAdmin(driver.admin)`), and use `client.admin` for
+     * users and roles.
+     */
     executeSql(sql: string, options?: {
         database?: string;
         role?: string;
@@ -244,7 +296,14 @@ export declare class RebaseWebSocketClient {
     runSqlScript(sql: string, options?: {
         database?: string;
         role?: string;
+        signal?: AbortSignal;
     }): Promise<SqlScriptResult>;
+    /**
+     * Stop a console run its caller gave up on: never written if it has not
+     * been yet, and cancelled on a server whose `hello` listed `cancel_sql`. A server
+     * that does not is left to finish it, bounded by its `statement_timeout`.
+     */
+    private cancelSqlRun;
     fetchAvailableDatabases(): Promise<string[]>;
     fetchAvailableRoles(): Promise<string[]>;
     fetchApplicationRoles(): Promise<string[]>;
@@ -253,17 +312,41 @@ export declare class RebaseWebSocketClient {
     count<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number>;
     fetchUnmappedTables(mappedPaths?: string[]): Promise<string[]>;
     fetchTableMetadata(tableName: string): Promise<TableMetadata>;
+    /**
+     * @deprecated Will leave the public `client.ws` type in the next minor.
+     * Not part of the app-facing client: the admin UI's SQL console reaches it
+     * through `<Rebase>`, and it answers only a caller with `database:write`.
+     * App code has no supported SQL or branch path on the client; run SQL
+     * server-side (`isSQLAdmin(driver.admin)`), and use `client.admin` for
+     * users and roles.
+     */
     createBranch(name: string, options?: {
         source?: string;
     }): Promise<BranchInfo>;
+    /**
+     * @deprecated Will leave the public `client.ws` type in the next minor.
+     * Not part of the app-facing client: the admin UI's SQL console reaches it
+     * through `<Rebase>`, and it answers only a caller with `database:write`.
+     * App code has no supported SQL or branch path on the client; run SQL
+     * server-side (`isSQLAdmin(driver.admin)`), and use `client.admin` for
+     * users and roles.
+     */
     deleteBranch(name: string): Promise<void>;
     listBranches(): Promise<BranchInfo[]>;
     /**
-     * Recursively compare two values for structural equality.
-     * Handles primitives, null, undefined, Date, RegExp, arrays, and plain objects.
+     * Recursively compare two values a refetch can carry for structural
+     * equality: primitives, null, undefined, Date, RegExp, arrays and objects.
+     *
+     * A relation compares by the reference it holds, not by the row it happens
+     * to have loaded, so its `data` is left out on both sides. That used to be
+     * done by normalising each side into a copy first — two deep copies of
+     * every cached row on every frame, most of which then compared equal. It is
+     * done in place now, and an unchanged row costs no copy.
+     *
+     * `relationAware` is off for a relation's own fields: the copies never
+     * looked inside those either.
      */
     private deepEqual;
-    private normalizeForComparison;
     /**
      * The address of a row, for matching it against another copy of itself.
      *
@@ -285,7 +368,7 @@ export declare class RebaseWebSocketClient {
      */
     private mergeRows;
     listenCollection<M extends Record<string, unknown>>(props: Omit<ListenCollectionProps<M>, "onUpdate" | "onError">, onUpdate: (rows: Record<string, unknown>[], meta?: CollectionUpdateMeta) => void, onError?: (error: Error) => void): () => void;
-    listenOne<M extends Record<string, unknown>>(props: FetchOneProps<M>, onUpdate: (row: Record<string, unknown> | null) => void, onError?: (error: Error) => void): () => void;
+    listenOne<M extends Record<string, unknown>>(props: ListenOneTarget<M>, onUpdate: (row: Record<string, unknown> | null) => void, onError?: (error: Error) => void): () => void;
     /**
      * Send a `subscribe_collection` for an already-registered subscription and
      * arm its watchdog.

package/package.json

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

package/dist/query_builder.d.ts

@@ -1 +0,0 @@
-export { QueryBuilder, or, and, cond } from "@rebasepro/common";