react-query-firebase 1.0.0

package/src/analytics/useLogEvent.ts

@@ -0,0 +1,27 @@
+import { logEvent } from "firebase/analytics";
+import { useAnalytics } from "../useAnalytics";
+import { useCallback, useMemo } from "react";
+
+type UseLogEventOptions = {
+    eventName: string;
+    eventParams?: {
+        [key: string]: unknown;
+    };
+};
+
+export const useLogEvent = ({ eventName, eventParams }: UseLogEventOptions) => {
+    const analytics = useAnalytics();
+
+    const logEventCallback = useCallback(() => {
+        if (analytics) {
+            logEvent(analytics, eventName, eventParams);
+        }
+    }, [eventName, eventParams]);
+
+    return useMemo(
+        () => ({
+            logEvent: logEventCallback
+        }),
+        [logEventCallback]
+    );
+};

package/src/auth/index.ts

@@ -0,0 +1,9 @@
+export * from "./mutation-keys";
+export * from "./useCreateUserWitEmailAndPasswordMutation";
+export * from "./useSendEmailVerificationMutation";
+export * from "./useSignInWitEmailAndPasswordMutation";
+export * from "./useCurrentUser";
+export * from "./useAuthStateReady";
+export * from "./useSignInWitRedirectMutation";
+export * from "./useUpdateProfileMutation";
+export * from "./useSignOutMutation";

package/src/auth/mutation-keys.ts

@@ -0,0 +1,19 @@
+export const CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY = [
+    "FIREBASE",
+    "AUTH",
+    "CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION"
+] as const;
+export const SEND_EMAIL_VERIFICATION_MUTATION_KEY = ["FIREBASE", "AUTH", "SEND_EMAIL_VERIFICATION_MUTATION"] as const;
+export const SIGN_IN_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY = [
+    "FIREBASE",
+    "AUTH",
+    "SIGN_IN_WITH_EMAIL_AND_PASSWORD_MUTATION"
+] as const;
+export const SIGN_IN_WITH_REDIRECT_MUTATION_KEY = ["FIREBASE", "AUTH", "SIGN_IN_WITH_REDIRECT_MUTATION"] as const;
+export const SIGN_OUT_MUTATION_KEY = ["FIREBASE", "AUTH", "SIGN_OUT"] as const;
+export const REAUTHENTICATE_WITH_REDIRECT_MUTATION_KEY = ["FIREBASE", "AUTH", "REAUTHENTICATE_WITH_REDIRECT"] as const;
+export const REAUTHENTICATE_WITH_CREDENTIAL_MUTATION_KEY = [
+    "FIREBASE",
+    "AUTH",
+    "REAUTHENTICATE_WITH_CREDENTIAL"
+] as const;

package/src/auth/useAuthStateReady.ts

@@ -0,0 +1,19 @@
+import { useAuth } from "../useAuth";
+import { useCallback, useEffect, useState } from "react";
+
+export const useAuthStateReady = () => {
+    const firebaseAuth = useAuth();
+
+    const [isAuthStateReady, setIsAuthStateReady] = useState(false);
+
+    const callback = useCallback(async () => {
+        await firebaseAuth.authStateReady();
+        setIsAuthStateReady(true);
+    }, [isAuthStateReady]);
+
+    useEffect(() => {
+        callback();
+    }, [callback]);
+
+    return isAuthStateReady;
+};

package/src/auth/useCreateUserWitEmailAndPasswordMutation.ts

@@ -0,0 +1,26 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { createUserWithEmailAndPassword, UserCredential } from "firebase/auth";
+import { useAuth } from "../useAuth";
+import { FirebaseError } from "firebase/app";
+import { CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY } from "./mutation-keys";
+
+export type UseCreateUserWitEmailAndPasswordMutationVariables = {
+    email: string;
+    password: string;
+};
+
+export const useCreateUserWitEmailAndPasswordMutation = <TContext = unknown>(
+    options: Omit<
+        UseMutationOptions<UserCredential, FirebaseError, UseCreateUserWitEmailAndPasswordMutationVariables, TContext>,
+        "mutationKey" | "mutationFn"
+    > = {}
+) => {
+    const firebaseAuth = useAuth();
+
+    return useMutation({
+        ...options,
+        mutationFn: async ({ email, password }: UseCreateUserWitEmailAndPasswordMutationVariables) =>
+            await createUserWithEmailAndPassword(firebaseAuth, email, password),
+        mutationKey: CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY
+    });
+};

