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

package/dist/server-postgresql/src/services/entityService.d.ts

@@ -0,0 +1,104 @@
+import { Entity, FilterValues } from "@rebasepro/types";
+import { EntityFetchService } from "./EntityFetchService";
+import { EntityPersistService } from "./EntityPersistService";
+import { RelationService } from "./RelationService";
+import { EntityRepository, DrizzleClient } from "../interfaces";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+export { sanitizeAndConvertDates, serializeDataToServer, parseDataFromServer } from "../data-transformer";
+export { EntityFetchService } from "./EntityFetchService";
+export { EntityPersistService } from "./EntityPersistService";
+export { RelationService } from "./RelationService";
+export * from "../interfaces";
+/**
+ * EntityService - Facade for entity operations.
+ *
+ * This class provides a unified API for entity CRUD operations by delegating
+ * to specialized services:
+ * - EntityFetchService: Read operations (fetch, search, count)
+ * - EntityPersistService: Write operations (save, delete)
+ * - RelationService: Relation operations (fetch related, update relations)
+ *
+ * Implements the EntityRepository interface for database abstraction.
+ */
+export declare class EntityService implements EntityRepository {
+    private db;
+    private registry;
+    private fetchService;
+    private persistService;
+    constructor(db: DrizzleClient, registry: PostgresCollectionRegistry);
+    /**
+     * Fetch a single entity by ID
+     */
+    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, unknown>>(collectionPath: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        offset?: number;
+        startAfter?: Record<string, unknown>;
+        searchString?: string;
+        databaseId?: string;
+    }): Promise<Entity<M>[]>;
+    /**
+     * Search entities by text
+     */
+    searchEntities<M extends Record<string, unknown>>(collectionPath: string, searchString: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        databaseId?: string;
+    }): Promise<Entity<M>[]>;
+    /**
+     * Count entities in a collection
+     */
+    countEntities<M extends Record<string, unknown>>(collectionPath: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        searchString?: string;
+        databaseId?: string;
+    }): Promise<number>;
+    /**
+     * Check if a field value is unique in a collection
+     */
+    checkUniqueField(collectionPath: string, fieldName: string, value: unknown, excludeEntityId?: string, databaseId?: string): Promise<boolean>;
+    /**
+     * Fetch entities related to a parent entity
+     */
+    fetchRelatedEntities<M extends Record<string, unknown>>(parentCollectionPath: string, parentEntityId: string | number, relationKey: string, options?: {
+        filter?: FilterValues<Extract<keyof M, string>>;
+        orderBy?: string;
+        order?: "desc" | "asc";
+        limit?: number;
+        startAfter?: Record<string, unknown>;
+        searchString?: string;
+        databaseId?: string;
+    }): Promise<Entity<M>[]>;
+    /**
+     * Save an entity (create or update)
+     */
+    saveEntity<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, entityId?: string | number, databaseId?: string): Promise<Entity<M>>;
+    /**
+     * Delete an entity by ID
+     */
+    deleteEntity(collectionPath: string, entityId: string | number, databaseId?: string): Promise<void>;
+    /**
+     * Execute raw SQL
+     */
+    executeSql(sqlText: string): Promise<Record<string, unknown>[]>;
+    /**
+     * Get the underlying EntityFetchService for advanced use
+     */
+    getFetchService(): EntityFetchService;
+    /**
+     * Get the underlying EntityPersistService for advanced use
+     */
+    getPersistService(): EntityPersistService;
+    /**
+     * Get the underlying RelationService for advanced use
+     */
+    getRelationService(): RelationService;
+}

package/dist/server-postgresql/src/services/index.d.ts

@@ -0,0 +1,4 @@
+export { EntityFetchService } from "./EntityFetchService";
+export { EntityPersistService } from "./EntityPersistService";
+export { RelationService } from "./RelationService";
+export { getCollectionByPath, getTableForCollection, getPrimaryKeys, parseIdValues, buildCompositeId } from "./entity-helpers";

package/dist/server-postgresql/src/services/realtimeService.d.ts

