@rebasepro/types 0.1.2 → 0.2.1

package/src/types/collections.ts

@@ -8,7 +8,7 @@ import type { EntityOverrides } from "./entity_overrides";
 import type { User } from "../users";
 import type { RebaseContext } from "../rebase_context";
 import type { Relation } from "./relations";
-import type { EntityCustomView } from "./entity_views";
+import type { EntityCustomView, EntityDetailViewConfig } from "./entity_views";
 import type { EntityAction } from "./entity_actions";
 import type { ComponentRef } from "./component_ref";
 
@@ -134,7 +134,26 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      * When editing an entity, you can choose to open the entity in a side dialog
      * or in a full screen dialog. Defaults to `full_screen`.
      */
-    openEntityMode?: "side_panel" | "full_screen" | "split";
+    openEntityMode?: "side_panel" | "full_screen" | "split" | "dialog";
+
+    /**
+     * Controls what happens when a user clicks on an entity in the collection view.
+     * - `"edit"` (default): Opens the entity in the edit form.
+     * - `"view"`: Opens a read-only detail view with an "Edit" button.
+     */
+    defaultEntityAction?: "view" | "edit";
+
+    /**
+     * Customization options for the read-only detail view.
+     * Only used when `defaultEntityAction` is `"view"`.
+     */
+    detailView?: EntityDetailViewConfig;
+
+    /**
+     * Prevent default actions from being displayed or executed on this collection.
+     */
+    disableDefaultActions?: ("edit" | "copy" | "delete")[];
+
 
 
     /**
@@ -200,6 +219,25 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      */
     readonly defaultFilter?: FilterValues<Extract<keyof M, string> | (string & {})>; // setting FilterValues<M> can break defining collections by code
 
+    /**
+     * Pre-defined filter presets that appear as quick-access options in the
+     * collection toolbar. Each preset applies a set of filters (and
+     * optionally a sort order) with a single click.
+     *
+     * ```ts
+     * filterPresets: [
+     *   {
+     *     label: "Shipped this month",
+     *     filterValues: {
+     *       status: ["==", "shipped"],
+     *       order_date: [">=", new Date(Date.now() - 30 * 86400000)]
+     *     }
+     *   }
+     * ]
+     * ```
+     */
+    readonly filterPresets?: FilterPreset<Extract<keyof M, string> | (string & {})>[];
+
     /**
      * Default sort applied to this collection.
      * When setting this prop, entities will have a default order
@@ -386,6 +424,13 @@ export interface PostgresCollection<M extends Record<string, unknown> = Record<s
      */
     table: string;
 
