@rebasepro/types 0.11.1-canary.gfd39654 → 0.12.1-canary.g181d0fe

package/dist/controllers/client.d.ts

@@ -83,6 +83,20 @@ export interface AuthClient {
      * Manually refresh the session token
      */
     refreshSession(): Promise<RebaseSession>;
+    /**
+     * Whether a session could exist that this client has not loaded yet.
+     *
+     * `false` means the only way this client can hold a session is an explicit
+     * sign-in during this page's lifetime: it neither persists sessions nor
+     * carries an httpOnly auth cookie, so there is nothing on disk or in the
+     * browser to restore from. A caller that would otherwise probe the server
+     * — `getUser()` on mount, say — can skip it, because the answer is already
+     * known and the request can only ever fail.
+     *
+     * Optional so that alternative {@link AuthClient} implementations need not
+     * supply it; treat a missing implementation as "unknown, go ahead and ask".
+     */
+    canRestoreSession?: () => boolean;
 }
 /**
  * User record as returned by the Admin API (`GET /admin/users`, etc.).
@@ -337,6 +351,16 @@ export interface RebaseClient<DB = unknown> {
     apiKeys?: ApiKeysAPI;
     /** Base HTTP URL of the backend server */
     baseUrl?: string;
+    /**
+     * The path every API route is mounted under, appended to {@link baseUrl}.
+     *
+     * `"/api"` unless the backend was configured with a different `basePath`
+     * and the client told to match. Exposed because code that builds a URL by
+     * hand — rather than going through the client's own methods — otherwise has
+     * to guess, and guessing `/api` is wrong for exactly the projects that set
+     * the option.
+     */
+    apiPath?: string;
     /** WebSocket client for realtime subscriptions */
     ws?: RebaseWebSocket;
     /** Set the auth token for subsequent requests */
@@ -435,6 +459,16 @@ export interface RebaseBrowserClient<DB = unknown> {
     apiKeys?: ApiKeysAPI;
     /** Base HTTP URL of the backend server */
     baseUrl?: string;
+    /**
+     * The path every API route is mounted under, appended to {@link baseUrl}.
+     *
+     * `"/api"` unless the backend was configured with a different `basePath`
+     * and the client told to match. Exposed because code that builds a URL by
+     * hand — rather than going through the client's own methods — otherwise has
+     * to guess, and guessing `/api` is wrong for exactly the projects that set
+     * the option.
+     */
+    apiPath?: string;
     /** WebSocket client for realtime subscriptions */
     ws?: RebaseWebSocket;
     /** Set the auth token for subsequent requests */

package/dist/controllers/collection_registry.d.ts

@@ -6,7 +6,7 @@ import type { EntityReference } from "../types/entities";
  */
 export type CollectionRegistryController<DB = Record<string, unknown>, EC extends CollectionConfig = CollectionConfig> = {
     /**
-     * List of the mapped collections in the CMS.
+     * List of the mapped collections in the admin.
      * Each entry relates to a collection in the root database.
      * Each of the navigation entries in this field
      * generates an entry in the main menu.

package/dist/controllers/data.d.ts

@@ -108,12 +108,12 @@ export interface FindResponse<M extends Record<string, unknown> = Record<string,
     };
 }
 /**
- * Fluent query builder for the **admin CMS** — resolves to `FindResponse<M>`
+ * Fluent query builder for the **admin admin** — resolves to `FindResponse<M>`
  * (Snapshot-wrapped rows).
  *
  * @internal App developers should use {@link SDKQueryBuilderInterface}
  * (flat rows, returned by `client.data.*` / `context.data.*`). This
- * Snapshot-flavored variant backs the admin CMS internals only.
+ * Snapshot-flavored variant backs the admin admin internals only.
  *
  * @group Data
  */
@@ -129,13 +129,13 @@ export interface QueryBuilderInterface<M extends Record<string, unknown> = Recor
     listen(onUpdate: (data: FindResponse<M>) => void, onError?: (error: Error) => void): () => void;
 }
 /**
- * A single collection's CRUD accessor for the **admin CMS** — every method
+ * A single collection's CRUD accessor for the **admin admin** — every method
  * resolves to `Snapshot`-wrapped rows (`FindResponse<M>` / `Snapshot<M>`).
  *
  * @internal App developers do **not** use this. The public, symmetric surface
  * is {@link SDKCollectionClient} (flat rows), exposed as `client.data.products`
  * in the SDK and `context.data.products` in framework callbacks. This
- * Snapshot-flavored accessor backs the admin CMS view-model only.
+ * Snapshot-flavored accessor backs the admin admin view-model only.
  *
  * @group Data
  */
@@ -222,6 +222,86 @@ export interface FindResult<M extends Record<string, unknown> = Record<string, u
     /** Pagination metadata */
     meta: PaginationMeta;
 }
