@rebasepro/common 0.8.0 → 0.9.1-canary.09aaf62

package/src/data/buildRebaseData.ts

@@ -1,103 +1,199 @@
 import {
-    DataDriver,
-    RebaseData,
     CollectionAccessor,
-    FindParams,
-    FindResponse,
+    DataDriver,
     Entity,
     EntityValues,
-    WhereFilterOp,
+    FindParams,
+    FindResponse,
+    FindResult,
     LogicalCondition,
+    RebaseData,
+    RebaseSdkData,
+    SDKCollectionClient,
+    SDKQueryBuilderInterface,
+    WhereFilterOp,
     WhereValue
 } from "@rebasepro/types";
 import { toSnakeCase } from "@rebasepro/utils";
 import { QueryBuilder } from "./query_builder";
 import { deserializeFilter } from "./filter-dialect";
+import { buildCompositeId, resolvePrimaryKeys, PrimaryKeyInfo } from "../util/identity";
+
+export interface EntityDataOptions {
+    /**
+     * Look up a collection's config by slug, to derive row addresses from its
+     * primary keys.
+     *
+     * Called lazily rather than up front: the data layer is created by `Rebase`,
+     * which sits *above* the admin that owns the collections, so a resolver
+     * registered on mount would otherwise arrive too late to be seen.
+     */
+    resolveCollection?: (slug: string) => { properties?: Record<string, unknown> } | undefined;
+}
+
+function createPrimaryKeyResolver(options?: EntityDataOptions) {
+    const cache = new Map<string, PrimaryKeyInfo[]>();
+    const warned = new Set<string>();
+
+    return function primaryKeysFor(slug: string): PrimaryKeyInfo[] {
+        const cached = cache.get(slug);
+        if (cached) return cached;
+
+        const collection = options?.resolveCollection?.(slug);
+        if (!collection) {
+            // The registry may not have been registered yet. Don't memoize a
+            // miss, or the collection would stay address-less for this session.
+            return [];
+        }
+
+        const keys = resolvePrimaryKeys(collection);
+        if (keys.length > 0) {
+            // Memoized for the session: a collection's key does not change
+            // while the app runs, and this is called once per row. Editing
+            // `isId` in the schema editor needs a reload to take effect here.
+            cache.set(slug, keys);
+            return keys;
+        }
+
+        if (!warned.has(slug)) {
+            warned.add(slug);
+            // Silence here surfaces much later as rows that cannot be opened,
+            // linked, or saved, with nothing pointing back at the cause.
+            console.warn(
+                `[rebase] Collection '${slug}' declares no primary key, so its rows have no address: ` +
+                `detail links, caching and relations will not work for it. ` +
+                `Mark the key property with \`isId\` in its collection config — the server logs which ` +
+                `column to mark at boot, if its schema knows the key.`
+            );
+        }
+        return keys;
+    };
+}
 
 /**
- * Parse an orderBy string like "created_at:desc" into [field, direction].
+ * Give a flat row the Entity view-model the admin renders.
+ *
+ * The address is *derived here* — it is not a column, and the row it came from
+ * does not contain one. Rows carry exactly what the table has, with the types
+ * Postgres returned; the id is this layer's invention, and this is the only
+ * place it is minted.
+ *
+ * `primaryKeys` empty falls back to a literal `id` on the row: drivers other
+ * than postgres still serve rows with one, and this keeps them working.
  */
