@rebasepro/types 0.17.3 → 0.18.1

package/README.md

@@ -8,6 +8,10 @@ Shared TypeScript type definitions and interfaces for the Rebase ecosystem.
 pnpm add @rebasepro/types
 ```
 
+ESM-only: `"type": "module"` with no CommonJS build, so it is loaded with
+`import`. `require()` of it resolves only on Node 22.12+, which supports
+`require(esm)`.
+
 ## What This Package Does
 
 Provides the canonical type definitions used across all Rebase packages — both client-side and server-side. This is a **types-only** package with no runtime dependencies. Every other `@rebasepro/*` package depends on it.

package/dist/call_context.d.ts

@@ -13,6 +13,26 @@ import type { User } from "./users/index.js";
  * backend process. Keeping them in one type meant every backend module that
  * touched a callback signature transitively named the admin UI.
  *
+ * ### When the callback runs
+ *
+ * Server-side, **every** callback around a write — `beforeSave`, the SQL,
+ * `afterSave`; `beforeDelete`, the delete, `afterDelete` — runs inside the one
+ * transaction opened for that request, and each is awaited. There is no
+ * after-commit tier: `afterSave` and `afterDelete` run *before* the commit, so a
+ * throw in either rolls the write back and the caller is answered
+ * `400 CALLBACK_REJECTED` with `details.stage` naming the hook.
+ *
+ * Two consequences worth designing around:
+ *
+ * - A callback holds the transaction open while it runs. Slow work there is a
+ *   lock held and a pooled connection tied up. Anything that talks to a third
+ *   party belongs on the job queue, not in the body.
+ * - Work that must survive the write being undone does not belong here at all —
+ *   by construction it is not part of the write.
+ *
+ * A request-scoped `afterRead` is narrower still: its transaction is
+ * `READ ONLY`, so a write attempted from one fails with SQLSTATE `25006`.
+ *
  * @group Hooks and utilities
  */
 export type RebaseCallContext<USER extends User = User> = {

package/dist/controllers/client.d.ts

@@ -1,4 +1,5 @@
 import type { User } from "../users/index.js";
+import type { ResourceRef } from "../types/resources.js";
 import type { RebaseSdkData } from "./data.js";
 import type { EmailService } from "./email.js";
 import type { StorageSource } from "./storage.js";
@@ -337,7 +338,23 @@ export interface RebaseClient<DB = unknown> {
      * routed to the matching `StorageController`. Used to lazily wire
      * `transport: "server"` sources on the frontend.
      */
-    createStorageSource?(storageId: string): StorageSource;
+    createStorageSource?(storageId: ResourceRef): StorageSource;
+    /**
+     * The storage source a bucket handle names, ready to use.
+     *
+     * ```ts
+     * import { media } from "../../config/resources";
+     * await rebase.bucket(media).putObject({ key, file });
+     * ```
+     *
+     * Named after the constructor: `bucket("media")` declares it, and
+     * `rebase.bucket(media)` reaches it — the same name, spelled once. A string
+     * key is accepted for callers that only have one. Throws on a source the
+     * backend did not register, naming the ones it did, rather than silently
+     * serving the default — the failure that used to look like an upload that
+     * worked.
+     */
+    bucket?(source: ResourceRef): StorageSource;
     /**
      * Discover the storage sources declared on the backend via
      * `GET /api/storage/sources`. Server-transport sources are auto-registered
@@ -435,8 +452,14 @@ export interface RebaseServerClient<DB = unknown> extends Omit<RebaseClient<DB>,
      */
     dataAsAdmin: RebaseSdkData<DB>;
     /**
-     * Server-side email service. Always present server-side (a no-op sender is
-     * wired when SMTP is not configured).
+     * Server-side email service. Always present — including on a backend that
+     * configured no mail at all, where `send()` throws a message naming what to
+     * set rather than the property being `undefined`.
+     *
+     * It is not a no-op sender. A no-op would swallow the reset mail a user is
+     * waiting for and report success, and nothing downstream could tell that from
+     * delivery. Ask {@link EmailService.isConfigured} before sending if the call
+     * site can carry on without mail.
      */
     email: EmailService;
     /**
@@ -458,10 +481,19 @@ export interface RebaseServerClient<DB = unknown> extends Omit<RebaseClient<DB>,
      * than discovering it at the call.
      */
     sql(query: string, options?: {
-        database?: string;
+        database?: ResourceRef;
         role?: string;
         params?: unknown[];
     }): Promise<Record<string, unknown>[]>;
+    /**
+     * The storage source a bucket handle names. Always present server-side.
+     *
+     * Always, for the same reason {@link RebaseServerClient.email} is: a
+     * backend with no storage configured at all answers with a refusal naming
+     * what to set, rather than with `undefined` and a `is not a function`
+     * three frames from the cause. See {@link RebaseClient.bucket}.
+     */
+    bucket(source: ResourceRef): StorageSource;
 }
 /**
  * Client-side registry for managing multiple storage sources.

package/dist/controllers/data.d.ts

@@ -1,7 +1,7 @@
 import type { VectorSearchParams } from "./data_driver.js";
 import type { ComputedSortField, SearchMatch } from "../types/search.js";
 import { Entity, EntityValues } from "../types/entities.js";
-import { WhereFilterOp, FieldPath, FilterValues, OrderBySpec } from "../types/filter-operators.js";
+import { WhereFilterOp, FieldPath, NonColumnFieldPath, FilterValues, OrderBySpec, RelationAggregateSort } from "../types/filter-operators.js";
 /**
  * The element type of an array column, and the column's own type otherwise.
  *
@@ -504,8 +504,27 @@ export type FindAllParams<M extends Record<string, unknown> = Record<string, unk
  */
 export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Record<string, unknown>> {
     where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): this;
+    /**
+     * Filter on a relation path (`author.name`) or a JSON path
+     * (`metadata->>tier`).
+     *
+     * A separate overload because the value cannot be typed: neither addresses
+     * a column of `M`, so there is nothing in a generated row type to check
+     * against — the driver resolves the path and refuses what it cannot. The
+     * key is still constrained to a *path*, so a mistyped column name does not
+     * fall through to here and lose its check.
+     *
+     * `find({ where })` has accepted both all along ({@link FieldPath}); the
+     * builder did not, so the documented relation-path filters were compile
+     * errors on a typed client.
+     */
+    where(column: NonColumnFieldPath, operator: WhereFilterOp, value: unknown): this;
     where(logicalCondition: LogicalCondition): this;
-    orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): this;
+    /**
+     * Sort by a column, a relation or JSON path, `_score`, or an aggregate over
+     * a to-many relation — the same key set {@link FindParams.orderBy} takes.
+     */
+    orderBy(column: FieldPath<M> | ComputedSortField | RelationAggregateSort, direction?: "asc" | "desc"): this;
     limit(count: number): this;
     offset(count: number): this;
     search(searchString: string, options?: {
@@ -526,6 +545,24 @@ export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Re
     }): this;
     include(...relations: string[]): this;
     find(): Promise<FindResult<M>>;
