@rebasepro/client 0.8.0 → 0.9.1-canary.09aaf62

package/src/websocket.ts

@@ -1,17 +1,18 @@
 import {
-    DeleteEntityProps,
-    Entity,
-    EntityCollection,
+    DeleteProps,
+    CollectionConfig,
     FetchCollectionProps,
-    FetchEntityProps,
-    SaveEntityProps,
+    FetchOneProps,
+    SaveProps,
     WebSocketMessage,
     WebSocketErrorPayload,
     CollectionUpdateMessage,
-    EntityUpdateMessage,
+    SingleUpdateMessage,
     TableMetadata,
-    BranchInfo
+    BranchInfo,
+    RebaseApiError
 } from "@rebasepro/types";
+import { buildCompositeId, COMPOSITE_ID_SEPARATOR, type PrimaryKeyInfo } from "@rebasepro/common";
 import { rebaseReviver } from "./reviver";
 
 
@@ -29,7 +30,14 @@ function extractMessageError(message: WebSocketMessage): { errorMessage: string;
     const errorCode = typeof errPayload === "object"
         ? errPayload.code
         : payload?.code;
-    return { errorMessage,
+    // Callers treat this as a string (`.toLowerCase()` in isAuthError). A frame
+    // carrying a non-string here would throw inside the message handler, where
+    // the surrounding try/catch would swallow it — and a subscription error that
+    // never reaches its listener is a view stuck loading forever.
+    const safeMessage = typeof errorMessage === "string"
+        ? errorMessage
+        : (errorMessage == null ? "Unknown error" : JSON.stringify(errorMessage));
+    return { errorMessage: safeMessage,
 errorCode };
 }
 
@@ -44,19 +52,15 @@ export interface RebaseWebSocketConfig {
 }
 
 
-export class ApiError extends Error {
-    public code?: string;
-    public error?: string;
-
-    constructor(message: string, error?: string, code?: string) {
-        super(message);
-        this.name = "ApiError";
-        this.code = code;
-        this.error = error;
-    }
-}
-
-
+/**
+ * Low-level realtime WebSocket client.
+ *
+ * @internal Not a stable app-facing API. `createRebaseClient()` constructs and
+ * manages this internally (exposed as `client.ws`, typed by the minimal
+ * `RebaseWebSocket` contract in `@rebasepro/types`). It is re-exported from the
+ * package root only because the `@rebasepro/client-postgres` driver
+ * instantiates it directly; its surface may change without a major bump.
+ */
 export class RebaseWebSocketClient {
     private websocketUrl: string;
     private ws: WebSocket | null = null;
@@ -68,6 +72,26 @@ export class RebaseWebSocketClient {
 
     private listeners = new Map<string, Set<(...args: unknown[]) => void>>();
 
+    /** Channel-name → handlers, for broadcast and presence frames. */
+    private channelHandlers = new Map<string, Set<(message: Record<string, unknown>) => void>>();
+
+    /** Subscribe to broadcast/presence frames for one channel. */
+    public onChannelMessage(channel: string, handler: (message: Record<string, unknown>) => void): () => void {
+        if (!this.channelHandlers.has(channel)) this.channelHandlers.set(channel, new Set());
+        this.channelHandlers.get(channel)!.add(handler);
+        return () => {
+            const handlers = this.channelHandlers.get(channel);
+            if (!handlers) return;
+            handlers.delete(handler);
+            if (handlers.size === 0) this.channelHandlers.delete(channel);
+        };
+    }
+
+    /** Notified after the socket comes back, so channels can re-join. */
+    public onReconnect(handler: () => void): () => void {
+        return this.on("reconnect", handler);
+    }
+
     public on(event: "connect" | "disconnect" | "reconnect" | "error", cb: (...args: unknown[]) => void) {
         if (!this.listeners.has(event)) {
             this.listeners.set(event, new Set());
@@ -86,25 +110,47 @@ export class RebaseWebSocketClient {
     private collectionSubscriptions = new Map<string, {
         backendSubscriptionId: string;
         callbacks: Map<string, {
-            onUpdate: (entities: Entity[]) => void;
+            onUpdate: (rows: Record<string, unknown>[]) => void;
             onError?: (error: Error) => void;
         }>;
         props: FetchCollectionProps;
-        latestData?: Entity[]; // Cache the latest data
+        latestData?: Record<string, unknown>[]; // Cache the latest flat rows
         lastUpdated?: number; // Timestamp for cache invalidation
         isInitialDataReceived?: boolean; // Track if we got initial data
+        /**
+         * A `subscribe_collection` frame is on the wire and its initial payload
+         * has not arrived yet. Without this, a subscription whose subscribe
+         * failed is indistinguishable from one still loading, and every later
+         * listener attaches to it and waits forever.
+         */
+        subscribeInFlight?: boolean;
+        /**
+         * Watchdog for the above. `subscribe_collection` expects no response
+         * envelope, so it is not covered by `pendingRequests`' timeout — a lost
+         * initial payload would otherwise hang the subscription indefinitely.
+         */
+        subscribeTimeout?: ReturnType<typeof setTimeout>;
+        /**
+         * The key columns of this collection, as told by the server on a patch.
+         * Rows are columns only, and the SDK holds no collection config, so
+         * without this there is nothing to derive an address from.
+         */
+        pks?: PrimaryKeyInfo[];
     }>();
 
-    private entitySubscriptions = new Map<string, {
+    private singleSubscriptions = new Map<string, {
         backendSubscriptionId: string;
         callbacks: Map<string, {
-            onUpdate: (entity: Entity | null) => void;
+            onUpdate: (row: Record<string, unknown> | null) => void;
             onError?: (error: Error) => void;
         }>;
-        props: FetchEntityProps;
-        latestData?: Entity | null; // Cache the latest data
+        props: FetchOneProps;
+        latestData?: Record<string, unknown> | null; // Cache the latest flat row
         lastUpdated?: number; // Timestamp for cache invalidation
         isInitialDataReceived?: boolean; // Track if we got initial data
+        /** See the collection subscription counterparts. */
+        subscribeInFlight?: boolean;
+        subscribeTimeout?: ReturnType<typeof setTimeout>;
     }>();
 
     // Maps to quickly find subscription by backend subscription ID
@@ -122,6 +168,7 @@ export class RebaseWebSocketClient {
     private isConnected = false;
     private messageQueue: Record<string, unknown>[] = [];
     private requestTimeoutMs = 30000;
+    private subscriptionTimeoutMs = 30000;
     private reconnectTimeout: ReturnType<typeof setTimeout> | null = null;
 
     private isAuthenticated = false;
@@ -267,6 +314,10 @@ export class RebaseWebSocketClient {
                 if (wasReconnect) {
                     this.resubscribeAll();
                 }
+
+                // Subscribes requested while offline have just gone out; they
+                // could not be watchdogged at request time.
+                this.armPendingSubscribeWatchdogs();
             };
 
             this.ws!.onmessage = (event) => {
@@ -283,6 +334,9 @@ export class RebaseWebSocketClient {
                 this.isConnected = false;
                 this.isAuthenticated = false;
                 this.authPromise = null;
+                // The reconnect path re-subscribes everything; a watchdog firing
+                // in the meantime would tear down healthy subscriptions.
+                this.suspendSubscribeWatchdogs();
                 this.emit("disconnect");
 
                 // Re-queue pending requests so the UI doesn't hang indefinitely or crash
@@ -294,7 +348,7 @@ export class RebaseWebSocketClient {
                         request.message._queuedReject = request.reject;
                         this.messageQueue.push(request.message);
                     } else {
-                        request.reject(new ApiError("Connection closed", "Connection closed"));
+                        request.reject(new RebaseApiError("Connection closed"));
                     }
                     this.pendingRequests.delete(reqId);
                 }
@@ -323,6 +377,11 @@ export class RebaseWebSocketClient {
     private attemptReconnect() {
         if (this.reconnectAttempts >= this.maxReconnectAttempts) {
             console.error("Max reconnection attempts reached");
+            // Nothing will re-subscribe now, so stop every subscription that
+            // never loaded from spinning forever.
+            this.failAllPendingSubscriptions(
+                new RebaseApiError("Connection lost", { code: "CONNECTION_LOST" })
+            );
             return;
         }
 
@@ -380,7 +439,7 @@ export class RebaseWebSocketClient {
     }
 
     /**
-     * Shared logic for re-subscribing a collection or entity subscription
+     * Shared logic for re-subscribing a collection or row subscription
      * after an auth error is resolved by refreshing credentials.
      */
     private resubscribeAfterAuthRefresh(
@@ -388,12 +447,12 @@ export class RebaseWebSocketClient {
         subscription: {
             backendSubscriptionId: string;
             callbacks: Map<string, { onUpdate: (...args: never[]) => void; onError?: (error: Error) => void }>;
-            props: FetchCollectionProps | FetchEntityProps;
+            props: FetchCollectionProps | FetchOneProps;
         },
         subscriptionKey: string,
-        idPrefix: "collection" | "entity",
+        idPrefix: "collection" | "row",
         backendKeyMap: Map<string, string>,
-        messageType: "subscribe_collection" | "subscribe_entity"
+        messageType: "subscribe_collection" | "subscribe_one"
     ): void {
         this.handleAuthFailure().then(refreshed => {
             if (refreshed) {
@@ -403,29 +462,32 @@ export class RebaseWebSocketClient {
                 backendKeyMap.delete(oldBackendId);
                 backendKeyMap.set(newBackendId, subscriptionKey);
 
-                this.sendMessage({
-                    type: messageType,
-                    payload: {
-                        ...subscription.props,
-                        subscriptionId: newBackendId
-                    }
-                }).catch(error => {
-                    console.error(`[WS] Failed to re-subscribe ${idPrefix} after auth refresh:`, subscriptionKey, error);
-                    subscription.callbacks.forEach(callback => {
-                        if (callback.onError) callback.onError(error);
-                    });
-                });
+                // Route through the helpers so the retry is watchdogged too.
+                if (messageType === "subscribe_collection") {
+                    this.sendCollectionSubscribe(subscriptionKey);
+                } else {
+                    this.sendEntitySubscribe(subscriptionKey);
+                }
+                return;
+            }
+
+            // The refresh did not produce usable credentials. Report the original
+            // error and drop the registration, so a later mount can try again
+            // rather than attaching to a subscription that will never load.
+            const { errorMessage, errorCode } = extractMessageError(message);
+            const error = new RebaseApiError(errorMessage, { code: errorCode });
+            if (messageType === "subscribe_collection") {
+                this.failCollectionSubscription(subscriptionKey, error);
             } else {
-                const { errorMessage, errorCode } = extractMessageError(message);
-                const error = new ApiError(errorMessage, errorMessage, errorCode);
-                subscription.callbacks.forEach(callback => {
-                    if (callback.onError) callback.onError(error);
-                });
+                this.failEntitySubscription(subscriptionKey, error);
             }
         }).catch(err => {
-            subscription.callbacks.forEach(callback => {
-                if (callback.onError) callback.onError(err);
-            });
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (messageType === "subscribe_collection") {
+                this.failCollectionSubscription(subscriptionKey, error);
+            } else {
+                this.failEntitySubscription(subscriptionKey, error);
+            }
         });
     }
 
@@ -447,7 +509,7 @@ export class RebaseWebSocketClient {
                             this.doSendMessage(pendingReq.message, pendingReq.resolve, pendingReq.reject).catch(pendingReq.reject);
                         } else {
                             const { errorMessage, errorCode } = extractMessageError(message);
-                            pendingReq.reject(new ApiError(errorMessage, errorMessage, errorCode));
+                            pendingReq.reject(new RebaseApiError(errorMessage, { code: errorCode }));
                         }
                     }).catch(err => {
                         pendingReq.reject(err);
@@ -455,7 +517,7 @@ export class RebaseWebSocketClient {
                 } else {
                     this.pendingRequests.delete(requestId);
                     const { errorMessage, errorCode } = extractMessageError(message);
-                    pendingReq.reject(new ApiError(errorMessage, errorMessage, errorCode));
+                    pendingReq.reject(new RebaseApiError(errorMessage, { code: errorCode }));
                 }
             } else {
                 this.pendingRequests.delete(requestId);
@@ -464,29 +526,60 @@ export class RebaseWebSocketClient {
             return;
         }
 
+        // Channel traffic (broadcast / presence) is addressed by channel name
+        // rather than by requestId or subscriptionId, so it is dispatched
+        // before the subscription paths — none of which would match it, and
+        // the message would otherwise fall through and be dropped silently.
+        if (typeof message.channel === "string" &&
+            (type === "broadcast" || type === "presence_state" || type === "presence_diff")) {
+            const handlers = this.channelHandlers.get(message.channel);
+            if (handlers) {
+                for (const handler of [...handlers]) {
+                    try {
+                        handler(message as unknown as Record<string, unknown>);
+                    } catch (error) {
+                        console.error("Error in channel handler:", error);
+                    }
+                }
+            }
+            return;
+        }
+
         // Handle subscription updates for collection subscriptions
         if (subscriptionId && type === "collection_update") {
             const subscriptionKey = this.backendToCollectionKey.get(subscriptionId);
             if (subscriptionKey) {
                 const collectionSub = this.collectionSubscriptions.get(subscriptionKey);
                 if (collectionSub) {
-                    const incomingEntities = (message.entities || []) as Entity[];
+                    const wireEntities = (message.rows || []) as unknown as Record<string, unknown>[];
+                    const incomingRows = wireEntities;
+
+                    // The keys arrive with the rows, so they are known before the
+                    // first merge — a CDC-driven change never sends a patch, and
+                    // learning them from patches alone would leave every
+                    // externally-written collection unable to match a thing.
+                    const updatePks = (message as unknown as { pks?: PrimaryKeyInfo[] }).pks;
+                    if (updatePks) collectionSub.pks = updatePks;
 
-                    // Structural merge: preserve cached entity references for entities
+                    // Structural merge: preserve cached row references for rows
                     // whose values haven't changed. This prevents downstream React components
                     // from re-rendering (VirtualTableCell uses deepEqual on rowData —
                     // same reference = instant true, avoiding expensive deep comparison).
-                    const entities = this.mergeEntities(collectionSub.latestData, incomingEntities);
+                    const rows = this.mergeRows(collectionSub.latestData, incomingRows, collectionSub.pks);
 
                     // Cache the latest data with optimizations
-                    collectionSub.latestData = entities;
+                    collectionSub.latestData = rows;
                     collectionSub.lastUpdated = Date.now();
                     collectionSub.isInitialDataReceived = true;
+                    // The subscribe landed — stand the watchdog down.
+                    if (collectionSub.subscribeTimeout) clearTimeout(collectionSub.subscribeTimeout);
+                    collectionSub.subscribeTimeout = undefined;
+                    collectionSub.subscribeInFlight = false;
 
                     // Notify all callbacks for this subscription
                     collectionSub.callbacks.forEach(callback => {
                         try {
-                            callback.onUpdate(entities);
+                            callback.onUpdate(rows);
                         } catch (error) {
                             console.error("Error in collection subscription callback:", error);
                             if (callback.onError) {
@@ -499,30 +592,43 @@ export class RebaseWebSocketClient {
             }
         }
 
-        // Handle instant entity-level patches for collection subscriptions.
+        // Handle instant row-level patches for collection subscriptions.
         // These arrive before the full refetch and give immediate cross-tab feedback.
-        if (subscriptionId && type === "collection_entity_patch") {
+        if (subscriptionId && type === "collection_patch") {
             const subscriptionKey = this.backendToCollectionKey.get(subscriptionId);
             if (subscriptionKey) {
                 const collectionSub = this.collectionSubscriptions.get(subscriptionKey);
                 if (collectionSub && collectionSub.isInitialDataReceived && collectionSub.latestData) {
-                    const patchEntity = message.entity ?? null;
-                    const patchEntityId = (message as unknown as { entityId: string }).entityId;
-                    let updated: Entity[];
-
-                    if (patchEntity === null || patchEntity === undefined) {
-                        // Entity was deleted — remove it from the cached list
-                        updated = collectionSub.latestData.filter(e => String(e.id) !== String(patchEntityId));
+                    const patchWireEntity = message.row ?? null;
+                    const patchMessage = message as unknown as { id: string; pks?: PrimaryKeyInfo[] };
+                    const patchEntityId = patchMessage.id;
+                    // The server knows the key columns; remember them, because the
+                    // refetch reconciliation needs them too and carries no id.
+                    if (patchMessage.pks) collectionSub.pks = patchMessage.pks;
+                    const patchRow = patchWireEntity ? (patchWireEntity as unknown as Record<string, unknown>) : null;
+                    let updated: Record<string, unknown>[];
+
+                    if (patchRow === null) {
+                        // Row was deleted — remove it from the cached list
+                        updated = collectionSub.latestData.filter(
+                            e => this.rowAddress(e, collectionSub.pks) !== String(patchEntityId)
+                        );
                     } else {
-                        // Entity was created or updated — merge into the cached list
-                        const idx = collectionSub.latestData.findIndex(e => String(e.id) === String(patchEntity.id));
+                        // Row was created or updated — merge into the cached list.
+                        // Matched against the patch's own address rather than
+                        // anything read off the row: `patchRow.id` is undefined
+                        // for a table not keyed on `id`, so every update looked
+                        // like a new row and was prepended as a duplicate.
+                        const idx = collectionSub.latestData.findIndex(
+                            e => this.rowAddress(e, collectionSub.pks) === String(patchEntityId)
+                        );
                         if (idx >= 0) {
                             // Update in place (preserve array position)
                             updated = [...collectionSub.latestData];
-                            updated[idx] = patchEntity;
+                            updated[idx] = patchRow;
                         } else {
-                            // New entity — prepend (most recently created entities first)
-                            updated = [patchEntity, ...collectionSub.latestData];
+                            // New row — prepend (most recently created first)
+                            updated = [patchRow, ...collectionSub.latestData];
                         }
                     }
 
@@ -545,24 +651,28 @@ export class RebaseWebSocketClient {
             }
         }
 
-        // Handle subscription updates for entity subscriptions
-        if (subscriptionId && type === "entity_update") {
+        // Handle subscription updates for row subscriptions
+        if (subscriptionId && type === "single_update") {
             const subscriptionKey = this.backendToEntityKey.get(subscriptionId);
             if (subscriptionKey) {
-                const entitySub = this.entitySubscriptions.get(subscriptionKey);
+                const entitySub = this.singleSubscriptions.get(subscriptionKey);
                 if (entitySub) {
-                    const entity = message.entity ?? null;
+                    const wireEntity = message.row ?? null;
+                    const row = wireEntity ? (wireEntity as unknown as Record<string, unknown>) : null;
                     // Cache the latest data with optimizations
-                    entitySub.latestData = entity;
+                    entitySub.latestData = row;
                     entitySub.lastUpdated = Date.now();
                     entitySub.isInitialDataReceived = true;
+                    if (entitySub.subscribeTimeout) clearTimeout(entitySub.subscribeTimeout);
+                    entitySub.subscribeTimeout = undefined;
+                    entitySub.subscribeInFlight = false;
 
                     // Notify all callbacks for this subscription
                     entitySub.callbacks.forEach(callback => {
                         try {
-                            callback.onUpdate(entity);
+                            callback.onUpdate(row);
                         } catch (error) {
-                            console.error("Error in entity subscription callback:", error);
+                            console.error("Error in row subscription callback:", error);
                             if (callback.onError) {
                                 callback.onError(error instanceof Error ? error : new Error(String(error)));
                             }
@@ -591,8 +701,16 @@ export class RebaseWebSocketClient {
                         return;
                     }
 
+                    // The server answered, so nothing is in flight any more. Leave
+                    // the registration in place (its listeners are still mounted
+                    // and have been told), but marked idle so the next listener
+                    // re-subscribes instead of attaching to a dead entry.
+                    if (collectionSub.subscribeTimeout) clearTimeout(collectionSub.subscribeTimeout);
+                    collectionSub.subscribeTimeout = undefined;
+                    collectionSub.subscribeInFlight = false;
+
                     const { errorMessage, errorCode } = extractMessageError(message);
-                    const error = new ApiError(errorMessage, errorMessage, errorCode);
+                    const error = new RebaseApiError(errorMessage, { code: errorCode });
                     collectionSub.callbacks.forEach(callback => {
                         if (callback.onError) {
                             callback.onError(error);
@@ -604,22 +722,26 @@ export class RebaseWebSocketClient {
 
             const entityKey = this.backendToEntityKey.get(subscriptionId);
             if (entityKey) {
-                const entitySub = this.entitySubscriptions.get(entityKey);
+                const entitySub = this.singleSubscriptions.get(entityKey);
                 if (entitySub) {
                     if (this.isAuthError(message)) {
                         this.resubscribeAfterAuthRefresh(
                             message,
                             entitySub,
                             entityKey,
-                            "entity",
+                            "row",
                             this.backendToEntityKey,
-                            "subscribe_entity"
+                            "subscribe_one"
                         );
                         return;
                     }
 
+                    if (entitySub.subscribeTimeout) clearTimeout(entitySub.subscribeTimeout);
+                    entitySub.subscribeTimeout = undefined;
+                    entitySub.subscribeInFlight = false;
+
                     const { errorMessage, errorCode } = extractMessageError(message);
-                    const error = new ApiError(errorMessage, errorMessage, errorCode);
+                    const error = new RebaseApiError(errorMessage, { code: errorCode });
                     entitySub.callbacks.forEach(callback => {
                         if (callback.onError) {
                             callback.onError(error);
@@ -639,7 +761,7 @@ export class RebaseWebSocketClient {
             if (message.type === "ERROR" || message.error) {
                 if (callback.onError) {
                     const { errorMessage, errorCode } = extractMessageError(message);
-                    callback.onError(new ApiError(errorMessage, errorMessage, errorCode));
+                    callback.onError(new RebaseApiError(errorMessage, { code: errorCode }));
                 }
             } else {
                 callback.onUpdate(message);
@@ -718,7 +840,11 @@ export class RebaseWebSocketClient {
         }
     }
 
-    private sendMessage(message: Record<string, unknown>): Promise<unknown> {
+    /**
+     * Public because `RebaseRealtimeChannel` sends channel frames through it.
+     * Not part of the stable surface — prefer `client.realtime.channel(name)`.
+     */
+    public sendMessage(message: Record<string, unknown>): Promise<unknown> {
         // If already has a requestId (re-sending from queue), use the stored promise handlers
         const queuedMsg = message as Record<string, unknown> & { _queuedResolve?: (p: unknown) => void; _queuedReject?: (p: Error) => void };
         if (queuedMsg._queuedResolve && queuedMsg._queuedReject) {
@@ -747,7 +873,7 @@ export class RebaseWebSocketClient {
                 await this.ensureAuthenticated();
             } catch (error: unknown) {
                 const errorMessage = error instanceof Error ? error.message : "Authentication required";
-                reject(new ApiError(errorMessage, errorMessage));
+                reject(new RebaseApiError(errorMessage));
                 return;
             }
         }
@@ -757,7 +883,7 @@ export class RebaseWebSocketClient {
 
         const expectsResponse = ![
             "subscribe_collection",
-            "subscribe_entity",
+            "subscribe_one",
             "unsubscribe",
             "join_channel",
             "leave_channel",
@@ -771,7 +897,7 @@ export class RebaseWebSocketClient {
             const timeoutHandle = setTimeout(() => {
                 if (this.pendingRequests.has(requestId)) {
                     this.pendingRequests.delete(requestId);
-                    reject(new ApiError("Request timed out", "Request timed out"));
+                    reject(new RebaseApiError("Request timed out"));
                 }
             }, this.requestTimeoutMs);
 
@@ -797,38 +923,39 @@ export class RebaseWebSocketClient {
             if (expectsResponse) {
                 this.pendingRequests.delete(requestId);
             }
-            reject(new ApiError("Failed to send message", error instanceof Error ? error.message : "Unknown error"));
+            reject(new RebaseApiError("Failed to send message", { cause: error }));
         }
     }
 
     // Data source methods
-    async fetchCollection<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<Entity<M>[]> {
+    async fetchCollection<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<Record<string, unknown>[]> {
         const response = await this.sendMessage({
             type: "FETCH_COLLECTION",
             payload: props
-        }) as { entities?: Entity<M>[] };
-        return response.entities || [];
+        }) as { rows?: Record<string, unknown>[] };
+        return (response.rows || []);
     }
 
-    async fetchEntity<M extends Record<string, unknown>>(props: FetchEntityProps<M>): Promise<Entity<M> | undefined> {
+    async fetchOne<M extends Record<string, unknown>>(props: FetchOneProps<M>): Promise<Record<string, unknown> | undefined> {
         const response = await this.sendMessage({
-            type: "FETCH_ENTITY",
+            type: "FETCH_ONE",
             payload: props
-        }) as { entity?: Entity<M> };
-        return response.entity ?? undefined;
+        }) as { row?: Record<string, unknown> };
+        const wireEntity = response.row;
+        return wireEntity ?? undefined;
     }
 
-    async saveEntity<M extends Record<string, unknown>>(props: SaveEntityProps<M>): Promise<Entity<M>> {
+    async save<M extends Record<string, unknown>>(props: SaveProps<M>): Promise<Record<string, unknown>> {
         const response = await this.sendMessage({
-            type: "SAVE_ENTITY",
+            type: "SAVE",
             payload: props
-        }) as { entity: Entity<M> };
-        return response.entity;
+        }) as { row: Record<string, unknown> };
+        return response.row;
     }
 
-    async deleteEntity<M extends Record<string, unknown>>(props: DeleteEntityProps<M>): Promise<void> {
+    async delete<M extends Record<string, unknown>>(props: DeleteProps<M>): Promise<void> {
         await this.sendMessage({
-            type: "DELETE_ENTITY",
+            type: "DELETE",
             payload: props
         });
     }
@@ -864,23 +991,23 @@ options }
         return response.database;
     }
 
-    async checkUniqueField(path: string, name: string, value: unknown, entityId?: string, collection?: EntityCollection): Promise<boolean> {
+    async checkUniqueField(path: string, name: string, value: unknown, id?: string, collection?: CollectionConfig): Promise<boolean> {
         const response = await this.sendMessage({
             type: "CHECK_UNIQUE_FIELD",
             payload: {
                 path,
                 name,
                 value,
-                entityId,
+                id,
                 collection
             }
         }) as { isUnique: boolean };
         return response.isUnique;
     }
 
-    async countEntities<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number> {
+    async count<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number> {
         const response = await this.sendMessage({
-            type: "COUNT_ENTITIES",
+            type: "COUNT",
             payload: props
         }) as { count: number };
         return response.count;
@@ -1017,52 +1144,75 @@ options }
     }
 
     /**
-     * Merge incoming entities with cached data, preserving cached references
-     * for entities whose values haven't changed. This avoids unnecessary
-     * React re-renders when the server refetches all entities but most
+     * The address of a row, for matching it against another copy of itself.
+     *
+     * A row is exactly its columns and carries no address, so it is derived
+     * from the key columns the server named — including the ordinary case where
+     * that key is `id`, which the server reports like any other.
+     *
+     * Undefined when there are no keys, which means the server could not
+     * resolve any: such rows genuinely cannot be recognised, and guessing at a
+     * column called `id` would be inventing an identity for a table that has
+     * none.
+     */
+    private rowAddress(row: Record<string, unknown>, pks: PrimaryKeyInfo[] | undefined): string | undefined {
+        if (!pks || pks.length === 0) return undefined;
+        const address = buildCompositeId(row, pks);
+        if (!address || address.split(COMPOSITE_ID_SEPARATOR).every(part => part === "")) return undefined;
+        return address;
+    }
+
+    /**
+     * Merge incoming rows with cached data, preserving cached references
+     * for rows whose values haven't changed. This avoids unnecessary
+     * React re-renders when the server refetches all rows but most
      * haven't actually changed.
      */
-    private mergeEntities(cached: Entity[] | undefined, incoming: Entity[]): Entity[] {
+    private mergeRows(
+        cached: Record<string, unknown>[] | undefined,
+        incoming: Record<string, unknown>[],
+        pks?: PrimaryKeyInfo[]
+    ): Record<string, unknown>[] {
         if (!cached || cached.length === 0) return incoming;
 
-        // Build a lookup from cached entities by ID for O(1) access
-        const cachedById = new Map<string | number, Entity>();
-        for (const entity of cached) {
-            cachedById.set(entity.id, entity);
+        // Build a lookup from cached rows by address for O(1) access
+        const cachedById = new Map<string, Record<string, unknown>>();
+        for (const row of cached) {
+            const address = this.rowAddress(row, pks);
+            if (address !== undefined) cachedById.set(address, row);
         }
 
-        return incoming.map(incomingEntity => {
-            const cachedEntity = cachedById.get(incomingEntity.id);
-            if (!cachedEntity) return incomingEntity;
+        return incoming.map(incomingRow => {
+            const address = this.rowAddress(incomingRow, pks);
+            const cachedRow = address === undefined ? undefined : cachedById.get(address);
+            if (!cachedRow) return incomingRow;
 
-            if (cachedEntity.path === incomingEntity.path) {
-                const normCached = this.normalizeForComparison(cachedEntity.values) as Record<string, unknown>;
-                const normIncoming = this.normalizeForComparison(incomingEntity.values) as Record<string, unknown>;
+            // Compare flat rows directly (no more path/values nesting)
+            const normCached = this.normalizeForComparison(cachedRow) as Record<string, unknown>;
+            const normIncoming = this.normalizeForComparison(incomingRow) as Record<string, unknown>;
 
-                if (this.deepEqual(normCached, normIncoming)) {
-                    return cachedEntity;
-                } else {
-                    // Deep debug: Why did it fail? Let's check which exact property differs
-                    // so the user can see it in their browser console if flashing still occurs.
-                    const mismatches: Record<string, { cached: unknown, incoming: unknown }> = {};
-                    const allKeys = new Set([...Object.keys(normCached), ...Object.keys(normIncoming)]);
-                    for (const key of allKeys) {
-                        if (!this.deepEqual(normCached[key], normIncoming[key])) {
-                            mismatches[key] = { cached: normCached[key],
+            if (this.deepEqual(normCached, normIncoming)) {
+                return cachedRow;
+            } else {
+                // Deep debug: Why did it fail?
+                const mismatches: Record<string, { cached: unknown, incoming: unknown }> = {};
+                const allKeys = new Set([...Object.keys(normCached), ...Object.keys(normIncoming)]);
+                for (const key of allKeys) {
+                    if (!this.deepEqual(normCached[key], normIncoming[key])) {
+                        mismatches[key] = { cached: normCached[key],
 incoming: normIncoming[key] };
-                        }
                     }
-                    console.debug(`[RebaseWS] Row ${incomingEntity.id} refetch mismatch:\n`, JSON.stringify(mismatches, null, 2));
                 }
+                console.debug(`[RebaseWS] Row ${address} refetch mismatch:\n`, JSON.stringify(mismatches, null, 2));
             }
-            return incomingEntity;
+            return incomingRow;
         });
     }
 
     // Subscription methods
     listenCollection<M extends Record<string, unknown>>(
         props: FetchCollectionProps<M>,
-        onUpdate: (entities: Entity[]) => void,
+        onUpdate: (rows: Record<string, unknown>[]) => void,
         onError?: (error: Error) => void
     ): () => void {
         const subscriptionKey = this.createCollectionSubscriptionKey(props);
@@ -1074,7 +1224,7 @@ incoming: normIncoming[key] };
         if (existingSubscription) {
             // Reuse existing subscription - just add the new callback
             const callbackMap = existingSubscription.callbacks as Map<string, {
-                onUpdate: (entities: Entity[]) => void;
+                onUpdate: (rows: Record<string, unknown>[]) => void;
                 onError?: (error: Error) => void;
             }>;
             callbackMap.set(callbackId, { onUpdate,
@@ -1090,13 +1240,21 @@ onError });
                         onError(error instanceof Error ? error : new Error(String(error)));
                     }
                 }
+            } else if (!existingSubscription.subscribeInFlight) {
+                // Registered but idle: its subscribe never landed (the send failed,
+                // or the server answered with an error). Nothing is coming, so
+                // re-issue it — otherwise this listener waits forever.
+                this.sendCollectionSubscribe(subscriptionKey);
             }
 
             // Return unsubscribe function
             return () => {
                 callbackMap.delete(callbackId);
                 if (callbackMap.size === 0) {
-                    // No more callbacks, unsubscribe from backend
+                    // Only tear down if this is still the same registration — a
+                    // failed subscribe may have replaced it in the meantime.
+                    if (this.collectionSubscriptions.get(subscriptionKey) !== existingSubscription) return;
+                    if (existingSubscription.subscribeTimeout) clearTimeout(existingSubscription.subscribeTimeout);
                     this.collectionSubscriptions.delete(subscriptionKey);
                     this.backendToCollectionKey.delete(existingSubscription.backendSubscriptionId);
                     if (this.isConnected && this.ws) {
@@ -1112,7 +1270,7 @@ onError });
         // Create new subscription
         const backendSubscriptionId = `collection_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
         const callbackMap = new Map<string, {
-            onUpdate: (entities: Entity[]) => void;
+            onUpdate: (rows: Record<string, unknown>[]) => void;
             onError?: (error: Error) => void;
         }>();
         callbackMap.set(callbackId, { onUpdate,
@@ -1127,16 +1285,9 @@ onError });
         // Add reverse lookup
         this.backendToCollectionKey.set(backendSubscriptionId, subscriptionKey);
 
-        // Send subscription request to backend
-        this.sendMessage({
-            type: "subscribe_collection",
-            payload: {
-                ...props,
-                subscriptionId: backendSubscriptionId
-            }
-        }).catch(error => {
-            if (onError) onError(error);
-        });
+        // Send subscription request to backend. A failure here drops the
+        // registration and notifies every listener, so the next mount retries.
+        this.sendCollectionSubscribe(subscriptionKey);
 
         // Return unsubscribe function
         return () => {
@@ -1145,6 +1296,7 @@ onError });
                 const callbacks = subscription.callbacks;
                 callbacks.delete(callbackId);
                 if (callbacks.size === 0) {
+                    if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
                     this.collectionSubscriptions.delete(subscriptionKey);
                     this.backendToCollectionKey.delete(subscription.backendSubscriptionId);
                     if (this.isConnected && this.ws) {
@@ -1158,21 +1310,21 @@ onError });
         };
     }
 
-    listenEntity<M extends Record<string, unknown>>(
-        props: FetchEntityProps<M>,
-        onUpdate: (entity: Entity | null) => void,
+    listenOne<M extends Record<string, unknown>>(
+        props: FetchOneProps<M>,
+        onUpdate: (row: Record<string, unknown> | null) => void,
         onError?: (error: Error) => void
     ): () => void {
-        const subscriptionKey = this.createEntitySubscriptionKey(props);
+        const subscriptionKey = this.createSingleSubscriptionKey(props);
         const callbackId = `callback_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 
         // Check if we already have a subscription for these exact parameters
-        const existingSubscription = this.entitySubscriptions.get(subscriptionKey);
+        const existingSubscription = this.singleSubscriptions.get(subscriptionKey);
 
         if (existingSubscription) {
             // Reuse existing subscription - just add the new callback
             const callbackMap = existingSubscription.callbacks as Map<string, {
-                onUpdate: (entity: Entity | null) => void;
+                onUpdate: (row: Record<string, unknown> | null) => void;
                 onError?: (error: Error) => void;
             }>;
             callbackMap.set(callbackId, { onUpdate,
@@ -1183,19 +1335,25 @@ onError });
                 try {
                     onUpdate(existingSubscription.latestData);
                 } catch (error) {
-                    console.error("Error in entity subscription callback:", error);
+                    console.error("Error in row subscription callback:", error);
                     if (onError) {
                         onError(error instanceof Error ? error : new Error(String(error)));
                     }
                 }
+            } else if (!existingSubscription.subscribeInFlight) {
+                // See listenCollection: a registration with nothing in flight is
+                // dead, and attaching to it silently would hang this listener.
+                this.sendEntitySubscribe(subscriptionKey);
             }
 
             // Return unsubscribe function
             return () => {
                 callbackMap.delete(callbackId);
                 if (callbackMap.size === 0) {
+                    if (this.singleSubscriptions.get(subscriptionKey) !== existingSubscription) return;
+                    if (existingSubscription.subscribeTimeout) clearTimeout(existingSubscription.subscribeTimeout);
                     // No more callbacks, unsubscribe from backend
-                    this.entitySubscriptions.delete(subscriptionKey);
+                    this.singleSubscriptions.delete(subscriptionKey);
                     this.backendToEntityKey.delete(existingSubscription.backendSubscriptionId);
                     if (this.isConnected && this.ws) {
                         this.sendMessage({
@@ -1210,13 +1368,13 @@ onError });
         // Create new subscription
         const backendSubscriptionId = `entity_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
         const callbackMap = new Map<string, {
-            onUpdate: (entity: Entity | null) => void;
+            onUpdate: (row: Record<string, unknown> | null) => void;
             onError?: (error: Error) => void;
         }>();
         callbackMap.set(callbackId, { onUpdate,
 onError });
 
-        this.entitySubscriptions.set(subscriptionKey, {
+        this.singleSubscriptions.set(subscriptionKey, {
             backendSubscriptionId,
             callbacks: callbackMap,
             props
@@ -1226,24 +1384,16 @@ onError });
         this.backendToEntityKey.set(backendSubscriptionId, subscriptionKey);
 
         // Send subscription request to backend
-        this.sendMessage({
-            type: "subscribe_entity",
-            payload: {
-                ...props,
-                subscriptionId: backendSubscriptionId
-            }
-        }).catch(error => {
-            if (onError) onError(error);
-        });
+        this.sendEntitySubscribe(subscriptionKey);
 
         // Return unsubscribe function
         return () => {
-            const subscription = this.entitySubscriptions.get(subscriptionKey);
+            const subscription = this.singleSubscriptions.get(subscriptionKey);
             if (subscription) {
                 const callbacks = subscription.callbacks;
                 callbacks.delete(callbackId);
                 if (callbacks.size === 0) {
-                    this.entitySubscriptions.delete(subscriptionKey);
+                    this.singleSubscriptions.delete(subscriptionKey);
                     this.backendToEntityKey.delete(subscription.backendSubscriptionId);
                     if (this.isConnected && this.ws) {
                         this.sendMessage({
@@ -1256,13 +1406,208 @@ onError });
         };
     }
 
+    /**
+     * Send a `subscribe_collection` for an already-registered subscription and
+     * arm its watchdog.
+     *
+     * Every path that registers a collection subscription goes through here, so
+     * that a subscribe which never lands — a rejected send, or a server that
+     * never answers — always ends up in `failCollectionSubscription` rather than
+     * leaving the entry parked with `isInitialDataReceived === false` forever.
+     */
+    private sendCollectionSubscribe(subscriptionKey: string): void {
+        const subscription = this.collectionSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+
+        const backendSubscriptionId = subscription.backendSubscriptionId;
+        subscription.subscribeInFlight = true;
+
+        if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+        subscription.subscribeTimeout = undefined;
+        // Only time out a frame that is actually on the wire. While offline the
+        // message just sits in the queue, and reconnect backoff can exceed the
+        // timeout — `armPendingSubscribeWatchdogs` picks these up on connect.
+        if (this.isConnected) this.sendCollectionSubscribeWatchdog(subscriptionKey);
+
+        this.sendMessage({
+            type: "subscribe_collection",
+            payload: {
+                ...subscription.props,
+                subscriptionId: backendSubscriptionId
+            }
+        }).catch(error => {
+            const current = this.collectionSubscriptions.get(subscriptionKey);
+            if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+            this.failCollectionSubscription(
+                subscriptionKey,
+                error instanceof Error ? error : new Error(String(error))
+            );
+        });
+    }
+
+    /** The `listenOne` counterpart of {@link sendCollectionSubscribe}. */
+    private sendEntitySubscribe(subscriptionKey: string): void {
+        const subscription = this.singleSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+
+        const backendSubscriptionId = subscription.backendSubscriptionId;
+        subscription.subscribeInFlight = true;
+
+        if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+        subscription.subscribeTimeout = undefined;
+        if (this.isConnected) this.sendEntitySubscribeWatchdog(subscriptionKey);
+
+        this.sendMessage({
+            type: "subscribe_one",
+            payload: {
+                ...subscription.props,
+                subscriptionId: backendSubscriptionId
+            }
+        }).catch(error => {
+            const current = this.singleSubscriptions.get(subscriptionKey);
+            if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+            this.failEntitySubscription(
+                subscriptionKey,
+                error instanceof Error ? error : new Error(String(error))
+            );
+        });
+    }
+
+    /**
+     * Report a subscribe failure to every listener and drop the registration.
+     *
+     * Dropping it is the point: the callbacks stay live (their components are
+     * still mounted and have been told), but the next `listenCollection` for
+     * these params finds no entry and issues a fresh subscribe instead of
+     * silently attaching to a dead one.
+     */
+    private failCollectionSubscription(subscriptionKey: string, error: Error): void {
+        const subscription = this.collectionSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+
+        if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+        subscription.subscribeInFlight = false;
+
+        this.collectionSubscriptions.delete(subscriptionKey);
+        this.backendToCollectionKey.delete(subscription.backendSubscriptionId);
+
+        subscription.callbacks.forEach(callback => {
+            if (callback.onError) {
+                try {
+                    callback.onError(error);
+                } catch (callbackError) {
+                    console.error("Error in collection subscription error callback:", callbackError);
+                }
+            }
+        });
+    }
+
+    /** The `listenOne` counterpart of {@link failCollectionSubscription}. */
+    private failEntitySubscription(subscriptionKey: string, error: Error): void {
+        const subscription = this.singleSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+
+        if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+        subscription.subscribeInFlight = false;
+
+        this.singleSubscriptions.delete(subscriptionKey);
+        this.backendToEntityKey.delete(subscription.backendSubscriptionId);
+
+        subscription.callbacks.forEach(callback => {
+            if (callback.onError) {
+                try {
+                    callback.onError(error);
+                } catch (callbackError) {
+                    console.error("Error in row subscription error callback:", callbackError);
+                }
+            }
+        });
+    }
+
+    /**
+     * Stop the watchdogs without failing anything — used when the socket drops,
+     * since the reconnect path re-subscribes everything anyway and a watchdog
+     * firing mid-reconnect would tear down healthy subscriptions.
+     */
+    private suspendSubscribeWatchdogs(): void {
+        for (const sub of this.collectionSubscriptions.values()) {
+            if (sub.subscribeTimeout) clearTimeout(sub.subscribeTimeout);
+            sub.subscribeTimeout = undefined;
+            sub.subscribeInFlight = false;
+        }
+        for (const sub of this.singleSubscriptions.values()) {
+            if (sub.subscribeTimeout) clearTimeout(sub.subscribeTimeout);
+            sub.subscribeTimeout = undefined;
+            sub.subscribeInFlight = false;
+        }
+    }
+
+    /**
+     * Arm watchdogs for subscribes that were requested while offline and have
+     * just been flushed to the socket. Their timers were deliberately not set at
+     * request time, so without this they would have no timeout at all.
+     */
+    private armPendingSubscribeWatchdogs(): void {
+        for (const [key, sub] of this.collectionSubscriptions.entries()) {
+            if (sub.subscribeInFlight && !sub.subscribeTimeout) this.sendCollectionSubscribeWatchdog(key);
+        }
+        for (const [key, sub] of this.singleSubscriptions.entries()) {
+            if (sub.subscribeInFlight && !sub.subscribeTimeout) this.sendEntitySubscribeWatchdog(key);
+        }
+    }
+
+    private sendCollectionSubscribeWatchdog(subscriptionKey: string): void {
+        const subscription = this.collectionSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+        const backendSubscriptionId = subscription.backendSubscriptionId;
+        subscription.subscribeTimeout = setTimeout(() => {
+            const current = this.collectionSubscriptions.get(subscriptionKey);
+            if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+            if (!current.subscribeInFlight) return;
+            this.failCollectionSubscription(
+                subscriptionKey,
+                new RebaseApiError("Subscription timed out", { code: "SUBSCRIPTION_TIMEOUT" })
+            );
+        }, this.subscriptionTimeoutMs);
+    }
+
+    private sendEntitySubscribeWatchdog(subscriptionKey: string): void {
+        const subscription = this.singleSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+        const backendSubscriptionId = subscription.backendSubscriptionId;
+        subscription.subscribeTimeout = setTimeout(() => {
+            const current = this.singleSubscriptions.get(subscriptionKey);
+            if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+            if (!current.subscribeInFlight) return;
+            this.failEntitySubscription(
+                subscriptionKey,
+                new RebaseApiError("Subscription timed out", { code: "SUBSCRIPTION_TIMEOUT" })
+            );
+        }, this.subscriptionTimeoutMs);
+    }
+
+    /**
+     * 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(error: Error): void {
+        for (const key of [...this.collectionSubscriptions.keys()]) {
+            const sub = this.collectionSubscriptions.get(key);
+            if (sub && !sub.isInitialDataReceived) this.failCollectionSubscription(key, error);
+        }
+        for (const key of [...this.singleSubscriptions.keys()]) {
+            const sub = this.singleSubscriptions.get(key);
+            if (sub && !sub.isInitialDataReceived) this.failEntitySubscription(key, error);
+        }
+    }
+
     /**
      * Re-send all active subscriptions to the backend after a reconnect.
      * The server wipes subscription state when a client disconnects, so
      * we need to re-register everything to resume receiving updates.
      */
     private resubscribeAll(): void {
-        console.debug(`[WS] Re-subscribing: ${this.collectionSubscriptions.size} collection(s), ${this.entitySubscriptions.size} entity(ies)`);
+        console.debug(`[WS] Re-subscribing: ${this.collectionSubscriptions.size} collection(s), ${this.singleSubscriptions.size} row(ies)`);
 
         // Re-subscribe collection subscriptions
         for (const [key, sub] of this.collectionSubscriptions.entries()) {
@@ -1275,19 +1620,11 @@ onError });
             this.backendToCollectionKey.delete(oldBackendId);
             this.backendToCollectionKey.set(newBackendId, key);
 
-            this.sendMessage({
-                type: "subscribe_collection",
-                payload: {
-                    ...sub.props,
-                    subscriptionId: newBackendId
-                }
-            }).catch(error => {
-                console.error("[WS] Failed to re-subscribe collection:", key, error);
-            });
+            this.sendCollectionSubscribe(key);
         }
 
-        // Re-subscribe entity subscriptions
-        for (const [key, sub] of this.entitySubscriptions.entries()) {
+        // Re-subscribe row subscriptions
+        for (const [key, sub] of this.singleSubscriptions.entries()) {
             const oldBackendId = sub.backendSubscriptionId;
             const newBackendId = `entity_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
             sub.backendSubscriptionId = newBackendId;
@@ -1295,15 +1632,7 @@ onError });
             this.backendToEntityKey.delete(oldBackendId);
             this.backendToEntityKey.set(newBackendId, key);
 
-            this.sendMessage({
-                type: "subscribe_entity",
-                payload: {
-                    ...sub.props,
-                    subscriptionId: newBackendId
-                }
-            }).catch(error => {
-                console.error("[WS] Failed to re-subscribe entity:", key, error);
-            });
+            this.sendEntitySubscribe(key);
         }
     }
 
@@ -1331,7 +1660,7 @@ onError });
         });
     }
 
-    private createEntitySubscriptionKey(props: FetchEntityProps): string {
-        return `${props.path}|${props.entityId}`;
+    private createSingleSubscriptionKey(props: FetchOneProps): string {
+        return `${props.path}|${props.id}`;
     }
 }