@rebasepro/server-mongodb 0.0.1-canary.09e5ec5

package/src/factory.ts

@@ -0,0 +1,289 @@
+/**
+ * MongoDB Backend Factory
+ *
+ * This module provides factory functions for creating MongoDB backend instances.
+ * It abstracts the creation of drivers, realtime services, and entity services.
+ */
+
+import { Db, MongoClient } from "mongodb";
+import { DataDriver, EntityCollection } from "@rebasepro/types";
+
+import { MongoEntityService } from "./db/MongoEntityService";
+import { MongoRealtimeService } from "./services/MongoRealtimeService";
+import { MongoDriver } from "./services/MongoDriver";
+import { MongoHistoryService, HistoryRetentionConfig } from "./services/MongoHistoryService";
+import { MongoDBConnection } from "./connection";
+import { BackendConfig, BackendInstance, CollectionRegistryInterface, EntityRepository, RealtimeProvider, DatabaseConnection, DatabaseAdmin, DocumentAdmin, SchemaAdmin, HealthCheckResult } from "@rebasepro/types";
+
+/**
+ * Configuration for creating a MongoDB backend.
+ */
+export interface MongoBackendConfig extends BackendConfig {
+    type: "mongodb";
+    /** MongoDB database instance */
+    connection: Db;
+    /** MongoDB client (for connection management) */
+    client: MongoClient;
+    /** Collections to register (optional, can be registered later) */
+    collections?: EntityCollection[];
+    /** History retention configuration */
+    historyRetention?: Partial<HistoryRetentionConfig>;
+}
+
+/**
+ * MongoDB-specific backend instance with additional MongoDB types.
+ */
+export interface MongoBackendInstance extends BackendInstance {
+    /** The MongoDB database instance */
+    db: Db;
+    /** The MongoDB client */
+    client: MongoClient;
+    /** MongoDB DataDriver for use with Rebase */
+    driver: DataDriver;
+    /** Entity service for direct database operations */
+    entityService: MongoEntityService;
+    /** Realtime service for subscriptions */
+    realtimeService: MongoRealtimeService;
+    /** Admin capabilities (DocumentAdmin + SchemaAdmin) */
+    admin: DatabaseAdmin;
+}
+
+// =============================================================================
+// Simple Collection Registry
+// =============================================================================
+
+/**
+ * Simple in-memory collection registry for MongoDB.
+ */
+export class MongoCollectionRegistry implements CollectionRegistryInterface {
+    private collections = new Map<string, EntityCollection>();
+
+    /**
+     * Register a collection
+     */
+    register(collection: EntityCollection): void {
+        this.collections.set(collection.name, collection);
+    }
+
+    /**
+     * Get a collection by its path
+     */
+    getCollectionByPath(path: string): EntityCollection | undefined {
+        return this.collections.get(path);
+    }
+
+    /**
+     * Get all registered collections
+     */
+    getCollections(): EntityCollection[] {
+        return Array.from(this.collections.values());
+    }
+}
+
+// =============================================================================
+// Factory Functions
+// =============================================================================
+
+/**
+ * Create a complete MongoDB backend instance.
+ *
+ * This factory function creates all the necessary services for a MongoDB backend:
+ * - MongoDBConnection (database connection wrapper)
+ * - MongoEntityService (implements EntityRepository)
+ * - MongoRealtimeService (implements RealtimeProvider)
+ * - MongoCollectionRegistry (implements CollectionRegistryInterface)
+ * - MongoDriver (for Rebase integration)
+ *
+ * @example
+ * ```typescript
+ * import { createMongoBackend } from "@rebasepro/server-mongodb";
+ *
+ * const client = new MongoClient("mongodb://localhost:27017");
+ * await client.connect();
+ * const db = client.db("my_database");
+ *
+ * const backend = createMongoBackend({
+ *     type: "mongodb",
+ *     connection: db,
+ *     client: client,
+ *     collections: myCollections
+ * });
+ *
+ * // Use the backend
+ * const entities = await backend.entityRepository.fetchCollection("users", {});
+ * ```
+ */
+export function createMongoBackend(config: MongoBackendConfig): MongoBackendInstance {
+    const { connection: db, client, collections } = config;
+
+    // Create collection registry
+    const collectionRegistry = new MongoCollectionRegistry();
+
+    // Register collections if provided
+    if (collections) {
+        collections.forEach(collection => collectionRegistry.register(collection));
+    }
+
+    // Create services
+    const entityService = new MongoEntityService(db);
+    const realtimeService = new MongoRealtimeService(db);
+    const historyService = new MongoHistoryService(db, config.historyRetention);
+    const driver = new MongoDriver(db, realtimeService, historyService);
+    const mongoConnection = new MongoDBConnection(db, client);
+
+    // Build admin capabilities for MongoDB
+    const admin: DatabaseAdmin = {
+        async executeAggregate(pipeline: Record<string, unknown>[]) {
+            // Run aggregation on a collection — requires a target collection
+            // from the pipeline's $match or $lookup stage:
+            const firstStage = pipeline[0];
+            const collName = typeof firstStage.$from === "string" ? firstStage.$from : "__admin__";
+            const cursor = db.collection(collName).aggregate(pipeline);
+            return await cursor.toArray() as Record<string, unknown>[];
+        },
+        async fetchCollectionStats(collectionName: string) {
+            const stats = await db.command({ collStats: collectionName }) as { count: number; size: number };
+            return { count: stats.count,
+sizeBytes: stats.size };
+        },
+        async fetchUnmappedTables(mappedPaths?: string[]) {
+            const allCollections = await db.listCollections().toArray();
+            const names = allCollections.map(c => c.name).filter(n => !n.startsWith("system."));
+            if (!mappedPaths || mappedPaths.length === 0) return names;
+            const mappedSet = new Set(mappedPaths.map(p => p.toLowerCase()));
+            return names.filter(n => !mappedSet.has(n.toLowerCase()));
+        },
+        async fetchTableMetadata(collectionName: string) {
+            // Sample a document to infer fields
+            const sample = await db.collection(collectionName).findOne();
+            if (!sample) return { columns: [],
+foreignKeys: [],
+junctions: [],
+policies: [] };
+            const columns = Object.entries(sample).map(([key, value]) => ({
+                column_name: key,
+                data_type: typeof value,
+                udt_name: typeof value,
+                is_nullable: "YES",
+                column_default: null,
+                character_maximum_length: null
+            }));
+            return { columns,
+foreignKeys: [],
+junctions: [],
+policies: [] };
+        }
+    } satisfies DocumentAdmin & SchemaAdmin;
+
+    return {
+        // Abstract interface implementations
+        connection: mongoConnection,
+        entityRepository: entityService,
+        realtimeProvider: realtimeService,
+        collectionRegistry: collectionRegistry,
+        admin,
+
+        // Lifecycle
+        async initialize() {
+            // Connection is already established via the MongoClient constructor
+        },
+        async healthCheck(): Promise<HealthCheckResult> {
+            const start = Date.now();
+            try {
+                await db.command({ ping: 1 });
+                return { healthy: true,
+latencyMs: Date.now() - start };
+            } catch {
+                return { healthy: false,
+latencyMs: Date.now() - start };
+            }
+        },
+        async destroy() {
+            await client.close();
+        },
+
+        // MongoDB-specific accessors
+        db,
+        client,
+        driver,
+        entityService,
+        realtimeService
+    };
+}
+
+/**
+ * Create a MongoDB DataDriver.
+ *
+ * This is a convenience function when you only need the DataDriver
+ * without the full backend instance.
+ *
+ * @example
+ * ```typescript
+ * import { createMongoDelegate } from "@rebasepro/server-mongodb";
+ *
+ * const delegate = createMongoDelegate(db);
+ * ```
+ */
+export function createMongoDelegate(
+    db: Db,
+    realtimeService?: MongoRealtimeService,
+    historyService?: MongoHistoryService
+): MongoDriver {
+    const realtime = realtimeService ?? new MongoRealtimeService(db);
+    const history = historyService ?? new MongoHistoryService(db);
+    return new MongoDriver(db, realtime, history);
+}
+
+/**
+ * Create a RealtimeService for MongoDB.
+ *
+ * @example
+ * ```typescript
+ * import { createMongoRealtimeService } from "@rebasepro/server-mongodb";
+ *
+ * const realtimeService = createMongoRealtimeService(db);
+ * ```
+ */
+export function createMongoRealtimeService(db: Db): MongoRealtimeService {
+    return new MongoRealtimeService(db);
+}
+
+/**
+ * Create a MongoDB entity repository.
+ *
+ * @example
+ * ```typescript
+ * import { createMongoEntityRepository } from "@rebasepro/server-mongodb";
+ *
+ * const repository = createMongoEntityRepository(db);
+ * const users = await repository.fetchCollection("users", {});
+ * ```
+ */
+export function createMongoEntityRepository(db: Db): EntityRepository {
+    return new MongoEntityService(db);
+}
+
+// =============================================================================
+// Type Guards
+// =============================================================================
+
+/**
+ * Check if a backend config is for MongoDB.
+ */
+export function isMongoBackendConfig(config: BackendConfig): config is MongoBackendConfig {
+    return config.type === "mongodb" &&
+        typeof (config as MongoBackendConfig).connection !== "undefined" &&
+        typeof (config as MongoBackendConfig).client !== "undefined";
+}
+
+/**
+ * Check if a driver config is for MongoDB.
+ */
+export function isMongoDriverConfig(obj: unknown): obj is { type: "mongodb"; connection: Db; client: MongoClient } {
+    return typeof obj === "object" &&
+        obj !== null &&
+        "type" in obj &&
+        (obj as Record<string, unknown>).type === "mongodb" &&
+        "connection" in obj &&
+        "client" in obj;
+}