@@ -0,0 +1,188 @@
+import { WebSocket } from "ws";
+import { EventEmitter } from "events";
+import { Entity, DataDriver, WebSocketMessage } from "@rebasepro/types";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { RealtimeProvider, CollectionSubscriptionConfig, EntitySubscriptionConfig } from "../interfaces";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+/**
+ * Auth context stored per-subscription so real-time refetches respect RLS.
+ * Mirrors the session variables set by PostgresBackendDriver.withAuth().
+ */
+export interface SubscriptionAuthContext {
+    userId: string;
+    roles: string[];
+}
+/**
+ * PostgreSQL-specific realtime service.
+ * Handles WebSocket connections and subscriptions for real-time entity updates.
+ *
+ * Implements the RealtimeProvider interface for database abstraction.
+ */
+export declare class RealtimeService extends EventEmitter implements RealtimeProvider {
+    private db;
+    private registry;
+    private clients;
+    private entityService;
+    private _subscriptions;
+    private subscriptionCallbacks;
+    private driver?;
+    /** Unique identifier for this process instance, used to skip own notifications. */
+    private readonly instanceId;
+    /** Dedicated pg.Client for LISTEN (outside the Drizzle pool). */
+    private listenClient?;
+    /** Connection string used for reconnecting the LISTEN client. */
+    private listenConnectionString?;
+    /** Whether cross-instance broadcasting is active. */
+    private broadcasting;
+    /** Reconnection timer handle. */
+    private reconnectTimer?;
+    /** Debounce timers for collection refetches to prevent refetch storms. */
+    private refetchTimers;
+    /** Debounce window (ms) for coalescing rapid entity updates into a single correctness refetch. */
+    private static readonly REFETCH_DEBOUNCE_MS;
+    constructor(db: NodePgDatabase<any>, registry: PostgresCollectionRegistry);
+    /** Whether to emit verbose debug logs (disabled in production). */
+    private static readonly DEBUG;
+    private debugLog;
+    setDataDriver(driver: DataDriver): void;
+    get subscriptions(): Map<string, {
+        clientId: string;
+        type: "collection" | "entity";
+        path: string;
+        entityId?: string | number;
+        collectionRequest?: {
+            filter?: Record<string, unknown>;
+            orderBy?: string;
+            order?: "desc" | "asc";
+            limit?: number;
+            offset?: number;
+            startAfter?: Record<string, unknown>;
+            databaseId?: string;
+            searchString?: string;
+        };
+        authContext?: SubscriptionAuthContext;
+    }>;
+    registerDataDriverSubscription(subscriptionId: string, subscription: {
+        clientId: string;
+        type: "collection" | "entity";
+        path: string;
+        entityId?: string | number;
+        collectionRequest?: {
+            filter?: Record<string, unknown>;
+            orderBy?: string;
+            order?: "desc" | "asc";
+            limit?: number;
+            offset?: number;
+            startAfter?: Record<string, unknown>;
+            databaseId?: string;
+            searchString?: string;
+        };
+        authContext?: SubscriptionAuthContext;
+    }): void;
+    addSubscriptionCallback(subscriptionId: string, callback: (data: Entity[] | Entity | null) => void): void;
+    removeSubscriptionCallback(subscriptionId: string): void;
+    /**
+     * Subscribe to collection changes (RealtimeProvider interface)
+     */
+    subscribeToCollection(subscriptionId: string, config: CollectionSubscriptionConfig, callback?: (entities: Entity[]) => void): void;
+    /**
+     * Subscribe to single entity changes (RealtimeProvider interface)
+     */
+    subscribeToEntity(subscriptionId: string, config: EntitySubscriptionConfig, callback?: (entity: Entity | null) => void): void;
+    /**
+     * Unsubscribe from a subscription (RealtimeProvider interface)
+     */
+    unsubscribe(subscriptionId: string): void;
+    addClient(clientId: string, ws: WebSocket): void;
+    handleClientMessage(clientId: string, message: WebSocketMessage, authContext?: SubscriptionAuthContext): Promise<void>;
+    removeClient(clientId: string): Promise<void>;
+    private handleMessage;
+    private handleCollectionSubscription;
+    private handleEntitySubscription;
+    private handleUnsubscribe;
+    /**
+     * Enhanced notification method that handles nested relation updates.
+     * @param broadcast When true (default), also sends a pg_notify so other instances
+     *                  pick up the change. Set to false when handling an incoming
+     *                  cross-instance notification to avoid infinite loops.
+     */
+    notifyEntityUpdate(path: string, entityId: string, entity: Entity | null, databaseId?: string, broadcast?: boolean): Promise<void>;
+    /**
+     * Notify subscriptions for a specific path
+     */
+    private notifyPathUpdate;
+    /**
+     * Debounce a collection refetch for a WebSocket subscription.
+     * Coalesces rapid entity mutations into a single database query.
+     */
+    private debouncedCollectionRefetch;
+    /**
+     * Debounce a collection refetch for a DataDriver callback subscription.
+     */
+    private debouncedDriverRefetch;
+    /**
+     * Fetch a collection with optional RLS auth context.
+     * When authContext is provided, the fetch runs inside a transaction
+     * with set_config calls so PostgreSQL RLS policies are enforced.
+     */
+    private fetchCollectionWithAuth;
+    /**
+     * Debounce an entity refetch for a WebSocket subscription.
+     */
+    private debouncedEntityRefetch;
+    /**
+     * Debounce an entity refetch for a Driver callback subscription.
+     */
+    private debouncedEntityDriverRefetch;
+    /**
+     * Fetch a single entity with optional RLS auth context.
+     */
+    private fetchEntityWithAuth;
+    private sendCollectionUpdate;
+    private sendEntityUpdate;
+    /**
+     * Send a lightweight entity-level patch to a collection subscriber.
+     * The client can merge this into its cached data for instant feedback.
+     */
+    private sendCollectionEntityPatch;
+    private sendError;
+    private sendMessage;
+    /**
+     * Extract parent paths from a nested path like "posts/70/tags"
+     * Returns ["posts", "posts/70"] for the example above
+     */
+    private getParentPaths;
+    /**
+     * Enable cross-instance realtime broadcasting via Postgres LISTEN/NOTIFY.
+     * Creates a dedicated pg.Client (outside the Drizzle pool) that stays
+     * connected and listens for change notifications from other instances.
+     *
+     * This is an **optional** feature — if never called, the backend operates
+     * in single-instance mode (the default, perfectly fine for most setups).
+     *
+     * @param connectionString Raw Postgres connection string for the LISTEN client.
+     */
+    startListening(connectionString: string): Promise<void>;
+    /**
+     * Stop listening and clean up the dedicated LISTEN connection.
+     */
+    stopListening(): Promise<void>;
+    /**
+     * Broadcast a change notification to other instances via pg_notify.
+     * Uses the main Drizzle connection (pooled) — NOT the LISTEN client.
+     */
+    private broadcastChange;
+    /**
+     * Create and connect the dedicated LISTEN client with auto-reconnect.
+     */
+    private connectListenClient;
+    /**
+     * Schedule a reconnection attempt with a fixed 3s delay.
+     */
+    private scheduleReconnect;
+}
+/**
+ * Alias for RealtimeService for consistent naming with other database implementations.
+ * This allows code to use PostgresRealtimeProvider alongside future MongoRealtimeProvider, etc.
+ */
+export declare const PostgresRealtimeProvider: typeof RealtimeService;

