@rebasepro/client-firebase 0.8.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,
@@ -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,12 +271,12 @@ export function useFirestoreDriver({
             subscriptions.forEach((p) => p());
         }
 
-    }, [firebaseApp, listenEntity]);
+    }, [firebaseApp, listenOne]);
 
     const initTextSearch = useCallback(async (props: {
         path: string,
         databaseId?: string,
-        collection?: EntityCollection
+        collection?: CollectionConfig
     }) => {
         console.debug("Init text search controller", searchControllerRef.current, props.path);
         if (!searchControllerRef.current) {
@@ -281,7 +302,7 @@ export function useFirestoreDriver({
      * @param orderBy
      * @param order
      * @return Function to cancel subscription
-     * @see useCollectionFetch if you need this functionality implemented as a hook
+     * @see useCollection if you need this functionality implemented as a hook
      * @group Firestore
      */
     const fetchCollection = useCallback(async <M extends Record<string, any>>({
@@ -294,7 +315,7 @@ export function useFirestoreDriver({
         order,
         collection
     }: FetchCollectionProps<M>
-    ): Promise<Entity<M>[]> => {
+    ): Promise<Record<string, unknown>[]> => {
 
         const databaseId = collection?.databaseId;
 
@@ -310,8 +331,8 @@ export function useFirestoreDriver({
         });
         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));
+        const entity = await getDocs(query);
+        return entity.docs.map((doc) => createRowFromDocument(doc));
     }, [buildQuery]);
 
     /**
@@ -327,7 +348,7 @@ export function useFirestoreDriver({
      * @param order
      * @param onUpdate
      * @return Function to cancel subscription
-     * @see useCollectionFetch if you need this functionality implemented as a hook
+     * @see useCollection if you need this functionality implemented as a hook
      * @group Firestore
      */
     const listenCollection = useCallback(<M extends Record<string, any>>(
@@ -379,9 +400,9 @@ export function useFirestoreDriver({
         const query = buildQuery(resolvedPath, filter, orderBy, order, startAfter as unknown[] | undefined, limit, databaseId);
         return onSnapshot(query,
             {
-                next: (snapshot) => {
+                next: (entity) => {
                     if (!searchString)
-                        onUpdate(snapshot.docs.map((doc) => createEntityFromDocument(doc, databaseId)));
+                        onUpdate(entity.docs.map((doc) => createRowFromDocument(doc)));
                 },
                 error: onError
             }
@@ -390,47 +411,47 @@ export function useFirestoreDriver({
     }, [buildQuery, firebaseApp, performTextSearch]);
 
     /**
-     * Retrieve an entity given a path and a collection
+     * Retrieve a entity given a path and a collection
      * @param path
-     * @param entityId
+     * @param id
      * @param collection
      * @group Firestore
      */
-    const fetchEntity = useCallback(<M extends Record<string, any>>({
+    const fetchOne = useCallback(<M extends Record<string, any>>({
         path,
-        entityId,
+        id,
         collection
-    }: FetchEntityProps<M>
-    ): Promise<Entity<M> | undefined> => {
+    }: FetchOneProps<M>
+    ): Promise<Record<string, unknown> | undefined> => {
         const resolvedPath = path;
-        return getAndBuildEntity(resolvedPath, entityId, collection?.databaseId);
+        return getAndBuildEntity(resolvedPath, id, collection?.databaseId);
     }, [getAndBuildEntity]);
 
     /**
      * Save entity to the specified path. Note that Firestore does not allow
      * undefined values.
      * @param path
-     * @param entityId
+     * @param id
      * @param values
      * @param schemaId
      * @param collection
      * @param status
      * @group Firestore
      */
-    const saveEntity = useCallback(<M extends Record<string, any>>(
+    const save = useCallback(<M extends Record<string, any>>(
         {
             path,
-            entityId,
+            id,
             values: valuesProp,
             collection,
             status
-        }: SaveEntityProps<M>): Promise<Entity<M>> => {
+        }: SaveProps<M>): Promise<Record<string, unknown>> => {
 
         if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
 
         console.debug("1", {
             path,
-            entityId,
+            id,
             values: valuesProp,
             collection
         })
@@ -438,7 +459,7 @@ export function useFirestoreDriver({
 
         console.debug("2", {
             path,
-            entityId,
+            id,
             values: valuesProp,
             collection
         })
@@ -449,24 +470,23 @@ export function useFirestoreDriver({
         const collectionReference: CollectionReference = collectionClause(firestore, path);
         console.debug("Saving entity", {
             path,
-            entityId,
+            id,
             values,
             databaseId
         });
 
         let documentReference: DocumentReference;
-        if (entityId) {
-            documentReference = doc(collectionReference, String(entityId));
+        if (id) {
+            documentReference = doc(collectionReference, String(id));
         } 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>;
+                    ...(firestoreToCMSModel(values) as Record<string, unknown>),
+                    id: documentReference.id
+                };
             })
             .catch((error) => {
                 console.error("Error saving entity", error);
@@ -476,22 +496,23 @@ export function useFirestoreDriver({
     }, [firebaseApp]);
 
     /**
-     * Delete an entity
+     * Delete a entity
      * @param entity
      * @param collection
      * @group Firestore
      */
-    const deleteEntity = useCallback(<M extends Record<string, any>>(
+    const deleteOne = useCallback(<M extends Record<string, any>>(
         {
-            entity
-        }: DeleteEntityProps<M>
+            row,
+            collection
+        }: DeleteProps<M>
     ): Promise<void> => {
         if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
 
-        const databaseId = entity.databaseId;
+        const databaseId = collection?.databaseId;
         const firestore = databaseId ? getFirestore(firebaseApp, databaseId) : getFirestore(firebaseApp);
 
-        return deleteDoc(doc(firestore, entity.path, String(entity.id)));
+        return deleteDoc(doc(firestore, row.path, String(row.id)));
     }, [firebaseApp]);
 
     /**
@@ -500,7 +521,7 @@ export function useFirestoreDriver({
      * @param name of the property
      * @param value
      * @param property
-     * @param entityId
+     * @param id
      * @return `true` if there are no other fields besides the given entity
      * @group Firestore
      */
@@ -508,8 +529,8 @@ export function useFirestoreDriver({
         path: string,
         name: string,
         value: unknown,
-        entityId?: string | number,
-        collection?: EntityCollection<any>
+        id?: string | number,
+        collection?: CollectionConfig<any>
     ): Promise<boolean> => {
 
         if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
@@ -521,12 +542,12 @@ export function useFirestoreDriver({
             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;
+        const entity = await getDocs(q);
+        return entity.docs.filter(doc => doc.id !== id).length === 0;
 
     }, [firebaseApp]);
 
-    const countEntities = useCallback(async ({
+    const count = useCallback(async ({
         path,
         filter,
         order,
@@ -537,8 +558,8 @@ export function useFirestoreDriver({
         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;
+        const entity = await getCountFromServer(query);
+        return entity.data().count;
     }, [firebaseApp]);
 
     const isFilterCombinationValid = useCallback(({
@@ -548,7 +569,7 @@ export function useFirestoreDriver({
         sortBy
     }: {
         path: string,
-        collection: EntityCollection<any>,
+        collection: CollectionConfig<any>,
         filterValues: FilterValues<any>,
         sortBy?: [string, "asc" | "desc"],
     }): boolean => {
@@ -600,40 +621,37 @@ export function useFirestoreDriver({
         initTextSearch,
         fetchCollection,
         listenCollection,
-        fetchEntity,
-        listenEntity,
-        saveEntity,
-        deleteEntity,
+        fetchOne,
+        listenOne,
+        save,
+        delete: deleteOne,
         checkUniqueField,
-        countEntities,
+        count,
         isFilterCombinationValid
     }), [
         firebaseApp,
         initTextSearch,
         fetchCollection,
         listenCollection,
-        fetchEntity,
-        listenEntity,
-        saveEntity,
-        deleteEntity,
+        fetchOne,
+        listenOne,
+        save,
+        deleteOne,
         checkUniqueField,
-        countEntities,
+        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
     };
 };
 
@@ -770,7 +788,7 @@ function buildTextSearchControllerWithLocalSearch({
         init: async (props: {
             path: string,
             databaseId?: string,
-            collection?: EntityCollection
+            collection?: CollectionConfig
         }) => {
             const b = await textSearchController.init(props);
             if (b) {

package/src/types/text_search.ts

@@ -1,6 +1,6 @@
 import { User as FirebaseUser } from "@firebase/auth";
 import { FirebaseApp } from "@firebase/app";
-import { EntityCollection } from "@rebasepro/types";
+import { CollectionConfig } from "@rebasepro/types";
 
 export type FirestoreTextSearchControllerBuilder = (props: {
     firebaseApp: FirebaseApp;
@@ -25,7 +25,7 @@ export type FirestoreTextSearchController = {
     init: (props: {
         path: string,
         databaseId?: string,
-        collection?: EntityCollection
+        collection?: CollectionConfig
     }) => Promise<boolean>,
     /**
      * Do the search and return a list of ids.
@@ -36,7 +36,7 @@ export type FirestoreTextSearchController = {
         path: string,
         currentUser?: FirebaseUser,
         databaseId?: string,
-        collection?: EntityCollection
+        collection?: CollectionConfig
     }) => (Promise<readonly string[] | undefined>),
 
 };

package/src/utils/collections_firestore.ts

@@ -1,5 +1,5 @@
 import { deleteField, DocumentSnapshot } from "@firebase/firestore";
-import { EntityCollection, FirebaseCollection, Properties, Property } from "@rebasepro/types";
+import { CollectionConfig, FirebaseCollectionConfig, Properties, Property } from "@rebasepro/types";
 import { COLLECTION_PATH_SEPARATOR, sortProperties, stripCollectionPath } from "@rebasepro/common";
 
 export function buildCollectionId(idOrPath: string, parentCollectionSlugs?: string[], parentEntityIds?: string[]): string {
@@ -9,7 +9,7 @@ export function buildCollectionId(idOrPath: string, parentCollectionSlugs?: stri
 }
 
 
-export const docsToCollectionTree = (docs: DocumentSnapshot[]): EntityCollection[] => {
+export const docsToCollectionTree = (docs: DocumentSnapshot[]): CollectionConfig[] => {
 
     const collectionsMap = docs.map((doc) => {
         const id: string = doc.id;
@@ -26,7 +26,7 @@ export const docsToCollectionTree = (docs: DocumentSnapshot[]): EntityCollection
             const parentId = id.split(COLLECTION_PATH_SEPARATOR).slice(0, -1).join(COLLECTION_PATH_SEPARATOR);
             const parentCollection = collectionsMap[parentId];
             if (parentCollection)
-                (parentCollection as FirebaseCollection).subcollections = () => [...((parentCollection as FirebaseCollection).subcollections?.() ?? []), collection];
+                (parentCollection as FirebaseCollectionConfig).subcollections = () => [...((parentCollection as FirebaseCollectionConfig).subcollections?.() ?? []), collection];
             delete collectionsMap[id];
         }
     });
@@ -34,7 +34,7 @@ export const docsToCollectionTree = (docs: DocumentSnapshot[]): EntityCollection
     return Object.values(collectionsMap);
 }
 
-export const docToCollection = (doc: DocumentSnapshot): EntityCollection => {
+export const docToCollection = (doc: DocumentSnapshot): CollectionConfig => {
     const data = doc.data();
     if (!data)
         throw Error("Entity collection has not been persisted correctly");
@@ -48,7 +48,7 @@ export const docToCollection = (doc: DocumentSnapshot): EntityCollection => {
         ...data,
         properties: sortedProperties,
         slug: data.id ?? data.alias ?? data.slug
-    } as EntityCollection;
+    } as CollectionConfig;
 }
 
 

package/src/utils/database.ts

@@ -12,8 +12,8 @@ export async function getFirestoreDataInPath(firebaseApp: FirebaseApp, path: str
     const firestore = getFirestore(firebaseApp);
     if (!parentPaths || parentPaths.length === 0) {
         const q = query(collection(firestore, path), limitClause(limit));
-        return getDocs(q).then((querySnapshot) => {
-            return querySnapshot.docs.map(doc => doc.data());
+        return getDocs(q).then((queryEntity) => {
+            return queryEntity.docs.map(doc => doc.data());
         });
     } else {
         let currentDocs: QueryDocumentSnapshot[] | undefined = undefined;

package/src/utils/local_text_search_controller.ts

@@ -2,7 +2,7 @@ import { collection, getFirestore, onSnapshot, query } from "@firebase/firestore
 import Fuse from "fuse.js"
 
 import { FirebaseApp } from "@firebase/app";
-import { EntityCollection } from "@rebasepro/types";
+import { CollectionConfig } from "@rebasepro/types";
 import { FirestoreTextSearchController, FirestoreTextSearchControllerBuilder } from "../types";
 
 const MAX_SEARCH_RESULTS = 80;
@@ -32,7 +32,7 @@ export const localSearchControllerBuilder: FirestoreTextSearchControllerBuilder
         databaseId
     }: {
         path: string,
-        collection?: EntityCollection,
+        collection?: CollectionConfig,
         databaseId?: string
     }): Promise<boolean> => {
 
@@ -49,11 +49,11 @@ export const localSearchControllerBuilder: FirestoreTextSearchControllerBuilder
                 const col = collection(firestore, path);
                 listeners[path] = onSnapshot(query(col),
                     {
-                        next: (snapshot) => {
-                            if (snapshot.metadata.fromCache && snapshot.metadata.hasPendingWrites) {
+                        next: (entity) => {
+                            if (entity.metadata.fromCache && entity.metadata.hasPendingWrites) {
                                 return;
                             }
-                            const docs = snapshot.docs.map(doc => ({
+                            const docs = entity.docs.map(doc => ({
                                 id: doc.id,
                                 ...doc.data()
                             }));
@@ -112,7 +112,7 @@ export const localSearchControllerBuilder: FirestoreTextSearchControllerBuilder
     }
 }
 
-function buildIndex(list: (object & { id: string })[], collection: EntityCollection) {
+function buildIndex(list: (object & { id: string })[], collection: CollectionConfig) {
 
     const keys = ["id", ...Object.keys(collection.properties)];
 

package/src/utils/pinecone.ts

@@ -1,6 +1,6 @@
 import { User as FirebaseUser } from "@firebase/auth";
 import { FirestoreTextSearchController, FirestoreTextSearchControllerBuilder } from "../types";
-import { EntityCollection } from "@rebasepro/types";
+import { CollectionConfig } from "@rebasepro/types";
 
 const DEFAULT_SERVER = "https://api.rebase.pro";
 
@@ -60,7 +60,7 @@ export function buildPineconeSearchController({
 
         const init = (props: {
             path: string,
-            collection?: EntityCollection
+            collection?: CollectionConfig
         }) => {
             // do nothing
             return Promise.resolve(isPathSupported(props.path));

package/src/utils/rebase_search_controller.ts

@@ -1,7 +1,7 @@
 import { FirestoreTextSearchController, FirestoreTextSearchControllerBuilder } from "../types";
 import { FirebaseApp } from "@firebase/app";
 import { getFunctions, httpsCallable } from "@firebase/functions";
-import { EntityCollection } from "@rebasepro/types";
+import { CollectionConfig } from "@rebasepro/types";
 
 /**
  * Configuration returned by the Rebase Search Extension
@@ -204,7 +204,7 @@ export function buildRebaseSearchController(
          */
         const init = async (props: {
             path: string;
-            collection?: EntityCollection;
+            collection?: CollectionConfig;
             databaseId?: string;
         }): Promise<boolean> => {
             try {
@@ -289,7 +289,7 @@ export function buildRebaseSearchController(
             searchString: string;
             path: string;
             databaseId?: string;
-            collection?: EntityCollection;
+            collection?: CollectionConfig;
         }): Promise<readonly string[] | undefined> => {
             if (!typesenseClient) {
                 // Ensure client is initialized

package/src/utils/text_search_controller.ts

@@ -1,5 +1,5 @@
 import { FirestoreTextSearchController, FirestoreTextSearchControllerBuilder } from "../types";
-import { EntityCollection } from "@rebasepro/types";
+import { CollectionConfig } from "@rebasepro/types";
 
 /**
  * Utility function to perform a text search in an external index,
@@ -20,7 +20,7 @@ export function buildExternalSearchController({
 
         const init = (props: {
             path: string,
-            collection?: EntityCollection
+            collection?: CollectionConfig
         }) => {
             return Promise.resolve(isPathSupported(props.path));
         }