@rebasepro/client 0.14.0 → 0.14.1

package/dist/offline-query.d.ts

@@ -1,4 +1,4 @@
-import { FilterValues, FindResult, LogicalCondition, FilterCondition, OrderByTuple, WhereFilterOp } from "@rebasepro/types";
+import { FilterValues, FindResult, LogicalCondition, FilterCondition, OrderBySpec, WhereFilterOp } from "@rebasepro/types";
 import { FindParams } from "./transport";
 /**
  * The server's page size when the caller does not ask for one.
@@ -38,8 +38,15 @@ export declare function matchesParams(row: Record<string, unknown>, params?: Fin
  * Sort in place, Postgres-style: nulls last ascending, first descending, with
  * the row id as a tiebreak so paging through an unsorted-but-equal run does
  * not shuffle rows between pages.
+ *
+ * The tiebreak runs *descending*, which is not a taste: every server-side sort
+ * ends on `id DESC` — `FetchService.buildOrderExpressions` appends it to make
+ * the ordering total, and the keyset cursor is built to match. This ran
+ * ascending, so two rows sharing a sort value came back from the local overlay
+ * in the opposite order to the server's, and {@link isLocallySortable} called
+ * that page exactly reproducible while it was not.
  */
-export declare function sortRows<M extends Record<string, unknown>>(rows: M[], orderBy?: OrderByTuple): M[];
+export declare function sortRows<M extends Record<string, unknown>>(rows: M[], orderBy?: OrderBySpec): M[];
 /**
  * Resolve `page`/`offset`/`limit` the way the server does.
  *
@@ -102,6 +109,6 @@ export declare function isExactlyEvaluable(params?: FindParams): boolean;
  * ascending, first descending) that matches Postgres and never reaches the
  * comparator.
  */
-export declare function isLocallySortable(rows: readonly Record<string, unknown>[], orderBy?: OrderByTuple): boolean;
+export declare function isLocallySortable(rows: readonly Record<string, unknown>[], orderBy?: OrderBySpec): boolean;
 /** Run a full query — filter, sort, paginate — over a set of rows. */
 export declare function runLocalQuery<M extends Record<string, unknown>>(rows: M[], params?: FindParams): FindResult<M>;

package/dist/sdk_query_builder.d.ts

@@ -25,6 +25,11 @@ export declare class SDKQueryBuilder<M extends Record<string, unknown> = Record<
     where(logicalCondition: LogicalCondition): this;
     /**
      * Order the results by a specific column.
+     *
+     * Call it again to add a tie-breaker rather than replace the sort: keys
+     * apply in the order they were added, so
+     * `.orderBy("roles").orderBy("created_at", "desc")` sorts by role and
+     * shows the newest first within each one.
      */
     orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): this;
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/client",
   "type": "module",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "HTTP SDK client for the Rebase custom backend",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -29,9 +29,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@rebasepro/types": "0.14.0",
-    "@rebasepro/common": "0.14.0",
-    "@rebasepro/utils": "0.14.0"
+    "@rebasepro/common": "0.14.1",
+    "@rebasepro/utils": "0.14.1",
+    "@rebasepro/types": "0.14.1"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",

package/src/collection.ts

@@ -12,7 +12,7 @@ import {
     WriteOptions,
     type ComputedSortField
 } from "@rebasepro/types";
-import { collectAllPages, paginateFind, resolveFindWindow } from "@rebasepro/common";
+import { collectAllPages, normalizeOrderBy, paginateFind, resolveFindWindow } from "@rebasepro/common";
 
 import { SDKQueryBuilder } from "./sdk_query_builder";
 
@@ -429,8 +429,11 @@ export function createCollectionClient<M extends Record<string, unknown> = Recor
                     // handed "20" where it expected a keyset value, and the
                     // offset it does understand never arrived at all.
                     offset: window.driverOffset,
-                    orderBy: params?.orderBy?.[0],
-                    order: params?.orderBy?.[1],
+                    // The list form, so a multi-key sort reaches the socket
+                    // whole. Indexing `[0]`/`[1]` here read a tuple-of-tuples as
+                    // a field name and a direction, and a live subscription came
+                    // back in a different order from the same query fetched.
+                    orderBy: normalizeOrderBy(params?.orderBy),
                     searchString: params?.searchString,
                     searchExplain: params?.searchExplain
                 },