package/dist/server-postgresql/src/utils/drizzle-conditions.d.ts

@@ -0,0 +1,116 @@
+import { SQL } from "drizzle-orm";
+import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
+import { FilterValues, WhereFilterOp, Relation } from "@rebasepro/types";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+/** Drizzle dynamic query builder — accepts innerJoin + where chaining */
+export interface DrizzleDynamicQuery {
+    innerJoin(table: PgTable<any>, condition: SQL): this;
+    where(condition: SQL | undefined): this;
+    limit(limit: number): this;
+}
+/**
+ * Unified condition builder for Drizzle/PostgreSQL queries.
+ *
+ * This class uses static methods and satisfies the ConditionBuilderStatic<SQL> type.
+ * It translates Rebase filter conditions to Drizzle SQL conditions.
+ *
+ * @example
+ * const builder: ConditionBuilderStatic<SQL> = DrizzleConditionBuilder;
+ */
+export declare class DrizzleConditionBuilder {
+    /**
+     * Build filter conditions from FilterValues
+     */
+    static buildFilterConditions<M extends Record<string, unknown>>(filter: FilterValues<Extract<keyof M, string>>, table: PgTable<any>, collectionPath: string): SQL[];
+    /**
+     * Build a single filter condition for a specific operator and value
+     */
+    static buildSingleFilterCondition(column: AnyPgColumn, op: WhereFilterOp, value: unknown): SQL | null;
+    /**
+     * Build relation-based conditions for different relation types
+     */
+    static buildRelationConditions(relation: Relation, parentEntityId: string | number | (string | number)[], targetTable: PgTable<any>, parentTable: PgTable<any>, parentIdColumn: AnyPgColumn, targetIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry): {
+        joinConditions: {
+            table: PgTable<any>;
+            condition: SQL;
+        }[];
+        whereConditions: SQL[];
+    };
+    /**
+     * Build conditions for join path relations
+     */
+    private static buildJoinPathConditions;
+    /**
+     * Build a single join condition between tables
+     */
+    private static buildSingleJoinCondition;
+    /**
+     * Try to build a junction table join when direct foreign key relationship is not found
+     */
+    private static tryBuildJunctionJoin;
+    /**
+     * Build conditions for junction table (many-to-many) relations
+     */
+    private static buildJunctionTableConditions;
+    /**
+     * Build conditions for inverse junction table (many-to-many) relations
+     */
+    private static buildInverseJunctionTableConditions;
+    /**
+     * Build conditions for simple relations (owning/inverse without join paths)
+     */
+    private static buildSimpleRelationCondition;
+    /**
+     * Combine multiple conditions with AND operator
+     */
+    static combineConditionsWithAnd(conditions: SQL[]): SQL | undefined;
+    /**
+     * Combine multiple conditions with OR operator
+     */
+    static combineConditionsWithOr(conditions: SQL[]): SQL | undefined;
+    /**
+     * Build search conditions for text fields
+     */
+    static buildSearchConditions(searchString: string, properties: Record<string, unknown>, table: PgTable<any>): SQL[];
+    /**
+     * Build a unique field check condition
+     */
+    static buildUniqueFieldCondition(fieldColumn: AnyPgColumn, value: unknown, idColumn?: AnyPgColumn, excludeId?: string | number): SQL[];
+    /**
+     * Build relation-based query with joins and conditions
+     */
+    static buildRelationQuery<T extends DrizzleDynamicQuery>(baseQuery: T, relation: Relation, parentEntityId: string | number | (string | number)[], targetTable: PgTable<any>, parentTable: PgTable<any>, parentIdColumn: AnyPgColumn, targetIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry, additionalFilters?: SQL[]): T;
+    /**
+     * Build count query for relations with proper joins and conditions
+     */
+    static buildRelationCountQuery<T extends DrizzleDynamicQuery>(baseCountQuery: T, relation: Relation, parentEntityId: string | number, targetTable: PgTable<any>, parentTable: PgTable<any>, parentIdColumn: AnyPgColumn, targetIdColumn: AnyPgColumn, registry: PostgresCollectionRegistry, additionalFilters?: SQL[]): T;
+    /**
+     * Build join path conditions for count queries
+     */
+    private static buildJoinPathCountQuery;
+    /**
+     * Build junction table conditions for count queries
+     */
+    private static buildJunctionCountQuery;
+    /**
+     * Build inverse junction table conditions for count queries
+     */
+    private static buildInverseJunctionCountQuery;
+    /**
+     * Helper method to extract table names from columns
+     */
+    static getTableNamesFromColumns(columns: string | string[]): string[];
+    /**
+     * Helper method to extract column names from columns
+     */
+    static getColumnNamesFromColumns(columns: string | string[]): string[];
+    /**
+     * Find the corresponding junction table for an inverse many-to-many relation
+     */
+    private static findCorrespondingJunctionTable;
+}
+/**
+ * Alias for DrizzleConditionBuilder for consistent naming with other database implementations.
+ * This allows code to use PostgresConditionBuilder alongside future MongoConditionBuilder, etc.
+ */
+export declare const PostgresConditionBuilder: typeof DrizzleConditionBuilder;

