@rebasepro/types 0.10.0 → 0.10.1-canary.0a881d4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.10.0",
+  "version": "0.10.1-canary.0a881d4",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -41,18 +41,15 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^25.9.3",
     "@types/object-hash": "^3.0.6",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
     "@types/react-measure": "^2.0.12",
-    "@vitejs/plugin-react": "^6.0.2",
-    "hono": "^4.12.25",
+    "hono": "^4.12.27",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11",
     "typescript": "^6.0.3",
     "vite": "^8.0.16"
   },
   "peerDependencies": {
-    "hono": "^4.12.21"
+    "hono": "^4.12.27"
   },
   "files": [
     "dist",

package/src/call_context.ts

@@ -0,0 +1,56 @@
+import type { StorageSource } from "./controllers/storage";
+import type { RebaseClient } from "./controllers/client";
+import type { RebaseSdkData } from "./controllers/data";
+import type { User } from "./users";
+
+/**
+ * Context that is provided to entity callbacks (hooks).
+ * It contains only the dependencies that are available in both the frontend and the backend.
+ *
+ * This is the *whole* context a collection callback gets, and it lives apart from
+ * {@link RebaseContext} on purpose. `RebaseContext` widens it with nine admin-panel
+ * controllers — navigation, side dialogs, snackbars — none of which exist in a
+ * backend process. Keeping them in one type meant every backend module that
+ * touched a callback signature transitively named the admin UI.
+ *
+ * @group Hooks and utilities
+ */
+export type RebaseCallContext<USER extends User = User> = {
+
+    /**
+     * The Rebase client instance.
+     * Available in all entity callbacks (beforeSave, afterSave, afterRead,
+     * beforeDelete, afterDelete) and in CollectionActionsProps via context.
+     * Use it to call backend functions, access data, storage, etc.
+     *
+     * @example
+     * // In a beforeSave callback:
+     * const result = await context.client.functions.invoke('my-function', { ... });
+     *
+     * @example
+     * // In a CollectionAction component:
+     * const { client } = props.context;
+     * const result = await client.functions.invoke('extract-job', { url });
+     */
+    client: RebaseClient;
+
+    /**
+     * Unified data access — `context.data.products.create(...)`.
+     * Access any collection as a dynamic property.
+     *
+     * Returns flat rows (`{ id, ...columns }`), identical to the frontend SDK
+     * client — so `context.data` in a backend callback and `client.data` in the
+     * frontend behave the same way (`row.title`, never `row.values.title`).
+     */
+    data: RebaseSdkData;
+
+    /**
+     * Used storage implementation
+     */
+    storageSource: StorageSource;
+
+    /**
+     * Set by the backend when callbacks are executed on the server.
+     */
+    user?: USER;
+}

package/src/controllers/auth_state.ts

@@ -0,0 +1,24 @@
+import type { User } from "../users";
+
+/**
+ * The read-only slice of authentication state that property resolution needs.
+ *
+ * `dynamicProps`, `conditions` and the JSON-Logic condition context all want the
+ * same one thing: who is asking. They used to be handed the entire
+ * {@link AuthController} — `signOut`, `googleLogin`, `authLoading`, thirty-odd
+ * members of frontend machinery — which meant `properties.ts` named a frontend
+ * controller, and so did `resolveProperty` in `@rebasepro/common`, which the
+ * Postgres schema generator calls at build time. A backend generating DDL had to
+ * satisfy a type with a login method in it.
+ *
+ * `User` already carries `roles` and `metadata`, so this is not a reduction in
+ * what a dynamic property can decide on — only in what it has to be given.
+ * An `AuthController` satisfies this structurally, so the frontend passes the
+ * controller it already has.
+ *
+ * @group Hooks and utilities
+ */
+export interface AuthState<USER extends User = User> {
+    /** The signed-in user, or `null` when nobody is. */
+    user: USER | null;
+}

package/src/controllers/client.ts

@@ -384,9 +384,10 @@ export interface RebaseServerClient<DB = unknown> extends RebaseClient<DB> {
 
     /**
      * Execute raw SQL against the database. Always present server-side for SQL
-     * engines.
+     * engines. Values interpolated into the query should be passed via
+     * `params`, referenced as `$1`, `$2`, … placeholders in the query text.
      */
-    sql(query: string, options?: { database?: string; role?: string }): Promise<Record<string, unknown>[]>;
+    sql(query: string, options?: { database?: string; role?: string; params?: unknown[] }): Promise<Record<string, unknown>[]>;
 }
 
 // ─── RebaseBrowserClient ─────────────────────────────────────────────────────

package/src/controllers/collection_registry.ts

@@ -15,8 +15,12 @@ export type CollectionRegistryController<
      * 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.
+     *
+     * `EC`, like {@link getCollection} — this was hardcoded to `CollectionConfig`
+     * while `getCollection` honoured the parameter, so the admin panel got its
+     * view model from one and the raw contract from the other.
      */
-    collections?: CollectionConfig[];
+    collections?: EC[];
 
     /**
      * Is the registry ready to be used

package/src/controllers/data_driver.ts

@@ -1,7 +1,7 @@
 import type { CollectionRegistryController } from "./collection_registry";
 import type { EntityStatus, EntityValues } from "../types/entities";
 import type { CollectionConfig, FilterValues } from "../types/collections";
-import type { RebaseContext } from "../rebase_context";
+import type { RebaseCallContext } from "../call_context";
 
 
 /**
@@ -40,6 +40,62 @@ export interface VectorSearchParams {
     threshold?: number;
 }
 
+// ── List pagination bounds ────────────────────────────────────────────────
+//
+// Client-driven list reads (REST `GET /<collection>` and the WebSocket
+// `subscribe_collection` message) accept a client-supplied `limit`. Without
+// bounds, an ABSENT limit streams the entire table into memory — a trivial
+// OOM/DoS — and `limit=100000000` (or `limit=0`, historically an unlimited
+// bypass) is honoured verbatim. `resolveClientListLimit` is the single shared
+// enforcement point so every untrusted ingress behaves identically. Trusted
+// server-side callers build fetch options directly and are intentionally NOT
+// bounded here (migrations, admin exports, and CDC refetches may need the full
+// set).
+
+/** 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. */
+export const MAX_LIST_LIMIT = 1000;
+
+/** Overridable bounds for {@link resolveClientListLimit}. */
+export interface ListLimitBounds {
+    /** Default page size for plain and text-search reads. */
+    defaultLimit?: number;
+    /** Default page size for vector-search reads. */
+    vectorDefaultLimit?: number;
+    /** Upper bound clamped onto any client-supplied limit. */
+    maxLimit?: number;
+}
+
+/**
+ * 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:
+ *   `vectorDefaultLimit` for a vector search, otherwise `defaultLimit`.
+ *
+ * The return is never `undefined` — no ingress that routes its client limit
+ * through this can produce an unbounded read.
+ */
+export function resolveClientListLimit(
+    rawLimit: number | string | null | undefined,
+    opts: ListLimitBounds & { vectorSearch?: boolean } = {}
+): 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);
+        }
+    }
+    return opts.vectorSearch
+        ? (opts.vectorDefaultLimit ?? DEFAULT_VECTOR_LIST_LIMIT)
+        : (opts.defaultLimit ?? DEFAULT_LIST_LIMIT);
+}
+
 /**
  * @internal
  */