package/src/auth/useCurrentUser.ts

@@ -0,0 +1,19 @@
+import { useAuth } from "../useAuth";
+import { useEffect, useState } from "react";
+
+export const useCurrentUser = () => {
+    const firebaseAuth = useAuth();
+
+    const [currentUser, setCurrentUser] = useState(firebaseAuth.currentUser);
+
+    useEffect(() => {
+        const unsubscribe = firebaseAuth.onAuthStateChanged((user) => {
+            setCurrentUser(user);
+        });
+        return () => {
+            unsubscribe();
+        };
+    }, [currentUser?.uid ?? ""]);
+
+    return currentUser;
+};

package/src/auth/useIdToken.ts

@@ -0,0 +1,35 @@
+import { useCallback, useEffect, useState } from "react";
+import { useCurrentUser } from "./useCurrentUser";
+
+export const useIdToken = () => {
+    const currentUser = useCurrentUser();
+    const [idToken, setIdToken] = useState("");
+
+    const callback = useCallback(async () => {
+        if (!currentUser) {
+            setIdToken("");
+            return;
+        }
+
+        const idToken = await currentUser.getIdToken();
+        setIdToken(idToken);
+    }, [currentUser, idToken]);
+
+    const refresh = useCallback(async () => {
+        if (!currentUser) {
+            return;
+        }
+
+        const idToken = await currentUser.getIdToken(true);
+        setIdToken(idToken);
+    }, [currentUser, idToken]);
+
+    useEffect(() => {
+        callback();
+    }, [currentUser?.uid ?? ""]);
+
+    return {
+        idToken,
+        refresh
+    };
+};

package/src/auth/useReauthenticateWitCredentialMutation.ts

@@ -0,0 +1,23 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { reauthenticateWithCredential, User, AuthCredential, UserCredential } from "firebase/auth";
+import { REAUTHENTICATE_WITH_CREDENTIAL_MUTATION_KEY } from "./mutation-keys";
+import { FirebaseError } from "firebase/app";
+
+export type UseReauthenticateWitCredentialMutationVariables = {
+    credential: AuthCredential;
+    user: User;
+};
+
+export const useReauthenticateWitCredentialMutation = <TContext = unknown>(
+    options: Omit<
+        UseMutationOptions<UserCredential, FirebaseError, UseReauthenticateWitCredentialMutationVariables, TContext>,
+        "mutationKey" | "mutationFn"
+    > = {}
+) => {
+    return useMutation({
+        ...options,
+        mutationFn: async ({ credential, user }: UseReauthenticateWitCredentialMutationVariables) =>
+            reauthenticateWithCredential(user, credential),
+        mutationKey: REAUTHENTICATE_WITH_CREDENTIAL_MUTATION_KEY
+    });
+};

package/src/auth/useReauthenticateWitRedirectMutation.ts

@@ -0,0 +1,29 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { reauthenticateWithRedirect, AuthProvider, PopupRedirectResolver, User } from "firebase/auth";
+
+import { REAUTHENTICATE_WITH_REDIRECT_MUTATION_KEY } from "./mutation-keys";
+import { FirebaseError } from "firebase/app";
+
+export type UseReauthenticateWitRedirectMutationVariables = {
+    authProvider: AuthProvider;
+    popupRedirectResolver?: PopupRedirectResolver;
+    user: User;
+};
+
+export const useReauthenticateWitRedirectMutation = <TContext = unknown>(
+    options: Omit<
+        UseMutationOptions<void, FirebaseError, UseReauthenticateWitRedirectMutationVariables, TContext>,
+        "mutationKey" | "mutationFn"
+    > = {}
+) => {
+    return useMutation({
+        ...options,
+        mutationFn: async ({
+            authProvider,
+            user,
+            popupRedirectResolver
+        }: UseReauthenticateWitRedirectMutationVariables) =>
+            reauthenticateWithRedirect(user, authProvider, popupRedirectResolver),
+        mutationKey: REAUTHENTICATE_WITH_REDIRECT_MUTATION_KEY
+    });
+};

