@rebasepro/server-postgresql 0.6.1 → 0.7.0

package/dist/services/entityService.d.ts

@@ -1,110 +0,0 @@
-import { Entity, FilterValues } from "@rebasepro/types";
-import type { VectorSearchParams } 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;
-        vectorSearch?: VectorSearchParams;
-    }): 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>;
-    /**
-     * Delete all entities from a collection
-     */
-    deleteAll(collectionPath: string, 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/services/index.d.ts

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

package/dist/services/realtimeService.d.ts

@@ -1,220 +0,0 @@
-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 channels;
-    private presence;
-    private presenceInterval?;
-    private static readonly PRESENCE_TIMEOUT_MS;
-    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;
-    /** Join a broadcast channel */
-    joinChannel(clientId: string, channel: string): void;
-    /** Leave a broadcast channel */
-    leaveChannel(clientId: string, channel: string): void;
-    /** Broadcast a message to all clients in a channel except sender */
-    broadcastToChannel(clientId: string, channel: string, event: string, payload: unknown): void;
-    /** Track presence in a channel */
-    trackPresence(clientId: string, channel: string, state: Record<string, unknown>): void;
-    /** Remove presence from a channel */
-    removePresence(clientId: string, channel: string): void;
-    /** Send full presence state to a specific client */
-    sendPresenceState(clientId: string, channel: string): void;
-    /** Broadcast presence diff (joins/leaves) to channel */
-    private broadcastPresenceDiff;
-    /** Periodic cleanup for stale presences */
-    private ensurePresenceCleanup;
-    /**
-     * Gracefully tear down all realtime resources.
-     *
-     * This MUST be called during process shutdown, **before** `pool.end()`.
-     * It ensures:
-     *  1. All debounced refetch timers are cancelled (prevents queries after pool closes).
-     *  2. All subscription state and callbacks are cleared.
-     *  3. The dedicated LISTEN client (outside the pool) is disconnected.
-     *  4. All WebSocket clients are removed (but not forcefully closed — the
-     *     HTTP server close will handle that).
-     */
-    destroy(): Promise<void>;
-    /**
-     * 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/types.d.ts

@@ -1,3 +0,0 @@
-import type { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
-/** Drizzle PgTable with column access by name. Runtime Drizzle tables satisfy this shape. */
-export type RebasePgTable = PgTable & Record<string, AnyPgColumn>;

package/dist/utils/drizzle-conditions.d.ts

@@ -1,138 +0,0 @@
-import { SQL } from "drizzle-orm";
-import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
-import { FilterValues, WhereFilterOp, Relation, LogicalCondition, FilterCondition } 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 logical conditions recursively from LogicalCondition or FilterCondition
-     */
-    static buildLogicalConditions(cond: LogicalCondition | FilterCondition, table: PgTable<any>, collectionPath: string): SQL | null;
-    /**
-     * 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;
-    /**
-     * Build vector similarity search expressions for pgvector.
-     *
-     * Returns:
-     * - `orderBy`: SQL expression to ORDER BY distance (ascending = closest first)
-     * - `filter`: optional WHERE clause for distance threshold
-     * - `distanceSelect`: SQL expression for selecting the distance as `_distance`
-     */
-    static buildVectorSearchConditions(table: PgTable<any>, vectorSearch: {
-        property: string;
-        vector: number[];
-        distance?: "cosine" | "l2" | "inner_product";
-        threshold?: number;
-    }): {
-        orderBy: SQL;
-        filter?: SQL;
-        distanceSelect: SQL;
-    };
-}
-/**
- * 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/utils/pg-array-null-patch.d.ts

@@ -1,16 +0,0 @@
-/**
- * Patches all PgArray columns on the given tables to handle NULL values safely.
- *
- * Drizzle ORM's `PgArray.mapFromDriverValue` calls `value.map(...)` without
- * guarding against `null`. When a PostgreSQL native array column (`text[]`,
- * `integer[]`, etc.) contains NULL, the pg driver returns `null` in JavaScript,
- * and `null.map(...)` throws `TypeError: value.map is not a function`.
- *
- * This function walks every column of every registered table and, for any
- * `PgArray` column, wraps its `mapFromDriverValue` to return `null` when the
- * database value is nullish.
- *
- * This is a workaround for a known Drizzle ORM issue. Should be removed once
- * Drizzle handles nullable arrays natively.
- */
-export declare function patchPgArrayNullSafety(tables: Record<string, unknown>): void;

package/dist/utils/pg-error-utils.d.ts

@@ -1,55 +0,0 @@
-/**
- * Shared PostgreSQL error extraction and user-friendly message formatting.
- *
- * Drizzle wraps native PG errors in a `.cause` chain. These utilities
- * unwrap that chain to get the real PostgreSQL error (identified by a
- * 5-character alphanumeric `code` such as `42P01`) and translate it into
- * a message that is safe and helpful to show to end-users.
- */
-/** Shape of PostgreSQL errors with diagnostic metadata. */
-export interface PostgresError extends Error {
-    code?: string;
-    detail?: string;
-    hint?: string;
-    constraint?: string;
-    column?: string;
-    table?: string;
-    dataType?: string;
-    cause?: unknown;
-}
-/**
- * Extract the underlying PostgreSQL error from a Drizzle wrapper.
- * Drizzle wraps PG errors in a `cause` property — this function
- * recursively walks the chain until it finds an object with a PG
- * error code (5-char alphanumeric, e.g. `42P01`).
- */
-export declare function extractPgError(error: unknown): PostgresError | null;
-/**
- * Walk the error cause chain and return the deepest meaningful message.
- */
-export declare function extractCauseMessage(error: unknown): string | null;
-/**
- * Translate a raw PostgreSQL error into a user-friendly message.
- *
- * @param pgError  - The extracted PostgreSQL error (from {@link extractPgError})
- * @param context  - A human-readable context string (e.g. collection slug or path)
- * @returns An object with a `message` safe for the client and the PG `code`.
- */
-export declare function pgErrorToFriendlyMessage(pgError: PostgresError, context: string): {
-    message: string;
-    code: string;
-};
-/**
- * Sanitize any error into a message safe and helpful for the client.
- *
- * Extracts the PG error from the Drizzle cause chain when possible;
- * falls back to a generic message that doesn't leak SQL.
- *
- * @param error   - The raw caught error
- * @param context - A human-readable context string (e.g. collection path)
- * @returns An object with `message` (user-friendly) and optional `code` (PG code).
- */
-export declare function sanitizeErrorForClient(error: unknown, context: string): {
-    message: string;
-    code?: string;
-};

package/dist/websocket.d.ts

@@ -1,11 +0,0 @@
-import { RealtimeService } from "./services/realtimeService";
-import { PostgresBackendDriver } from "./PostgresBackendDriver";
-import type { AuthAdapter } from "@rebasepro/types";
-import { Server } from "http";
-/** Minimal subset of RebaseAuthConfig used by the WebSocket layer. */
-interface WsAuthConfig {
-    requireAuth?: boolean;
-    jwtSecret?: string;
-}
-export declare function createPostgresWebSocket(server: Server, realtimeService: RealtimeService, driver: PostgresBackendDriver, authConfig?: WsAuthConfig, authAdapter?: AuthAdapter): void;
-export {};