@rebasepro/types 0.13.0 → 0.13.1-canary.g06dbe5b

package/src/controllers/data_driver.ts

@@ -1,3 +1,4 @@
+import { RebaseApiError } from "../errors";
 import type { CollectionRegistryController } from "./collection_registry";
 import type { EntityStatus, EntityValues } from "../types/entities";
 import type { CollectionConfig, FilterValues } from "../types/collections";
@@ -52,12 +53,23 @@ export interface VectorSearchParams {
 // server-side callers build fetch options directly and are intentionally NOT
 // bounded here (migrations, admin exports, and CDC refetches may need the full
 // set).
+//
+// A limit the platform will not serve is REFUSED, not quietly shrunk. Clamping
+// answers a request for 100 000 rows with 1 000 of them, and a short page is
+// indistinguishable from "that is all the data there is" — which is how a CSV
+// export shipped 50 rows of a 100 000-row collection under a filename that read
+// like the whole thing. `meta.total`/`meta.hasMore` make truncation *detectable*
+// on the REST list response, but only for a caller who thinks to compare what it
+// asked for against what it got, and the WebSocket `collection_update` frame
+// carries neither — so signalling cannot be the answer on every surface and
+// rejecting is. An ABSENT limit still defaults: naming no window is not the same
+// as asking for one that cannot be served.
 
 /** Rows returned for a plain / text-search list read when the client sends no `limit`. */
 export const DEFAULT_LIST_LIMIT = 50;
 /** Rows returned for a vector-search list read when the client sends no `limit`. */
 export const DEFAULT_VECTOR_LIST_LIMIT = 10;
-/** Hard ceiling clamped onto any client-supplied `limit`, on every surface. */
+/** Largest `limit` a client may ask for on any surface. Above it, the read is refused. */
 export const MAX_LIST_LIMIT = 1000;
 
 /** Overridable bounds for {@link resolveClientListLimit}. */
@@ -66,20 +78,46 @@ export interface ListLimitBounds {
     defaultLimit?: number;
     /** Default page size for vector-search reads. */
     vectorDefaultLimit?: number;
-    /** Upper bound clamped onto any client-supplied limit. */
+    /** Largest limit a client may ask for. A larger one is rejected, not clamped. */
     maxLimit?: number;
 }
 
+/**
+ * Thrown by {@link resolveClientListLimit} for a `limit` the platform will not
+ * serve. Carries an HTTP status so an ingress that speaks HTTP can forward it
+ * verbatim, and `maxLimit` so one can be built without re-deriving the ceiling.
+ *
+ * @group Errors
+ */
+export class ListLimitError extends RebaseApiError {
+    /** The ceiling that was exceeded — what the caller should page by instead. */
+    readonly maxLimit: number;
+
+    constructor(message: string, maxLimit: number) {
+        super(message, { status: 400, code: "INVALID_LIMIT" });
+        this.name = "ListLimitError";
+        this.maxLimit = maxLimit;
+        // Keeps `instanceof` working when this is compiled down for an older
+        // target, where extending a builtin otherwise loses the prototype.
+        Object.setPrototypeOf(this, ListLimitError.prototype);
+    }
+}
+
 /**
  * Resolve a client-supplied list `limit` into a safe, always-defined value.
  *
- * - A provided limit is coerced to an integer and clamped to `[1, maxLimit]`,
- *   so `0`, negatives, and absurd values can never bypass the cap.
- * - An absent / blank / non-numeric limit falls back to the mode default:
+ * - An absent / blank limit falls back to the mode default:
  *   `vectorDefaultLimit` for a vector search, otherwise `defaultLimit`.
+ * - A limit that is present must be an integer in `[1, maxLimit]`. Anything
+ *   else — `0`, a negative, `1.5`, `abc`, `100000000` — throws
+ *   {@link ListLimitError} rather than being coerced into range, because every
+ *   coercion answers a question the caller did not ask with a page it cannot
+ *   tell apart from the whole collection.
  *
  * The return is never `undefined` — no ingress that routes its client limit
  * through this can produce an unbounded read.
+ *
+ * @throws {ListLimitError} when a present `limit` is not an integer in range.
  */
 export function resolveClientListLimit(
     rawLimit: number | string | null | undefined,
@@ -87,10 +125,24 @@ export function resolveClientListLimit(
 ): number {
     const maxLimit = opts.maxLimit ?? MAX_LIST_LIMIT;
     if (rawLimit != null && String(rawLimit).trim() !== "") {
-        const parsed = typeof rawLimit === "number" ? rawLimit : parseInt(String(rawLimit), 10);
-        if (Number.isFinite(parsed)) {
-            return Math.min(Math.max(1, Math.floor(parsed)), maxLimit);
+        // `Number`, not `parseInt`: `parseInt("50rows")` is 50, which silently
+        // reads a typo as a window the caller never wrote.
+        const parsed = typeof rawLimit === "number" ? rawLimit : Number(String(rawLimit).trim());
+        if (!Number.isInteger(parsed) || parsed < 1) {
+            throw new ListLimitError(
+                `Invalid \`limit\`: ${String(rawLimit)}. Expected a whole number between 1 and ${maxLimit}.`,
+                maxLimit
+            );
+        }
+        if (parsed > maxLimit) {
+            throw new ListLimitError(
+                `\`limit\` ${parsed} is above the maximum of ${maxLimit}. Ask for at most ${maxLimit} rows ` +
+                "per read and page through the rest with `offset` — answering with a smaller page would be " +
+                "indistinguishable from there being no more rows.",
+                maxLimit
+            );
         }
+        return parsed;
     }
     return opts.vectorSearch
         ? (opts.vectorDefaultLimit ?? DEFAULT_VECTOR_LIST_LIMIT)
@@ -117,6 +169,8 @@ export interface FetchCollectionProps<M extends Record<string, unknown> = Record
     startAfter?: unknown;
     orderBy?: string;
     searchString?: string;
+    /** Ask each row which declared search field matched — populates `_matches`. */
+    searchExplain?: boolean;
     order?: "desc" | "asc";
     /** Vector similarity search configuration */
     vectorSearch?: VectorSearchParams;
@@ -169,6 +223,23 @@ export interface SaveManyProps<M extends Record<string, unknown> = Record<string
     upsert?: boolean;
 }
 
+/**
+ * @internal
+ */
+export interface UpdateManyProps<M extends Record<string, unknown> = Record<string, unknown>> {
+    path: string;
+    /**
+     * The rows to update, each named by its address.
+     *
+     * Distinct from {@link SaveManyProps.rows}, which carries keys *inside* the
+     * values and is insert-shaped — `saveMany` passes `status: "new"` and no
+     * `id`, so it cannot express "update exactly this row". This can, and it is
+     * why bulk update is a separate driver method rather than a flag on that one.
+     */
+    updates: { id: string | number; values: Partial<EntityValues<M>> }[];
+    collection?: CollectionConfig<M>;
+}
+
 /**
  * @internal
  */
@@ -177,6 +248,15 @@ export interface DeleteProps<M extends Record<string, unknown> = Record<string,
     collection?: CollectionConfig<M>;
 }
 
+/**
+ * @internal
+ */
+export interface DeleteManyProps<M extends Record<string, unknown> = Record<string, unknown>> {
+    path: string;
+    ids: (string | number)[];
+    collection?: CollectionConfig<M>;
+}
+
 export type FilterCombinationValidProps = {
     path: string;
     databaseId?: string;
@@ -258,6 +338,17 @@ export interface DataDriver {
      */
     saveMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveManyProps<M>): Promise<Record<string, unknown>[]>;
 
+    /**
+     * Update many rows in one transaction, each addressed by id.
+     *
+     * Optional for the same reason `saveMany` is: a driver that cannot make the
+     * batch atomic should not pretend to. The REST layer reports
+     * `BULK_UNSUPPORTED` rather than silently falling back to a loop of single
+     * writes, which would be neither atomic nor one round trip — the two things
+     * a caller reaches for a batch to get.
+     */
+    updateMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: UpdateManyProps<M>): Promise<Record<string, unknown>[]>;
+
     /**
      * Delete a entity
      * @param props
@@ -271,6 +362,14 @@ export interface DataDriver {
      */
     deleteAll?(path: string): Promise<void>;
 
+    /**
+     * Delete many rows in one transaction, addressed by id.
+     *
+     * Ids rather than a filter, deliberately — see
+     * {@link SDKCollectionClient.deleteMany}. Optional, as `saveMany` is.
+     */
+    deleteMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: DeleteManyProps<M>): Promise<void>;
+
     /**
      * Check if the given property is unique in the given collection
      * @param path Collection path
@@ -383,6 +482,8 @@ export interface RestFetchService {
             offset?: number;
             startAfter?: Record<string, unknown>;
             searchString?: string;
+            /** Ask each row which declared search fields matched — populates `_matches`. */
+            searchExplain?: boolean;
             databaseId?: string;
             vectorSearch?: VectorSearchParams;
         },