package/src/auth/useSendEmailVerificationMutation.ts

@@ -0,0 +1,22 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { sendEmailVerification, User } from "firebase/auth";
+
+import { SEND_EMAIL_VERIFICATION_MUTATION_KEY } from "./mutation-keys";
+import { FirebaseError } from "firebase/app";
+
+export type UseSendEmailVerificationMutationVariables = {
+    user: User;
+};
+
+export const useSendEmailVerificationMutation = <TContext = unknown>(
+    options: Omit<
+        UseMutationOptions<void, FirebaseError, UseSendEmailVerificationMutationVariables, TContext>,
+        "queryKey" | "queryFn"
+    > = {}
+) => {
+    return useMutation({
+        ...options,
+        mutationFn: async ({ user }) => await sendEmailVerification(user),
+        mutationKey: SEND_EMAIL_VERIFICATION_MUTATION_KEY
+    });
+};

package/src/auth/useSignInWitEmailAndPasswordMutation.ts

@@ -0,0 +1,27 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { signInWithEmailAndPassword, UserCredential } from "firebase/auth";
+
+import { useAuth } from "../useAuth";
+import { SIGN_IN_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY } from "./mutation-keys";
+import { FirebaseError } from "firebase/app";
+
+export type UseSignInWitEmailAndPasswordMutationVariables = {
+    email: string;
+    password: string;
+};
+
+export const useSignInWitEmailAndPasswordMutation = <TContext = unknown>(
+    options: Omit<
+        UseMutationOptions<UserCredential, FirebaseError, UseSignInWitEmailAndPasswordMutationVariables, TContext>,
+        "mutationKey" | "mutationFn"
+    > = {}
+) => {
+    const firebaseAuth = useAuth();
+
+    return useMutation({
+        ...options,
+        mutationFn: async ({ email, password }: UseSignInWitEmailAndPasswordMutationVariables) =>
+            signInWithEmailAndPassword(firebaseAuth, email, password),
+        mutationKey: SIGN_IN_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY
+    });
+};

package/src/auth/useSignInWitRedirectMutation.ts

@@ -0,0 +1,27 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { signInWithRedirect, AuthProvider, PopupRedirectResolver } from "firebase/auth";
+
+import { useAuth } from "../useAuth";
+import { SIGN_IN_WITH_REDIRECT_MUTATION_KEY } from "./mutation-keys";
+import { FirebaseError } from "firebase/app";
+
+export type UseSignInWitRedirectMutationVariables = {
+    authProvider: AuthProvider;
+    popupRedirectResolver?: PopupRedirectResolver;
+};
+
+export const useSignInWitRedirectMutation = <TContext = unknown>(
+    options: Omit<
+        UseMutationOptions<void, FirebaseError, UseSignInWitRedirectMutationVariables, TContext>,
+        "mutationKey" | "mutationFn"
+    > = {}
+) => {
+    const firebaseAuth = useAuth();
+
+    return useMutation({
+        ...options,
+        mutationFn: async ({ authProvider, popupRedirectResolver }: UseSignInWitRedirectMutationVariables) =>
+            signInWithRedirect(firebaseAuth, authProvider, popupRedirectResolver),
+        mutationKey: SIGN_IN_WITH_REDIRECT_MUTATION_KEY
+    });
+};

package/src/auth/useSignOutMutation.ts

@@ -0,0 +1,18 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { signOut } from "firebase/auth";
+
+import { SIGN_OUT_MUTATION_KEY } from "./mutation-keys";
+import { FirebaseError } from "firebase/app";
+import { useAuth } from "../useAuth";
+
+export const useSignOutMutation = <TContext = unknown>(
+    options: Omit<UseMutationOptions<void, FirebaseError, void, TContext>, "queryKey" | "queryFn"> = {}
+) => {
+    const firebaseAuth = useAuth();
+
+    return useMutation({
+        ...options,
+        mutationFn: async () => await signOut(firebaseAuth),
+        mutationKey: SIGN_OUT_MUTATION_KEY
+    });
+};