package/src/offline-query.test.ts

@@ -158,9 +158,26 @@ describe("local query engine", () => {
             expect(sortRows([...rows], ["n", "desc"]).map((r) => r.id)).toEqual([2, 1, 3]);
         });
 
-        it("breaks ties on id so paging cannot shuffle equal rows between pages", () => {
-            const rows: Row[] = [{ id: "c", n: 1 }, { id: "a", n: 1 }, { id: "b", n: 1 }];
-            expect(sortRows(rows, ["n", "asc"]).map((r) => r.id)).toEqual(["a", "b", "c"]);
+        it("breaks ties on id descending, which is what the server orders by", () => {
+            // Not an arbitrary direction: `FetchService.buildOrderExpressions`
+            // appends `id DESC` to every sort it builds, and the keyset cursor
+            // is written to match it. Ascending here meant the overlay handed
+            // back tied rows in the opposite order to the network answer for
+            // the same query — while `isLocallySortable` reported the page as
+            // exactly reproducible.
+            const rows: Row[] = [{ id: "a", n: 1 }, { id: "c", n: 1 }, { id: "b", n: 1 }];
+            expect(sortRows(rows, ["n", "asc"]).map((r) => r.id)).toEqual(["c", "b", "a"]);
+            expect(sortRows(rows, ["n", "desc"]).map((r) => r.id)).toEqual(["c", "b", "a"]);
+        });
+
+        it("lets a later key decide before the id tiebreak does", () => {
+            const rows: Row[] = [
+                { id: 1, role: "admin", at: 2 },
+                { id: 2, role: "admin", at: 1 },
+                { id: 3, role: "user", at: 9 }
+            ];
+            expect(sortRows(rows, [["role", "asc"], ["at", "desc"]]).map((r) => r.id))
+                .toEqual([1, 2, 3]);
         });
 
         it("orders dates chronologically, not lexicographically", () => {

package/src/offline-query.ts

@@ -4,12 +4,12 @@ import {
     FindResult,
     LogicalCondition,
     FilterCondition,
-    OrderByTuple,
+    OrderBySpec,
     WhereFilterOp,
     toCanonicalOp
 } from "@rebasepro/types";
 import { FindParams } from "./transport";
-import { resolveFindWindow } from "@rebasepro/common";
+import { normalizeOrderBy, resolveFindWindow } from "@rebasepro/common";
 
 /**
  * A local evaluator for `FindParams`, so cached rows can answer a query the
@@ -307,30 +307,55 @@ export function matchesParams(row: Record<string, unknown>, params?: FindParams)
  * Sort in place, Postgres-style: nulls last ascending, first descending, with
  * the row id as a tiebreak so paging through an unsorted-but-equal run does
  * not shuffle rows between pages.
+ *
+ * The tiebreak runs *descending*, which is not a taste: every server-side sort
+ * ends on `id DESC` — `FetchService.buildOrderExpressions` appends it to make
+ * the ordering total, and the keyset cursor is built to match. This ran
+ * ascending, so two rows sharing a sort value came back from the local overlay
+ * in the opposite order to the server's, and {@link isLocallySortable} called
+ * that page exactly reproducible while it was not.
  */
-export function sortRows<M extends Record<string, unknown>>(rows: M[], orderBy?: OrderByTuple): M[] {
-    if (!orderBy) return rows;
-    const [field, direction = "asc"] = orderBy;
-    const sign = direction === "desc" ? -1 : 1;
+export function sortRows<M extends Record<string, unknown>>(rows: M[], orderBy?: OrderBySpec): M[] {
+    const keys = normalizeOrderBy(orderBy);
+    if (!keys) return rows;
     return rows.sort((a, b) => {
-        const av = a[field];
-        const bv = b[field];
-        const aNull = isNullish(toComparable(av));
-        const bNull = isNullish(toComparable(bv));
-        if (aNull || bNull) {
-            if (aNull && bNull) return tiebreak(a, b);
-            // NULLS LAST ascending, NULLS FIRST descending.
-            return (aNull ? 1 : -1) * (direction === "desc" ? -1 : 1);
+        for (const [field, direction = "asc"] of keys) {
+            const cmp = compareOnKey(a, b, field, direction);
+            // Equal on this key — and equal is not a decision, so the next key
+            // gets to make one. Returning the tiebreak here instead is what a
+            // single-key sort does at the end, and doing it per key would order
+            // by the id the moment two rows shared a role.
+            if (cmp !== 0) return cmp;
         }
-        const cmp = compareValues(av, bv);
-        if (cmp === undefined || cmp === 0) return tiebreak(a, b);
-        return cmp * sign;
+        return tiebreak(a, b);
     });
 }
 
+/** One key's verdict: negative, positive, or 0 for "these two are equal here". */
+function compareOnKey(
+    a: Record<string, unknown>,
+    b: Record<string, unknown>,
+    field: string,
+    direction: "asc" | "desc"
+): number {
+    const av = a[field];
+    const bv = b[field];
+    const aNull = isNullish(toComparable(av));
+    const bNull = isNullish(toComparable(bv));
+    if (aNull || bNull) {
+        if (aNull && bNull) return 0;
+        // NULLS LAST ascending, NULLS FIRST descending.
+        return (aNull ? 1 : -1) * (direction === "desc" ? -1 : 1);
+    }
+    const cmp = compareValues(av, bv);
+    if (cmp === undefined || cmp === 0) return 0;
+    return cmp * (direction === "desc" ? -1 : 1);
+}
+
+/** The last word, and the server's: `id DESC`. */
 function tiebreak(a: Record<string, unknown>, b: Record<string, unknown>): number {
     const cmp = compareValues(a.id, b.id);
-    return cmp ?? 0;
+    return cmp === undefined ? 0 : -cmp;
 }
 
 /**
@@ -433,21 +458,22 @@ export function isExactlyEvaluable(params?: FindParams): boolean {
  */
 export function isLocallySortable(
     rows: readonly Record<string, unknown>[],
-    orderBy?: OrderByTuple
+    orderBy?: OrderBySpec
 ): boolean {
-    if (!orderBy) return true;
-    const [field] = orderBy;
-    for (const row of rows) {
+    const keys = normalizeOrderBy(orderBy);
+    if (!keys) return true;
+    // Every key has to be decidable, not just the first: a sort the local side
+    // can only agree with down to its second column is one it disagrees with.
+    return keys.every(([field]) => rows.every((row) => {
         const value = toComparable(row[field]);
-        if (isNullish(value)) continue;
-        if (typeof value === "number" || typeof value === "boolean") continue;
-        if (typeof value === "bigint") continue;
+        if (isNullish(value)) return true;
+        if (typeof value === "number" || typeof value === "boolean") return true;
+        if (typeof value === "bigint") return true;
         // 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;
+        if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) return true;
         return false;
-    }
-    return true;
+    }));
 }
 
 /** Run a full query — filter, sort, paginate — over a set of rows. */

package/src/sdk_query_builder.ts

@@ -2,12 +2,14 @@ import {
     FindParams,
     FindResult,
     LogicalCondition,
+    OrderByTuple,
     SDKCollectionClient,
     SDKQueryBuilderInterface,
     WhereFilterOp,
     WhereValueFor,
     type ComputedSortField
 } from "@rebasepro/types";
+import { normalizeOrderBy } from "@rebasepro/common";
 
 /**
  * SDK Query Builder — returns flat rows (`FindResult<M>`) instead of
@@ -72,9 +74,15 @@ export class SDKQueryBuilder<M extends Record<string, unknown> = Record<string,
 
     /**
      * Order the results by a specific column.
+     *
+     * Call it again to add a tie-breaker rather than replace the sort: keys
+     * apply in the order they were added, so
+     * `.orderBy("roles").orderBy("created_at", "desc")` sorts by role and
+     * shows the newest first within each one.
      */
     orderBy(column: (keyof M & string) | ComputedSortField, direction: "asc" | "desc" = "asc"): this {
-        this.params.orderBy = [column, direction];
+        const existing = normalizeOrderBy(this.params.orderBy) ?? [];
+        this.params.orderBy = [...existing, [column, direction] as OrderByTuple];
         return this;
     }