package/src/errors.ts

@@ -1,3 +1,42 @@
+/**
+ * The error codes every route can produce, as `RebaseApiError.code`.
+ *
+ * These are the defaults on `ApiError`'s static constructors server-side, so
+ * any endpoint can answer with one. They are **not** the complete set: routes
+ * pass their own more specific codes too (`EMAIL_EXISTS`, `TOKEN_EXPIRED`,
+ * `INVALID_BULK_BODY`, …), and auth alone defines a couple of dozen.
+ *
+ * Hence the union is deliberately open rather than closed. It exists to give
+ * autocomplete and to catch a typo in the common cases — `code` was a bare
+ * `string`, so `e.code === "NOT_FOUND"` and `e.code === "NOTFOUND"` were
+ * equally valid and only one of them worked. Closing it would be a lie that
+ * broke the moment a route added a code.
+ *
+ * @example
+ * if (e instanceof RebaseApiError) {
+ *   switch (e.code) {
+ *     case "NOT_FOUND": return null;          // completed
+ *     case "FORBIDDEN": return redirect();
+ *     default: throw e;                       // routes' own codes land here
+ *   }
+ * }
+ *
+ * @group Errors
+ */
+export type RebaseErrorCode =
+    | "BAD_REQUEST"
+    | "UNAUTHORIZED"
+    | "FORBIDDEN"
+    | "NOT_FOUND"
+    | "CONFLICT"
+    | "INTERNAL_ERROR"
+    | "SERVICE_UNAVAILABLE"
+    | "DB_PERMISSION_DENIED"
+    | "SCHEMA_DRIFT"
+    // `string & {}` keeps the union open while preserving completion on the
+    // literals above — a bare `| string` would collapse them and offer nothing.
+    | (string & {});
+
 /**
  * Structured initializer for {@link RebaseApiError}.
  *
@@ -10,8 +49,8 @@ export interface RebaseErrorInit {
      * logic errors that have no HTTP status.
      */
     status?: number;