-function parseOrderBy(orderBy?: string): [string, "asc" | "desc"] | undefined {
-    if (!orderBy) return undefined;
-    const parts = orderBy.split(":");
-    const field = parts[0];
-    const direction = (parts[1] as "asc" | "desc") || "asc";
-    return [field, direction];
+function rowToEntity<M extends Record<string, unknown>>(
+    row: Record<string, unknown>,
+    slug: string,
+    primaryKeys: PrimaryKeyInfo[] = []
+): Entity<M> {
+    return {
+        id: primaryKeys.length > 0
+            ? buildCompositeId(row, primaryKeys)
+            : row.id as string | number,
+        path: slug,
+        values: row as EntityValues<M>
+    };
 }
 
 function createDriverAccessor<M extends Record<string, unknown> = Record<string, unknown>>(
     driver: DataDriver,
-    slug: string
+    slug: string,
+    getPks: () => PrimaryKeyInfo[] = () => []
 ): CollectionAccessor<M> {
     const accessor: CollectionAccessor<M> = {
         async find(params?: FindParams): Promise<FindResponse<M>> {
-            const orderParsed = parseOrderBy(params?.orderBy);
             // Ensure filters are in canonical [op, value] format even if passed as PostgREST strings
-            const filter = params?.where ? deserializeFilter(params.where as any) : undefined;
-            
-            const entities = await driver.fetchCollection<M>({
-                path: slug,
-                limit: params?.limit,
-                offset: params?.offset,
-                filter,
-                orderBy: orderParsed?.[0],
-                order: orderParsed?.[1],
-                searchString: params?.searchString
-            });
+            const filter = params?.where ? deserializeFilter(params.where as Record<string, unknown>) : undefined;
             const limit = params?.limit ?? 20;
             const offset = params?.offset ?? 0;
+
+            // Use the RestFetchService for include-aware queries when available
+            const fetchService = driver.restFetchService;
+            const rows = (fetchService && params?.include && params.include.length > 0)
+                ? await fetchService.fetchCollectionForRest(
+                    slug,
+                    {
+                        filter,
+                        limit: params?.limit,
+                        offset: params?.offset,
+                        orderBy: params?.orderBy?.[0],
+                        order: params?.orderBy?.[1],
+                        searchString: params?.searchString
+                    },
+                    params.include
+                )
+                : await driver.fetchCollection<M>({
+                    path: slug,
+                    limit: params?.limit,
+                    offset: params?.offset,
+                    filter,
+                    orderBy: params?.orderBy?.[0],
+                    order: params?.orderBy?.[1],
+                    searchString: params?.searchString
+                });
+
+            // Compute real total when count is available
+            let total = rows.length + offset;
+            let hasMore = rows.length >= limit;
+            if (driver.count) {
+                total = await driver.count({ path: slug, filter });
+                hasMore = offset + rows.length < total;
+            }
+
             return {
-                data: entities,
-                meta: {
-                    total: entities.length,
-                    limit,
-                    offset,
-                    hasMore: entities.length >= limit
-                }
+                data: rows.map((row: Record<string, unknown>) => rowToEntity<M>(row, slug, getPks())),
+                meta: { total, limit, offset, hasMore }
             };
         },
 
         async findById(id: string | number): Promise<Entity<M> | undefined> {
-            return driver.fetchEntity<M>({ path: slug,
-entityId: id });
+            const row = await driver.fetchOne<M>({ path: slug, id: id });
+            return row ? rowToEntity<M>(row, slug, getPks()) : undefined;
         },
 
         async create(data: Partial<EntityValues<M>>, id?: string | number): Promise<Entity<M>> {
-            return driver.saveEntity<M>({
+            const row = await driver.save<M>({
                 path: slug,
                 values: data,
-                entityId: id,
+                id: id,
                 status: "new"
             });
+            return rowToEntity<M>(row, slug, getPks());
         },
 
+        createMany: driver.saveMany
+            ? async (data: Partial<EntityValues<M>>[], options?: { upsert?: boolean }): Promise<Entity<M>[]> => {
+                const rows = await driver.saveMany!<M>({
+                    path: slug,
+                    rows: data,
+                    upsert: options?.upsert
+                });
+                return rows.map((row) => rowToEntity<M>(row, slug, getPks()));
+            }
+            : undefined,
+
         async update(id: string | number, data: Partial<EntityValues<M>>): Promise<Entity<M>> {
-            return driver.saveEntity<M>({
+            const row = await driver.save<M>({
                 path: slug,
                 values: data,
-                entityId: id,
+                id: id,
                 status: "existing"
             });
+            return rowToEntity<M>(row, slug, getPks());
         },
 
         async delete(id: string | number): Promise<void> {
-            return driver.deleteEntity({
-                entity: { id,
+            return driver.delete({
+                row: { id,
 path: slug,
 values: {} as Record<string, unknown> }
             });
         },
 
-        deleteAll: driver.deleteAll
-            ? async (): Promise<void> => {
-                return driver.deleteAll!(slug);
-            }
-            : undefined,
-
-        count: driver.countEntities
+        count: driver.count
             ? async (params?: FindParams): Promise<number> => {
-                const filter = params?.where ? deserializeFilter(params.where as any) : undefined;
-                return driver.countEntities!({
+                const filter = params?.where ? deserializeFilter(params.where as Record<string, unknown>) : undefined;
+                return driver.count!({
                     path: slug,
                     filter
                 });
@@ -106,7 +202,6 @@ values: {} as Record<string, unknown> }
 
         listen: driver.listenCollection
             ? (params: FindParams | undefined, onUpdate: (response: FindResponse<M>) => void, onError?: (error: Error) => void) => {
-                const orderParsed = parseOrderBy(params?.orderBy);
                 const limit = params?.limit ?? 20;
                 const offset = params?.offset ?? 0;
                 return driver.listenCollection!<M>({
@@ -114,12 +209,12 @@ values: {} as Record<string, unknown> }
                     limit: params?.limit,
                     offset: params?.offset,
                     filter: params?.where,
-                    orderBy: orderParsed?.[0],
-                    order: orderParsed?.[1],
+                    orderBy: params?.orderBy?.[0],
+                    order: params?.orderBy?.[1],
                     searchString: params?.searchString,
                     onUpdate: (entities) => {
                         onUpdate({
-                            data: entities,
+                            data: entities.map((row: Record<string, unknown>) => rowToEntity<M>(row, slug, getPks())),
                             meta: {
                                 total: entities.length,
                                 limit,
@@ -132,12 +227,12 @@ values: {} as Record<string, unknown> }
                 });
             } : undefined,
 
-        listenById: driver.listenEntity
+        listenById: driver.listenOne
             ? (id: string | number, onUpdate: (entity: Entity<M> | undefined) => void, onError?: (error: Error) => void) => {
-                return driver.listenEntity!<M>({
+                return driver.listenOne!<M>({
                     path: slug,
-                    entityId: id,
-                    onUpdate: (entity) => onUpdate(entity ?? undefined),
+                    id: id,
+                    onUpdate: (entity) => onUpdate(entity ? rowToEntity<M>(entity, slug, getPks()) : undefined),
                     onError
                 });
             } : undefined,
@@ -180,15 +275,16 @@ values: {} as Record<string, unknown> }
  * @example
  * const data = buildRebaseData(driver);
  * await data.products.create({ name: "Camera", price: 299 });
- * const { data: items } = await data.products.find({ where: { status: "eq.published" } });
+ * const { data: items } = await data.products.find({ where: { status: ["==", "published"] } });
  */
-export function buildRebaseData(driver: DataDriver): RebaseData {
+export function buildRebaseData(driver: DataDriver, options?: EntityDataOptions): RebaseData {
     const cache = new Map<string, CollectionAccessor>();
+    const primaryKeysFor = createPrimaryKeyResolver(options);
 
     function getAccessor(slug: string): CollectionAccessor {
         let accessor = cache.get(slug);
         if (!accessor) {
-            accessor = createDriverAccessor(driver, slug);
+            accessor = createDriverAccessor(driver, slug, () => primaryKeysFor(slug));
             cache.set(slug, accessor);
         }
         return accessor;
@@ -212,3 +308,277 @@ export function buildRebaseData(driver: DataDriver): RebaseData {
         }
     });
 }
+
+// =============================================================================
+// SDK data — flat rows (symmetric with the frontend SDK client)
+// =============================================================================
+
+/**
+ * Unwrap a Entity back into the flat row it was built from. `rowToEntity` keeps
+ * the row untouched under `.values` and derives `.id` alongside it, so dropping
+ * the wrapper is the whole operation — the address was never part of the row.
+ */
+function entityToRow<M extends Record<string, unknown>>(entity: Entity<M>): M {
+    return entity.values as unknown as M;
+}
+
+/**
+ * Fluent query builder for the flat SDK data layer. Mirrors {@link QueryBuilder}
+ * but resolves to `FindResult<M>` (flat rows) instead of Entity-wrapped
+ * `FindResponse<M>`.
+ */
+class SdkQueryBuilder<M extends Record<string, unknown> = Record<string, unknown>> implements SDKQueryBuilderInterface<M> {
+    private params: FindParams = { where: {} };
+
+    constructor(private client: SDKCollectionClient<M>) {}
+
+    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
+    where(logicalCondition: LogicalCondition): this;
+    where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown): this {
+        if (typeof columnOrCondition === "object" && columnOrCondition !== null && "type" in columnOrCondition) {
+            this.params.logical = columnOrCondition as LogicalCondition;
+            return this;
+        }
+        if (!this.params.where) this.params.where = {};
+        const column = columnOrCondition as string;
+        const condition: [WhereFilterOp, unknown] = [operator!, value];
+        const existing = this.params.where[column];
+        if (existing === undefined) {
+            this.params.where[column] = condition;
+        } else if (Array.isArray(existing) && existing.length > 0 && Array.isArray(existing[0])) {
+            (this.params.where[column] as [WhereFilterOp, unknown][]).push(condition);
+        } else {
+            let firstCondition: [WhereFilterOp, unknown];
+            if (Array.isArray(existing) && existing.length === 2 && typeof existing[0] === "string") {
+                firstCondition = existing as [WhereFilterOp, unknown];
+            } else {
+                firstCondition = ["==", existing];
+            }
+            this.params.where[column] = [firstCondition, condition];
+        }
+        return this;
+    }
+
+    orderBy(column: keyof M & string, direction: "asc" | "desc" = "asc"): this {
+        this.params.orderBy = [column, direction];
+        return this;
+    }
+
+    limit(count: number): this { this.params.limit = count; return this; }
+    offset(count: number): this { this.params.offset = count; return this; }
+    search(searchString: string): this { this.params.searchString = searchString; return this; }
+    include(...relations: string[]): this { this.params.include = relations; return this; }
+
+    async find(): Promise<FindResult<M>> {
+        return this.client.find(this.params);
+    }
+
+    async count(): Promise<number> {
+        return this.client.count ? this.client.count(this.params) : 0;
+    }
+
+    listen(onUpdate: (data: FindResult<M>) => void, onError?: (error: Error) => void): () => void {
+        if (!this.client.listen) {
+            throw new Error("Listen is only available when the driver supports realtime.");
+        }
+        return this.client.listen(this.params, onUpdate, onError);
+    }
+}
+
+/**
+ * Wrap a Entity-shaped {@link CollectionAccessor} into a flat
+ * {@link SDKCollectionClient}. Every returned record is unwrapped to a flat row
+ * so the backend SDK is byte-for-byte the same shape as the frontend client.
+ */
+function toSdkCollectionClient<M extends Record<string, unknown>>(
+    snap: CollectionAccessor<M>
+): SDKCollectionClient<M> {
+    const client: SDKCollectionClient<M> = {
+        async find(params?: FindParams): Promise<FindResult<M>> {
+            const res = await snap.find(params);
+            return { data: res.data.map(entityToRow), meta: res.meta };
+        },
+        async findById(id: string | number): Promise<M | undefined> {
+            const s = await snap.findById(id);
+            return s ? entityToRow(s) : undefined;
+        },
+        async create(data: Partial<M>, id?: string | number): Promise<M> {
+            return entityToRow(await snap.create(data as Partial<EntityValues<M>>, id));
+        },
+        async createMany(data: Partial<M>[], options?: { upsert?: boolean }): Promise<M[]> {
+            if (!Array.isArray(data)) {
+                throw new TypeError("createMany expects an array of records.");
+            }
+            if (data.length === 0) return [];
+            if (!snap.createMany) {
+                throw new Error(
+                    "Bulk writes are not supported by this collection's data source. " +
+                    "Fall back to create() per record."
+                );
+            }
+            const rows = await snap.createMany(data as Partial<EntityValues<M>>[], options);
+            return rows.map(entityToRow);
+        },
+        async update(id: string | number, data: Partial<M>): Promise<M> {
+            return entityToRow(await snap.update(id, data as Partial<EntityValues<M>>));
+        },
+        delete(id: string | number): Promise<void> {
+            return snap.delete(id);
+        },
+        count: snap.count ? (params?: FindParams) => snap.count!(params) : undefined,
+        listen: snap.listen
+            ? (params: FindParams | undefined, onUpdate: (r: FindResult<M>) => void, onError?: (e: Error) => void) =>
+                snap.listen!(params, (res) => onUpdate({ data: res.data.map(entityToRow), meta: res.meta }), onError)
+            : undefined,
+        listenById: snap.listenById
+            ? (id: string | number, onUpdate: (r: M | undefined) => void, onError?: (e: Error) => void) =>
+                snap.listenById!(id, (s) => onUpdate(s ? entityToRow(s) : undefined), onError)
+            : undefined,
+        where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown) {
+            const builder = new SdkQueryBuilder<M>(client);
+            if (typeof columnOrCondition === "object") {
+                return builder.where(columnOrCondition);
+            }
+            return builder.where(columnOrCondition as keyof M & string, operator!, value as WhereValue<M[keyof M & string]>);
+        },
+        orderBy: (column: keyof M & string, direction?: "asc" | "desc") => new SdkQueryBuilder<M>(client).orderBy(column, direction),
+        limit: (count: number) => new SdkQueryBuilder<M>(client).limit(count),
+        offset: (count: number) => new SdkQueryBuilder<M>(client).offset(count),
+        search: (searchString: string) => new SdkQueryBuilder<M>(client).search(searchString),
+        include: (...relations: string[]) => new SdkQueryBuilder<M>(client).include(...relations)
+    };
+    return client;
+}
+
+/**
+ * Wrap a flat {@link SDKCollectionClient} into a Entity-shaped
+ * {@link CollectionAccessor}. Every returned row is re-wrapped into the
+ * `{ id, path, values }` view-model the admin CMS renders.
+ */
+function toEntityAccessor<M extends Record<string, unknown>>(
+    sdk: SDKCollectionClient<M>,
+    slug: string,
+    getPks: () => PrimaryKeyInfo[] = () => []
+): CollectionAccessor<M> {
+    const accessor: CollectionAccessor<M> = {
+        async find(params?: FindParams): Promise<FindResponse<M>> {
+            const res = await sdk.find(params);
+            return { data: res.data.map((row) => rowToEntity<M>(row, slug, getPks())), meta: res.meta };
+        },
+        async findById(id: string | number): Promise<Entity<M> | undefined> {
+            const row = await sdk.findById(id);
+            return row ? rowToEntity<M>(row, slug, getPks()) : undefined;
+        },
+        async create(data: Partial<EntityValues<M>>, id?: string | number): Promise<Entity<M>> {
+            return rowToEntity<M>(await sdk.create(data as Partial<M>, id), slug, getPks());
+        },
+        async update(id: string | number, data: Partial<EntityValues<M>>): Promise<Entity<M>> {
+            const row = await sdk.update(id, data as Partial<M>);
+            if (!row) throw new Error(`Update returned no data for id ${id}`);
+            return rowToEntity<M>(row, slug, getPks());
+        },
+        delete(id: string | number): Promise<void> {
+            return sdk.delete(id);
+        },
+        count: sdk.count ? (params?: FindParams) => sdk.count!(params) : undefined,
+        listen: sdk.listen
+            ? (params: FindParams | undefined, onUpdate: (r: FindResponse<M>) => void, onError?: (e: Error) => void) =>
+                sdk.listen!(params, (res) => onUpdate({ data: res.data.map((row) => rowToEntity<M>(row, slug, getPks())), meta: res.meta }), onError)
+            : undefined,
+        listenById: sdk.listenById
+            ? (id: string | number, onUpdate: (s: Entity<M> | undefined) => void, onError?: (e: Error) => void) =>
+                sdk.listenById!(id, (row) => onUpdate(row ? rowToEntity<M>(row, slug, getPks()) : undefined), onError)
+            : undefined,
+        where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown) {
+            const builder = new QueryBuilder<M>(accessor);
+            if (typeof columnOrCondition === "object") {
+                return builder.where(columnOrCondition);
+            }
+            return builder.where(columnOrCondition as keyof M & string, operator!, value as WhereValue<M[keyof M & string]>);
+        },
+        orderBy: (column: keyof M & string, direction?: "asc" | "desc") => new QueryBuilder<M>(accessor).orderBy(column, direction),
+        limit: (count: number) => new QueryBuilder<M>(accessor).limit(count),
+        offset: (count: number) => new QueryBuilder<M>(accessor).offset(count),
+        search: (searchString: string) => new QueryBuilder<M>(accessor).search(searchString),
+        include: (...relations: string[]) => new QueryBuilder<M>(accessor).include(...relations)
+    };
+    return accessor;
+}
+
+/**
+ * Wrap a flat {@link RebaseSdkData} into a Entity-shaped {@link RebaseData}.
+ *
+ * This is the **CMS boundary**: the SDK client (`client.data`) returns flat
+ * rows, but the admin renders the `Entity` view-model (`entity.values.*`).
+ * `core/Rebase.tsx` wraps `client.data` through this before handing it to the
+ * CMS `RebaseDataContext` — without it the admin renders rows with only their
+ * `id`.
+ */
+export function wrapAsEntityData(sdkData: RebaseSdkData, options?: EntityDataOptions): RebaseData {
+    const cache = new Map<string, CollectionAccessor>();
+    const primaryKeysFor = createPrimaryKeyResolver(options);
+
+    function getAccessor(slug: string): CollectionAccessor {
+        let accessor = cache.get(slug);
+        if (!accessor) {
+            accessor = toEntityAccessor(sdkData.collection(slug), slug, () => primaryKeysFor(slug));
+            cache.set(slug, accessor);
+        }
+        return accessor;
+    }
+
+    const target = { collection: getAccessor } as RebaseData;
+
+    return new Proxy(target, {
+        get(_target, prop: string | symbol) {
+            if (prop === "collection") return getAccessor;
+            if (typeof prop === "symbol") return undefined;
+            if (prop === "then" || prop === "toJSON" || prop === "$$typeof") return undefined;
+            return getAccessor(toSnakeCase(prop));
+        }
+    });
+}
+
+/**
+ * Wrap a Entity-shaped {@link RebaseData} into a flat {@link RebaseSdkData}.
+ *
+ * Every collection accessor is adapted to return flat rows. Use this to derive
+ * the flat SDK data layer (`context.data`) from an existing Entity data layer
+ * — e.g. the admin routes its Entity data via `useData()` and exposes the
+ * same routing as flat `context.data` for callbacks by wrapping it here.
+ */
+export function wrapAsSdkData(entityData: RebaseData): RebaseSdkData {
+    const cache = new Map<string, SDKCollectionClient>();
+
+    function getAccessor(slug: string): SDKCollectionClient {
+        let accessor = cache.get(slug);
+        if (!accessor) {
+            accessor = toSdkCollectionClient(entityData.collection(slug));
+            cache.set(slug, accessor);
+        }
+        return accessor;
+    }
+
+    const target = { collection: getAccessor } as RebaseSdkData;
+
+    return new Proxy(target, {
+        get(_target, prop: string | symbol) {
+            if (prop === "collection") return getAccessor;
+            if (typeof prop === "symbol") return undefined;
+            if (prop === "then" || prop === "toJSON" || prop === "$$typeof") return undefined;
+            return getAccessor(toSnakeCase(prop));
+        }
+    });
+}
+
+/**
+ * Build a flat {@link RebaseSdkData} from a `DataDriver`.
+ *
+ * This is the developer-facing SDK data layer used by backend framework
+ * callbacks & scripts (`context.data` / `rebase.data`). It returns flat rows —
+ * identical in shape to the frontend SDK client — so the API is symmetric
+ * across front and back. The admin CMS uses {@link buildRebaseData} (Entity).
+ */
+export function buildSdkData(driver: DataDriver): RebaseSdkData {
+    return wrapAsSdkData(buildRebaseData(driver));
+}

package/src/data/buildRoutedRebaseData.ts

@@ -1,24 +1,30 @@
-import { RebaseData, CollectionAccessor } from "@rebasepro/types";
+import { RebaseData, RebaseSdkData } from "@rebasepro/types";
 import { toSnakeCase } from "@rebasepro/utils";
 
+/**
+ * The two data-layer shapes that can be routed: the Entity-shaped admin
+ * {@link RebaseData} or the flat SDK {@link RebaseSdkData}. Both expose a
+ * `.collection(slug)` accessor, which is all the router needs.
+ */
+export type RoutableData = RebaseData | RebaseSdkData;
+
 /**
  * Parameters for {@link buildRoutedRebaseData}.
  */
-export interface RoutedRebaseDataParams {
+export interface RoutedRebaseDataParams<T extends RoutableData = RebaseData> {
     /**
      * The default data source. Handles every collection that does not
      * resolve to an entry in `sources` (i.e. server-transport collections,
      * which ride the Rebase client).
      */
-    defaultData: RebaseData;
+    defaultData: T;
 
     /**
-     * Per-data-source {@link RebaseData} instances for direct and custom
-     * transports, keyed by data-source key (e.g. `"analytics"`). Server-
-     * mediated sources are not listed here — they fall through to
-     * `defaultData`.
+     * Per-data-source instances for direct and custom transports, keyed by
+     * data-source key (e.g. `"analytics"`). Server-mediated sources are not
+     * listed here — they fall through to `defaultData`.
      */
-    sources: Record<string, RebaseData>;
+    sources: Record<string, T>;
 
     /**
      * Resolve the data-source key for a given collection slug or path.
@@ -55,11 +61,11 @@ export interface RoutedRebaseDataParams {
  * await data.products.find();        // → default (server / Postgres)
  * await data.events.find();          // → Firestore, if `events.dataSource === "analytics"`
  */
-export function buildRoutedRebaseData({
+export function buildRoutedRebaseData<T extends RoutableData = RebaseData>({
     defaultData,
     sources,
     resolveKey
-}: RoutedRebaseDataParams): RebaseData {
+}: RoutedRebaseDataParams<T>): T {
 
     // Fast path: nothing to route → return the default untouched (preserves
     // referential identity for effect dependencies).
@@ -67,21 +73,21 @@ export function buildRoutedRebaseData({
         return defaultData;
     }
 
-    function resolve(slugOrPath: string): RebaseData {
+    function resolve(slugOrPath: string): T {
         const key = resolveKey(slugOrPath);
         if (key && sources[key]) return sources[key];
         return defaultData;
     }
 
-    function getAccessor(slugOrPath: string): CollectionAccessor {
-        return resolve(slugOrPath).collection(slugOrPath);
+    function getAccessor(slugOrPath: string) {
+        return (resolve(slugOrPath) as RoutableData).collection(slugOrPath);
     }
 
     const target = {
         collection: getAccessor
-    } as RebaseData;
+    } as unknown as T;
 
-    return new Proxy(target, {
+    return new Proxy(target as object, {
         get(_target, prop: string | symbol) {
             if (prop === "collection") return getAccessor;
             // Ignore Symbol properties (e.g. Symbol.toPrimitive, Symbol.iterator)
@@ -93,5 +99,5 @@ export function buildRoutedRebaseData({
             // buildRebaseData so dynamic access routes consistently.
             return getAccessor(toSnakeCase(prop));
         }
-    });
+    }) as T;
 }