@rebasepro/types 0.7.0 → 0.9.0

package/src/types/component_overrides.ts

@@ -1,4 +1,6 @@
 import type React from "react";
+import type { Property } from "./properties";
+import type { WhereFilterOp } from "./filter-operators";
 
 // ── Scoped component name unions ──────────────────────────────────────
 
@@ -43,13 +45,14 @@ export type CollectionComponentName =
     | "Collection.Card"
     | "Collection.EmptyState"
     | "Collection.Actions"
+    | "Collection.FilterField"
 
     // ── Entity / Form ──
     | "Entity.Form"
-    | "Entity.FormActions"
-    | "Entity.DetailView"
+    | "EditView.FormActions"
+    | "DetailView"
     | "Entity.SidePanel"
-    | "Entity.Preview"
+    | "EntityPreview"
     | "Entity.MissingReference";
 
 /**
@@ -58,6 +61,70 @@ export type CollectionComponentName =
  */
 export type OverridableComponentName = AppComponentName | CollectionComponentName;
 
+/**
+ * Props received by a filter field component — whether it is a built-in
+ * per-type field, a property-level replacement (`property.ui.Filter`), or a
+ * `"Collection.FilterField"` override.
+ *
+ * The `operators` list is **already resolved**: it is the intersection of the
+ * engine's {@link DataSourceCapabilities.filterOperators}, the property-type
+ * defaults, and any `property.ui.filterOperators` narrowing. A custom field
+ * should only offer operators from this list — anything else may throw at
+ * query time on engines that cannot execute it.
+ *
+ * @example
+ * ```tsx
+ * function MyStatusFilter({ value, setValue, operators }: FilterFieldBindingProps) {
+ *     return (
+ *         <select
+ *             value={value?.[1] as string ?? ""}
+ *             onChange={e => setValue(e.target.value ? ["==", e.target.value] : undefined)}>
+ *             <option value="">Any</option>
+ *             <option value="active">Active</option>
+ *             <option value="archived">Archived</option>
+ *         </select>
+ *     );
+ * }
+ * ```
+ *
+ * @group Component Overrides
+ */
+export interface FilterFieldBindingProps {
+    /** Key of the property being filtered (the column id). */
+    propertyKey: string;
+
+    /**
+     * The resolved property. For array properties this is the **item**
+     * property (`property.of`), with `isArray` set to true.
+     */
+    property: Property;
+
+    /** True when the underlying property is an array of `property`. */
+    isArray: boolean;
+
+    /**
+     * Operators this field may offer, already narrowed by engine
+     * capabilities, property-type defaults, and `property.ui.filterOperators`.
+     */
+    operators: readonly WhereFilterOp[];
+
+    /** Current filter condition for this property, if any. */
+    value?: [WhereFilterOp, unknown];
+
+    /** Set (or clear, with `undefined`) the filter condition. */
+    setValue: (value?: [WhereFilterOp, unknown]) => void;
+
+    /** Display title for the field (usually the property name). */
+    title?: string;
+
+    /**
+     * Coordination flags used by fields that open their own dialogs
+     * (e.g. the reference picker hides the parent filters dialog).
+     */
+    hidden?: boolean;
+    setHidden?: (hidden: boolean) => void;
+}
+
 // ── Override entry ────────────────────────────────────────────────────
 
 /**
@@ -89,7 +156,7 @@ export type OverridableComponentName = AppComponentName | CollectionComponentNam
  *
  * @group Component Overrides
  */
