@rebasepro/types 0.14.0 → 0.14.1-canary.g7e666eb

package/dist/types/backend.d.ts

@@ -1,4 +1,5 @@
 import type { CollectionConfig, FilterValues, WhereFilterOp } from "./collections";
+import type { OrderByTuple } from "./filter-operators";
 import type { LogicalCondition } from "../controllers/data";
 import type { AuthAdapter } from "./auth_adapter";
 import type { HistoryConfig } from "../controllers/client";
@@ -34,7 +35,8 @@ export interface QueryFilter {
  */
 export interface FetchCollectionOptions<M extends Record<string, unknown> = Record<string, unknown>> {
     filter?: FilterValues<Extract<keyof M, string>>;
-    orderBy?: string;
+    /** See `FetchCollectionProps.orderBy`: a field name plus `order`, or a list of tuples. */
+    orderBy?: string | OrderByTuple[];
     order?: "desc" | "asc";
     limit?: number;
     offset?: number;
@@ -48,7 +50,8 @@ export interface FetchCollectionOptions<M extends Record<string, unknown> = Reco
  */
 export interface SearchOptions<M extends Record<string, unknown> = Record<string, unknown>> {
     filter?: FilterValues<Extract<keyof M, string>>;
-    orderBy?: string;
+    /** See `FetchCollectionProps.orderBy`: a field name plus `order`, or a list of tuples. */
+    orderBy?: string | OrderByTuple[];
     order?: "desc" | "asc";
     limit?: number;
     databaseId?: string;
@@ -156,7 +159,25 @@ export interface CollectionSubscriptionConfig {
     clientId: string;
     path: string;
     filter?: unknown;
-    orderBy?: string;
+    /**
+     * An `or(...)`/`and(...)` group, applied alongside `filter`.
+     *
+     * Declared here because a subscription is a query, and every field a query
+     * has this one needs too. It was missing, so the type-checked boundary
+     * dropped it: the client sent the group, nothing rejected it, and the
+     * subscription re-fetched with the group gone — pushing every row the
+     * caller's policies allowed rather than the ones they asked for. The same
+     * defect `FetchCollectionProps.logical` documents, one layer up.
+     */
+    logical?: LogicalCondition;
+    /**
+     * Where the subscription's page starts. Missing for the same reason, with
+     * a quieter symptom: a subscriber watching page two was pushed page one,
+     * and a `collection_update` frame carries no window for it to notice with.
+     */
+    offset?: number;
+    /** See `FetchCollectionProps.orderBy`: a field name plus `order`, or a list of tuples. */
+    orderBy?: string | OrderByTuple[];
     order?: "desc" | "asc";
     limit?: number;
     startAfter?: unknown;

package/dist/types/filter-operators.d.ts

@@ -44,12 +44,28 @@
  * boundary, handled by `serializeOrderBy` / `deserializeOrderBy` in
  * `@rebasepro/common`.
  *
- * Design note: the natural extension for multi-column sort is
- * `OrderByTuple[]` — not implemented yet (server consumes only the first).
- *
  * @group Models
  */
 export type OrderByTuple<Key extends string = string> = [Key, "asc" | "desc"];
+/**
+ * One sort key, or several applied in order of significance.
+ *
+ * ```ts
+ * orderBy: ["created_at", "desc"]                      // one key
+ * orderBy: [["roles", "asc"], ["created_at", "desc"]]  // roles, then newest first
+ * ```
+ *
+ * The two forms are told apart by whether the first element is itself an
+ * array, so a single tuple never needs wrapping and every existing caller
+ * keeps working unchanged. `normalizeOrderBy` in `@rebasepro/common` collapses
+ * both to the list form, which is what every layer below the call site speaks.
+ *
+ * Ties on the last key are broken by the row id, so a multi-key sort is a
+ * total order and pages over it neither repeat nor skip rows.
+ *
+ * @group Models
+ */
+export type OrderBySpec<Key extends string = string> = OrderByTuple<Key> | OrderByTuple<Key>[];
 /**
  * Canonical filter operators supported across all database backends.
  * Each DB driver translates these to its native query format.
@@ -133,8 +149,9 @@ export interface FilterPreset<Key extends string = string> {
     filterValues: FilterValues<Key>;
     /**
      * Optional sort override to apply alongside the filter values.
+     * One key, or several in order of significance.
      */
-    sort?: OrderByTuple<Key>;
+    sort?: OrderBySpec<Key>;
 }
 /**
  * PostgREST short-code operators. Wire format only — these never appear

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.14.0",
+  "version": "0.14.1-canary.g7e666eb",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"

package/src/controllers/data.ts

@@ -1,7 +1,7 @@
 import type { VectorSearchParams } from "./data_driver";
 import type { ComputedSortField, SearchMatch } from "../types/search";
 import { Entity, EntityValues } from "../types/entities";
-import { WhereFilterOp, FieldPath, FilterValues, OrderByTuple } from "../types/filter-operators";
+import { WhereFilterOp, FieldPath, FilterValues, OrderBySpec } from "../types/filter-operators";
 
 /**
  * Operator-blind filter value: whatever the column holds, a list of it, or null.
@@ -160,10 +160,13 @@ export interface FindParams<M extends Record<string, unknown> = Record<string, u
      */
     logical?: LogicalCondition;
     /**
-     * Sort order as a `[field, direction]` tuple.
+     * Sort order as a `[field, direction]` tuple, or a list of them applied in
+     * order of significance — the second key breaks ties on the first, and so on.
+     *
      * @example orderBy: ["created_at", "desc"]
+     * @example orderBy: [["roles", "asc"], ["created_at", "desc"]]
      */
-    orderBy?: OrderByTuple<FieldPath<M> | ComputedSortField>;
+    orderBy?: OrderBySpec<FieldPath<M> | ComputedSortField>;
     /**
      * Relations to include in the response.
      *

package/src/controllers/data_driver.ts

@@ -2,6 +2,7 @@ import { RebaseApiError } from "../errors";
 import type { CollectionRegistryController } from "./collection_registry";
 import type { EntityStatus, EntityValues } from "../types/entities";
 import type { CollectionConfig, FilterValues } from "../types/collections";
+import type { OrderByTuple } from "../types/filter-operators";
 import type { RebaseCallContext } from "../call_context";
 import type { LogicalCondition } from "./data";
 
@@ -167,10 +168,25 @@ export interface FetchCollectionProps<M extends Record<string, unknown> = Record
     limit?: number;
     offset?: number;
     startAfter?: unknown;
-    orderBy?: string;
+    /**
+     * The sort, in either of two spellings:
+     *
+     * - a field name, whose direction is the separate `order` below — the
+     *   original single-column contract, which every existing driver reads;
+     * - a list of `[field, direction]` tuples applied in order of significance,
+     *   which carries a multi-column sort and ignores `order` entirely.
+     *
+     * `normalizeDriverOrderBy` in `@rebasepro/common` collapses the pair to the
+     * list form. A driver that has not been taught the list form should read it
+     * through that helper rather than assume a string: handed an array, `String()`
+     * would produce a field name like `roles,asc` and the sort would 400 (or,
+     * with unknown-field warnings on, silently vanish).
+     */
+    orderBy?: string | OrderByTuple[];
     searchString?: string;
     /** Ask each row which declared search field matched — populates `_matches`. */
     searchExplain?: boolean;
+    /** Direction for the string form of `orderBy`. Ignored when `orderBy` is a list. */
     order?: "desc" | "asc";
     /** Vector similarity search configuration */
     vectorSearch?: VectorSearchParams;
@@ -508,7 +524,8 @@ export interface RestFetchService {
             filter?: FilterValues<string>;
             /** An `or(...)`/`and(...)` group, applied alongside `filter`. */
             logical?: LogicalCondition;
-            orderBy?: string;
+            /** See `FetchCollectionProps.orderBy`: a field name plus `order`, or a list of tuples. */
+            orderBy?: string | OrderByTuple[];
             order?: "desc" | "asc";
             limit?: number;
             offset?: number;

package/src/types/backend.ts

@@ -1,4 +1,5 @@
 import type { CollectionConfig, FilterValues, WhereFilterOp } from "./collections";
+import type { OrderByTuple } from "./filter-operators";
 import type { LogicalCondition } from "../controllers/data";
 import type { AuthAdapter } from "./auth_adapter";
 import type { HistoryConfig } from "../controllers/client";
@@ -47,7 +48,8 @@ export interface QueryFilter {
  */
 export interface FetchCollectionOptions<M extends Record<string, unknown> = Record<string, unknown>> {
     filter?: FilterValues<Extract<keyof M, string>>;
-    orderBy?: string;
+    /** See `FetchCollectionProps.orderBy`: a field name plus `order`, or a list of tuples. */
+    orderBy?: string | OrderByTuple[];
     order?: "desc" | "asc";
     limit?: number;
     offset?: number;
@@ -62,7 +64,8 @@ export interface FetchCollectionOptions<M extends Record<string, unknown> = Reco
  */
 export interface SearchOptions<M extends Record<string, unknown> = Record<string, unknown>> {
     filter?: FilterValues<Extract<keyof M, string>>;
-    orderBy?: string;
+    /** See `FetchCollectionProps.orderBy`: a field name plus `order`, or a list of tuples. */
+    orderBy?: string | OrderByTuple[];
     order?: "desc" | "asc";
     limit?: number;
     databaseId?: string;
@@ -237,7 +240,25 @@ export interface CollectionSubscriptionConfig {
     clientId: string;
     path: string;
     filter?: unknown;
-    orderBy?: string;
+    /**
+     * An `or(...)`/`and(...)` group, applied alongside `filter`.
+     *
+     * Declared here because a subscription is a query, and every field a query
+     * has this one needs too. It was missing, so the type-checked boundary
+     * dropped it: the client sent the group, nothing rejected it, and the
+     * subscription re-fetched with the group gone — pushing every row the
+     * caller's policies allowed rather than the ones they asked for. The same
+     * defect `FetchCollectionProps.logical` documents, one layer up.
+     */
+    logical?: LogicalCondition;
+    /**
+     * Where the subscription's page starts. Missing for the same reason, with
+     * a quieter symptom: a subscriber watching page two was pushed page one,
+     * and a `collection_update` frame carries no window for it to notice with.
+     */
+    offset?: number;
+    /** See `FetchCollectionProps.orderBy`: a field name plus `order`, or a list of tuples. */
+    orderBy?: string | OrderByTuple[];
     order?: "desc" | "asc";
     limit?: number;
     startAfter?: unknown;

package/src/types/filter-operators.ts

@@ -45,13 +45,30 @@
  * boundary, handled by `serializeOrderBy` / `deserializeOrderBy` in
  * `@rebasepro/common`.
  *
- * Design note: the natural extension for multi-column sort is
- * `OrderByTuple[]` — not implemented yet (server consumes only the first).
- *
  * @group Models
  */
 export type OrderByTuple<Key extends string = string> = [Key, "asc" | "desc"];
 
+/**
+ * One sort key, or several applied in order of significance.
+ *
+ * ```ts
+ * orderBy: ["created_at", "desc"]                      // one key
+ * orderBy: [["roles", "asc"], ["created_at", "desc"]]  // roles, then newest first
+ * ```
+ *
+ * The two forms are told apart by whether the first element is itself an
+ * array, so a single tuple never needs wrapping and every existing caller
+ * keeps working unchanged. `normalizeOrderBy` in `@rebasepro/common` collapses
+ * both to the list form, which is what every layer below the call site speaks.
+ *
+ * Ties on the last key are broken by the row id, so a multi-key sort is a
+ * total order and pages over it neither repeat nor skip rows.
+ *
+ * @group Models
+ */
+export type OrderBySpec<Key extends string = string> = OrderByTuple<Key> | OrderByTuple<Key>[];
+
 /**
  * Canonical filter operators supported across all database backends.
  * Each DB driver translates these to its native query format.
@@ -161,8 +178,9 @@ export interface FilterPreset<Key extends string = string> {
 
     /**
      * Optional sort override to apply alongside the filter values.
+     * One key, or several in order of significance.
      */
-    sort?: OrderByTuple<Key>;
+    sort?: OrderBySpec<Key>;
 }
 
 /**