@rebasepro/types 0.14.0 → 0.14.1-canary.g932d14c

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;
@@ -617,8 +638,14 @@ export interface BackendBootstrapper {
      * enum types, and never drop, narrow or rewrite anything. This runs
      * unattended against live customer data with nobody reading a diff, so the
      * destructive half stays a deliberate migration.
+     *
+     * `driverResult` is optional: this runs before `initializeDriver`, and only
+     * the bundle path has a pre-init stand-in to pass. An adapter built by an
+     * application already holds its own connection and MUST use it when this is
+     * `undefined` — dereferencing it unconditionally works for managed tenants
+     * and breaks every app that builds its own adapter.
      */
-    ensureCollectionSchema?(collections: unknown[], driverResult: InitializedDriver, log?: (message: string) => void): Promise<{
+    ensureCollectionSchema?(collections: unknown[], driverResult?: InitializedDriver, log?: (message: string) => void): Promise<{
         applied: number;
     }>;
     /**
@@ -637,7 +664,7 @@ export interface BackendBootstrapper {
      * Runs after auth initialization, because the generated policies call the
      * `auth.*` helper functions and `CREATE POLICY` validates they exist.
      */
-    ensureCollectionPolicies?(collections: unknown[], driverResult: InitializedDriver, log?: (message: string) => void): Promise<{
+    ensureCollectionPolicies?(collections: unknown[], driverResult?: InitializedDriver, log?: (message: string) => void): Promise<{
         applied: number;
     }>;
     /**

package/dist/types/database_adapter.d.ts

@@ -84,8 +84,16 @@ export interface DatabaseAdapter {
      * into a `BackendBootstrapper`: the runtime calls it through the bootstrapper
      * at boot, and a wrapper that silently omits it leaves a managed tenant
      * 500ing every data route with no create step ever having run.
+     *
+     * `driverResult` is optional because this runs BEFORE `initializeDriver`, so
+     * there may be no result to pass. The bundle path can supply a pre-init
+     * stand-in because the coordinator opened the connection itself; an app that
+     * constructed this adapter never handed the framework a connection handle,
+     * so it passes `undefined` and the adapter MUST fall back to the connection
+     * it was constructed with. An adapter that dereferences `driverResult`
+     * unconditionally works for managed tenants and breaks every self-built one.
      */
-    ensureCollectionSchema?(collections: unknown[], driverResult: InitializedDriver, log?: (message: string) => void): Promise<{
+    ensureCollectionSchema?(collections: unknown[], driverResult?: InitializedDriver, log?: (message: string) => void): Promise<{
         applied: number;
     }>;
     /**
@@ -98,7 +106,7 @@ export interface DatabaseAdapter {
      * policies, tables exist but every user-context read is denied (a public
      * collection answers 401).
      */
-    ensureCollectionPolicies?(collections: unknown[], driverResult: InitializedDriver, log?: (message: string) => void): Promise<{
+    ensureCollectionPolicies?(collections: unknown[], driverResult?: InitializedDriver, log?: (message: string) => void): Promise<{
         applied: number;
     }>;
     /**
@@ -147,4 +155,25 @@ export interface DatabaseAdapterInitConfig {
     baas?: {
         unprotectedTables?: "exclude" | "serve";
     };
+    /**
+     * What the runtime's boot-time table provisioning did, in this process,
+     * before this driver was initialized.
+     *
+     * A driver that checks for missing tables cannot otherwise tell "the create
+     * step ran and this table still is not here" from "no create step ran at
+     * all" — and those need opposite advice. The Postgres driver's drift warning
+     * assumed the first, told operators to redeploy with REBASE_MIGRATE_ON_BOOT
+     * unset, and pointed at driver version skew; for an app whose boot path had
+     * no provisioning step, all of that was unactionable and one investigation
+     * chased a driver that was perfectly current.
+     *
+     * Absent when the caller predates this field: treat that as "unknown" and
+     * fall back to generic guidance rather than asserting either case.
+     */
+    schemaProvisioning?: {
+        /** Whether the table-creation hook actually ran this boot. */
+        attempted: boolean;
+        /** Why it did not, when it did not — safe to print verbatim. */
+        reason?: string;
+    };
 }

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.g932d14c",
   "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;
@@ -522,6 +539,31 @@ export interface RestFetchService {
         include?: string[]
     ): Promise<Record<string, unknown>[]>;
 
+    /**
+     * `count`/`sum`/`avg`/`min`/`max` over the rows a filter selects,
+     * optionally grouped.
+     *
+     * Optional, and the REST route answers 501 where a driver does not
+     * implement it — an aggregate is not a thing to approximate, and an empty
+     * result set would read as "nothing matched".
+     *
+     * Any implementation **must apply the same row-level authorization as a
+     * read**. An aggregate is an efficient way to learn about rows you cannot
+     * select, and `count(*)` over a table whose policies would return nothing
+     * has to be zero.
+     */
+    aggregate?(
+        collectionPath: string,
+        options: {
+            aggregates: { fn: "count" | "sum" | "avg" | "min" | "max"; field?: string; alias: string }[];
+            groupBy?: string[];
+            filter?: FilterValues<string>;
+            logical?: LogicalCondition;
+            searchString?: string;
+            limit?: number;
+        }
+    ): Promise<Record<string, unknown>[]>;
+
     /**
      * Fetch a single flattened entity with optional relation includes.
      */

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;
@@ -801,10 +822,16 @@ export interface BackendBootstrapper {
      * enum types, and never drop, narrow or rewrite anything. This runs
      * unattended against live customer data with nobody reading a diff, so the
      * destructive half stays a deliberate migration.
+     *
+     * `driverResult` is optional: this runs before `initializeDriver`, and only
+     * the bundle path has a pre-init stand-in to pass. An adapter built by an
+     * application already holds its own connection and MUST use it when this is
+     * `undefined` — dereferencing it unconditionally works for managed tenants
+     * and breaks every app that builds its own adapter.
      */
     ensureCollectionSchema?(
         collections: unknown[],
-        driverResult: InitializedDriver,
+        driverResult?: InitializedDriver,
         log?: (message: string) => void
     ): Promise<{ applied: number }>;
 
@@ -826,7 +853,7 @@ export interface BackendBootstrapper {
      */
     ensureCollectionPolicies?(
         collections: unknown[],
-        driverResult: InitializedDriver,
+        driverResult?: InitializedDriver,
         log?: (message: string) => void
     ): Promise<{ applied: number }>;
 

package/src/types/database_adapter.ts

@@ -108,10 +108,18 @@ export interface DatabaseAdapter {
      * into a `BackendBootstrapper`: the runtime calls it through the bootstrapper
      * at boot, and a wrapper that silently omits it leaves a managed tenant
      * 500ing every data route with no create step ever having run.
+     *
+     * `driverResult` is optional because this runs BEFORE `initializeDriver`, so
+     * there may be no result to pass. The bundle path can supply a pre-init
+     * stand-in because the coordinator opened the connection itself; an app that
+     * constructed this adapter never handed the framework a connection handle,
+     * so it passes `undefined` and the adapter MUST fall back to the connection
+     * it was constructed with. An adapter that dereferences `driverResult`
+     * unconditionally works for managed tenants and breaks every self-built one.
      */
     ensureCollectionSchema?(
         collections: unknown[],
-        driverResult: InitializedDriver,
+        driverResult?: InitializedDriver,
         log?: (message: string) => void,
     ): Promise<{ applied: number }>;
 
@@ -127,7 +135,7 @@ export interface DatabaseAdapter {
      */
     ensureCollectionPolicies?(
         collections: unknown[],
-        driverResult: InitializedDriver,
+        driverResult?: InitializedDriver,
         log?: (message: string) => void,
     ): Promise<{ applied: number }>;
 
@@ -178,4 +186,25 @@ export interface DatabaseAdapterInitConfig {
      * Drivers that introspect should honour `unprotectedTables`.
      */
     baas?: { unprotectedTables?: "exclude" | "serve" };
+    /**
+     * What the runtime's boot-time table provisioning did, in this process,
+     * before this driver was initialized.
+     *
+     * A driver that checks for missing tables cannot otherwise tell "the create
+     * step ran and this table still is not here" from "no create step ran at
+     * all" — and those need opposite advice. The Postgres driver's drift warning
+     * assumed the first, told operators to redeploy with REBASE_MIGRATE_ON_BOOT
+     * unset, and pointed at driver version skew; for an app whose boot path had
+     * no provisioning step, all of that was unactionable and one investigation
+     * chased a driver that was perfectly current.
+     *
+     * Absent when the caller predates this field: treat that as "unknown" and
+     * fall back to generic guidance rather than asserting either case.
+     */
+    schemaProvisioning?: {
+        /** Whether the table-creation hook actually ran this boot. */
+        attempted: boolean;
+        /** Why it did not, when it did not — safe to print verbatim. */
+        reason?: string;
+    };
 }

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>;
 }
 
 /**