package/src/auth/useUpdateProfileMutation.ts

@@ -0,0 +1,23 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { updateProfile, User } from "firebase/auth";
+import { FirebaseError } from "firebase/app";
+import { CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY } from "./mutation-keys";
+
+export type UseUpdateProfileMutationVariables = {
+    displayName?: string;
+    user: User;
+};
+
+export const useUpdateProfileMutation = <TContext = unknown>(
+    options: Omit<
+        UseMutationOptions<void, FirebaseError, UseUpdateProfileMutationVariables, TContext>,
+        "mutationKey" | "mutationFn"
+    > = {}
+) => {
+    return useMutation({
+        ...options,
+        mutationFn: async ({ displayName, user }: UseUpdateProfileMutationVariables) =>
+            await updateProfile(user, { displayName }),
+        mutationKey: CREATE_USER_WITH_EMAIL_AND_PASSWORD_MUTATION_KEY
+    });
+};

package/src/firestore/index.ts

@@ -0,0 +1,14 @@
+export * from "./useAddDocMutation";
+export * from "./useBatchWrite";
+export * from "./useCollectionReference";
+export * from "./useCompositeFilter";
+export * from "./useCountQuery";
+export * from "./useDeleteDocMutation";
+export * from "./useDocReference";
+export * from "./useDocReferences";
+export * from "./useGetDocData";
+export * from "./useInfiniteQuery";
+export * from "./useQuery";
+export * from "./useRunTransaction";
+export * from "./useSetDocMutation";
+export * from "./useUpdateDocMutation";

package/src/firestore/useAddDocMutation.ts

@@ -0,0 +1,51 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import {
+    DocumentData,
+    addDoc,
+    WithFieldValue,
+    CollectionReference,
+    getDoc,
+    FirestoreDataConverter
+} from "firebase/firestore";
+
+import { FirebaseError } from "firebase/app";
+import { useMemo } from "react";
+
+export type UseAddDocMutationValues<AppModelType> = {
+    data: WithFieldValue<AppModelType>;
+};
+
+export type UseAddDocMutationOptions<
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData,
+    TContext = unknown
+> = {
+    reference: CollectionReference<AppModelType, DbModelType>;
+    converter?: FirestoreDataConverter<AppModelType, DbModelType>;
+    options?: Omit<
+        UseMutationOptions<AppModelType, FirebaseError, UseAddDocMutationValues<AppModelType>, TContext>,
+        "mutationFn" | "mutationKey"
+    >;
+};
+
+export const useAddDocMutation = <
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData,
+    TContext = unknown
+>({
+    reference,
+    converter,
+    options = {}
+}: UseAddDocMutationOptions<AppModelType, DbModelType, TContext>) => {
+    const mutationKey = useMemo(() => [reference.path], [reference.path]);
+
+    return useMutation({
+        ...options,
+        mutationFn: async ({ data }) => {
+            const docRef = await addDoc<AppModelType, DbModelType>(reference, data);
+            const docSnap = await getDoc(converter ? docRef.withConverter(converter) : docRef);
+            return docSnap.data() as AppModelType;
+        },
+        mutationKey
+    });
+};

package/src/firestore/useBatchWrite.ts

@@ -0,0 +1,24 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { writeBatch, WriteBatch } from "firebase/firestore";
+
+import { FirebaseError } from "firebase/app";
+import { useFirestore } from "../useFirestore";
+
+export type UseBatchWriteVariables = (batch: WriteBatch) => Promise<void> | void;
+
+export type UseBatchWriteOptions<TContext = unknown> = {
+    options?: Omit<UseMutationOptions<void, FirebaseError, UseBatchWriteVariables, TContext>, "mutationFn">;
+};
+
+export const useBatchWrite = <TContext = unknown>({ options = {} }: UseBatchWriteOptions<TContext> = {}) => {
+    const db = useFirestore();
+
+    return useMutation({
+        ...options,
+        mutationFn: async (batchWriteFn) => {
+            const batch = writeBatch(db);
+            await batchWriteFn(batch);
+            return batch.commit();
+        }
+    });
+};

