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

package/src/serve-spa.ts

@@ -0,0 +1,81 @@
+import { Hono } from "hono";
+import { serveStatic } from "@hono/node-server/serve-static";
+import * as path from "path";
+import * as fs from "fs";
+
+/**
+ * Configuration for serving a Single Page Application
+ */
+export interface ServeSPAConfig {
+    /**
+     * Absolute path to the frontend build directory
+     * @example path.join(__dirname, "../../frontend/dist")
+     */
+    frontendPath: string;
+
+    /**
+     * Base path for API routes (default: "/api")
+     * Requests to this path will be passed through to API handlers
+     */
+    apiBasePath?: string;
+
+    /**
+     * Additional paths to exclude from SPA handling
+     * These paths will be passed through to other handlers
+     * @example ["/health", "/ws", "/metrics"]
+     */
+    excludePaths?: string[];
+
+    /**
+     * Index file to serve for SPA routes (default: "index.html")
+     */
+    indexFile?: string;
+}
+
+/**
+ * Serve a Single Page Application from an Hono app.
+ */
+export function serveSPA<E extends import("hono").Env>(app: Hono<E>, config: ServeSPAConfig): void {
+    const {
+        frontendPath,
+        apiBasePath = "/api",
+        excludePaths = [],
+        indexFile = "index.html"
+    } = config;
+
+    // Validate frontend path exists
+    if (!fs.existsSync(frontendPath)) {
+        console.warn(`⚠️ Frontend build path does not exist: ${frontendPath}`);
+        console.warn("   SPA serving is disabled. Build your frontend first.");
+        return;
+    }
+
+    // Serve static files from frontend build
+    app.use("/*", serveStatic({
+        root: path.relative(process.cwd(), frontendPath)
+    }));
+
+    // Build list of paths to exclude from SPA handling
+    const allExcludePaths = [apiBasePath, ...excludePaths];
+
+    // SPA fallback - serve index.html for all non-excluded routes
+    app.get("*", async (c, next) => {
+        // Skip excluded paths (API, health checks, etc.)
+        if (allExcludePaths.some(p => c.req.path.startsWith(p))) {
+            return next();
+        }
+
+        const indexPath = path.join(frontendPath, indexFile);
+
+        if (!fs.existsSync(indexPath)) {
+            console.warn(`⚠️ Index file not found: ${indexPath}`);
+            return next();
+        }
+
+        const html = fs.readFileSync(indexPath, "utf-8");
+        return c.html(html);
+    });
+
+    console.log(`✅ SPA serving enabled from: ${frontendPath}`);
+}
+

package/src/services/driver-registry.ts