package/dist/server-postgresql/src/websocket.d.ts

@@ -0,0 +1,5 @@
+import { RealtimeService } from "./services/realtimeService";
+import { PostgresBackendDriver } from "./PostgresBackendDriver";
+import { Server } from "http";
+import { AuthConfig } from "@rebasepro/server-core";
+export declare function createPostgresWebSocket(server: Server, realtimeService: RealtimeService, driver: PostgresBackendDriver, authConfig?: AuthConfig): void;

package/dist/types/src/controllers/analytics_controller.d.ts

@@ -0,0 +1,7 @@
+export type AnalyticsController = {
+    /**
+     * Callback used to get analytics events from the CMS
+     */
+    onAnalyticsEvent?: (event: AnalyticsEvent, data?: object) => void;
+};
+export type AnalyticsEvent = "entity_click" | "entity_click_from_reference" | "reference_selection_clear" | "reference_selection_toggle" | "reference_selected_single" | "reference_selection_new_entity" | "edit_entity_clicked" | "entity_edited" | "new_entity_click" | "new_entity_saved" | "copy_entity_click" | "entity_copied" | "single_delete_dialog_open" | "multiple_delete_dialog_open" | "single_entity_deleted" | "multiple_entities_deleted" | "drawer_navigate_to_home" | "drawer_navigate_to_collection" | "drawer_navigate_to_view" | "home_navigate_to_collection" | "home_favorite_navigate_to_collection" | "home_navigate_to_view" | "home_navigate_to_admin_view" | "home_favorite_navigate_to_view" | "home_move_card" | "home_move_group" | "home_drop_new_group" | "collection_inline_editing" | "view_mode_changed" | "kanban_card_moved" | "kanban_column_reorder" | "kanban_property_changed" | "kanban_new_entity_in_column" | "kanban_backfill_order" | "card_view_entity_click" | "unmapped_event";

