@rebasepro/server-postgresql 0.0.1-canary.4d4fb3e → 0.0.1-canary.ca2cb6e

package/src/services/EntityFetchService.ts

@@ -1,7 +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 { resolveCollectionRelations } from "@rebasepro/common";
+import { resolveCollectionRelations, findRelation, createRelationRef, createRelationRefWithData } from "@rebasepro/common";
 import { DrizzleConditionBuilder } from "../utils/drizzle-conditions";
 import {
     getCollectionByPath,
@@ -43,7 +43,7 @@ export class EntityFetchService {
      * Build filter conditions from FilterValues
      * Delegates to DrizzleConditionBuilder.buildFilterConditions
      */
-    buildFilterConditions<M extends Record<string, any>>(
+    buildFilterConditions<M extends Record<string, unknown>>(
         filter: FilterValues<Extract<keyof M, string>>,
         table: PgTable<any>,
         collectionPath: string
@@ -55,6 +55,25 @@ export class EntityFetchService {
     // DRIZZLE QUERY HELPERS
     // =============================================================
 
+    /**
+     * Resolves the correct Drizzle column for sorting.
+     * Automatically maps owning relation property keys to their underlying foreign key column.
+     */
+    private resolveOrderByField(
+        table: PgTable<any>,
+        orderBy: string,
+        collection?: EntityCollection
+    ): AnyPgColumn | undefined {
+        let orderByField = table[orderBy as keyof typeof table] as AnyPgColumn;
+        if (!orderByField && collection) {
+            const property = collection.properties[orderBy];
+            if (property && property.type === "relation" && "relation" in property && property.relation?.direction === "owning") {
+                orderByField = table[`${orderBy}_id` as keyof typeof table] as AnyPgColumn;
+            }
+        }
+        return orderByField;
+    }
+
     /**
      * Build the `with` config for Drizzle's relational query API.
      * Converts collection relations to a Drizzle-compatible `with` object.
@@ -69,8 +88,7 @@ export class EntityFetchService {
         collection: EntityCollection,
         include?: string[]
     ): Record<string, boolean | { with: Record<string, boolean> }> {
-        const resolvedRelations = resolveCollectionRelations(collection as import("@rebasepro/types").PostgresCollection<any, any>);
-        const propertyKeys = new Set(Object.keys(collection.properties || {}));
+        const resolvedRelations = resolveCollectionRelations(collection);
         const withConfig: Record<string, boolean | { with: Record<string, boolean> }> = {};
 
         const shouldInclude = (key: string) =>
@@ -78,8 +96,6 @@ export class EntityFetchService {
 
         for (const [key, relation] of Object.entries(resolvedRelations)) {
             if (!shouldInclude(key)) continue;
-            // Only include relations that map to actual properties (or include all for REST)
-            if (!include && !propertyKeys.has(key)) continue;
 
             const drizzleRelName = relation.relationName || key;
 
@@ -141,7 +157,7 @@ export class EntityFetchService {
      * - Converting nested relation objects to { id, path, __type: "relation" } for CMS
      * - Flattening junction-table many-to-many results
      */
-    private drizzleResultToEntity<M extends Record<string, any>>(
+    private drizzleResultToEntity<M extends Record<string, unknown>>(
         row: Record<string, unknown>,
         collection: EntityCollection,
         collectionPath: string,
@@ -149,15 +165,13 @@ export class EntityFetchService {
         databaseId?: string,
         idInfoArray?: { fieldName: string; type: "string" | "number" }[]
     ): Entity<M> {
-        const resolvedRelations = resolveCollectionRelations(collection as import("@rebasepro/types").PostgresCollection<any, any>);
-        const propertyKeys = new Set(Object.keys(collection.properties || {}));
+        const resolvedRelations = resolveCollectionRelations(collection);
 
         // Normalize non-relation values (dates, numbers, etc.)
         const normalizedValues = normalizeDbValues(row as M, collection);
 
         // Convert nested relation objects to CMS-style { id, path, __type: "relation" }
         for (const [key, relation] of Object.entries(resolvedRelations)) {
-            if (!propertyKeys.has(key)) continue;
             const drizzleRelName = relation.relationName || key;
             const relData = row[drizzleRelName];
 
@@ -186,17 +200,12 @@ export class EntityFetchService {
                     const relId = String(targetEntity[targetIdField] ?? targetEntity.id ?? targetEntity[Object.keys(targetEntity)[0]]);
                     const targetValues = normalizeDbValues(targetEntity, targetCollection);
 
-                    return {
+                    return createRelationRefWithData(relId, targetPath, {
                         id: relId,
                         path: targetPath,
-                        __type: "relation" as const,
-                        data: {
-                            id: relId,
-                            path: targetPath,
-                            values: targetValues,
-                            databaseId
-                        }
-                    };
+                        values: targetValues,
+                        databaseId
+                    });
                 });
             } else if (relation.cardinality === "one" && typeof relData === "object" && !Array.isArray(relData)) {
                 const targetCollection = relation.target();
@@ -208,22 +217,17 @@ export class EntityFetchService {
                 const relId = String(relObj[targetIdField] ?? relObj.id ?? relObj[Object.keys(relObj)[0]]);
                 const targetValues = normalizeDbValues(relObj, targetCollection);
 
-                (normalizedValues as Record<string, unknown>)[key] = {
+                (normalizedValues as Record<string, unknown>)[key] = createRelationRefWithData(relId, targetPath, {
                     id: relId,
                     path: targetPath,
-                    __type: "relation" as const,
-                    data: {
-                        id: relId,
-                        path: targetPath,
-                        values: targetValues,
-                        databaseId
-                    }
-                };
+                    values: targetValues,
+                    databaseId
+                });
             }
         }
 
         return {
-            id: (idInfoArray && idInfoArray.length > 1) ? buildCompositeId(row as Record<string, any>, idInfoArray) : String(row[idInfo.fieldName]),
+            id: (idInfoArray && idInfoArray.length > 1) ? buildCompositeId(row as Record<string, unknown>, idInfoArray) : String(row[idInfo.fieldName]),
             path: collectionPath,
             values: normalizedValues as M,
             databaseId
@@ -235,18 +239,17 @@ export class EntityFetchService {
      * joinPath relations cannot be expressed via Drizzle's `with` config,
      * so they must be loaded separately after the primary query.
      */
-    private async resolveJoinPathRelations<M extends Record<string, any>>(
+    private async resolveJoinPathRelations<M extends Record<string, unknown>>(
         entity: Entity<M>,
         collection: EntityCollection,
         collectionPath: string,
         parsedId: string | number,
         databaseId?: string
     ): Promise<void> {
-        const resolvedRelations = resolveCollectionRelations(collection as import("@rebasepro/types").PostgresCollection<any, any>);
-        const propertyKeys = new Set(Object.keys(collection.properties || {}));
+        const resolvedRelations = resolveCollectionRelations(collection);
 
         const promises = Object.entries(resolvedRelations)
-            .filter(([key, relation]) => propertyKeys.has(key) && relation.joinPath && relation.joinPath.length > 0)
+            .filter(([key, relation]) => relation.joinPath && relation.joinPath.length > 0)
             .map(async ([key, relation]) => {
                 try {
                     const relatedEntities = await this.relationService.fetchRelatedEntities(
@@ -258,19 +261,11 @@ export class EntityFetchService {
 
                     if (relation.cardinality === "one" && relatedEntities.length > 0) {
                         const e = relatedEntities[0];
-                        (entity.values as Record<string, unknown>)[key] = {
-                            id: e.id,
-                            path: e.path,
-                            __type: "relation" as const,
-                            data: e
-                        };
+                        (entity.values as Record<string, unknown>)[key] = createRelationRefWithData(e.id, e.path, e);
                     } else if (relation.cardinality === "many") {
-                        (entity.values as Record<string, unknown>)[key] = relatedEntities.map(e => ({
-                            id: e.id,
-                            path: e.path,
-                            __type: "relation" as const,
-                            data: e
-                        }));
+                        (entity.values as Record<string, unknown>)[key] = relatedEntities.map(e =>
+                            createRelationRefWithData(e.id, e.path, e)
+                        );
                     }
                 } catch (e) {
                     console.warn(`Could not resolve joinPath relation '${key}':`, e);
@@ -284,7 +279,7 @@ export class EntityFetchService {
      * Post-fetch joinPath relations for a batch of entities.
      * Uses batch fetching to avoid N+1 queries for list views.
      */
-    private async resolveJoinPathRelationsBatch<M extends Record<string, any>>(
+    private async resolveJoinPathRelationsBatch<M extends Record<string, unknown>>(
         entities: Entity<M>[],
         collection: EntityCollection,
         collectionPath: string,
@@ -293,11 +288,10 @@ export class EntityFetchService {
     ): Promise<void> {
         if (entities.length === 0) return;
 
-        const resolvedRelations = resolveCollectionRelations(collection as import("@rebasepro/types").PostgresCollection<any, any>);
-        const propertyKeys = new Set(Object.keys(collection.properties || {}));
+        const resolvedRelations = resolveCollectionRelations(collection);
 
         const joinPathRelations = Object.entries(resolvedRelations)
-            .filter(([key, relation]) => propertyKeys.has(key) && relation.joinPath && relation.joinPath.length > 0);
+            .filter(([key, relation]) => relation.joinPath && relation.joinPath.length > 0);
 
         if (joinPathRelations.length === 0) return;
 
@@ -318,21 +312,94 @@ export class EntityFetchService {
                 for (const entity of entities) {
                     const parsed = parseIdValues(entity.id, [idInfo]);
                     const entityId = parsed[idInfo.fieldName] as string | number;
-                    const relatedEntity = resultMap.get(entityId);
+                    const relatedEntity = resultMap.get(String(entityId));
 
                     if (relatedEntity) {
                         if (relation.cardinality === "one") {
-                            (entity.values as Record<string, unknown>)[key] = {
+                            (entity.values as Record<string, unknown>)[key] = createRelationRefWithData(relatedEntity.id, relatedEntity.path, relatedEntity);
+                        }
+                    }
+                }
+            } catch (e) {
+                console.warn(`Could not batch resolve joinPath relation '${key}':`, e);
+            }
+        }
+    }
+
+    /**
+     * Resolves joinPath relations for raw REST rows and directly injects them.
+     * Uses RelationService to query the database and maps results back to the flattened objects.
+     */
+    private async resolveJoinPathRelationsBatchRest(
+        rows: Record<string, unknown>[],
+        collection: EntityCollection,
+        collectionPath: string,
+        idInfoArray: { fieldName: string; type: "string" | "number" }[],
+        include?: string[]
+    ): Promise<void> {
+        if (rows.length === 0) return;
+
+        const resolvedRelations = resolveCollectionRelations(collection);
+        const propertyKeys = new Set(Object.keys(collection.properties || {}));
+        const shouldInclude = (key: string) =>
+            !include || include.length === 0 || include[0] === "*" || include.includes(key);
+
+        const joinPathRelations = Object.entries(resolvedRelations)
+            .filter(([key, relation]) => relation.joinPath && relation.joinPath.length > 0 && propertyKeys.has(key) && shouldInclude(key));
+
+        if (joinPathRelations.length === 0) return;
+
+        const idInfo = idInfoArray[0];
+
+        for (const [key, relation] of joinPathRelations) {
+            try {
+                // Determine the parent IDs based on the parsed string ID from the REST row
+                const entityIds = rows.map(r => {
+                    const parsed = parseIdValues(String(r.id), idInfoArray);
+                    return parsed[idInfo.fieldName] as string | number;
+                });
+
+                if (relation.cardinality === "one") {
+                    const resultMap = await this.relationService.batchFetchRelatedEntities(
+                        collectionPath,
+                        entityIds,
+                        key,
+                        relation
+                    );
+
+                    for (const row of rows) {
+                        const parsed = parseIdValues(String(row.id), idInfoArray);
+                        const entityId = parsed[idInfo.fieldName] as string | number;
+                        const relatedEntity = resultMap.get(String(entityId));
+
+                        if (relatedEntity) {
+                            row[key] = {
                                 id: relatedEntity.id,
-                                path: relatedEntity.path,
-                                __type: "relation" as const,
-                                data: relatedEntity
+                                ...relatedEntity.values
                             };
+                        } else {
+                            row[key] = null;
                         }
                     }
+                } else if (relation.cardinality === "many") {
+                    const resultMap = await this.batchFetchManyRelatedEntities(
+                        collectionPath,
+                        entityIds,
+                        key
+                    );
+
+                    for (const row of rows) {
+                        const parsed = parseIdValues(String(row.id), idInfoArray);
+                        const entityId = parsed[idInfo.fieldName] as string | number;
+                        const relatedList = resultMap.get(String(entityId)) || [];
+                        row[key] = relatedList.map(e => ({
+                            id: e.id,
+                            ...e.values
+                        }));
+                    }
                 }
             } catch (e) {
-                console.warn(`Could not batch resolve joinPath relation '${key}':`, e);
+                console.warn(`Could not batch resolve joinPath relation '${key}' for REST:`, e);
             }
         }
     }
@@ -346,13 +413,13 @@ export class EntityFetchService {
         idInfo: { fieldName: string; type: "string" | "number" },
         idInfoArray?: { fieldName: string; type: "string" | "number" }[]
     ): Record<string, unknown> {
-        const flat: Record<string, unknown> = { id: (idInfoArray && idInfoArray.length > 1) ? buildCompositeId(row as Record<string, any>, idInfoArray) : String(row[idInfo.fieldName]) };
-        const resolvedRelations = resolveCollectionRelations(collection as import("@rebasepro/types").PostgresCollection<any, any>);
+        const flat: Record<string, unknown> = { id: (idInfoArray && idInfoArray.length > 1) ? buildCompositeId(row as Record<string, unknown>, idInfoArray) : String(row[idInfo.fieldName]) };
+        const resolvedRelations = resolveCollectionRelations(collection);
 
         for (const [k, v] of Object.entries(row)) {
             if (k === idInfo.fieldName) continue;
 
-            const relation = resolvedRelations[k];
+            const relation = findRelation(resolvedRelations, k);
             if (Array.isArray(v) && relation) {
                 // Many relation — flatten each nested entity, handling junction tables
                 flat[k] = v.map((item: Record<string, unknown>) => {
@@ -362,15 +429,18 @@ export class EntityFetchService {
                         );
                         if (nestedKey) {
                             const nested = item[nestedKey] as Record<string, unknown>;
-                            return { id: String(nested.id ?? nested[Object.keys(nested)[0]]), ...nested };
+                            return { id: String(nested.id ?? nested[Object.keys(nested)[0]]),
+...nested };
                         }
                     }
-                    return { id: String(item.id ?? item[Object.keys(item)[0]]), ...item };
+                    return { id: String(item.id ?? item[Object.keys(item)[0]]),
+...item };
                 });
             } else if (typeof v === "object" && v !== null && !Array.isArray(v) && relation) {
                 // One-to-one relation — inline the object
                 const relObj = v as Record<string, unknown>;
-                flat[k] = { id: String(relObj.id ?? relObj[Object.keys(relObj)[0]]), ...relObj };
+                flat[k] = { id: String(relObj.id ?? relObj[Object.keys(relObj)[0]]),
+...relObj };
             } else {
                 flat[k] = v;
             }
@@ -382,7 +452,7 @@ export class EntityFetchService {
      * Build db.query-compatible options from standard fetch options.
      * Handles filter, search, orderBy, limit, and cursor-based pagination.
      */
-    private buildDrizzleQueryOptions<M extends Record<string, any>>(
+    private buildDrizzleQueryOptions<M extends Record<string, unknown>>(
         table: PgTable<any>,
         idField: AnyPgColumn,
         idInfo: { fieldName: string; type: "string" | "number" },
@@ -391,11 +461,12 @@ export class EntityFetchService {
             orderBy?: string;
             order?: "desc" | "asc";
             limit?: number;
+            offset?: number;
             startAfter?: Record<string, unknown>;
             searchString?: string;
         },
         collectionPath: string,
-        withConfig?: Record<string, any>
+        withConfig?: Record<string, unknown>
     ): Record<string, unknown> {
         const queryOpts: Record<string, unknown> = {};
 
@@ -424,7 +495,7 @@ export class EntityFetchService {
 
         // Cursor-based pagination (startAfter)
         if (options.startAfter) {
-            const cursorConditions = this.buildCursorConditions(table, idField, idInfo, options);
+            const cursorConditions = this.buildCursorConditions(table, idField, idInfo, options, collectionPath);
             if (cursorConditions.length > 0) allConditions.push(...cursorConditions);
         }
 
@@ -435,7 +506,8 @@ export class EntityFetchService {
         // OrderBy
         const orderExpressions: unknown[] = [];
         if (options.orderBy) {
-            const orderByField = table[options.orderBy as keyof typeof table] as AnyPgColumn;
+            const collection = getCollectionByPath(collectionPath, this.registry);
+            const orderByField = this.resolveOrderByField(table, options.orderBy, collection);
             if (orderByField) {
                 orderExpressions.push(options.order === "asc" ? asc(orderByField) : desc(orderByField));
             }
@@ -449,6 +521,9 @@ export class EntityFetchService {
         const limitValue = options.searchString ? (options.limit || 50) : options.limit;
         if (limitValue) queryOpts.limit = limitValue;
 
+        // Offset (numeric pagination)
+        if (options.offset && options.offset > 0) queryOpts.offset = options.offset;
+
         return queryOpts;
     }
 
@@ -459,13 +534,15 @@ export class EntityFetchService {
         table: PgTable<any>,
         idField: AnyPgColumn,
         idInfo: { fieldName: string; type: "string" | "number" },
-        options: { orderBy?: string; order?: "desc" | "asc"; startAfter?: Record<string, unknown> }
+        options: { orderBy?: string; order?: "desc" | "asc"; startAfter?: Record<string, unknown> },
+        collectionPath?: string
     ): SQL[] {
         if (!options.startAfter) return [];
         const cursor = options.startAfter;
 
         if (options.orderBy) {
-            const orderByField = table[options.orderBy as keyof typeof table] as AnyPgColumn;
+            const collection = collectionPath ? getCollectionByPath(collectionPath, this.registry) : undefined;
+            const orderByField = this.resolveOrderByField(table, options.orderBy, collection);
             if (orderByField) {
                 const startAfterOrderValue = (cursor.values as Record<string, unknown> | undefined)?.[options.orderBy] ?? cursor[options.orderBy];
                 const startAfterId = cursor.id ?? cursor[idInfo.fieldName];
@@ -499,7 +576,7 @@ export class EntityFetchService {
     /**
      * Fetch a single entity by ID
      */
-    async fetchEntity<M extends Record<string, any>>(
+    async fetchEntity<M extends Record<string, unknown>>(
         collectionPath: string,
         entityId: string | number,
         databaseId?: string
@@ -518,14 +595,14 @@ export class EntityFetchService {
         const parsedId = parsedIdObj[idInfo.fieldName];
 
         // Primary path: use db.query.findFirst with relation loading
-        
+
         const tableName = getTableName(table);
 
         const qb = this.getQueryBuilder(tableName);
         if (qb) {
             try {
                 const withConfig = this.buildWithConfig(collection);
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- dynamic query config
+
                 const row = await qb.findFirst({
                     where: eq(idField, parsedId),
                     with: withConfig
@@ -557,7 +634,7 @@ export class EntityFetchService {
         const values = await parseDataFromServer(raw, collection, this.db, this.registry);
 
         // Load relations based on cardinality (N+1 — only used in fallback)
-        const resolvedRelations = resolveCollectionRelations(collection as import("@rebasepro/types").PostgresCollection<any, any>);
+        const resolvedRelations = resolveCollectionRelations(collection);
         const propertyKeys = new Set(Object.keys(collection.properties));
 
         const relationPromises = Object.entries(resolvedRelations)
@@ -570,11 +647,9 @@ export class EntityFetchService {
                         key,
                         {}
                     );
-                    (values as Record<string, unknown>)[key] = relatedEntities.map(e => ({
-                        id: e.id,
-                        path: e.path,
-                        __type: "relation"
-                    }));
+                    (values as Record<string, unknown>)[key] = relatedEntities.map(e =>
+                        createRelationRef(e.id, e.path)
+                    );
                 } else if (relation.cardinality === "one") {
                     if ((values as Record<string, unknown>)[key] == null) {
                         try {
@@ -586,11 +661,7 @@ export class EntityFetchService {
                             );
                             if (relatedEntities.length > 0) {
                                 const e = relatedEntities[0];
-                                (values as Record<string, unknown>)[key] = {
-                                    id: e.id,
-                                    path: e.path,
-                                    __type: "relation"
-                                };
+                                (values as Record<string, unknown>)[key] = createRelationRef(e.id, e.path);
                             }
                         } catch (e) {
                             console.warn(`Could not resolve one-to-one relation property: ${key}`, e);
@@ -612,13 +683,14 @@ export class EntityFetchService {
     /**
      * Unified method to fetch entities with optional search functionality
      */
-    async fetchEntitiesWithConditions<M extends Record<string, any>>(
+    async fetchEntitiesWithConditions<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;
@@ -635,27 +707,30 @@ export class EntityFetchService {
         }
 
         // Primary path: use db.query.findMany with relation loading
-        
+        // Skip when searchString is present (same reason as fetchCollectionForRest)
+        // Skip when collection has relations — lateral JOINs are catastrophically
+        // slow for large collections (7s+ for 350 rows). The db.select fallback
+        // path uses batch relation resolution which is 50x faster.
+
         const tableName = getTableName(table);
 
         const qb = this.getQueryBuilder(tableName);
-        if (qb) {
+        const withConfig = this.buildWithConfig(collection);
+        const hasRelations = withConfig && Object.keys(withConfig).length > 0;
+
+        if (qb && !options.searchString && !hasRelations) {
             try {
-                const withConfig = this.buildWithConfig(collection);
                 const queryOpts = this.buildDrizzleQueryOptions<M>(
-                    table, idField, idInfo, options, collectionPath, withConfig
+                    table, idField, idInfo, options, collectionPath, undefined
                 );
 
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- dynamic query config
+
                 const results = await qb.findMany(queryOpts as unknown as Parameters<NonNullable<typeof qb>["findMany"]>[0]);
 
                 const entities = (results as Record<string, unknown>[]).map(row =>
                     this.drizzleResultToEntity<M>(row, collection, collectionPath, idInfo, options.databaseId, idInfoArray)
                 );
 
-                // Post-fetch joinPath relations that Drizzle's `with` can't express
-                await this.resolveJoinPathRelationsBatch(entities, collection, collectionPath, idInfo, options.databaseId);
-
                 return entities;
             } catch (e) {
                 console.warn(`[EntityFetchService] db.query.findMany failed for ${collectionPath}, falling back to db.select:`, e);
@@ -686,7 +761,7 @@ export class EntityFetchService {
 
         const orderExpressions = [];
         if (options.orderBy) {
-            const orderByField = table[options.orderBy as keyof typeof table] as AnyPgColumn;
+            const orderByField = this.resolveOrderByField(table, options.orderBy, collection);
             if (orderByField) {
                 orderExpressions.push(options.order === "asc" ? asc(orderByField) : desc(orderByField));
             }
@@ -695,7 +770,7 @@ export class EntityFetchService {
         if (orderExpressions.length > 0) query = query.orderBy(...orderExpressions);
 
         if (options.startAfter) {
-            const cursorConditions = this.buildCursorConditions(table, idField, idInfo, options);
+            const cursorConditions = this.buildCursorConditions(table, idField, idInfo, options, collectionPath);
             if (cursorConditions.length > 0) {
                 allConditions.push(...cursorConditions);
                 const finalCondition = DrizzleConditionBuilder.combineConditionsWithAnd(allConditions);
@@ -706,6 +781,9 @@ export class EntityFetchService {
         const limitValue = 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;
 
         return this.processEntityResults<M>(results, collection, collectionPath, idInfo, options.databaseId, false, idInfoArray);
@@ -718,31 +796,36 @@ export class EntityFetchService {
      *
      * Process raw database results into Entity objects with relations.
      */
-    private async processEntityResults<M extends Record<string, any>>(
+    private async processEntityResults<M extends Record<string, unknown>>(
         results: Record<string, unknown>[],
         collection: EntityCollection,
         collectionPath: string,
         idInfo: { fieldName: string; type: "string" | "number" },
         databaseId?: string,
-        skipRelations: boolean = false,
+        skipRelations = false,
         idInfoArray?: { fieldName: string; type: "string" | "number" }[]
     ): Promise<Entity<M>[]> {
         if (results.length === 0) return [];
 
-        // First pass: parse all entities
+        // First pass: parse all entities WITHOUT per-entity relation queries.
+        // We deliberately omit db/registry so parseDataFromServer only does type
+        // coercion (dates, numbers, FK→relation stubs for owning relations) and
+        // does NOT issue individual SQL queries for inverse relations.  The second
+        // pass below batch-loads all inverse/many relations in O(1) queries per
+        // relation type, avoiding the N+1 that plagued the old path.
         const entitiesWithValues = await Promise.all(results.map(async (entity: Record<string, unknown>) => {
-            const values = await parseDataFromServer(entity as M, collection, this.db, this.registry);
+            const values = await parseDataFromServer(entity as M, collection);
             return {
                 entity,
                 values,
-                id: (idInfoArray && idInfoArray.length > 1) ? buildCompositeId(entity as Record<string, any>, idInfoArray!) : String(entity[idInfo.fieldName]),
+                id: (idInfoArray && idInfoArray.length > 1) ? buildCompositeId(entity as Record<string, unknown>, idInfoArray!) : String(entity[idInfo.fieldName]),
                 path: collectionPath
             };
         }));
 
         if (!skipRelations) {
             // Second pass: batch load missing one-to-one relations
-            const resolvedRelations = resolveCollectionRelations(collection as import("@rebasepro/types").PostgresCollection<any, any>);
+            const resolvedRelations = resolveCollectionRelations(collection);
             const propertyKeys = new Set(Object.keys(collection.properties));
 
             for (const [key, relation] of Object.entries(resolvedRelations)) {
@@ -768,14 +851,9 @@ export class EntityFetchService {
 
                     entitiesMissingRelation.forEach(item => {
                         const entityId = item.entity[idInfo.fieldName] as string | number;
-                        const relatedEntity = relationResults.get(entityId);
+                        const relatedEntity = relationResults.get(String(entityId));
                         if (relatedEntity) {
-                            (item.values as Record<string, unknown>)[key] = {
-                                id: relatedEntity.id,
-                                path: relatedEntity.path,
-                                __type: "relation",
-                                data: relatedEntity
-                            };
+                            (item.values as Record<string, unknown>)[key] = createRelationRefWithData(relatedEntity.id, relatedEntity.path, relatedEntity);
                         }
                     });
                 } catch (e) {
@@ -783,32 +861,32 @@ export class EntityFetchService {
                 }
             }
 
-            // Handle many relations
-            const manyRelationPromises = entitiesWithValues.map(async (item) => {
-                const manyRelationQueries = Object.entries(resolvedRelations)
-                    .filter(([key, relation]) => propertyKeys.has(key) && relation.cardinality === "many")
-                    .map(async ([key]) => {
-                        try {
-                            const relatedEntities = await this.relationService.fetchRelatedEntities(
-                                collectionPath,
-                                item.entity[idInfo.fieldName] as string | number,
-                                key,
-                                {}
-                            );
-                            (item.values as Record<string, unknown>)[key] = relatedEntities.map(e => ({
-                                id: e.id,
-                                path: e.path,
-                                __type: "relation",
-                                data: e
-                            }));
-                        } catch (e) {
-                            console.warn(`Could not resolve many relation property: ${key}`, e);
-                        }
-                    });
-                await Promise.all(manyRelationQueries);
-            });
+            // Batch load many-cardinality relations (1 query per relation type
+            // instead of N queries per entity)
+            const manyRelations = Object.entries(resolvedRelations)
+                .filter(([key, relation]) => propertyKeys.has(key) && relation.cardinality === "many");
+
+            for (const [key, relation] of manyRelations) {
+                try {
+                    const entityIds = entitiesWithValues.map(item => item.entity[idInfo.fieldName] as string | number);
+                    const relationResults = await this.relationService.batchFetchRelatedEntitiesMany(
+                        collectionPath,
+                        entityIds,
+                        key,
+                        relation
+                    );
 
-            await Promise.all(manyRelationPromises);
+                    entitiesWithValues.forEach(item => {
+                        const entityId = String(item.entity[idInfo.fieldName]);
+                        const relatedEntities = relationResults.get(entityId) || [];
+                        (item.values as Record<string, unknown>)[key] = relatedEntities.map(e =>
+                            createRelationRefWithData(e.id, e.path, e)
+                        );
+                    });
+                } catch (e) {
+                    console.warn(`Could not batch load many relation property: ${key}`, e);
+                }
+            }
         }
 
         return entitiesWithValues.map(item => ({
@@ -822,13 +900,14 @@ export class EntityFetchService {
     /**
      * Fetch a collection of entities
      */
-    async fetchCollection<M extends Record<string, any>>(
+    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;
@@ -845,7 +924,7 @@ export class EntityFetchService {
     /**
      * Search entities by text
      */
-    async searchEntities<M extends Record<string, any>>(
+    async searchEntities<M extends Record<string, unknown>>(
         collectionPath: string,
         searchString: string,
         options: {
@@ -865,7 +944,7 @@ export class EntityFetchService {
     /**
      * Fetch collection from multi-segment path
      */
-    private async fetchCollectionFromPath<M extends Record<string, any>>(
+    private async fetchCollectionFromPath<M extends Record<string, unknown>>(
         path: string,
         options: {
             filter?: FilterValues<Extract<keyof M, string>>;
@@ -889,20 +968,27 @@ export class EntityFetchService {
 
         for (let i = 2; i < pathSegments.length; i += 2) {
             const relationKey = pathSegments[i];
-            const resolvedRelations = resolveCollectionRelations(currentCollection as import("@rebasepro/types").PostgresCollection<any, any>);
-            const relation = resolvedRelations[relationKey];
+            const resolvedRelations = resolveCollectionRelations(currentCollection);
+            const relation = findRelation(resolvedRelations, relationKey);
 
             if (!relation) {
                 throw new Error(`Relation '${relationKey}' not found in collection '${currentCollection.slug}'`);
             }
 
             if (i === pathSegments.length - 1) {
-                return this.relationService.fetchRelatedEntities<M>(
+                const entities = await this.relationService.fetchRelatedEntities<M>(
                     currentCollection.slug,
                     currentEntityId,
                     relationKey,
                     options
                 );
+                // Remap entity paths to use the full subcollection path (e.g., "authors/19/posts")
+                // instead of just the target collection slug ("posts"). This ensures
+                // delete/update operations use the correct path for WebSocket notification matching.
+                for (const entity of entities) {
+                    entity.path = path;
+                }
+                return entities;
             }
 
             if (i + 1 < pathSegments.length) {
@@ -918,10 +1004,11 @@ export class EntityFetchService {
     /**
      * Count entities in a collection
      */
-    async countEntities<M extends Record<string, any>>(
+    async countEntities<M extends Record<string, unknown>>(
         collectionPath: string,
         options: {
             filter?: FilterValues<Extract<keyof M, string>>;
+            searchString?: string;
             databaseId?: string;
         } = {}
     ): Promise<number> {
@@ -933,12 +1020,24 @@ export class EntityFetchService {
         const table = getTableForCollection(collection, this.registry);
 
         let query = this.db.select({ count: count() }).from(table).$dynamic();
+        const allConditions: SQL[] = [];
+
+        if (options.searchString) {
+            const searchConditions = DrizzleConditionBuilder.buildSearchConditions(
+                options.searchString, collection.properties, table
+            );
+            if (searchConditions.length === 0) return 0;
+            allConditions.push(DrizzleConditionBuilder.combineConditionsWithOr(searchConditions)!);
+        }
 
         if (options.filter) {
             const filterConditions = this.buildFilterConditions(options.filter, table, collectionPath);
-            if (filterConditions.length > 0) {
-                query = query.where(and(...filterConditions));
-            }
+            if (filterConditions.length > 0) allConditions.push(...filterConditions);
+        }
+
+        if (allConditions.length > 0) {
+            const finalCondition = DrizzleConditionBuilder.combineConditionsWithAnd(allConditions);
+            if (finalCondition) query = query.where(finalCondition);
         }
 
         const result = await query;
@@ -948,7 +1047,7 @@ export class EntityFetchService {
     /**
      * Count entities from multi-segment path
      */
-    private async countEntitiesFromPath<M extends Record<string, any>>(
+    private async countEntitiesFromPath<M extends Record<string, unknown>>(
         path: string,
         options: { filter?: FilterValues<Extract<keyof M, string>>; databaseId?: string } = {}
     ): Promise<number> {
@@ -964,8 +1063,8 @@ export class EntityFetchService {
 
         for (let i = 2; i < pathSegments.length; i += 2) {
             const relationKey = pathSegments[i];
-            const resolvedRelations = resolveCollectionRelations(currentCollection as import("@rebasepro/types").PostgresCollection<any, any>);
-            const relation = resolvedRelations[relationKey];
+            const resolvedRelations = resolveCollectionRelations(currentCollection);
+            const relation = findRelation(resolvedRelations, relationKey);
 
             if (!relation) {
                 throw new Error(`Relation '${relationKey}' not found`);
@@ -1046,13 +1145,14 @@ export class EntityFetchService {
      *
      * @param include - Array of relation keys to populate, or ["*"] for all
      */
-    async fetchCollectionForRest<M extends Record<string, any>>(
+    async fetchCollectionForRest<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;
@@ -1066,11 +1166,14 @@ export class EntityFetchService {
         const idField = table[idInfo.fieldName as keyof typeof table] as AnyPgColumn;
 
         // Primary path: use db.query.findMany
-        
+        // NOTE: Skip db.query path when searchString is present because
+        // Drizzle's relational query API doesn't properly apply raw SQL
+        // ILIKE conditions — the fallback db.select path handles them correctly.
+
         const tableName = getTableName(table);
 
         const qb = this.getQueryBuilder(tableName);
-        if (qb) {
+        if (qb && !options.searchString) {
             try {
                 const withConfig = (include && include.length > 0)
                     ? this.buildWithConfig(collection, include)
@@ -1080,12 +1183,17 @@ export class EntityFetchService {
                     table, idField, idInfo, options, collectionPath, withConfig
                 );
 
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- dynamic query config
+
                 const results = await qb.findMany(queryOpts as unknown as Parameters<NonNullable<typeof qb>["findMany"]>[0]);
 
-                return (results as Record<string, unknown>[]).map(row =>
+                const restRows = (results as Record<string, unknown>[]).map(row =>
                     this.drizzleResultToRestRow(row, collection, idInfo, idInfoArray)
                 );
+
+                // Drizzle relational query API doesn't resolve joinPath relations, fetch manually
+                await this.resolveJoinPathRelationsBatchRest(restRows, collection, collectionPath, idInfoArray, include);
+
+                return restRows;
             } catch (e) {
                 console.warn(`[fetchCollectionForRest] db.query.findMany failed for ${collectionPath}, falling back:`, e);
             }
@@ -1096,13 +1204,13 @@ export class EntityFetchService {
 
         if (!include || include.length === 0) {
             return entities.map(entity => ({
-                id: (idInfoArray.length > 1) ? buildCompositeId(entity as Record<string, any>, idInfoArray) : String(entity[idInfo.fieldName]),
+                id: (idInfoArray.length > 1) ? buildCompositeId(entity as Record<string, unknown>, idInfoArray) : String(entity[idInfo.fieldName]),
                 ...entity
             }));
         }
 
         // Fallback relation loading via batch
-        const resolvedRelations = resolveCollectionRelations(collection as import("@rebasepro/types").PostgresCollection<any, any>);
+        const resolvedRelations = resolveCollectionRelations(collection);
         const propertyKeys = new Set(Object.keys(collection.properties || {}));
         const shouldInclude = (key: string) =>
             include[0] === "*" || include.includes(key);
@@ -1117,9 +1225,10 @@ export class EntityFetchService {
                 );
                 for (const entity of entities) {
                     const eid = entity[idInfo.fieldName] as string | number;
-                    const related = batchResults.get(eid);
+                    const related = batchResults.get(String(eid));
                     if (related) {
-                        (entity as Record<string, unknown>)[key] = { id: related.id, ...related.values };
+                        (entity as Record<string, unknown>)[key] = { id: related.id,
+...related.values };
                     }
                 }
             } catch (e) {
@@ -1137,7 +1246,8 @@ export class EntityFetchService {
                     const eid = entity[idInfo.fieldName] as string | number;
                     const relatedList = batchResults.get(String(eid)) || [];
                     (entity as Record<string, unknown>)[key] = relatedList.map(e => ({
-                        id: e.id, ...e.values
+                        id: e.id,
+...e.values
                     }));
                 }
             } catch (e) {
@@ -1146,7 +1256,7 @@ export class EntityFetchService {
         }
 
         return entities.map(entity => ({
-            id: (idInfoArray.length > 1) ? buildCompositeId(entity as Record<string, any>, idInfoArray) : String(entity[idInfo.fieldName]),
+            id: (idInfoArray.length > 1) ? buildCompositeId(entity as Record<string, unknown>, idInfoArray) : String(entity[idInfo.fieldName]),
             ...entity
         }));
     }
@@ -1154,7 +1264,7 @@ export class EntityFetchService {
     /**
      * Fetch a single entity with optional relation includes for REST API.
      */
-    async fetchEntityForRest<M extends Record<string, any>>(
+    async fetchEntityForRest<M extends Record<string, unknown>>(
         collectionPath: string,
         entityId: string | number,
         include?: string[],
@@ -1170,7 +1280,7 @@ export class EntityFetchService {
         const parsedId = parsedIdObj[idInfo.fieldName];
 
         // Primary path: use db.query.findFirst
-        
+
         const tableName = getTableName(table);
 
         const qb = this.getQueryBuilder(tableName);
@@ -1180,7 +1290,7 @@ export class EntityFetchService {
                     ? this.buildWithConfig(collection, include)
                     : undefined;
 
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- dynamic query config
+
                 const row = await qb.findFirst({
                     where: eq(idField, parsedId),
                     ...(withConfig ? { with: withConfig } : {})
@@ -1188,7 +1298,12 @@ export class EntityFetchService {
 
                 if (!row) return null;
 
-                return this.drizzleResultToRestRow(row, collection, idInfo, idInfoArray);
+                const restRow = this.drizzleResultToRestRow(row, collection, idInfo, idInfoArray);
+
+                // Drizzle relational query API doesn't resolve joinPath relations, fetch manually
+                await this.resolveJoinPathRelationsBatchRest([restRow], collection, collectionPath, idInfoArray, include);
+
+                return restRow;
             } catch (e) {
                 console.warn(`[fetchEntityForRest] db.query.findFirst failed for ${collectionPath}, falling back:`, e);
             }
@@ -1204,14 +1319,15 @@ export class EntityFetchService {
         if (result.length === 0) return null;
 
         const raw = result[0] as Record<string, unknown>;
-        const flatEntity: Record<string, unknown> = { id: (idInfoArray.length > 1) ? buildCompositeId(raw as Record<string, any>, idInfoArray) : String(raw[idInfo.fieldName]), ...raw };
+        const flatEntity: Record<string, unknown> = { id: (idInfoArray.length > 1) ? buildCompositeId(raw as Record<string, unknown>, idInfoArray) : String(raw[idInfo.fieldName]),
+...raw };
 
         if (!include || include.length === 0) {
             return flatEntity;
         }
 
         // Fallback relation population
-        const resolvedRelations = resolveCollectionRelations(collection as import("@rebasepro/types").PostgresCollection<any, any>);
+        const resolvedRelations = resolveCollectionRelations(collection);
         const propertyKeys = new Set(Object.keys(collection.properties || {}));
         const shouldInclude = (key: string) =>
             include[0] === "*" || include.includes(key);
@@ -1227,11 +1343,13 @@ export class EntityFetchService {
                 if (relation.cardinality === "one") {
                     if (relatedEntities.length > 0) {
                         const e = relatedEntities[0];
-                        flatEntity[key] = { id: e.id, ...e.values };
+                        flatEntity[key] = { id: e.id,
+...e.values };
                     }
                 } else {
                     flatEntity[key] = relatedEntities.map(e => ({
-                        id: e.id, ...e.values
+                        id: e.id,
+...e.values
                     }));
                 }
             } catch (e) {
@@ -1245,13 +1363,14 @@ export class EntityFetchService {
     /**
      * Fetch raw rows without any relation processing (for REST fast path)
      */
-    private async fetchEntitiesWithConditionsRaw<M extends Record<string, any>>(
+    private async fetchEntitiesWithConditionsRaw<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;
         } = {}
@@ -1285,7 +1404,7 @@ export class EntityFetchService {
 
         const orderExpressions = [];
         if (options.orderBy) {
-            const orderByField = table[options.orderBy as keyof typeof table] as AnyPgColumn;
+            const orderByField = this.resolveOrderByField(table, options.orderBy, collection);
             if (orderByField) {
                 orderExpressions.push(options.order === "asc" ? asc(orderByField) : desc(orderByField));
             }
@@ -1296,6 +1415,9 @@ export class EntityFetchService {
         const limitValue = 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>[];
     }
 
@@ -1305,7 +1427,7 @@ export class EntityFetchService {
      * Note: Primary path now uses inline `getQueryBuilder()` checks.
      */
     private hasDrizzleQueryAPI(collectionPath: string): boolean {
-        
+
         const qb = this.getQueryBuilder("__probe__");
         if (!qb) {
             // If getQueryBuilder returns undefined even for a probe, query API is not available
@@ -1323,7 +1445,7 @@ export class EntityFetchService {
      * Returns null if the API is not available or the query fails.
      * Note: Primary path now uses `buildWithConfig` + `buildDrizzleQueryOptions`.
      */
-    private async fetchWithDrizzleQuery<M extends Record<string, any>>(
+    private async fetchWithDrizzleQuery<M extends Record<string, unknown>>(
         collectionPath: string,
         collection: EntityCollection,
         options: {
@@ -1337,7 +1459,7 @@ export class EntityFetchService {
         idInfoArray?: { fieldName: string; type: "string" | "number" }[]
     ): Promise<Record<string, unknown>[] | null> {
         try {
-            
+
             const table = getTableForCollection(collection, this.registry);
             const tableName = getTableName(table);
             const queryTarget = this.getQueryBuilder(tableName);
@@ -1345,7 +1467,7 @@ export class EntityFetchService {
             if (!queryTarget?.findMany) return null;
 
             // Build the `with` config from include array
-            const resolvedRelations = resolveCollectionRelations(collection as import("@rebasepro/types").PostgresCollection<any, any>);
+            const resolvedRelations = resolveCollectionRelations(collection);
             const withConfig: Record<string, boolean> = {};
             for (const [key, relation] of Object.entries(resolvedRelations)) {
                 if (include[0] === "*" || include.includes(key)) {
@@ -1371,18 +1493,18 @@ export class EntityFetchService {
 
             // Build orderBy
             if (options.orderBy) {
-                const orderByField = table[options.orderBy as keyof typeof table] as AnyPgColumn;
+                const orderByField = this.resolveOrderByField(table, options.orderBy, collection);
                 if (orderByField) {
                     queryOpts.orderBy = options.order === "asc" ? asc(orderByField) : desc(orderByField);
                 }
             }
 
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- deprecated method, will be removed
+
             const results = await queryTarget.findMany(queryOpts as unknown as Parameters<NonNullable<typeof queryTarget>["findMany"]>[0]);
 
             // Flatten the nested Drizzle results into REST format
             return results.map((row: Record<string, unknown>) => {
-                const flat: Record<string, unknown> = { id: (idInfoArray && idInfoArray.length > 1) ? buildCompositeId(row as Record<string, any>, idInfoArray) : String(row[idInfo.fieldName]) };
+                const flat: Record<string, unknown> = { id: (idInfoArray && idInfoArray.length > 1) ? buildCompositeId(row as Record<string, unknown>, idInfoArray) : String(row[idInfo.fieldName]) };
                 for (const [k, v] of Object.entries(row)) {
                     if (k === idInfo.fieldName) continue;
                     if (Array.isArray(v)) {
@@ -1394,14 +1516,17 @@ export class EntityFetchService {
                             const nestedObj = keys.find(nk => typeof item[nk] === "object" && item[nk] !== null && !Array.isArray(item[nk]));
                             if (nestedObj && keys.length <= 3) {
                                 const nested = item[nestedObj] as Record<string, unknown>;
-                                return { id: String(nested.id ?? nested[Object.keys(nested)[0]]), ...nested };
+                                return { id: String(nested.id ?? nested[Object.keys(nested)[0]]),
+...nested };
                             }
-                            return { id: String(item.id ?? item[Object.keys(item)[0]]), ...item };
+                            return { id: String(item.id ?? item[Object.keys(item)[0]]),
+...item };
                         });
                     } else if (typeof v === "object" && v !== null) {
                         // One-to-one relation — inline the object
                         const relObj = v as Record<string, unknown>;
-                        flat[k] = { id: String(relObj.id ?? relObj[Object.keys(relObj)[0]]), ...relObj };
+                        flat[k] = { id: String(relObj.id ?? relObj[Object.keys(relObj)[0]]),
+...relObj };
                     } else {
                         flat[k] = v;
                     }
@@ -1427,21 +1552,25 @@ export class EntityFetchService {
         parentIds: (string | number)[],
         relationKey: string
     ): Promise<Map<string, Entity[]>> {
-        const resultMap = new Map<string, Entity[]>();
+        if (parentIds.length === 0) return new Map();
 
-        // Fetch for all parents using Promise.all (limited batch)
-        const batchPromises = parentIds.map(async (parentId) => {
-            try {
-                const related = await this.relationService.fetchRelatedEntities(
-                    parentCollectionPath, parentId, relationKey, {}
-                );
-                resultMap.set(String(parentId), related);
-            } catch (e) {
-                resultMap.set(String(parentId), []);
-            }
-        });
+        // Resolve the relation definition so we can use the true batch method
+        const collection = getCollectionByPath(parentCollectionPath, this.registry);
+        const resolvedRelations = resolveCollectionRelations(collection);
+        const relation = resolvedRelations[relationKey];
+
+        if (!relation) {
+            console.warn(`[batchFetchManyRelatedEntities] Relation '${relationKey}' not found, skipping`);
+            return new Map();
+        }
 
-        await Promise.all(batchPromises);
-        return resultMap;
+        // Delegate to RelationService.batchFetchRelatedEntitiesMany which
+        // uses a single SQL query with IN(...) — O(1) instead of O(N).
+        return this.relationService.batchFetchRelatedEntitiesMany(
+            parentCollectionPath,
+            parentIds,
+            relationKey,
+            relation
+        );
     }
 }