+/**
+ * Which column an iteration seeks on, for keyset ("seek") pagination.
+ *
+ * Either the column name on its own — sorted ascending — or the column plus an
+ * explicit direction. The column must be **unique** and must be the column the
+ * query is ordered by; see {@link PageWalkOptions.cursor}.
+ *
+ * @group Data
+ */
+export type CursorSpec<M extends Record<string, unknown> = Record<string, unknown>> = (Extract<keyof M, string>) | {
+    field: Extract<keyof M, string>;
+    direction?: "asc" | "desc";
+};
+/**
+ * How {@link SDKCollectionClient.iterate} / {@link SDKCollectionClient.findAll}
+ * walk a collection, layered on top of the normal `find()` parameters.
+ *
+ * @group Data
+ */
+export interface PageWalkOptions<M extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Rows fetched per request. Defaults to 200; values below 1 are clamped up.
+     * This is the request size, not a result cap — the iteration keeps going
+     * until the server says there is nothing left.
+     */
+    pageSize?: number;
+    /**
+     * Paginate by **seeking on a column** instead of by offset.
+     *
+     * Offset paging — the default — re-counts rows on every request, so a row
+     * inserted or deleted *while the iteration runs* shifts the window and the
+     * walk silently skips or repeats rows. Seeking is immune to that: each page
+     * asks for rows strictly after the last one seen, so concurrent writes
+     * before the cursor cannot move it.
+     *
+     * Prefer this whenever the collection has a unique, sortable column
+     * (typically its primary key). The column must be unique — a repeated value
+     * at a page boundary either skips rows or stalls, and the iterator throws
+     * rather than looping — and the query is ordered by it, so a `cursor` and a
+     * conflicting `orderBy` is an error, not a silent override.
+     *
+     * Implemented with the parameters `find()` already takes (an `orderBy` plus
+     * a `>` / `<` filter on the cursor column), so it works on every transport
+     * and needs nothing new from the server.
+     *
+     * @example
+     * for await (const job of client.data.jobs.iterate({ cursor: "id" })) { … }
+     */
+    cursor?: CursorSpec<M>;
+    /**
+     * Hard ceiling on the number of requests one walk may make, so a server
+     * that never stops saying `hasMore` cannot spin forever. Defaults to
+     * 10 000 pages; hitting it throws.
+     */
+    maxPages?: number;
+}
+/**
+ * Parameters accepted by {@link SDKCollectionClient.iterate} — everything
+ * `find()` takes except the window itself (`limit`, `offset`, `page`), which
+ * the iterator owns, plus the walk options.
+ *
+ * @group Data
+ */
+export type IterateParams<M extends Record<string, unknown> = Record<string, unknown>> = Omit<FindParams<M>, "limit" | "offset" | "page"> & PageWalkOptions<M>;
+/**
+ * Parameters accepted by {@link SDKCollectionClient.findAll}: the iteration
+ * parameters plus the ceiling that keeps a whole collection from being pulled
+ * into memory unnoticed.
+ *
+ * @group Data
+ */
+export type FindAllParams<M extends Record<string, unknown> = Record<string, unknown>> = IterateParams<M> & {
+    /**
+     * Most rows to materialise. Defaults to 10 000. Exceeding it **throws**
+     * — a truncated array returned as if it were the whole answer is the
+     * kind of quiet wrong that shows up months later in a report. Pass
+     * `Infinity` to opt out deliberately, or use `iterate()` to stream.
+     */
+    maxRows?: number;
+};
 /**
  * Fluent Query Builder Interface for the SDK client.
  * Returns `FindResult<M>` (flat rows) instead of `FindResponse<M>` (Entity-wrapped).
@@ -244,7 +324,7 @@ export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Re
  * SDK collection client — returns flat rows, no Entity wrapper.
  *
  * This is the public API surface for app developers using
- * `createRebaseClient()`. CMS internals use `CollectionAccessor` instead.
+ * `createRebaseClient()`. admin internals use `CollectionAccessor` instead.
  *
  * Type parameters:
  * - `M` — the **Row** shape returned by reads (`find`, `findById`, `listen`).
@@ -290,6 +370,65 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * Find multiple records with optional filtering, pagination, and sorting.
      */
     find(params?: FindParams<M>): Promise<FindResult<M>>;