+    /**
+     * The PostgreSQL schema name for this table.
+     * E.g. "public", "rebase", "auth".
+     * If not specified, "public" is used (or the default search path).
+     */
+    schema?: string;
+
     /**
      * For SQL databases, you can define the relations between collections here.
      * Relations describe JOINs, foreign keys, and junction tables.
@@ -646,6 +691,36 @@ export type WhereFilterOp =
 export type FilterValues<Key extends string> =
     Partial<Record<Key, [WhereFilterOp, unknown]>>;
 
+/**
+ * A pre-defined filter preset for quick access in the collection toolbar.
+ * Users can select a preset to instantly apply a set of filters and
+ * optionally a sort order.
+ *
+ * @group Models
+ */
+export interface FilterPreset<Key extends string = string> {
+    /**
+     * Display label shown in the preset menu.
+     * If omitted, a summary is auto-generated from the filter keys.
+     */
+    label?: string;
+
+    /**
+     * The filter values to apply when this preset is selected.
+     */
+    filterValues: FilterValues<Key>;
+
+    /**
+     * Optional sort override to apply alongside the filter values.
+     */
+    sort?: [Key, "asc" | "desc"];
+}
+
+/**
+ * @deprecated Use {@link FilterPreset} instead.
+ */
+export type QuickFilter<Key extends string = string> = FilterPreset<Key>;
+
 /**
  * Used to indicate valid filter combinations (e.g. created in Firestore)
  * If the user selects a specific filter/sort combination, the CMS checks if it's

package/src/types/component_ref.d.ts

@@ -0,0 +1,47 @@
+import type React from "react";
+/**
+ * Internal marker for a lazily-loaded component reference.
+ * Created by the Vite transform plugin when converting string paths
+ * to deferred `import()` calls. Users should NOT create these manually.
+ *
+ * @internal
+ */
+export interface LazyComponentRef<P = unknown> {
+    readonly __rebaseLazy: true;
+    readonly load: () => Promise<{
+        default: React.ComponentType<P>;
+    }>;
+}
+/**
+ * A reference to a React component that can be provided in three forms:
+ *
+ * 1. **String path** (recommended for collection configs):
+ *    ```ts
+ *    Field: "../../frontend/src/components/MyField"
+ *    ```
+ *    The Vite plugin transforms this into a `LazyComponentRef` at build time.
+ *    On the backend, the string stays inert and is never evaluated.
+ *
+ * 2. **Lazy import function**:
+ *    ```ts
+ *    Field: () => import("../../frontend/src/components/MyField")
+ *    ```
+ *    Standard ES dynamic import. Backend never calls the function.
+ *
+ * 3. **Direct component reference** (use only in frontend-only code):
+ *    ```ts
+ *    Field: MyFieldComponent
+ *    ```
+ *    Importing a component at the top level will pull React into the
+ *    backend runtime — only safe in code that the backend never imports.
+ *
+ * @group Types
+ */
+export type ComponentRef<P = unknown> = React.ComponentType<P> | LazyComponentRef<P> | (() => Promise<{
+    default: React.ComponentType<P>;
+}>) | string;
+/**
+ * Type guard: checks if a value is a `LazyComponentRef` produced by the
+ * Vite transform plugin.
+ */
+export declare function isLazyComponentRef<P = unknown>(ref: unknown): ref is LazyComponentRef<P>;

package/src/types/cron.d.ts

@@ -0,0 +1,102 @@
+import type { RebaseClient } from "../controllers/client";
+/**
+ * Cron Job type definitions for Rebase.
+ *
+ * These types define the shape of cron job definitions, their runtime
+ * status, and execution log entries — used across server-core, client,
+ * and studio packages.
+ */
+/**
+ * A cron job definition file exports this shape as its default export.
+ * See the example cron files in `app/backend/crons/` for usage.
+ */
+export interface CronJobDefinition {
+    schedule: string;
+    /** Human-readable name shown in the Studio UI. */
+    name: string;
+    /** Optional description shown in the Studio UI. */
+    description?: string;
+    /**
+     * Whether the job is enabled at startup. Defaults to `true`.
+     * Can be toggled at runtime via the Admin API.
+     */
+    enabled?: boolean;
+    /**
+     * Maximum number of seconds the handler may run before being
+     * considered timed-out. Default: 300 (5 min).
+     */
+    timeoutSeconds?: number;
+    /**
+     * The handler function executed on each tick.
+     * Receives a context object with the data driver and logger.
+     * May return arbitrary JSON-serialisable data stored in the log.
+     */
+    handler: (ctx: CronJobContext) => Promise<unknown> | unknown;
+}
+/**
+ * Context passed to each cron handler invocation.
+ */
+export interface CronJobContext {
+    /** The job's unique ID (derived from filename). */
+    jobId: string;
+    /** The current scheduled tick timestamp. */
+    scheduledAt: Date;
+    /** A simple logger scoped to this job run. */
+    log: (...args: unknown[]) => void;
+    /** The RebaseClient instance to interact with the database. */
+    client: RebaseClient<any>;
+}
+export type CronJobRunState = "idle" | "running" | "success" | "error" | "disabled";
+/**
+ * Full runtime information about a registered cron job.
+ */
+export interface CronJobStatus {
+    /** Unique identifier (derived from filename, e.g. "cleanup-sessions"). */
+    id: string;
+    /** Human-readable name from the definition. */
+    name: string;
+    /** Description from the definition. */
+    description?: string;
+    /** The cron schedule expression. */
+    schedule: string;
+    /** Whether the job is currently enabled. */
+    enabled: boolean;
+    /** Current run state. */
+    state: CronJobRunState;
+    /** ISO timestamp of the last execution start. */
+    lastRunAt?: string;
+    /** ISO timestamp of the next scheduled execution. */
+    nextRunAt?: string;
+    /** Duration of the last run in milliseconds. */
+    lastDurationMs?: number;
+    /** Error message from the last failed run. */
+    lastError?: string;
+    /** Total number of executions since server start. */
+    totalRuns: number;
+    /** Total number of failed executions since server start. */
+    totalFailures: number;
+}
+export type CronLogLevel = "info" | "error" | "warn";
+/**
+ * A single execution log entry stored in the in-memory ring buffer.
+ */
+export interface CronJobLogEntry {
+    /** The job ID this log belongs to. */
+    jobId: string;
+    /** ISO timestamp when execution started. */
+    startedAt: string;
+    /** ISO timestamp when execution finished. */
+    finishedAt: string;
+    /** Duration in milliseconds. */
+    durationMs: number;
+    /** Whether this run succeeded. */
+    success: boolean;
+    /** Error message if the run failed. */
+    error?: string;
+    /** Arbitrary result data returned by the handler. */
+    result?: unknown;
+    /** Captured log lines. */
+    logs: string[];
+    /** Whether this was a manual trigger. */
+    manual?: boolean;
+}

