@rebasepro/client 0.19.1 → 0.19.2-canary.g09316f6

package/dist/offline-query.d.ts

@@ -60,36 +60,6 @@ export declare function resolvePagination(params?: FindParams): {
     limit: number;
     offset: number;
 };
-/**
- * Can a locally evaluated answer to `params` be trusted to match the server's,
- * assuming the cache holds every row of the collection?
- *
- * `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 declare function isExactlyEvaluable(params?: FindParams): boolean;
 /**
  * Would sorting `rows` locally reproduce the order the server would have sent?

package/dist/sdk_query_builder.d.ts

@@ -1,4 +1,4 @@
-import { FindResult, LogicalCondition, PageWalkOptions, RelationAggregateSort, SDKCollectionClient, SDKQueryBuilderInterface, WhereFilterOp, WhereValueFor, type ComputedSortField, type FieldPath, type NonColumnFieldPath } from "@rebasepro/types";
+import { FindResult, LogicalCondition, PageWalkOptions, RelationAggregateSort, SDKCollectionClient, SDKQueryBuilderInterface, WhereFilterOp, WhereValueFor, type AggregateParams, type AggregateRow, type ComputedSortField, type FieldPath, type IncludeSpec, type NonColumnFieldPath, type NullsPlacement } from "@rebasepro/types";
 /**
  * SDK Query Builder — returns flat rows (`FindResult<M>`) instead of
  * Entity-wrapped results (`FindResponse<M>`).
@@ -33,7 +33,14 @@ export declare class SDKQueryBuilder<M extends Record<string, unknown> = Record<
      * `.orderBy("roles").orderBy("created_at", "desc")` sorts by role and
      * shows the newest first within each one.
      */
-    orderBy(column: FieldPath<M> | ComputedSortField | RelationAggregateSort, direction?: "asc" | "desc"): this;
+    orderBy(column: FieldPath<M> | ComputedSortField | RelationAggregateSort, direction?: "asc" | "desc", 
+    /**
+     * Where this key's NULLs go. Omitted means the direction's own
+     * convention — last ascending, first descending — which is what put
+     * every undated row at the top of a `.orderBy("published_at", "desc")`
+     * list, ahead of everything real.
+     */
+    nulls?: NullsPlacement): this;
     /**
      * Limit the number of results returned.
      */
@@ -89,18 +96,84 @@ export declare class SDKQueryBuilder<M extends Record<string, unknown> = Record<
         threshold?: number;
     }): this;
     /**
-     * Include related entities in the response.
-     * Relations will be populated with full data instead of just IDs.
+     * Load related rows into the response, in place of their foreign keys.
      *
-     * @param relations - Relation names to include, or "*" for all.
-     * @example
-     * client.data.posts.include("tags", "author").find()
+     * Three spellings, all the same request:
+     *
+     * ```ts
+     * client.data.posts.include("tags", "author")            // names
+     * client.data.posts.include("comments.author")           // a dotted path
+     * client.data.posts.include({                            // parametrised
+     *     comments: {
+     *         limit: 5,
+     *         where: { published: ["==", true] },
+     *         orderBy: ["created_at", "desc"],
+     *         include: { author: true }
+     *     }
+     * })
+     * ```
+     *
+     * Up to three hops deep, and `"*"` still loads every relation one hop
+     * deep. A name that is not a relation of the collection is a 400
+     * `UNKNOWN_RELATION` — it used to be ignored, which answers 200 with the
+     * field missing and reads exactly like a row that has no related row.
+     *
+     * Repeated calls **merge**: `.include("author").include("tags")` asks for
+     * both. Assigning here — which is what it used to do — meant the second
+     * call silently discarded the first.
+     */
+    include(...relations: (string | IncludeSpec)[]): this;
+    /**
+     * Return only these columns.
+     *
+     * A projection at the database, not a trim of the response: a query that
+     * needs two fields of a wide row reads two columns. The primary key always
+     * comes back regardless — a row that cannot be addressed cannot be
+     * updated, deleted or paged past — and `excludeFromApi` columns stay
+     * hidden whether or not they are named.
+     */
+    fields(...columns: (FieldPath<M> | string)[]): this;
+    /**
+     * Collapse rows that are identical over the columns being returned.
+     *
+     * Only meaningful alongside {@link fields}: the primary key is always in
+     * the projection, so without narrowing it every row is already distinct.
+     *
+     * ```ts
+     * client.data.posts.fields("status").distinct().find()   // the statuses in use
+     * ```
+     */
+    distinct(enabled?: boolean): this;
+    /**
+     * Continue after a previous page's `meta.nextCursor` — keyset paging.
+     *
+     * Unlike `offset`, a row inserted or deleted before the cursor cannot
+     * shift the window, so a walk neither repeats nor skips rows. Keep
+     * `orderBy` identical across pages: a cursor only continues the listing it
+     * came from, and one used against a different sort is refused rather than
+     * seeked in an order nobody asked for.
      */
-    include(...relations: string[]): this;
+    after(cursor: string): this;
     /**
      * Execute the find query and return the results as flat rows.
      */
     find(): Promise<FindResult<M>>;