@@ -0,0 +1,182 @@
+/**
+ * Driver Registry
+ *
+ * Manages multiple driver delegates for Rebase backend.
+ * Allows different databases for different collections.
+ *
+ * Usage:
+ * - Single DB: Pass a single DataDriver → maps to "(default)"
+ * - Multiple DBs: Pass a map of { dbId: DataDriver }
+ * - Collections use `databaseId` property to specify which driver to use
+ * - Collections without `databaseId` fallback to "(default)"
+ */
+
+import { DataDriver } from "@rebasepro/types";
+
+/**
+ * The default driver identifier used when:
+ * - A single driver is provided (not a map)
+ * - A collection doesn't specify a databaseId
+ */
+export const DEFAULT_DRIVER_ID = "(default)";
+
+/**
+ * Registry for managing multiple driver delegates
+ */
+export interface DriverRegistry {
+    /**
+     * Register a driver delegate with an ID
+     * @param id - Unique identifier for this driver (e.g., "analytics", "users")
+     * @param delegate - The DataDriver instance
+     */
+    register(id: string, delegate: DataDriver): void;
+
+    /**
+     * Get the default driver delegate (id = "(default)")
+     * @throws Error if no default driver is registered
+     */
+    getDefault(): DataDriver;
+
+    /**
+     * Get a driver delegate by ID
+     * @param id - Driver identifier, or undefined/null for default
+     * @returns The DataDriver, or undefined if not found
+     */
+    get(id: string | undefined | null): DataDriver | undefined;
+
+    /**
+     * Get a driver delegate by ID, with fallback to default
+     * @param id - Driver identifier, or undefined/null for default
+     * @returns The DataDriver (falls back to default if id not found)
+     * @throws Error if neither the specified nor default driver exists
+     */
+    getOrDefault(id: string | undefined | null): DataDriver;
+
+    /**
+     * Check if a driver with the given ID exists
+     */
+    has(id: string): boolean;
+
+    /**
+     * List all registered driver IDs
+     */
+    list(): string[];
+
+    /**
+     * Get the number of registered drivers
+     */
+    size(): number;
+}
+
+/**
+ * Default implementation of DriverRegistry
+ */
+export class DefaultDriverRegistry implements DriverRegistry {
+    private delegates = new Map<string, DataDriver>();
+
+    /**
+     * Create a DriverRegistry from either a single delegate or a map
+     * @param input - Single DataDriver (maps to "(default)") or Record<string, DataDriver>
+     */
+    static create(
+        input: DataDriver | Record<string, DataDriver>
+    ): DefaultDriverRegistry {
+        const registry = new DefaultDriverRegistry();
+
+        if (isDataDriverDelegate(input)) {
+            // Single delegate → register as "(default)"
+            registry.register(DEFAULT_DRIVER_ID, input);
+        } else {
+            // Map of delegates → register each
+            for (const [id, delegate] of Object.entries(input)) {
+                registry.register(id, delegate);
+            }
+            // Ensure there's a default if not explicitly provided
+            if (!registry.has(DEFAULT_DRIVER_ID) && registry.size() > 0) {
+                // If no explicit "(default)", use the first one as default
+                const firstId = Object.keys(input)[0];
+                console.warn(
+                    `[DriverRegistry] No "${DEFAULT_DRIVER_ID}" driver provided. ` +
+                    `Using "${firstId}" as the default.`
+                );
+                registry.register(DEFAULT_DRIVER_ID, input[firstId]);
+            }
+        }
+
+        return registry;
+    }
+
+    register(id: string, delegate: DataDriver): void {
+        if (this.delegates.has(id)) {
+            console.warn(`[DriverRegistry] Overwriting driver with id "${id}"`);
+        }
+        this.delegates.set(id, delegate);
+    }
+
+    getDefault(): DataDriver {
+        const delegate = this.delegates.get(DEFAULT_DRIVER_ID);
+        if (!delegate) {
+            throw new Error(
+                "[DriverRegistry] No default driver registered. " +
+                `Register one with id "${DEFAULT_DRIVER_ID}" or pass a single DataDriver.`
+            );
+        }
+        return delegate;
+    }
+
+    get(id: string | undefined | null): DataDriver | undefined {
+        if (id === undefined || id === null) {
+            return this.delegates.get(DEFAULT_DRIVER_ID);
+        }
+        return this.delegates.get(id);
+    }
+
+    getOrDefault(id: string | undefined | null): DataDriver {
+        // If no ID specified, return default
+        if (id === undefined || id === null) {
+            return this.getDefault();
+        }
+
+        // Try to get by ID
+        const delegate = this.delegates.get(id);
+        if (delegate) {
+            return delegate;
+        }
+
+        // Fallback to default with warning
+        console.warn(
+            `[DriverRegistry] Driver "${id}" not found, falling back to "${DEFAULT_DRIVER_ID}"`
+        );
+        return this.getDefault();
+    }
+
+    has(id: string): boolean {
+        return this.delegates.has(id);
+    }
+
+    list(): string[] {
+        return Array.from(this.delegates.keys());
+    }
+
+    size(): number {
+        return this.delegates.size;
+    }
+}
+
+/**
+ * Type guard to check if an object is a DataDriver
+ */
+function isDataDriverDelegate(obj: unknown): obj is DataDriver {
+    if (typeof obj !== "object" || obj === null) {
+        return false;
+    }
+    const delegate = obj as DataDriver;
+    // Check for required DataDriver properties
+    return (
+        typeof delegate.key === "string" &&
+        typeof delegate.fetchCollection === "function" &&
+        typeof delegate.fetchEntity === "function" &&
+        typeof delegate.saveEntity === "function" &&
+        typeof delegate.deleteEntity === "function"
+    );
+}

