@rebasepro/server-postgresql 0.5.0 → 0.6.1

package/src/utils/drizzle-conditions.ts

@@ -4,6 +4,8 @@ import { FilterValues, WhereFilterOp, Relation, JoinStep, LogicalCondition, Filt
 import { getColumnName, resolveCollectionRelations } from "@rebasepro/common";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 import { ConditionBuilderStatic } from "../interfaces";
+import { logger } from "@rebasepro/server-core";
+import { getColumnMeta } from "../services/entity-helpers";
 
 /** Drizzle dynamic query builder — accepts innerJoin + where chaining */
 
@@ -48,7 +50,7 @@ export class DrizzleConditionBuilder {
             }
 
             if (!fieldColumn) {
-                console.warn(`Filtering by field '${field}', but it does not exist in table for collection '${collectionPath}'`);
+                logger.warn(`Filtering by field '${field}', but it does not exist in table for collection '${collectionPath}'`);
                 continue;
             }
 
@@ -90,7 +92,7 @@ export class DrizzleConditionBuilder {
                 }
             }
             if (!fieldColumn) {
-                console.warn(`Filtering by field '${cond.column}', but it does not exist in table for collection '${collectionPath}'`);
+                logger.warn(`Filtering by field '${cond.column}', but it does not exist in table for collection '${collectionPath}'`);
                 return null;
             }
             return this.buildSingleFilterCondition(fieldColumn, cond.operator as WhereFilterOp, cond.value);
@@ -129,25 +131,39 @@ export class DrizzleConditionBuilder {
                     return inArray(column, value);
                 }
                 return null;
-            case "array-contains":
+            case "array-contains": {
+                const meta = getColumnMeta(column);
+                if (meta.dataType === "array" || meta.columnType === "PgArray") {
+                    return sql`${column} @> ARRAY[${value}]`;
+                }
                 // 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
+            }
+            case "array-contains-any": {
+                const meta = getColumnMeta(column);
+                const isNativeArray = meta.dataType === "array" || meta.columnType === "PgArray";
                 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`, `)}]`;
+                    if (isNativeArray) {
+                        return sql`${column} && ARRAY[${sql.join(value.map(v => sql`${v}`), sql`, `)}]`;
+                    } else {
+                        // 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
+                if (isNativeArray) {
+                    return sql`${column} @> ARRAY[${value}]`;
+                }
                 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}`);
+                logger.warn(`Unsupported filter operation: ${op}`);
                 return null;
         }
     }
