@rebasepro/client 0.13.0 → 0.13.1-canary.g06dbe5b

package/src/index.ts

@@ -42,6 +42,9 @@ import { toSnakeCase } from "@rebasepro/utils";
 // data-proxy's unknown-collection error.
 export { RebaseApiError } from "./transport";
 export { RebaseClientError } from "./errors";
+// The codes `RebaseApiError.code` carries. An open union — routes add their own
+// — so it gives completion on the common ones without pretending to be closed.
+export type { RebaseErrorCode } from "@rebasepro/types";
 
 // Query + collection types (annotate SDK results; construct via the fluent API).
 export type { RebaseClientConfig, FindParams, FindResponse } from "./transport";
@@ -238,35 +241,48 @@ export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<Rebase
 /**
  * Derive a WebSocket URL from an HTTP base URL.
  * `http://` → `ws://`, `https://` → `wss://`.
+ *
+ * A backend mounted under a path is the reason `baseUrl` accepts one, so the
+ * path is kept. It used to be kept for an absolute `baseUrl` and dropped for a
+ * relative one — resolved through `.origin` — so one deployment dialled two
+ * different sockets depending on whether its config said `"/backend"` or
+ * `"https://app.example.com/backend"`.
+ *
+ * Returns `""` when there is nothing to resolve against: a relative `baseUrl`
+ * outside a browser has no origin, and inventing one would dial somewhere
+ * arbitrary. The caller warns rather than leaving that silent.
  */
 function deriveWebSocketUrl(baseUrl?: string): string {
+    const toWsProtocol = (url: string): string => {
+        const secure = /^(https|wss):/i.test(url);
+        return url
+            .replace(/^https?:\/\//i, secure ? "wss://" : "ws://")
+            .replace(/^wss?:\/\//i, secure ? "wss://" : "ws://")
+            .replace(/\/$/, "");
+    };
+
     if (typeof window !== "undefined") {
-        let absoluteUrl = "";
+        let absoluteUrl: string;
         if (!baseUrl) {
             absoluteUrl = window.location.origin;
         } else if (/^https?:\/\//i.test(baseUrl) || /^wss?:\/\//i.test(baseUrl)) {
             absoluteUrl = baseUrl;
         } else {
             try {
-                absoluteUrl = new URL(baseUrl, window.location.href).origin;
+                const resolved = new URL(baseUrl, window.location.href);
+                absoluteUrl = resolved.origin + resolved.pathname;
             } catch {
                 absoluteUrl = window.location.origin;
             }
         }
-        const protocol = absoluteUrl.startsWith("https:") || absoluteUrl.startsWith("wss:") ? "wss:" : "ws:";
-        return absoluteUrl
-            .replace(/^https?:\/\//i, `${protocol}//`)
-            .replace(/^wss?:\/\//i, `${protocol}//`)
-            .replace(/\/$/, "");
+        return toWsProtocol(absoluteUrl);
     }
 
     if (!baseUrl) return "";
     if (!/^https?:\/\//i.test(baseUrl) && !/^wss?:\/\//i.test(baseUrl)) {
         return "";
     }
-    return baseUrl
-        .replace(/^https?:\/\//i, (match) => match.toLowerCase() === "https://" ? "wss://" : "ws://")
-        .replace(/\/$/, "");
+    return toWsProtocol(baseUrl);
 }
 
 export function createRebaseClient<DB = Record<string, unknown>>(options: CreateRebaseClientOptions): CreateRebaseClientResult<DB> {
@@ -332,6 +348,24 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         ? (options.websocketUrl ?? deriveWebSocketUrl(options.baseUrl))
         : undefined;
 
+    // Realtime is on unless it was switched off, so "on, but no URL could be
+    // derived" is a misconfiguration and not a choice. It used to be silent:
+    // the client simply had no socket, `observe()` quietly degraded to a
+    // one-shot fetch, and `realtime.channel()` blamed `realtime: false` — an
+    // option the caller had not passed.
+    const realtimeUnreachable = realtimeEnabled && !resolvedWsUrl;
+    const unreachableReason =
+        "no WebSocket URL could be derived from baseUrl " +
+        `${JSON.stringify(options.baseUrl ?? null)} — outside a browser there is no page origin ` +
+        "to resolve a relative URL against. Pass an absolute `baseUrl`, set `websocketUrl` " +
+        "explicitly, or pass `realtime: false` to say this was intended.";
+    if (realtimeUnreachable) {
+        console.warn(
+            `[Rebase] Realtime is enabled but ${unreachableReason} ` +
+            "Live queries will fall back to a single fetch and channels will throw."
+        );
+    }
+
     let ws: RebaseWebSocketClient | undefined;
     /** One channel object per name — see `realtime.channel`. */
     const realtimeChannels = new Map<string, RebaseRealtimeChannel>();
@@ -529,13 +563,15 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
              * 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.
+                // Being merely *unconnected* is not an error: the socket opens
+                // on the first channel operation, which is the whole point of
+                // asking for a channel before you use one. Having no socket at
+                // all is, and there are two reasons for it — say which.
                 if (!ws) {
                     throw new RebaseClientError(
-                        "Realtime is disabled on this client (realtime: false), so channels are unavailable."
+                        realtimeUnreachable
+                            ? `Realtime is enabled but ${unreachableReason}`
+                            : "Realtime is disabled on this client (realtime: false), so channels are unavailable."
                     );
                 }
                 let existing = realtimeChannels.get(name);

package/src/like-pattern-redos.test.ts

@@ -0,0 +1,61 @@
+import { matchesOperator } from "./offline-query";
+
+/**
+ * A `like` pattern is user input, and it becomes a regular expression.
+ *
+ * `%` translates to `[\s\S]*`, so `%%%%X` becomes four adjacent unbounded
+ * quantifiers followed by a literal. On a subject that does not match, the
+ * engine has to try every way of splitting the subject between them — which is
+ * exponential. Twelve `%` against a forty-character value took **100 seconds**
+ * on this machine before answering `false`.
+ *
+ * The pattern arrives over HTTP: `?title=like.%25%25%25…` is a public filter
+ * operator, listed in the operator table. On the offline evaluator that freezes
+ * the tab; the same translation in the Mongo driver hands the expression to the
+ * database, where it occupies a server thread instead.
+ *
+ * Consecutive `%` mean exactly what one `%` means, so collapsing a run is
+ * semantics-preserving and removes the ambiguity the backtracking feeds on.
+ */
+const HOSTILE = "%".repeat(14) + "X";
+const SUBJECT = "a".repeat(48);
+
+describe("like patterns cannot be made to backtrack", () => {
+    it("answers a hostile pattern promptly", () => {
+        const started = Date.now();
+        const result = matchesOperator(SUBJECT, "like", HOSTILE);
+        const elapsed = Date.now() - started;
+
+        expect(result).toBe(false);
+        expect(elapsed).toBeLessThan(1000);
+    });
+
+    it("answers the case-insensitive form promptly too", () => {
+        const started = Date.now();
+        matchesOperator(SUBJECT, "ilike", HOSTILE);
+
+        expect(Date.now() - started).toBeLessThan(1000);
+    });
+
+    it("still means what LIKE means", () => {
+        expect(matchesOperator("post-1", "like", "post-%")).toBe(true);
+        expect(matchesOperator("post-1", "like", "%1")).toBe(true);
+        expect(matchesOperator("post-1", "like", "%st-%")).toBe(true);
+        expect(matchesOperator("post-1", "like", "other-%")).toBe(false);
+        // A run of wildcards is the same query as one wildcard.
+        expect(matchesOperator("post-1", "like", "post%%%%1")).toBe(true);
+        expect(matchesOperator("abc", "like", "a_c")).toBe(true);
+        expect(matchesOperator("abbc", "like", "a_c")).toBe(false);
+        // `_` is fixed-width, so a run of them still counts.
+        expect(matchesOperator("abc", "like", "a__")).toBe(true);
+        expect(matchesOperator("ab", "like", "a__")).toBe(false);
+    });
+
+    it("keeps an escaped percent literal", () => {
+        expect(matchesOperator("50%", "like", "50\\%")).toBe(true);
+        expect(matchesOperator("500", "like", "50\\%")).toBe(false);
+        // An escaped percent next to a wildcard is still a literal.
+        expect(matchesOperator("50%off", "like", "50\\%%")).toBe(true);
+        expect(matchesOperator("50off", "like", "50\\%%")).toBe(false);
+    });
+});

package/src/offline-connectivity.test.ts

@@ -1,4 +1,9 @@
-import { ConnectivityMonitor, isNetworkError, isRetryableError } from "./offline-connectivity";
+import {
+    ConnectivityMonitor,
+    isDuplicateKeyError,
+    isNetworkError,
+    isRetryableError
+} from "./offline-connectivity";
 import { RebaseApiError } from "./transport";
 
 /**
@@ -35,6 +40,35 @@ describe("network error classification", () => {
         // blip, and retrying it forever jams every write queued behind it.
         expect(isRetryableError(new RebaseApiError("boom", { status: 500 }))).toBe(false);
     });
+
+    it("retries a write the server is still answering, and only that 409", () => {
+        // The server's own message says to retry — "its result will be
+        // replayed" — and a key whose claim outlived the process that took it
+        // is refused until the lease expires. Giving up instead rolls back a
+        // write that retrying would have completed.
+        expect(isRetryableError(new RebaseApiError("in progress", {
+            status: 409, code: "IDEMPOTENCY_KEY_IN_PROGRESS"
+        }))).toBe(true);
+        // Every other 409 is a real conflict and stays fatal.
+        expect(isRetryableError(new RebaseApiError("row exists", { status: 409, code: "23505" }))).toBe(false);
+        expect(isRetryableError(new RebaseApiError("conflict", { status: 409 }))).toBe(false);
+        expect(isRetryableError(new RebaseApiError("reused", {
+            status: 422, code: "IDEMPOTENCY_KEY_REUSED"
+        }))).toBe(false);
+    });
+
+    it("does not read an unanswered write as a row that is already there", () => {
+        // The status alone cannot decide it. Read as a duplicate, the queue
+        // went looking for a row that was never written, found nothing,
+        // concluded there was nothing left to do and deleted the write.
+        expect(isDuplicateKeyError(new RebaseApiError("in progress", {
+            status: 409, code: "IDEMPOTENCY_KEY_IN_PROGRESS"
+        }))).toBe(false);
+
+        expect(isDuplicateKeyError(new RebaseApiError("dup", { status: 400, code: "23505" }))).toBe(true);
+        expect(isDuplicateKeyError(new RebaseApiError("conflict", { status: 409 }))).toBe(true);
+        expect(isDuplicateKeyError(new RebaseApiError("gone", { status: 404 }))).toBe(false);
+    });
 });
 
 describe("ConnectivityMonitor", () => {

package/src/offline-connectivity.ts

@@ -38,11 +38,37 @@ export function isNetworkError(error: unknown): boolean {
  */
 const RETRYABLE_STATUSES = new Set([408, 425, 429, 502, 503, 504]);
 
+/**
+ * The server holds this key for a request it has not answered yet.
+ *
+ * It is a 409 like a duplicate row is a 409, and nothing but the code separates
+ * them — one means "your write is already there", the other means "your write
+ * may not have happened at all, ask again".
+ */
+const IDEMPOTENCY_IN_PROGRESS = "IDEMPOTENCY_KEY_IN_PROGRESS";
+
+/**
+ * Is the server still answering an earlier attempt of this same write?
+ *
+ * The only correct response is to ask again — which is exactly what the
+ * server's own message says, and exactly what this SDK used not to do.
+ */
+export function isIdempotencyInProgressError(error: unknown): boolean {
+    return error instanceof RebaseApiError
+        && error.status === 409
+        && error.code === IDEMPOTENCY_IN_PROGRESS;
+}
+
 /** Is this failure worth another attempt later? */
 export function isRetryableError(error: unknown): boolean {
     if (isNetworkError(error)) return true;
-    if (error instanceof RebaseApiError) return error.status !== undefined && RETRYABLE_STATUSES.has(error.status);
-    return false;
+    if (!(error instanceof RebaseApiError)) return false;
+    // The one 409 that resolves on its own. A key whose claim outlived the
+    // request that took it — the process was killed between the write and the
+    // answer — is refused until the claim's lease expires, and giving up on it
+    // means dropping a write that retrying would have completed.
+    if (isIdempotencyInProgressError(error)) return true;
+    return error.status !== undefined && RETRYABLE_STATUSES.has(error.status);
 }
 
 /**
@@ -55,10 +81,16 @@ export function isRetryableError(error: unknown): boolean {
  * The queue uses this to recognise its own earlier attempt. A create whose
  * response was lost is replayed, and for a row carrying an id the SDK generated
  * the server can only be rejecting it because the first attempt actually landed.
+ *
+ * Which is why the status alone cannot decide it: `IDEMPOTENCY_KEY_IN_PROGRESS`
+ * is a 409 that means the opposite — the row may not exist at all. Read as a
+ * duplicate, the queue looked for a row that was never written, found nothing,
+ * concluded there was nothing left to do and deleted the write from the queue.
  */
 export function isDuplicateKeyError(error: unknown): boolean {
     if (!(error instanceof RebaseApiError)) return false;
-    return error.code === "23505" || error.status === 409;
+    if (error.code === "23505") return true;
+    return error.status === 409 && !isIdempotencyInProgressError(error);
 }
 
 export interface ConnectivityOptions {

package/src/offline-query.test.ts

@@ -1,6 +1,7 @@
 import {
     compareValues,
     isExactlyEvaluable,
+    isLocallySortable,
     looseEquals,
     matchesLogical,
     matchesOperator,
@@ -10,7 +11,8 @@ import {
     runLocalQuery,
     sortRows
 } from "./offline-query";
-import { EntityRelation } from "@rebasepro/types";
+import { DEFAULT_LIST_LIMIT, EntityRelation } from "@rebasepro/types";
+import { resolveFindWindow } from "@rebasepro/common";
 import type { FindParams } from "./transport";
 
 type Row = Record<string, unknown>;
@@ -172,12 +174,37 @@ describe("local query engine", () => {
 
     describe("pagination", () => {
         it("resolves page over offset the way the server does", () => {
-            expect(resolvePagination()).toEqual({ limit: 20, offset: 0 });
             expect(resolvePagination({ limit: 10, offset: 30 })).toEqual({ limit: 10, offset: 30 });
             expect(resolvePagination({ limit: 10, page: 3 })).toEqual({ limit: 10, offset: 20 });
             // `page` wins over `offset`, and the first page is not negative.
             expect(resolvePagination({ limit: 10, page: 1, offset: 99 })).toEqual({ limit: 10, offset: 0 });
         });
+
+        it("defaults to the same page size the server would apply", () => {
+            // Asserted against the constant, not against a number written here.
+            // This test used to say `{ limit: 20 }` — restating a default this
+            // module had invented, while `/api/data` paged by 50. The local
+            // answer and the network answer to one `observe()` were therefore
+            // different lengths, and the test agreed with the wrong one.
+            expect(resolvePagination()).toEqual({ limit: DEFAULT_LIST_LIMIT, offset: 0 });
+        });
+
+        it("agrees with the shared resolver on every shape of window", () => {
+            // The one that matters: the local evaluator and every other
+            // transport must resolve identical windows, or a cached list and a
+            // fetched list disagree about which rows page two holds.
+            for (const params of [
+                undefined,
+                { limit: 10 },
+                { offset: 30 },
+                { page: 4 },
+                { limit: 25, page: 2 },
+                { limit: 10, page: 1, offset: 99 }
+            ]) {
+                const { limit, offset } = resolveFindWindow(params);
+                expect(resolvePagination(params)).toEqual({ limit, offset });
+            }
+        });
     });
 
     describe("runLocalQuery", () => {
@@ -229,6 +256,93 @@ describe("local query engine", () => {
             expect(isExactlyEvaluable({ include: ["author"] })).toBe(false);
             expect(isExactlyEvaluable({ include: [] })).toBe(true);
         });
+
+        /**
+         * An ordering comparison is answered here by `compareValues`, which
+         * falls back to an `Intl.Collator`, and by Postgres using the
+         * *database's* collation — a property of the server this process has
+         * never been told. `'apple' < 'Banana'` is false under the C collation
+         * and true under `en_US.UTF-8`; the collator says true. So the two
+         * select different sets, in whichever direction the deployment happened
+         * to be created.
+         */
+        it("refuses an ordering comparison, whose answer depends on the server's collation", () => {
+            for (const op of ["<", "<=", ">", ">="] as const) {
+                expect({ op, exact: isExactlyEvaluable({ where: { name: [op, "Banana"] } }) })
+                    .toEqual({ op, exact: false });
+            }
+            // Equality, membership and pattern matching are unaffected — all
+            // verified against a real database in
+            // `server-postgres/test/e2e/offline-query-agreement.test.ts`.
+            for (const op of ["==", "!=", "in", "not-in", "like", "ilike"] as const) {
+                expect({ op, exact: isExactlyEvaluable({ where: { name: [op, "x"] } }) })
+                    .toEqual({ op, exact: true });
+            }
+            expect(isExactlyEvaluable({ where: { a: ["is-null", null] } })).toBe(true);
+        });
+
+        it("refuses a numeric range too, because the operand type does not settle it", () => {
+            // `compareValues` deliberately reads numeric strings as numbers, so
+            // it cannot tell an integer column from a text column of digits —
+            // and on the latter Postgres orders "10" before "9" while this
+            // orders 9 before 10. Conservative on purpose; the schema would be
+            // needed to do better.
+            expect(isExactlyEvaluable({ where: { qty: [">", 10] } })).toBe(false);
+        });
+
+        it("looks inside and/or groups, not just the top-level where", () => {
+            expect(isExactlyEvaluable({
+                logical: { type: "or", conditions: [
+                    { column: "a", operator: "==", value: 1 },
+                    { column: "b", operator: "==", value: 2 }
+                ] }
+            } as never)).toBe(true);
+            expect(isExactlyEvaluable({
+                logical: { type: "or", conditions: [
+                    { column: "a", operator: "==", value: 1 },
+                    { type: "and", conditions: [{ column: "b", operator: "<", value: "m" }] }
+                ] }
+            } as never)).toBe(false);
+        });
+
+        it("still refuses several conditions on one field when any of them orders", () => {
+            expect(isExactlyEvaluable({ where: { a: [["==", 1], ["<", "m"]] } } as never)).toBe(false);
+            expect(isExactlyEvaluable({ where: { a: [["==", 1], ["!=", 2]] } } as never)).toBe(true);
+        });
+    });
+
+    describe("isLocallySortable", () => {
+        /**
+         * Asked of the rows rather than the query, because unlike a filter this
+         * one is decidable from the data in hand: the collator is reachable
+         * only when a value cannot be read as a number.
+         */
+        it("accepts a column this page holds only as numbers", () => {
+            expect(isLocallySortable([{ id: 1, n: 3 }, { id: 2, n: 10 }], ["n", "asc"])).toBe(true);
+            // The wire's type erasure is already undone by `compareValues`.
+            expect(isLocallySortable([{ id: 1, n: "3" }, { id: 2, n: "10" }], ["n", "asc"])).toBe(true);
+            // Dates normalise to instants before any comparison happens.
+            expect(isLocallySortable(
+                [{ id: 1, at: new Date(1) }, { id: 2, at: new Date(2) }], ["at", "desc"]
+            )).toBe(true);
+        });
+
+        it("refuses a column holding text, whose order is the database's to decide", () => {
+            expect(isLocallySortable([{ id: 1, name: "apple" }, { id: 2, name: "Banana" }], ["name", "asc"]))
+                .toBe(false);
+            // One text value is enough — a column is one type, and the page that
+            // happens to be cached does not get to vote.
+            expect(isLocallySortable([{ id: 1, n: 3 }, { id: 2, n: "x" }], ["n", "asc"])).toBe(false);
+        });
+
+        it("ignores nulls, which are ordered by an explicit rule", () => {
+            expect(isLocallySortable([{ id: 1, n: null }, { id: 2, n: 5 }], ["n", "asc"])).toBe(true);
+            expect(isLocallySortable([{ id: 1 }, { id: 2 }], ["missing", "asc"])).toBe(true);
+        });
+
+        it("is vacuously true with no sort", () => {
+            expect(isLocallySortable([{ id: 1, name: "a" }], undefined)).toBe(true);
+        });
     });
 
     describe("primitives", () => {

package/src/offline-query.ts

@@ -9,6 +9,7 @@ import {
     toCanonicalOp
 } from "@rebasepro/types";
 import { FindParams } from "./transport";
+import { resolveFindWindow } from "@rebasepro/common";
 
 /**
  * A local evaluator for `FindParams`, so cached rows can answer a query the
@@ -38,8 +39,15 @@ const collator = typeof Intl !== "undefined" && typeof Intl.Collator === "functi
     ? new Intl.Collator(undefined, { numeric: false, sensitivity: "variant" })
     : undefined;
 
-/** The server's page size when the caller does not ask for one. */
-export const DEFAULT_PAGE_SIZE = 20;
+/**
+ * The server's page size when the caller does not ask for one.
+ *
+ * Re-exported rather than redeclared. This was its own `= 20` — a third
+ * constant of this name in the workspace, next to `@rebasepro/common`'s 200 and
+ * the 50 the REST layer actually applies — and a local copy of a number that
+ * belongs to another process is a number that goes stale silently.
+ */
+export { DEFAULT_LIST_LIMIT as DEFAULT_PAGE_SIZE } from "@rebasepro/types";
 
 function isNullish(value: unknown): boolean {
     return value === null || value === undefined;
@@ -137,17 +145,31 @@ export function looseEquals(a: unknown, b: unknown): boolean {
  */
 function likeToRegExp(pattern: string, caseInsensitive: boolean): RegExp {
     let source = "^";
+    // Runs of `%` collapse to one. `%%%%X` means exactly what `%X` means, but
+    // as a regular expression it is four adjacent unbounded quantifiers, and on
+    // a subject that does not match the engine tries every way of splitting the
+    // subject between them. Fourteen of them against a forty-eight character
+    // value took eighty-seven seconds to answer `false`.
+    //
+    // The pattern is user input — `?title=like.%25%25%25…` over HTTP — so that
+    // is a request that pins a CPU. Collapsing is semantics-preserving and
+    // removes the ambiguity the backtracking feeds on.
+    let lastWasWildcard = false;
     for (let i = 0; i < pattern.length; i++) {
         const char = pattern[i];
         if (char === "\\" && i + 1 < pattern.length) {
             source += pattern[i + 1].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
             i++;
+            lastWasWildcard = false;
         } else if (char === "%") {
-            source += "[\\s\\S]*";
+            if (!lastWasWildcard) source += "[\\s\\S]*";
+            lastWasWildcard = true;
         } else if (char === "_") {
             source += "[\\s\\S]";
+            lastWasWildcard = false;
         } else {
             source += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            lastWasWildcard = false;
         }
     }
     return new RegExp(source + "$", caseInsensitive ? "i" : "");
@@ -311,15 +333,42 @@ function tiebreak(a: Record<string, unknown>, b: Record<string, unknown>): numbe
     return cmp ?? 0;
 }
 
-/** Resolve `page`/`offset`/`limit` the way the server does. */
+/**
+ * Resolve `page`/`offset`/`limit` the way the server does.
+ *
+ * It did not: this defaulted an absent limit to 20 while `/api/data` pages by
+ * 50, so the same `observe()` answered with 20 rows from the local database and
+ * 50 from the network — a list that changed length depending on which side
+ * answered, with `page` striding differently on each. Delegated now, so the
+ * sentence above is true by construction rather than by agreement.
+ */
 export function resolvePagination(params?: FindParams): { limit: number; offset: number } {
-    const limit = params?.limit ?? DEFAULT_PAGE_SIZE;
-    const offset = params?.page != null
-        ? Math.max(0, (params.page - 1) * limit)
-        : (params?.offset ?? 0);
+    const { limit, offset } = resolveFindWindow(params);
     return { limit, offset };
 }
 
+/** `<`, `<=`, `>`, `>=` — the operators whose answer depends on a collation. */
+const ORDERING_OPS = new Set<WhereFilterOp>(["<", "<=", ">", ">="]);
+
+/** Does any condition in this `where` clause order its operands? */
+function whereOrders(where: FilterValues<string> | undefined): boolean {
+    if (!where) return false;
+    for (const condition of Object.values(where)) {
+        const tuples = isTuple(condition) ? [condition] : (condition as unknown[]).filter(isTuple);
+        if (tuples.some(([op]) => ORDERING_OPS.has(op))) return true;
+    }
+    return false;
+}
+
+/** The same question, through an `and(...)`/`or(...)` tree. */
+function logicalOrders(condition: LogicalCondition | FilterCondition | undefined, depth = 0): boolean {
+    if (!condition || depth > 32) return false;
+    if ("type" in condition) {
+        return (condition.conditions ?? []).some((c) => logicalOrders(c, depth + 1));
+    }
+    return ORDERING_OPS.has(condition.operator);
+}
+
 /**
  * Can a locally evaluated answer to `params` be trusted to match the server's,
  * assuming the cache holds every row of the collection?
@@ -327,11 +376,77 @@ export function resolvePagination(params?: FindParams): { limit: number; offset:
  * `include` pulls in rows from other collections that this evaluator never
  * sees, and `searchString` is only approximated — both make the local answer a
  * best effort rather than an equivalent one.
+ *
+ * **Ordering comparisons are refused, and that is the interesting one.**
+ * `compareValues` falls back to an `Intl.Collator` for operands it cannot read
+ * as numbers or instants. PostgreSQL orders text by the *database's* collation,
+ * which is a property of the server this process has never been told: under the
+ * C collation `'apple' < 'Banana'` is false, under `en_US.UTF-8` it is true,
+ * and the collator says true. So `["<", "Banana"]` selects a different set here
+ * than it does there — silently, and in whichever direction the deployment
+ * happens to have been created.
+ *
+ * The refusal covers *every* ordering comparison rather than only the ones with
+ * a string operand, because the operand type does not settle it: a numeric
+ * bound against a text column (`["<", 10]` on a `varchar`) also reaches the
+ * collator, and nothing in `params` says what the column holds. Conservative on
+ * purpose — the cost is that a query combining an ordering filter with
+ * *unsynced local writes* stops placing those writes optimistically, which is a
+ * degraded answer rather than a wrong one. Claiming exactness we do not have is
+ * the other way round.
+ *
+ * This says nothing about ordering *results*; that is a separate claim with a
+ * separate answer, because a sort changes which rows come first and not which
+ * rows match. See {@link isLocallySortable}.
  */
 export function isExactlyEvaluable(params?: FindParams): boolean {
     if (!params) return true;
     if (params.include && params.include.length > 0) return false;
     if (params.searchString) return false;
+    // Nearest-neighbour ordering is the server's to compute: the cache holds no
+    // vectors, and even with them, answering from a subset would return the
+    // nearest of what happens to be cached while looking like the nearest there
+    // are — a wrong answer that is indistinguishable from a right one.
+    if (params.vectorSearch) return false;
+    if (whereOrders(params.where)) return false;
+    if (logicalOrders(params.logical)) return false;
+    return true;
+}
+
+/**
+ * Would sorting `rows` locally reproduce the order the server would have sent?
+ *
+ * Asked of the rows rather than of the query, because unlike a filter this one
+ * *is* decidable from the data in hand: {@link compareValues} reaches the
+ * collator only when it cannot read both operands as numbers, and `toComparable`
+ * has already turned dates and relations into numbers and ids by then. If every
+ * value on the sort column normalises to a number, the collator is unreachable
+ * and the local order is the server's order.
+ *
+ * A text column is therefore refused — see {@link isExactlyEvaluable} for why
+ * the two cannot be made to agree — and so is a column this page happens to see
+ * only as strings, which is the same thing from here.
+ *
+ * Nulls are fine either way: they are ordered by an explicit rule (last
+ * ascending, first descending) that matches Postgres and never reaches the
+ * comparator.
+ */
+export function isLocallySortable(
+    rows: readonly Record<string, unknown>[],
+    orderBy?: OrderByTuple
+): boolean {
+    if (!orderBy) return true;
+    const [field] = orderBy;
+    for (const row of rows) {
+        const value = toComparable(row[field]);
+        if (isNullish(value)) continue;
+        if (typeof value === "number" || typeof value === "boolean") continue;
+        if (typeof value === "bigint") continue;
+        // A numeric string is compared as a number, so it is safe too — this is
+        // the wire's type erasure, which `compareValues` already undoes.
+        if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) continue;
+        return false;
+    }
     return true;
 }
 

package/src/offline-store.ts

@@ -52,9 +52,13 @@ export interface PendingMutation {
     /** Unique, lexicographically sortable identity — also the queue key suffix. */
     mutationId: string;
     collection: string;
-    type: "create" | "createMany" | "update" | "delete";
+    type: "create" | "createMany" | "update" | "updateMany" | "delete" | "deleteMany";
     /** Target row id for update/delete, and the (client-generated) id of an offline create. */
     id?: string | number;
+    /** Target row ids for `deleteMany`. */
+    ids?: (string | number)[];
+    /** `{ id, data }` entries for `updateMany`. */
+    updates?: { id: string | number; data: Record<string, unknown> }[];
     /**
      * True when the SDK minted this create's id itself. Only such creates may
      * cancel out against a later offline delete: a freshly generated UUID