package/src/types/data_source.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Describes the capabilities and features supported by a data source (driver).
+ *
+ * Each driver (Postgres, Firebase, MongoDB, etc.) declares which features it
+ * supports. The CMS uses this descriptor to:
+ * - Show/hide editor tabs (e.g. Relations for SQL, Subcollections for Firebase)
+ * - Filter the property type picker (e.g. `relation` for SQL, `reference` for Firebase)
+ * - Toggle driver-specific form controls (e.g. `columnType` for SQL)
+ *
+ * @group Models
+ */
+export interface DataSourceCapabilities {
+    /** Unique driver key (e.g. "postgres", "firestore", "mongodb") */
+    key: string;
+    /** Human-readable label for the UI (e.g. "PostgreSQL", "Firebase / Firestore") */
+    label: string;
+    /** Does this source support SQL-style relations (JOINs)? */
+    supportsRelations: boolean;
+    /** Does this source support nested subcollections? */
+    supportsSubcollections: boolean;
+    /** Does this source support Row Level Security policies? */
+    supportsRLS: boolean;
+    /** Does this source support document references (Firebase-style)? */
+    supportsReferences: boolean;
+    /** Does this source support SQL column type annotations? */
+    supportsColumnTypes: boolean;
+    /** Does this source support real-time listeners? */
+    supportsRealtime: boolean;
+    /** Does this source support SQL admin operations (SQL editor, EXPLAIN, etc.)? */
+    supportsSQLAdmin: boolean;
+    /** Does this source support document admin operations (aggregation, stats)? */
+    supportsDocumentAdmin: boolean;
+    /** Does this source support schema admin (unmapped tables, table metadata)? */
+    supportsSchemaAdmin: boolean;
+}
+/**
+ * Subset of DataSourceCapabilities containing only feature flags.
+ * Useful when you only need to check capabilities without UI metadata.
+ * @group Models
+ */
+export type DataSourceFeatures = Omit<DataSourceCapabilities, "key" | "label">;
+/** @group Models */
+export declare const POSTGRES_CAPABILITIES: DataSourceCapabilities;
+/** @group Models */
+export declare const FIREBASE_CAPABILITIES: DataSourceCapabilities;
+/** @group Models */
+export declare const MONGODB_CAPABILITIES: DataSourceCapabilities;
+/**
+ * Fallback capabilities when the driver is unknown.
+ * Enables everything so nothing is hidden unexpectedly.
+ * @group Models
+ */
+export declare const DEFAULT_CAPABILITIES: DataSourceCapabilities;
+/**
+ * Look up capabilities for a given driver key.
+ * If `driver` is undefined or not found, returns `DEFAULT_CAPABILITIES`.
+ * @group Models
+ */
+export declare function getDataSourceCapabilities(driver?: string): DataSourceCapabilities;
+/**
+ * Register custom capabilities for a third-party driver.
+ * @group Models
+ */
+export declare function registerDataSourceCapabilities(capabilities: DataSourceCapabilities): void;