@@ -247,7 +263,7 @@ export class DrizzleConditionBuilder {
                 );
                 whereConditions.push(simpleCondition);
             } else {
-                console.error("🔍 [buildRelationConditions] Failed to find junction table info and no foreign key specified");
+                logger.error("🔍 [buildRelationConditions] Failed to find junction table info and no foreign key specified");
                 throw new Error(`Cannot resolve inverse many relation '${relation.relationName}'. Either specify 'through' property, ensure corresponding owning relation exists with junction table configuration, or specify 'foreignKeyOnTarget' for one-to-many relationships.`);
             }
         } else {
@@ -711,9 +727,9 @@ export class DrizzleConditionBuilder {
                 const fieldColumn = table[key as keyof typeof table] as AnyPgColumn;
                 if (fieldColumn) {
                     // Verify that the underlying database column supports string pattern-matching
-                    const supportsILike = 
-                        fieldColumn instanceof PgVarchar || 
-                        fieldColumn instanceof PgText || 
+                    const supportsILike =
+                        fieldColumn instanceof PgVarchar ||
+                        fieldColumn instanceof PgText ||
                         fieldColumn instanceof PgChar ||
                         (fieldColumn && typeof fieldColumn === "object" && !("columnType" in fieldColumn));
                     if (supportsILike) {
@@ -1058,7 +1074,7 @@ export class DrizzleConditionBuilder {
             console.debug("🔍 [findCorrespondingJunctionTable] Returning junction info:", result);
             return result;
         } catch (error) {
-            console.error(`🔍 [findCorrespondingJunctionTable] Error finding corresponding junction table for relation '${relation.relationName}':`, error);
+            logger.error(`🔍 [findCorrespondingJunctionTable] Error finding corresponding junction table for relation '${relation.relationName}'`, { error: error });
             return null;
         }
     }
@@ -1108,7 +1124,7 @@ export class DrizzleConditionBuilder {
             filter: vectorSearch.threshold != null
                 ? sql`(${column} ${sql.raw(operator)} ${sql.raw(vectorLiteral)}) < ${vectorSearch.threshold}`
                 : undefined,
-            distanceSelect: sql`(${column} ${sql.raw(operator)} ${sql.raw(vectorLiteral)})`,
+            distanceSelect: sql`(${column} ${sql.raw(operator)} ${sql.raw(vectorLiteral)})`
         };
     }
 }

package/src/utils/pg-array-null-patch.ts

@@ -0,0 +1,42 @@
+import { getTableColumns } from "drizzle-orm";
+import { PgArray, PgTable } from "drizzle-orm/pg-core";
+import { logger } from "@rebasepro/server-core";
+
+/**
+ * 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 function patchPgArrayNullSafety(tables: Record<string, unknown>): void {
+    let patchedCount = 0;
+
+    for (const tableOrRelation of Object.values(tables)) {
+        if (!(tableOrRelation instanceof PgTable)) continue;
+
+        const columns = getTableColumns(tableOrRelation);
+        for (const column of Object.values(columns)) {
+            if (column instanceof PgArray) {
+                const original = column.mapFromDriverValue.bind(column);
+                column.mapFromDriverValue = function (value: unknown) {
+                    if (value == null) return null;
+                    return original(value as string | unknown[]);
+                };
+                patchedCount++;
+            }
+        }
+    }
+
+    if (patchedCount > 0) {
+        logger.debug(`[PgArray] Patched ${patchedCount} array column(s) for null-safety`);
+    }
+}

package/src/utils/pg-error-utils.ts

@@ -0,0 +1,211 @@
+/**
+ * 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.
+ */
+
+import { logger } from "@rebasepro/server-core";
+
+/** 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 function extractPgError(error: unknown): PostgresError | null {
+    if (!error || typeof error !== "object") return null;
+    if (!(error instanceof Error)) {
+        // Check non-Error objects for a cause chain (Drizzle sometimes wraps oddly)
+        if ("cause" in error && (error as Record<string, unknown>).cause && typeof (error as Record<string, unknown>).cause === "object") {
+            return extractPgError((error as Record<string, unknown>).cause);
+        }
+        return null;
+    }
+
+    // Check if the error itself has a PG error code
+    if ("code" in error && typeof (error as PostgresError).code === "string" && /^[0-9A-Z]{5}$/.test((error as PostgresError).code!)) {
+        return error as PostgresError;
+    }
+
+    // Check the cause chain (Drizzle wraps PG errors)
+    if (error.cause && typeof error.cause === "object") {
+        return extractPgError(error.cause);
+    }
+
+    return null;
+}
+
+/**
+ * Walk the error cause chain and return the deepest meaningful message.
+ */
+export function extractCauseMessage(error: unknown): string | null {
+    if (!error || typeof error !== "object") return null;
+    if (!(error instanceof Error)) return null;
+
+    if (error.cause && typeof error.cause === "object") {
+        const deeper = extractCauseMessage(error.cause);
+        if (deeper) return deeper;
+        // The cause itself has a message
+        if (error.cause instanceof Error && error.cause.message) {
+            return error.cause.message;
+        }
+    }
+    return 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 function pgErrorToFriendlyMessage(pgError: PostgresError, context: string): { message: string; code: string } {
+    const detail = pgError.detail as string | undefined;
+    const hint = pgError.hint as string | undefined;
+    const constraint = pgError.constraint as string | undefined;
+    const column = pgError.column as string | undefined;
+    const table = pgError.table as string | undefined;
+    const dataType = pgError.dataType as string | undefined;
+    const pgMessage = pgError.message || "Unknown database error";
+    const code = pgError.code || "UNKNOWN";
+
+    const suffix = hint ? ` Hint: ${hint}` : "";
+    const tableRef = table ?? context;
+
+    switch (pgError.code) {
+        case "23503": // foreign_key_violation
+            return {
+                message: detail
+                    ? `Foreign key constraint violated: ${detail}${suffix}`
+                    : `Cannot complete operation: a foreign key constraint${constraint ? ` (${constraint})` : ""} was violated in "${context}".${suffix}`,
+                code
+            };
+        case "23505": // unique_violation
+            return {
+                message: detail
+                    ? `Duplicate value: ${detail}${suffix}`
+                    : `Cannot complete operation: a unique constraint${constraint ? ` (${constraint})` : ""} was violated in "${context}".${suffix}`,
+                code
+            };
+        case "23502": // not_null_violation
+            return {
+                message: `Missing required field: "${column ?? "unknown"}" in "${tableRef}" cannot be empty.${suffix}`,
+                code
+            };
+        case "23514": // check_violation
+            return {
+                message: `Validation failed: a check constraint${constraint ? ` (${constraint})` : ""} was violated in "${context}".${suffix}`,
+                code
+            };
+        case "22P02": // invalid_text_representation (e.g. invalid UUID, wrong enum value)
+            return {
+                message: `Invalid data format in "${context}": ${pgMessage}${suffix}`,
+                code
+            };
+        case "22001": // string_data_right_truncation (value too long)
+            return {
+                message: `Value too long for column "${column ?? "unknown"}" in "${tableRef}": ${pgMessage}${suffix}`,
+                code
+            };
+        case "22003": // numeric_value_out_of_range
+            return {
+                message: `Numeric value out of range for column "${column ?? "unknown"}" in "${tableRef}": ${pgMessage}${suffix}`,
+                code
+            };
+        case "42703": // undefined_column
+            return {
+                message: `Unknown column in "${tableRef}": ${pgMessage}. Check if your schema is up to date (run migrations).${suffix}`,
+                code
+            };
+        case "42P01": // undefined_table
+            return {
+                message: `Table not found for "${context}": ${pgMessage}. Check if your schema is up to date (run migrations).${suffix}`,
+                code
+            };
+        case "42501": // insufficient_privilege
+            return {
+                message: `Permission denied on "${tableRef}". Check your database credentials and RLS policies.${suffix}`,
+                code
+            };
+        case "28000": // invalid_authorization_specification
+            return {
+                message: `Authorization failed for "${context}". Check your database credentials.${suffix}`,
+                code
+            };
+        default: {
+            // Unhandled PG code — still surface the actual database message
+            const parts = [`Database error in "${context}" [${code}]: ${pgMessage}`];
+            if (detail) parts.push(`Detail: ${detail}`);
+            if (column) parts.push(`Column: ${column}`);
+            if (dataType) parts.push(`Data type: ${dataType}`);
+            if (constraint) parts.push(`Constraint: ${constraint}`);
+            if (hint) parts.push(`Hint: ${hint}`);
+            return { message: parts.join(". "), code };
+        }
+    }
+}
+
+/**
+ * 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 function sanitizeErrorForClient(error: unknown, context: string): { message: string; code?: string } {
+    // ── Always log the full, unsanitized error server-side ──────────
+    const pgError = extractPgError(error);
+
+    if (pgError) {
+        logger.error(`[PG ${pgError.code}] Error in "${context}"`, {
+            code: pgError.code,
+            message: pgError.message,
+            detail: pgError.detail,
+            hint: pgError.hint,
+            column: pgError.column,
+            table: pgError.table,
+            constraint: pgError.constraint,
+            dataType: pgError.dataType,
+            // Also log the outer Drizzle wrapper message for full context
+            drizzleMessage: error instanceof Error ? error.message : String(error)
+        });
+        return pgErrorToFriendlyMessage(pgError, context);
+    }
+
+    // No PG error found — log the raw error as-is
+    logger.error(`Database error in "${context}" (no PG error extracted)`, {
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+        cause: error instanceof Error && error.cause
+            ? (error.cause instanceof Error ? error.cause.message : String(error.cause))
+            : undefined
+    });
+
+    // Try to get the deepest cause message
+    const causeMessage = extractCauseMessage(error);
+    if (causeMessage) {
+        return { message: `Database error in "${context}": ${causeMessage}` };
+    }
+
+    // Last resort — generic message, never leak raw SQL
+    return { message: `Could not load data for "${context}". Check server logs for details.` };
+}

package/src/websocket.ts

@@ -7,6 +7,7 @@ import { WebSocketServer, WebSocket } from "ws";
 import { Server } from "http";
 import { inspect } from "util";
 import { extractUserFromToken, AccessTokenPayload } from "@rebasepro/server-core";
+import { logger } from "@rebasepro/server-core";
 
 /** Minimal subset of RebaseAuthConfig used by the WebSocket layer. */
 interface WsAuthConfig {
@@ -33,7 +34,6 @@ interface ClientSession {
 }
 
 
-
 /** Maximum messages per client per window */
 const WS_RATE_LIMIT = 2000;
 /** Rate limit window in milliseconds (60 seconds) */
@@ -105,7 +105,7 @@ export function createPostgresWebSocket(
             // Silently absorbed — listenWithPortRetry will retry the next port
             return;
         }
-        console.error("❌ [WebSocket Server] Error:", err);
+        logger.error("❌ [WebSocket Server] Error", { error: err });
     });
 
     // Auth is required when either: an adapter is present (secure by default),
@@ -170,14 +170,14 @@ code } }
                             const adapterUser = authAdapter.verifyToken
                                 ? await authAdapter.verifyToken(token)
                                 : await authAdapter.verifyRequest(new Request("http://localhost/_ws_auth", {
-                                    headers: { Authorization: `Bearer ${token}` },
+                                    headers: { Authorization: `Bearer ${token}` }
                                 }));
 
                             if (adapterUser) {
                                 verifiedUser = {
                                     userId: adapterUser.uid,
                                     roles: adapterUser.roles,
-                                    isAdmin: adapterUser.isAdmin,
+                                    isAdmin: adapterUser.isAdmin
                                 };
                             }
                         } catch {
@@ -190,7 +190,7 @@ code } }
                             verifiedUser = {
                                 userId: jwtPayload.userId,
                                 roles: jwtPayload.roles ?? [],
-                                isAdmin: (jwtPayload.roles ?? []).some((r: string) => r === "admin"),
+                                isAdmin: (jwtPayload.roles ?? []).some((r: string) => r === "admin")
                             };
                         }
                     }
