@rebasepro/types 0.17.3 → 0.18.1

package/src/types/database_adapter.ts

@@ -1,267 +0,0 @@
-/**
- * @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-postgres";
- *
- * initializeRebaseBackend({
- *   database: createPostgresAdapter({ connection: db, schema }),
- *   auth: { jwtSecret: "..." },
- * });
- * ```
- *
- * @group Backend
- */
-
-import type { DataDriver } from "../controllers/data_driver";
-import type { CollectionConfig } from "./collections";
-import type {
-    CollectionRegistryInterface,
-    DatabaseAdmin,
-    InitializedDriver,
-    RealtimeProvider,
-    BootstrappedAuth
-} from "./backend";
-import type { HistoryConfig } from "../controllers/client";
-
-/**
- * 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: HistoryConfig,
-        driverResult: InitializedDriver,
-    ): Promise<{ historyService: unknown } | undefined>;
-
-    /**
-     * Initialize WebSocket server for realtime operations.
-     *
-     * `adapter` is the configured AuthAdapter, if any. It is what makes the
-     * socket secure by default: an implementation that receives one requires
-     * authentication regardless of whether a local `jwtSecret` exists. The
-     * parameter was missing from this signature while the caller in `init.ts`
-     * already passed it, so it was dropped at every adapter that routed through
-     * here — turning an adapter-authenticated server's socket into one that
-     * accepted every client as already authenticated.
-     */
-    initializeWebsockets?(
-        server: unknown,
-        realtimeService: RealtimeProvider,
-        driver: DataDriver,
-        config?: unknown,
-        adapter?: import("./auth_adapter").AuthAdapter,
-    ): Promise<void> | void;
-
-    /**
-     * Bring the database's collection tables up to date, additively — the boot
-     * companion to `db push`. See `BackendBootstrapper.ensureCollectionSchema`
-     * for the contract (create-only; never drop, narrow, or rewrite).
-     *
-     * Optional, and MUST be forwarded by any wrapper that turns this adapter
-     * into a `BackendBootstrapper`: the runtime calls it through the bootstrapper
-     * at boot, and a wrapper that silently omits it leaves a managed tenant
-     * 500ing every data route with no create step ever having run.
-     *
-     * `driverResult` is optional because this runs BEFORE `initializeDriver`, so
-     * there may be no result to pass. The bundle path can supply a pre-init
-     * stand-in because the coordinator opened the connection itself; an app that
-     * constructed this adapter never handed the framework a connection handle,
-     * so it passes `undefined` and the adapter MUST fall back to the connection
-     * it was constructed with. An adapter that dereferences `driverResult`
-     * unconditionally works for managed tenants and breaks every self-built one.
-     */
-    ensureCollectionSchema?(
-        collections: unknown[],
-        driverResult?: InitializedDriver,
-        log?: (message: string) => void,
-    ): Promise<{ applied: number }>;
-
-    /**
-     * Apply the collections' RLS policies (ENABLE ROW LEVEL SECURITY + the
-     * `securityRules` compiled to `CREATE POLICY`) — the boot companion to the
-     * policy half of `db push`. Idempotent; see
-     * `BackendBootstrapper.ensureCollectionPolicies`.
-     *
-     * Same forwarding requirement as `ensureCollectionSchema`: without the
-     * policies, tables exist but every user-context read is denied (a public
-     * collection answers 401).
-     */
-    ensureCollectionPolicies?(
-        collections: unknown[],
-        driverResult?: InitializedDriver,
-        log?: (message: string) => void,
-    ): Promise<{ applied: number }>;
-
-    /**
-     * Read the collections schema version this database was last provisioned
-     * from, or `null` when nothing has ever stamped it.
-     *
-     * `null` is not an error and MUST NOT be treated as one — every database
-     * provisioned before the stamp existed reads this way, and so does every
-     * fresh one until its first provisioning boot finishes.
-     *
-     * Same forwarding requirement as the two hooks above: a wrapper that omits
-     * it turns the check off, and a check that is off looks exactly like a check
-     * that passed.
-     */
-    readCollectionsSchemaVersion?(
-        driverResult?: InitializedDriver,
-    ): Promise<string | null>;
-
-    /**
-     * Record the collections schema version this process just applied.
-     *
-     * Called only by the process that provisions, and only after the tables AND
-     * the policies are in place — a stamp written earlier would claim a schema
-     * that a half-finished boot never finished creating.
-     */
-    stampCollectionsSchemaVersion?(
-        version: string,
-        driverResult?: InitializedDriver,
-    ): Promise<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: CollectionConfig[];
-    /** The shared collection registry to register into. */
-    collectionRegistry: CollectionRegistryInterface;
-    /**
-     * Whether this driver should describe its own schema.
-     *
-     * True when the project declared no collections, so there is nothing to
-     * serve unless the driver reads the live database and reports what it found
-     * on `InitializedDriver.collections`. Drivers that cannot introspect may
-     * ignore it — `initializeRebaseBackend` fails the boot with their name
-     * rather than serving nothing.
-     *
-     * This was a `mode: "cms" | "baas"` flag, which was never independent of
-     * `collections`: every consumer already required the list to be empty
-     * before acting on it, so the flag could only ever agree or contradict.
-     */
-    introspectCollections?: boolean;
-    /**
-     * Options for an introspecting driver — see `RebaseBackendConfig.baas`.
-     * Drivers that introspect should honour `unprotectedTables`.
-     */
-    baas?: { unprotectedTables?: "exclude" | "serve" };
-    /**
-     * What the runtime's boot-time table provisioning did, in this process,
-     * before this driver was initialized.
-     *
-     * A driver that checks for missing tables cannot otherwise tell "the create
-     * step ran and this table still is not here" from "no create step ran at
-     * all" — and those need opposite advice. The Postgres driver's drift warning
-     * assumed the first, told operators to redeploy with REBASE_MIGRATE_ON_BOOT
-     * unset, and pointed at driver version skew; for an app whose boot path had
-     * no provisioning step, all of that was unactionable and one investigation
-     * chased a driver that was perfectly current.
-     *
-     * Absent when the caller predates this field: treat that as "unknown" and
-     * fall back to generic guidance rather than asserting either case.
-     */
-    schemaProvisioning?: {
-        /** Whether the table-creation hook actually ran this boot. */
-        attempted: boolean;
-        /** Why it did not, when it did not — safe to print verbatim. */
-        reason?: string;
-    };
-    /**
-     * What this process wants from the realtime subsystem.
-     *
-     * Both halves used to be assumed true, and both were wrong for a split
-     * deployment. A `functions` or `worker` process has no websocket clients, so
-     * consuming change events buys it a dedicated `LISTEN` connection to deliver
-     * to nobody; and it is explicitly not the process that owns schema DDL, so
-     * installing capture triggers from it contradicts the one-owner rule the
-     * runtime otherwise refuses to boot without.
-     *
-     * Absent means both — every caller that predates this field is a
-     * single-process deployment, where both are true.
-     */
-    realtime?: {
-        /**
-         * Consume change events: open the `LISTEN` connection, start CDC or the
-         * app-level fallback. False for a process that serves no websockets.
-         *
-         * Writes made by a non-consuming process are still published: capture is
-         * database triggers, so the publisher is the database.
-         */
-        subscribe: boolean;
-        /**
-         * Install what capture needs — the trigger function, the per-table
-         * triggers, any channel-history tables. This is DDL, and it follows the
-         * same single-owner rule as every other boot-time schema change.
-         */
-        provision: boolean;
-    };
-}