package/src/types/database_adapter.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @module DatabaseAdapter
+ *
+ * Pluggable database abstraction for Rebase.
+ *
+ *
+ * A `DatabaseAdapter` focuses purely on data persistence and related concerns (realtime, history).
+ * It does NOT handle authentication — auth is managed separately by an `AuthAdapter`.
+ *
+ * @example
+ * ```ts
+ * import { createPostgresAdapter } from "@rebasepro/server-postgresql";
+ *
+ * initializeRebaseBackend({
+ *   database: createPostgresAdapter({ connection: db, schema }),
+ *   auth: { jwtSecret: "..." },
+ * });
+ * ```
+ *
+ * @group Backend
+ */
+import type { DataDriver } from "../controllers/data_driver";
+import type { EntityCollection } from "./collections";
+import type { CollectionRegistryInterface, DatabaseAdmin, InitializedDriver, RealtimeProvider } from "./backend";
+/**
+ * A `DatabaseAdapter` provides data persistence for Rebase.
+ *
+ * @group Backend
+ */
+export interface DatabaseAdapter {
+    /**
+     * Which database engine this adapter handles.
+     *
+     * @example "postgres", "mysql", "mongodb", "sqlite"
+     */
+    readonly type: string;
+    /**
+     * Create the DataDriver for CRUD operations.
+     *
+     * This is the only **required** method.
+     *
+     * @param config - Coordinator-provided config containing registered
+     *                 collections and the collection registry.
+     */
+    initializeDriver(config: DatabaseAdapterInitConfig): Promise<InitializedDriver>;
+    /**
+     * Create a realtime provider for this database.
+     *
+     * Return `undefined` if the database does not support realtime
+     * change notifications.
+     */
+    initializeRealtime?(driverResult: InitializedDriver): Promise<RealtimeProvider | undefined>;
+    /**
+     * Initialize entity history tracking.
+     *
+     * Return `undefined` if the database does not support history.
+     */
+    initializeHistory?(config: unknown, driverResult: InitializedDriver): Promise<{
+        historyService: unknown;
+    } | undefined>;
+    /**
+     * Initialize WebSocket server for realtime operations.
+     */
+    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: DataDriver, config?: unknown): Promise<void> | void;
+    /**
+     * Return admin capabilities for this database (SQL editor, schema browser, branching).
+     */
+    getAdmin?(driverResult: InitializedDriver): DatabaseAdmin | undefined;
+    /**
+     * Mount any database-specific HTTP routes (e.g., custom admin endpoints).
+     *
+     * Called after all adapters are initialized.
+     */
+    mountRoutes?(app: unknown, basePath: string, driverResult: InitializedDriver): void;
+    /**
+     * Graceful shutdown: close connections, release resources.
+     */
+    destroy?(): Promise<void>;
+}
+/**
+ * Configuration passed by the coordinator to `DatabaseAdapter.initializeDriver()`.
+ *
+ * @group Backend
+ */
+export interface DatabaseAdapterInitConfig {
+    /** Registered collection definitions. */
+    collections: EntityCollection[];
+    /** The shared collection registry to register into. */
+    collectionRegistry: CollectionRegistryInterface;
+}

package/src/types/database_adapter.ts