+    /**
+     * Walk every record matching a query, one row at a time, fetching pages as
+     * the consumer consumes them.
+     *
+     * This is the pagination primitive: `find()` returns one window, `iterate()`
+     * returns all of them without the caller hand-rolling the
+     * `limit` / `offset += ` / "am I done yet" loop. Nothing is buffered — rows
+     * are yielded as each page arrives, so a million-row walk costs one page of
+     * memory. `break` stops the walk and no further requests are made.
+     *
+     * Termination is driven by the server's `meta.hasMore`, never by comparing
+     * a page's length against the requested limit — a final page that happens
+     * to be exactly full is indistinguishable that way, and a walk that stops
+     * there drops rows. An empty page also ends the walk, and
+     * {@link PageWalkOptions.maxPages} bounds a server that never stops saying
+     * there is more.
+     *
+     * ## Consistency
+     *
+     * By default this pages by **offset**, which is only as stable as the table
+     * is still: a row inserted or deleted ahead of the cursor between two
+     * requests shifts every later window, so the walk can skip a row or hand
+     * back the same one twice. That is inherent to offset paging, not a bug
+     * here. On a collection with a unique sortable column, pass
+     * {@link PageWalkOptions.cursor} to seek on it instead — the walk then
+     * asks for rows strictly after the last one it saw, which concurrent writes
+     * cannot perturb.
+     *
+     * @example
+     * for await (const job of client.data.jobs.iterate({
+     *     where: { status: ["==", "queued"] },
+     *     cursor: "id",
+     *     pageSize: 500
+     * })) {
+     *     await handle(job);
+     * }
+     */
+    iterate(params?: IterateParams<M>): AsyncIterableIterator<M>;
+    /**
+     * {@link iterate}, collected into an array.
+     *
+     * Convenient when the result is known to be small and awkward to stream.
+     * Because "known to be small" is an assumption and not a fact, the result is
+     * capped — 10 000 rows by default — and going over the cap **throws**
+     * rather than returning a short array that reads like a complete one. Raise
+     * {@link FindAllParams.maxRows} when the data really is bigger, or switch to
+     * `iterate()` and stream it.
+     *
+     * The offset-drift caveat on {@link iterate} applies here too.
+     *
+     * @throws When more rows match than `maxRows` allows.
+     *
+     * @example
+     * const overdue = await client.data.invoices.findAll({
+     *     where: { due_at: ["<", today] },
+     *     cursor: "id"
+     * });
+     */
+    findAll(params?: FindAllParams<M>): Promise<M[]>;
     /**
      * Find a single record by its ID.
      */
@@ -367,16 +506,16 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
     include(...relations: string[]): SDKQueryBuilderInterface<M>;
 }
 /**
- * The unified data access object for the **admin CMS** (Entity-shaped).
+ * The unified data access object for the **admin admin** (Entity-shaped).
  *
  * Access collections as dynamic properties: `data.products.find(...)`. Each
  * accessor returns `Entity`-wrapped records (`{ id, path, values }`) — the
- * view-model the CMS renders. This is what `useData()` / the admin
+ * view-model the admin renders. This is what `useData()` / the admin
  * `RebaseContext.data` are backed by.
  *
  * @internal App developers do **not** use this — they use
  * {@link RebaseSdkData} (flat rows), which is what the SDK client and backend
- * `context.data` expose. This Entity-shaped map backs the admin CMS only.
+ * `context.data` expose. This Entity-shaped map backs the admin admin only.
  *
  * @group Data
  */
@@ -415,7 +554,7 @@ export type RebaseData<DB = unknown> = {
  *
  * Every accessor returns flat rows (the table's columns) via
  * {@link SDKCollectionClient} — access fields directly (`row.title`), never
- * `row.values.title`. The admin CMS uses {@link RebaseData} (Entity) instead.
+ * `row.values.title`. The admin uses {@link RebaseData} (Entity) instead.
  *
  * @example
  * // Frontend SDK