package/src/firestore/useCollectionReference.ts

@@ -0,0 +1,26 @@
+import { collection, CollectionReference, DocumentData, DocumentReference } from "firebase/firestore";
+
+import { useMemo } from "react";
+import { useFirestore } from "../useFirestore";
+
+export type UseCollectionReferenceOptions<AppModelType, DbModelType extends DocumentData = DocumentData> = {
+    reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
+    path: string;
+    pathSegments?: string[];
+};
+
+export const useCollectionReference = <AppModelType, DbModelType extends DocumentData = DocumentData>({
+    path,
+    reference,
+    pathSegments
+}: UseCollectionReferenceOptions<AppModelType, DbModelType>) => {
+    const db = useFirestore();
+
+    return useMemo(() => {
+        return !reference
+            ? collection(db, path || "", ...(pathSegments || []))
+            : reference.type === "collection"
+              ? collection(reference, path, ...(pathSegments || []))
+              : collection(reference, path, ...(pathSegments || []));
+    }, [path, reference?.path, pathSegments]);
+};

package/src/firestore/useCompositeFilter.ts

@@ -0,0 +1,68 @@
+import {
+    DocumentData,
+    QueryCompositeFilterConstraint,
+    QueryFilterConstraint,
+    WhereFilterOp,
+    and,
+    documentId,
+    or,
+    where
+} from "firebase/firestore";
+import { useMemo } from "react";
+
+type CompositeFilterDocumentData = DocumentData;
+
+export type QueryElement<DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData> =
+    Partial<QueryCompositeFilterConstraint> & {
+        children?: QueryElement[];
+        field?: keyof (DbModelType & { documentId?: string[] });
+        value?: DbModelType[keyof DbModelType];
+        op?: WhereFilterOp;
+    };
+
+export type CompositeFilter<DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData> =
+    QueryCompositeFilterConstraint & {
+        children: QueryElement<DbModelType & { documentId?: string[] }>[];
+    };
+
+export type UseCompositeFilter<DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData> = {
+    query?: CompositeFilter<DbModelType>;
+};
+
+const buildCompositeQuery = <DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData>(
+    query: QueryElement<DbModelType>
+): QueryFilterConstraint | null => {
+    if (query.children) {
+        const queryConstraints = query.children
+            .map((subQuery) => buildCompositeQuery(subQuery))
+            .filter<QueryFilterConstraint>((constraint) => !!constraint);
+
+        if (queryConstraints.length <= 0) {
+            return null;
+        }
+
+        return (query as CompositeFilter).type === "or" ? or(...queryConstraints) : and(...queryConstraints);
+    }
+
+    if (query.field && query.op) {
+        return where(query.field === "documentId" ? documentId() : (query.field as string), query.op, query.value);
+    }
+
+    return null;
+};
+
+export const useCompositeFilter = <DbModelType extends CompositeFilterDocumentData = CompositeFilterDocumentData>({
+    query
+}: UseCompositeFilter<DbModelType>) => {
+    return useMemo(() => {
+        const queryConstraints =
+            query?.children?.map?.((subQuery) => buildCompositeQuery(subQuery))?.filter<QueryFilterConstraint>?.(
+                (constraint) => !!constraint
+            ) ?? [];
+
+        if (queryConstraints.length <= 0) {
+            return undefined;
+        }
+        return query?.type === "or" ? or(...queryConstraints) : and(...queryConstraints);
+    }, [query]);
+};

package/src/firestore/useCountQuery.ts