@@ -0,0 +1,120 @@
+/**
+ * @module DatabaseAdapter
+ *
+ * Pluggable database abstraction for Rebase.
+ *
+ *
+ * A `DatabaseAdapter` focuses purely on data persistence and related concerns (realtime, history).
+ * It does NOT handle authentication — auth is managed separately by an `AuthAdapter`.
+ *
+ * @example
+ * ```ts
+ * import { createPostgresAdapter } from "@rebasepro/server-postgresql";
+ *
+ * initializeRebaseBackend({
+ *   database: createPostgresAdapter({ connection: db, schema }),
+ *   auth: { jwtSecret: "..." },
+ * });
+ * ```
+ *
+ * @group Backend
+ */
+
+import type { DataDriver } from "../controllers/data_driver";
+import type { EntityCollection } from "./collections";
+import type {
+    CollectionRegistryInterface,
+    DatabaseAdmin,
+    InitializedDriver,
+    RealtimeProvider,
+    BootstrappedAuth,
+} from "./backend";
+
+/**
+ * A `DatabaseAdapter` provides data persistence for Rebase.
+ *
+ * @group Backend
+ */
+export interface DatabaseAdapter {
+    /**
+     * Which database engine this adapter handles.
+     *
+     * @example "postgres", "mysql", "mongodb", "sqlite"
+     */
+    readonly type: string;
+
+    /**
+     * Create the DataDriver for CRUD operations.
+     *
+     * This is the only **required** method.
+     *
+     * @param config - Coordinator-provided config containing registered
+     *                 collections and the collection registry.
+     */
+    initializeDriver(config: DatabaseAdapterInitConfig): Promise<InitializedDriver>;
+
+    /**
+     * Create a realtime provider for this database.
+     *
+     * Return `undefined` if the database does not support realtime
+     * change notifications.
+     */
+    initializeRealtime?(driverResult: InitializedDriver): Promise<RealtimeProvider | undefined>;
+
+    /**
+     * Initialize auth tables / services if this driver supports them.
+     */
+    initializeAuth?(
+        config: unknown,
+        driverResult: InitializedDriver,
+    ): Promise<BootstrappedAuth | undefined>;
+
+    /**
+     * Initialize entity history tracking.
+     *
+     * Return `undefined` if the database does not support history.
+     */
+    initializeHistory?(
+        config: unknown,
+        driverResult: InitializedDriver,
+    ): Promise<{ historyService: unknown } | undefined>;
+
+    /**
+     * Initialize WebSocket server for realtime operations.
+     */
+    initializeWebsockets?(
+        server: unknown,
+        realtimeService: RealtimeProvider,
+        driver: DataDriver,
+        config?: unknown,
+    ): Promise<void> | void;
+
+    /**
+     * Return admin capabilities for this database (SQL editor, schema browser, branching).
+     */
+    getAdmin?(driverResult: InitializedDriver): DatabaseAdmin | undefined;
+
+    /**
+     * Mount any database-specific HTTP routes (e.g., custom admin endpoints).
+     *
+     * Called after all adapters are initialized.
+     */
+    mountRoutes?(app: unknown, basePath: string, driverResult: InitializedDriver): void;
+
+    /**
+     * Graceful shutdown: close connections, release resources.
+     */
+    destroy?(): Promise<void>;
+}
+
+/**
+ * Configuration passed by the coordinator to `DatabaseAdapter.initializeDriver()`.
+ *
+ * @group Backend
+ */
+export interface DatabaseAdapterInitConfig {
+    /** Registered collection definitions. */
+    collections: EntityCollection[];
+    /** The shared collection registry to register into. */
+    collectionRegistry: CollectionRegistryInterface;
+}

package/src/types/entities.d.ts

