@rebasepro/firebase 0.13.0 → 0.13.1-canary.g06dbe5b

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/firebase",
   "type": "module",
-  "version": "0.13.0",
+  "version": "0.13.1-canary.g06dbe5b",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -14,13 +14,13 @@
     "fast-equals": "6.0.2",
     "fuse.js": "^7.5.0",
     "react-router": "^8.3.0",
-    "@rebasepro/admin": "0.13.0",
-    "@rebasepro/admin-types": "0.13.0",
-    "@rebasepro/app": "0.13.0",
-    "@rebasepro/common": "0.13.0",
-    "@rebasepro/types": "0.13.0",
-    "@rebasepro/utils": "0.13.0",
-    "@rebasepro/ui": "0.13.0"
+    "@rebasepro/admin": "0.13.1-canary.g06dbe5b",
+    "@rebasepro/app": "0.13.1-canary.g06dbe5b",
+    "@rebasepro/admin-types": "0.13.1-canary.g06dbe5b",
+    "@rebasepro/common": "0.13.1-canary.g06dbe5b",
+    "@rebasepro/utils": "0.13.1-canary.g06dbe5b",
+    "@rebasepro/types": "0.13.1-canary.g06dbe5b",
+    "@rebasepro/ui": "0.13.1-canary.g06dbe5b"
   },
   "peerDependencies": {
     "firebase": "^10.12.2 || ^11.0.0 || ^12.0.0",

package/src/components/RebaseFirebaseAppProps.tsx

@@ -147,7 +147,7 @@ export type RebaseFirebaseAppProps = {
     plugins?: RebasePlugin[];
 
     /**
-     * Open the drawer on hover. Defaults to `false`
+     * Open the drawer on hover. Defaults to `true`
      */
     autoOpenDrawer?: boolean;
 

package/src/hooks/useBuildUserManagement.tsx

@@ -57,6 +57,51 @@ export interface UserManagementDelegateParams<CONTROLLER extends AuthController<
 
 }
 
+/**
+ * Why the access gate answered the way it did.
+ *
+ * `users-unreadable` is a state of its own because it used to be
+ * indistinguishable from `bootstrap`: the users listener's `onError` empties
+ * the user list, so a `permission-denied` on the users path — a rules
+ * misconfiguration, a rules deploy that has not landed, a renamed path —
+ * reached the gate as "no users created yet" and every authenticated user was
+ * let in. An unreadable list is not an empty one, and only one of the two may
+ * open the door.
+ */
+export type AccessDecision =
+    | "loading"
+    | "no-user"
+    | "users-unreadable"
+    | "bootstrap"
+    | "known-user"
+    | "unknown-user";
+
+/**
+ * Decide whether a user may access the CMS, given the state of the user
+ * management collection.
+ *
+ * A plain function rather than logic inside the gate callback so the states
+ * that must stay distinct can be asserted without a React render.
+ */
+export function resolveAccessDecision({
+    loading,
+    usersError,
+    users,
+    user
+}: {
+    loading: boolean;
+    usersError?: Error;
+    users: { email?: string | null }[];
+    user: { email?: string | null } | null;
+}): AccessDecision {
+    if (loading) return "loading";
+    if (!user) return "no-user";
+    if (usersError) return "users-unreadable";
+    if (users.length === 0) return "bootstrap";
+    const known = users.some(u => u.email?.toLowerCase() === user.email?.toLowerCase());
+    return known ? "known-user" : "unknown-user";
+}
+
 /**
  * This hook is used to build a user management object that can be used to
  * manage users and roles in a Firestore backend.
@@ -265,21 +310,37 @@ export function useBuildUserManagement<CONTROLLER extends AuthController<User> =
 
     const accessGate: FirebaseAccessGate<USER> = useCallback(({ user }) => {
 
-        if (loading) {
+        const decision = resolveAccessDecision({
+            loading,
+            usersError,
+            users,
+            user
+        });
+
+        if (decision === "loading") {
             return false;
         }
-        if (user === null) {
+
+        if (decision === "no-user") {
             console.warn("User is null, returning");
             return false;
         }
 
-        if (users.length === 0) {
+        if (decision === "users-unreadable") {
+            // The users collection could not be read, so we do not know whether
+            // this user is in it. Denying is the only safe reading: the
+            // bootstrap branch below would otherwise admit everyone.
+            console.error("Denying access: the user management collection could not be read", usersError);
+            return false;
+        }
+
+        if (decision === "bootstrap") {
             console.warn("No users created yet");
             return true; // If there are no users created yet, we allow access to every user
         }
 
         const mgmtUser = users.find(u => u.email?.toLowerCase() === user?.email?.toLowerCase());
-        if (mgmtUser) {
+        if (decision === "known-user" && mgmtUser && user) {
             // check if the uid or photoURL needs to be updated in the user management system
             const needsUidUpdate = mgmtUser.uid !== user.uid;
             const needsPhotoUpdate = user.photoURL && mgmtUser.photoURL !== user.photoURL;
@@ -302,7 +363,7 @@ export function useBuildUserManagement<CONTROLLER extends AuthController<User> =
         }
 
         throw Error("Could not find a user with the provided email in the user management system.");
-    }, [loading, users]);
+    }, [loading, users, usersError]);
 
     const userRoles = authController.user ? defineRolesFor(authController.user) : undefined;
     const isAdmin = (userRoles ?? []).some(r => r === "admin");

package/src/hooks/useFirebaseAuthController.ts

@@ -26,6 +26,28 @@ import { FirebaseApp } from "firebase/app";
 import { FirebaseAuthController, FirebaseSignInOption, FirebaseSignInProvider, FirebaseUserWrapper } from "../types";
 import type { User } from "@rebasepro/types";
 
+/**
+ * Resolve `user`'s roles through `defineRolesFor` and report whether they
+ * differ from the ones already applied.
+ *
+ * A plain function rather than a check inside the hook because the check that
+ * used to live there read `!equal(userRoles, userRoles)` — the local shadowed
+ * the state of the same name, so the fresh roles were compared to themselves,
+ * the guard was never true, and a `defineRolesFor` result arriving after the
+ * auth-state change never reached the controller.
+ */
+export async function resolveRoleRefresh(
+    defineRolesFor: (user: User) => Promise<string[] | undefined> | string[] | undefined,
+    user: User,
+    currentRoles: string[] | undefined
+): Promise<{ changed: boolean, roles: string[] | undefined }> {
+    const roles = await defineRolesFor(user);
+    return {
+        changed: !equal(currentRoles, roles),
+        roles
+    };
+}
+
 export interface FirebaseAuthControllerProps {
     loading?: boolean;
     firebaseApp?: FirebaseApp;
@@ -78,9 +100,12 @@ export const useFirebaseAuthController = <USER extends FirebaseUserWrapper = any
 
     const updateRoles = useCallback(async (user: User | null) => {
         if (defineRolesFor && user) {
-            const userRoles = await defineRolesFor(user);
-            if (!equal(userRoles, userRoles)) {
-                setUserRoles(userRoles);
+            const {
+                changed,
+                roles
+            } = await resolveRoleRefresh(defineRolesFor, user, userRoles);
+            if (changed) {
+                setUserRoles(roles);
             }
         }
     }, [defineRolesFor, userRoles]);

package/src/hooks/useFirebaseRealTimeDBDelegate.ts

@@ -1,6 +1,8 @@
 import { FirebaseApp } from "firebase/app";
 import {
     Database,
+    endAt,
+    equalTo,
     get,
     getDatabase,
     limitToFirst,
@@ -9,43 +11,189 @@ import {
     orderByKey,
     push,
     query,
+    QueryConstraint,
     ref,
     remove,
     set,
+    startAfter,
     startAt
 } from "firebase/database";
 import { useCallback } from "react";
-import { DataDriver, DeleteProps, FetchCollectionProps, FetchOneProps, FilterValues, ListenCollectionProps, ListenOneProps, SaveProps } from "@rebasepro/types";
+import { DataDriver, DeleteProps, FetchCollectionProps, FetchOneProps, FilterValues, ListenCollectionProps, ListenOneProps, SaveProps, WhereFilterOp } from "@rebasepro/types";
+
+/** The values the Realtime Database can order or bound a query by. */
+type RTDBFilterValue = string | number | boolean | null;
+
+/**
+ * A read expressed in the Realtime Database's own query model.
+ *
+ * @see planRTDBQuery
+ */
+export type RTDBQueryPlan = {
+    /** Child key to order — and therefore to bound — by. Absent means order by key. */
+    orderByChild?: string;
+    equalTo?: RTDBFilterValue;
+    startAt?: RTDBFilterValue;
+    /** Key the window starts after, exclusive. Only valid in key order. */
+    startAfter?: RTDBFilterValue;
+    endAt?: RTDBFilterValue;
+    limitToFirst?: number;
+    /**
+     * Rows to drop from the front of the result — the caller's `offset`, which
+     * the database has no constraint for. Applied by the caller, not by
+     * {@link rtdbConstraints}.
+     */
+    skip?: number;
+};
+
+const RTDB = "useFirebaseRTDBDelegate";
+
+const isRTDBValue = (value: unknown): value is RTDBFilterValue =>
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean";
+
+/**
+ * Translate a driver read into the Realtime Database's query model, or refuse it.
+ *
+ * The Realtime Database orders by a single child key per query and bounds that
+ * one key with `equalTo`/`startAt`/`endAt`. Nothing else is expressible: no
+ * second field, no descending order, no text search, no `or(...)` group.
+ *
+ * Everything beyond `limit` and `startAfter` used to be destructured out of the
+ * read and then never referenced, so a caller asking for `status == "draft"`
+ * was handed the entire collection, presented as the answer. A query this
+ * database cannot express is refused here instead — a caller that sees an error
+ * can fall back, a caller that sees the wrong rows cannot.
+ */
+export function planRTDBQuery<M extends Record<string, any>>({
+    filter,
+    orderBy,
+    order,
+    searchString,
+    logical,
+    limit,
+    offset,
+    startAfter: startAfterKey
+}: Pick<FetchCollectionProps<M>, "filter" | "orderBy" | "order" | "searchString" | "logical" | "limit" | "offset" | "startAfter">): RTDBQueryPlan {
+
+    if (searchString) {
+        throw new Error(`${RTDB}: the Realtime Database has no text search, so \`searchString\` cannot be applied. Index the data in a search service instead.`);
+    }
+    if (logical) {
+        throw new Error(`${RTDB}: the Realtime Database cannot evaluate \`or(...)\`/\`and(...)\` groups.`);
+    }
+    if (order === "desc") {
+        throw new Error(`${RTDB}: the Realtime Database only orders ascending, so \`order: "desc"\` cannot be applied.`);
+    }
+
+    const conditions: [string, WhereFilterOp, unknown][] = [];
+    Object.entries((filter ?? {}) as FilterValues<string>).forEach(([key, entry]) => {
+        if (!entry) return;
+        const tuples = Array.isArray(entry[0])
+            ? entry as [WhereFilterOp, unknown][]
+            : [entry as [WhereFilterOp, unknown]];
+        tuples.forEach(([op, value]) => conditions.push([key, op, value]));
+    });
+
+    const fields = Array.from(new Set(conditions.map(([key]) => key)));
+    if (fields.length > 1) {
+        throw new Error(`${RTDB}: the Realtime Database filters on one child key per query; this read asked for ${fields.join(", ")}.`);
+    }
+
+    const [field] = fields;
+    if (field && orderBy && orderBy !== field) {
+        throw new Error(`${RTDB}: a query is ordered by the key it filters on; cannot filter \`${field}\` while ordering by \`${orderBy}\`.`);
+    }
+
+    const orderChild = field ?? orderBy;
+    const plan: RTDBQueryPlan = orderChild ? { orderByChild: orderChild } : {};
+
+    for (const [key, op, value] of conditions) {
+        if (!isRTDBValue(value)) {
+            throw new Error(`${RTDB}: cannot bound \`${key}\` by a ${Array.isArray(value) ? "array" : typeof value} value; the Realtime Database compares strings, numbers, booleans and null.`);
+        }
+        if (op === "==") {
+            if (conditions.length > 1) {
+                throw new Error(`${RTDB}: \`==\` bounds a query on its own; it cannot be combined with another condition on \`${key}\`.`);
+            }
+            plan.equalTo = value;
+        } else if (op === ">=") {
+            plan.startAt = value;
+        } else if (op === "<=") {
+            plan.endAt = value;
+        } else {
+            throw new Error(`${RTDB}: the Realtime Database does not support the "${op}" operator (on \`${key}\`). It bounds a single child key with ==, >= and <=.`);
+        }
+    }
+
+    if (startAfterKey !== undefined) {
+        if (orderChild) {
+            throw new Error(`${RTDB}: \`startAfter\` pages in key order and cannot be combined with a filter or \`orderBy\`.`);
+        }
+        plan.startAfter = String(startAfterKey);
+    }
+
+    // No constraint expresses `offset`, so the window is read `offset` rows
+    // wider and the front is dropped. Dropping it instead — which is what this
+    // driver did — serves page one to every page, and a paginated walk that
+    // takes the driver at its word never terminates.
+    const skip = offset !== undefined && Number.isFinite(offset) && offset > 0
+        ? Math.floor(offset)
+        : 0;
+    if (skip > 0) {
+        plan.skip = skip;
+    }
+
+    if (limit !== undefined) {
+        plan.limitToFirst = limit + skip;
+    }
+
+    return plan;
+}
+
+/** The plan as Realtime Database query constraints. */
+function rtdbConstraints(plan: RTDBQueryPlan): QueryConstraint[] {
+    const constraints: QueryConstraint[] = [];
+    const bounded = plan.equalTo !== undefined ||
+        plan.startAt !== undefined ||
+        plan.startAfter !== undefined ||
+        plan.endAt !== undefined;
+
+    if (plan.orderByChild !== undefined) {
+        constraints.push(orderByChild(plan.orderByChild));
+    } else if (bounded) {
+        constraints.push(orderByKey());
+    }
+
+    if (plan.equalTo !== undefined) constraints.push(equalTo(plan.equalTo));
+    if (plan.startAt !== undefined) constraints.push(startAt(plan.startAt));
+    if (plan.startAfter !== undefined) constraints.push(startAfter(plan.startAfter));
+    if (plan.endAt !== undefined) constraints.push(endAt(plan.endAt));
+    if (plan.limitToFirst !== undefined) constraints.push(limitToFirst(plan.limitToFirst));
+
+    return constraints;
+}
 
 export function useFirebaseRTDBDelegate({ firebaseApp }: { firebaseApp?: FirebaseApp }): DataDriver {
 
-    const fetchCollection = useCallback(async <M extends Record<string, any>>({
-        path,
-        filter,
-        limit,
-        startAfter,
-        orderBy,
-        order,
-        searchString
-    }: FetchCollectionProps<M>): Promise<Record<string, unknown>[]> => {
+    const fetchCollection = useCallback(async <M extends Record<string, any>>(
+        props: FetchCollectionProps<M>
+    ): Promise<Record<string, unknown>[]> => {
         if (!firebaseApp) {
             throw new Error("Firebase app not provided");
         }
         const database = getDatabase(firebaseApp);
 
-        let dbQuery = query(ref(database, path));
-
-        // Example to apply "limit" and "startAfter"
-        if (startAfter !== undefined) {
-            dbQuery = query(dbQuery, orderByKey(), startAt(String(startAfter)));
-        }
-        if (limit !== undefined) {
-            dbQuery = query(dbQuery, limitToFirst(limit));
-        }
+        // Throws on any narrowing this database cannot express, rather than
+        // answering a filtered read with the whole collection.
+        const plan = planRTDBQuery(props);
+        const dbQuery = query(ref(database, props.path), ...rtdbConstraints(plan));
 
         const entity = await get(dbQuery);
         if (entity.exists()) {
-            return Object.entries(entity.val()).map(([id, values]) => ({
+            return Object.entries(entity.val()).slice(plan.skip ?? 0).map(([id, values]) => ({
                 ...(delegateToCMSModel(values) as Record<string, unknown>),
                 id
             }));
@@ -53,20 +201,26 @@ export function useFirebaseRTDBDelegate({ firebaseApp }: { firebaseApp?: Firebas
         return [];
     }, [firebaseApp]);
 
-    const listenCollection = useCallback(<M extends Record<string, any>>({
-        path,
-        onUpdate
-        // Realtime Database does not directly support onError in onValue
-    }: ListenCollectionProps<M>): () => void => {
+    const listenCollection = useCallback(<M extends Record<string, any>>(
+        props: ListenCollectionProps<M>
+    ): () => void => {
         if (!firebaseApp) {
             throw new Error("Firebase app not provided");
         }
         const database = getDatabase(firebaseApp);
 
-        const dbRef = ref(database, path);
-        const unsubscribe = onValue(dbRef, (entity) => {
+        const {
+            onUpdate,
+            onError
+        } = props;
+
+        // Same refusal as `fetchCollection`: this used to read the whole node
+        // regardless of what the subscription asked for.
+        const plan = planRTDBQuery(props);
+        const dbQuery = query(ref(database, props.path), ...rtdbConstraints(plan));
+        const unsubscribe = onValue(dbQuery, (entity) => {
             if (entity.exists()) {
-                const result: Record<string, unknown>[] = Object.entries(entity.val()).map(([id, values]) => ({
+                const result: Record<string, unknown>[] = Object.entries(entity.val()).slice(plan.skip ?? 0).map(([id, values]) => ({
                     ...(delegateToCMSModel(values) as Record<string, unknown>),
                     id
                 }));
@@ -74,7 +228,7 @@ export function useFirebaseRTDBDelegate({ firebaseApp }: { firebaseApp?: Firebas
             } else {
                 onUpdate([]);
             }
-        });
+        }, (error) => onError?.(error));
 
         return () => unsubscribe();
     }, [firebaseApp]);

package/src/hooks/useFirestoreDriver.ts

@@ -75,6 +75,35 @@ export type FirestoreDataDriver = DataDriver & {
     }) => Promise<boolean>,
 }
 
+/**
+ * The window a read has to ask Firestore for in order to honour `offset`.
+ *
+ * Firestore's web SDK has no `offset()` — it pages by cursor (`startAfter`)
+ * only. Callers that page by offset (`buildRebaseData`, and through it every
+ * `findAll()` and `iterate()`) were therefore served page one every time:
+ * `count` is a real server count, so `hasMore` never went false, the walk
+ * accumulated the same rows over and over, and it ended by tripping its row
+ * cap and reporting "matched more than N rows" — a condition that had not
+ * occurred.
+ *
+ * So the read asks for `offset + limit` documents and drops the first
+ * `offset`. Those documents are billed either way: Firestore charges for every
+ * document a cursor walks past, which is why `startAfter` is the cheap way to
+ * page and offset paging over a large collection is not.
+ */
+export function resolveOffsetWindow(
+    limit: number | undefined,
+    offset: number | undefined
+): { fetchLimit: number | undefined, skip: number } {
+    const skip = offset !== undefined && Number.isFinite(offset) && offset > 0
+        ? Math.floor(offset)
+        : 0;
+    return {
+        fetchLimit: limit === undefined ? undefined : limit + skip,
+        skip
+    };
+}
+
 /**
  * Use this hook to build a {@link DataDriver} based on Firestore
  * @param firebaseApp
@@ -298,11 +327,12 @@ export function useFirestoreDriver({
      * @param collection
      * @param filter
      * @param limit
+     * @param offset
      * @param startAfter
      * @param searchString
      * @param orderBy
      * @param order
-     * @return Function to cancel subscription
+     * @return The rows in the requested window
      * @see useCollection if you need this functionality implemented as a hook
      * @group Firestore
      */
@@ -310,6 +340,7 @@ export function useFirestoreDriver({
         path,
         filter,
         limit,
+        offset,
         startAfter,
         searchString,
         orderBy,
@@ -325,15 +356,21 @@ export function useFirestoreDriver({
         console.debug("Fetching collection", {
             path,
             limit,
+            offset,
             filter,
             startAfter,
             orderBy,
             order
         });
-        const query = buildQuery(resolvedPath, filter, orderBy, order, startAfter as unknown[] | undefined, limit, databaseId);
+        // Firestore has no `offset()`; see resolveOffsetWindow.
+        const {
+            fetchLimit,
+            skip
+        } = resolveOffsetWindow(limit, offset);
+        const query = buildQuery(resolvedPath, filter, orderBy, order, startAfter as unknown[] | undefined, fetchLimit, databaseId);
 
         const entity = await getDocs(query);
-        return entity.docs.map((doc) => createRowFromDocument(doc));
+        return entity.docs.slice(skip).map((doc) => createRowFromDocument(doc));
     }, [buildQuery]);
 
     /**