@rebasepro/client 0.9.1-canary.fd3754b → 0.10.0

package/src/index.ts

@@ -10,6 +10,7 @@ import { createFunctionsClient } from "./functions";
 import { createStorage } from "./storage";
 import { ClientStorageSourceRegistry } from "./storage-registry";
 import { RebaseWebSocketClient } from "./websocket";
+import { RebaseRealtimeChannel, type ChannelOptions } from "./realtime-channel";
 import {
     DEFAULT_STORAGE_SOURCE_KEY,
     InsertOf,
@@ -76,6 +77,16 @@ export type { FunctionInvokeOptions, FunctionsClient } from "./functions";
 // but re-exported (see @internal on the class) because the `client-postgres`
 // driver constructs it directly. Not a stable app-facing API.
 export { RebaseWebSocketClient } from "./websocket";
+export { RebaseRealtimeChannel } from "./realtime-channel";
+export type {
+    PresenceState,
+    PresenceDiff,
+    BroadcastEvent,
+    ChannelTransport,
+    ChannelOptions,
+    ChannelHistoryEntry,
+    ChannelHistoryResult
+} from "./realtime-channel";
 
 export interface CreateRebaseClientOptions extends RebaseClientConfig {
     auth?: CreateAuthOptions;
@@ -142,11 +153,38 @@ export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<Rebase
     apiKeys: ReturnType<typeof createApiKeys>;
     functions: ReturnType<typeof createFunctionsClient>;
     ws?: RebaseWebSocketClient;
+    /**
+     * Broadcast and presence channels.
+     *
+     * Was missing from this type while present on the returned object, which
+     * made `client.realtime.channel(...)` a type error and forced every adopter
+     * to cast around the feature before they could reach it.
+     */
+    realtime: {
+        /**
+         * Join a broadcast/presence channel. Repeated calls with the same name
+         * return the same channel object. Throws only when the client was
+         * created with `realtime: false`.
+         *
+         * Pass `{ history: true }` to have the channel replay what it missed on
+         * join and on every reconnect, for channels the server retains.
+         */
+        channel: (name: string, options?: ChannelOptions) => RebaseRealtimeChannel;
+    };
+    /**
+     * Release the realtime socket and its reconnect timer.
+     *
+     * 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.
+     */
+    close: () => void;
     storage: StorageSource;
     storageRegistry: StorageSourceRegistry;
     createStorageSource: (storageId: string) => StorageSource;
     fetchStorageSources: () => Promise<StorageSourceDefinition[]>;
     call: <T = unknown>(endpoint: string, payload?: unknown) => Promise<T>;
+    collection: <M extends Record<string, unknown> = Record<string, unknown>>(slug: string) => CollectionClient<M>;
     data: TypedDataLayer<DB>;
 };
 
@@ -238,9 +276,17 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         return storageSourcesPromise;
     };
 
-    const resolvedWsUrl = options.websocketUrl ?? deriveWebSocketUrl(options.baseUrl);
+    // Opting out has to happen before the URL is derived: `deriveWebSocketUrl`
+    // always produces one, so a truthy check alone can never leave the socket
+    // closed.
+    const realtimeEnabled = options.realtime !== false;
+    const resolvedWsUrl = realtimeEnabled
+        ? (options.websocketUrl ?? deriveWebSocketUrl(options.baseUrl))
+        : undefined;
 
     let ws: RebaseWebSocketClient | undefined;
+    /** One channel object per name — see `realtime.channel`. */
+    const realtimeChannels = new Map<string, RebaseRealtimeChannel>();
     if (resolvedWsUrl) {
         const wsOnUnauthorized = options.onUnauthorized || (async () => {
             try {
@@ -268,9 +314,15 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         auth.onAuthStateChange((event, session) => {
             if (!ws) return;
             if (event === "SIGNED_OUT") {
+                // Not permanent: the client stays usable, and a later subscribe
+                // should reconnect anonymously.
                 ws.disconnect();
             } else if (event === "SIGNED_IN" || event === "TOKEN_REFRESHED") {
-                if (session?.accessToken) {
+                // Only re-authenticate a socket that already exists. Signing in
+                // is not a request for realtime, and dialling here would undo
+                // lazy connect for every app with a login. A socket opened
+                // later authenticates itself from `getAuthToken` on open.
+                if (session?.accessToken && ws.hasSocket) {
                     ws.authenticate(session.accessToken).catch(console.warn);
                 }
             }
@@ -408,6 +460,57 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         createStorageSource,
         fetchStorageSources,
         ws,
+        realtime: {
+            /**
+             * Join a broadcast/presence channel.
+             *
+             * Repeated calls with the same name return the same channel, so
+             * separate components can attach handlers without each opening its
+             * own membership — and `leave()` from one would otherwise silently
+             * cut off the others.
+             */
+            channel: (name: string, options?: ChannelOptions): RebaseRealtimeChannel => {
+                // Only `realtime: false` gets here — a hard opt-out, so this
+                // stays an error. Being merely *unconnected* does not: the
+                // socket opens on the first channel operation, which is the
+                // whole point of asking for a channel before you use one.
+                if (!ws) {
+                    throw new RebaseClientError(
+                        "Realtime is disabled on this client (realtime: false), so channels are unavailable."
+                    );
+                }
+                let existing = realtimeChannels.get(name);
+                if (!existing) {
+                    existing = new RebaseRealtimeChannel(name, ws, options);
+                    realtimeChannels.set(name, existing);
+                } else if (options?.history) {
+                    // Same object by name, so options on a later call have no
+                    // new channel to apply to. Asking for history upgrades the
+                    // one that exists rather than being quietly ignored — but
+                    // never the reverse, so a caller that omits the option
+                    // cannot switch it off under one that asked for it.
+                    existing.enableHistory();
+                }
+                return existing;
+            }
+        },
+        /**
+         * Release the realtime socket and its reconnect timer.
+         *
+         * 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.
+         */
+        close: () => {
+            // Channels hold presence heartbeat timers, which would otherwise
+            // keep firing (and keep a Node process alive) after the socket
+            // they publish over is gone.
+            for (const channel of realtimeChannels.values()) void channel.leave();
+            realtimeChannels.clear();
+            // Permanent: nothing queued afterwards may redial and keep the
+            // event loop alive, which is the reason this method exists.
+            ws?.disconnect(true);
+        },
         setToken: transport.setToken,
         setAuthTokenGetter: transport.setAuthTokenGetter,
         setOnUnauthorized: transport.setOnUnauthorized,