@rebasepro/server-mongo 0.17.3 → 0.18.1

package/src/factory.ts

@@ -1,331 +0,0 @@
-/**
- * MongoDB Backend Factory
- *
- * This module provides factory functions for creating MongoDB backend instances.
- * It abstracts the creation of drivers, realtime services, and row services.
- */
-
-import { Db, MongoClient } from "mongodb";
-import { DataDriver, CollectionConfig, getCollectionDataPath } from "@rebasepro/types";
-
-import { MongoDataService } from "./db/MongoDataService";
-import { MongoRealtimeService } from "./services/MongoRealtimeService";
-import { MongoDriver } from "./services/MongoDriver";
-import { MongoHistoryService, HistoryRetentionConfig } from "./services/MongoHistoryService";
-import { MongoDBConnection } from "./connection";
-import { BackendConfig, BackendInstance, CollectionRegistryInterface, DataRepository, RealtimeProvider, DatabaseConnection, DatabaseAdmin, DocumentAdmin, SchemaAdmin, SchemaEditingAdmin, HealthCheckResult } from "@rebasepro/types";
-import { planMongoSchemaChange } from "./schema/plan-schema-change";
-
-/**
- * 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?: CollectionConfig[];
-    /** 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 */
-    dataService: MongoDataService;
-    /** 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 {
-    /** Every addressable key → collection. See {@link register}. */
-    private collections = new Map<string, CollectionConfig>();
-    /** Registration order, so `getCollections()` returns each collection once. */
-    private registered: CollectionConfig[] = [];
-    private _globalCallbacks?: any;
-
-    /**
-     * Register a collection under every name it can be addressed by.
-     *
-     * A Mongo collection has up to three: `slug` (the routing key), `path` (the
-     * MongoDB collection-name override, which is what `getCollectionDataPath`
-     * hands the driver) and `name` (the human label). Registering only `name`
-     * meant every `getCollectionByPath` lookup missed — and the realtime path,
-     * whose only source of the collection is this registry, ran with no
-     * `securityRules`, no `properties` and no callbacks.
-     */
-    register(collection: CollectionConfig): void {
-        this.registered.push(collection);
-        for (const key of [getCollectionDataPath(collection), collection.slug, collection.name]) {
-            if (key) this.collections.set(key, collection);
-        }
-    }
-
-    /**
-     * Get a collection by its path
-     */
-    getCollectionByPath(path: string): CollectionConfig | undefined {
-        return this.collections.get(path);
-    }
-
-    /**
-     * Get all registered collections
-     */
-    getCollections(): CollectionConfig[] {
-        return [...this.registered];
-    }
-
-    /**
-     * Get the currently registered global callbacks, if any.
-     */
-    getGlobalCallbacks(): any | undefined {
-        return this._globalCallbacks;
-    }
-
-    /**
-     * Set global lifecycle callbacks that apply to every collection.
-     */
-    setGlobalCallbacks(callbacks: any): void {
-        this._globalCallbacks = callbacks;
-    }
-}
-
-// =============================================================================
-// Factory Functions
-// =============================================================================
-
-/**
- * Create a complete MongoDB backend instance.
- *
- * This factory function creates all the necessary services for a MongoDB backend:
- * - MongoDBConnection (database connection wrapper)
- * - MongoDataService (implements DataRepository)
- * - MongoRealtimeService (implements RealtimeProvider)
- * - MongoCollectionRegistry (implements CollectionRegistryInterface)
- * - MongoDriver (for Rebase integration)
- *
- * @example
- * ```typescript
- * import { createMongoBackend } from "@rebasepro/server-mongo";
- *
- * 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 rows = 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 dataService = new MongoDataService(db);
-    const realtimeService = new MongoRealtimeService(db);
-    const historyService = new MongoHistoryService(db, config.historyRetention);
-    const driver = new MongoDriver(db, realtimeService, historyService, collectionRegistry);
-    const mongoConnection = new MongoDBConnection(db, client);
-
-    // Build admin capabilities for MongoDB
-    const admin: DatabaseAdmin = {
-        // A document database has no table to alter, so a collection change is
-        // the commit and nothing else. Offered here because `isSchemaEditingAdmin`
-        // is a structural check: without this method a Mongo project was told
-        // live schema editing was *unsupported*, when it is the one place the
-        // change cannot fail.
-        planSchemaChange: async (before, after) => planMongoSchemaChange(
-            before as CollectionConfig[],
-            after as CollectionConfig[]
-        ),
-        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` narrows the literal regardless of the annotation above, so
-        // the schema-editing method has to be named here too or it reads as an
-        // excess property.
-    } satisfies DocumentAdmin & SchemaAdmin & SchemaEditingAdmin;
-
-    return {
-        // Abstract interface implementations
-        connection: mongoConnection,
-        entityRepository: dataService,
-        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,
-        dataService,
-        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-mongo";
- *
- * const delegate = createMongoDelegate(db);
- * ```
- */
-export function createMongoDelegate(
-    db: Db,
-    realtimeService?: MongoRealtimeService,
-    historyService?: MongoHistoryService,
-    registry?: CollectionRegistryInterface
-): MongoDriver {
-    const realtime = realtimeService ?? new MongoRealtimeService(db);
-    const history = historyService ?? new MongoHistoryService(db);
-    return new MongoDriver(db, realtime, history, registry);
-}
-
-/**
- * Create a RealtimeService for MongoDB.
- *
- * @example
- * ```typescript
- * import { createMongoRealtimeService } from "@rebasepro/server-mongo";
- *
- * const realtimeService = createMongoRealtimeService(db);
- * ```
- */
-export function createMongoRealtimeService(db: Db): MongoRealtimeService {
-    return new MongoRealtimeService(db);
-}
-
-/**
- * Create a MongoDB row repository.
- *
- * @example
- * ```typescript
- * import { createMongoEntityRepository } from "@rebasepro/server-mongo";
- *
- * const repository = createMongoEntityRepository(db);
- * const users = await repository.fetchCollection("users", {});
- * ```
- */
-export function createMongoEntityRepository(db: Db): DataRepository {
-    return new MongoDataService(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

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

package/src/index.ts

@@ -1,25 +0,0 @@
-/**
- * @rebasepro/server-mongo
- *
- * 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
- * (DataRepository, RealtimeProvider, CollectionRegistryInterface, etc.)
- */
-
-// Connection
-export * from "./connection";
-
-// Factory functions
-export * from "./factory";
-
-// Database services
-export * from "./db/MongoDataService";
-export * from "./db/MongoConditionBuilder";
-
-// Services
-export * from "./services/MongoRealtimeService";
-export * from "./services/MongoDriver";
-export * from "./MongoBootstrapper";

package/src/schema/plan-schema-change.ts

@@ -1,159 +0,0 @@
-/**
- * Planning a collection change for MongoDB.
- *
- * Shorter than the Postgres one by the whole of its difficulty. A document
- * database has no table to alter: adding a property adds nothing, removing one
- * removes nothing, and a document written yesterday is still valid tomorrow. So
- * the plan is the commit, and there is no DDL to run, refuse or get wrong.
- *
- * ## Why this exists at all, rather than leaving Mongo unsupported
- *
- * Because "unsupported" was the wrong answer, and it was the answer only
- * because nothing had been written here. `isSchemaEditingAdmin` is a structural
- * check — a driver either offers `planSchemaChange` or it does not — so a Mongo
- * project got `SCHEMA_EDITING_UNSUPPORTED` and fell back to the source-only
- * editor, which is off in production. A schemaless database is the one place
- * where changing a collection against a *running* backend is completely safe,
- * and it was the one place it did not work.
- *
- * ## What a verdict means here
- *
- * Every change is `safe`, because none of them can fail. That is not the
- * classifier being lax: on Postgres a verdict answers "will the database end up
- * matching this configuration", and here it always does — there is nothing in
- * the database that describes the shape.
- *
- * What the changes still say is what happens to the **data**, because that is
- * the part a reader can be surprised by. Removing a property does not delete
- * the field from documents that have it; those documents keep it and the API
- * stops serving it. Saying so is the difference between a reader who knows the
- * data is still there and one who assumes it is gone.
- */
-import type {
-    CollectionConfig,
-    SchemaChange,
-    SchemaChangePlan
-} from "@rebasepro/types";
-
-const bySlug = (collections: CollectionConfig[]): Map<string, CollectionConfig> => {
-    const map = new Map<string, CollectionConfig>();
-    for (const collection of collections) {
-        if (collection.slug) map.set(collection.slug, collection);
-    }
-    return map;
-};
-
-const propertiesOf = (collection: CollectionConfig): Record<string, unknown> =>
-    (collection.properties ?? {}) as Record<string, unknown>;
-
-/**
- * What changed, in the terms a document database makes true.
- *
- * Exported because it is the interesting half and worth testing without a
- * driver: the shape of the answer is the product, and the rest is plumbing.
- */
-export function classifyMongoChanges(
-    before: CollectionConfig[],
-    after: CollectionConfig[]
-): SchemaChange[] {
-    const previous = bySlug(before);
-    const next = bySlug(after);
-    const changes: SchemaChange[] = [];
-
-    for (const [slug, collection] of next) {
-        if (!previous.has(slug)) {
-            changes.push({
-                kind: "add-collection",
-                verdict: "safe",
-                collection: slug,
-                detail: `New collection "${slug}". MongoDB creates it on the first write; nothing ` +
-                    "is created now."
-            });
-            continue;
-        }
-
-        const oldProps = propertiesOf(previous.get(slug)!);
-        const newProps = propertiesOf(collection);
-
-        for (const name of Object.keys(newProps)) {
-            if (name in oldProps) continue;
-            changes.push({
-                kind: "add-property",
-                verdict: "safe",
-                collection: slug,
-                property: name,
-                detail: `New property "${name}". Existing documents do not have it and are not ` +
-                    "rewritten; reads return it as absent until something writes it."
-            });
-        }
-
-        for (const name of Object.keys(oldProps)) {
-            if (name in newProps) continue;
-            changes.push({
-                kind: "remove-property",
-                verdict: "safe",
-                collection: slug,
-                property: name,
-                // The one thing worth being explicit about. On Postgres this is
-                // refused because it would drop a column; here nothing is
-                // dropped, and a reader who assumes otherwise has it backwards.
-                detail: `"${name}" is no longer served. Documents that have it keep it — MongoDB ` +
-                    "stores no schema, so nothing is removed from the data."
-            });
-        }
-    }
-
-    for (const [slug] of previous) {
-        if (next.has(slug)) continue;
-        changes.push({
-            kind: "remove-collection",
-            verdict: "safe",
-            collection: slug,
-            detail: `Collection "${slug}" is no longer served. The MongoDB collection and every ` +
-                "document in it are left exactly as they are."
-        });
-    }
-
-    return changes;
-}
-
-/** A commit message that says what changed rather than that something did. */
-function commitMessage(changes: SchemaChange[]): string {
-    if (changes.length === 0) return "chore(schema): no change";
-
-    const collections = [...new Set(changes.map(c => c.collection))].sort();
-    const added = changes.filter(c => c.kind === "add-collection");
-    const properties = changes.filter(c => c.kind === "add-property");
-
-    const subject = added.length === 1 && changes.length === 1
-        ? `add the ${added[0].collection} collection`
-        : properties.length === 1 && changes.length === 1
-            ? `add ${properties[0].property} to ${properties[0].collection}`
-            : collections.length === 1
-                ? `${changes.length} change(s) to ${collections[0]}`
-                : `${changes.length} change(s) across ${collections.length} collections`;
-
-    return `feat(schema): ${subject}\n\n${changes.map(c => `- ${c.detail}`).join("\n")}\n`;
-}
-
-/**
- * The plan: a commit, and nothing to run.
- *
- * `files` is empty here and filled by the caller with the rewritten collection
- * source. Postgres adds generated artifacts — a Drizzle schema, declarative
- * DDL — because a stale one breaks the next deploy. MongoDB generates none, so
- * the collection file is the whole of the change.
- */
-export async function planMongoSchemaChange(
-    before: CollectionConfig[],
-    after: CollectionConfig[]
-): Promise<SchemaChangePlan> {
-    const changes = classifyMongoChanges(before, after);
-    return {
-        files: [],
-        statements: [],
-        classified: { changes, verdict: "safe", applicable: true },
-        message: commitMessage(changes),
-        withheldConstraints: []
-    };
-}