@rebasepro/cms-types 0.17.3-canary.gdd23447 → 0.18.0

package/README.md

@@ -0,0 +1,49 @@
+# @rebasepro/cms-types
+
+Type definitions for the Rebase CMS: collection and property shapes, the entity
+and navigation models, and the translation keys the admin panel renders.
+
+This package contains **types only**. Nothing here executes — it is the
+vocabulary that the runtime, the generated SDK and the admin panel all agree on,
+kept in one package so a change to a collection's shape cannot mean one thing to
+the server and another to the panel.
+
+The runtime that consumes these types is
+[`@rebasepro/cms`](https://www.npmjs.com/package/@rebasepro/cms). If you are
+building an app, that is the package you want; you will normally get this one as
+a transitive dependency rather than installing it yourself.
+
+## Installation
+
+```bash
+npm install @rebasepro/cms-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)`.
+
+## Usage
+
+```ts
+import type { CollectionConfig } from "@rebasepro/cms-types";
+
+export const posts: CollectionConfig = {
+    name: "Posts",
+    slug: "posts",
+    table: "posts",
+    properties: {
+        title: { name: "Title", type: "string", validation: { required: true } },
+        body: { name: "Body", type: "string", admin: { multiline: true } }
+    }
+};
+```
+
+## Documentation
+
+- [Collections](https://rebase.pro/docs/backend/collections)
+- [Full documentation](https://rebase.pro/docs)
+
+## License
+
+MIT

package/dist/admin_collection.d.ts

@@ -15,7 +15,7 @@
  * `WhereFilterOp` mistake, and this block is far bigger than one union.
  */
 import type React from "react";
-import type { CollectionConfig, ComponentRef, FilterPreset, FilterValues, FirebaseCollectionConfig, FirebaseProperties, InferEntityType, MongoDBCollectionConfig, MongoProperties, OrderBySpec, PostgresCollectionConfig, PostgresProperties, User } from "@rebasepro/types";
+import type { CollectionCallbacks, CollectionConfig, ComponentRef, FilterPreset, FilterValues, OrderBySpec, PostgresCollectionConfig, User } from "@rebasepro/types";
 import type { AdditionalFieldDelegate, CollectionActionsProps, CollectionSize, DefaultSelectedViewBuilder, KanbanConfig, SelectionController, ViewMode } from "./collections.js";
 import type { EntityCustomView, FormViewConfig } from "./types/entity_views.js";
 import type { CollectionCustomView } from "./types/collection_views.js";
@@ -122,6 +122,48 @@ export type AdminCollectionOptions<M extends Record<string, unknown> = Record<st
      * If not specified, the list view uses a smart default (Title, Status, Date).
      */
     listProperties?: ColumnKey<M>[];
+    /**
+     * Lifecycle callbacks that run **in the browser**, in the admin panel.
+     *
+     * The twin of the collection's top-level `callbacks`, and the distinction is
+     * only where the code runs — the shape is identical:
+     *
+     * - `callbacks` runs on the server, on every path that reaches it (REST,
+     *   realtime, `dataAsAdmin`). Its bodies are stripped from the admin bundle,
+     *   so a secret read there never leaves the server.
+     * - `browserCallbacks` runs in the panel, and nowhere else. It ships to
+     *   every visitor.
+     *
+     * This exists for collections on a `direct` or `custom` transport — a
+     * Firestore collection the panel talks to itself, with no Rebase server in
+     * the request path. Nothing server-side sees those writes, so `callbacks`
+     * can never fire for them; this block is the only place their lifecycle
+     * logic can live.
+     *
+     * Two rules follow from "ships to every visitor", and neither is a style
+     * preference:
+     *
+     * 1. **No secrets.** No API keys, no `process.env`, no logic you would mind
+     *    a reader of the bundle seeing. Put that in `callbacks`.
+     * 2. **Not a security boundary.** A `browserCallbacks.afterRead` that
+     *    redacts a field redacts it *after* the browser already holds the row —
+     *    for a direct transport the raw document came straight from the store.
+     *    It is presentation. Redaction that has to hold belongs in `callbacks`,
+     *    or in the store's own rules.
+     *
+     * On a server-transport collection (the default) the server has already run
+     * `callbacks` before the row arrives, so a `browserCallbacks.afterRead`
+     * here runs *in addition* — write it to be idempotent, or don't write it.
+     *
+     * ```ts
+     * admin: {
+     *     browserCallbacks: {
+     *         afterRead: ({ row }) => ({ ...row, label: `${row.city} (${row.code})` })
+     *     }
+     * }
+     * ```
+     */
+    browserCallbacks?: CollectionCallbacks<M, USER>;
     /**
      * How a record of this collection shows up — its title, subtitle, image,
      * status, date and tags.
@@ -509,55 +551,13 @@ export type AdminCollectionOptions<M extends Record<string, unknown> = Record<st
  * writing one is an error — which is the guarantee a BaaS install depends on.
  */
 /**
- * Define a collection with the admin block type-checked.
- *
- * The same identity function as `defineCollection` in `@rebasepro/common` — which
- * is what a BaaS or headless project uses, and where `admin` does not exist at all
- * — with one difference: importing this one brings the augmentation with it, so
- * `admin: { icon, listProperties, kanban }` gets completion and a typo is an
- * error. See {@link AdminCollectionOptions}.
- *
- * Import it from the layer you are in. A project with an admin panel wants this
- * one; a project without one has no `admin` block to check.
- *
- * `const P` captures the literal property types, which is what gives
- * `admin.display`, `admin.sort` and `admin.propertiesOrder` completion over
- * the collection's own property keys rather than plain `string`.
+ * `defineCollection` lives in `./define_collection`, and this is why.
  *
- * @example
- * export default defineCollection({
- *     slug: "posts",
- *     table: "posts",
- *     properties: {
- *         title: { name: "Title", type: "string" },
- *         status: { name: "Status", type: "string" }
- *     },
- *     admin: {
- *         icon: "FileText",
- *         display: { title: "title" },   // completion: "title" | "status"
- *         listProperties: ["title", "status"]
- *     }
- * });
- *
- * @group Builder
+ * A collection file is loaded by the backend as well as by the panel, so the
+ * builder it imports has to be reachable without React. This module names
+ * `React` throughout — it describes the panel's option types — so the builder
+ * sits apart from it and the barrel exports both.
  */
-export declare function defineCollection<const P extends PostgresProperties, USER extends User = User>(collection: Omit<PostgresCollectionConfig<InferEntityType<P>, USER>, "properties"> & {
-    properties: P;
-}): PostgresCollectionConfig<InferEntityType<P>, USER> & {
-    properties: P;
-};
-/** Define a Firestore-backed collection with the admin block checked. @group Builder */
-export declare function defineCollection<const P extends FirebaseProperties, USER extends User = User>(collection: Omit<FirebaseCollectionConfig<InferEntityType<P>, USER>, "properties"> & {
-    properties: P;
-}): FirebaseCollectionConfig<InferEntityType<P>, USER> & {
-    properties: P;
-};
-/** Define a MongoDB-backed collection with the admin block checked. @group Builder */
-export declare function defineCollection<const P extends MongoProperties, USER extends User = User>(collection: Omit<MongoDBCollectionConfig<InferEntityType<P>, USER>, "properties"> & {
-    properties: P;
-}): MongoDBCollectionConfig<InferEntityType<P>, USER> & {
-    properties: P;
-};
 /**
  * Re-exported from `@rebasepro/types`, where the list has to live: the ts-morph
  * schema editor in `@rebasepro/server` needs it to know which keys go inside the
@@ -573,12 +573,8 @@ export type { AdminCollectionKey } from "@rebasepro/types";
  * Core's list, re-exported through a `satisfies` clause that is the agreement
  * check: a key core names that is not an option here fails to compile, and
  * `satisfies` keeps the literal tuple type rather than widening it to `string[]`.
- *
- * The reverse direction — an option missing from core's list — has no type-level
- * expression, since there is no exhaustiveness check over an optional-property
- * keyof. `test/admin_collection.test.ts` counts them instead.
  */
-export declare const ADMIN_COLLECTION_KEYS: readonly ["Actions", "additionalFields", "alwaysApplyDefaultValues", "components", "customViews", "defaultEntityAction", "defaultFilter", "defaultSelectedView", "defaultSize", "defaultViewMode", "disableDefaultActions", "display", "enabledViews", "entityActions", "entityViews", "exportable", "filterPresets", "fixedFilter", "form", "formAutoSave", "formView", "group", "hideFromEntityViews", "hideFromNavigation", "hideIdFromCollection", "hideIdFromForm", "icon", "includeJsonView", "inlineEditing", "kanban", "listProperties", "localChangesBackup", "openEntityMode", "orderProperty", "pagination", "previewProperties", "propertiesOrder", "selectionController", "selectionEnabled", "sideDialogWidth", "sort"];
+export declare const ADMIN_COLLECTION_KEYS: readonly ["Actions", "additionalFields", "alwaysApplyDefaultValues", "browserCallbacks", "components", "customViews", "defaultEntityAction", "defaultFilter", "defaultSelectedView", "defaultSize", "defaultViewMode", "disableDefaultActions", "display", "enabledViews", "entityActions", "entityViews", "exportable", "filterPresets", "fixedFilter", "form", "formAutoSave", "formView", "group", "hideFromEntityViews", "hideFromNavigation", "hideIdFromCollection", "hideIdFromForm", "icon", "includeJsonView", "inlineEditing", "kanban", "listProperties", "localChangesBackup", "openEntityMode", "orderProperty", "pagination", "previewProperties", "propertiesOrder", "selectionController", "selectionEnabled", "sideDialogWidth", "sort"];
 /**
  * A collection as the admin panel works with it: the contract with the `admin`
  * block flattened onto the top level.

package/dist/collections.d.ts

@@ -12,7 +12,7 @@
  * That is what made them safe to lift: they were never part of the BaaS surface,
  * only stored next to it.
  */
-import React from "react";
+import type React from "react";
 import type { Entity, EntityStatus, FilterValues, OrderByTuple, User } from "@rebasepro/types";
 import type { RebaseContext } from "./rebase_context.js";
 import type { AdminCollection, PropertyPath } from "@rebasepro/cms-types";

package/dist/controllers/customization_controller.d.ts

@@ -5,7 +5,7 @@ import type { EntityCustomView } from "../types/entity_views.js";
 import type { CollectionCustomView } from "../types/collection_views.js";
 import type { RebasePlugin } from "../types/plugins.js";
 import type { PropertyConfig } from "../types/property_config.js";
-import type { SlotContribution } from "../types/slots.js";
+import type { AnySlotContribution } from "../types/slots.js";
 import type { ComponentOverrideMap } from "../types/component_overrides.js";
 export type CustomizationController = {
     /**
@@ -19,7 +19,7 @@ export type CustomizationController = {
     /**
      * Pre-merged slots from plugins + direct slot contributions.
      */
-    resolvedSlots: SlotContribution[];
+    resolvedSlots: AnySlotContribution[];
     /**
      * List of additional custom views for entities.
      * You can use the key to reference the custom view in

package/dist/controllers/navigation.d.ts

@@ -125,7 +125,6 @@ export interface AppView {
      * You can use any of the icons in the Lucide specs:
      * https://lucide.dev/icons/
      * e.g. 'ShoppingCart' or 'User'
-     * Find all the icons in https://rebase.pro/docs/icons
      */
     icon?: string | React.ReactNode;
     /**

package/dist/controllers/registry.d.ts

@@ -67,8 +67,28 @@ export interface RebaseCMSConfig<EC extends AdminCollection = AdminCollection> {
     basePath?: string;
 }
 export interface RebaseStudioConfig {
+    /**
+     * Which built-in tools to register. Omit for all of them; pass a shorter
+     * list to hide the rest.
+     */
     tools?: ("sql" | "js" | "rls" | "schema" | "storage" | "cron" | "schema-visualizer" | "branches" | "backups" | "api" | "logs" | "api-keys")[];
+    /** Replaces the Studio landing page. */
     homePage?: ReactNode;
+    /**
+     * Your own tools, added beside the built-in ones.
+     *
+     * These are ordinary {@link AppView}s — the only thing that makes a view a
+     * Studio tool rather than a CMS view is being registered here rather than
+     * on `<RebaseCMS views>`: the drawer shows CMS views in content mode and
+     * these in Studio mode.
+     *
+     * @example
+     * ```tsx
+     * <RebaseStudio devViews={[
+     *     { slug: "queues", name: "Queues", group: "Compute", view: <QueuesView/> }
+     * ]}/>
+     * ```
+     */
     devViews?: AppView[];
 }
 /**

package/dist/define_collection.d.ts

@@ -0,0 +1,132 @@
+/**
+ * `defineCollection` — the admin-aware builder, in a module a backend can load.
+ *
+ * This is the function every scaffolded collection file imports, and it must be
+ * reachable from a Node process that has no React and no DOM. So it lives here,
+ * apart from `admin_collection.ts` (which describes the panel's option types and
+ * names `React` throughout) and well away from `collections.ts` (the panel's
+ * view models, which import React as a value).
+ *
+ * The side-effect import below is the other half of what the import buys you:
+ * `augment.ts` is what declares `admin` on `BaseCollectionConfig` and on every
+ * property type, so importing this builder brings the block's type-checking with
+ * it. It is types only, and compiles to nothing.
+ */
+import "./augment.js";
+import type { FirebaseCollectionConfig, FirebaseProperties, FirebaseProperty, InferEntityType, MongoDBCollectionConfig, MongoProperties, MongoProperty, PostgresCollectionConfig, PostgresProperties, PostgresProperty, Properties, Property, StrictProperties, User } from "@rebasepro/types";
+import { type ResourceRef } from "@rebasepro/types";
+/**
+ * The engines a collection can name. Absent means Postgres.
+ *
+ * The discriminant that replaced three overloads of `defineCollection`. See
+ * {@link CollectionConfigForEngine} for why that mattered.
+ */
+type CollectionEngine = "postgres" | "firestore" | "mongodb";
+/**
+ * The concrete collection type an `engine` selects.
+ *
+ * `defineCollection` used to be three overloads — one per engine — and overload
+ * resolution is what made its errors unreadable. When no overload matches,
+ * TypeScript emits **one** diagnostic at the call site listing each overload's
+ * *first* failure, so:
+ *
+ *  - a bad `defaultValue` **and** a misspelled `admin.display.title` in the same
+ *    collection reported only the first. Fixing it revealed the second on the
+ *    next run, one per edit-compile cycle;
+ *  - the error landed on `defineCollection(`, not on the key that was wrong;
+ *  - and every Postgres collection's error dragged `FirebaseCollectionConfig`
+ *    and `MongoDBCollectionConfig` through the message, naming two engines the
+ *    author had not mentioned and does not use.
+ *
+ * With one signature there is no resolution to fail: each error is reported
+ * where it is, all of them at once, against the one config type the `engine`
+ * selects.
+ */
+type CollectionConfigForEngine<E, P, USER extends User> = E extends "firestore" ? FirebaseCollectionConfig<EntityShapeOf<P>, USER> : E extends "mongodb" ? MongoDBCollectionConfig<EntityShapeOf<P>, USER> : PostgresCollectionConfig<EntityShapeOf<P>, USER>;
+/**
+ * `InferEntityType`, tolerant of a property map that has an error in it.
+ *
+ * `P` is deliberately **unconstrained** on the builder, and this is why. A
+ * constraint TypeScript cannot satisfy is a constraint it silently falls back
+ * from: one property with a bad `defaultValue` made `P extends PostgresProperties`
+ * fail, `P` became `PostgresProperties`, `M` became `Record<string, unknown>`,
+ * and every `admin` key — `display.title`, `listProperties`, `propertiesOrder` —
+ * widened to `string` and stopped being checked. So a collection with two
+ * mistakes reported one, and reported the second only after the first was fixed.
+ *
+ * With no constraint, `keyof P` survives a bad property and the `admin` block is
+ * still checked against the real key set. Exactness and the engine gate move
+ * into `StrictProperties`, which reports them on the property itself.
+ */
+type EntityShapeOf<P> = InferEntityType<{
+    [K in keyof P]: P[K] extends Property ? P[K] : Property;
+}>;
+/** The property union an engine admits — the engine gate, as a type. */
+type PropertyForEngine<E> = E extends "firestore" ? FirebaseProperty : E extends "mongodb" ? MongoProperty : PostgresProperty;
+/** {@link PropertyForEngine} as a property map, for the `P` constraint. */
+type PropertiesForEngine<E> = E extends "firestore" ? FirebaseProperties : E extends "mongodb" ? MongoProperties : PostgresProperties;
+/**
+ * Define a collection with the admin block type-checked.
+ *
+ * The same identity function as `defineCollection` in `@rebasepro/common` — which
+ * is what a BaaS or headless project uses, and where `admin` does not exist at all
+ * — with one difference: importing this one brings the augmentation with it, so
+ * `admin: { icon, listProperties, kanban }` gets completion and a typo is an
+ * error. See {@link AdminCollectionOptions}.
+ *
+ * Import it from the layer you are in. A project with an admin panel wants this
+ * one; a project without one has no `admin` block to check.
+ *
+ * `const P` captures the literal property types, which is what gives
+ * `admin.display`, `admin.sort` and `admin.propertiesOrder` completion over
+ * the collection's own property keys rather than plain `string`.
+ *
+ * @example
+ * export default defineCollection({
+ *     slug: "posts",
+ *     table: "posts",
+ *     properties: {
+ *         title: { name: "Title", type: "string" },
+ *         status: { name: "Status", type: "string" }
+ *     },
+ *     admin: {
+ *         icon: "FileText",
+ *         display: { title: "title" },   // completion: "title" | "status"
+ *         listProperties: ["title", "status"]
+ *     }
+ * });
+ *
+ * @group Builder
+ */
+export declare function defineCollection<const E extends CollectionEngine = "postgres", 
+/**
+ * The properties, **constrained**. This is what checks them, and — just as
+ * importantly — what supplies the contextual type inside them: without a
+ * constraint the parameter of an inline
+ * `callbacks: { beforeSave: ({ value }) => … }` has nothing to be typed
+ * from, and TypeScript reports an implicit `any` on a callback the author
+ * wrote correctly.
+ */
+const P extends PropertiesForEngine<E> & Properties = PropertiesForEngine<E> & Properties, 
+/**
+ * The properties again, **unconstrained**, and this is why there are two.
+ *
+ * A constraint TypeScript cannot satisfy is one it silently falls back
+ * from: one property with a bad `defaultValue` made `P` become
+ * `PostgresProperties`, the entity shape become `Record<string, unknown>`,
+ * and every `admin` key — `display.title`, `listProperties`,
+ * `propertiesOrder` — widen to `string` and stop being checked. A
+ * collection with two mistakes reported one, and revealed the second only
+ * after the first was fixed.
+ *
+ * `KEYS` has no constraint to fall back from, so `keyof KEYS` survives a bad
+ * property and the `admin` block is still checked against the real key set.
+ */
+const KEYS = Properties, USER extends User = User>(collection: Omit<CollectionConfigForEngine<E, KEYS, USER>, "properties" | "engine" | "dataSource"> & {
+    engine?: E;
+    properties: StrictProperties<P, PropertyForEngine<E>> & KEYS;
+    dataSource?: ResourceRef;
+}): CollectionConfigForEngine<E, KEYS, USER> & {
+    properties: KEYS;
+};
+export {};

package/dist/index.d.ts

@@ -11,6 +11,7 @@
 import "./augment.js";
 export * from "./types/property_options.js";
 export * from "./react_component_ref.js";
+export * from "./define_collection.js";
 export * from "./collections.js";
 export * from "./admin_collection.js";
 export * from "./rebase_context.js";

package/dist/index.es.js

@@ -1,4 +1,4 @@
-import { ADMIN_COLLECTION_KEYS as ADMIN_COLLECTION_KEYS$1, ADMIN_PROPERTY_KEYS as ADMIN_PROPERTY_KEYS$1, nestAdminCollectionKeys } from "@rebasepro/types";
+import { ADMIN_COLLECTION_KEYS as ADMIN_COLLECTION_KEYS$1, ADMIN_PROPERTY_KEYS as ADMIN_PROPERTY_KEYS$1, nestAdminCollectionKeys, resolveResourceRefs } from "@rebasepro/types";
 //#region src/types/property_options.ts
 /**
 * Core's list, re-exported through the same `satisfies` agreement check that
@@ -39,19 +39,23 @@ function asReactComponent(component) {
 	return component;
 }
 //#endregion
-//#region src/admin_collection.ts
-/** Identity at runtime; the overloads above are the whole point. @group Builder */
+//#region src/define_collection.ts
+/**
+* At runtime this records the collection as data: a resource handle written
+* where a key belongs — `dataSource: analytics`, `storageSource: media` — is
+* replaced by its key, so what leaves here serialises and compares like the
+* string it always was. The signature above is the rest of the point.
+* @group Builder
+*/
 function defineCollection(collection) {
-	return collection;
+	return resolveResourceRefs(collection);
 }
+//#endregion
+//#region src/admin_collection.ts
 /**
 * Core's list, re-exported through a `satisfies` clause that is the agreement
 * check: a key core names that is not an option here fails to compile, and
 * `satisfies` keeps the literal tuple type rather than widening it to `string[]`.
-*
-* The reverse direction — an option missing from core's list — has no type-level
-* expression, since there is no exhaustiveness check over an optional-property
-* keyof. `test/admin_collection.test.ts` counts them instead.
 */
 var ADMIN_COLLECTION_KEYS = ADMIN_COLLECTION_KEYS$1;
 /**