@rebasepro/firebase 0.13.0 → 0.13.1-canary.g06dbe5b

package/dist/components/RebaseFirebaseAppProps.d.ts

@@ -117,7 +117,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/dist/hooks/useBuildUserManagement.d.ts

@@ -35,6 +35,35 @@ export interface UserManagementDelegateParams<CONTROLLER extends AuthController<
      */
     allowDefaultRolesCreation?: boolean;
 }
+/**
+ * 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 declare function resolveAccessDecision({ loading, usersError, users, user }: {
+    loading: boolean;
+    usersError?: Error;
+    users: {
+        email?: string | null;
+    }[];
+    user: {
+        email?: string | null;
+    } | null;
+}): AccessDecision;
 /**
  * This hook is used to build a user management object that can be used to
  * manage users and roles in a Firestore backend.

package/dist/hooks/useFirebaseAuthController.d.ts

@@ -1,6 +1,20 @@
 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 declare function resolveRoleRefresh(defineRolesFor: (user: User) => Promise<string[] | undefined> | string[] | undefined, user: User, currentRoles: string[] | undefined): Promise<{
+    changed: boolean;
+    roles: string[] | undefined;
+}>;
 export interface FirebaseAuthControllerProps {
     loading?: boolean;
     firebaseApp?: FirebaseApp;

package/dist/hooks/useFirebaseRealTimeDBDelegate.d.ts

@@ -1,5 +1,43 @@
 import { FirebaseApp } from "firebase/app";
-import { DataDriver } from "@rebasepro/types";
+import { DataDriver, FetchCollectionProps } 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;
+};
+/**
+ * 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 declare 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;
 export declare function useFirebaseRTDBDelegate({ firebaseApp }: {
     firebaseApp?: FirebaseApp;
 }): DataDriver;
+export {};

package/dist/hooks/useFirestoreDriver.d.ts

@@ -36,6 +36,26 @@ export type FirestoreDataDriver = DataDriver & {
         collection?: CollectionConfig;
     }) => 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 declare function resolveOffsetWindow(limit: number | undefined, offset: number | undefined): {
+    fetchLimit: number | undefined;
+    skip: number;
+};
 /**
  * Use this hook to build a {@link DataDriver} based on Firestore
  * @param firebaseApp

package/dist/index.es.js

@@ -9,7 +9,7 @@ import { DocumentReference, GeoPoint as GeoPoint$1, Timestamp, VectorValue, coll
 import { COLLECTION_PATH_SEPARATOR, buildRebaseData, sortProperties, stripCollectionPath } from "@rebasepro/common";
 import Fuse from "fuse.js";
 import { getFunctions, httpsCallable } from "firebase/functions";
-import { get, getDatabase, limitToFirst, onValue, orderByChild, orderByKey, push, query as query$1, ref as ref$1, remove, set, startAt } from "firebase/database";
+import { endAt, equalTo, get, getDatabase, limitToFirst, onValue, orderByChild, orderByKey, push, query as query$1, ref as ref$1, remove, set, startAfter as startAfter$1, startAt } from "firebase/database";
 import { removeUndefined } from "@rebasepro/utils";
 import { AdminModeControllerProvider, ErrorView, ModeControllerProvider, Rebase, RebaseLogo, RebaseRoutes, SnackbarProvider, useBrowserTitleAndIcon, useBuildAdminModeController, useBuildLocalConfigurationPersistence, useBuildModeController, useModeController, useSnackbarController } from "@rebasepro/app";
 import { AppBar, CollectionRegistryContext, Drawer, NavigationStateContext, RebaseRoute, Scaffold, SideDialogs, SidePanelProvider, UrlContext, useBuildCollectionRegistryController, useBuildNavigationStateController, useBuildUrlController } from "@rebasepro/admin";
@@ -18,6 +18,23 @@ import { Navigate, Outlet, Route } from "react-router";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/hooks/useFirebaseAuthController.ts
 /**
+* 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.
+*/
+async function resolveRoleRefresh(defineRolesFor, user, currentRoles) {
+	const roles = await defineRolesFor(user);
+	return {
+		changed: !deepEqual(currentRoles, roles),
+		roles
+	};
+}
+/**
 * Use this hook to build an {@link AuthController} based on Firebase Auth
 * @group Firebase
 */