package/src/types/entities.ts

@@ -1,226 +0,0 @@
-import type { SearchMatch } from "./search";
-/**
- * New or existing status
- * @group Models
- */
-export type EntityStatus = "new" | "existing" | "copy";
-
-/**
- * Representation of a 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>;
-
-    /**
-     * Why this entity is in a search result: which declared fields matched, and
-     * the text around each hit.
-     *
-     * Present only on rows returned by a search that asked for it. A sibling of
-     * `values` rather than a key inside it, because it describes the *query*,
-     * not the record — nothing in the collection declares it, no form edits it,
-     * and a record fetched by id never has one.
-     */
-    searchMatches?: SearchMatch[];
-
-    /**
-     * 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 a 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 a 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 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 a 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) {
-        this.id = props.id;
-        this.path = props.path;
-        this.driver = props.driver;
-        this.databaseId = props.databaseId;
-    }
-
-    get pathWithId() {
-        return `${this.path}/${this.id}`;
-    }
-
-    /**
-     * 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() {
-        const parts: string[] = [];
-
-        // Add driver prefix if not default
-        if (this.driver && this.driver !== "(default)") {
-            parts.push(this.driver);
-        }
-
-        // Add database prefix if specified
-        if (this.databaseId && this.databaseId !== "(default)") {
-            parts.push(this.databaseId);
-        }
-
-        if (parts.length > 0) {
-            return `${parts.join(":")}:::${this.path}/${this.id}`;
-        }
-        return this.pathWithId;
-    }
-
-    isEntityReference() {
-        return true;
-    }
-}
-
-/**
- * Class used to create a reference to a entity in a different path
- */
-export 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?: Record<string, unknown>;
-
-    constructor(id: string | number, path: string, data?: Record<string, unknown>) {
-        this.id = id;
-        this.path = path;
-        this.data = data;
-    }
-
-    get pathWithId() {
-        return `${this.path}/${this.id}`;
-    }
-
-    isEntityReference() {
-        return false;
-    }
-
-    isEntityRelation() {
-        return true;
-    }
-}
-
-export 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) {
-        this.latitude = latitude;
-        this.longitude = longitude;
-    }
-}
-
-export class Vector {
-    readonly value: number[];
-
-    constructor(value: number[]) {
-        this.value = value;
-    }
-}