@@ -205,7 +205,8 @@ code } }
                         ws.send(JSON.stringify({
                             type: "AUTH_SUCCESS",
                             requestId,
-                            payload: { userId: verifiedUser.userId, roles: verifiedUser.roles }
+                            payload: { userId: verifiedUser.userId,
+roles: verifiedUser.roles }
                         }));
                         wsDebug(`🔐 [WebSocket Server] Client ${clientId} authenticated as ${verifiedUser.userId}`);
                     } else {
@@ -277,7 +278,7 @@ code } }
                                 };
                             return await driver.withAuth(userForAuth);
                         } catch (e) {
-                            console.error("Failed to create RLS scoped delegate for WS request", e);
+                            logger.error("Failed to create RLS scoped delegate for WS request", { error: e });
                             throw new Error("Internal authentication error");
                         }
                     }
@@ -576,8 +577,10 @@ colors: true }));
                         // Attach auth context from the WS session so RLS-aware refetches work
                         const session = clientSessions.get(clientId);
                         const authContext = session?.user
-                            ? { userId: session.user.userId, roles: session.user.roles ?? [] }
-                            : { userId: "anon", roles: ["anon"] };
+                            ? { userId: session.user.userId,
+roles: session.user.roles ?? [] }
+                            : { userId: "anon",
+roles: ["anon"] };
                         // Let RealtimeService handle these messages
                         await realtimeService.handleClientMessage(clientId, {
                             type,
@@ -588,12 +591,12 @@ colors: true }));
                     }
 
                     default:
-                        console.error("❌ [WebSocket Server] Unknown message type:", type);
+                        logger.error("❌ [WebSocket Server] Unknown message type", { detail: type });
                 }
             } catch (error: unknown) {
-                console.error("💥 [WebSocket Server] Error handling message:", error);
+                logger.error("💥 [WebSocket Server] Error handling message", { error: error });
                 if (error instanceof Error) {
-                    console.error("Stack trace:", error.stack);
+                    logger.error("Stack trace", { detail: error.stack });
                 }
                 const errorMessage = process.env.NODE_ENV === "production"
                     ? "An unexpected error occurred"