@rebasepro/common 0.14.0 → 0.14.1-canary.g7e666eb

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/common",
   "type": "module",
-  "version": "0.14.0",
+  "version": "0.14.1-canary.g7e666eb",
   "description": "Rebase shared core — collection registry, data driver adapter and fluent query builder. No React dependency.",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -40,8 +40,8 @@
   "dependencies": {
     "fast-equals": "6.0.2",
     "json-logic-js": "^2.0.5",
-    "@rebasepro/types": "0.14.0",
-    "@rebasepro/utils": "0.14.0"
+    "@rebasepro/types": "0.14.1-canary.g7e666eb",
+    "@rebasepro/utils": "0.14.1-canary.g7e666eb"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",

package/src/data/buildRebaseData.ts

@@ -9,6 +9,7 @@ import {
     FindResult,
     IterateParams,
     LogicalCondition,
+    OrderByTuple,
     RebaseData,
     RebaseSdkData,
     SDKCollectionClient,
@@ -21,6 +22,7 @@ import {
 import { toSnakeCase } from "@rebasepro/utils";
 import { QueryBuilder } from "./query_builder";
 import { collectAllPages, paginateFind, resolveFindWindow } from "./paginate";
+import { normalizeOrderBy } from "./sort-dialect";
 import { deserializeFilter } from "./filter-dialect";
 import { buildCompositeId, resolvePrimaryKeys, PrimaryKeyInfo } from "../util/identity";
 
@@ -191,8 +193,7 @@ function createDriverAccessor<M extends Record<string, unknown> = Record<string,
                         logical: params?.logical,
                         limit,
                         offset: driverOffset,
-                        orderBy: params?.orderBy?.[0],
-                        order: params?.orderBy?.[1],
+                        orderBy: normalizeOrderBy(params?.orderBy),
                         searchString: params?.searchString
                     },
                     params?.include
@@ -203,8 +204,7 @@ function createDriverAccessor<M extends Record<string, unknown> = Record<string,
                     offset: driverOffset,
                     filter,
                     logical: params?.logical,
-                    orderBy: params?.orderBy?.[0],
-                    order: params?.orderBy?.[1],
+                    orderBy: normalizeOrderBy(params?.orderBy),
                     searchString: params?.searchString
                 });
 
@@ -330,8 +330,7 @@ ids });
                     offset: driverOffset,
                     filter: params?.where,
                     logical: params?.logical,
-                    orderBy: params?.orderBy?.[0],
-                    order: params?.orderBy?.[1],
+                    orderBy: normalizeOrderBy(params?.orderBy),
                     searchString: params?.searchString,
                     searchExplain: params?.searchExplain,
                     onUpdate: (entities) => {
@@ -494,8 +493,10 @@ class SdkQueryBuilder<M extends Record<string, unknown> = Record<string, unknown
         return this;
     }
 
+    /** Called again, this adds a tie-breaker rather than replacing the sort. */
     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;
     }
 

package/src/data/paginate.ts

@@ -8,6 +8,7 @@ import {
     IterateParams,
     WhereFilterOp
 } from "@rebasepro/types";