-    /** Stable, machine-readable error code (e.g. `"NOT_FOUND"`, `"BAD_REQUEST"`). */
-    code?: string;
+    /** Stable, machine-readable error code. See {@link RebaseErrorCode}. */
+    code?: RebaseErrorCode;
     /** Structured error payload returned by the server, when present. */
     details?: unknown;
     /** The underlying error this one wraps, if any. */
@@ -45,8 +84,8 @@ export interface RebaseErrorInit {
 export class RebaseApiError extends Error {
     /** HTTP status code, or `undefined` for non-HTTP errors. */
     readonly status?: number;
-    /** Stable machine-readable error code, when the server supplied one. */
-    readonly code?: string;
+    /** Stable machine-readable error code, when the server supplied one. See {@link RebaseErrorCode}. */
+    readonly code?: RebaseErrorCode;
     /** Structured error payload from the server, when present. */
     readonly details?: unknown;
 

package/src/types/admin_block.ts

@@ -41,6 +41,7 @@ export const ADMIN_COLLECTION_KEYS = [
     "defaultSize",
     "defaultViewMode",
     "disableDefaultActions",
+    "display",
     "enabledViews",
     "entityActions",
     "entityViews",
@@ -51,6 +52,7 @@ export const ADMIN_COLLECTION_KEYS = [
     "formAutoSave",
     "formView",
     "group",
+    "hideFromEntityViews",
     "hideFromNavigation",
     "hideIdFromCollection",
     "hideIdFromForm",
@@ -122,3 +124,86 @@ export const ADMIN_PROPERTY_KEYS = [
 
 /** A key of a property's `admin` block. @group Models */
 export type AdminPropertyKey = typeof ADMIN_PROPERTY_KEYS[number];
+
+/**
+ * Move flattened admin keys back down into the `admin` block.
+ *
+ * The admin panel works with a *flat* view model — the block merged onto the
+ * collection — so what comes back from a form has `icon` and `defaultViewMode`
+ * at the top level while `admin` still holds whatever the file was loaded with.
+ * This is the way back.
+ *
+ * **The top-level value wins.** It is the one the form just wrote; the block is
+ * the copy the collection was loaded with, and preferring it resolves every edit
+ * in favour of the value the user changed away from.
+ *
+ * This lives here, next to the key lists, because it had two implementations —
+ * `toAdminCollectionConfig` in `@rebasepro/admin-types` and `nestAdminKeys` in
+ * `@rebasepro/server`'s schema editor — that agreed on everything except that
+ * precedence, which is the only part that decides whether a save is visible.
+ *
+ * @group Models
+ */
+export function nestAdminKeysOf(
+    source: Record<string, unknown>,
+    adminKeys: readonly string[]
+): Record<string, unknown> {
+    const keys = new Set<string>(adminKeys);
+    const top: Record<string, unknown> = {};
+    const block: Record<string, unknown> = { ...((source.admin as Record<string, unknown> | undefined) ?? {}) };
+
+    for (const [key, value] of Object.entries(source)) {
+        if (key === "admin") continue;
+        if (keys.has(key)) block[key] = value;
+        else top[key] = value;
+    }
+
+    if (Object.keys(block).length > 0) top.admin = block;
+    return top;
+}
+
+/**
+ * {@link nestAdminKeysOf} for a collection.
+ *
+ * @group Models
+ */
+export function nestAdminCollectionKeys(collection: Record<string, unknown>): Record<string, unknown> {
+    return nestAdminKeysOf(collection, ADMIN_COLLECTION_KEYS);
+}
+
+/**
+ * {@link nestAdminKeysOf} for a property, applied to its children too.
+ *
+ * A map property carries `properties`, an array property carries `of`, and both
+ * hold properties with `admin` blocks of their own. A flat `readOnly` left on a
+ * child is as dead — and as fatal at the next boot — as one left on the parent,
+ * so the walk goes all the way down.
+ *
+ * @group Models
+ */
+export function nestAdminPropertyKeys(property: Record<string, unknown>): Record<string, unknown> {
+    const nested = nestAdminKeysOf(property, ADMIN_PROPERTY_KEYS);
+
+    const children = nested.properties;
+    if (children && typeof children === "object" && !Array.isArray(children)) {
+        nested.properties = Object.fromEntries(
+            Object.entries(children as Record<string, unknown>).map(([key, child]) => [
+                key,
+                child && typeof child === "object" && !Array.isArray(child)
+                    ? nestAdminPropertyKeys(child as Record<string, unknown>)
+                    : child
+            ])
+        );
+    }
+
+    const of = nested.of;
+    if (Array.isArray(of)) {
+        nested.of = of.map(entry => entry && typeof entry === "object" && !Array.isArray(entry)
+            ? nestAdminPropertyKeys(entry as Record<string, unknown>)
+            : entry);
+    } else if (of && typeof of === "object") {
+        nested.of = nestAdminPropertyKeys(of as Record<string, unknown>);
+    }
+
+    return nested;
+}

package/src/types/backend.ts

@@ -243,6 +243,8 @@ export interface CollectionSubscriptionConfig {
     startAfter?: unknown;
     databaseId?: string;
     searchString?: string;
+    /** Ask each row which declared search field matched. */
+    searchExplain?: boolean;
 }
 
 /**

package/src/types/collections.ts

@@ -7,6 +7,7 @@ import type { Relation } from "./relations";
 import type { SecurityRule } from "./security_rules";
 import { getDataSourceCapabilities } from "./data_source";
 import type { WhereFilterOp, FilterValues, FilterPreset } from "./filter-operators";
+import type { SearchConfig } from "./search";
 
 /**
  * Base interface containing all driver-agnostic collection properties.
@@ -19,9 +20,27 @@ import type { WhereFilterOp, FilterValues, FilterPreset } from "./filter-operato
 export interface BaseCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
 
     /**
-     * You can set an alias that will be used internally instead of the collection name.
-     * The `slug` value will be used to determine the URL of the collection.
-     * Note that you can use this value in reference properties too.
+     * The collection's identity. Required, and the value nearly everything else
+     * keys on:
+     *
+     * - the REST path — `/api/data/<slug>`
+     * - the SDK accessor — `client.data.<slug>` / `client.data.collection("<slug>")`
+     * - the admin panel's URL
+     * - the target of a `reference` or `relation` property
+     *
+     * Conventionally kebab-case and plural (`blog-posts`). It is independent of
+     * {@link table}: the slug is what callers say, the table is where the rows
+     * live, and renaming one does not rename the other.
+     *
+     * Treat it as frozen once anything has shipped against it — changing a slug
+     * changes every URL and every generated accessor at once.
+     *
+     * @example
+     * defineCollection({
+     *     slug: "blog-posts",   // /api/data/blog-posts, client.data.blogPosts
+     *     table: "posts",
+     *     properties: { … }
+     * })
      */
     slug: string;
 
@@ -192,11 +211,16 @@ export interface BaseCollectionConfig<M extends Record<string, unknown> = Record
      * Whether a write naming a field this collection does not declare is
      * rejected with a 400. Defaults to `true`.
      *
-     * Set to `false` to let unknown keys through to the database, which is what
-     * happened before this existed: a typo reached the INSERT and came back as
-     * a Postgres error about a column, or — where a column really does exist
-     * that the config never declared, populated by a trigger or a default —
-     * quietly worked. The second case is the reason for the escape hatch.
+     * Set to `false` where a column really does exist that the config never
+     * declared — populated by a trigger, or introspected rather than declared —
+     * and callers need to write it. The column still has to exist: the driver
+     * checks the key against the table's own columns whatever this is set to,
+     * because a key with no column behind it is not passed to the database and
+     * refused, it is dropped from the statement and answered 201.
+     *
+     * It does not let a typo through to Postgres for Postgres to judge. That is
+     * what this flag was documented as doing, and no such judgment ever
+     * happened.
      */
     strictWrites?: boolean;
 
@@ -283,6 +307,21 @@ export interface PostgresCollectionConfig<M extends Record<string, unknown> = Re
      * @default false
      */
     disableDefaultPolicies?: boolean;
+
+    /**
+     * Opt in to Postgres full-text search for this collection.
+     *
+     * Omit it and `.search()` keeps its existing behaviour exactly — an
+     * `ILIKE '%term%'` across top-level string properties. Declare it and the
+     * collection gains one generated `tsvector` column and a GIN index, and
+     * `.search()` compiles to a ranked `@@ websearch_to_tsquery` against them.
+     *
+     * Postgres-only, like {@link VectorProperty}: the block is rejected at boot
+     * on other engines rather than silently ignored.
+     *
+     * @see SearchConfig
+     */
+    search?: SearchConfig;
 }
 
 /**

package/src/types/cron.ts

@@ -1,4 +1,5 @@
-import type { RebaseClient } from "../controllers/client";
+import type { RebaseServerClient } from "../controllers/client";
+import type { RebaseSdkData } from "../controllers/data";
 
 /**
  * Cron Job type definitions for Rebase.
@@ -93,16 +94,57 @@ export interface CronJobContext {
     log: (...args: unknown[]) => void;
 
     /**
-     * The server-side {@link RebaseClient}. This is the **same singleton**
-     * exposed as `rebase` (imported from `@rebasepro/server`) and as
-     * `context` in collection callbacks — it is only named `client` here.
+     * The server-side Rebase singleton — the **same object** `import { rebase }
+     * from "@rebasepro/server"` returns, and the same one `defineFunction`
+     * hands its callback. Spelled the same way here so that one thing has one
+     * name across every server-side authoring surface.
      *
-     * Its data plane (`client.data`) runs with **admin privileges and bypasses
-     * RLS** (`{ uid: "service", roles: ["admin"] }`). There is no per-request
-     * user in a cron, so treat every query as fully trusted and scope your own
-     * filters explicitly.
+     * Its data plane is {@link RebaseServerClient.dataAsAdmin}, which runs with
+     * **admin privileges and bypasses RLS** (`{ uid: "service", roles:
+     * ["admin"] }`). A cron has no per-request user, so there is no user-scoped
+     * alternative here and no policy to fall back on: scope every query's
+     * filters yourself.
+     *
+     * @example
+     * export default defineCron({
+     *     name: "Nightly cleanup",
+     *     schedule: "0 3 * * *",
+     *     async handler({ rebase, log }) {
+     *         const expired = await rebase.dataAsAdmin.sessions.findAll({
+     *             where: { expired: ["==", true] }
+     *         });
+     *         for (const session of expired) {
+     *             await rebase.dataAsAdmin.sessions.delete(session.id as string);
+     *         }
+     *         log(`Deleted ${expired.length} expired sessions`);
+     *     }
+     * });
+     */
+    rebase: RebaseServerClient;
+
+    /**
+     * The same object as {@link rebase}, under the name this context used
+     * before.
+     *
+     * @deprecated Use `rebase` instead. Two things made the old name a problem,
+     * and neither was cosmetic. It contradicted every other server surface,
+     * where the singleton is `rebase` — the previous docstring had to end with
+     * *"it is only named `client` here"*. And typing it as `RebaseClient`
+     * re-exposed `client.data`, the alias that {@link RebaseServerClient}
+     * deliberately `Omit`s so the RLS-bypassing plane has exactly one name and
+     * the privilege is visible at the call site. A reader who learned
+     * `client.data` here carried it to a collection callback, where
+     * `context.data` is the *user-scoped* plane — same spelling, opposite
+     * privilege.
+     *
+     * Still the full server client at runtime, and `data` still resolves, so
+     * existing cron files keep working and keep compiling. It will be removed
+     * in the next major.
      */
-    client: RebaseClient;
+    client: RebaseServerClient & {
+        /** @deprecated Use `rebase.dataAsAdmin` — the name states the privilege. */
+        data: RebaseSdkData;
+    };
 }
 
 // =============================================================================

package/src/types/entities.ts

@@ -1,3 +1,4 @@
+import type { SearchMatch } from "./search";
 /**
  * New or existing status
  * @group Models
@@ -26,6 +27,17 @@ export interface Entity<M extends Record<string, unknown> = Record<string, unkno
      */
     values: EntityValues<M>;
 
+    /**
+     * Why this entity is in a search result: which declared fields matched, and
+     * the text around each hit.
+     *
+     * Present only on rows returned by a search that asked for it. A sibling of
+     * `values` rather than a key inside it, because it describes the *query*,
+     * not the record — nothing in the collection declares it, no form edits it,
+     * and a record fetched by id never has one.
+     */
+    searchMatches?: SearchMatch[];
+
     /**
      * Which driver this entity belongs to (e.g., 'postgres', 'firestore').
      * If not specified, the default driver is assumed.

package/src/types/entity_callbacks.ts

@@ -8,7 +8,8 @@ import type { RebaseCallContext } from "../call_context";
  *
  * Register per-collection on the collection's `callbacks` field, or globally
  * via `initializeRebaseBackend({ callbacks })`. Fires on **every** data path — REST API,
- * WebSocket / realtime subscriptions, and server-side `rebase.data`.
+ * WebSocket / realtime subscriptions, and server-side writes through
+ * `rebase.dataAsAdmin`.
  *
  * When both global and per-collection callbacks are registered, execution
  * order is: **global → collection → property callbacks**.

package/src/types/index.ts

@@ -5,8 +5,10 @@ export * from "./chips";
 export * from "./properties";
 export * from "./admin_block";
 export * from "./collections";
+export * from "./search";
 export * from "./relations";
 export * from "./policy";
+export * from "./rls-functions";
 export * from "./security_rules";
 
 export * from "./entity_callbacks";