@@ -246,7 +302,7 @@ export interface DataDriver {
     cmsToDelegateModel?: (data: unknown) => unknown;
 
     initTextSearch?: (props: {
-        context: RebaseContext,
+        context: RebaseCallContext,
         path: string,
         databaseId?: string,
         collection: CollectionConfig,

package/src/controllers/index.ts

@@ -1,21 +1,12 @@
 export * from "./collection_registry";
-export * from "./analytics_controller";
-export * from "./auth";
+export * from "./auth_state";
 
 export * from "./data";
 export * from "./database_admin";
 export * from "./data_driver";
 
-export * from "./local_config_persistence";
-export * from "./navigation";
 export * from "./effective_role";
 
 export * from "./storage";
 export * from "./email";
 export * from "./client";
-export * from "./customization_controller";
-export * from "./side_panel_controller";
-export * from "./side_dialogs_controller";
-export * from "./dialogs_controller";
-export * from "./snackbar";
-export * from "./registry";

package/src/index.ts

@@ -1,5 +1,5 @@
 export * from "./errors";
-export * from "./rebase_context";
+export * from "./call_context";
 export * from "./types";
 export * from "./controllers";
 export * from "./users";

package/src/types/admin_block.ts

@@ -0,0 +1,75 @@
+/**
+ * The keys of a collection's admin block, as data.
+ *
+ * There is no *type* for the block in this package any more, and that is the point:
+ * `admin` is not declared on `BaseCollectionConfig` or on any property here, so a
+ * BaaS install cannot even write one. `@rebasepro/admin-types` adds the field back by
+ * declaration merging, which is why installing it is what makes the admin surface
+ * appear.
+ *
+ * The *list* still has to live here, because three runtime consumers need it and two
+ * of them are core — see below.
+ */
+
+/**
+ * Every key that belongs inside a collection's `admin` block, as data.
+ *
+ * The type that describes these fields is `AdminCollectionOptions` in
+ * `@rebasepro/admin-types`, and it is erased at build time — but three runtime
+ * consumers need the list, and two of them are core:
+ *
+ * - `serializeCollections`, to drop the block from the contract
+ * - the ts-morph schema editor in `@rebasepro/server`, which rewrites collection
+ *   files on disk from the admin panel and has to know where each key goes. A key
+ *   missing from this list gets written to the *top level* of the file, where the
+ *   backend ignores it and the panel never finds it again.
+ * - the `collections-admin-block` codemod
+ *
+ * `@rebasepro/admin-types` re-exports this and asserts it names only real option
+ * keys; the count is pinned by a test there.
+ *
+ * @group Models
+ */
+export const ADMIN_COLLECTION_KEYS = [
+    "Actions",
+    "additionalFields",
+    "alwaysApplyDefaultValues",
+    "components",
+    "defaultEntityAction",
+    "defaultFilter",
+    "defaultSelectedView",
+    "defaultSize",
+    "defaultViewMode",
+    "disableDefaultActions",
+    "enabledViews",
+    "entityActions",
+    "entityViews",
+    "exportable",
+    "filterPresets",
+    "fixedFilter",
+    "formAutoSave",
+    "formView",
+    "group",
+    "hideFromNavigation",
+    "hideIdFromCollection",
+    "hideIdFromForm",
+    "icon",
+    "includeJsonView",
+    "inlineEditing",
+    "kanban",
+    "listProperties",
+    "localChangesBackup",
+    "openEntityMode",
+    "orderProperty",
+    "pagination",
+    "previewProperties",
+    "propertiesOrder",
+    "selectionController",
+    "selectionEnabled",
+    "sideDialogWidth",
+    "sort",
+    "titleProperty"
+] as const;
+
+/** A key of a collection's `admin` block. @group Models */
+export type AdminCollectionKey = typeof ADMIN_COLLECTION_KEYS[number];

package/src/types/backend.ts

@@ -1,6 +1,7 @@
 import type { CollectionConfig, FilterValues, WhereFilterOp } from "./collections";
 import type { AuthAdapter } from "./auth_adapter";
 import type { HistoryConfig } from "../controllers/client";
+import type { ChannelBusSetting } from "./channel_bus";
 
 // =============================================================================
 // DATABASE CONNECTION INTERFACES
@@ -272,13 +273,23 @@ export interface ChannelRetentionRule {
     ttl?: number | string;
 }
 
-/** Server-side realtime options. */
+/**
+ * Server-side realtime options.
+ *
+ * The channel bus contract and its config live in `./channel_bus` so that a
+ * transport shipped as its own package depends on the contract alone.
+ */
 export interface RealtimeChannelsConfig {
     /**
      * Retention rules, most specific first — the first match wins. Omitted or
      * empty means no channel retains anything.
      */
     channels?: ChannelRetentionRule[];
+    /**
+     * How channel broadcast and presence reach other backend instances.
+     * Defaults to `{ type: "memory" }` — i.e. they don't.
+     */
+    bus?: ChannelBusSetting;
 }
 
 /**
@@ -766,6 +777,27 @@ export interface BackendBootstrapper {
      */
     getAdmin?(driverResult: InitializedDriver): DatabaseAdmin | undefined;
 
+    /**
+     * Bring the database's collection tables up to date, additively.
+     *
+     * Optional because it is only meaningful for schema-ful drivers. A managed
+     * runtime boots a compiled project against a database it has never seen; auth
+     * tables are ensured on boot but collection tables were created by nothing,
+     * so every data request answered 500 on a missing relation. The CLI's `db
+     * push` cannot fill the gap — it needs Atlas, and the runtime image ships no
+     * CLI.
+     *
+     * Implementations MUST be additive-only: create missing tables, columns and
+     * 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.
+     */
+    ensureCollectionSchema?(
+        collections: unknown[],
+        driverResult: InitializedDriver,
+        log?: (message: string) => void
+    ): Promise<{ applied: number }>;
+
     /**
      * Initialize WebSocket server for realtime operations.
      */

package/src/types/channel_bus.ts

@@ -0,0 +1,202 @@
+/**
+ * The cross-instance transport for channel broadcast and presence, and the
+ * contract anyone implementing one has to meet.
+ *
+ * These types live in `@rebasepro/types` rather than in the Postgres adapter on
+ * purpose: a transport package should depend on the contract, not on the
+ * database driver that happens to ship the default implementation. A
+ * `@rebasepro/channel-bus-<something>` package needs this file and nothing else.
+ *
+ * Why a transport exists at all: entity/collection realtime already spans
+ * instances (CDC, or per-mutation LISTEN/NOTIFY). Channel broadcast and presence
+ * did not — they fanned out from per-process maps, so two clients served by
+ * different replicas could not see each other, and nothing errored. The bus is
+ * the missing hop, and deliberately *only* that hop: which local clients receive
+ * a frame stays in the realtime service, so a transport never has to know what a
+ * subscription, a WebSocket or a presence roster is.
+ */
+
+/**
+ * A frame in flight between instances.
+ *
+ * `sid` identifies the publishing instance. The realtime service drops frames
+ * carrying its own `sid` on arrival — local fan-out already happened before the
+ * publish — so a transport that echoes a publisher's own messages back to it is
+ * still correct, merely wasteful.
+ *
+ * Keys are spelled out rather than abbreviated. The one shipped transport with a
+ * size limit has a pointer path for anything that would approach it, so shaving
+ * bytes off key names buys nothing worth the opacity.
+ */
+export type ChannelBusFrame =
+    /** A broadcast carrying its payload. */
+    | {
+        kind: "broadcast";
+        sid: string;
+        channel: string;
+        event: string;
+        /** Originating client, echoed so receivers can skip it if it is theirs. */
+        from?: string;
+        /** Sequence number, present only on retained channels. */
+        seq?: number;
+        payload: unknown;
+    }
+    /**
+     * A broadcast too large for the transport to carry inline: the body is
+     * already durable in `rebase.channel_messages`, so the frame carries only
+     * its address and each receiver reads it back. Only ever emitted for
+     * retained channels, and only by a transport with a finite
+     * {@link ChannelBus.maxFrameBytes}.
+     */
+    | {
+        kind: "broadcast_ref";
+        sid: string;
+        channel: string;
+        from?: string;
+        seq: number;
+    }
+    /** A presence join/leave/update, small by construction. */
+    | {
+        kind: "presence_diff";
+        sid: string;
+        channel: string;
+        joins: Record<string, Record<string, unknown>>;
+        leaves: Record<string, Record<string, unknown>>;
+    };
+
+/** Receives frames published by *other* instances. */
+export type ChannelBusHandler = (frame: ChannelBusFrame) => void | Promise<void>;
+
+/**
+ * A cross-instance transport.
+ *
+ * ## What an implementation must guarantee
+ *
+ * - **`start()` rejects if the transport is unusable.** The caller falls back to
+ *   in-process delivery when it does. Resolving while disconnected produces a
+ *   cluster that believes it is connected and silently is not, which is the
+ *   exact failure this whole mechanism exists to remove.
+ * - **`publish()` reaches every *other* instance, or rejects.** Delivery back to
+ *   the publisher is permitted but pointless (see {@link ChannelBusFrame.sid}).
+ * - **`stop()` is idempotent** and releases everything, including anything
+ *   holding the event loop open.
+ * - **A malformed message never throws out of the transport.** Parsing happens
+ *   inside the implementation; drop and log what you cannot understand, so one
+ *   bad frame cannot take the listener down.
+ *
+ * ## What it does *not* have to guarantee
+ *
+ * - **Ordering.** Retained channels carry `seq`, and the client SDK orders by
+ *   it. Unsequenced broadcasts are cursor-grade traffic where order is not
+ *   meaningful.
+ * - **Durability.** A frame lost in transit is a missed live update; retained
+ *   channels repair themselves through the client's `channel_history` replay.
+ * - **Exactly-once.** Duplicates are tolerated — retained frames are deduped by
+ *   `seq`, and presence diffs are idempotent by construction.
+ */
+export interface ChannelBus {
+    /**
+     * Identifies the transport in logs and in `getChannelBusKind()`. Use your
+     * own name; the framework only compares against `"memory"` to decide
+     * whether publishing is worth attempting at all.
+     */
+    readonly kind: string;
+
+    /**
+     * Largest frame this transport will carry, in bytes of encoded JSON, or
+     * `Infinity` when there is no meaningful ceiling.
+     *
+     * A broadcast that exceeds it is published as a `broadcast_ref` pointer when
+     * the channel is retained, and refused with an error to the sender when it
+     * is not. Implementations with no limit should return `Infinity` rather than
+     * a large number, so the pointer path is never taken needlessly.
+     */
+    readonly maxFrameBytes: number;
+
+    /** Connect and begin delivering remote frames to `handler`. */
+    start(handler: ChannelBusHandler): Promise<void>;
+
+    /** Publish a frame to the other instances. */
+    publish(frame: ChannelBusFrame): Promise<void>;
+
+    /** Disconnect and release resources. Idempotent. */
+    stop(): Promise<void>;
+}
+
+/**
+ * Which transport to use, for the two that ship with the Postgres adapter.
+ *
+ * To use one that does not ship here — a Redis package, or your own class —
+ * pass the {@link ChannelBus} instance itself instead of a config object.
+ *
+ * There are deliberately only two built in, and neither adds a service to a
+ * deployment. Rebase deploys as Postgres + backend + frontend; a bus that
+ * required a message broker would put a second stateful service into every
+ * `docker-compose.yml` the CLI scaffolds, for a feature most applications never
+ * use. Measured across two backend instances against one Postgres container,
+ * the Postgres bus carried ~10k cross-instance messages/second with no losses,
+ * and stayed flat out to eight instances — comfortably past what live-cursor
+ * collaboration generates. The extension point below is the answer for anyone
+ * who does outgrow it.
+ */
+export type ChannelBusConfig =
+    /**
+     * In-process only — the historical behaviour. Broadcast and presence reach
+     * the clients connected to *this* instance and no further.
+     */
+    | { type: "memory" }
+    /**
+     * Postgres LISTEN/NOTIFY, reusing infrastructure the deployment already has.
+     *
+     * `pg_notify` caps a payload at 8000 bytes, so a broadcast larger than that
+     * is delivered cross-instance only on a *retained* channel, where the
+     * notification carries a pointer (`seq`) instead of the message and each
+     * receiver reads the body back from `rebase.channel_messages`. An oversized
+     * broadcast on an ephemeral channel is refused rather than silently
+     * delivered to half the cluster.
+     *
+     * NOTE: `LISTEN` needs a session-mode connection. Behind PgBouncer in
+     * transaction mode this must point at the database directly
+     * (`DATABASE_DIRECT_URL`), not at the pooler.
+     */
+    | {
+        type: "postgres";
+        /** Direct connection for the LISTEN client. Defaults to `DATABASE_DIRECT_URL`. */
+        connectionString?: string;
+        /**
+         * How long to coalesce outgoing frames into a single notification, in
+         * milliseconds. Defaults to 10.
+         *
+         * A notify is a query on your primary database, so under load this is
+         * the difference between one query per message and one per window. The
+         * window is leading-edge: a frame arriving when none is open goes out
+         * immediately, so an idle channel pays no added latency and only a
+         * sustained stream is batched.
+         *
+         * Set to 0 to disable coalescing and send every frame on its own.
+         */
+        batchWindowMs?: number;
+    };
+
+/**
+ * What `realtime.bus` accepts: a built-in transport by name, or any
+ * {@link ChannelBus} instance.
+ *
+ * ```typescript
+ * realtime: { bus: { type: "postgres" } }        // shipped
+ * realtime: { bus: new MyRedisChannelBus(url) }  // a separate package, or your own
+ * ```
+ */
+export type ChannelBusSetting = ChannelBusConfig | ChannelBus;
+
+/**
+ * Whether `setting` is an already-constructed transport rather than a request
+ * for a built-in one.
+ *
+ * Structural rather than nominal so that an instance from a *different copy* of
+ * `@rebasepro/types` — an entirely normal outcome of a separately versioned
+ * transport package — is still recognised.
+ */
+export function isChannelBusInstance(setting: ChannelBusSetting | undefined): setting is ChannelBus {
+    return typeof (setting as ChannelBus | undefined)?.publish === "function";
+}