+import { normalizeOrderBy } from "./sort-dialect";
 
 /**
  * The pagination engine behind `iterate()` / `findAll()`.
@@ -184,16 +185,29 @@ export async function* paginateFind<M extends Record<string, unknown> = Record<s
 
     let direction: "asc" | "desc" = "asc";
     if (cursorField) {
-        const orderBy = findParams.orderBy;
-        if (orderBy && orderBy[0] !== cursorField) {
+        const orderBy = normalizeOrderBy(findParams.orderBy);
+        // A seek is one `>`/`<` on one column, so it can only follow a sort of
+        // one column. Over a multi-key sort the same comparison both repeats
+        // rows (every later key's ties) and skips them, which is the failure
+        // this error exists to prevent — name it rather than seek anyway.
+        if (orderBy && orderBy.length > 1) {
             throw new RebasePaginationError(
                 "cursor-order-mismatch",
-                `Cannot seek on "${cursorField}" while ordering "${label}" by "${orderBy[0]}": ` +
+                `Cannot seek on "${cursorField}" while ordering "${label}" by ` +
+                `${orderBy.map(([field]) => `"${field}"`).join(", ")}: ` +
+                `keyset pagination advances along a single column. ` +
+                `Order by "${cursorField}" alone, or drop the cursor and page by offset.`
+            );
+        }
+        if (orderBy && orderBy[0][0] !== cursorField) {
+            throw new RebasePaginationError(
+                "cursor-order-mismatch",
+                `Cannot seek on "${cursorField}" while ordering "${label}" by "${orderBy[0][0]}": ` +
                 `keyset pagination only advances along the column the query is sorted by. ` +
                 `Order by "${cursorField}", or drop the cursor and page by offset.`
             );
         }
-        direction = requestedDirection ?? orderBy?.[1] ?? "asc";
+        direction = requestedDirection ?? orderBy?.[0][1] ?? "asc";
         findParams.orderBy = [cursorField, direction] as FindParams<M>["orderBy"];
     }
     const seekOp: WhereFilterOp = direction === "desc" ? "<" : ">";

package/src/data/query_builder.ts

@@ -4,11 +4,13 @@ import {
     FindParams,
     FindResponse,
     LogicalCondition,
+    OrderByTuple,
     QueryBuilderInterface,
     WhereFilterOp,
     WhereValueFor,
     type ComputedSortField
 } from "@rebasepro/types";
+import { normalizeOrderBy } from "./sort-dialect";
 
 export function or(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition {
     return { type: "or",
@@ -78,11 +80,18 @@ export class QueryBuilder<M extends Record<string, unknown> = Record<string, unk
 
     /**
      * Order the results by a specific column.
+     *
+     * Called again, this adds a tie-breaker rather than replacing the sort:
+     * keys apply in the order they were added.
+     *
      * @example
      * client.collection('users').orderBy('createdAt', 'desc').find()
+     * @example
+     * client.collection('users').orderBy('roles').orderBy('createdAt', 'desc').find()
      */
     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;
     }
 

package/src/data/sort-dialect.ts

