@rebasepro/client-firebase 0.7.0 → 0.9.0

package/src/hooks/useFirestoreDriver.ts

@@ -1,4 +1,4 @@
-import { DataDriver, DeleteEntityProps, Entity, EntityCollection, EntityReference, FetchCollectionProps, FetchEntityProps, FilterCombination, FilterValues, GeoPoint, ListenCollectionProps, ListenEntityProps, SaveEntityProps, WhereFilterOp } from "@rebasepro/types";
+import { DataDriver, DeleteProps, CollectionConfig, EntityReference, FetchCollectionProps, FetchOneProps, FilterCombination, FilterValues, GeoPoint, ListenCollectionProps, ListenOneProps, SaveProps, WhereFilterOp } from "@rebasepro/types";
 import { User } from "@firebase/auth";
 import {
     collection as collectionClause,
@@ -31,7 +31,7 @@ import {
 import type { FieldValue } from "@firebase/firestore";
 import { FirebaseApp } from "@firebase/app";
 import { FirestoreTextSearchController, FirestoreTextSearchControllerBuilder } from "../types/text_search";
-import { useCallback, useEffect, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
 import { localSearchControllerBuilder } from "../utils";
 import { getAuth } from "@firebase/auth";
 
@@ -62,7 +62,7 @@ export interface FirestoreDataDriverProps {
 
 export type FirestoreIndexesBuilder = (params: {
     path: string,
-    collection: EntityCollection<any>,
+    collection: CollectionConfig<any>,
 }) => FilterCombination<string>[] | undefined
 
 export type FirestoreDataDriver = DataDriver & {
@@ -70,7 +70,7 @@ export type FirestoreDataDriver = DataDriver & {
     initTextSearch: (props: {
         path: string,
         databaseId?: string,
-        collection?: EntityCollection
+        collection?: CollectionConfig
     }) => Promise<boolean>,
 }
 
@@ -120,6 +120,26 @@ export function useFirestoreDriver({
                 .filter(([_, entry]) => !!entry)
                 .forEach(([key, filterParameter]) => {
                     const [op, value] = filterParameter as [WhereFilterOp, any];
+
+                    // Null-testing operators map to Firestore's == / != against null.
+                    if (op === "is-null") {
+                        queryParams.push(whereClause(key, "==", null));
+                        return;
+                    }
+                    if (op === "is-not-null") {
+                        queryParams.push(whereClause(key, "!=", null));
+                        return;
+                    }
+
+                    // Firestore has no LIKE/ILIKE — fail loudly rather than silently
+                    // returning wrong results. Use `searchString` / a search index instead.
+                    if (op === "like" || op === "ilike" || op === "not-like" || op === "not-ilike") {
+                        throw new Error(
+                            `Firestore does not support the "${op}" operator (SQL pattern matching). ` +
+                            "Use a full-text search index or the collection's searchString instead."
+                        );
+                    }
+
                     queryParams.push(whereClause(key, op, cmsToFirestoreModel(value, firestore)));
                 });
         }
@@ -139,31 +159,31 @@ export function useFirestoreDriver({
         return query(collectionReference, ...queryParams);
     }, [firebaseApp]);
 
-    const getAndBuildEntity = useCallback(<M extends Record<string, any>>(path: string,
-        entityId: string | number,
+    const getAndBuildEntity = useCallback((path: string,
+        id: string | number,
         databaseId?: string
-    ): Promise<Entity<M> | undefined> => {
+    ): Promise<Record<string, unknown> | undefined> => {
         if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
 
         const firestore = databaseId ? getFirestore(firebaseApp, databaseId) : getFirestore(firebaseApp);
 
-        return getDoc(doc(firestore, path, String(entityId)))
-            .then((docSnapshot) => {
-                if (!docSnapshot.exists()) {
+        return getDoc(doc(firestore, path, String(id)))
+            .then((docEntity) => {
+                if (!docEntity.exists()) {
                     return undefined;
                 }
-                return createEntityFromDocument(docSnapshot, databaseId);
+                return createRowFromDocument(docEntity);
             });
     }, [firebaseApp]);
 
-    const listenEntity = useCallback(<M extends Record<string, any>>(
+    const listenOne = useCallback(<M extends Record<string, any>>(
         {
             path,
-            entityId,
+            id,
             collection,
             onUpdate,
             onError
-        }: ListenEntityProps<M>): () => void => {
+        }: ListenOneProps<M>): () => void => {
         if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
 
         const databaseId = collection?.databaseId;
@@ -171,10 +191,10 @@ export function useFirestoreDriver({
         const resolvedPath = path;
 
         return onSnapshot(
-            doc(firestore, resolvedPath, String(entityId)),
+            doc(firestore, resolvedPath, String(id)),
             {
-                next: (docSnapshot) => {
-                    onUpdate(createEntityFromDocument(docSnapshot, databaseId));
+                next: (docEntity) => {
+                    onUpdate(docEntity.exists() ? createRowFromDocument(docEntity) : null);
                 },
                 error: onError
             }
@@ -190,7 +210,7 @@ export function useFirestoreDriver({
         path: string,
         databaseId?: string,
         searchString: string;
-        onUpdate: (entities: Entity<M>[]) => void,
+        onUpdate: (rows: Record<string, unknown>[]) => void,
     }): () => void => {
 
         if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
@@ -222,23 +242,24 @@ export function useFirestoreDriver({
                 onUpdate([]);
             }
 
-            const entities: Entity<M>[] = [];
+            const rows: Record<string, unknown>[] = [];
             const addedEntitiesSet = new Set<string | number>();
             subscriptions = (ids ?? [])
-                .map((entityId) => {
-                    return listenEntity({
+                .map((id) => {
+                    return listenOne({
                         path,
-                        entityId,
-                        onUpdate: (entity: Entity<any> | null) => {
-                            if (entity?.values) {
-                                if (entity.id && !addedEntitiesSet.has(entity.id)) {
-                                    addedEntitiesSet.add(entity.id);
-                                    entities.push(entity);
-                                    onUpdate(entities);
+                        id,
+                        onUpdate: (row: Record<string, unknown> | null) => {
+                            const incomingId = row?.id as string | number | undefined;
+                            if (row && incomingId !== undefined) {
+                                if (!addedEntitiesSet.has(incomingId)) {
+                                    addedEntitiesSet.add(incomingId);
+                                    rows.push(row);
+                                    onUpdate(rows);
                                 }
-                            } else if (entity?.id) {
-                                addedEntitiesSet.delete(entity.id);
-                                onUpdate([...entities.filter(e => e.id !== entityId)])
+                            } else {
+                                addedEntitiesSet.delete(id);
+                                onUpdate([...rows.filter(r => r.id !== id)])
                             }
                         }
                     })
@@ -250,48 +271,88 @@ export function useFirestoreDriver({
             subscriptions.forEach((p) => p());
         }
 
-    }, [firebaseApp, listenEntity]);
+    }, [firebaseApp, listenOne]);
 
-    return {
-        key: "firestore",
+    const initTextSearch = useCallback(async (props: {
+        path: string,
+        databaseId?: string,
+        collection?: CollectionConfig
+    }) => {
+        console.debug("Init text search controller", searchControllerRef.current, props.path);
+        if (!searchControllerRef.current) {
+            console.warn("You are trying to use text search, but have not provided a text search controller in `useFirestoreDriver`. You can also set the flag `localTextSearchEnabled` to use local search in `useFirestoreDriver`. Local text search can incur in performance issues and higher costs for large datasets.");
+            return false;
+        }
+        try {
+            return searchControllerRef.current.init(props);
+        } catch (e) {
+            console.error("Error initializing text search controller", e);
+            return false;
+        }
+    }, []);
 
-        currentTime,
+    /**
+     * Fetch entities in a Firestore path
+     * @param path
+     * @param collection
+     * @param filter
+     * @param limit
+     * @param startAfter
+     * @param searchString
+     * @param orderBy
+     * @param order
+     * @return Function to cancel subscription
+     * @see useCollection if you need this functionality implemented as a hook
+     * @group Firestore
+     */
+    const fetchCollection = useCallback(async <M extends Record<string, any>>({
+        path,
+        filter,
+        limit,
+        startAfter,
+        searchString,
+        orderBy,
+        order,
+        collection
+    }: FetchCollectionProps<M>
+    ): Promise<Record<string, unknown>[]> => {
 
-        initialised: Boolean(firebaseApp),
+        const databaseId = collection?.databaseId;
 
-        initTextSearch: useCallback(async (props: {
-            path: string,
-            databaseId?: string,
-            collection?: EntityCollection
-        }) => {
-            console.debug("Init text search controller", searchControllerRef.current, props.path);
-            if (!searchControllerRef.current) {
-                console.warn("You are trying to use text search, but have not provided a text search controller in `useFirestoreDriver`. You can also set the flag `localTextSearchEnabled` to use local search in `useFirestoreDriver`. Local text search can incur in performance issues and higher costs for large datasets.");
-                return false;
-            }
-            try {
-                return searchControllerRef.current.init(props);
-            } catch (e) {
-                console.error("Error initializing text search controller", e);
-                return false;
-            }
-        }, []),
-
-        /**
-         * Fetch entities in a Firestore path
-         * @param path
-         * @param collection
-         * @param filter
-         * @param limit
-         * @param startAfter
-         * @param searchString
-         * @param orderBy
-         * @param order
-         * @return Function to cancel subscription
-         * @see useCollectionFetch if you need this functionality implemented as a hook
-         * @group Firestore
-         */
-        fetchCollection: useCallback(async <M extends Record<string, any>>({
+        const resolvedPath = path;
+
+        console.debug("Fetching collection", {
+            path,
+            limit,
+            filter,
+            startAfter,
+            orderBy,
+            order
+        });
+        const query = buildQuery(resolvedPath, filter, orderBy, order, startAfter as unknown[] | undefined, limit, databaseId);
+
+        const entity = await getDocs(query);
+        return entity.docs.map((doc) => createRowFromDocument(doc));
+    }, [buildQuery]);
+
+    /**
+     * Listen to a entities in a given path
+     * @param path
+     * @param collection
+     * @param onError
+     * @param filter
+     * @param limit
+     * @param startAfter
+     * @param searchString
+     * @param orderBy
+     * @param order
+     * @param onUpdate
+     * @return Function to cancel subscription
+     * @see useCollection if you need this functionality implemented as a hook
+     * @group Firestore
+     */
+    const listenCollection = useCallback(<M extends Record<string, any>>(
+        {
             path,
             filter,
             limit,
@@ -299,334 +360,298 @@ export function useFirestoreDriver({
             searchString,
             orderBy,
             order,
+            onUpdate,
+            onError,
+            collection
+        }: ListenCollectionProps<M>
+    ): () => void => {
+
+        console.debug("Listening collection", {
+            path,
+            searchString,
+            limit,
+            filter,
+            startAfter,
+            orderBy,
+            order,
             collection
-        }: FetchCollectionProps<M>
-        ): Promise<Entity<M>[]> => {
+        });
 
-            const databaseId = collection?.databaseId;
+        if (!firebaseApp) {
+            throw Error("useFirestoreDriver Firebase not initialised");
+        }
 
-            const resolvedPath = path;
+        const databaseId = collection?.databaseId;
 
-            console.debug("Fetching collection", {
-                path,
-                limit,
-                filter,
-                startAfter,
-                orderBy,
-                order
-            });
-            const query = buildQuery(resolvedPath, filter, orderBy, order, startAfter as unknown[] | undefined, limit, databaseId);
-
-            const snapshot = await getDocs(query);
-            return snapshot.docs.map((doc) => createEntityFromDocument(doc, databaseId));
-        }, [buildQuery]),
-
-        /**
-         * Listen to a entities in a given path
-         * @param path
-         * @param collection
-         * @param onError
-         * @param filter
-         * @param limit
-         * @param startAfter
-         * @param searchString
-         * @param orderBy
-         * @param order
-         * @param onUpdate
-         * @return Function to cancel subscription
-         * @see useCollectionFetch if you need this functionality implemented as a hook
-         * @group Firestore
-         */
-        listenCollection: useCallback(<M extends Record<string, any>>(
-            {
+        if (searchString) {
+            return performTextSearch<M>({
                 path,
-                filter,
-                limit,
-                startAfter,
                 searchString,
-                orderBy,
-                order,
                 onUpdate,
-                onError,
-                collection
-            }: ListenCollectionProps<M>
-        ): () => void => {
-
-            console.debug("Listening collection", {
-                path,
-                searchString,
-                limit,
-                filter,
-                startAfter,
-                orderBy,
-                order,
-                collection
+                databaseId
             });
+        }
 
-            if (!firebaseApp) {
-                throw Error("useFirestoreDriver Firebase not initialised");
+        const resolvedPath = path;
+        console.debug("Resolved path for listening", {
+            path,
+            resolvedPath
+        });
+        const query = buildQuery(resolvedPath, filter, orderBy, order, startAfter as unknown[] | undefined, limit, databaseId);
+        return onSnapshot(query,
+            {
+                next: (entity) => {
+                    if (!searchString)
+                        onUpdate(entity.docs.map((doc) => createRowFromDocument(doc)));
+                },
+                error: onError
             }
+        );
 
-            const databaseId = collection?.databaseId;
+    }, [buildQuery, firebaseApp, performTextSearch]);
 
-            if (searchString) {
-                return performTextSearch<M>({
-                    path,
-                    searchString,
-                    onUpdate,
-                    databaseId
-                });
-            }
+    /**
+     * Retrieve a entity given a path and a collection
+     * @param path
+     * @param id
+     * @param collection
+     * @group Firestore
+     */
+    const fetchOne = useCallback(<M extends Record<string, any>>({
+        path,
+        id,
+        collection
+    }: FetchOneProps<M>
+    ): Promise<Record<string, unknown> | undefined> => {
+        const resolvedPath = path;
+        return getAndBuildEntity(resolvedPath, id, collection?.databaseId);
+    }, [getAndBuildEntity]);
 
-            const resolvedPath = path;
-            console.debug("Resolved path for listening", {
-                path,
-                resolvedPath
-            });
-            const query = buildQuery(resolvedPath, filter, orderBy, order, startAfter as unknown[] | undefined, limit, databaseId);
-            return onSnapshot(query,
-                {
-                    next: (snapshot) => {
-                        if (!searchString)
-                            onUpdate(snapshot.docs.map((doc) => createEntityFromDocument(doc, databaseId)));
-                    },
-                    error: onError
-                }
-            );
-
-        }, [buildQuery, firebaseApp, performTextSearch]),
-
-        /**
-         * Retrieve an entity given a path and a collection
-         * @param path
-         * @param entityId
-         * @param collection
-         * @group Firestore
-         */
-        fetchEntity: useCallback(<M extends Record<string, any>>({
+    /**
+     * Save entity to the specified path. Note that Firestore does not allow
+     * undefined values.
+     * @param path
+     * @param id
+     * @param values
+     * @param schemaId
+     * @param collection
+     * @param status
+     * @group Firestore
+     */
+    const save = useCallback(<M extends Record<string, any>>(
+        {
             path,
-            entityId,
+            id,
+            values: valuesProp,
+            collection,
+            status
+        }: SaveProps<M>): Promise<Record<string, unknown>> => {
+
+        if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
+
+        console.debug("1", {
+            path,
+            id,
+            values: valuesProp,
             collection
-        }: FetchEntityProps<M>
-        ): Promise<Entity<M> | undefined> => {
-            const resolvedPath = path;
-            return getAndBuildEntity(resolvedPath, entityId, collection?.databaseId);
-        }, [getAndBuildEntity]),
-
-        /**
-         *
-         * @param path
-         * @param entityId
-         * @param collection
-         * @param onUpdate
-         * @param onError
-         * @return Function to cancel subscription
-         * @group Firestore
-         */
-        listenEntity,
-
-        /**
-         * Save entity to the specified path. Note that Firestore does not allow
-         * undefined values.
-         * @param path
-         * @param entityId
-         * @param values
-         * @param schemaId
-         * @param collection
-         * @param status
-         * @group Firestore
-         */
-        saveEntity: useCallback(<M extends Record<string, any>>(
-            {
-                path,
-                entityId,
-                values: valuesProp,
-                collection,
-                status
-            }: SaveEntityProps<M>): Promise<Entity<M>> => {
+        })
+        const values = cmsToFirestoreModel(valuesProp, getFirestore(firebaseApp));
 
-            if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
+        console.debug("2", {
+            path,
+            id,
+            values: valuesProp,
+            collection
+        })
+        const databaseId = collection?.databaseId;
+        const firestore = databaseId ? getFirestore(firebaseApp, databaseId) : getFirestore(firebaseApp);
+        const resolvedPath = path;
 
-            console.debug("1", {
-                path,
-                entityId,
-                values: valuesProp,
-                collection
-            })
-            const values = cmsToFirestoreModel(valuesProp, getFirestore(firebaseApp));
+        const collectionReference: CollectionReference = collectionClause(firestore, path);
+        console.debug("Saving entity", {
+            path,
+            id,
+            values,
+            databaseId
+        });
 
-            console.debug("2", {
-                path,
-                entityId,
-                values: valuesProp,
-                collection
+        let documentReference: DocumentReference;
+        if (id) {
+            documentReference = doc(collectionReference, String(id));
+        } else {
+            documentReference = doc(collectionReference);
+        }
+        return setDoc(documentReference, values as Record<string, unknown>, { merge: true })
+            .then(() => {
+                return {
+                    ...(firestoreToCMSModel(values) as Record<string, unknown>),
+                    id: documentReference.id
+                };
             })
-            const databaseId = collection?.databaseId;
-            const firestore = databaseId ? getFirestore(firebaseApp, databaseId) : getFirestore(firebaseApp);
-            const resolvedPath = path;
+            .catch((error) => {
+                console.error("Error saving entity", error);
+                throw error;
 
-            const collectionReference: CollectionReference = collectionClause(firestore, path);
-            console.debug("Saving entity", {
-                path,
-                entityId,
-                values,
-                databaseId
             });
+    }, [firebaseApp]);
 
-            let documentReference: DocumentReference;
-            if (entityId) {
-                documentReference = doc(collectionReference, String(entityId));
-            } else {
-                documentReference = doc(collectionReference);
-            }
-            return setDoc(documentReference, values as Record<string, unknown>, { merge: true })
-                .then(() => {
-                    return {
-                        id: documentReference.id,
-                        path,
-                        values: firestoreToCMSModel(values)
-                    } as Entity<M>;
-                })
-                .catch((error) => {
-                    console.error("Error saving entity", error);
-                    throw error;
+    /**
+     * Delete a entity
+     * @param entity
+     * @param collection
+     * @group Firestore
+     */
+    const deleteOne = useCallback(<M extends Record<string, any>>(
+        {
+            row,
+            collection
+        }: DeleteProps<M>
+    ): Promise<void> => {
+        if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
 
-                });
-        }, [firebaseApp]),
-
-        /**
-         * Delete an entity
-         * @param entity
-         * @param collection
-         * @group Firestore
-         */
-        deleteEntity: useCallback(<M extends Record<string, any>>(
-            {
-                entity
-            }: DeleteEntityProps<M>
-        ): Promise<void> => {
-            if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
-
-            const databaseId = entity.databaseId;
-            const firestore = databaseId ? getFirestore(firebaseApp, databaseId) : getFirestore(firebaseApp);
-
-            return deleteDoc(doc(firestore, entity.path, String(entity.id)));
-        }, [firebaseApp]),
-
-        /**
-         * Check if the given property is unique in the given collection
-         * @param path Collection path
-         * @param name of the property
-         * @param value
-         * @param property
-         * @param entityId
-         * @return `true` if there are no other fields besides the given entity
-         * @group Firestore
-         */
-        checkUniqueField: useCallback(async (
-            path: string,
-            name: string,
-            value: unknown,
-            entityId?: string | number,
-            collection?: EntityCollection<any>
-        ): Promise<boolean> => {
+        const databaseId = collection?.databaseId;
+        const firestore = databaseId ? getFirestore(firebaseApp, databaseId) : getFirestore(firebaseApp);
 
-            if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
+        return deleteDoc(doc(firestore, row.path, String(row.id)));
+    }, [firebaseApp]);
 
-            const databaseId = collection?.databaseId;
-            const firestore = databaseId ? getFirestore(firebaseApp, databaseId) : getFirestore(firebaseApp);
+    /**
+     * Check if the given property is unique in the given collection
+     * @param path Collection path
+     * @param name of the property
+     * @param value
+     * @param property
+     * @param id
+     * @return `true` if there are no other fields besides the given entity
+     * @group Firestore
+     */
+    const checkUniqueField = useCallback(async (
+        path: string,
+        name: string,
+        value: unknown,
+        id?: string | number,
+        collection?: CollectionConfig<any>
+    ): Promise<boolean> => {
 
-            if (value === undefined || value === null) {
-                return Promise.resolve(true);
-            }
-            const q = query(collectionClause(firestore, path), whereClause(name, "==", cmsToFirestoreModel(value, firestore)));
-            const snapshot = await getDocs(q);
-            return snapshot.docs.filter(doc => doc.id !== entityId).length === 0;
+        if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
 
-        }, [firebaseApp]),
+        const databaseId = collection?.databaseId;
+        const firestore = databaseId ? getFirestore(firebaseApp, databaseId) : getFirestore(firebaseApp);
 
-        countEntities: useCallback(async ({
-            path,
-            filter,
-            order,
-            orderBy,
-            collection
-        }: FetchCollectionProps<any>): Promise<number> => {
-            if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
-            const databaseId = collection?.databaseId;
-            const resolvedPath = path;
-            const query = buildQuery(resolvedPath, filter, orderBy, order, undefined, undefined, databaseId);
-            const snapshot = await getCountFromServer(query);
-            return snapshot.data().count;
-        }, [firebaseApp]),
-
-        isFilterCombinationValid: useCallback(({
-            path,
-            collection,
-            filterValues,
-            sortBy
-        }: {
-            path: string,
-            collection: EntityCollection<any>,
-            filterValues: FilterValues<any>,
-            sortBy?: [string, "asc" | "desc"],
-        }): boolean => {
+        if (value === undefined || value === null) {
+            return Promise.resolve(true);
+        }
+        const q = query(collectionClause(firestore, path), whereClause(name, "==", cmsToFirestoreModel(value, firestore)));
+        const entity = await getDocs(q);
+        return entity.docs.filter(doc => doc.id !== id).length === 0;
 
-            if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
+    }, [firebaseApp]);
 
-            // If no indexes are defined, we assume the query is valid.
-            // If there is no index in Firestore, and error message will be shown
-            if (firestoreIndexesBuilder === undefined) return true;
-            const resolvedPath = path;
+    const count = useCallback(async ({
+        path,
+        filter,
+        order,
+        orderBy,
+        collection
+    }: FetchCollectionProps<any>): Promise<number> => {
+        if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
+        const databaseId = collection?.databaseId;
+        const resolvedPath = path;
+        const query = buildQuery(resolvedPath, filter, orderBy, order, undefined, undefined, databaseId);
+        const entity = await getCountFromServer(query);
+        return entity.data().count;
+    }, [firebaseApp]);
 
-            const indexes = firestoreIndexesBuilder?.({
-                path: resolvedPath,
-                collection
-            });
+    const isFilterCombinationValid = useCallback(({
+        path,
+        collection,
+        filterValues,
+        sortBy
+    }: {
+        path: string,
+        collection: CollectionConfig<any>,
+        filterValues: FilterValues<any>,
+        sortBy?: [string, "asc" | "desc"],
+    }): boolean => {
+
+        if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
 
-            const sortKey = sortBy ? sortBy[0] : undefined;
-            const sortDirection = sortBy ? sortBy[1] : undefined;
+        // If no indexes are defined, we assume the query is valid.
+        // If there is no index in Firestore, and error message will be shown
+        if (firestoreIndexesBuilder === undefined) return true;
+        const resolvedPath = path;
 
-            // Order by clause cannot contain a field with an equality filter
-            const values: [WhereFilterOp, any][] = Object.values(filterValues) as [WhereFilterOp, any][];
+        const indexes = firestoreIndexesBuilder?.({
+            path: resolvedPath,
+            collection
+        });
 
-            const filterKeys = Object.keys(filterValues);
-            const filtersCount = filterKeys.length;
+        const sortKey = sortBy ? sortBy[0] : undefined;
+        const sortDirection = sortBy ? sortBy[1] : undefined;
 
-            if (!sortKey && values.every((v) => v[0] === "==")) {
-                return true;
-            }
+        // Order by clause cannot contain a field with an equality filter
+        const values: [WhereFilterOp, any][] = Object.values(filterValues) as [WhereFilterOp, any][];
 
-            if (filtersCount === 1 && (!sortKey || sortKey === filterKeys[0])) {
-                return true;
-            }
+        const filterKeys = Object.keys(filterValues);
+        const filtersCount = filterKeys.length;
 
-            if (!indexes && filtersCount > 1) {
-                return false;
-            }
+        if (!sortKey && values.every((v) => v[0] === "==")) {
+            return true;
+        }
 
-            return !!indexes && indexes
-                .filter((compositeIndex) => !sortKey || sortKey in compositeIndex)
-                .find((compositeIndex) =>
-                    Object.entries(filterValues).every(([key, value]) => compositeIndex[key] !== undefined && (!sortDirection || compositeIndex[key] === sortDirection))
-                ) !== undefined;
-        }, [firebaseApp])
+        if (filtersCount === 1 && (!sortKey || sortKey === filterKeys[0])) {
+            return true;
+        }
 
-    };
+        if (!indexes && filtersCount > 1) {
+            return false;
+        }
+
+        return !!indexes && indexes
+            .filter((compositeIndex) => !sortKey || sortKey in compositeIndex)
+            .find((compositeIndex) =>
+                Object.entries(filterValues).every(([key, value]) => compositeIndex[key] !== undefined && (!sortDirection || compositeIndex[key] === sortDirection))
+            ) !== undefined;
+    }, [firebaseApp]);
+
+    return useMemo(() => ({
+        key: "firestore" as const,
+        currentTime,
+        initialised: Boolean(firebaseApp),
+        initTextSearch,
+        fetchCollection,
+        listenCollection,
+        fetchOne,
+        listenOne,
+        save,
+        delete: deleteOne,
+        checkUniqueField,
+        count,
+        isFilterCombinationValid
+    }), [
+        firebaseApp,
+        initTextSearch,
+        fetchCollection,
+        listenCollection,
+        fetchOne,
+        listenOne,
+        save,
+        deleteOne,
+        checkUniqueField,
+        count,
+        isFilterCombinationValid
+    ]);
 
 }
 
-const createEntityFromDocument = <M extends Record<string, any>>(
-    docSnap: DocumentSnapshot,
-    databaseId?: string
-): Entity<M> => {
-    const values = firestoreToCMSModel(docSnap.data()) as M;
-    const path = getCMSPathFromFirestorePath(docSnap.ref.path);
+const createRowFromDocument = (
+    docSnap: DocumentSnapshot
+): Record<string, unknown> => {
+    const values = firestoreToCMSModel(docSnap.data()) as Record<string, unknown>;
     return {
-        id: docSnap.id,
-        path: path,
-        values,
-        databaseId
+        ...values,
+        // Spread the canonical document id last so it wins over a literal `id` field
+        id: docSnap.id
     };
 };
 
@@ -763,7 +788,7 @@ function buildTextSearchControllerWithLocalSearch({
         init: async (props: {
             path: string,
             databaseId?: string,
-            collection?: EntityCollection
+            collection?: CollectionConfig
         }) => {
             const b = await textSearchController.init(props);
             if (b) {