@@ -0,0 +1,51 @@
+import {
+    DocumentData,
+    getCountFromServer,
+    Query,
+    query,
+    QueryCompositeFilterConstraint,
+    QueryConstraint,
+    QueryNonFilterConstraint
+} from "firebase/firestore";
+
+import {
+    UseQueryResult,
+    useQuery as useReactQuery,
+    UseQueryOptions as UseReactQueryOptions
+} from "@tanstack/react-query";
+
+type UseCountQueryOptions<
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData
+> = {
+    options: Omit<UseReactQueryOptions<number, Error, number>, "queryFn"> &
+        Required<Pick<UseReactQueryOptions<number, Error, number>, "queryKey">>;
+    query: Query<AppModelType, DbModelType>;
+    queryConstraints?: QueryConstraint[] | QueryNonFilterConstraint[];
+    compositeFilter?: QueryCompositeFilterConstraint;
+};
+
+export const useCountQuery = <
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData
+>({
+    options,
+    query: queryReference,
+    queryConstraints = [],
+    compositeFilter
+}: UseCountQueryOptions<AppModelType, DbModelType>): UseQueryResult<number> => {
+    return useReactQuery({
+        ...options,
+        queryFn: async () => {
+            const queryToExecute = compositeFilter
+                ? query(queryReference, compositeFilter, ...(queryConstraints as QueryNonFilterConstraint[]))
+                : query(queryReference, ...queryConstraints);
+
+            const querySnapshot = await getCountFromServer(queryToExecute);
+            if (querySnapshot) {
+                return querySnapshot.data().count;
+            }
+            return 0;
+        }
+    });
+};

package/src/firestore/useDeleteDocMutation.ts

@@ -0,0 +1,40 @@
+import { useMutation, UseMutationOptions } from "@tanstack/react-query";
+import { DocumentData, deleteDoc, WithFieldValue, DocumentReference } from "firebase/firestore";
+
+import { FirebaseError } from "firebase/app";
+import { useMemo } from "react";
+
+export type UseDeleteDocMutationValues<AppModelType> = {
+    data: WithFieldValue<AppModelType>;
+};
+
+export type UseDeleteDocMutationOptions<
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData,
+    TContext = unknown
+> = {
+    reference: DocumentReference<AppModelType, DbModelType> | null;
+    options?: Omit<UseMutationOptions<void, FirebaseError, void, TContext>, "mutationFn" | "mutationKey">;
+};
+
+export const useDeleteDocMutation = <
+    AppModelType extends DocumentData = DocumentData,
+    DbModelType extends DocumentData = DocumentData,
+    TContext = unknown
+>({
+    reference,
+    options = {}
+}: UseDeleteDocMutationOptions<AppModelType, DbModelType, TContext>) => {
+    const mutationKey = useMemo(() => [reference?.path], [reference?.path]);
+
+    return useMutation({
+        ...options,
+        mutationFn: async () => {
+            if (!reference) {
+                throw new Error("Reference is undefined");
+            }
+            await deleteDoc<AppModelType, DbModelType>(reference);
+        },
+        mutationKey
+    });
+};

package/src/firestore/useDocReference.ts

@@ -0,0 +1,44 @@
+import { doc, CollectionReference, DocumentData, DocumentReference, Firestore } from "firebase/firestore";
+
+import { useEffect, useRef } from "react";
+import { useFirestore } from "../useFirestore";
+
+export type UseDocReferenceOptions<AppModelType, DbModelType extends DocumentData = DocumentData> = {
+    reference?: CollectionReference<AppModelType, DbModelType> | DocumentReference<AppModelType, DbModelType>;
+    path?: string;
+    pathSegments?: string[];
+};
+
+const getDocReference = <AppModelType, DbModelType extends DocumentData = DocumentData>(
+    db: Firestore,
+    { path, pathSegments, reference }: UseDocReferenceOptions<AppModelType, DbModelType>
+) => {
+    if (!path) {
+        return null;
+    }
+
+    return (
+        !reference
+            ? doc(db, path || "", ...(pathSegments || []))
+            : reference.type === "collection"
+              ? doc(reference, path, ...(pathSegments || []))
+              : doc(reference, path, ...(pathSegments || []))
+    ) as DocumentReference<AppModelType, DbModelType>;
+};
+
+export const useDocReference = <AppModelType, DbModelType extends DocumentData = DocumentData>({
+    path,
+    reference,
+    pathSegments
+}: UseDocReferenceOptions<AppModelType, DbModelType>) => {
+    const db = useFirestore();
+    const ref = useRef<DocumentReference<AppModelType, DbModelType> | null>(
+        getDocReference(db, { path, pathSegments, reference })
+    );
+
+    useEffect(() => {
+        ref.current = getDocReference(db, { path, pathSegments, reference });
+    }, [path, reference, pathSegments]);
+
+    return ref.current;
+};