@@ -1,10 +1,11 @@
-import type { OrderByTuple } from "@rebasepro/types";
+import type { OrderBySpec, OrderByTuple } from "@rebasepro/types";
 
 /**
  * Sort-order wire codec.
  *
  * This is the ONLY module that knows about the colon-delimited wire format
- * (`"field:direction"`) used in HTTP query parameters.
+ * (`"field:direction"`) used in HTTP query parameters, and about the JSON-array
+ * form that carries a multi-column sort over the same parameter.
  * Everything else speaks {@link OrderByTuple} exclusively.
  *
  * Mirrors the filter architecture in `filter-dialect.ts`.
@@ -13,26 +14,140 @@ import type { OrderByTuple } from "@rebasepro/types";
  */
 
 /**
- * Serialize an {@link OrderByTuple} to the wire format `"field:direction"`.
+ * Collapse the one-key and many-key spellings of a sort into the list form.
+ *
+ * `["a", "desc"]` and `[["a", "desc"]]` mean the same thing and normalize to
+ * the same value; the two are told apart by whether the first element is
+ * itself an array, which no field name ever is.
+ *
+ * @returns The keys in order of significance, or `undefined` for no sort. An
+ *   empty list also returns `undefined` — "sort by nothing" is no sort, and
+ *   letting `[]` through would have every layer below re-deciding what it meant.
+ */
+export function normalizeOrderBy(orderBy?: OrderBySpec): OrderByTuple[] | undefined {
+    if (!orderBy || orderBy.length === 0) return undefined;
+    const list = Array.isArray(orderBy[0])
+        ? orderBy as OrderByTuple[]
+        : [orderBy as OrderByTuple];
+    return list.length > 0 ? list : undefined;
+}
+
+/**
+ * The most significant sort key, for a caller that can only express one —
+ * a column header's arrow, a URL parameter, a driver that has not been taught
+ * the list form.
+ */
+export function primaryOrderBy(orderBy?: OrderBySpec): OrderByTuple | undefined {
+    return normalizeOrderBy(orderBy)?.[0];
+}
+
+/**
+ * Collapse the driver-level `{orderBy, order}` pair into the list form.
+ *
+ * The driver contract spells a single-column sort as a field name plus a
+ * separate direction, and a multi-column one as a list of tuples that leaves
+ * `order` meaningless. Every driver reads both through here so neither
+ * spelling has to be handled twice.
+ *
+ * An absent direction means ascending — the same thing a bare `?orderBy=name`
+ * has always meant over HTTP. The Postgres driver used to read the same pair as
+ * *descending* while Mongo read it as ascending, so one field name and no
+ * direction described two different queries depending on which database was
+ * underneath. Neither had a caller: every path in the workspace passes a
+ * direction, which is why the disagreement went unnoticed rather than being
+ * load-bearing.
+ */
+export function normalizeDriverOrderBy(
+    orderBy?: string | OrderByTuple[],
+    order?: "asc" | "desc"
+): OrderByTuple[] | undefined {
+    if (!orderBy) return undefined;
+    if (typeof orderBy === "string") return [[orderBy, order === "desc" ? "desc" : "asc"]];
+    return orderBy.length > 0 ? orderBy : undefined;
+}
+
+/** A sort whose *shape* is unusable, as opposed to one naming a field that does not exist. */
+export class OrderBySpecError extends Error {
+    readonly code = "INVALID_ORDER_BY";
+    constructor(detail: string) {
+        super(
+            `Invalid \`orderBy\`: ${detail}. Expected a field name, or a list of ` +
+            "[field, direction] pairs like [[\"roles\",\"asc\"],[\"created_at\",\"desc\"]]"
+        );
+        this.name = "OrderBySpecError";
+    }
+}
+
+/**
+ * Validate an `orderBy` that arrived from outside this process — a WebSocket
+ * subscribe frame, a driver call from untyped JavaScript — and return it in the
+ * list form.
+ *
+ * Strict on purpose, in the same way the REST `parseOrderByParam` is: the
+ * failure mode for a shape nobody checks is not a crash but a *silently
+ * different query*. A malformed entry read as a field name resolves to no
+ * column, and under the lenient unknown-field mode the sort is then dropped and
+ * the rows come back in whatever order the database pleased — sorted, as far as
+ * the subscriber can tell, by whatever they asked for.
+ */
+export function parseOrderBySpecStrict(raw: unknown, order?: "asc" | "desc"): OrderByTuple[] | undefined {
+    if (raw === undefined || raw === null || raw === "") return undefined;
+    // The string spelling is the driver contract's, so it takes its direction
+    // from the same companion `order` — and defaults the same way it does.
+    if (typeof raw === "string") return normalizeDriverOrderBy(raw, order);
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new OrderBySpecError(`${typeof raw} is not a field name or a list of sort keys`);
+    }
+
+    // The single-tuple spelling, `["created_at", "desc"]`.
+    if (typeof raw[0] === "string") return [toStrictTuple(raw, 0)];
+
+    return raw.map(toStrictTuple);
+}
+
+function toStrictTuple(raw: unknown, index: number): OrderByTuple {
+    if (!Array.isArray(raw) || typeof raw[0] !== "string" || raw[0].trim() === "") {
+        throw new OrderBySpecError(`entry ${index} has no field name`);
+    }
+    const direction = raw[1];
+    if (direction !== undefined && direction !== "asc" && direction !== "desc") {
+        throw new OrderBySpecError(`entry ${index} has direction '${String(direction)}'`);
+    }
+    return [raw[0], direction ?? "asc"];
+}
+
+/**
+ * Serialize a sort to the wire.
+ *
+ * A single key keeps the `"field:direction"` shorthand it has always used —
+ * short, readable in a URL, and what every existing client and test expects.
+ * Several keys are emitted as the canonical JSON array the server already
+ * accepts, because the shorthand has no separator to spare: a comma-joined
+ * `"a:asc,b:desc"` parses as one field named `a` with the direction
+ * `"asc,b:desc"`, which the server refuses.
  *
  * **Runtime tolerance:** if the input is already a well-formed wire string
  * (from an untyped JS caller), it is returned unchanged.
  * This is undocumented tolerance, not public API — don't rely on it.
  *
- * @param orderBy - A canonical `[field, direction]` tuple, or at runtime
+ * @param orderBy - A canonical tuple or list of tuples, or at runtime
  *   possibly a pre-serialized string (undocumented tolerance).
  * @returns The wire-format string, or `undefined` if the input is falsy.
  *
  * @remarks
  * Field names containing `:` are representable in the tuple form but
- * **not** on the wire — this is an inherent limitation of the colon-delimited
- * encoding and is not resolved here.
+ * **not** in the single-key wire encoding — this is an inherent limitation of
+ * the colon-delimited shorthand and is not resolved here.
  */