@@ -44,8 +61,8 @@ var useFirebaseAuthController = ({ loading, firebaseApp, signInOptions, onSignOu
 	}, [loading]);
 	const updateRoles = useCallback(async (user) => {
 		if (defineRolesFor && user) {
-			const userRoles = await defineRolesFor(user);
-			if (!deepEqual(userRoles, userRoles)) setUserRoles(userRoles);
+			const { changed, roles } = await resolveRoleRefresh(defineRolesFor, user, userRoles);
+			if (changed) setUserRoles(roles);
 		}
 	}, [defineRolesFor, userRoles]);
 	useEffect(() => {
@@ -944,6 +961,29 @@ function buildRebaseSearchController(options) {
 //#endregion
 //#region src/hooks/useFirestoreDriver.ts
 /**
+* 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.
+*/
+function resolveOffsetWindow(limit, offset) {
+	const skip = offset !== void 0 && Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 0;
+	return {
+		fetchLimit: limit === void 0 ? void 0 : limit + skip,
+		skip
+	};
+}
+/**
 * Use this hook to build a {@link DataDriver} based on Firestore
 * @param firebaseApp
 * @param textSearchControllerBuilder
@@ -964,7 +1004,7 @@ function useFirestoreDriver({ firebaseApp, textSearchControllerBuilder, firestor
 		localTextSearchEnabled,
 		textSearchControllerBuilder
 	]);
-	const buildQuery = useCallback((path, filter, orderBy$1, order, startAfter$1, limit$1, databaseId) => {
+	const buildQuery = useCallback((path, filter, orderBy$1, order, startAfter$2, limit$1, databaseId) => {
 		if (!firebaseApp) throw Error("useFirestoreDriver Firebase not initialised");
 		const firestore = databaseId ? getFirestore(firebaseApp, databaseId) : getFirestore(firebaseApp);
 		const collectionReference = collection(firestore, path);
@@ -983,7 +1023,7 @@ function useFirestoreDriver({ firebaseApp, textSearchControllerBuilder, firestor
 			queryParams.push(where(key, op, rebaseToFirestoreModel(value, firestore)));
 		});
 		if (orderBy$1 && order) queryParams.push(orderBy(orderBy$1, order));
-		if (startAfter$1) queryParams.push(startAfter(startAfter$1));
+		if (startAfter$2) queryParams.push(startAfter(startAfter$2));
 		if (limit$1) queryParams.push(limit(limit$1));
 		return query(collectionReference, ...queryParams);
 	}, [firebaseApp]);
@@ -1067,26 +1107,29 @@ function useFirestoreDriver({ firebaseApp, textSearchControllerBuilder, firestor
 	* @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
 	*/
-	const fetchCollection = useCallback(async ({ path, filter, limit, startAfter, searchString, orderBy, order, collection }) => {
+	const fetchCollection = useCallback(async ({ path, filter, limit, offset, startAfter, searchString, orderBy, order, collection }) => {
 		const databaseId = collection?.databaseId;
 		const resolvedPath = path;
 		console.debug("Fetching collection", {
 			path,
 			limit,
+			offset,
 			filter,
 			startAfter,
 			orderBy,
 			order
 		});
-		return (await getDocs(buildQuery(resolvedPath, filter, orderBy, order, startAfter, limit, databaseId))).docs.map((doc) => createRowFromDocument(doc));
+		const { fetchLimit, skip } = resolveOffsetWindow(limit, offset);
+		return (await getDocs(buildQuery(resolvedPath, filter, orderBy, order, startAfter, fetchLimit, databaseId))).docs.slice(skip).map((doc) => createRowFromDocument(doc));
 	}, [buildQuery]);
 	/**
 	* Listen to a entities in a given path
@@ -1384,30 +1427,99 @@ function buildTextSearchControllerWithLocalSearch({ textSearchControllerBuilder,
 }
 //#endregion
 //#region src/hooks/useFirebaseRealTimeDBDelegate.ts
+var RTDB = "useFirebaseRTDBDelegate";
+var isRTDBValue = (value) => 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.
+*/
+function planRTDBQuery({ filter, orderBy, order, searchString, logical, limit, offset, startAfter: startAfterKey }) {
+	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 = [];
+	Object.entries(filter ?? {}).forEach(([key, entry]) => {
+		if (!entry) return;
+		(Array.isArray(entry[0]) ? entry : [entry]).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 = 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 !== void 0) {
+		if (orderChild) throw new Error(`${RTDB}: \`startAfter\` pages in key order and cannot be combined with a filter or \`orderBy\`.`);
+		plan.startAfter = String(startAfterKey);
+	}
+	const skip = offset !== void 0 && Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 0;
+	if (skip > 0) plan.skip = skip;
+	if (limit !== void 0) plan.limitToFirst = limit + skip;
+	return plan;
+}
+/** The plan as Realtime Database query constraints. */
+function rtdbConstraints(plan) {
+	const constraints = [];
+	const bounded = plan.equalTo !== void 0 || plan.startAt !== void 0 || plan.startAfter !== void 0 || plan.endAt !== void 0;
+	if (plan.orderByChild !== void 0) constraints.push(orderByChild(plan.orderByChild));
+	else if (bounded) constraints.push(orderByKey());
+	if (plan.equalTo !== void 0) constraints.push(equalTo(plan.equalTo));
+	if (plan.startAt !== void 0) constraints.push(startAt(plan.startAt));
+	if (plan.startAfter !== void 0) constraints.push(startAfter$1(plan.startAfter));
+	if (plan.endAt !== void 0) constraints.push(endAt(plan.endAt));
+	if (plan.limitToFirst !== void 0) constraints.push(limitToFirst(plan.limitToFirst));
+	return constraints;
+}
 function useFirebaseRTDBDelegate({ firebaseApp }) {
 	return {
 		key: "firebase_rtdb",
-		fetchCollection: useCallback(async ({ path, filter, limit, startAfter, orderBy, order, searchString }) => {
+		fetchCollection: useCallback(async (props) => {
 			if (!firebaseApp) throw new Error("Firebase app not provided");
-			let dbQuery = query$1(ref$1(getDatabase(firebaseApp), path));
-			if (startAfter !== void 0) dbQuery = query$1(dbQuery, orderByKey(), startAt(String(startAfter)));
-			if (limit !== void 0) dbQuery = query$1(dbQuery, limitToFirst(limit));
-			const entity = await get(dbQuery);
-			if (entity.exists()) return Object.entries(entity.val()).map(([id, values]) => ({
+			const database = getDatabase(firebaseApp);
+			const plan = planRTDBQuery(props);
+			const entity = await get(query$1(ref$1(database, props.path), ...rtdbConstraints(plan)));
+			if (entity.exists()) return Object.entries(entity.val()).slice(plan.skip ?? 0).map(([id, values]) => ({
 				...delegateToCMSModel(values),
 				id
 			}));
 			return [];
 		}, [firebaseApp]),
-		listenCollection: useCallback(({ path, onUpdate }) => {
+		listenCollection: useCallback((props) => {
 			if (!firebaseApp) throw new Error("Firebase app not provided");
-			const unsubscribe = onValue(ref$1(getDatabase(firebaseApp), path), (entity) => {
-				if (entity.exists()) onUpdate(Object.entries(entity.val()).map(([id, values]) => ({
-					...delegateToCMSModel(values),
-					id
-				})));
-				else onUpdate([]);
-			});
+			const database = getDatabase(firebaseApp);
+			const { onUpdate, onError } = props;
+			const plan = planRTDBQuery(props);
+			const unsubscribe = onValue(query$1(ref$1(database, props.path), ...rtdbConstraints(plan)), (entity) => {
+				if (entity.exists()) {
+					const result = Object.entries(entity.val()).slice(plan.skip ?? 0).map(([id, values]) => ({
+						...delegateToCMSModel(values),
+						id
+					}));
+					onUpdate(result);
+				} else onUpdate([]);
+			}, (error) => onError?.(error));
 			return () => unsubscribe();
 		}, [firebaseApp]),
 		fetchOne: useCallback(async ({ path, id }) => {
@@ -1512,6 +1624,20 @@ function useRecaptcha() {
 //#endregion
 //#region src/hooks/useBuildUserManagement.tsx
 /**
+* 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.
+*/
+function resolveAccessDecision({ loading, usersError, users, user }) {
+	if (loading) return "loading";
+	if (!user) return "no-user";
+	if (usersError) return "users-unreadable";
+	if (users.length === 0) return "bootstrap";
+	return users.some((u) => u.email?.toLowerCase() === user.email?.toLowerCase()) ? "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.
 * @param authController
@@ -1675,17 +1801,27 @@ function useBuildUserManagement({ authController, dataSourceDelegate, roles: rol
 		return mgmtUser.roles;
 	}, [usersWithRoleIds]);
 	const accessGate = useCallback(({ user }) => {
-		if (loading) return false;
-		if (user === null) {
+		const decision = resolveAccessDecision({
+			loading,
+			usersError,
+			users,
+			user
+		});
+		if (decision === "loading") return false;
+		if (decision === "no-user") {
 			console.warn("User is null, returning");
 			return false;
 		}
-		if (users.length === 0) {
+		if (decision === "users-unreadable") {
+			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;
 		}
 		const mgmtUser = users.find((u) => u.email?.toLowerCase() === user?.email?.toLowerCase());
-		if (mgmtUser) {
+		if (decision === "known-user" && mgmtUser && user) {
 			const needsUidUpdate = mgmtUser.uid !== user.uid;
 			const needsPhotoUpdate = user.photoURL && mgmtUser.photoURL !== user.photoURL;
 			if (needsUidUpdate || needsPhotoUpdate) {
@@ -1704,7 +1840,11 @@ function useBuildUserManagement({ authController, dataSourceDelegate, roles: rol
 			return true;
 		}
 		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) : void 0;
 	const isAdmin = (userRoles ?? []).some((r) => r === "admin");
 	useEffect(() => {
@@ -2649,6 +2789,6 @@ function RebaseFirebaseApp({ name, logo, logoDark, accessGate, collections, view
 	}) });
 }
 //#endregion
-export { FirebaseLoginView, LoginButton, RECAPTCHA_CONTAINER_ID, RebaseFirebaseApp, buildCollectionId, buildExternalSearchController, buildPineconeSearchController, buildRebaseSearchController, docToCollection, docsToCollectionTree, firestoreToRebaseModel, getFirestoreDataInPath, localSearchControllerBuilder, performAlgoliaTextSearch, performPineconeTextSearch, rebaseToFirestoreModel, useAppCheck, useBuildUserManagement, useFirebaseAccessGate, useFirebaseAuthController, useFirebaseRTDBDelegate, useFirebaseStorageSource, useFirestoreDriver, useInitialiseFirebase, useRecaptcha };
+export { FirebaseLoginView, LoginButton, RECAPTCHA_CONTAINER_ID, RebaseFirebaseApp, buildCollectionId, buildExternalSearchController, buildPineconeSearchController, buildRebaseSearchController, docToCollection, docsToCollectionTree, firestoreToRebaseModel, getFirestoreDataInPath, localSearchControllerBuilder, performAlgoliaTextSearch, performPineconeTextSearch, planRTDBQuery, rebaseToFirestoreModel, resolveAccessDecision, resolveOffsetWindow, resolveRoleRefresh, useAppCheck, useBuildUserManagement, useFirebaseAccessGate, useFirebaseAuthController, useFirebaseRTDBDelegate, useFirebaseStorageSource, useFirestoreDriver, useInitialiseFirebase, useRecaptcha };
 
 //# sourceMappingURL=index.es.js.map