@rebasepro/server-postgresql 0.5.0 → 0.6.0

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-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"

package/test/auth-services.test.ts

@@ -8,7 +8,9 @@ jest.mock("drizzle-orm", () => {
     const actual = jest.requireActual("drizzle-orm");
     return {
         ...actual,
-        eq: jest.fn((field, value) => ({ field, value, type: "eq" })),
+        eq: jest.fn((field, value) => ({ field,
+value,
+type: "eq" })),
         sql: Object.assign(
             jest.fn((strings: TemplateStringsArray, ...values: unknown[]) => ({
                 strings,
@@ -16,8 +18,11 @@ jest.mock("drizzle-orm", () => {
                 type: "sql"
             })),
             {
-                raw: jest.fn((val: string) => ({ val, type: "sql-raw" })),
-                join: jest.fn((parts: unknown[], separator: unknown) => ({ parts, separator, type: "sql-join" }))
+                raw: jest.fn((val: string) => ({ val,
+type: "sql-raw" })),
+                join: jest.fn((parts: unknown[], separator: unknown) => ({ parts,
+separator,
+type: "sql-join" }))
             }
         ),
         relations: jest.fn(() => ({}))
@@ -133,11 +138,11 @@ describe("Auth Services", () => {
                     email: "test@example.com",
                     displayName: "Test User"
                 };
-                const dbReturnedUser = { 
+                const dbReturnedUser = {
                     id: "user-123",
                     ...newUser,
                     createdAt: new Date(),
-                    updatedAt: new Date() 
+                    updatedAt: new Date()
                 };
                 mockInsertReturning.mockResolvedValueOnce([dbReturnedUser]);
 
@@ -154,7 +159,8 @@ describe("Auth Services", () => {
 
         describe("getUserById", () => {
             it("should return user when found", async () => {
-                const mockUser = { id: "user-123", email: "test@example.com" };
+                const mockUser = { id: "user-123",
+email: "test@example.com" };
                 mockSelectWhere.mockResolvedValueOnce([mockUser]);
 
                 const result = await userService.getUserById("user-123");
@@ -174,7 +180,8 @@ describe("Auth Services", () => {
 
         describe("getUserByEmail", () => {
             it("should return user when found by email", async () => {
-                const mockUser = { id: "user-123", email: "test@example.com" };
+                const mockUser = { id: "user-123",
+email: "test@example.com" };
                 mockSelectWhere.mockResolvedValueOnce([mockUser]);
 
                 const result = await userService.getUserByEmail("test@example.com");
@@ -194,13 +201,15 @@ describe("Auth Services", () => {
 
         describe("getUserByIdentity", () => {
             it("should fetch user by identity", async () => {
-                const mockUser = { id: "user-123", email: "test@example.com" };
+                const mockUser = { id: "user-123",
+email: "test@example.com" };
                 mockSelectWhere.mockResolvedValueOnce([{ user: mockUser }]);
 
                 const result = await userService.getUserByIdentity("google", "google-abc");
 
                 expect(db.select).toHaveBeenCalled();
-                expect(result).toEqual(expect.objectContaining({ id: "user-123", email: "test@example.com" }));
+                expect(result).toEqual(expect.objectContaining({ id: "user-123",
+email: "test@example.com" }));
             });
         });
 
@@ -223,10 +232,10 @@ describe("Auth Services", () => {
 
         describe("updateUser", () => {
             it("should update user and return updated record", async () => {
-                const updatedUser = { 
+                const updatedUser = {
                     id: "user-123",
                     email: "test@example.com",
-                    displayName: "Updated Name" 
+                    displayName: "Updated Name"
                 };
                 mockUpdateReturning.mockResolvedValueOnce([updatedUser]);
 
@@ -261,8 +270,10 @@ describe("Auth Services", () => {
         describe("listUsers", () => {
             it("should return all users", async () => {
                 const mockUsers = [
-                    { id: "user-1", email: "user1@example.com" },
-                    { id: "user-2", email: "user2@example.com" }
+                    { id: "user-1",
+email: "user1@example.com" },
+                    { id: "user-2",
+email: "user2@example.com" }
                 ];
                 mockSelectFrom.mockReturnValueOnce(Promise.resolve(mockUsers));
 
@@ -270,8 +281,10 @@ describe("Auth Services", () => {
 
                 expect(db.select).toHaveBeenCalled();
                 expect(result).toEqual([
-                    mockUserData({ id: "user-1", email: "user1@example.com" }),
-                    mockUserData({ id: "user-2", email: "user2@example.com" })
+                    mockUserData({ id: "user-1",
+email: "user1@example.com" }),
+                    mockUserData({ id: "user-2",
+email: "user2@example.com" })
                 ]);
             });
         });
@@ -332,7 +345,8 @@ describe("Auth Services", () => {
 
         describe("getUserByVerificationToken", () => {
             it("should find user by verification token", async () => {
-                const mockUser = { id: "user-123", email: "test@example.com" };
+                const mockUser = { id: "user-123",
+email: "test@example.com" };
                 mockSelectWhere.mockResolvedValueOnce([mockUser]);
 
                 const result = await userService.getUserByVerificationToken("token-abc");
@@ -396,7 +410,8 @@ describe("Auth Services", () => {
 
         describe("getUserWithRoles", () => {
             it("should return user with roles", async () => {
-                const mockUser = { id: "user-123", email: "test@example.com" };
+                const mockUser = { id: "user-123",
+email: "test@example.com" };
                 mockSelectWhere.mockResolvedValueOnce([mockUser]);
                 mockExecute.mockResolvedValueOnce({
                     rows: [{ roles: ["admin"] }]
@@ -427,7 +442,8 @@ describe("Auth Services", () => {
             it("should return paginated and filtered users list", async () => {
                 mockExecute
                     .mockResolvedValueOnce({ rows: [{ total: 1 }] })
-                    .mockResolvedValueOnce({ rows: [{ id: "user-123", email: "test@example.com" }] });
+                    .mockResolvedValueOnce({ rows: [{ id: "user-123",
+email: "test@example.com" }] });
 
                 const result = await userService.listUsersPaginated({
                     limit: 10,
@@ -439,7 +455,8 @@ describe("Auth Services", () => {
 
                 expect(mockExecute).toHaveBeenCalledTimes(2);
                 expect(result).toEqual({
-                    users: [mockUserData({ id: "user-123", email: "test@example.com" })],
+                    users: [mockUserData({ id: "user-123",
+email: "test@example.com" })],
                     total: 1,
                     limit: 10,
                     offset: 0