-export interface ComponentOverride<P = any> {
+export interface ComponentOverride<P = Record<string, unknown>> {
     /**
      * The replacement component. Receives the same props as the built-in
      * component it replaces.
@@ -161,7 +228,7 @@ export type CollectionComponentOverrideMap = {
  *         "HomePage": { Component: MyDashboard },
  *
  *         // Collection defaults: apply to ALL collections
- *         "Entity.FormActions": {
+ *         "EditView.FormActions": {
  *             Component: MyFormActions,
  *             wrap: true
  *         },

package/src/types/cron.ts

@@ -60,7 +60,16 @@ export interface CronJobContext {
     /** A simple logger scoped to this job run. */
     log: (...args: unknown[]) => void;
 
-    /** The RebaseClient instance to interact with the database. */
+    /**
+     * The server-side {@link RebaseClient}. This is the **same singleton**
+     * exposed as `rebase` (imported from `@rebasepro/server-core`) and as
+     * `context` in collection callbacks — it is only named `client` here.
+     *
+     * 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.
+     */
     client: RebaseClient;
 }
 

package/src/types/data_source.ts

@@ -1,3 +1,5 @@
+import { ALL_WHERE_FILTER_OPS, WhereFilterOp } from "./filter-operators";
+
 /**
  * Describes the capabilities and features supported by a data source (driver).
  *
@@ -35,6 +37,17 @@ export interface DataSourceCapabilities {
     /** Does this source support real-time listeners? */
     supportsRealtime: boolean;
 
+    /**
+     * Canonical filter operators this engine can execute.
+     *
+     * The admin UI intersects this set with the property-type defaults and
+     * any per-property narrowing (`property.ui.filterOperators`) to decide
+     * which operators to offer in filter fields — so an engine that cannot
+     * run `ilike` (e.g. Firestore) never shows a "Contains" filter that
+     * would throw at query time.
+     */
+    filterOperators: readonly WhereFilterOp[];
+
     // ── Admin capability flags ───────────────────────────────────────
     /** Does this source support SQL admin operations (SQL editor, EXPLAIN, etc.)? */
     supportsSQLAdmin: boolean;
@@ -102,9 +115,11 @@ export interface DataSourceDefinition {
     engine: string;
 
     /**
-     * How the frontend reaches this source. Defaults to `"server"`.
+     * How the frontend reaches this source. Optional — when omitted it is
+     * inferred: `"direct"` if the definition carries a client-side driver,
+     * `"server"` otherwise.
      */
-    transport: DataSourceTransport;
+    transport?: DataSourceTransport;
 
     /**
      * The physical database/schema/Firestore-database within the engine.
@@ -149,6 +164,7 @@ export const POSTGRES_CAPABILITIES: DataSourceCapabilities = {
     supportsReferences: false,
     supportsColumnTypes: true,
     supportsRealtime: true,
+    filterOperators: ALL_WHERE_FILTER_OPS,
     supportsSQLAdmin: true,
     supportsDocumentAdmin: false,
     supportsSchemaAdmin: true
@@ -164,6 +180,10 @@ export const FIREBASE_CAPABILITIES: DataSourceCapabilities = {
     supportsReferences: true,
     supportsColumnTypes: false,
     supportsRealtime: true,
+    // Firestore has no SQL pattern matching — the driver throws on the LIKE
+    // family, so the UI must never offer it.
+    filterOperators: ALL_WHERE_FILTER_OPS.filter(op =>
+        op !== "like" && op !== "ilike" && op !== "not-like" && op !== "not-ilike"),
     supportsSQLAdmin: false,
     supportsDocumentAdmin: false,
     supportsSchemaAdmin: false
@@ -179,6 +199,7 @@ export const MONGODB_CAPABILITIES: DataSourceCapabilities = {
     supportsReferences: true,
     supportsColumnTypes: false,
     supportsRealtime: false,
+    filterOperators: ALL_WHERE_FILTER_OPS,
     supportsSQLAdmin: false,
     supportsDocumentAdmin: true,
     supportsSchemaAdmin: true
@@ -198,6 +219,7 @@ export const DEFAULT_CAPABILITIES: DataSourceCapabilities = {
     supportsReferences: true,
     supportsColumnTypes: true,
     supportsRealtime: true,
+    filterOperators: ALL_WHERE_FILTER_OPS,
     supportsSQLAdmin: true,
     supportsDocumentAdmin: true,
     supportsSchemaAdmin: true
@@ -211,13 +233,13 @@ const CAPABILITIES_REGISTRY: Record<string, DataSourceCapabilities> = {
 };
 
 /**
- * Look up capabilities for a given driver key.
- * If `driver` is undefined or not found, returns `DEFAULT_CAPABILITIES`.
+ * Look up capabilities for a given engine key.
+ * If `engine` is undefined or not found, returns `DEFAULT_CAPABILITIES`.
  * @group Models
  */
-export function getDataSourceCapabilities(driver?: string): DataSourceCapabilities {
-    if (!driver) return POSTGRES_CAPABILITIES; // postgres is the default driver
-    return CAPABILITIES_REGISTRY[driver] ?? DEFAULT_CAPABILITIES;
+export function getDataSourceCapabilities(engine?: string): DataSourceCapabilities {
+    if (!engine) return POSTGRES_CAPABILITIES; // postgres is the default engine
+    return CAPABILITIES_REGISTRY[engine] ?? DEFAULT_CAPABILITIES;
 }
 
 /**

package/src/types/database_adapter.ts

@@ -21,7 +21,7 @@
  */
 
 import type { DataDriver } from "../controllers/data_driver";
-import type { EntityCollection } from "./collections";
+import type { CollectionConfig } from "./collections";
 import type {
     CollectionRegistryInterface,
     DatabaseAdmin,
@@ -29,6 +29,7 @@ import type {
     RealtimeProvider,
     BootstrappedAuth
 } from "./backend";
+import type { HistoryConfig } from "../controllers/client";
 
 /**
  * A `DatabaseAdapter` provides data persistence for Rebase.
@@ -75,7 +76,7 @@ export interface DatabaseAdapter {
      * Return `undefined` if the database does not support history.
      */
     initializeHistory?(
-        config: unknown,
+        config: HistoryConfig,
         driverResult: InitializedDriver,
     ): Promise<{ historyService: unknown } | undefined>;
 
@@ -114,7 +115,7 @@ export interface DatabaseAdapter {
  */
 export interface DatabaseAdapterInitConfig {
     /** Registered collection definitions. */
-    collections: EntityCollection[];
+    collections: CollectionConfig[];
     /** The shared collection registry to register into. */
     collectionRegistry: CollectionRegistryInterface;
 }

package/src/types/entities.ts

@@ -5,7 +5,7 @@
 export type EntityStatus = "new" | "existing" | "copy";
 
 /**
- * Representation of an entity fetched from the driver
+ * Representation of a entity fetched from the driver
  * @group Models
  */
 export interface Entity<M extends Record<string, unknown> = Record<string, unknown>> {
@@ -47,7 +47,7 @@ export interface Entity<M extends Record<string, unknown> = Record<string, unkno
 export type EntityValues<M extends Record<string, unknown>> = M;
 
 /**
- * Props for creating an EntityReference
+ * Props for creating a EntityReference
  */
 export interface EntityReferenceProps {
     /** ID of the entity */
@@ -61,7 +61,7 @@ export interface EntityReferenceProps {
 }
 
 /**
- * Class used to create a reference to an entity in a different path.
+ * Class used to create a reference to a entity in a different path.
  *
  * @example
  * // Simple reference (most common case - single driver, single db)
@@ -99,7 +99,7 @@ export class EntityReference {
     readonly databaseId?: string;
 
     /**
-     * Create a reference to an entity.
+     * Create a reference to a entity.
      *
      * @example
      * // Simple reference (most common case)
@@ -148,7 +148,7 @@ export class EntityReference {
 }
 
 /**
- * Class used to create a reference to an entity in a different path
+ * Class used to create a reference to a entity in a different path
  */
 export class EntityRelation {
 
@@ -167,9 +167,9 @@ export class EntityRelation {
      * Pre-fetched data payload to eliminate N+1 queries.
      * When present, clients can use this directly instead of fetching.
      */
-    readonly data?: Entity;
+    readonly data?: Record<string, unknown>;
 
-    constructor(id: string | number, path: string, data?: Entity) {
+    constructor(id: string | number, path: string, data?: Record<string, unknown>) {
         this.id = id;
         this.path = path;
         this.data = data;

package/src/types/entity_actions.tsx

@@ -1,13 +1,13 @@
 import React from "react";
 import type { Entity } from "./entities";
-import type { EntityCollection, SelectionController } from "./collections";
+import type { CollectionConfig, SelectionController } from "./collections";
 import type { FormContext } from "./entity_views";
 import type { User } from "../users";
 import type { RebaseContext } from "../rebase_context";
-import type { SideEntityController } from "../controllers/side_entity_controller";
+import type { SidePanelController } from "../controllers/side_panel_controller";
 
 /**
- * An entity action is a custom action that can be performed on an entity.
+ * A entity action is a custom action that can be performed on a entity.
  * They are displayed in the entity view and in the collection view.
  */
 export interface EntityAction<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
@@ -72,7 +72,7 @@ export type EntityActionClickProps<M extends Record<string, unknown>, USER exten
     context?: RebaseContext<USER>;
 
     path?: string;
-    collection?: EntityCollection<M>;
+    collection?: CollectionConfig<M>;
 
     /**
      * Optional form context, present if the action is being called from a form.
@@ -83,7 +83,7 @@ export type EntityActionClickProps<M extends Record<string, unknown>, USER exten
     /**
      * Present if this actions is being called from a side dialog only
      */
-    sideEntityController?: SideEntityController;
+    sidePanelController?: SidePanelController;
 
     /**
      * Is the action being called from the collection view or from the entity form view?
@@ -113,12 +113,12 @@ export type EntityActionClickProps<M extends Record<string, unknown>, USER exten
     unhighlightEntity?: (entity: Entity<Record<string, unknown>>) => void;
 
     /**
-     * Optional function to navigate back (e.g. when deleting an entity or navigating from a form)
+     * Optional function to navigate back (e.g. when deleting a entity or navigating from a form)
      */
     navigateBack?: () => void;
 
     /**
-     * Callback to be called when the collection changes, e.g. after an entity is deleted or created.
+     * Callback to be called when the collection changes, e.g. after a entity is deleted or created.
      */
     onCollectionChange?: () => void;
 

package/src/types/entity_callbacks.ts

@@ -1,76 +1,88 @@
-import type { EntityCollection } from "./collections";
-import type { Entity, EntityStatus, EntityValues } from "./entities";
+import type { CollectionConfig } from "./collections";
+import type { EntityStatus, EntityValues } from "./entities";
 import type { User } from "../users";
 import type { RebaseCallContext } from "../rebase_context";
 
 /**
- * This interface defines all the callbacks that can be used when an entity
- * is being created, updated or deleted.
- * Useful for adding your own logic or blocking the execution of the operation.
+ * Lifecycle callbacks for entity CRUD operations.
+ *
+ * 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`.
+ *
+ * When both global and per-collection callbacks are registered, execution
+ * order is: **global → collection → property callbacks**.
+ *
  * @group Models
  */
-export type EntityCallbacks<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> = {
+export type CollectionCallbacks<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> = {
 
     /**
-     * Callback used after fetching data
+     * Callback used after fetching data.
+     *
+     * Fires on every read path. Use this for security-critical redaction
+     * (PII masking, row filtering) — no read path bypasses it.
+     *
      * @param props
      */
-    afterRead?(props: EntityAfterReadProps<M, USER>)
-        : Promise<Entity<M>> | Entity<M>;
+    afterRead?(props: AfterReadProps<M, USER>)
+        : Promise<Record<string, unknown>> | Record<string, unknown>;
 
 
     /**
      * Callback used before saving, you need to return the values that will get
      * saved. If you throw an error in this method the process stops, and an
-     * error snackbar gets displayed.
+     * HTTP error response is returned to the client.
      * This runs after schema validation.
+     *
      * @param props
      */
-    beforeSave?(props: EntityBeforeSaveProps<M, USER>)
+    beforeSave?(props: BeforeSaveProps<M, USER>)
         : Promise<Partial<EntityValues<M>>> | Partial<EntityValues<M>>;
 
     /**
-     * Callback used when save is successful
+     * Callback used when save is successful.
+     *
      * @param props
      */
-    afterSave?(props: EntityAfterSaveProps<M, USER>)
+    afterSave?(props: AfterSaveProps<M, USER>)
         : Promise<void> | void;
 
     /**
      * Callback used when saving fails
      * @param props
      */
-    afterSaveError?(props: EntityAfterSaveErrorProps<M, USER>)
+    afterSaveError?(props: AfterSaveErrorProps<M, USER>)
         : Promise<void> | void;
 
     /**
      * Callback used before the entity is deleted.
      * If you throw an error in this method the process stops, and an
-     * error snackbar gets displayed.
+     * HTTP error response is returned to the client.
      *
      * @param props
      */
-    beforeDelete?(props: EntityBeforeDeleteProps<M, USER>): Promise<boolean | void> | boolean | void;
+    beforeDelete?(props: BeforeDeleteProps<M, USER>): Promise<boolean | void> | boolean | void;
 
     /**
      * Callback used after the entity is deleted.
      *
      * @param props
      */
-    afterDelete?(props: EntityAfterDeleteProps<M, USER>): void;
+    afterDelete?(props: AfterDeleteProps<M, USER>): Promise<void> | void;
 
 }
 
 /**
- * Parameters passed to hooks when an entity is fetched
+ * Parameters passed to hooks when a entity is fetched
  * @group Models
  */
-export interface EntityAfterReadProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
+export interface AfterReadProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
 
     /**
      * Collection of the entity
      */
-    collection: EntityCollection<M>;
+    collection: CollectionConfig<M>;
 
     /**
      * Full path of the CMS where this collection is being fetched.
@@ -79,9 +91,9 @@ export interface EntityAfterReadProps<M extends Record<string, unknown> = Record
     path: string;
 
     /**
-     * Fetched entity
+     * Fetched row (flat — `{ id, ...columns }`)
      */
-    entity: Entity<M>
+    row: Record<string, unknown>
 
     /**
      * Context of the app status
@@ -90,34 +102,34 @@ export interface EntityAfterReadProps<M extends Record<string, unknown> = Record
 }
 
 /**
- * Parameters passed to hooks before an entity is saved
+ * Parameters passed to hooks before a entity is saved
  * @group Models
  */
-export type EntityBeforeSaveProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> =
-    Omit<EntityAfterSaveProps<M, USER>, "entityId">
+export type BeforeSaveProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> =
+    Omit<AfterSaveProps<M, USER>, "id">
     & {
-        entityId?: string | number;
+        id?: string | number;
     }
 /**
- * Parameters passed to hooks before an entity is saved
+ * Parameters passed to hooks before a entity is saved
  * @group Models
  */
-export type EntityAfterSaveErrorProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> =
-    Omit<EntityAfterSaveProps<M, USER>, "entityId">
+export type AfterSaveErrorProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> =
+    Omit<AfterSaveProps<M, USER>, "id">
     & {
-        entityId?: string | number;
+        id?: string | number;
     }
 
 /**
- * Parameters passed to hooks when an entity is saved
+ * Parameters passed to hooks when a entity is saved
  * @group Models
  */
-export interface EntityAfterSaveProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
+export interface AfterSaveProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
 
     /**
      * Resolved collection of the entity
      */
-    collection: EntityCollection<M>;
+    collection: CollectionConfig<M>;
 
     /**
      * Full path of the CMS where this entity is being saved.
@@ -128,7 +140,7 @@ export interface EntityAfterSaveProps<M extends Record<string, unknown> = Record
     /**
      * ID of the entity
      */
-    entityId: string | number;
+    id: string | number;
 
     /**
      * Values being saved
@@ -152,15 +164,15 @@ export interface EntityAfterSaveProps<M extends Record<string, unknown> = Record
 }
 
 /**
- * Parameters passed to hooks when an entity is deleted
+ * Parameters passed to hooks when a entity is deleted
  * @group Models
  */
-export interface EntityBeforeDeleteProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
+export interface BeforeDeleteProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
 
     /**
      * collection of the entity being deleted
      */
-    collection: EntityCollection<M>;
+    collection: CollectionConfig<M>;
 
     /**
      * Path of the parent collection
@@ -170,12 +182,12 @@ export interface EntityBeforeDeleteProps<M extends Record<string, unknown> = Rec
     /**
      * Deleted entity id
      */
-    entityId: string | number;
+    id: string | number;
 
     /**
-     * Deleted entity
+     * Deleted row (flat — `{ id, ...columns }`)
      */
-    entity: Entity<M>;
+    row: Record<string, unknown>;
 
     /**
      * Context of the app status
@@ -184,15 +196,15 @@ export interface EntityBeforeDeleteProps<M extends Record<string, unknown> = Rec
 }
 
 /**
- * Parameters passed to hooks after an entity is deleted
+ * Parameters passed to hooks after a entity is deleted
  * @group Models
  */
-export interface EntityAfterDeleteProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
+export interface AfterDeleteProps<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
 
     /**
      * collection of the entity being deleted
      */
-    collection: EntityCollection<M>;
+    collection: CollectionConfig<M>;
 
     /**
      * Path of the parent collection
@@ -202,16 +214,15 @@ export interface EntityAfterDeleteProps<M extends Record<string, unknown> = Reco
     /**
      * Deleted entity id
      */
-    entityId: string | number;
+    id: string | number;
 
     /**
-     * Deleted entity
+     * Deleted row (flat — `{ id, ...columns }`)
      */
-    entity: Entity<M>;
+    row: Record<string, unknown>;
 
     /**
      * Context of the app status
      */
     context: RebaseCallContext<USER>;
 }
-

package/src/types/entity_views.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import type { Entity, EntityValues } from "./entities";
-import type { EntityCollection } from "./collections";
+import type { CollectionConfig } from "./collections";
 import type { FormexController } from "./formex";
 import type { ComponentRef } from "./component_ref";
 
@@ -37,7 +37,7 @@ export interface FormContext<M extends Record<string, unknown> = Record<string,
     /**
      * Collection of the entity being modified
      */
-    collection?: EntityCollection<M>;
+    collection?: CollectionConfig<M>;
 
     /**
      * Entity id, it can be undefined if it's a new entity
@@ -105,7 +105,7 @@ export type FormViewConfig<M extends Record<string, unknown> = Record<string, un
 };
 
 export interface EntityCustomViewParams<M extends Record<string, unknown> = Record<string, unknown>> {
-    collection: EntityCollection<M>;
+    collection: CollectionConfig<M>;
     entity?: Entity<M>;
     modifiedValues?: EntityValues<M>;
     formContext: FormContext<M>;