@rebasepro/server-core 0.7.0 → 0.9.0

package/src/api/rest/api-generator.ts

@@ -1,747 +0,0 @@
-import { Hono } from "hono";
-import { AuthAdapter, DataDriver, Entity, EntityCollection, FetchCollectionProps, DataHooks, BackendHookContext, RestFetchService } from "@rebasepro/types";
-import { QueryOptions, HonoEnv } from "../types";
-import { ApiError, isRebaseApiError } from "../errors";
-import { parseQueryOptions } from "./query-parser";
-import { httpMethodToOperation, isOperationAllowed } from "../../auth/api-keys/api-key-permission-guard";
-import type { ApiKeyMasked } from "../../auth/api-keys/api-key-types";
-import { logger } from "../../utils/logger";
-
-
-/**
- * Lightweight REST API generator that leverages existing Rebase DataDriver.
- * Supports `include` query parameter for eager-loading relations via Drizzle.
- */
-export class RestApiGenerator {
-    private collections: EntityCollection[];
-    private router: Hono<HonoEnv>;
-    private driver: DataDriver;
-    private dataHooks?: DataHooks;
-    private authAdapter?: AuthAdapter;
-
-    constructor(
-        collections: EntityCollection[],
-        driver: DataDriver,
-        dataHooks?: DataHooks,
-        authAdapter?: AuthAdapter
-    ) {
-        this.collections = collections;
-        this.driver = driver;
-        this.dataHooks = dataHooks;
-        this.authAdapter = authAdapter;
-        this.router = new Hono<HonoEnv>();
-    }
-
-    /** Build a BackendHookContext from a Hono context */
-    private buildHookContext(c: { get: (key: string) => unknown }, method: BackendHookContext["method"]): BackendHookContext {
-        const user = c.get("user") as { userId: string; roles?: string[] } | undefined;
-        return {
-            requestUser: user ? { userId: user.userId,
-roles: user.roles ?? [] } : undefined,
-            method
-        };
-    }
-
-    /**
-     * Generate REST routes using existing DataDriver
-     */
-    generateRoutes(): Hono<HonoEnv> {
-        this.collections.forEach(collection => {
-            this.createCollectionRoutes(collection);
-        });
-
-        // Catch-all routes for subcollection paths like
-        // /authors/111094/posts  and  /authors/111094/posts/43
-        // The DataDriver already knows how to resolve nested relation paths.
-        this.createSubcollectionRoutes();
-
-        return this.router;
-    }
-
-    /**
-     * Check API key permissions for a collection operation.
-     * Throws 403 if the key doesn't have the required permission.
-     * No-ops if the request is not authenticated via an API key.
-     */
-    private enforceApiKeyPermission(
-        c: { get: (key: string) => unknown; req: { method: string } },
-        collectionSlug: string
-    ): void {
-        const apiKey = c.get("apiKey") as ApiKeyMasked | undefined;
-        if (!apiKey) return; // Not an API key request — skip
-
-        const operation = httpMethodToOperation(c.req.method);
-        if (!isOperationAllowed(apiKey.permissions, collectionSlug, operation)) {
-            throw ApiError.forbidden(
-                `API key does not have "${operation}" permission for collection "${collectionSlug}"`,
-                "API_KEY_FORBIDDEN"
-            );
-        }
-    }
-
-    /**
-     * Get the request-scoped driver. Throws if none is set — never falls
-     * back to the unscoped `this.driver` to avoid bypassing RLS/auth.
-     */
-    private getScopedDriver(c: { get: (key: string) => unknown }): DataDriver {
-        const driver = c.get("driver") as DataDriver | undefined;
-        if (!driver) throw ApiError.internal("Scoped driver not available");
-        return driver;
-    }
-
-    /**
-     * Get the typed RestFetchService from a driver if it exposes one (for include support).
-     */
-    private getFetchService(driver: DataDriver): RestFetchService | undefined {
-        return driver.restFetchService;
-    }
-
-    /**
-     * Create REST routes for a collection using existing Rebase patterns
-     */
-    private createCollectionRoutes(collection: EntityCollection): void {
-        const basePath = `/${collection.slug}`;
-        const resolvedCollection = collection;
-
-        // GET /collection/count - Count entities (with optional filters)
-        this.router.get(`${basePath}/count`, async (c) => {
-            this.enforceApiKeyPermission(c, collection.slug);
-            const queryDict = c.req.queries();
-            const queryOptions = parseQueryOptions(queryDict);
-            const searchString = Array.isArray(queryDict.searchString) ? queryDict.searchString[queryDict.searchString.length - 1] : undefined;
-            const driver = this.getScopedDriver(c);
-
-            const total = await this.countRawEntities(driver, resolvedCollection, queryOptions, searchString);
-            return c.json({ count: total });
-        });
-
-        // GET /collection - List entities
-        this.router.get(basePath, async (c) => {
-            this.enforceApiKeyPermission(c, collection.slug);
-            const queryDict = c.req.queries();
-            const queryOptions = parseQueryOptions(queryDict);
-            const searchString = Array.isArray(queryDict.searchString) ? queryDict.searchString[queryDict.searchString.length - 1] : undefined;
-
-            const driver = this.getScopedDriver(c);
-            const fetchService = this.getFetchService(driver);
-            const hookCtx = this.buildHookContext(c, "GET");
-
-            // Use include-aware path when available
-            if (fetchService) {
-                const collectionPath = collection.slug;
-                let entities = await fetchService.fetchCollectionForRest(
-                    collectionPath,
-                    {
-                        filter: queryOptions.where as FetchCollectionProps["filter"],
-                        limit: queryOptions.limit,
-                        offset: queryOptions.offset,
-                        orderBy: queryOptions.orderBy?.[0]?.field,
-                        order: queryOptions.orderBy?.[0]?.direction === "desc" ? "desc" : "asc",
-                        searchString,
-                        vectorSearch: queryOptions.vectorSearch
-                    },
-                    queryOptions.include
-                );
-
-                entities = await this.applyAfterReadBatch(collection.slug, entities, hookCtx);
-
-                const total = await this.countRawEntities(driver, resolvedCollection, queryOptions, searchString);
-
-                return c.json({
-                    data: entities,
-                    meta: {
-                        total,
-                        limit: queryOptions.limit,
-                        offset: queryOptions.offset,
-                        hasMore: (queryOptions.offset || 0) + entities.length < total
-                    }
-                });
-            }
-
-            // Fallback path
-            let entities = await this.fetchRawCollection(driver, resolvedCollection, queryOptions, searchString);
-
-            entities = await this.applyAfterReadBatch(collection.slug, entities, hookCtx);
-
-            const total = await this.countRawEntities(driver, resolvedCollection, queryOptions, searchString);
-
-            return c.json({
-                data: entities,
-                meta: {
-                    total,
-                    limit: queryOptions.limit,
-                    offset: queryOptions.offset,
-                    hasMore: (queryOptions.offset || 0) + entities.length < total
-                }
-            });
-        });
-
-        // GET /collection/:id - Get single entity
-        this.router.get(`${basePath}/:id`, async (c) => {
-            this.enforceApiKeyPermission(c, collection.slug);
-            const id = c.req.param("id");
-            const queryDict = c.req.queries();
-            const queryOptions = parseQueryOptions(queryDict);
-            const driver = this.getScopedDriver(c);
-            const fetchService = this.getFetchService(driver);
-            const hookCtx = this.buildHookContext(c, "GET");
-
-            // Use include-aware path when available
-            if (fetchService) {
-                const collectionPath = collection.slug;
-                let entity = await fetchService.fetchEntityForRest(
-                    collectionPath,
-                    String(id),
-                    queryOptions.include
-                );
-
-                if (!entity) {
-                    throw ApiError.notFound("Entity not found");
-                }
-
-                entity = await this.applyAfterRead(collection.slug, entity, hookCtx);
-                if (!entity) {
-                    throw ApiError.notFound("Entity not found");
-                }
-
-                return c.json(entity);
-            }
-
-            // Fallback
-            let entity = await this.fetchRawEntity(driver, resolvedCollection, String(id));
-
-            if (!entity) {
-                throw ApiError.notFound("Entity not found");
-            }
-
-            entity = await this.applyAfterRead(collection.slug, entity, hookCtx);
-            if (!entity) {
-                throw ApiError.notFound("Entity not found");
-            }
-
-            return c.json(entity);
-        });
-
-        // POST /collection - Create entity
-        this.router.post(basePath, async (c) => {
-            try {
-                this.enforceApiKeyPermission(c, collection.slug);
-                const driver = this.getScopedDriver(c);
-                const path = collection.slug;
-                const hookCtx = this.buildHookContext(c, "POST");
-
-                let body = await c.req.json().catch(() => ({}));
-
-                if (this.dataHooks?.beforeSave) {
-                    body = await this.dataHooks.beforeSave(path, body, undefined, hookCtx);
-                }
-
-                const isAuth = collection.auth;
-                const isAuthCollection = isAuth === true || (isAuth && typeof isAuth === "object" && isAuth.enabled === true);
-
-                if (isAuthCollection && this.authAdapter?.prepareUserCreation) {
-                    const collectionAuthConfig = typeof isAuth === "object" ? isAuth : undefined;
-                    const prepared = await this.authAdapter.prepareUserCreation(body, collectionAuthConfig);
-
-                    const entity = await driver.saveEntity({
-                        path,
-                        values: prepared.values,
-                        collection: resolvedCollection,
-                        status: "new"
-                    });
-
-                    const result = prepared.hookHandledEmail
-                        ? { temporaryPassword: prepared.clearPassword,
-invitationSent: prepared.invitationSent }
-                        : this.authAdapter.finalizeUserCreation
-                            ? await this.authAdapter.finalizeUserCreation(
-                                { id: entity.id as string,
-values: entity.values as Record<string, unknown> },
-                                prepared.clearPassword
-                            )
-                            : { invitationSent: false };
-
-                    const response = this.formatResponse(entity) as Record<string, unknown>;
-
-                    if (this.dataHooks?.afterSave) {
-                        Promise.resolve(this.dataHooks.afterSave(path, response, hookCtx)).catch(err => {
-                            logger.error("[BackendHooks] data.afterSave error", { error: err instanceof Error ? err.message : err });
-                        });
-                    }
-
-                    return c.json({
-                        ...response,
-                        invitationSent: result.invitationSent,
-                        ...(result.temporaryPassword ? { temporaryPassword: result.temporaryPassword } : {})
-                    }, 201);
-                }
-
-                const entity = await driver.saveEntity({
-                    path,
-                    values: body,
-                    collection: resolvedCollection,
-                    status: "new"
-                });
-
-                const response = this.formatResponse(entity);
-
-                if (this.dataHooks?.afterSave) {
-                    Promise.resolve(this.dataHooks.afterSave(path, response as Record<string, unknown>, hookCtx)).catch(err => {
-                        logger.error("[BackendHooks] data.afterSave error", { error: err instanceof Error ? err.message : err });
-                    });
-                }
-
-                return c.json(response, 201);
-            } catch (error) {
-                if (isRebaseApiError(error) && !error.code) {
-                    // Only classify as BAD_REQUEST if it's an operational error
-                    // (e.g. validation, DB constraints). Runtime bugs like TypeError,
-                    // RangeError etc. should remain as 500 INTERNAL_ERROR.
-                    const isRuntimeBug = error instanceof TypeError
-                        || error instanceof RangeError
-                        || error instanceof SyntaxError
-                        || error instanceof ReferenceError;
-                    if (!isRuntimeBug) {
-                        error.code = "BAD_REQUEST";
-                    }
-                }
-                throw error;
-            }
-        });
-
-        // PUT /collection/:id - Update entity
-        this.router.put(`${basePath}/:id`, async (c) => {
-            try {
-                this.enforceApiKeyPermission(c, collection.slug);
-                const id = c.req.param("id");
-                const driver = this.getScopedDriver(c);
-                const hookCtx = this.buildHookContext(c, "PUT");
-
-                const existingEntity = await driver.fetchEntity({
-                    path: collection.slug,
-                    entityId: String(id),
-                    collection: resolvedCollection
-                });
-
-                if (!existingEntity) {
-                    throw ApiError.notFound("Entity not found");
-                }
-
-                let body = await c.req.json().catch(() => ({}));
-
-                if (this.dataHooks?.beforeSave) {
-                    body = await this.dataHooks.beforeSave(collection.slug, body, String(id), hookCtx);
-                }
-
-                const entity = await driver.saveEntity({
-                    path: collection.slug,
-                    entityId: String(id),
-                    values: body,
-                    collection: resolvedCollection,
-                    status: "existing"
-                });
-
-                const response = this.formatResponse(entity);
-
-                if (this.dataHooks?.afterSave) {
-                    Promise.resolve(this.dataHooks.afterSave(collection.slug, response as Record<string, unknown>, hookCtx)).catch(err => {
-                        logger.error("[BackendHooks] data.afterSave error", { error: err instanceof Error ? err.message : err });
-                    });
-                }
-
-                return c.json(response);
-            } catch (error) {
-                if (isRebaseApiError(error) && !error.code) {
-                    // Only classify as BAD_REQUEST if it's an operational error.
-                    // Runtime bugs (TypeError, RangeError, etc.) stay as 500.
-                    const isRuntimeBug = error instanceof TypeError
-                        || error instanceof RangeError
-                        || error instanceof SyntaxError
-                        || error instanceof ReferenceError;
-                    if (!isRuntimeBug) {
-                        error.code = "BAD_REQUEST";
-                    }
-                }
-                throw error;
-            }
-        });
-
-        // DELETE /collection/:id - Delete entity
-        this.router.delete(`${basePath}/:id`, async (c) => {
-            this.enforceApiKeyPermission(c, collection.slug);
-            const id = c.req.param("id");
-            const driver = this.getScopedDriver(c);
-            const hookCtx = this.buildHookContext(c, "DELETE");
-
-            const existingEntity = await driver.fetchEntity({
-                path: collection.slug,
-                entityId: String(id),
-                collection: resolvedCollection
-            });
-
-            if (!existingEntity) {
-                throw ApiError.notFound("Entity not found");
-            }
-
-            if (this.dataHooks?.beforeDelete) {
-                await this.dataHooks.beforeDelete(collection.slug, String(id), hookCtx);
-            }
-
-            await driver.deleteEntity({
-                entity: existingEntity,
-                collection: resolvedCollection
-            });
-
-            if (this.dataHooks?.afterDelete) {
-                Promise.resolve(this.dataHooks.afterDelete(collection.slug, String(id), hookCtx)).catch(err => {
-                    logger.error("[BackendHooks] data.afterDelete error", { error: err instanceof Error ? err.message : err });
-                });
-            }
-
-            return new Response(null, { status: 204 });
-        });
-    }
-
-    /**
-     * Catch-all routes for subcollection paths.
-     *
-     * Matches URL patterns like:
-     *   GET    /authors/111094/posts          → list child collection
-     *   GET    /authors/111094/posts/43       → get child entity
-     *   POST   /authors/111094/posts          → create child entity
-     *   PUT    /authors/111094/posts/43       → update child entity
-     *   DELETE /authors/111094/posts/43       → delete child entity
-     *
-     * The `:rest{.+}` regex param captures the full remainder of the URL
-     * path (Hono v4 `*` wildcard does not populate `c.req.param("*")`).
-     * We split it into segments and reconstruct the `collectionPath`
-     * (e.g. "authors/111094/posts") and optional `entityId` (e.g. "43").
-     *
-     * The DataDriver.saveEntity / fetchCollection / etc. already know how to
-     * resolve multi-segment relation paths, so we just forward to them.
-     */
-    private createSubcollectionRoutes(): void {
-        // Reserved path segments that should NOT be treated as relation names.
-        // These are handled by dedicated route handlers (e.g., history routes)
-        // mounted on the same data router.
-        const RESERVED_SEGMENTS = new Set(["history"]);
-
-        // Helper: parse a path like "authors/111094/posts/43" into
-        // { collectionPath: "authors/111094/posts", entityId: "43" }
-        // or "authors/111094/posts" into
-        // { collectionPath: "authors/111094/posts", entityId: undefined }
-        const parseSubPath = (rawPath: string): { collectionPath: string; entityId?: string } | null => {
-            const segments = rawPath.split("/").filter(s => s && s !== "undefined");
-            // Need at least 3 segments for a subcollection path (parent/id/child)
-            if (segments.length < 3) return null;
-
-            // If any segment is a reserved path (e.g. "history"), this is not a
-            // subcollection route — let it fall through to other handlers.
-            if (segments.some(s => RESERVED_SEGMENTS.has(s))) return null;
-
-            // Odd segment count → collection path (parent/id/child or parent/id/child/id2/grandchild)
-            // Even segment count → entity path   (parent/id/child/entityId)
-            if (segments.length % 2 === 1) {
-                return { collectionPath: segments.join("/") };
-            } else {
-                const entityId = segments.pop()!;
-                return { collectionPath: segments.join("/"),
-entityId };
-            }
-        };
-
-        // GET /<subcollection-path> — list or get single entity
-        // Use :rest{.+} instead of * because Hono v4's wildcard doesn't
-        // capture into c.req.param("*") — it always returns undefined.
-        this.router.get("/:parent/:parentId/:rest{.+}", async (c, next) => {
-            const rest = c.req.param("rest");
-            if (!rest || rest === "undefined") return next();
-            const rawPath = `${c.req.param("parent")}/${c.req.param("parentId")}/${rest}`;
-            const parsed = parseSubPath(rawPath);
-            if (!parsed) return next();
-
-            const driver = this.getScopedDriver(c);
-
-            this.enforceApiKeyPermission(c, c.req.param("parent"));
-
-            const hookCtx = this.buildHookContext(c, "GET");
-
-            if (parsed.entityId === "count") {
-                // GET /parent/:parentId/child/count — count child entities
-                const queryDict = c.req.queries();
-                const queryOptions = parseQueryOptions(queryDict);
-                const searchString = Array.isArray(queryDict.searchString) ? queryDict.searchString[queryDict.searchString.length - 1] : undefined;
-
-                const total = driver.countEntities ? await driver.countEntities({
-                    path: parsed.collectionPath,
-                    filter: queryOptions.where as FetchCollectionProps["filter"],
-                    searchString
-                }) : 0;
-
-                return c.json({ count: total });
-            } else if (parsed.entityId) {
-                // GET /parent/:parentId/child/:id — single entity
-                const entity = await driver.fetchEntity({
-                    path: parsed.collectionPath,
-                    entityId: parsed.entityId
-                });
-                if (!entity) throw ApiError.notFound("Entity not found");
-
-                const flatResult = this.flattenEntity(entity);
-                const hookResult = await this.applyAfterRead(c.req.param("parent"), flatResult, hookCtx);
-                if (!hookResult) throw ApiError.notFound("Entity not found");
-
-                return c.json(hookResult);
-            } else {
-                // GET /parent/:parentId/child — list entities
-                const queryDict = c.req.queries();
-                const queryOptions = parseQueryOptions(queryDict);
-                const searchString = Array.isArray(queryDict.searchString) ? queryDict.searchString[queryDict.searchString.length - 1] : undefined;
-                const entities = await driver.fetchCollection({
-                    path: parsed.collectionPath,
-                    filter: queryOptions.where as FetchCollectionProps["filter"],
-                    limit: queryOptions.limit,
-                    orderBy: queryOptions.orderBy?.[0]?.field,
-                    order: queryOptions.orderBy?.[0]?.direction === "desc" ? "desc" : "asc",
-                    searchString
-                });
-
-                let flatEntities = entities.map(e => this.flattenEntity(e));
-                flatEntities = await this.applyAfterReadBatch(c.req.param("parent"), flatEntities, hookCtx);
-
-                const total = driver.countEntities ? await driver.countEntities({
-                    path: parsed.collectionPath,
-                    filter: queryOptions.where as FetchCollectionProps["filter"],
-                    searchString
-                }) : flatEntities.length;
-
-                return c.json({
-                    data: flatEntities,
-                    meta: {
-                        total,
-                        limit: queryOptions.limit,
-                        offset: queryOptions.offset,
-                        hasMore: (queryOptions.offset || 0) + flatEntities.length < total
-                    }
-                });
-            }
-        });
-
-        // POST /<subcollection-path> — create entity
-        this.router.post("/:parent/:parentId/:rest{.+}", async (c, next) => {
-            const rest = c.req.param("rest");
-            if (!rest || rest === "undefined") return next();
-            const rawPath = `${c.req.param("parent")}/${c.req.param("parentId")}/${rest}`;
-            const parsed = parseSubPath(rawPath);
-            if (!parsed || parsed.entityId) return next();
-
-            const driver = this.getScopedDriver(c);
-            const hookCtx = this.buildHookContext(c, "POST");
-
-            this.enforceApiKeyPermission(c, c.req.param("parent"));
-            let body = await c.req.json().catch(() => ({}));
-
-            if (this.dataHooks?.beforeSave) {
-                body = await this.dataHooks.beforeSave(parsed.collectionPath, body, undefined, hookCtx);
-            }
-
-            const entity = await driver.saveEntity({
-                path: parsed.collectionPath,
-                values: body,
-                status: "new"
-            });
-
-            const response = this.formatResponse(entity);
-
-            if (this.dataHooks?.afterSave) {
-                Promise.resolve(this.dataHooks.afterSave(parsed.collectionPath, response as Record<string, unknown>, hookCtx)).catch(err => {
-                    logger.error("[BackendHooks] data.afterSave error", { error: err instanceof Error ? err.message : err });
-                });
-            }
-
-            return c.json(response, 201);
-        });
-
-        // PUT /<subcollection-path>/:id — update entity
-        this.router.put("/:parent/:parentId/:rest{.+}", async (c, next) => {
-            const rest = c.req.param("rest");
-            if (!rest || rest === "undefined") return next();
-            const rawPath = `${c.req.param("parent")}/${c.req.param("parentId")}/${rest}`;
-            const parsed = parseSubPath(rawPath);
-            if (!parsed || !parsed.entityId) return next();
-
-            const driver = this.getScopedDriver(c);
-            const hookCtx = this.buildHookContext(c, "PUT");
-
-            this.enforceApiKeyPermission(c, c.req.param("parent"));
-
-            let body = await c.req.json().catch(() => ({}));
-
-            if (this.dataHooks?.beforeSave) {
-                body = await this.dataHooks.beforeSave(parsed.collectionPath, body, parsed.entityId, hookCtx);
-            }
-
-            const entity = await driver.saveEntity({
-                path: parsed.collectionPath,
-                entityId: parsed.entityId,
-                values: body,
-                status: "existing"
-            });
-
-            const response = this.formatResponse(entity);
-
-            if (this.dataHooks?.afterSave) {
-                Promise.resolve(this.dataHooks.afterSave(parsed.collectionPath, response as Record<string, unknown>, hookCtx)).catch(err => {
-                    logger.error("[BackendHooks] data.afterSave error", { error: err instanceof Error ? err.message : err });
-                });
-            }
-
-            return c.json(response);
-        });
-
-        // DELETE /<subcollection-path>/:id — delete entity
-        this.router.delete("/:parent/:parentId/:rest{.+}", async (c, next) => {
-            const rest = c.req.param("rest");
-            if (!rest || rest === "undefined") return next();
-            const rawPath = `${c.req.param("parent")}/${c.req.param("parentId")}/${rest}`;
-            const parsed = parseSubPath(rawPath);
-            if (!parsed || !parsed.entityId) return next();
-
-            const driver = this.getScopedDriver(c);
-            const hookCtx = this.buildHookContext(c, "DELETE");
-
-            this.enforceApiKeyPermission(c, c.req.param("parent"));
-
-            const existingEntity = await driver.fetchEntity({
-                path: parsed.collectionPath,
-                entityId: parsed.entityId
-            });
-
-            if (!existingEntity) throw ApiError.notFound("Entity not found");
-
-            if (this.dataHooks?.beforeDelete) {
-                await this.dataHooks.beforeDelete(parsed.collectionPath, parsed.entityId, hookCtx);
-            }
-
-            await driver.deleteEntity({ entity: existingEntity });
-
-            if (this.dataHooks?.afterDelete) {
-                Promise.resolve(this.dataHooks.afterDelete(parsed.collectionPath, parsed.entityId, hookCtx)).catch(err => {
-                    logger.error("[BackendHooks] data.afterDelete error", { error: err instanceof Error ? err.message : err });
-                });
-            }
-
-            return new Response(null, { status: 204 });
-        });
-    }
-
-    /**
-     * Format successful API response - flattened for traditional REST API
-     */
-    private formatResponse<T>(data: T, meta?: Record<string, unknown>): unknown {
-        if (Array.isArray(data)) {
-            const flattenedData = data.map(entity => this.flattenEntity(entity));
-            if (meta) {
-                return {
-                    data: flattenedData,
-                    meta
-                };
-            }
-            return flattenedData;
-        }
-
-        if (data && typeof data === "object" && "values" in data) {
-            return this.flattenEntity(data as unknown as Entity<Record<string, unknown>>);
-        }
-
-        if (meta) {
-            return {
-                data,
-                meta
-            };
-        }
-        return data;
-    }
-
-    /**
-     * Flatten Rebase entity structure to traditional REST format
-     */
-    private flattenEntity(entity: Entity<Record<string, unknown>>): Record<string, unknown> {
-        if (!entity || typeof entity !== "object") {
-            return entity;
-        }
-
-        if ("values" in entity && typeof entity.values === "object") {
-            return {
-                id: entity.id,
-                ...entity.values
-            };
-        }
-
-        return entity as unknown as Record<string, unknown>;
-    }
-
-    /**
-     * Fetch raw collection data without Entity wrapper (fallback for non-Postgres)
-     */
-    private async fetchRawCollection(driver: DataDriver, collection: EntityCollection, queryOptions: QueryOptions, searchString?: string) {
-        const entities = await driver.fetchCollection({
-            path: collection.slug,
-            collection,
-            filter: queryOptions.where as FetchCollectionProps["filter"],
-            limit: queryOptions.limit,
-            orderBy: queryOptions.orderBy?.[0]?.field,
-            order: queryOptions.orderBy?.[0]?.direction === "desc" ? "desc" : "asc",
-            startAfter: queryOptions.offset ? String(queryOptions.offset) : undefined,
-            searchString,
-            vectorSearch: queryOptions.vectorSearch
-        });
-
-        return entities.map(entity => this.flattenEntity(entity));
-    }
-
-    /**
-     * Count raw entities for a collection
-     */
-    private async countRawEntities(driver: DataDriver, collection: EntityCollection, queryOptions: QueryOptions, searchString?: string): Promise<number> {
-        return driver.countEntities ? await driver.countEntities({
-            path: collection.slug,
-            collection,
-            filter: queryOptions.where as FetchCollectionProps["filter"],
-            searchString
-        }) : 0;
-    }
-
-    /**
-     * Fetch single entity raw data without Entity wrapper (fallback)
-     */
-    private async fetchRawEntity(driver: DataDriver, collection: EntityCollection, entityId: string) {
-        const entity = await driver.fetchEntity({
-            path: collection.slug,
-            entityId,
-            collection
-        });
-
-        return entity ? this.flattenEntity(entity) : null;
-    }
-
-    /**
-     * Apply data.afterRead hook to a single entity.
-     * Returns the transformed entity, or null to filter it out.
-     */
-    private async applyAfterRead(slug: string, entity: Record<string, unknown>, ctx: BackendHookContext): Promise<Record<string, unknown> | null> {
-        if (!this.dataHooks?.afterRead) return entity;
-        return this.dataHooks.afterRead(slug, entity, ctx);
-    }
-
-    /**
-     * Apply data.afterRead hook to an array of entities, filtering out nulls.
-     */
-    private async applyAfterReadBatch(slug: string, entities: Record<string, unknown>[], ctx: BackendHookContext): Promise<Record<string, unknown>[]> {
-        if (!this.dataHooks?.afterRead) return entities;
-        const results = await Promise.all(
-            entities.map(e => this.applyAfterRead(slug, e, ctx))
-        );
-        return results.filter((e): e is Record<string, unknown> => e !== null);
-    }
-}