@rebasepro/client 0.13.1-canary.gf57a27e → 0.14.0

package/src/offline.ts

@@ -1,10 +1,16 @@
 import { buildQueryString, FindParams, RebaseApiError } from "./transport";
-import { FindAllParams, FindResult, IterateParams, LogicalCondition, SDKCollectionClient, WhereFilterOp, WhereValue, WriteOptions } from "@rebasepro/types";
+import { FindAllParams, FindResult, IterateParams, LogicalCondition, SDKCollectionClient, WhereFilterOp, WhereValueFor, WriteOptions } from "@rebasepro/types";
 import { collectAllPages, paginateFind } from "@rebasepro/common";
 import { CollectionClient, LiveResult, ObserveOptions, RowSnapshotMeta } from "./collection";
 import { SDKQueryBuilder } from "./sdk_query_builder";
 import { dehydrateRow, hydrateRow } from "./offline-codec";
-import { ConnectivityMonitor, isDuplicateKeyError, isNetworkError, isRetryableError } from "./offline-connectivity";
+import {
+    ConnectivityMonitor,
+    isDuplicateKeyError,
+    isIdempotencyInProgressError,
+    isNetworkError,
+    isRetryableError
+} from "./offline-connectivity";
 import {
     IndexedDBOfflineStore,
     MemoryOfflineStore,
@@ -14,6 +20,7 @@ import {
 } from "./offline-store";
 import {
     isExactlyEvaluable,
+    isLocallySortable,
     matchesParams,
     resolvePagination,
     runLocalQuery,
@@ -218,6 +225,18 @@ interface Observer {
 // all 1,700 lines of it in silence.
 const MISSING = "\u0000missing";
 
+/**
+ * Replays to spend on a mutation whose idempotency key the server is still
+ * holding, when the app has not asked for more.
+ *
+ * Retries double from a second and cap at the sync interval, so the default
+ * budget of five covers about half a minute — less than the lease a server
+ * gives a claim nobody came back for. This many outlast it with room for a slow
+ * batch, and the count is what stops a server that never releases the key from
+ * blocking the queue behind it indefinitely.
+ */
+const IN_PROGRESS_MIN_RETRIES = 12;
+
 export class OfflineManager {
     private readonly store: OfflineStore;
     private readonly maxCachedQueries: number;
@@ -729,7 +748,7 @@ data: u.data as AnyRow })),
                 return builder.where(
                     columnOrCondition as keyof M & string,
                     operator!,
-                    value as WhereValue<M[keyof M & string]>
+                    value as WhereValueFor<WhereFilterOp, M[keyof M & string]>
                 );
             },
             orderBy: (column, direction) => new SDKQueryBuilder<M>(wrapped).orderBy(column, direction),
@@ -1085,7 +1104,17 @@ data: u.data as AnyRow })),
         // `sort` being silently ignored on every list backed by this overlay:
         // the query carries it, the server honours it, and the answer served
         // from here did not.
-        if (params?.orderBy) sortRows(rows, params.orderBy);
+        //
+        // …but only when the local sort would land where the server's did.
+        // `snapshot.ids` already arrived in the server's order, so re-sorting a
+        // text column with `Intl.Collator` *replaces* a correct order with a
+        // possibly different one — under the C collation Postgres puts
+        // `Banana` before `apple` and the collator does not. When the column
+        // cannot be ordered locally the snapshot's order is the better answer,
+        // and the result says so rather than presenting it as the sorted page
+        // that was asked for.
+        const orderIsLocal = isLocallySortable(rows, params?.orderBy);
+        if (params?.orderBy && orderIsLocal) sortRows(rows, params.orderBy);
 
         const total = Math.max(rows.length, snapshot.total - removed + added);
         return {
@@ -1098,7 +1127,9 @@ data: u.data as AnyRow })),
             },
             fromCache,
             hasPendingWrites: rows.some((row) => this.hasPending(slug, row.id as string | number)),
-            partial: !exact
+            // Not the page that was asked for if either the membership
+            // decision or the order could not be reproduced here.
+            partial: !exact || !orderIsLocal
         };
     }
 