-export function serializeOrderBy(orderBy?: OrderByTuple | string): string | undefined {
+export function serializeOrderBy(orderBy?: OrderBySpec | string): string | undefined {
     if (!orderBy) return undefined;
     // Runtime tolerance: pass through a pre-serialized wire string unchanged.
     if (typeof orderBy === "string") return orderBy;
-    return `${orderBy[0]}:${orderBy[1]}`;
+    const list = normalizeOrderBy(orderBy);
+    if (!list) return undefined;
+    if (list.length === 1) return `${list[0][0]}:${list[0][1]}`;
+    return JSON.stringify(list.map(([field, direction]) => ({ field,
+direction })));
 }
 
 /**
@@ -43,6 +158,10 @@ export function serializeOrderBy(orderBy?: OrderByTuple | string): string | unde
  * - Unknown direction: `"name:foo"` → `["name", "asc"]`
  * - Empty / falsy input: → `undefined`
  *
+ * Reads the single-key shorthand only. For a value that may carry several keys,
+ * use {@link deserializeOrderByList} — handed a JSON array this returns the
+ * whole array as one nonsensical field name.
+ *
  * @param raw - The wire-format string from an HTTP query parameter.
  * @returns The canonical tuple, or `undefined` if the input is empty/falsy.
  */
@@ -54,3 +173,41 @@ export function deserializeOrderBy(raw?: string): OrderByTuple | undefined {
     const dir = raw.slice(idx + 1);
     return [field, dir === "desc" ? "desc" : "asc"];
 }
+
+/**
+ * Deserialize either wire spelling — the single-key shorthand or the JSON
+ * array — into the list form.
+ *
+ * Lenient in the same way {@link deserializeOrderBy} is: this is the client end
+ * of the codec, where the value was produced by {@link serializeOrderBy} a
+ * moment earlier. The *server* end parses the same shapes strictly, in
+ * `parseOrderByParam`, because there the value came from a stranger and a
+ * direction it cannot read has to be refused rather than quietly turned into
+ * `"asc"`.
+ */
+export function deserializeOrderByList(raw?: string): OrderByTuple[] | undefined {
+    if (!raw) return undefined;
+    const trimmed = raw.trim();
+    if (trimmed.startsWith("[")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (Array.isArray(parsed)) {
+                const list = parsed
+                    .map((entry): OrderByTuple | undefined => {
+                        if (typeof entry === "string") return deserializeOrderBy(entry);
+                        if (entry && typeof entry === "object" && typeof entry.field === "string") {
+                            return [entry.field, entry.direction === "desc" ? "desc" : "asc"];
+                        }
+                        return undefined;
+                    })
+                    .filter((entry): entry is OrderByTuple => entry !== undefined);
+                return list.length > 0 ? list : undefined;
+            }
+        } catch {
+            // Not JSON after all — fall through to the shorthand, which is what
+            // a field name that merely begins with "[" would be.
+        }
+    }
+    const single = deserializeOrderBy(trimmed);
+    return single ? [single] : undefined;
+}