package/src/singleton.test.ts

@@ -0,0 +1,28 @@
+import { rebase, _initRebase } from "./singleton";
+import type { RebaseClient } from "@rebasepro/types";
+
+describe("rebase singleton", () => {
+    beforeEach(() => {
+        // Reset the singleton before each test
+        // By calling _initRebase with null (cast to bypass type checking for the reset)
+        _initRebase(null as unknown as RebaseClient);
+    });
+
+    it("should throw an error if accessed before initialization", () => {
+        expect(() => rebase.data).toThrow(
+            "rebase.data: server not initialized yet. The singleton is available after Rebase starts — don't call it at import time."
+        );
+    });
+
+    it("should return the correctly initialized instance properties", () => {
+        const mockClient = {
+            data: { test: "mockData" },
+            auth: { test: "mockAuth" }
+        } as unknown as RebaseClient;
+
+        _initRebase(mockClient);
+
+        expect(rebase.data).toEqual({ test: "mockData" });
+        expect(rebase.auth).toEqual({ test: "mockAuth" });
+    });
+});

package/src/singleton.ts

@@ -0,0 +1,70 @@
+import type { RebaseClient } from "@rebasepro/types";
+
+let _instance: RebaseClient | null = null;
+
+/**
+ * @internal Called once during server initialization to set the backing instance.
+ * This is invoked by `initializeRebaseBackend()` — never call it manually.
+ */
+export function _initRebase(client: RebaseClient): void {
+    _instance = client;
+}
+
+/**
+ * @internal Allows overriding the underlying instance for unit testing.
+ * Throws an error if used in a non-test environment to prevent production abuse.
+ */
+export function _setRebaseMock(mockInstance: Partial<RebaseClient>): void {
+    if (process.env.NODE_ENV !== "test") {
+        throw new Error("_setRebaseMock can only be called in a test environment (NODE_ENV=test).");
+    }
+    _instance = { ...(_instance || {} as RebaseClient),
+...mockInstance } as RebaseClient;
+}
+
+/**
+ * @internal Resets the singleton instance, useful for afterEach() in test suites.
+ */
+export function _resetRebaseMock(): void {
+    if (process.env.NODE_ENV !== "test") {
+        throw new Error("_resetRebaseMock can only be called in a test environment.");
+    }
+    _instance = null;
+}
+
+/**
+ * The server-side Rebase singleton.
+ *
+ * Initialized automatically during server startup. Provides access to all
+ * app-scoped services: **data**, **auth**, **storage**, and **email**.
+ *
+ * `rebase.data` runs with **admin privileges** (no RLS). For user-scoped
+ * queries inside request handlers, continue using the handler's context
+ * or the RLS-scoped driver.
+ *
+ * @example
+ * ```typescript
+ * import { rebase } from "@rebasepro/server-core";
+ *
+ * // In a Hono handler, cron job, hook, or service file:
+ * await rebase.email?.send({ to: "admin@co.com", subject: "Alert", html: "<p>Hi</p>" });
+ * const jobs = await rebase.data.jobs.find({ limit: 10 });
+ * ```
+ */
+export const rebase: RebaseClient = new Proxy({} as RebaseClient, {
+    get(_, prop) {
+        if (!_instance) {
+            throw new Error(
+                `rebase.${String(prop)}: server not initialized yet. ` +
+                "The singleton is available after Rebase starts — don't call it at import time."
+            );
+        }
+        return _instance[prop as keyof RebaseClient];
+    },
+    set(_, prop) {
+        throw new Error(
+            `Cannot set rebase.${String(prop)} directly. ` +
+            "The singleton is read-only. Use _initRebase() during server startup."
+        );
+    }
+});