@@ -1479,7 +1510,18 @@ data: u.data as AnyRow })),
                         }
                         op.attempts = (op.attempts ?? 0) + 1;
                         op.lastError = (error as Error)?.message ?? String(error);
-                        if (isRetryableError(error) && op.attempts < this.maxRetries) {
+                        // A key the server is still holding gets a longer
+                        // budget than a busy server does. The claim outlives
+                        // the request that took it — the process was killed
+                        // between the write and its answer — so it is refused
+                        // until the claim's lease runs out, which is longer
+                        // than the default five retries reach. Giving up on
+                        // that schedule rolls back precisely the write the key
+                        // exists to save.
+                        const limit = isIdempotencyInProgressError(error)
+                            ? Math.max(this.maxRetries, IN_PROGRESS_MIN_RETRIES)
+                            : this.maxRetries;
+                        if (isRetryableError(error) && op.attempts < limit) {
                             // The server is busy, not unhappy. Keep the op — and
                             // its place in line, since later writes may depend on
                             // it — and come back after a backoff.

package/src/query-contract.types.ts

@@ -23,7 +23,7 @@
  * generated SDK — where `M` is a concrete row type — the documented call was a
  * compile error. Nothing in this repo noticed; a downstream application did.
  */
-import type { FindParams, FindResult, SDKQueryBuilderInterface } from "@rebasepro/types";
+import type { FindParams, FindResult, SDKQueryBuilderInterface, WhereFilterOp } from "@rebasepro/types";
 
 /**
  * A row shaped the way a **generated** SDK shapes one: a type alias with a
@@ -43,8 +43,16 @@ type ContractRow = {
     id: string;
     title: string;
     created_at: string;
+    /** An `array` property, which codegen emits as `Array<X>`. */
+    tags: string[];
+    age: number;
+    deleted_at: string | null;
 };
 
+/** A to-many relation, which codegen emits as `Array<TargetRow>`. */
+type TagRow = { id: string; label: string };
+type PostRow = { id: string; title: string; tags: TagRow[] };
+
 // ── orderBy accepts relevance, and still rejects nonsense ───────────────────
 
 /** The documented relevance sort must compile. */
@@ -80,6 +88,90 @@ export const fluentTypo = (qb: SDKQueryBuilderInterface<ContractRow>) =>
 export const fluentVector = (qb: SDKQueryBuilderInterface<ContractRow>) =>
     qb.vectorSearch("embedding", [0.1, 0.2], { threshold: 0.3 }).limit(10);
 
+// ── the operator decides what the value is ─────────────────────────────────
+
+/**
+ * `array-contains` takes an **element** of the column, not the column.
+ *
+ * This was the second `_score`: documented in `docs/sdk/querying.md`, accepted
+ * by the runtime, and a compile error on a generated SDK — because
+ * `WhereValue<T> = T | T[] | null` was one value type for all sixteen
+ * operators, so on `tags: string[]` it wanted a `string[]`. The spelling that
+ * did compile, `["featured"]`, builds `@> ARRAY[$1]` with the whole array bound
+ * as the single element and matches nothing, forever, with no error anywhere.
+ */
+export const fluentArrayContains = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.where("tags", "array-contains", "featured");
+
+export const fluentArrayContainsWrapped = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    // @ts-expect-error - the column is not one of its own elements
+    qb.where("tags", "array-contains", ["featured"]);
+
+/**
+ * Same defect, and the case the relation compiler was specifically built for:
+ * a to-many relation is emitted as `Array<TargetRow>`, and the compiler answers
+ * `array-contains` on it by comparing **ids**. So the id must be accepted even
+ * though it is not the element type.
+ */
+export const fluentRelationContains = (qb: SDKQueryBuilderInterface<PostRow>, tagId: string) =>
+    qb.where("tags", "array-contains", tagId);
+
+export const fluentRelationIn = (qb: SDKQueryBuilderInterface<PostRow>, tagIds: string[]) =>
+    qb.where("tags", "in", tagIds);
+
+export const fluentRelationTypo = (qb: SDKQueryBuilderInterface<PostRow>) =>
+    // @ts-expect-error - neither a `TagRow` nor a `TagRow["id"]`
+    qb.where("tags", "array-contains", 42);
+
+/** The list operators take a list of elements — or one, read as a one-element list. */
+export const fluentInList = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.where("tags", "in", ["featured", "new"]);
+
+export const fluentInScalar = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.where("title", "in", "hello");
+
+export const fluentInNested = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    // @ts-expect-error - a list of lists is not a list of elements
+    qb.where("tags", "in", [["featured"]]);
+
+/** A comparison takes one value. `eq(column, ["a","b"])` is not a query anyone meant. */
+export const fluentEqArray = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    // @ts-expect-error - `==` compares against a value, not a list
+    qb.where("title", "==", ["a", "b"]);
+
+/**
+ * A pattern is a string on every column type. The driver casts, so refusing
+ * `"%3%"` on a numeric column was the type being stricter than the runtime.
+ */
+export const fluentLikeOnNumber = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.where("age", "like", "%3%");
+
+/** The null operators ignore their value; `null` is the conventional spelling. */
+export const fluentIsNull = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.where("deleted_at", "is-null", null);
+
+/**
+ * A caller holding an unnarrowed operator — a dynamic filter UI — must keep
+ * compiling. `WhereValueFor` distributes over the operator, so this is the
+ * union of every branch rather than a `never`.
+ */
+export const fluentDynamicOp = (qb: SDKQueryBuilderInterface<ContractRow>, op: WhereFilterOp) =>
+    qb.where("title", op, "anything");
+
+/** Two conditions on one column: the shape the Mongo compiler used to drop. */
+export const fluentRange = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.where("age", ">=", 18).where("age", "<", 65);
+
+/** The object form must accept exactly what the fluent form accepts. */
+export const paramsArrayContains: FindParams<ContractRow> = {
+    where: { tags: ["array-contains", "featured"] }
+};
+
+/** …and the array-of-tuples form the builder produces from two `.where()` calls. */
+export const paramsRange: FindParams<ContractRow> = {
+    where: { age: [[">=", 18], ["<", 65]] }
+};
+
 // ── what a query computes is readable off the row ──────────────────────────
 
 /**

package/src/realtime-error-surfacing.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect, beforeEach, afterEach, jest } from "@jest/globals";
+
+/**
+ * Server errors about channel frames used to be discarded by the client.
+ *
+ * Channel messages are fire-and-forget by design: the SDK deliberately
+ * registers no `pendingRequests` waiter for them, because their answers come
+ * back addressed by channel rather than in a response envelope. The consequence
+ * was that an `ERROR` frame — `RATE_LIMITED`, `CHANNEL_FORBIDDEN`,
+ * `CHANNEL_HISTORY_WRITE_FAILED` — matched no waiter, no channel and no
+ * subscription, fell through every branch of `handleWebSocketMessage`, and was
+ * dropped. `await channel.broadcast(...)` resolved as if it had been sent.
+ */
+function fakeSocket() {
+    const sockets: FakeWS[] = [];
+
+    class FakeWS {
+        static readonly OPEN = 1;
+        readyState = 1;
+        onopen: (() => void) | null = null;
+        onclose: (() => void) | null = null;
+        onerror: (() => void) | null = null;
+        onmessage: ((event: { data: string }) => void) | null = null;
+
+        constructor(public url: string) {
+            sockets.push(this);
+            setTimeout(() => this.onopen?.(), 0);
+        }
+
+        send() { /* nothing here needs the outgoing frames */ }
+        close() { /* noop */ }
+    }
+
+    const instance = () => sockets[sockets.length - 1];
+
+    return {
+        FakeWS: FakeWS as unknown as typeof WebSocket,
+        deliver: (frame: unknown) => instance()?.onmessage?.({ data: JSON.stringify(frame) })
+    };
+}
+
+describe("unmatched realtime error frames", () => {
+    let warn: any;
+
+    beforeEach(() => {
+        jest.useFakeTimers();
+        warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        warn.mockRestore();
+        jest.useRealTimers();
+    });
+
+    const connect = async () => {
+        const { RebaseWebSocketClient } = await import("./websocket");
+        const { FakeWS, deliver } = fakeSocket();
+        const client = new RebaseWebSocketClient({
+            websocketUrl: "ws://localhost:3000",
+            WebSocket: FakeWS
+        });
+        client.ensureConnected();
+        await jest.advanceTimersByTimeAsync(1);
+        return { client, deliver };
+    };
+
+    it("surfaces a channel rate-limit refusal that matches no waiter", async () => {
+        const { deliver } = await connect();
+
+        deliver({
+            type: "ERROR",
+            requestId: "req-the-client-never-registered",
+            payload: { error: { message: "Too many channel messages. Please slow down.", code: "RATE_LIMITED" } }
+        });
+
+        expect(warn).toHaveBeenCalledTimes(1);
+        expect(String(warn.mock.calls[0][0])).toContain("RATE_LIMITED");
+        expect(String(warn.mock.calls[0][0])).toContain("Too many channel messages");
+    });
+
+    it("surfaces a refused channel action", async () => {
+        const { deliver } = await connect();
+
+        // What the server now sends for a broadcast into a channel the sender
+        // never joined — `sendError` addresses it by neither requestId nor
+        // channel, so nothing else in the client will ever see it.
+        deliver({
+            type: "error",
+            payload: { error: { message: "Refused broadcast on channel \"doc:42\"", code: "CHANNEL_FORBIDDEN" } },
+            error: "Refused broadcast on channel \"doc:42\""
+        });
+
+        expect(warn).toHaveBeenCalledTimes(1);
+        expect(String(warn.mock.calls[0][0])).toContain("CHANNEL_FORBIDDEN");
+    });
+
+    it("stays quiet for frames that are not errors", async () => {
+        const { deliver } = await connect();
+
+        deliver({ type: "broadcast", channel: "doc:42", event: "op", payload: { n: 1 } });
+        deliver({ type: "presence_state", channel: "doc:42", presences: {} });
+
+        expect(warn).not.toHaveBeenCalled();
+    });
+});

package/src/sdk_query_builder.ts

@@ -5,7 +5,7 @@ import {
     SDKCollectionClient,
     SDKQueryBuilderInterface,
     WhereFilterOp,
-    WhereValue,
+    WhereValueFor,
     type ComputedSortField
 } from "@rebasepro/types";
 
@@ -37,7 +37,7 @@ export class SDKQueryBuilder<M extends Record<string, unknown> = Record<string,
      * @example
      * client.data.users.where('age', '>=', 18).find()
      */
-    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
+    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): this;
     where(logicalCondition: LogicalCondition): this;
     where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown): this {
         if (typeof columnOrCondition === "object" && columnOrCondition !== null && "type" in columnOrCondition) {

package/src/transport.ts

@@ -325,6 +325,27 @@ export function createTransport(config: RebaseClientConfig, environment?: Transp
         };
     }
 
+    /**
+     * The refusal for a success status carrying a body this client cannot read.
+     *
+     * The first 120 characters go in the message because they identify the
+     * sender at a glance: `<!doctype html>` says "you are talking to a web
+     * server, not to this API" faster than any wording here could.
+     *
+     * One function for both the first attempt and the post-refresh retry — the
+     * retry is a second copy of this whole response-reading path, and copies
+     * are how one of them ends up fixed and the other not.
+     */
+    function unreadableResponse(status: number, text: string): RebaseApiError {
+        return new RebaseApiError(
+            `The server answered ${status} with a body that is not JSON, so there is nothing to return. ` +
+            "This usually means the request reached something other than the Rebase API — a single-page-app " +
+            "fallback serving index.html, or a proxy error page — so check the API URL configuration " +
+            `(e.g. VITE_API_URL). The body began: ${JSON.stringify(text.slice(0, 120))}`,
+            { status, code: "INVALID_JSON_RESPONSE" }
+        );
+    }
+
     async function request<T = unknown>(path: string, init?: RequestInit): Promise<T> {
         const url = resolveBaseUrl(config.baseUrl) + apiPath + path;
 
@@ -356,11 +377,27 @@ headers });
 
         const text = await res.text().catch(() => "");
         let body: Record<string, unknown> = {};