+    /**
+     * Aggregate the rows this query matches instead of returning them.
+     *
+     * The builder's `where`/`logical`/`search` narrow which rows are
+     * aggregated; its `orderBy`, `include` and window do not apply — an
+     * aggregate has no rows to sort, no relations to load and no page to
+     * continue.
+     *
+     * ```ts
+     * await client.data.orders
+     *     .where("created_at", ">=", startOfMonth)
+     *     .aggregate({ select: [{ fn: "sum", field: "total" }], groupBy: ["status"] });
+     * // [{ status: "paid", sum_total: 41822.5 }, …]
+     * ```
+     */
+    aggregate(params: Omit<AggregateParams<M>, "where" | "logical" | "searchString">): Promise<AggregateRow[]>;
     /**
      * Page through everything this query matches, one row at a time.
      *

package/dist/transport.d.ts

@@ -1,4 +1,4 @@
-import { FindParams as TypesFindParams, FindResponse as TypesFindResponse } from "@rebasepro/types";
+import { AggregateParams, FindParams as TypesFindParams, FindResponse as TypesFindResponse } from "@rebasepro/types";
 export { RebaseApiError } from "@rebasepro/types";
 export type { RebaseErrorInit } from "@rebasepro/types";
 export interface RebaseClientConfig {
@@ -127,8 +127,43 @@ export declare const ANONYMOUS_SERVER_CLIENT_WARNING: string;
 export type FindParams<M extends Record<string, unknown> = Record<string, unknown>> = TypesFindParams<M>;
 export type FindResponse<T> = TypesFindResponse<T extends Record<string, unknown> ? T : Record<string, unknown>>;
 export declare function buildQueryString(params?: FindParams): string;
+/**
+ * The query string for `GET /<collection>/aggregate`.
+ *
+ * `?select=sum(total),count()` is SQL's spelling, because whoever writes an
+ * aggregate is thinking in SQL and any other spelling has to be learned first —
+ * and because it is what the route already parses. The filters are serialised
+ * by exactly the same code a `find()` uses, so "revenue by status, this month"
+ * narrows the same rows whichever call is asking.
+ *
+ * `orderBy`, `include` and the page are deliberately not here: an aggregate has
+ * no rows to sort, no relations to load and no page to continue. `limit` is,
+ * and bounds the number of *groups*.
+ */
+export declare function buildAggregateQueryString(params: AggregateParams): string;
+/**
+ * Response metadata a caller can ask for, filled in by `request`.
+ *
+ * An out-parameter rather than a second return value, because every one of the
+ * fifty-odd call sites wants the body and nothing else, and changing the return
+ * shape would mean rewriting all of them to reach past a wrapper. It is also
+ * why this is a third *optional* parameter: a `Transport` stub in a test that
+ * ignores it is still a valid `Transport`.
+ *
+ * Only `ETag` for now, and only because a row's version is not part of the row.
+ * It cannot be: adding it as a column would put it in the generated `Row` type,
+ * in every `find()` result, in the offline cache and in what a caller sends
+ * back on the next write — a field the server would then have to strip. The
+ * header is where HTTP puts it, so the header is where this reads it.
+ */
+export interface ResponseMeta {
+    /** The `ETag` header, when the response carried one. */
+    etag?: string;
+    /** The HTTP status, for a caller that has to tell 200 from 204. */
+    status?: number;
+}
 export interface Transport {
-    request: <T = unknown>(path: string, init?: RequestInit) => Promise<T>;
+    request: <T = unknown>(path: string, init?: RequestInit, meta?: ResponseMeta) => Promise<T>;
     setToken: (newToken: string | null) => void;
     setAuthTokenGetter: (getter: () => Promise<string | null>) => void;
     setOnUnauthorized: (handler: () => Promise<boolean>) => void;

package/dist/websocket.d.ts

@@ -1,4 +1,4 @@
-import { DeleteProps, CollectionConfig, FetchCollectionProps, FetchOneProps, SaveProps, TableMetadata, BranchInfo } from "@rebasepro/types";
+import { DeleteProps, CollectionConfig, FetchCollectionProps, ListenCollectionProps, FetchOneProps, SaveProps, CollectionUpdateMeta, TableMetadata, BranchInfo } from "@rebasepro/types";
 export interface RebaseWebSocketConfig {
     websocketUrl: string;
     /** Optional auth token getter for WebSocket authentication */
@@ -171,7 +171,7 @@ export declare class RebaseWebSocketClient {
      * haven't actually changed.
      */
     private mergeRows;
-    listenCollection<M extends Record<string, unknown>>(props: FetchCollectionProps<M>, onUpdate: (rows: Record<string, unknown>[]) => void, onError?: (error: Error) => void): () => void;
+    listenCollection<M extends Record<string, unknown>>(props: Omit<ListenCollectionProps<M>, "onUpdate" | "onError">, onUpdate: (rows: Record<string, unknown>[], meta?: CollectionUpdateMeta) => void, onError?: (error: Error) => void): () => void;
     listenOne<M extends Record<string, unknown>>(props: FetchOneProps<M>, onUpdate: (row: Record<string, unknown> | null) => void, onError?: (error: Error) => void): () => void;
     /**
      * Send a `subscribe_collection` for an already-registered subscription and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebasepro/client",
-  "version": "0.19.1",
+  "version": "0.19.2-canary.g09316f6",
   "description": "HTTP SDK client for the Rebase custom backend",
   "keywords": [
     "rebase",
@@ -41,9 +41,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@rebasepro/common": "0.19.1",
-    "@rebasepro/utils": "0.19.1",
-    "@rebasepro/types": "0.19.1"
+    "@rebasepro/common": "0.19.2-canary.g09316f6",
+    "@rebasepro/types": "0.19.2-canary.g09316f6",
+    "@rebasepro/utils": "0.19.2-canary.g09316f6"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",