@rebasepro/server-postgresql 0.2.3 → 0.2.5

package/src/services/EntityFetchService.ts

@@ -1,6 +1,7 @@
 import { and, asc, count, desc, eq, getTableName, gt, lt, or, SQL, TableRelationalConfig, TablesRelationalConfig } from "drizzle-orm";
 import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
 import { Entity, EntityCollection, FilterValues, Relation } from "@rebasepro/types";
+import type { VectorSearchParams } from "@rebasepro/types";
 import { resolveCollectionRelations, findRelation, createRelationRef, createRelationRefWithData } from "@rebasepro/common";
 import { DrizzleConditionBuilder } from "../utils/drizzle-conditions";
 import {
@@ -698,6 +699,7 @@ export class EntityFetchService {
             startAfter?: Record<string, unknown>;
             searchString?: string;
             databaseId?: string;
+            vectorSearch?: VectorSearchParams;
         } = {}
     ): Promise<Entity<M>[]> {
         const collection = getCollectionByPath(collectionPath, this.registry);
@@ -722,7 +724,9 @@ export class EntityFetchService {
         const withConfig = this.buildWithConfig(collection);
         const hasRelations = withConfig && Object.keys(withConfig).length > 0;
 
-        if (qb && !options.searchString && !hasRelations) {
+        // Skip db.query path when vectorSearch is present — it doesn't support
+        // custom SELECT expressions needed for the _distance column.
+        if (qb && !options.searchString && !hasRelations && !options.vectorSearch) {
             try {
                 const queryOpts = this.buildDrizzleQueryOptions<M>(
                     table, idField, idInfo, options, collectionPath, undefined
@@ -746,7 +750,15 @@ export class EntityFetchService {
         }
 
         // Fallback: db.select + processEntityResults (N+1 for relations)
-        let query = this.db.select().from(table).$dynamic();
+        // When vectorSearch is present, add _distance to the SELECT.
+        let vectorMeta: { orderBy: SQL; filter?: SQL; distanceSelect: SQL } | undefined;
+        if (options.vectorSearch) {
+            vectorMeta = DrizzleConditionBuilder.buildVectorSearchConditions(table, options.vectorSearch);
+        }
+
+        let query = vectorMeta
+            ? this.db.select({ table_row: table, _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
+            : this.db.select().from(table).$dynamic();
         const allConditions: SQL[] = [];
 
         if (options.searchString) {
@@ -762,13 +774,21 @@ export class EntityFetchService {
             if (filterConditions.length > 0) allConditions.push(...filterConditions);
         }
 
+        // Vector distance threshold filter
+        if (vectorMeta?.filter) {
+            allConditions.push(vectorMeta.filter);
+        }
+
         if (allConditions.length > 0) {
             const finalCondition = DrizzleConditionBuilder.combineConditionsWithAnd(allConditions);
             if (finalCondition) query = query.where(finalCondition);
         }
 
         const orderExpressions = [];
-        if (options.orderBy) {
+        // Vector search overrides ORDER BY with distance (ascending = closest first)
+        if (vectorMeta) {
+            orderExpressions.push(asc(vectorMeta.orderBy));
+        } else if (options.orderBy) {
             const orderByField = this.resolveOrderByField(table, options.orderBy, collection);
             if (orderByField) {
                 orderExpressions.push(options.order === "asc" ? asc(orderByField) : desc(orderByField));
@@ -786,13 +806,24 @@ export class EntityFetchService {
             }
         }
 
-        const limitValue = options.searchString ? (options.limit || 50) : options.limit;
+        const limitValue = options.vectorSearch
+            ? (options.limit || 10)
+            : options.searchString ? (options.limit || 50) : options.limit;
         if (limitValue) query = query.limit(limitValue);
 
         // Offset (numeric pagination)
         if (options.offset && options.offset > 0) query = query.offset(options.offset);
 
-        const results = await query;
+        const rawResults = await query;
+
+        // When vector search is active, unwrap the nested select shape and
+        // attach _distance to each entity's values.
+        const results = vectorMeta
+            ? (rawResults as { table_row: Record<string, unknown>; _distance: unknown }[]).map(r => ({
+                ...r.table_row,
+                _distance: typeof r._distance === "number" ? r._distance : parseFloat(String(r._distance))
+            }))
+            : rawResults as Record<string, unknown>[];
 
         return this.processEntityResults<M>(results, collection, collectionPath, idInfo, options.databaseId, false, idInfoArray);
     }
@@ -919,6 +950,7 @@ export class EntityFetchService {
             startAfter?: Record<string, unknown>;
             searchString?: string;
             databaseId?: string;
+            vectorSearch?: VectorSearchParams;
         } = {}
     ): Promise<Entity<M>[]> {
         // Handle multi-segment paths by resolving through relations
@@ -1164,6 +1196,7 @@ export class EntityFetchService {
             startAfter?: Record<string, unknown>;
             searchString?: string;
             databaseId?: string;
+            vectorSearch?: VectorSearchParams;
         } = {},
         include?: string[]
     ): Promise<Record<string, unknown>[]> {
@@ -1181,7 +1214,8 @@ export class EntityFetchService {
         const tableName = getTableName(table);
 
         const qb = this.getQueryBuilder(tableName);
-        if (qb && !options.searchString) {
+        // Skip db.query path when vectorSearch is present — needs custom SELECT
+        if (qb && !options.searchString && !options.vectorSearch) {
             try {
                 const withConfig = (include && include.length > 0)
                     ? this.buildWithConfig(collection, include)
@@ -1389,6 +1423,7 @@ export class EntityFetchService {
             offset?: number;
             startAfter?: Record<string, unknown>;
             searchString?: string;
+            vectorSearch?: VectorSearchParams;
         } = {}
     ): Promise<Record<string, unknown>[]> {
         const collection = getCollectionByPath(collectionPath, this.registry);
@@ -1397,7 +1432,14 @@ export class EntityFetchService {
         const idInfo = idInfoArray[0];
         const idField = table[idInfo.fieldName as keyof typeof table] as AnyPgColumn;
 
-        let query = this.db.select().from(table).$dynamic();
+        let vectorMeta: { orderBy: SQL; filter?: SQL; distanceSelect: SQL } | undefined;
+        if (options.vectorSearch) {
+            vectorMeta = DrizzleConditionBuilder.buildVectorSearchConditions(table, options.vectorSearch);
+        }
+
+        let query = vectorMeta
+            ? this.db.select({ table_row: table, _distance: vectorMeta.distanceSelect }).from(table).$dynamic()
+            : this.db.select().from(table).$dynamic();
         const allConditions: SQL[] = [];
 
         if (options.searchString) {
@@ -1413,13 +1455,19 @@ export class EntityFetchService {
             if (filterConditions.length > 0) allConditions.push(...filterConditions);
         }
 
+        if (vectorMeta?.filter) {
+            allConditions.push(vectorMeta.filter);
+        }
+
         if (allConditions.length > 0) {
             const finalCondition = DrizzleConditionBuilder.combineConditionsWithAnd(allConditions);
             if (finalCondition) query = query.where(finalCondition);
         }
 
         const orderExpressions = [];
-        if (options.orderBy) {
+        if (vectorMeta) {
+            orderExpressions.push(asc(vectorMeta.orderBy));
+        } else if (options.orderBy) {
             const orderByField = this.resolveOrderByField(table, options.orderBy, collection);
             if (orderByField) {
                 orderExpressions.push(options.order === "asc" ? asc(orderByField) : desc(orderByField));
@@ -1428,13 +1476,24 @@ export class EntityFetchService {
         orderExpressions.push(desc(idField));
         if (orderExpressions.length > 0) query = query.orderBy(...orderExpressions);
 
-        const limitValue = options.searchString ? (options.limit || 50) : options.limit;
+        const limitValue = options.vectorSearch
+            ? (options.limit || 10)
+            : options.searchString ? (options.limit || 50) : options.limit;
         if (limitValue) query = query.limit(limitValue);
 
         // Offset (numeric pagination)
         if (options.offset && options.offset > 0) query = query.offset(options.offset);
 
-        return await query as Record<string, unknown>[];
+        const rawResults = await query;
+
+        if (vectorMeta) {
+            return (rawResults as { table_row: Record<string, unknown>; _distance: unknown }[]).map(r => ({
+                ...r.table_row,
+                _distance: typeof r._distance === "number" ? r._distance : parseFloat(String(r._distance))
+            }));
+        }
+
+        return rawResults as Record<string, unknown>[];
     }
 
     /**

package/src/services/EntityPersistService.ts

@@ -53,6 +53,15 @@ export class EntityPersistService {
             .where(eq(idField, parsedId));
     }
 
+    /**
+     * Delete all entities from a collection
+     */
+    async deleteAll(collectionPath: string, _databaseId?: string): Promise<void> {
+        const collection = getCollectionByPath(collectionPath, this.registry);
+        const table = getTableForCollection(collection, this.registry);
+        await this.db.delete(table);
+    }
+
     /**
      * Save an entity (create or update)
      */

package/src/services/entityService.ts

@@ -1,5 +1,6 @@
 // import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { Entity, FilterValues } from "@rebasepro/types";
+import type { VectorSearchParams } from "@rebasepro/types";
 import { EntityFetchService } from "./EntityFetchService";
 import { EntityPersistService } from "./EntityPersistService";
 import { RelationService } from "./RelationService";
@@ -66,6 +67,7 @@ export class EntityService implements EntityRepository {
             startAfter?: Record<string, unknown>;
             searchString?: string;
             databaseId?: string;
+            vectorSearch?: VectorSearchParams;
         } = {}
     ): Promise<Entity<M>[]> {
         return this.fetchService.fetchCollection<M>(collectionPath, options);
@@ -167,6 +169,13 @@ export class EntityService implements EntityRepository {
         return this.persistService.deleteEntity(collectionPath, entityId, databaseId);
     }
 
+    /**
+     * Delete all entities from a collection
+     */
+    async deleteAll(collectionPath: string, databaseId?: string): Promise<void> {
+        return this.persistService.deleteAll(collectionPath, databaseId);
+    }
+
 
     /**
      * Execute raw SQL

package/src/services/realtimeService.ts

@@ -41,6 +41,14 @@ type RealTimeListenEntityProps = ListenEntityProps & { subscriptionId: string };
  */
 export class RealtimeService extends EventEmitter implements RealtimeProvider {
     private clients = new Map<string, WebSocket>();
+
+    // Broadcast channels: channel name → set of client IDs
+    private channels = new Map<string, Set<string>>();
+
+    // Presence: channel → Map<clientId, { state, lastSeen }>
+    private presence = new Map<string, Map<string, { state: Record<string, unknown>; lastSeen: number }>>();
+    private presenceInterval?: ReturnType<typeof setInterval>;
+    private static readonly PRESENCE_TIMEOUT_MS = 30000; // 30s
     private entityService: EntityService;
     // Enhanced subscriptions storage with full request parameters
     private _subscriptions = new Map<string, {
@@ -237,9 +245,24 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                 }
             }
         }
+
+        // Remove from all broadcast channels
+        for (const [channel, members] of this.channels.entries()) {
+            if (members.has(clientId)) {
+                members.delete(clientId);
+                this.removePresence(clientId, channel);
+                if (members.size === 0) this.channels.delete(channel);
+            }
+        }
+
+        // Remove from all presence channels
+        for (const [channel] of this.presence) {
+            this.removePresence(clientId, channel);
+        }
     }
 
     private async handleMessage(clientId: string, message: WebSocketMessage, authContext?: SubscriptionAuthContext) {
+        const payload = message.payload as Record<string, unknown> | undefined;
         switch (message.type) {
             case "subscribe_collection":
                 await this.handleCollectionSubscription(clientId, message.payload as RealTimeListenCollectionProps, authContext);
@@ -250,6 +273,40 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             case "unsubscribe":
                 await this.handleUnsubscribe(clientId, message.subscriptionId!);
                 break;
+
+            // ── Broadcast Channels ──
+            case "join_channel":
+                this.joinChannel(clientId, payload?.channel as string);
+                break;
+            case "leave_channel":
+                this.leaveChannel(clientId, payload?.channel as string);
+                break;
+            case "broadcast":
+                this.broadcastToChannel(
+                    clientId,
+                    payload?.channel as string,
+                    payload?.event as string,
+                    payload?.payload
+                );
+                break;
+
+            // ── Presence ──
+            case "presence_track":
+                // Auto-join the channel so presence works without a separate join
+                this.joinChannel(clientId, payload?.channel as string);
+                this.trackPresence(
+                    clientId,
+                    payload?.channel as string,
+                    payload?.state as Record<string, unknown> ?? {}
+                );
+                break;
+            case "presence_untrack":
+                this.removePresence(clientId, payload?.channel as string);
+                break;
+            case "presence_state":
+                this.sendPresenceState(clientId, payload?.channel as string);
+                break;
+
             default:
                 this.sendError(clientId, "Unknown message type " + message.type, message.subscriptionId);
         }
@@ -839,6 +896,153 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
 
         return parentPaths;
     }
+
+    // =============================================================================
+    // Broadcast Channels
+    // =============================================================================
+
+    /** Join a broadcast channel */
+    joinChannel(clientId: string, channel: string): void {
+        if (!this.channels.has(channel)) {
+            this.channels.set(channel, new Set());
+        }
+        this.channels.get(channel)!.add(clientId);
+        this.debugLog(`📡 [Broadcast] Client ${clientId} joined channel: ${channel}`);
+    }
+
+    /** Leave a broadcast channel */
+    leaveChannel(clientId: string, channel: string): void {
+        const members = this.channels.get(channel);
+        if (members) {
+            members.delete(clientId);
+            if (members.size === 0) this.channels.delete(channel);
+        }
+        // Also remove presence
+        this.removePresence(clientId, channel);
+    }
+
+    /** Broadcast a message to all clients in a channel except sender */
+    broadcastToChannel(clientId: string, channel: string, event: string, payload: unknown): void {
+        const members = this.channels.get(channel);
+        if (!members) return;
+
+        const message = JSON.stringify({
+            type: "broadcast",
+            channel,
+            event,
+            payload
+        });
+
+        for (const memberId of members) {
+            if (memberId === clientId) continue; // Don't echo back to sender
+            const ws = this.clients.get(memberId);
+            if (ws && ws.readyState === WebSocket.OPEN) {
+                ws.send(message);
+            }
+        }
+    }
+
+    // =============================================================================
+    // Presence
+    // =============================================================================
+
+    /** Track presence in a channel */
+    trackPresence(clientId: string, channel: string, state: Record<string, unknown>): void {
+        if (!this.presence.has(channel)) {
+            this.presence.set(channel, new Map());
+        }
+
+        const channelPresence = this.presence.get(channel)!;
+        channelPresence.set(clientId, { state, lastSeen: Date.now() });
+
+        // Broadcast join / state update to channel
+        this.broadcastPresenceDiff(channel, { [clientId]: state }, {});
+
+        // Start cleanup interval if not running
+        this.ensurePresenceCleanup();
+    }
+
+    /** Remove presence from a channel */
+    removePresence(clientId: string, channel: string): void {
+        const channelPresence = this.presence.get(channel);
+        if (!channelPresence) return;
+
+        const entry = channelPresence.get(clientId);
+        if (entry) {
+            channelPresence.delete(clientId);
+            this.broadcastPresenceDiff(channel, {}, { [clientId]: entry.state });
+        }
+
+        if (channelPresence.size === 0) {
+            this.presence.delete(channel);
+        }
+    }
+
+    /** Send full presence state to a specific client */
+    sendPresenceState(clientId: string, channel: string): void {
+        const channelPresence = this.presence.get(channel);
+        const presences: Record<string, Record<string, unknown>> = {};
+
+        if (channelPresence) {
+            for (const [id, { state }] of channelPresence) {
+                presences[id] = state;
+            }
+        }
+
+        const ws = this.clients.get(clientId);
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({
+                type: "presence_state",
+                channel,
+                presences
+            }));
+        }
+    }
+
+    /** Broadcast presence diff (joins/leaves) to channel */
+    private broadcastPresenceDiff(
+        channel: string,
+        joins: Record<string, Record<string, unknown>>,
+        leaves: Record<string, Record<string, unknown>>
+    ): void {
+        const members = this.channels.get(channel);
+        if (!members) return;
+
+        const message = JSON.stringify({
+            type: "presence_diff",
+            channel,
+            joins,
+            leaves
+        });
+
+        for (const memberId of members) {
+            const ws = this.clients.get(memberId);
+            if (ws && ws.readyState === WebSocket.OPEN) {
+                ws.send(message);
+            }
+        }
+    }
+
+    /** Periodic cleanup for stale presences */
+    private ensurePresenceCleanup(): void {
+        if (this.presenceInterval) return;
+        this.presenceInterval = setInterval(() => {
+            const now = Date.now();
+            for (const [channel, channelPresence] of this.presence) {
+                for (const [clientId, entry] of channelPresence) {
+                    if (now - entry.lastSeen > RealtimeService.PRESENCE_TIMEOUT_MS) {
+                        this.removePresence(clientId, channel);
+                    }
+                }
+            }
+            // Stop interval if no presences tracked
+            if (this.presence.size === 0 && this.presenceInterval) {
+                clearInterval(this.presenceInterval);
+                this.presenceInterval = undefined;
+            }
+        }, 10000); // Check every 10s
+    }
+
     // =============================================================================
     // Lifecycle / Cleanup
     // =============================================================================
@@ -865,10 +1069,18 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
         this._subscriptions.clear();
         this.subscriptionCallbacks.clear();
 
-        // 3. Disconnect the dedicated LISTEN client
+        // 3. Clear broadcast channels and presence
+        this.channels.clear();
+        this.presence.clear();
+        if (this.presenceInterval) {
+            clearInterval(this.presenceInterval);
+            this.presenceInterval = undefined;
+        }
+
+        // 4. Disconnect the dedicated LISTEN client
         await this.stopListening();
 
-        // 4. Drop client references (don't close — server.close drains them)
+        // 5. Drop client references (don't close — server.close drains them)
         this.clients.clear();
 
         this.debugLog("🧹 [RealtimeService] destroy() complete — all resources released.");

package/src/utils/drizzle-conditions.ts

@@ -38,7 +38,15 @@ export class DrizzleConditionBuilder {
             if (!filterParam) continue;
 
             const [op, value] = filterParam as [WhereFilterOp, any];
-            const fieldColumn = table[field as keyof typeof table] as AnyPgColumn;
+            let fieldColumn = table[field as keyof typeof table] as AnyPgColumn;
+
+            if (!fieldColumn) {
+                // Fallback for relations (e.g. project -> project_id)
+                const relationKey = `${field}_id`;
+                if (relationKey in table) {
+                    fieldColumn = table[relationKey as keyof typeof table] as AnyPgColumn;
+                }
+            }
 
             if (!fieldColumn) {
                 console.warn(`Filtering by field '${field}', but it does not exist in table for collection '${collectionPath}'`);
@@ -87,8 +95,22 @@ export class DrizzleConditionBuilder {
                 }
                 return null;
             case "array-contains":
-                // For JSONB arrays
+                // For JSONB arrays: checks if the column contains the given value
+                return sql`${column} @> ${JSON.stringify([value])}`;
+            case "array-contains-any":
+                // For JSONB arrays: checks if the column contains any of the given values
+                if (Array.isArray(value) && value.length > 0) {
+                    // Use the ?| operator for JSONB overlap with text array
+                    const textValues = value.map(v => String(v));
+                    return sql`${column} ?| array[${sql.join(textValues.map(v => sql`${v}`), sql`, `)}]`;
+                }
+                // Single value fallback: treat as array-contains
                 return sql`${column} @> ${JSON.stringify([value])}`;
+            case "not-in":
+                if (Array.isArray(value) && value.length > 0) {
+                    return sql`${column} NOT IN (${sql.join(value.map(v => sql`${v}`), sql`, `)})`;
+                }
+                return null;
             default:
                 console.warn(`Unsupported filter operation: ${op}`);
                 return null;
@@ -1005,6 +1027,55 @@ export class DrizzleConditionBuilder {
             return null;
         }
     }
+
+    /**
+     * 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 } {
+        const column = table[vectorSearch.property as keyof typeof table] as AnyPgColumn;
+        if (!column) {
+            throw new Error(`Vector column '${vectorSearch.property}' not found in table`);
+        }
+
+        const vectorLiteral = `'[${vectorSearch.vector.join(",")}]'::vector`;
+        const distanceFn = vectorSearch.distance || "cosine";
+
+        let operator: string;
+        switch (distanceFn) {
+            case "cosine":
+                operator = "<=>";
+                break;
+            case "l2":
+                operator = "<->";
+                break;
+            case "inner_product":
+                operator = "<#>";
+                break;
+        }
+
+        const distanceExpr = sql`${column} ${sql.raw(operator)} ${sql.raw(vectorLiteral)}`;
+
+        return {
+            orderBy: distanceExpr,
+            filter: vectorSearch.threshold != null
+                ? sql`(${column} ${sql.raw(operator)} ${sql.raw(vectorLiteral)}) < ${vectorSearch.threshold}`
+                : undefined,
+            distanceSelect: sql`(${column} ${sql.raw(operator)} ${sql.raw(vectorLiteral)})`,
+        };
+    }
 }
 
 /**
@@ -1012,3 +1083,4 @@ export class DrizzleConditionBuilder {
  * This allows code to use PostgresConditionBuilder alongside future MongoConditionBuilder, etc.
  */
 export const PostgresConditionBuilder = DrizzleConditionBuilder;
+

package/src/websocket.ts

@@ -550,8 +550,16 @@ colors: true }));
                     // Route subscription messages to RealtimeService
                     case "subscribe_collection":
                     case "subscribe_entity":
-                    case "unsubscribe": {
-                        wsDebug("🔄 [WebSocket Server] Routing subscription message to RealtimeService:", type);
+                    case "unsubscribe":
+                    // Broadcast channels
+                    case "join_channel":
+                    case "leave_channel":
+                    case "broadcast":
+                    // Presence
+                    case "presence_track":
+                    case "presence_untrack":
+                    case "presence_state": {
+                        wsDebug("🔄 [WebSocket Server] Routing realtime message to RealtimeService:", type);
                         // Attach auth context from the WS session so RLS-aware refetches work
                         const session = clientSessions.get(clientId);
                         const authContext = session?.user