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

package/src/services/entity-helpers.ts

@@ -0,0 +1,147 @@
+import { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
+import { EntityCollection, Property } from "@rebasepro/types";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+import { getTableName } from "@rebasepro/common";
+
+/**
+ * Shared helper functions for entity operations.
+ * These are used by EntityFetchService, EntityPersistService, and RelationService.
+ *
+ * All functions that need collection/table lookups require an explicit
+ * `PostgresCollectionRegistry` instance — there is no global singleton.
+ */
+
+/**
+ * Interface for Drizzle column metadata introspection.
+ * Replaces unsafe `as unknown as Record<string, unknown>` double-cast chains.
+ */
+export interface DrizzleColumnMeta {
+    columnType?: string;
+    dataType?: string;
+    primary?: boolean;
+}
+
+/** Safely extract Drizzle column metadata from a column object. */
+export function getColumnMeta(col: AnyPgColumn): DrizzleColumnMeta {
+    const raw = col as unknown as Record<string | symbol, unknown>;
+    return {
+        columnType: typeof raw.columnType === "string" ? raw.columnType : undefined,
+        dataType: typeof raw.dataType === "string" ? raw.dataType : undefined,
+        primary: typeof raw.primary === "boolean" ? raw.primary : undefined
+    };
+}
+
+export function getCollectionByPath(collectionPath: string, registry: PostgresCollectionRegistry): EntityCollection {
+    const collection = registry.getCollectionByPath(collectionPath);
+    if (!collection) {
+        const registered = registry.getCollections().map(c => c.slug).join(", ");
+        throw new Error(`Collection not found: ${collectionPath}. Registered collections: [${registered}]`);
+    }
+    return collection;
+}
+
+export function getTableForCollection(collection: EntityCollection, registry: PostgresCollectionRegistry): PgTable<any> {
+    const tableName = getTableName(collection);
+    const table = registry.getTable(tableName);
+    if (!table) {
+        throw new Error(`Table not found for collection '${collection.slug}' (table: ${tableName})`);
+    }
+    return table;
+}
+
+export function getPrimaryKeys(collection: EntityCollection, registry: PostgresCollectionRegistry): { fieldName: string; type: "string" | "number"; isUUID?: boolean }[] {
+    const table = getTableForCollection(collection, registry);
+
+    // Fallback to explicitly defined isId properties
+    if (collection.properties) {
+        const idProps = Object.entries(collection.properties)
+            .filter(([_, prop]) => "isId" in (prop as object) && Boolean((prop as { isId?: unknown }).isId))
+            .map(([key, prop]) => ({
+                fieldName: key,
+                type: prop.type === "number" ? "number" as const : "string" as const,
+                isUUID: (prop as { isId?: unknown }).isId === "uuid"
+            }));
+
+        if (idProps.length > 0) {
+            return idProps;
+        }
+    }
+
+    // Otherwise infer from Drizzle schema
+    const keys: { fieldName: string; type: "string" | "number"; isUUID?: boolean }[] = [];
+    for (const [key, colRaw] of Object.entries(table)) {
+        const col = colRaw as AnyPgColumn;
+        if (col && typeof col === "object" && "primary" in col && col.primary) {
+            const meta = getColumnMeta(col);
+            const type = col.dataType === "number" || meta.columnType === "PgSerial" || meta.columnType === "PgInteger" ? "number" : "string";
+            const isUUID = meta.columnType === "PgUUID";
+            keys.push({ fieldName: key, type, isUUID });
+        }
+    }
+
+    // Default to 'id' if no primary keys are found and it exists in the schema
+    // This maintains backwards compatibility
+    if (keys.length === 0 && "id" in table) {
+        const idCol = table["id" as keyof typeof table] as AnyPgColumn;
+        const idMeta = getColumnMeta(idCol);
+        const type = idCol.dataType === "number" || idMeta.columnType === "PgSerial" || idMeta.columnType === "PgInteger" ? "number" : "string";
+        const isUUID = idMeta.columnType === "PgUUID";
+        keys.push({ fieldName: "id", type, isUUID });
+    }
+
+    return keys;
+}
+
+export function parseIdValues(idValue: string | number, primaryKeys: { fieldName: string; type: "string" | "number"; isUUID?: boolean }[]): Record<string, string | number> {
+    const result: Record<string, string | number> = {};
+
+    if (primaryKeys.length === 0) {
+        return result;
+    }
+
+    if (primaryKeys.length === 1) {
+        const pk = primaryKeys[0];
+        if (pk.type === "number" && !pk.isUUID) {
+            const parsed = typeof idValue === "number" ? idValue : parseInt(String(idValue), 10);
+            if (isNaN(parsed)) {
+                throw new Error(`Invalid numeric ID: ${idValue}`);
+            }
+            result[pk.fieldName] = parsed;
+        } else {
+            result[pk.fieldName] = String(idValue);
+        }
+        return result;
+    }
+
+    // Composite key - split by :::
+    const parts = String(idValue).split(":::");
+    if (parts.length !== primaryKeys.length) {
+        throw new Error(`Composite ID parts mismatch. Expected ${primaryKeys.length}, got ${parts.length} for ID: ${idValue}`);
+    }
+
+    for (let i = 0; i < primaryKeys.length; i++) {
+        const pk = primaryKeys[i];
+        const val = parts[i];
+        if (pk.type === "number" && !pk.isUUID) {
+            const parsed = parseInt(val, 10);
+            if (isNaN(parsed)) {
+                throw new Error(`Invalid numeric ID component: ${val}`);
+            }
+            result[pk.fieldName] = parsed;
+        } else {
+            result[pk.fieldName] = val;
+        }
+    }
+
+    return result;
+}
+
+export function buildCompositeId(values: Record<string, unknown>, primaryKeys: { fieldName: string; type: "string" | "number"; isUUID?: boolean }[]): string {
+    if (primaryKeys.length === 0) {
+        return "";
+    }
+    if (primaryKeys.length === 1) {
+        return String(values[primaryKeys[0].fieldName] ?? "");
+    }
+    return primaryKeys.map(pk => String(values[pk.fieldName] ?? "")).join(":::");
+}

package/src/services/entityService.ts

@@ -0,0 +1,211 @@
+// import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { Entity, FilterValues } from "@rebasepro/types";
+import { EntityFetchService } from "./EntityFetchService";
+import { EntityPersistService } from "./EntityPersistService";
+import { RelationService } from "./RelationService";
+import { EntityRepository, FetchCollectionOptions, SearchOptions, CountOptions, DrizzleClient } from "../interfaces";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+
+// Re-export data transformer functions for external use
+export { sanitizeAndConvertDates, serializeDataToServer, parseDataFromServer } from "../data-transformer";
+
+// Re-export service classes for direct use
+export { EntityFetchService } from "./EntityFetchService";
+export { EntityPersistService } from "./EntityPersistService";
+export { RelationService } from "./RelationService";
+
+// Re-export interfaces
+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 class EntityService implements EntityRepository {
+    private fetchService: EntityFetchService;
+    private persistService: EntityPersistService;
+
+    constructor(private db: DrizzleClient, private registry: PostgresCollectionRegistry) {
+        this.fetchService = new EntityFetchService(db, registry);
+        this.persistService = new EntityPersistService(db, registry);
+    }
+
+    // =============================================================
+    // READ OPERATIONS - Delegated to EntityFetchService
+    // =============================================================
+
+    /**
+     * Fetch a single entity by ID
+     */
+    async fetchEntity<M extends Record<string, unknown>>(
+        collectionPath: string,
+        entityId: string | number,
+        databaseId?: string
+    ): Promise<Entity<M> | undefined> {
+        return this.fetchService.fetchEntity<M>(collectionPath, entityId, databaseId);
+    }
+
+    /**
+     * Fetch a collection of entities with optional filtering, ordering, and pagination
+     */
+    async fetchCollection<M extends Record<string, unknown>>(
+        collectionPath: string,
+        options: {
+            filter?: FilterValues<Extract<keyof M, string>>;
+            orderBy?: string;
+            order?: "desc" | "asc";
+            limit?: number;
+            offset?: number;
+            startAfter?: Record<string, unknown>;
+            searchString?: string;
+            databaseId?: string;
+        } = {}
+    ): Promise<Entity<M>[]> {
+        return this.fetchService.fetchCollection<M>(collectionPath, options);
+    }
+
+    /**
+     * Search entities by text
+     */
+    async 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>[]> {
+        return this.fetchService.searchEntities<M>(collectionPath, searchString, options);
+    }
+
+    /**
+     * Count entities in a collection
+     */
+    async countEntities<M extends Record<string, unknown>>(
+        collectionPath: string,
+        options: {
+            filter?: FilterValues<Extract<keyof M, string>>;
+            searchString?: string;
+            databaseId?: string;
+        } = {}
+    ): Promise<number> {
+        return this.fetchService.countEntities<M>(collectionPath, options);
+    }
+
+    /**
+     * Check if a field value is unique in a collection
+     */
+    async checkUniqueField(
+        collectionPath: string,
+        fieldName: string,
+        value: unknown,
+        excludeEntityId?: string,
+        databaseId?: string
+    ): Promise<boolean> {
+        return this.fetchService.checkUniqueField(collectionPath, fieldName, value, excludeEntityId, databaseId);
+    }
+
+    /**
+     * Fetch entities related to a parent entity
+     */
+    async 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>[]> {
+        return this.fetchService.getRelationService().fetchRelatedEntities<M>(
+            parentCollectionPath,
+            parentEntityId,
+            relationKey,
+            options
+        );
+    }
+
+    // =============================================================
+    // WRITE OPERATIONS - Delegated to EntityPersistService
+    // =============================================================
+
+    /**
+     * Save an entity (create or update)
+     */
+    async saveEntity<M extends Record<string, unknown>>(
+        collectionPath: string,
+        values: Partial<M>,
+        entityId?: string | number,
+        databaseId?: string
+    ): Promise<Entity<M>> {
+        return this.persistService.saveEntity<M>(collectionPath, values, entityId, databaseId);
+    }
+
+    /**
+     * Delete an entity by ID
+     */
+    async deleteEntity(
+        collectionPath: string,
+        entityId: string | number,
+        databaseId?: string
+    ): Promise<void> {
+        return this.persistService.deleteEntity(collectionPath, entityId, databaseId);
+    }
+
+
+    /**
+     * Execute raw SQL
+     */
+    async executeSql(sqlText: string): Promise<Record<string, unknown>[]> {
+        if (process.env.NODE_ENV !== "production") {
+            console.debug("Executing raw SQL:", sqlText);
+        }
+        const { sql } = await import("drizzle-orm");
+        const result = await this.db.execute(sql.raw(sqlText));
+        const rows = result.rows;
+        if (process.env.NODE_ENV !== "production") {
+            console.debug(`SQL executed successfully. Returned ${Array.isArray(rows) ? rows.length : "non-array"} rows.`);
+        }
+        return rows as Record<string, unknown>[];
+    }
+
+    // =============================================================
+    // SERVICE ACCESSORS
+    // =============================================================
+
+    /**
+     * Get the underlying EntityFetchService for advanced use
+     */
+    getFetchService(): EntityFetchService {
+        return this.fetchService;
+    }
+
+    /**
+     * Get the underlying EntityPersistService for advanced use
+     */
+    getPersistService(): EntityPersistService {
+        return this.persistService;
+    }
+
+    /**
+     * Get the underlying RelationService for advanced use
+     */
+    getRelationService(): RelationService {
+        return this.fetchService.getRelationService();
+    }
+}

package/src/services/index.ts

@@ -0,0 +1,13 @@
+// Re-export all service classes
+export { EntityFetchService } from "./EntityFetchService";
+export { EntityPersistService } from "./EntityPersistService";
+export { RelationService } from "./RelationService";
+
+// Re-export helper functions
+export {
+    getCollectionByPath,
+    getTableForCollection,
+    getPrimaryKeys,
+    parseIdValues,
+    buildCompositeId
+} from "./entity-helpers";