@rebasepro/types 0.0.1-canary.0 → 0.0.1-canary.0e2f892

package/dist/rebase_context.d.ts

@@ -1,6 +1,11 @@
-import { AnalyticsController, AuthController, CustomizationController, DataSource, DialogsController, NavigationController, SideDialogsController, SideEntityController, SnackbarController, StorageSource, UserConfigurationPersistence } from "./controllers";
-import { User } from "./users";
-import { UserManagementDelegate, EffectiveRoleController } from "./types";
+import type { AnalyticsController } from "./controllers/analytics_controller";
+import type { AuthController } from "./controllers/auth";
+import type { StorageSource } from "./controllers/storage";
+import type { UserConfigurationPersistence } from "./controllers/local_config_persistence";
+import type { DatabaseAdmin } from "./types/backend";
+import type { RebaseData } from "./controllers/data";
+import type { User } from "./users";
+import type { UserManagementDelegate } from "./types/user_management_delegate";
 /**
  * Context that is provided to entity callbacks (hooks).
  * It contains only the dependencies that are available in both the frontend and the backend.
@@ -8,9 +13,10 @@ import { UserManagementDelegate, EffectiveRoleController } from "./types";
  */
 export type RebaseCallContext<USER extends User = User> = {
     /**
-     * Connector to your database, e.g. your Firestore database
+     * Unified data access — `context.data.products.create(...)`.
+     * Access any collection as a dynamic property.
      */
-    dataSource: DataSource;
+    data: RebaseData;
     /**
      * Used storage implementation
      */
@@ -28,39 +34,42 @@ export type RebaseCallContext<USER extends User = User> = {
  * @see useRebaseContext
  */
 export type RebaseContext<USER extends User = User, AuthControllerType extends AuthController<USER> = AuthController<USER>> = RebaseCallContext<USER> & {
+    authController: AuthControllerType;
     /**
-     * Context that includes the resolved navigation and utility methods and
-     * attributes.
-     * @see useNavigation
+     * Controller mapping strings to collections
      */
-    navigation?: NavigationController;
+    collectionRegistryController?: import("./controllers/collection_registry").CollectionRegistryController;
     /**
-     * Controller to open the side dialog displaying entity forms
-     * @see useSideEntityController
+     * Controller for navigation state
+     */
+    navigationStateController?: import("./controllers/navigation").NavigationStateController;
+    /**
+     * Controller for side dialogs (side sheets)
      */
-    sideEntityController?: SideEntityController;
+    sideDialogsController?: import("./controllers/side_dialogs_controller").SideDialogsController;
     /**
-     * Controller used to open side dialogs
-     * This is the controller used internally by side entity dialogs
-     * or reference dialogs.
+     * Controller to open the side dialog displaying entity forms
      */
-    sideDialogsController?: SideDialogsController;
+    sideEntityController?: import("./controllers/side_entity_controller").SideEntityController;
     /**
-     * Controller used to open regular dialogs
+     * Controller resolving URLs in the CMS
      */
-    dialogsController?: DialogsController;
+    urlController?: import("./controllers/navigation").UrlController;
     /**
-     * Used auth controller
+     * Controller to handle simple confirmation and alert dialogs
      */
-    authController?: AuthControllerType;
+    dialogsController?: import("./controllers/dialogs_controller").DialogsController;
     /**
-     * This controller holds the customization options for the CMS.
+     * Controller for CMS customization
      */
-    customizationController?: CustomizationController;
+    customizationController?: import("./controllers/customization_controller").CustomizationController;
     /**
-     * Use this controller to display snackbars
+     * Controller for effective role
      */
-    snackbarController?: SnackbarController;
+    effectiveRoleController?: {
+        effectiveRole: string | null;
+        setEffectiveRole: (role: string | null) => void;
+    };
     /**
      * Use this controller to access data stored in the browser for the user
      */
@@ -85,7 +94,12 @@ export type RebaseContext<USER extends User = User, AuthControllerType extends A
      */
     userManagement?: UserManagementDelegate<USER>;
     /**
-     * Controller to simulate different roles when dev mode is active.
+     * Administrative database operations (SQL, schema discovery).
+     * Only available in developer/admin contexts.
+     */
+    databaseAdmin?: DatabaseAdmin;
+    /**
+     * Controller for snackbars
      */
-    effectiveRoleController?: EffectiveRoleController;
+    snackbarController?: import("./controllers/snackbar").SnackbarController;
 };

package/dist/types/backend.d.ts

@@ -1,4 +1,5 @@
-import { Entity, EntityCollection, FilterValues, WhereFilterOp } from "./index";
+import type { Entity } from "./entities";
+import type { EntityCollection, FilterValues, WhereFilterOp } from "./collections";
 /**
  * Abstract database connection interface.
  * Represents a connection to any database system.
@@ -13,7 +14,7 @@ export interface DatabaseConnection {
      */
     readonly isConnected?: boolean;
     /**
-     * Close the database connection
+     * Close the database connection and release resources.
      */
     close?(): Promise<void>;
 }
@@ -28,30 +29,34 @@ export interface QueryFilter {
 /**
  * Options for fetching a collection of entities
  */
-export interface FetchCollectionOptions<M extends Record<string, any> = any> {
+export interface FetchCollectionOptions<M extends Record<string, unknown> = Record<string, unknown>> {
     filter?: FilterValues<Extract<keyof M, string>>;
     orderBy?: string;
     order?: "desc" | "asc";
     limit?: number;
+    offset?: number;
     startAfter?: unknown;
     searchString?: string;
     databaseId?: string;
+    collection?: EntityCollection;
 }
 /**
  * Options for searching entities
  */
-export interface SearchOptions<M extends Record<string, any> = any> {
+export interface SearchOptions<M extends Record<string, unknown> = Record<string, unknown>> {
     filter?: FilterValues<Extract<keyof M, string>>;
     orderBy?: string;
     order?: "desc" | "asc";
     limit?: number;
     databaseId?: string;
+    collection?: EntityCollection;
 }
 /**
  * Options for counting entities
  */
-export interface CountOptions<M extends Record<string, any> = any> {
+export interface CountOptions<M extends Record<string, unknown> = Record<string, unknown>> {
     filter?: FilterValues<Extract<keyof M, string>>;
+    searchString?: string;
     databaseId?: string;
 }
 /**
@@ -63,11 +68,11 @@ export interface CountOptions<M extends Record<string, any> = any> {
  *
  * @template T The type of condition returned by the builder (e.g., SQL for PostgreSQL, Filter<Document> for MongoDB)
  */
-export interface ConditionBuilder<T = any> {
+export interface ConditionBuilder<T = unknown> {
     /**
      * Build filter conditions from Rebase FilterValues
      */
-    buildFilterConditions<M extends Record<string, any>>(filter: FilterValues<Extract<keyof M, string>>, collectionPath: string, ...args: unknown[]): T[];
+    buildFilterConditions<M extends Record<string, unknown>>(filter: FilterValues<Extract<keyof M, string>>, collectionPath: string, ...args: unknown[]): T[];
     /**
      * Build search conditions for text search
      */
@@ -89,8 +94,8 @@ export interface ConditionBuilder<T = any> {
  * // DrizzleConditionBuilder satisfies this type
  * const builder: ConditionBuilderStatic<SQL> = DrizzleConditionBuilder;
  */
-export type ConditionBuilderStatic<T = any> = {
-    buildFilterConditions<M extends Record<string, any>>(filter: FilterValues<Extract<keyof M, string>>, ...args: unknown[]): T[];
+export type ConditionBuilderStatic<T = unknown> = {
+    buildFilterConditions<M extends Record<string, unknown>>(filter: FilterValues<Extract<keyof M, string>>, ...args: unknown[]): T[];
     buildSearchConditions(searchString: string, properties: Record<string, unknown>, ...args: unknown[]): T[];
     combineConditionsWithAnd(conditions: T[]): T | undefined;
     combineConditionsWithOr(conditions: T[]): T | undefined;
@@ -108,23 +113,23 @@ export interface EntityRepository {
     /**
      * Fetch a single entity by ID
      */
-    fetchEntity<M extends Record<string, any>>(collectionPath: string, entityId: string | number, databaseId?: string): Promise<Entity<M> | undefined>;
+    fetchEntity<M extends Record<string, unknown>>(collectionPath: string, entityId: string | number, databaseId?: string): Promise<Entity<M> | undefined>;
     /**
      * Fetch a collection of entities with optional filtering, ordering, and pagination
      */
-    fetchCollection<M extends Record<string, any>>(collectionPath: string, options?: FetchCollectionOptions<M>): Promise<Entity<M>[]>;
+    fetchCollection<M extends Record<string, unknown>>(collectionPath: string, options?: FetchCollectionOptions<M>): Promise<Entity<M>[]>;
     /**
      * Search entities by text
      */
-    searchEntities<M extends Record<string, any>>(collectionPath: string, searchString: string, options?: SearchOptions<M>): Promise<Entity<M>[]>;
+    searchEntities<M extends Record<string, unknown>>(collectionPath: string, searchString: string, options?: SearchOptions<M>): Promise<Entity<M>[]>;
     /**
      * Count entities in a collection
      */
-    countEntities<M extends Record<string, any>>(collectionPath: string, options?: CountOptions<M>): Promise<number>;
+    countEntities<M extends Record<string, unknown>>(collectionPath: string, options?: CountOptions<M>): Promise<number>;
     /**
      * Save an entity (create or update)
      */
-    saveEntity<M extends Record<string, any>>(collectionPath: string, values: Partial<M>, entityId?: string | number, databaseId?: string): Promise<Entity<M>>;
+    saveEntity<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, entityId?: string | number, databaseId?: string): Promise<Entity<M>>;
     /**
      * Delete an entity by ID
      */
@@ -204,11 +209,173 @@ export interface DataTransformer {
     /**
      * Transform entity data for storage in the database
      */
-    serializeToDatabase<M extends Record<string, any>>(entity: M, collection: EntityCollection): Record<string, any>;
+    serializeToDatabase<M extends Record<string, unknown>>(entity: M, collection: EntityCollection): Record<string, unknown>;
     /**
      * Transform database data back to entity format
      */
-    deserializeFromDatabase<M extends Record<string, any>>(data: Record<string, any>, collection: EntityCollection): Promise<M>;
+    deserializeFromDatabase<M extends Record<string, unknown>>(data: Record<string, unknown>, collection: EntityCollection): Promise<M>;
+}
+/**
+ * Administrative operations for SQL-based databases (PostgreSQL, MySQL, etc.).
+ * Used by the SQL Editor, RLS Editor, and schema browser.
+ *
+ * @group Admin
+ */
+export interface SQLAdmin {
+    /**
+     * Execute raw SQL against the database.
+     */
+    executeSql(sql: string, options?: {
+        database?: string;
+        role?: string;
+    }): Promise<Record<string, unknown>[]>;
+    /**
+     * Fetch the available databases on the server.
+     */
+    fetchAvailableDatabases?(): Promise<string[]>;
+    /**
+     * Fetch the available database roles.
+     */
+    fetchAvailableRoles?(): Promise<string[]>;
+    /**
+     * Fetch the current database name.
+     */
+    fetchCurrentDatabase?(): Promise<string | undefined>;
+}
+/**
+ * Administrative operations for document-based databases (MongoDB, Firestore, etc.).
+ * Used by future document administration tools.
+ *
+ * @group Admin
+ */
+export interface DocumentAdmin {
+    /**
+     * Execute an aggregation pipeline or equivalent query.
+     */
+    executeAggregate?(pipeline: Record<string, unknown>[]): Promise<Record<string, unknown>[]>;
+    /**
+     * Fetch statistics for a collection (document count, size, etc.).
+     */
+    fetchCollectionStats?(collectionName: string): Promise<{
+        count: number;
+        sizeBytes?: number;
+    }>;
+}
+/**
+ * Administrative operations for schema management.
+ * Shared across SQL and document databases.
+ *
+ * @group Admin
+ */
+export interface SchemaAdmin {
+    /**
+     * Fetch database tables/collections not yet mapped to a Rebase collection.
+     */
+    fetchUnmappedTables?(mappedPaths?: string[]): Promise<string[]>;
+    /**
+     * Fetch column/field metadata for a single table/collection.
+     * The return type is generic — SQL backends return TableMetadata,
+     * document backends may return a different shape.
+     */
+    fetchTableMetadata?(tableName: string): Promise<unknown>;
+}
+/**
+ * Metadata for a database branch.
+ * @group Admin
+ */
+export interface BranchInfo {
+    /** Branch name (without prefix). */
+    name: string;
+    /** The database this branch was created from. */
+    parentDatabase: string;
+    /** When the branch was created. */
+    createdAt: Date;
+    /** Size in bytes, if available from the server. */
+    sizeBytes?: number;
+}
+/**
+ * Administrative operations for database branching.
+ * Allows creating isolated database copies for development/preview workflows.
+ *
+ * @group Admin
+ */
+export interface BranchAdmin {
+    /** Create a new branch (database copy) from the current or specified source database. */
+    createBranch(name: string, options?: {
+        source?: string;
+    }): Promise<BranchInfo>;
+    /** Delete a branch database. Cannot delete the main/default database. */
+    deleteBranch(name: string): Promise<void>;
+    /** List all branches (databases that were created via branching). */
+    listBranches(): Promise<BranchInfo[]>;
+    /** Get info about a specific branch. */
+    getBranchInfo(name: string): Promise<BranchInfo | undefined>;
+}
+/**
+ * Union type for all admin capabilities.
+ * A backend may implement any combination of these interfaces.
+ *
+ * Use type guards (`isSQLAdmin`, `isDocumentAdmin`, `isSchemaAdmin`, `isBranchAdmin`)
+ * to safely narrow the type before calling methods.
+ *
+ * @group Admin
+ */
+export type DatabaseAdmin = Partial<SQLAdmin> & Partial<DocumentAdmin> & Partial<SchemaAdmin> & Partial<BranchAdmin>;
+/**
+ * Type guard: does this admin support SQL operations?
+ * @group Admin
+ */
+export declare function isSQLAdmin(admin: DatabaseAdmin | undefined): admin is SQLAdmin;
+/**
+ * Type guard: does this admin support document operations?
+ * @group Admin
+ */
+export declare function isDocumentAdmin(admin: DatabaseAdmin | undefined): admin is DocumentAdmin;
+/**
+ * Type guard: does this admin support schema management?
+ * @group Admin
+ */
+export declare function isSchemaAdmin(admin: DatabaseAdmin | undefined): admin is SchemaAdmin;
+/**
+ * Type guard: does this admin support database branching?
+ * @group Admin
+ */
+export declare function isBranchAdmin(admin: DatabaseAdmin | undefined): admin is BranchAdmin;
+/**
+ * Health check result returned by `healthCheck()`.
+ * @group Lifecycle
+ */
+export interface HealthCheckResult {
+    /** Whether the backend is healthy and able to serve requests. */
+    healthy: boolean;
+    /** Round-trip latency to the database in milliseconds. */
+    latencyMs: number;
+    /** Optional details (e.g., pool stats, replication lag). */
+    details?: Record<string, unknown>;
+}
+/**
+ * Lifecycle contract for backend components that hold resources
+ * (database connections, WebSocket pools, timers, etc.).
+ *
+ * All methods are optional — simple backends (e.g., in-memory) can skip them.
+ * @group Lifecycle
+ */
+export interface BackendLifecycle {
+    /**
+     * Initialize the backend: open connections, run migrations, seed data.
+     * Called once during startup. Idempotent.
+     */
+    initialize?(): Promise<void>;
+    /**
+     * Check whether the backend is healthy and reachable.
+     * Should be fast (< 1 s) and safe to call frequently.
+     */
+    healthCheck?(): Promise<HealthCheckResult>;
+    /**
+     * Gracefully shut down: close connections, flush buffers, cancel timers.
+     * After calling `destroy()`, no other methods should be called.
+     */
+    destroy?(): Promise<void>;
 }
 /**
  * Configuration for creating a database backend
@@ -228,9 +395,11 @@ export interface BackendConfig {
     schema?: unknown;
 }
 /**
- * A complete backend instance with all required services
+ * A complete backend instance with all required services.
+ *
+ * Now includes optional lifecycle management and admin capabilities.
  */
-export interface BackendInstance {
+export interface BackendInstance extends BackendLifecycle {
     /**
      * Entity repository for CRUD operations
      */
@@ -247,8 +416,121 @@ export interface BackendInstance {
      * The underlying database connection
      */
     connection: DatabaseConnection;
+    /**
+     * Administrative operations (SQL, schema, documents).
+     * What's available depends on the backend type — use type guards
+     * (`isSQLAdmin`, `isSchemaAdmin`, etc.) to narrow.
+     */
+    admin?: DatabaseAdmin;
 }
 /**
  * Factory function type for creating backend instances
  */
 export type BackendFactory<TConfig extends BackendConfig = BackendConfig> = (config: TConfig) => BackendInstance;
+/**
+ * A `BackendBootstrapper` encapsulates all driver-specific initialization logic.
+ *
+ * Instead of hard-coding Postgres setup into `initializeRebaseBackend()`,
+ * each database backend provides its own bootstrapper that knows how to:
+ * - Create the DataDriver from a config object
+ * - Optionally initialize auth tables
+ * - Optionally create a realtime service
+ * - Mount driver-specific API routes
+ *
+ * The main `initializeRebaseBackend()` becomes a **coordinator** that iterates
+ * registered bootstrappers, calls their hooks, and wires the results together.
+ *
+ * @group Backend
+ *
+ * @example
+ * ```typescript
+ * // Third-party MySQL bootstrapper
+ * const mysqlBootstrapper: BackendBootstrapper = {
+ *   type: "mysql",
+ *   initializeDriver: async (config) => new MySQLDataDriver(config.connection),
+ *   initializeRealtime: async (config) => new MySQLChangeStreamRealtime(config.connection),
+ * };
+ *
+ * initializeRebaseBackend({
+ *   ...config,
+ *   bootstrappers: [postgresBootstrapper, mysqlBootstrapper]
+ * });
+ * ```
+ */
+export interface BackendBootstrapper {
+    /**
+     * Which driver type this bootstrapper handles.
+     * Must match the `type` field on the driver config object
+     * (e.g., `"postgres"`, `"mongodb"`, `"mysql"`).
+     */
+    type: string;
+    /**
+     * Create a DataDriver from the given config.
+     * This is the only **required** method.
+     */
+    initializeDriver(config: unknown): Promise<InitializedDriver>;
+    /**
+     * Initialize auth tables / services if this driver supports them.
+     * Return undefined if auth is not supported by this backend.
+     */
+    initializeAuth?(config: unknown, driverResult: InitializedDriver): Promise<BootstrappedAuth | undefined>;
+    /**
+     * Initialize history tables / services if this driver supports them.
+     * Return undefined if history is not supported by this backend.
+     */
+    initializeHistory?(config: unknown, driverResult: InitializedDriver): Promise<{
+        historyService: unknown;
+    } | undefined>;
+    /**
+     * Create a realtime provider for this driver.
+     * Return undefined if the driver does not support realtime.
+     */
+    initializeRealtime?(config: unknown, driverResult: InitializedDriver): Promise<RealtimeProvider | undefined>;
+    /**
+     * Mount any driver-specific HTTP routes (e.g., custom admin endpoints).
+     * Called after all drivers are initialized.
+     */
+    mountRoutes?(app: unknown, basePath: string, driverResult: InitializedDriver): void;
+    /**
+     * Return admin capabilities for this driver.
+     */
+    getAdmin?(driverResult: InitializedDriver): DatabaseAdmin | undefined;
+    /**
+     * Initialize WebSocket server for realtime operations.
+     */
+    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: import("../controllers/data_driver").DataDriver, config?: unknown): Promise<void> | void;
+}
+/**
+ * Result of `BackendBootstrapper.initializeDriver()`.
+ * @group Backend
+ */
+export interface InitializedDriver {
+    /** The DataDriver instance, ready for use. */
+    driver: import("../controllers/data_driver").DataDriver;
+    /** The realtime service, if the driver created one during init. */
+    realtimeProvider?: RealtimeProvider;
+    /** A collection registry to register schema / tables into. */
+    collectionRegistry?: CollectionRegistryInterface;
+    /** The underlying database connection (for lifecycle management). */
+    connection?: DatabaseConnection;
+    /**
+     * Opaque handle that the bootstrapper can use in subsequent hooks
+     * (e.g., `initializeAuth`, `mountRoutes`) to access driver internals.
+     * Not used by the coordinator.
+     */
+    internals?: unknown;
+}
+/**
+ * Result of `BackendBootstrapper.initializeAuth()`.
+ * @group Backend
+ */
+export interface BootstrappedAuth {
+    /** User management service. */
+    userService: unknown;
+    /** Role management service. */
+    roleService: unknown;
+    /** Email service (optional). */
+    emailService?: unknown;
+    /** Combined Auth Repository for unified token and user management. */
+    authRepository?: unknown;
+}

package/dist/types/builders.d.ts

@@ -0,0 +1,15 @@
+import type { AuthController } from "../controllers/auth";
+import type { RebaseData } from "../controllers/data";
+import type { User } from "../users";
+import type { EntityCollection } from "./collections";
+import type { AppView } from "../controllers/navigation";
+export type EntityCollectionsBuilder<EC extends EntityCollection = EntityCollection> = (params: {
+    user: User | null;
+    authController: AuthController;
+    data: RebaseData;
+}) => EC[] | Promise<EC[]>;
+export type AppViewsBuilder = (params: {
+    user: User | null;
+    authController: AuthController;
+    data: RebaseData;
+}) => AppView[] | Promise<AppView[]>;

package/dist/types/chips.d.ts

@@ -2,4 +2,4 @@ export type ColorScheme = {
     color: string;
     text: string;
 };
-export type ColorKey = "blueLighter" | "cyanLighter" | "tealLighter" | "greenLighter" | "yellowLighter" | "orangeLighter" | "redLighter" | "pinkLighter" | "purpleLighter" | "grayLighter" | "blueLight" | "cyanLight" | "tealLight" | "greenLight" | "yellowLight" | "orangeLight" | "redLight" | "pinkLight" | "purpleLight" | "grayLight" | "blueDark" | "cyanDark" | "tealDark" | "greenDark" | "yellowDark" | "orangeDark" | "redDark" | "pinkDark" | "purpleDark" | "grayDark" | "blueDarker" | "cyanDarker" | "tealDarker" | "greenDarker" | "yellowDarker" | "orangeDarker" | "redDarker" | "pinkDarker" | "purpleDarker" | "grayDarker";
+export type ColorKey = "blue" | "cyan" | "teal" | "green" | "yellow" | "orange" | "red" | "pink" | "purple" | "gray" | "indigo" | "violet" | "fuchsia" | "rose" | "emerald";