package/src/history/ensure-history-collection.ts

@@ -0,0 +1,19 @@
+import { Db } from "mongodb";
+
+export async function ensureHistoryCollectionExists(db: Db): Promise<void> {
+    console.log("🔍 Checking MongoDB history collection and indexes...");
+
+    try {
+        const history = db.collection("__rebase_history");
+        
+        // Index for finding history entries for a specific entity
+        await history.createIndex({ entity_id: 1, table_name: 1, updated_at: -1 });
+
+        // Index for pruning by date
+        await history.createIndex({ updated_at: 1 });
+
+        console.log("✅ MongoDB History collection ready");
+    } catch (error) {
+        console.error("❌ Failed to set up MongoDB history collection:", error);
+    }
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * @rebasepro/server-mongodb
+ *
+ * MongoDB backend implementation for Rebase
+ * This package provides a complete backend solution for Rebase applications
+ * using MongoDB as the database.
+ *
+ * The package implements the abstract interfaces from @rebasepro/server-core
+ * (EntityRepository, RealtimeProvider, CollectionRegistryInterface, etc.)
+ */
+
+// Connection
+export * from "./connection";
+
+// Factory functions
+export * from "./factory";
+
+// Database services
+export * from "./db/MongoEntityService";
+export * from "./db/MongoConditionBuilder";
+
+// Services
+export * from "./services/MongoRealtimeService";
+export * from "./services/MongoDriver";
+export * from "./MongoBootstrapper";

package/src/services/MongoDriver.ts

@@ -0,0 +1,297 @@
+/**
+ * MongoDB DataDriver Delegate
+ *
+ * Implements the DataDriver interface for Rebase frontend integration.
+ * This is the main entry point for Rebase to interact with MongoDB.
+ */
+
+import { Db, ObjectId } from "mongodb";
+import {
+    DataDriver,
+    DeleteEntityProps,
+    Entity,
+    EntityCollection,
+    FetchCollectionProps,
+    FetchEntityProps,
+    ListenCollectionProps,
+    ListenEntityProps,
+    SaveEntityProps
+} from "@rebasepro/types";
+import { MongoEntityService } from "../db/MongoEntityService";
+import { MongoRealtimeService } from "./MongoRealtimeService";
+import { MongoHistoryService } from "./MongoHistoryService";
+
+/**
+ * MongoDB DataDriver Delegate
+ *
+ * Implements the DataDriver interface for Rebase.
+ * Provides all data operations needed by the Rebase frontend.
+ */
+export class MongoDriver implements DataDriver {
+    key = "mongodb";
+    initialised = true;
+
+    private entityService: MongoEntityService;
+    private realtimeService: MongoRealtimeService;
+    public historyService: MongoHistoryService;
+
+    constructor(
+        private db: Db,
+        realtimeService?: MongoRealtimeService,
+        historyService?: MongoHistoryService
+    ) {
+        this.entityService = new MongoEntityService(db);
+        this.realtimeService = realtimeService ?? new MongoRealtimeService(db);
+        this.historyService = historyService ?? new MongoHistoryService(db);
+    }
+
+
+    /**
+     * Get the current timestamp
+     */
+    currentTime(): Date {
+        return new Date();
+    }
+
+    /**
+     * Fetch a collection of entities
+     */
+    async fetchCollection<M extends Record<string, any>>({
+        path,
+        collection,
+        filter,
+        limit,
+        startAfter,
+        orderBy,
+        searchString,
+        order
+    }: FetchCollectionProps<M>): Promise<Entity<M>[]> {
+        return this.entityService.fetchCollection<M>(path, {
+            filter,
+            limit,
+            startAfter,
+            orderBy,
+            order,
+            searchString,
+            collection: collection as unknown as EntityCollection
+        });
+    }
+
+    /**
+     * Listen to collection changes
+     */
+    listenCollection<M extends Record<string, any>>({
+        path,
+        collection,
+        filter,
+        limit,
+        startAfter,
+        orderBy,
+        searchString,
+        order,
+        onUpdate,
+        onError
+    }: ListenCollectionProps<M>): () => void {
+        const subscriptionId = this.generateSubscriptionId();
+
+        const callback = (entities: Entity<any>[]) => {
+            try {
+                onUpdate(entities as Entity<M>[]);
+            } catch (error) {
+                console.error("Error in collection update callback:", error);
+                if (onError) {
+                    onError(error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+        };
+
+        this.realtimeService.subscribeToCollection(
+            subscriptionId,
+            {
+                clientId: "driver",
+                path,
+                filter,
+                orderBy,
+                order,
+                limit,
+                startAfter,
+                searchString
+            },
+            callback
+        );
+
+        // Return unsubscribe function
+        return () => {
+            this.realtimeService.unsubscribe(subscriptionId);
+        };
+    }
+
+    /**
+     * Fetch a single entity
+     */
+    async fetchEntity<M extends Record<string, any>>({
+        path,
+        entityId,
+        databaseId,
+        collection
+    }: FetchEntityProps<M>): Promise<Entity<M> | undefined> {
+        return this.entityService.fetchEntity<M>(path, entityId, databaseId);
+    }
+
+    /**
+     * Listen to entity changes
+     */
+    listenEntity<M extends Record<string, any>>({
+        path,
+        entityId,
+        collection,
+        onUpdate,
+        onError
+    }: ListenEntityProps<M>): () => void {
+        const subscriptionId = this.generateSubscriptionId();
+
+        const callback = (entity: Entity<any> | null) => {
+            try {
+                onUpdate(entity as Entity<M>);
+            } catch (error) {
+                console.error("Error in entity update callback:", error);
+                if (onError) {
+                    onError(error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+        };
+
+        this.realtimeService.subscribeToEntity(
+            subscriptionId,
+            {
+                clientId: "driver",
+                path,
+                entityId
+            },
+            callback
+        );
+
+        // Return unsubscribe function
+        return () => {
+            this.realtimeService.unsubscribe(subscriptionId);
+        };
+    }
+
+    /**
+     * Save an entity (create or update)
+     */
+    async saveEntity<M extends Record<string, any>>({
+        path,
+        entityId,
+        values,
+        previousValues,
+        collection,
+        status
+    }: SaveEntityProps<M>): Promise<Entity<M>> {
+        const isNew = status === "new" || !previousValues;
+
+        const entity = await this.entityService.saveEntity<M>(path, values, entityId);
+
+        // Handle history recording
+        if (collection?.history) {
+            this.historyService.recordHistory({
+                action: isNew ? "create" : "update",
+                entityId: String(entity.id),
+                tableName: path,
+                values: entity.values,
+                previousValues: isNew ? undefined : previousValues,
+            }).catch(err => {
+                // Fire and forget, don't fail the save operation
+                console.error(`Failed to record history for ${path}/${entity.id}:`, err);
+            });
+        }
+
+        // Notify subscribers of the update
+        await this.realtimeService.notifyEntityUpdate(path, String(entity.id), entity);
+
+        return entity;
+    }
+
+    /**
+     * Delete an entity
+     */
+    async deleteEntity<M extends Record<string, any>>({
+        entity,
+        collection
+    }: DeleteEntityProps<M>): Promise<void> {
+        await this.entityService.deleteEntity(entity.path, entity.id);
+
+        if (collection?.history) {
+            this.historyService.recordHistory({
+                action: "delete",
+                entityId: String(entity.id),
+                tableName: entity.path,
+                previousValues: entity.values,
+            }).catch(err => {
+                console.error(`Failed to record history for ${entity.path}/${entity.id}:`, err);
+            });
+        }
+
+        // Notify subscribers of the deletion
+        await this.realtimeService.notifyEntityUpdate(entity.path, String(entity.id), null);
+    }
+
+    /**
+     * Check if a field value is unique
+     */
+    async checkUniqueField(
+        path: string,
+        name: string,
+        value: any,
+        entityId?: string,
+        collection?: EntityCollection
+    ): Promise<boolean> {
+        return this.entityService.checkUniqueField(path, name, value, entityId);
+    }
+
+    /**
+     * Generate a new entity ID
+     */
+    generateEntityId(path: string, collection?: EntityCollection): string {
+        return this.entityService.generateEntityId();
+    }
+
+    /**
+     * Count entities in a collection
+     */
+    async countEntities<M extends Record<string, any>>({
+        path,
+        collection,
+        filter
+    }: FetchCollectionProps<M>): Promise<number> {
+        return this.entityService.countEntities<M>(path, { filter });
+    }
+
+    /**
+     * Generate a unique subscription ID
+     */
+    private generateSubscriptionId(): string {
+        return `mongo_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+    }
+
+    /**
+     * Check if the delegate is ready
+     */
+    isReady(): boolean {
+        return this.initialised;
+    }
+
+    /**
+     * Get the underlying entity service for direct access
+     */
+    getEntityService(): MongoEntityService {
+        return this.entityService;
+    }
+
+    /**
+     * Get the underlying realtime service for direct access
+     */
+    getRealtimeService(): MongoRealtimeService {
+        return this.realtimeService;
+    }
+}