package/dist/types/src/controllers/auth.d.ts

@@ -0,0 +1,119 @@
+import { StorageSource } from "./storage";
+import { Role, User } from "../users";
+import { RebaseData } from "./data";
+/**
+ * Capabilities advertised by an auth provider.
+ * UI components use this to show/hide features dynamically
+ * (e.g. password reset, registration, session management).
+ * @group Hooks and utilities
+ */
+export interface AuthCapabilities {
+    emailPasswordLogin?: boolean;
+    googleLogin?: boolean;
+    registration?: boolean;
+    passwordReset?: boolean;
+    sessionManagement?: boolean;
+    profileUpdate?: boolean;
+    emailVerification?: boolean;
+    /** List of enabled OAuth provider IDs (e.g. ["google", "github", "discord"]) */
+    enabledProviders?: string[];
+}
+/**
+ * Controller for retrieving the logged user or performing auth related operations.
+ * Note that if you are implementing your AuthController, you probably will want
+ * to do it as the result of a hook.
+ * @group Hooks and utilities
+ */
+export type AuthController<USER extends User = User, ExtraData = unknown> = {
+    /**
+     * The user currently logged in
+     * The values can be: the user object, null if they skipped login
+     */
+    user: USER | null;
+    /**
+     * Initial loading flag. It is used not to display the login screen
+     * when the app first loads, and it has not been checked whether the user
+     * is logged in or not.
+     */
+    initialLoading?: boolean;
+    /**
+     * Loading flag. It is used to display a loading screen when the user is
+     * logging in or out.
+     */
+    authLoading: boolean;
+    /**
+     * Sign out
+     */
+    signOut: () => Promise<void>;
+    /**
+     * Error initializing the authentication
+     */
+    authError?: unknown;
+    /**
+     * Error dispatched by the auth provider
+     */
+    authProviderError?: unknown;
+    /**
+     * You can use this method to retrieve the auth token for the current user.
+     */
+    getAuthToken: () => Promise<string>;
+    /**
+     * Has the user skipped the login process
+     */
+    loginSkipped: boolean;
+    extra: ExtraData;
+    setExtra: (extra: ExtraData) => void;
+    setUser?(user: USER | null): void;
+    setUserRoles?(roles: Role[]): void;
+    /**
+     * Capabilities advertised by the auth provider.
+     * UI components use this to feature-detect what the backend supports.
+     */
+    capabilities?: AuthCapabilities;
+};
+/**
+ * Extended auth controller with common optional auth methods.
+ * Backend implementations (Rebase backend, Firebase, Supabase, etc.)
+ * extend this with their own backend-specific extras.
+ * @group Hooks and utilities
+ */
+export interface AuthControllerExtended<USER extends User = User, ExtraData = unknown> extends AuthController<USER, ExtraData> {
+    /** Login with email and password */
+    emailPasswordLogin?(email: string, password: string): Promise<void>;
+    /** Login with a Google ID token or trigger Google popup */
+    googleLogin?(idToken: string): Promise<void>;
+    /** Register a new user */
+    register?(email: string, password: string, displayName?: string): Promise<void>;
+    /** Skip login (for anonymous access if enabled) */
+    skipLogin?(): void;
+    /** Request password reset email */
+    forgotPassword?(email: string): Promise<void>;
+    /** Reset password using a token */
+    resetPassword?(token: string, password: string): Promise<void>;
+    /** Change password for the authenticated user */
+    changePassword?(oldPassword: string, newPassword: string): Promise<void>;
+    /** Update user profile */
+    updateProfile?(displayName?: string, photoURL?: string): Promise<USER>;
+}
+/**
+ * Implement this function to allow access to specific users.
+ * @group Hooks and utilities
+ */
+export type Authenticator<USER extends User = User> = (props: {
+    /**
+     * Logged-in user or null
+     */
+    user: USER | null;
+    /**
+     * AuthController
+     */
+    authController: AuthController<USER>;
+    /**
+     * Unified data access API
+     */
+    data: RebaseData;
+    /**
+     * Used storage implementation
+     */
+    storageSource: StorageSource;
+}) => boolean | Promise<boolean>;