+    /**
+     * Page through everything this query matches, one row at a time.
+     *
+     * The same walker {@link SDKCollectionClient.iterate} uses, so the ceiling
+     * on `limit` is not a ceiling on what a query can read. `.limit()` set on
+     * the builder becomes the **page size** here, not a total.
+     */
+    iterate(options?: PageWalkOptions<M>): AsyncIterableIterator<M>;
+    /**
+     * Collect everything this query matches into one array.
+     *
+     * {@link SDKCollectionClient.findAll}'s `maxRows` guard applies: an
+     * unbounded collect is a memory hazard, so it stops and says so rather than
+     * growing until the process dies.
+     */
+    findAll(options?: PageWalkOptions<M> & {
+        maxRows?: number;
+    }): Promise<M[]>;
     count(): Promise<number>;
     listen(onUpdate: (data: FindResult<M>) => void, onError?: (error: Error) => void): () => void;
 }
@@ -588,6 +625,26 @@ export interface WriteOptions {
 export interface SDKCollectionClient<M extends Record<string, unknown> = Record<string, unknown>, I = Partial<M>, U = Partial<M>> {
     /**
      * Find multiple records with optional filtering, pagination, and sorting.
+     *
+     * ## What a list method returns
+     *
+     * Two shapes, and one rule that tells them apart: **a window is wrapped, a
+     * whole answer is not.**
+     *
+     * - `find()` and `listen()` return {@link FindResult} — `{ data, meta }` —
+     *   because they hand back *one page*. `meta.total` and `meta.hasMore` are
+     *   the caller's only way to know there is more, so a bare array would lose
+     *   the answer to the question the call raises.
+     * - `findAll()`, `createMany()` and `updateMany()` return a plain `M[]`,
+     *   because there is nothing left over to report: the walk finished, or the
+     *   batch is exactly the rows that were written. A `meta` there would be
+     *   `{ total: rows.length, hasMore: false }`, which says nothing.
+     * - `iterate()` yields rows one at a time and never materialises a list at
+     *   all.
+     *
+     * So `data` is not a wrapper the SDK sometimes adds and sometimes forgets —
+     * it is where the pagination metadata lives, and it is present exactly when
+     * there is some.
      */
     find(params?: FindParams<M>): Promise<FindResult<M>>;
     /**
@@ -653,6 +710,38 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * Find a single record by its ID.
      */
     findById(id: string | number): Promise<M | undefined>;
+    /**
+     * Read one record by its ID, or throw if it is not there.
+     *
+     * The counterpart to {@link findById}, and the one most reads want. A row
+     * fetched by an id that came from a link, a route parameter or another row
+     * is expected to exist; when it does not, that is the error case, not a
+     * value to thread through the rest of the function.
+     *
+     * `findById` returns `M | undefined`, so every caller had to prove the row
+     * existed before touching a field:
+     *
+     * ```ts
+     * const post = await rebase.data.posts.findById(id);
+     * post.title;                        // TS18048: 'post' is possibly 'undefined'
+     * const ok = (await rebase.data.posts.findById(id))!.title;   // the `!` everyone reaches for
+     * ```
+     *
+     * With `get`, the absent case is an exception with a code you can branch on,
+     * and the happy path is typed as present:
+     *
+     * ```ts
+     * const post = await rebase.data.posts.get(id);   // M, not M | undefined
+     * ```
+     *
+     * Same split as Prisma's `findUnique` / `findUniqueOrThrow`: two contracts,
+     * both wanted, named so the choice is visible at the call site.
+     *
+     * @throws {RebaseApiError} `NOT_FOUND` (status 404) when no such row exists,
+     *   or is visible to the caller — row-level security makes a row the caller
+     *   may not read indistinguishable from one that is not there, deliberately.
+     */
+    get(id: string | number): Promise<M>;
     /**
      * Create a new record.
      * @param data The record data to create (the collection's `Insert` shape).
@@ -702,10 +791,18 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
     /**
      * Update an existing record by ID.
      * @param data The fields to update (the collection's `Update` shape).
+     * @param options Per-request write options — notably `idempotencyKey`.
      * @returns The updated row.
      * @throws {RebaseApiError} with status 404 when the record does not exist.
+     *
+     * `create`, `createMany`, `updateMany`, `delete` and `deleteMany` all took
+     * {@link WriteOptions}; this one did not, so the single-row update was the
+     * one write on the surface that could not be made idempotent. A client that
+     * never sees the response retries, and without a key the server cannot tell
+     * that retry from a second deliberate edit — which on a `PATCH` that
+     * increments or appends is a second edit applied.
      */
-    update(id: string | number, data: U): Promise<M>;
+    update(id: string | number, data: U, options?: WriteOptions): Promise<M>;
     /**
      * Update many records in a single request and a single transaction.
      *
@@ -788,20 +885,33 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * does not call back. `listen` does none of that; it forwards what the
      * socket sends.
      *
-     * Optional because it is only present when realtime is enabled. `observe()`
-     * is not — it degrades to a single fetch — which is the other reason to
-     * reach for it instead.
+     * Always present. A client that cannot subscribe — one built with
+     * `realtime: false`, or on a driver with no `listenCollection` — installs a
+     * stub that throws a `RebaseClientError` naming the configuration that
+     * would make it work. It used to be optional, which made every call site
+     * either write `listen!(…)` or a null check the type system could not tell
+     * apart from a real capability question; the answer to *that* question is
+     * {@link isUnsupported}, and the answer for ordinary code is to just call
+     * it.
+     *
+     * `observe()` degrades to a single fetch instead of throwing, which is the
+     * other reason to reach for it instead.
      */
-    listen?(params: FindParams<M> | undefined, onUpdate: (response: FindResult<M>) => void, onError?: (error: Error) => void): () => void;
+    listen(params: FindParams<M> | undefined, onUpdate: (response: FindResult<M>) => void, onError?: (error: Error) => void): () => void;
     /** {@link listen} for a single row. Prefer `observeById()`. */
-    listenById?(id: string | number, onUpdate: (row: M | undefined) => void, onError?: (error: Error) => void): () => void;
+    listenById(id: string | number, onUpdate: (row: M | undefined) => void, onError?: (error: Error) => void): () => void;
     /**
      * Count the number of records matching the given filter.
+     *
+     * Always present; see {@link listen} for what a transport that cannot serve
+     * it does instead.
      */
-    count?(params?: FindParams<M>): Promise<number>;
+    count(params?: FindParams<M>): Promise<number>;
     where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): SDKQueryBuilderInterface<M>;
+    /** A relation path (`author.name`) or a JSON path (`metadata->>tier`). */
+    where(column: NonColumnFieldPath, operator: WhereFilterOp, value: unknown): SDKQueryBuilderInterface<M>;
     where(logicalCondition: LogicalCondition): SDKQueryBuilderInterface<M>;
-    orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): SDKQueryBuilderInterface<M>;
+    orderBy(column: FieldPath<M> | ComputedSortField | RelationAggregateSort, direction?: "asc" | "desc"): SDKQueryBuilderInterface<M>;
     limit(count: number): SDKQueryBuilderInterface<M>;
     offset(count: number): SDKQueryBuilderInterface<M>;
     search(searchString: string, options?: {

package/dist/errors.d.ts

@@ -23,7 +23,7 @@
  *
  * @group Errors
  */
-export type RebaseErrorCode = "BAD_REQUEST" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "INTERNAL_ERROR" | "SERVICE_UNAVAILABLE" | "DB_PERMISSION_DENIED" | "SCHEMA_DRIFT" | (string & {});
+export type RebaseErrorCode = "BAD_REQUEST" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "INTERNAL_ERROR" | "SERVICE_UNAVAILABLE" | "NETWORK_ERROR" | "OFFLINE" | "DB_PERMISSION_DENIED" | "SCHEMA_DRIFT" | (string & {});
 /**
  * Structured initializer for {@link RebaseApiError}.
  *
@@ -32,14 +32,41 @@ export type RebaseErrorCode = "BAD_REQUEST" | "UNAUTHORIZED" | "FORBIDDEN" | "NO
 export interface RebaseErrorInit {
     /**
      * HTTP status code, when the error originated from an HTTP response.
-     * Left `undefined` for realtime/WebSocket, network, and client-side
-     * logic errors that have no HTTP status.
+     *
+     * Three states, and they mean different things:
+     *
+     * - a real status — the server answered, and this is what it said;
+     * - **`0`** — the request never reached a server: DNS, a refused
+     *   connection, CORS, an abort. `XMLHttpRequest` has always spelled that
+     *   `0`, and a fabricated 5xx would be indistinguishable from one the
+     *   server actually sent. The original failure is on `cause`;
+     * - `undefined` — nothing was sent at all: a realtime/WebSocket failure,
+     *   or a client-side logic error raised before any request.
      */
     status?: number;
     /** Stable, machine-readable error code. See {@link RebaseErrorCode}. */
     code?: RebaseErrorCode;
     /** Structured error payload returned by the server, when present. */
     details?: unknown;
+    /**
+     * The server's correlation id for the request that failed, when it sent
+     * one — the `requestId` in the error envelope, which also comes back on the
+     * `X-Request-ID` header.
+     *
+     * The envelope has carried it for a while; the client dropped it on the
+     * floor, so a bug report from an app could never quote the one string that
+     * finds the server-side line.
+     */
+    requestId?: string;
+    /**
+     * Seconds to wait before retrying, from the response's `Retry-After`
+     * header. Present on a 429 and on some 503s.
+     *
+     * Also dropped. The offline queue's own backoff therefore ignored a server
+     * that had said exactly how long to wait — the one number that turns a
+     * retry storm into a queue that drains.
+     */
+    retryAfterSeconds?: number;
     /** The underlying error this one wraps, if any. */
     cause?: unknown;
 }
@@ -74,6 +101,10 @@ export declare class RebaseApiError extends Error {
     readonly code?: RebaseErrorCode;
     /** Structured error payload from the server, when present. */
     readonly details?: unknown;
+    /** See {@link RebaseErrorInit.requestId}. Quote it in a bug report. */
+    readonly requestId?: string;
+    /** See {@link RebaseErrorInit.retryAfterSeconds}. */
+    readonly retryAfterSeconds?: number;
     constructor(message: string, init?: RebaseErrorInit);
 }
 /**
@@ -86,5 +117,53 @@ export declare class RebaseApiError extends Error {
  * @group Errors
  */
 export declare class RebaseClientError extends RebaseApiError {
-    constructor(message: string);
+    /**
+     * `init` is the same one {@link RebaseApiError} takes, and it is what makes
+     * `code` reachable at all.
+     *
+     * The constructor used to accept a message and nothing else, so every
+     * client-side failure — an undefined filter value, an unknown accessor,
+     * `listen()` on a client built with `realtime: false`, a function name with
+     * a `/` in it, `refreshSession()` while signed out — arrived with `code ===
+     * undefined`. The documented `switch (e.code)` in this file's own example
+     * fell to `default: throw e` for all of them, and the only client-side error
+     * that *did* carry a code was `OFFLINE`, because that one path minted a
+     * `RebaseApiError` instead.
+     */
+    constructor(message: string, init?: RebaseErrorInit);
 }
+/**
+ * Build the stub a client installs for a contract method it cannot serve.
+ *
+ * `listen`, `listenById` and `count` are part of `SDKCollectionClient`, not
+ * optional extras — a caller should be able to write
+ * `client.data.posts.count()` without asking first, and a transport that cannot
+ * serve it should answer with a sentence naming the configuration that would,
+ * rather than with `undefined is not a function` at the call site. Where the
+ * transport genuinely cannot (a client built with `realtime: false`, a driver
+ * with no `listenCollection`), it installs one of these instead of omitting the
+ * method.
+ *
+ * @param message What to tell the caller, naming the fix.
+ * @group Errors
+ */
+export declare function unsupportedMethod<F>(message: string): F;
+/**
+ * Can this method actually do anything?
+ *
+ * `true` for a stub from {@link unsupportedMethod} **and** for a method that is
+ * simply not there — a partial client, a hand-built test double, an
+ * implementation written against an older shape of the interface. Both mean the
+ * same thing to a caller, so both answer the same way, and an adapter that
+ * checks this cannot be caught out by either.
+ *
+ * Ordinary code does not need it: calling the method and letting it throw is
+ * the normal path. Adapters do — the admin panel chooses between subscribing
+ * and a one-shot `find()` by asking whether the client can listen, and a UI
+ * that subscribes into a throw is worse than one that polls. This is the
+ * question `if (accessor.listen)` used to be asking, made explicit now that the
+ * method is always there to call.
+ *
+ * @group Errors
+ */
+export declare function isUnsupported(method: unknown): boolean;