+        /**
+         * Whether the body was there and could not be read as JSON.
+         *
+         * On an error status this does not matter — the status is the answer
+         * and the message falls back to `statusText`. On a *success* status it
+         * is the whole answer, and `{}` was being returned as though the server
+         * had sent it: `find()` answered `{}` instead of an array, `getOne()`
+         * an empty object, with nothing thrown.
+         *
+         * The case that produces it is not exotic. Point `VITE_API_URL` at the
+         * frontend's own host and `/api/data/posts` lands on the SPA fallback,
+         * which answers `200` with `index.html` — so the misconfiguration the
+         * 404 branch below spends four lines explaining reaches the caller, in
+         * its most common form, as an empty success.
+         */
+        let unreadableBody = false;
         if (text) {
             try {
                 body = JSON.parse(text, rebaseReviver) as Record<string, unknown>;
             } catch (e) {
-                // If not valid JSON, fallback
+                unreadableBody = true;
             }
         }
 
@@ -393,10 +430,13 @@ headers: retryHeaders });
                 if (retryRes.status === 204) return undefined as T; // SAFETY: HTTP 204 No Content has no body
                 const retryText = await retryRes.text().catch(() => "");
                 let retryBody: Record<string, unknown> = {};
+                let retryUnreadable = false;
                 if (retryText) {
                     try {
                         retryBody = JSON.parse(retryText, rebaseReviver);
-                    } catch (e) { /* ignore */ }
+                    } catch (e) {
+                        retryUnreadable = true;
+                    }
                 }
                 if (!retryRes.ok) {
                     let fallbackMessage = retryRes.statusText;
@@ -413,6 +453,7 @@ headers: retryHeaders });
                         }
                     );
                 }