package/src/util/policy/policyToPostgres.ts

@@ -192,9 +192,62 @@ function schemaOf(collection?: CollectionConfig): string | undefined {
 function resolveColumnName(propName: string, collection?: CollectionConfig): string {
     const prop = collection?.properties?.[propName] as Property | undefined;
     if (prop && "columnName" in prop && typeof (prop as { columnName?: unknown }).columnName === "string") {
-        return (prop as { columnName: string }).columnName;
+        return quoteColumnIdentifier((prop as { columnName: string }).columnName);
     }
-    return toSnakeCase(propName);
+    return quoteColumnIdentifier(toSnakeCase(propName));
+}
+
+/**
+ * Every PostgreSQL keyword that cannot stand as a bare column reference.
+ * Appendix C's two reserved categories — plain "reserved", and "reserved (can
+ * be function or type name)" — since neither may name a column unquoted.
+ */
+const RESERVED_SQL_WORDS = new Set([
+    "all", "analyse", "analyze", "and", "any", "array", "as", "asc", "asymmetric", "authorization",
+    "binary", "both", "case", "cast", "check", "collate", "collation", "column", "concurrently",
+    "constraint", "create", "cross", "current_catalog", "current_date", "current_role",
+    "current_schema", "current_time", "current_timestamp", "current_user", "default", "deferrable",
+    "desc", "distinct", "do", "else", "end", "except", "false", "fetch", "for", "foreign", "freeze",
+    "from", "full", "grant", "group", "having", "ilike", "in", "initially", "inner", "intersect",
+    "into", "is", "isnull", "join", "lateral", "leading", "left", "like", "limit", "localtime",
+    "localtimestamp", "natural", "not", "notnull", "null", "offset", "on", "only", "or", "order",
+    "outer", "overlaps", "placing", "primary", "references", "returning", "right", "select",
+    "session_user", "similar", "some", "symmetric", "system_user", "table", "tablesample", "then",
+    "to", "trailing", "true", "union", "unique", "user", "using", "variadic", "verbose", "when",
+    "where", "window", "with"
+]);
+
+/** An identifier Postgres reads back unchanged without quotes. */
+const BARE_IDENTIFIER = /^[a-z_][a-z0-9_$]*$/;
+
+/**
+ * Quote a column reference when Postgres would not read the bare name as that
+ * column — and only then.
+ *
+ * Three ways a bare name goes wrong, in ascending order of how long it takes to
+ * notice:
+ *
+ * - **Case.** `columnName` is used verbatim, and `rebase schema introspect`
+ *   populates it from a live database, so a legacy `"createdAt"` column arrives
+ *   spelled exactly that way. Unquoted, Postgres folds it to `createdat` and
+ *   `CREATE POLICY` fails with "column does not exist" — the collection keeps
+ *   RLS enabled with no policy, which denies every row.
+ * - **Syntax.** A column named `order` or `default` is a syntax error mid-clause.
+ * - **Silent rebinding.** `user`, `current_user`, `session_user`, `current_date`
+ *   and friends are *valid bare expressions*, so the policy compiles, applies,
+ *   and is reported as a success — while comparing against the connected role
+ *   or the wall clock instead of the column. Under RLS every request runs as the
+ *   same `rebase_user` role, so `USING (user = rebase.uid())` is a constant: it
+ *   denies everything, and its negation admits everything.
+ *
+ * Only the names that need it are quoted, so an ordinary snake_case policy body
+ * is emitted byte-for-byte as before. That keeps generated artifacts and the
+ * policies already stored in shipped databases stable — this fix reaches the
+ * clauses that were broken and no others.
+ */
+function quoteColumnIdentifier(name: string): string {
+    if (BARE_IDENTIFIER.test(name) && !RESERVED_SQL_WORDS.has(name)) return name;
+    return `"${name.replace(/"/g, "\"\"")}"`;
 }
 
 function quoteLiteral(value: string | number | boolean | null): string {