@@ -0,0 +1,145 @@
+/**
+ * New or existing status
+ * @group Models
+ */
+export type EntityStatus = "new" | "existing" | "copy";
+/**
+ * Representation of an entity fetched from the driver
+ * @group Models
+ */
+export interface Entity<M extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * ID of the entity
+     */
+    id: string | number;
+    /**
+     * A string representing the path of the referenced document (relative
+     * to the root of the database).
+     */
+    path: string;
+    /**
+     * Current values
+     */
+    values: EntityValues<M>;
+    /**
+     * Which driver this entity belongs to (e.g., 'postgres', 'firestore').
+     * If not specified, the default driver is assumed.
+     */
+    driver?: string;
+    /**
+     * Which database within the driver (e.g., for Firestore multi-database).
+     * If not specified, the default database of the driver is used.
+     */
+    databaseId?: string;
+}
+/**
+ * This type represents a record of key value pairs as described in an
+ * entity collection.
+ * @group Models
+ */
+export type EntityValues<M extends Record<string, unknown>> = M;
+/**
+ * Props for creating an EntityReference
+ */
+export interface EntityReferenceProps {
+    /** ID of the entity */
+    id: string;
+    /** Path of the collection (relative to the root of the database) */
+    path: string;
+    /** Which driver (e.g., 'postgres', 'firestore'). Defaults to "(default)" */
+    driver?: string;
+    /** Which database within the driver. Defaults to "(default)" */
+    databaseId?: string;
+}
+/**
+ * Class used to create a reference to an entity in a different path.
+ *
+ * @example
+ * // Simple reference (most common case - single driver, single db)
+ * new EntityReference({ id: "123", path: "users" })
+ *
+ * // Reference to a different driver (e.g., Firestore)
+ * new EntityReference({ id: "123", path: "analytics", driver: "firestore" })
+ *
+ * // Reference to a specific database within a driver
+ * new EntityReference({ id: "123", path: "orders", driver: "postgres", databaseId: "orders_db" })
+ */
+export declare class EntityReference {
+    readonly __type = "reference";
+    /**
+     * ID of the entity
+     */
+    readonly id: string;
+    /**
+     * A string representing the path of the referenced document (relative
+     * to the root of the database).
+     */
+    readonly path: string;
+    /**
+     * Which driver (e.g., 'postgres', 'firestore').
+     * Defaults to "(default)" if not specified.
+     */
+    readonly driver?: string;
+    /**
+     * Which database within the driver.
+     * Defaults to "(default)" if not specified.
+     */
+    readonly databaseId?: string;
+    /**
+     * Create a reference to an entity.
+     *
+     * @example
+     * // Simple reference (most common case)
+     * new EntityReference({ id: "123", path: "users" })
+     *
+     * // With driver
+     * new EntityReference({ id: "123", path: "analytics", driver: "firestore" })
+     */
+    constructor(props: EntityReferenceProps);
+    get pathWithId(): string;
+    /**
+     * Get the full path including driver and database prefixes if specified.
+     * For the common case (single driver, single db), this just returns pathWithId.
+     */
+    get fullPath(): string;
+    isEntityReference(): boolean;
+}
+/**
+ * Class used to create a reference to an entity in a different path
+ */
+export declare class EntityRelation {
+    readonly __type = "relation";
+    /**
+     * ID of the entity
+     */
+    readonly id: string | number;
+    /**
+     * A string representing the path of the referenced document (relative
+     * to the root of the database).
+     */
+    readonly path: string;
+    /**
+     * Pre-fetched data payload to eliminate N+1 queries.
+     * When present, clients can use this directly instead of fetching.
+     */
+    readonly data?: Entity;
+    constructor(id: string | number, path: string, data?: Entity);
+    get pathWithId(): string;
+    isEntityReference(): boolean;
+    isEntityRelation(): boolean;
+}
+export declare class GeoPoint {
+    /**
+     * The latitude of this GeoPoint instance.
+     */
+    readonly latitude: number;
+    /**
+     * The longitude of this GeoPoint instance.
+     */
+    readonly longitude: number;
+    constructor(latitude: number, longitude: number);
+}
+export declare class Vector {
+    readonly value: number[];
+    constructor(value: number[]);
+}