+                if (retryUnreadable) throw unreadableResponse(retryRes.status, retryText);
                 return retryBody as T;
             }
         }
@@ -433,6 +474,8 @@ headers: retryHeaders });
             );
         }
 
+        if (unreadableBody) throw unreadableResponse(res.status, text);
+
         return body as T;
     }
 

package/src/websocket.ts

@@ -76,9 +76,11 @@ const CHANNEL_MESSAGE_TYPES = new Set([
  *
  * @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.
+ * `RebaseWebSocket` contract in `@rebasepro/types`). It stays exported from the
+ * package root for the same reason it always was — a data-source driver may
+ * instantiate it directly — but nothing in this repo does since
+ * `@rebasepro/client-postgres` was removed; its surface may change without a
+ * major bump.
  */
 export class RebaseWebSocketClient {
     private websocketUrl: string;
@@ -895,6 +897,22 @@ export class RebaseWebSocketClient {
             } else {
                 callback.onUpdate(message);
             }
+            return;
+        }
+
+        // An error that matched no waiter used to fall off the end of this
+        // method and disappear. Channel frames are the ones that always do:
+        // they are fire-and-forget by design, so no `pendingRequests` entry
+        // exists to reject and the server's errors about them — RATE_LIMITED,
+        // CHANNEL_FORBIDDEN, CHANNEL_HISTORY_WRITE_FAILED — were dropped while
+        // `await channel.broadcast(...)` resolved as if it had been sent. A
+        // console warning is the floor, not the answer: an `onError` on
+        // `RebaseRealtimeChannel` is the shape this should eventually take.
+        if (type === "ERROR" || type === "error" || message.error) {
+            const { errorMessage, errorCode } = extractMessageError(message);
+            console.warn(
+                `[Rebase] Realtime error from the server${errorCode ? ` (${errorCode})` : ""}: ${errorMessage}`
+            );
         }
     }