diff --git a/README.md b/README.md
index 183e66b..bd3a71f 100644
--- a/README.md
+++ b/README.md
@@ -5,8 +5,9 @@ A set of reusable [React Hooks](https://reactjs.org/docs/hooks-intro.html) for [
[](https://www.npmjs.com/package/react-firebase-hooks)
[](https://www.npmjs.com/package/react-firebase-hooks)
-This documentation is for v4 of React Firebase Hooks which makes the package compatible with Firebase v9 and drops support for previous versions of Firebase - more details [here](https://github.com/CSFrequency/react-firebase-hooks/releases/tag/v4.0.0).
+This documentation is for v5 of React Firebase Hooks which requires Firebase v9 or higher.
+- For v3 documentation (Firebase v9), see [here](https://github.com/CSFrequency/react-firebase-hooks/tree/v4.0.2).
- For v3 documentation (Firebase v8), see [here](https://github.com/CSFrequency/react-firebase-hooks/tree/v3.0.4).
- For v2 documentation, see [here](https://github.com/CSFrequency/react-firebase-hooks/tree/v2.2.0).
@@ -28,18 +29,18 @@ This assumes that you’re using the [npm](https://npmjs.com) or [yarn](https://
## Why?
-There has been a **lot** of hype around React Hooks, but this hype merely reflects that there are obvious real world benefits of Hooks to React developers everywhere.
-
This library explores how React Hooks can work to make integration with Firebase even more straightforward than it already is. It takes inspiration for naming from RxFire and is based on an internal library that we had been using in a number of apps prior to the release of React Hooks. The implementation with hooks is 10x simpler than our previous implementation.
-## Upgrading from v3 to v4
+## Upgrading from v4 to v5
-To upgrade your project from v3 to v4 check out the [Release Notes](https://github.com/CSFrequency/react-firebase-hooks/releases/tag/v4.0.0) which have full details of everything that needs to be changed.
+To upgrade your project from v4 to v5 check out the [Release Notes](https://github.com/CSFrequency/react-firebase-hooks/releases/tag/v5.0.0) which have full details of everything that needs to be changed.
## Documentation
-- [Auth Hooks](/auth)
+- [Authentication Hooks](/auth)
- [Cloud Firestore Hooks](/firestore)
+- [Cloud Functions Hooks](/functions)
+- [Cloud Messaging Hooks](/messaging)
- [Cloud Storage Hooks](/storage)
- [Realtime Database Hooks](/database)
diff --git a/auth/README.md b/auth/README.md
index 81b0d40..d44b318 100644
--- a/auth/README.md
+++ b/auth/README.md
@@ -13,11 +13,23 @@ List of Auth hooks:
- [useAuthState](#useauthstate)
- [useCreateUserWithEmailAndPassword](#usecreateuserwithemailandpassword)
- [useSignInWithEmailAndPassword](#usesigninwithemailandpassword)
+- [useSignInWithApple](#usesigninwithapple)
+- [useSignInWithFacebook](#usesigninwithfacebook)
+- [useSignInWithGithub](#usesigninwithgithub)
+- [useSignInWithGoogle](#usesigninwithgoogle)
+- [useSignInWithMicrosoft](#usesigninwithmicrosoft)
+- [useSignInWithTwitter](#usesigninwithtwitter)
+- [useSignInWithYahoo](#usesigninwithyahoo)
+- [useUpdateEmail](#useupdateemail)
+- [useUpdatePassword](#useupdatepassword)
+- [useUpdateProfile](#useupdateprofile)
+- [useSendPasswordResetEmail](#usesendpasswordresetemail)
+- [useSendEmailVerification](#usesendemailverification)
### useAuthState
```js
-const [user, loading, error] = useAuthState(auth);
+const [user, loading, error] = useAuthState(auth, options);
```
Retrieve and monitor the authentication state from Firebase.
@@ -25,6 +37,8 @@ Retrieve and monitor the authentication state from Firebase.
The `useAuthState` hook takes the following parameters:
- `auth`: `auth.Auth` instance for the app you would like to monitor
+- `options`: (optional) `Object with the following parameters:
+ - `onUserChanged`: (optional) function to be called with `auth.User` each time the user changes. This allows you to do things like load custom claims.
Returns:
@@ -40,13 +54,13 @@ Returns:
import { getAuth, signInWithEmailAndPassword, signOut } from 'firebase/auth';
import { useAuthState } from 'react-firebase-hooks/auth';
-const auth = getAuth(firebaseApp)
+const auth = getAuth(firebaseApp);
const login = () => {
signInWithEmailAndPassword(auth, 'test@test.com', 'password');
};
const logout = () => {
- signOut(auth)
+ signOut(auth);
};
const CurrentUser = () => {
@@ -165,7 +179,7 @@ const [
user,
loading,
error,
-] = useSignInWithEmailAndPassword(auth, email, password);
+] = useSignInWithEmailAndPassword(auth);
```
Login a user with email and password. Wraps the underlying `auth.signInWithEmailAndPassword` method and provides additional `loading` and `error` information.
@@ -232,3 +246,501 @@ const SignIn = () => {
);
};
```
+
+### useSignInWithApple
+
+```js
+const [signInWithApple, user, loading, error] = useSignInWithApple(auth);
+```
+
+Login a user with Apple Authenticatiton. Wraps the underlying `auth.signInWithPopup` method with the `auth.OAuthProvider` and provides additional `loading` and `error` information.
+
+The `useSignInWithApple` hook takes the following parameters:
+
+- `auth`: `Auth` instance for the app you would like to monitor
+
+Returns:
+
+- `signInWithApple(scopes: string[], customOAuthParameters: auth.CustomParameters)`: a function you can call to start the login
+- `user`: The `auth.User` if the user was logged in or `undefined` if not
+- `loading`: A `boolean` to indicate whether the the user login is processing
+- `error`: Any `Error` returned by Firebase when trying to login the user, or `undefined` if there is no error
+
+#### Full example
+
+See [social login example](#social-login-example)
+
+### useSignInWithFacebook
+
+```js
+const [signInWithFacebook, user, loading, error] = useSignInWithFacebook(auth);
+```
+
+Login a user with Facebook Authenticatiton. Wraps the underlying `auth.signInWithPopup` method with the `auth.OAuthProvider` and provides additional `loading` and `error` information.
+
+The `useSignInWithApple` hook takes the following parameters:
+
+- `auth`: `Auth` instance for the app you would like to monitor
+
+Returns:
+
+- `signInWithFacebook(scopes: string[], customOAuthParameters: auth.CustomParameters)`: a function you can call to start the login
+- `user`: The `auth.User` if the user was logged in or `undefined` if not
+- `loading`: A `boolean` to indicate whether the the user login is processing
+- `error`: Any `Error` returned by Firebase when trying to login the user, or `undefined` if there is no error
+
+#### Full example
+
+See [social login example](#social-login-example)
+
+### useSignInWithGithub
+
+```js
+const [signInWithGithub, user, loading, error] = useSignInWithGithub(auth);
+```
+
+Login a user with Github Authenticatiton. Wraps the underlying `auth.signInWithPopup` method with the `auth.OAuthProvider` and provides additional `loading` and `error` information.
+
+The `useSignInWithGithub` hook takes the following parameters:
+
+- `auth`: `Auth` instance for the app you would like to monitor
+
+Returns:
+
+- `signInWithGithub(scopes: string[], customOAuthParameters: auth.CustomParameters)`: a function you can call to start the login
+- `user`: The `auth.User` if the user was logged in or `undefined` if not
+- `loading`: A `boolean` to indicate whether the the user login is processing
+- `error`: Any `Error` returned by Firebase when trying to login the user, or `undefined` if there is no error
+
+#### Full example
+
+See [social login example](#social-login-example)
+
+### useSignInWithGoogle
+
+```js
+const [signInWithGoogle, user, loading, error] = useSignInWithGoogle(auth);
+```
+
+Login a user with Google Authenticatiton. Wraps the underlying `auth.signInWithPopup` method with the `auth.GoogleProvider` and provides additional `loading` and `error` information.
+
+The `useSignInWithGoogle` hook takes the following parameters:
+
+- `auth`: `Auth` instance for the app you would like to monitor
+
+Returns:
+
+- `signInWithGoogle(scopes: string[], customOAuthParameters: auth.CustomParameters)`: a function you can call to start the login
+- `user`: The `auth.User` if the user was logged in or `undefined` if not
+- `loading`: A `boolean` to indicate whether the the user login is processing
+- `error`: Any `Error` returned by Firebase when trying to login the user, or `undefined` if there is no error
+
+#### Full example
+
+See [social login example](#social-login-example)
+
+### useSignInWithMicrosoft
+
+```js
+const [signInWithMicrosoft, user, loading, error] = useSignInWithMicrosoft(
+ auth
+);
+```
+
+Login a user with Microsoftt Authenticatiton. Wraps the underlying `auth.signInWithPopup` method with the `auth.OAuthProvider` and provides additional `loading` and `error` information.
+
+The `useSignInWithMicrosoft` hook takes the following parameters:
+
+- `auth`: `Auth` instance for the app you would like to monitor
+
+Returns:
+
+- `signInWithMicrosoft(scopes: string[], customOAuthParameters: auth.CustomParameters)`: a function you can call to start the login
+- `user`: The `auth.User` if the user was logged in or `undefined` if not
+- `loading`: A `boolean` to indicate whether the the user login is processing
+- `error`: Any `Error` returned by Firebase when trying to login the user, or `undefined` if there is no error
+
+#### Full example
+
+See [social login example](#social-login-example)
+
+### useSignInWithTwittter
+
+```js
+const [signInWithTwitter, user, loading, error] = useSignInWithTwitter(auth);
+```
+
+Login a user with Twitter Authenticatiton. Wraps the underlying `auth.signInWithPopup` method with the `auth.OAuthProvider` and provides additional `loading` and `error` information.
+
+The `useSignInWithTwitter` hook takes the following parameters:
+
+- `auth`: `Auth` instance for the app you would like to monitor
+
+Returns:
+
+- `signInWithTwitter(scopes: string[], customOAuthParameters: auth.CustomParameters)`: a function you can call to start the login
+- `user`: The `auth.User` if the user was logged in or `undefined` if not
+- `loading`: A `boolean` to indicate whether the the user login is processing
+- `error`: Any `Error` returned by Firebase when trying to login the user, or `undefined` if there is no error
+
+#### Full example
+
+See [social login example](#social-login-example)
+
+### useSignInWithYahoo
+
+```js
+const [signInWithYahoo, user, loading, error] = useSignInWithYahoo(auth);
+```
+
+Login a user with Yahoo Authenticatiton. Wraps the underlying `auth.signInWithPopup` method with the `auth.OAuthProvider` and provides additional `loading` and `error` information.
+
+The `useSignInWithYahoo` hook takes the following parameters:
+
+- `auth`: `Auth` instance for the app you would like to monitor
+
+Returns:
+
+- `signInWithYahoo(scopes: string[], customOAuthParameters: auth.CustomParameters)`: a function you can call to start the login
+- `user`: The `auth.User` if the user was logged in or `undefined` if not
+- `loading`: A `boolean` to indicate whether the the user login is processing
+- `error`: Any `Error` returned by Firebase when trying to login the user, or `undefined` if there is no error
+
+#### Full example
+
+See [social login example](#social-login-example)
+
+### Social Login Example
+
+```jsx
+import { useSignInWithXXX } from 'react-firebase-hooks/auth';
+
+const SignIn = () => {
+ const [signInWithXXX, user, loading, error] = useSignInWithXXX(auth);
+
+ if (error) {
+ return (
+
+ );
+};
+```
+
+### useUpdateEmail
+
+```js
+const [updateEmail, updating, error] = useUpdateEmail(auth);
+```
+
+Update the current user's email address. Wraps the underlying `auth.updateEmail` method and provides additional `updating` and `error` information.
+
+The `useUpdateEmail` hook takes the following parameters:
+
+- `auth`: `Auth` instance for the app you would like to monitor
+
+Returns:
+
+- `updateEmail(email: string)`: a function you can call to update the current user's email addres
+- `updating`: A `boolean` to indicate whether the user update is processing
+- `error`: Any `Error` returned by Firebase when trying to update the user, or `undefined` if there is no error
+
+#### Full Example
+
+```jsx
+import { useUpdateEmail } from 'react-firebase-hooks/auth';
+
+const UpdateEmail = () => {
+ const [email, setEmail] = useState('');
+ const [updateEmail, updating, error] = useUpdateEmail(auth);
+
+ if (error) {
+ return (
+
+
Error: {error.message}
+
+ );
+ }
+ if (updating) {
+ return
Updating...
;
+ }
+ return (
+
+ setEmail(e.target.value)}
+ />
+
+
+ );
+};
+```
+
+### useUpdatePassword
+
+```js
+const [updatePassword, updating, error] = useUpdatePassword(auth);
+```
+
+Update the current user's password. Wraps the underlying `auth.updatePassword` method and provides additional `updating` and `error` information.
+
+The `useUpdatePassword` hook takes the following parameters:
+
+- `auth`: `Auth` instance for the app you would like to monitor
+
+Returns:
+
+- `updatePassword(password: string)`: a function you can call to update the current user's password
+- `updating`: A `boolean` to indicate whether the user update is processing
+- `error`: Any `Error` returned by Firebase when trying to update the user, or `undefined` if there is no error
+
+#### Full Example
+
+```jsx
+import { useUpdatePassword } from 'react-firebase-hooks/auth';
+
+const UpdatePassword = () => {
+ const [password, setPassword] = useState('');
+ const [updatePassword, updating, error] = useUpdatePassword(auth);
+
+ if (error) {
+ return (
+
+
Error: {error.message}
+
+ );
+ }
+ if (updating) {
+ return
Updating...
;
+ }
+ return (
+
+ setPassword(e.target.value)}
+ />
+
+
+ );
+};
+```
+
+### useUpdateProfile
+
+```js
+const [updateProfile, updating, error] = useUpdateProfile(auth);
+```
+
+Update the current user's profile. Wraps the underlying `auth.updateProfile` method and provides additional `updating` and `error` information.
+
+The `useUpdateProfile` hook takes the following parameters:
+
+- `auth`: `Auth` instance for the app you would like to monitor
+
+Returns:
+
+- `updateProfile({ displayName: string, photoURL: string })`: a function you can call to update the current user's profile
+- `updating`: A `boolean` to indicate whether the user update is processing
+- `error`: Any `Error` returned by Firebase when trying to update the user, or `undefined` if there is no error
+
+#### Full Example
+
+```jsx
+import { useUpdateProfile } from 'react-firebase-hooks/auth';
+
+const UpdateProfile = () => {
+ const [displayName, setDisplayName] = useState('');
+ const [photoURL, setPhotoURL] = useState('');
+ const [updateProfile, updating, error] = useUpdateProfile(auth);
+
+ if (error) {
+ return (
+
+ );
+};
+```
+
+### useSendPasswordResetEmail
+
+```js
+const [sendPasswordResetEmail, sending, error] = useSendPasswordResetEmail(
+ auth
+);
+```
+
+Send a password reset email to the specified email address. Wraps the underlying `auth.sendPasswordResetEmail` method and provides additional `sending` and `error` information.
+
+The `useSendPasswordResetEmail` hook takes the following parameters:
+
+- `auth`: `Auth` instance for the app you would like to monitor
+
+Returns:
+
+- `sendPasswordResetEmail(email: string)`: a function you can call to send a password reset emaail
+- `sending`: A `boolean` to indicate whether the email is being sent
+- `error`: Any `Error` returned by Firebase when trying to send the email, or `undefined` if there is no error
+
+#### Full Example
+
+```jsx
+import { useSendPasswordResetEmail } from 'react-firebase-hooks/auth';
+
+const SendPasswordReset = () => {
+ const [email, setEmail] = useState('');
+ const [sendPasswordResetEmail, sending, error] = useSendPasswordResetEmail(
+ auth
+ );
+
+ if (error) {
+ return (
+
+
Error: {error.message}
+
+ );
+ }
+ if (sending) {
+ return
Sending...
;
+ }
+ return (
+
+ setEmail(e.target.value)}
+ />
+
+
+ );
+};
+```
+
+### useSendEmailVerification
+
+```js
+const [sendEmailVerification, sending, error] = useSendEmailVerification(auth);
+```
+
+Send a verification email to the current user. Wraps the underlying `auth.sendEmailVerification` method and provides additional `sending` and `error` information.
+
+The `useSendEmailVerification` hook takes the following parameters:
+
+- `auth`: `Auth` instance for the app you would like to monitor
+
+Returns:
+
+- `sendEmailVerification()`: a function you can call to send a password reset emaail
+- `sending`: A `boolean` to indicate whether the email is being sent
+- `error`: Any `Error` returned by Firebase when trying to send the email, or `undefined` if there is no error
+
+#### Full Example
+
+```jsx
+import { useSendEmailVerification } from 'react-firebase-hooks/auth';
+
+const SendEmailVerification = () => {
+ const [email, setEmail] = useState('');
+ const [sendEmailVerification, sending, error] = useSendEmailVerification(
+ auth
+ );
+
+ if (error) {
+ return (
+
+
Error: {error.message}
+
+ );
+ }
+ if (sending) {
+ return
Sending...
;
+ }
+ return (
+
+
+
+ );
+};
+```
diff --git a/auth/index.js.flow b/auth/index.js.flow
deleted file mode 100644
index 2ee9b8a..0000000
--- a/auth/index.js.flow
+++ /dev/null
@@ -1,7 +0,0 @@
-// @flow
-import type { Auth, AuthError, User } from 'firebase/auth';
-
-type LoadingHook = [T | void, boolean, AuthError | void];
-
-export type AuthStateHook = LoadingHook;
-declare export function useAuthState(auth: Auth): AuthStateHook;
diff --git a/auth/index.ts b/auth/index.ts
index 7d97376..a880dad 100644
--- a/auth/index.ts
+++ b/auth/index.ts
@@ -1,5 +1,30 @@
export { default as useAuthState, AuthStateHook } from './useAuthState';
-export { default as useSignInWithEmailAndPassword } from './useSignInWithEmailAndPassword';
export { default as useCreateUserWithEmailAndPassword } from './useCreateUserWithEmailAndPassword';
+export {
+ default as useSendEmailVerification,
+ SendEmailVerificationHook,
+} from './useSendEmailVerification';
+export {
+ default as useSendPasswordResetEmail,
+ SendPasswordResetEmailHook,
+} from './useSendPasswordResetEmail';
+export { default as useSignInWithEmailAndPassword } from './useSignInWithEmailAndPassword';
+export {
+ useSignInWithApple,
+ useSignInWithFacebook,
+ useSignInWithGithub,
+ useSignInWithGoogle,
+ useSignInWithMicrosoft,
+ useSignInWithTwitter,
+ useSignInWithYahoo,
+} from './useSignInWithPopup';
+export {
+ useUpdateEmail,
+ useUpdatePassword,
+ useUpdateProfile,
+ UpdateEmailHook,
+ UpdatePasswordHook,
+ UpdateProfileHook,
+} from './useUpdateUser';
-export { EmailAndPasswordActionHook } from './types';
+export { EmailAndPasswordActionHook, SignInWithPopupHook } from './types';
diff --git a/auth/types.ts b/auth/types.ts
index 204ffca..7c8f8cd 100644
--- a/auth/types.ts
+++ b/auth/types.ts
@@ -1,16 +1,24 @@
-import { ActionCodeSettings, AuthError, UserCredential } from 'firebase/auth';
+import {
+ ActionCodeSettings,
+ AuthError,
+ CustomParameters,
+ UserCredential,
+} from 'firebase/auth';
-export type AuthActionHook = [
- (email: string, password: string) => Promise,
- T | undefined,
+export type AuthActionHook = [
+ M,
+ UserCredential | undefined,
boolean,
- E | undefined
+ AuthError | undefined
];
export type CreateUserOptions = {
emailVerificationOptions?: ActionCodeSettings;
sendEmailVerification?: boolean;
};
export type EmailAndPasswordActionHook = AuthActionHook<
- UserCredential,
- AuthError
+ (email: string, password: string) => Promise
+>;
+
+export type SignInWithPopupHook = AuthActionHook<
+ (scopes?: string[], customOAuthParameters?: CustomParameters) => Promise
>;
diff --git a/auth/useAuthState.ts b/auth/useAuthState.ts
index e888375..3c80778 100644
--- a/auth/useAuthState.ts
+++ b/auth/useAuthState.ts
@@ -4,15 +4,37 @@ import { LoadingHook, useLoadingValue } from '../util';
export type AuthStateHook = LoadingHook;
-export default (auth: Auth): AuthStateHook => {
+type AuthStateOptions = {
+ onUserChanged?: (user: User | null) => Promise;
+};
+
+export default (auth: Auth, options?: AuthStateOptions): AuthStateHook => {
const { error, loading, setError, setValue, value } = useLoadingValue<
User | null,
Error
>(() => auth.currentUser);
useEffect(() => {
- return onAuthStateChanged(auth, setValue, setError);
- }, [auth]);
+ const listener = onAuthStateChanged(
+ auth,
+ async (user) => {
+ if (options?.onUserChanged) {
+ // onUserChanged function to process custom claims on any other trigger function
+ try {
+ await options.onUserChanged(user);
+ } catch (e) {
+ setError(e as Error);
+ }
+ }
+ setValue(user);
+ },
+ setError
+ );
+
+ return () => {
+ listener();
+ };
+ }, [auth, options]);
const resArray: AuthStateHook = [value, loading, error];
return useMemo(() => resArray, resArray);
diff --git a/auth/useSendEmailVerification.ts b/auth/useSendEmailVerification.ts
new file mode 100644
index 0000000..5c91f34
--- /dev/null
+++ b/auth/useSendEmailVerification.ts
@@ -0,0 +1,39 @@
+import {
+ Auth,
+ AuthError,
+ sendEmailVerification as fbSendEmailVerification,
+} from 'firebase/auth';
+import { useMemo, useState } from 'react';
+
+export type SendEmailVerificationHook = [
+ () => Promise,
+ boolean,
+ AuthError | Error | undefined
+];
+
+export default (auth: Auth): SendEmailVerificationHook => {
+ const [error, setError] = useState();
+ const [loading, setLoading] = useState(false);
+
+ const sendEmailVerification = async () => {
+ setLoading(true);
+ try {
+ if (auth.currentUser) {
+ await fbSendEmailVerification(auth.currentUser);
+ } else {
+ setError(new Error('No user is logged in') as AuthError);
+ }
+ } catch (err) {
+ setError(err as AuthError);
+ } finally {
+ setLoading(false);
+ }
+ };
+
+ const resArray: SendEmailVerificationHook = [
+ sendEmailVerification,
+ loading,
+ error,
+ ];
+ return useMemo(() => resArray, resArray);
+};
diff --git a/auth/useSendPasswordResetEmail.ts b/auth/useSendPasswordResetEmail.ts
new file mode 100644
index 0000000..13c20d3
--- /dev/null
+++ b/auth/useSendPasswordResetEmail.ts
@@ -0,0 +1,39 @@
+import {
+ Auth,
+ AuthError,
+ sendPasswordResetEmail as fbSendPasswordResetEmail,
+} from 'firebase/auth';
+import { useMemo, useState } from 'react';
+
+export type SendPasswordResetEmailHook = [
+ (email: string) => Promise,
+ boolean,
+ AuthError | Error | undefined
+];
+
+export default (auth: Auth): SendPasswordResetEmailHook => {
+ const [error, setError] = useState();
+ const [loading, setLoading] = useState(false);
+
+ const sendPasswordResetEmail = async (email: string) => {
+ setLoading(true);
+ try {
+ if (auth.currentUser) {
+ await fbSendPasswordResetEmail(auth, email);
+ } else {
+ setError(new Error('No user is logged in') as AuthError);
+ }
+ } catch (err) {
+ setError(err as AuthError);
+ } finally {
+ setLoading(false);
+ }
+ };
+
+ const resArray: SendPasswordResetEmailHook = [
+ sendPasswordResetEmail,
+ loading,
+ error,
+ ];
+ return useMemo(() => resArray, resArray);
+};
diff --git a/auth/useSignInWithPopup.ts b/auth/useSignInWithPopup.ts
new file mode 100644
index 0000000..a7c6bf5
--- /dev/null
+++ b/auth/useSignInWithPopup.ts
@@ -0,0 +1,151 @@
+import { useState, useMemo } from 'react';
+import {
+ Auth,
+ AuthError,
+ AuthProvider,
+ CustomParameters,
+ FacebookAuthProvider,
+ GithubAuthProvider,
+ GoogleAuthProvider,
+ OAuthProvider,
+ TwitterAuthProvider,
+ signInWithPopup,
+ UserCredential,
+} from 'firebase/auth';
+import { SignInWithPopupHook } from './types';
+
+export const useSignInWithApple = (auth: Auth): SignInWithPopupHook => {
+ return useSignInWithOAuth(auth, 'apple.com');
+};
+
+export const useSignInWithFacebook = (auth: Auth): SignInWithPopupHook => {
+ const createFacebookAuthProvider = (
+ scopes?: string[],
+ customOAuthParameters?: CustomParameters
+ ) => {
+ const provider = new FacebookAuthProvider();
+ if (scopes) {
+ scopes.forEach((scope) => provider.addScope(scope));
+ }
+ if (customOAuthParameters) {
+ provider.setCustomParameters(customOAuthParameters);
+ }
+ return provider;
+ };
+ return useSignInWithPopup(auth, createFacebookAuthProvider);
+};
+
+export const useSignInWithGithub = (auth: Auth): SignInWithPopupHook => {
+ const createGithubAuthProvider = (
+ scopes?: string[],
+ customOAuthParameters?: CustomParameters
+ ) => {
+ const provider = new GithubAuthProvider();
+ if (scopes) {
+ scopes.forEach((scope) => provider.addScope(scope));
+ }
+ if (customOAuthParameters) {
+ provider.setCustomParameters(customOAuthParameters);
+ }
+ return provider;
+ };
+ return useSignInWithPopup(auth, createGithubAuthProvider);
+};
+
+export const useSignInWithGoogle = (auth: Auth): SignInWithPopupHook => {
+ const createGoogleAuthProvider = (
+ scopes?: string[],
+ customOAuthParameters?: CustomParameters
+ ) => {
+ const provider = new GoogleAuthProvider();
+ if (scopes) {
+ scopes.forEach((scope) => provider.addScope(scope));
+ }
+ if (customOAuthParameters) {
+ provider.setCustomParameters(customOAuthParameters);
+ }
+ return provider;
+ };
+ return useSignInWithPopup(auth, createGoogleAuthProvider);
+};
+
+export const useSignInWithMicrosoft = (auth: Auth): SignInWithPopupHook => {
+ return useSignInWithOAuth(auth, 'microsoft.com');
+};
+
+export const useSignInWithTwitter = (auth: Auth): SignInWithPopupHook => {
+ const createTwitterAuthProvider = (
+ scopes?: string[],
+ customOAuthParameters?: CustomParameters
+ ) => {
+ const provider = new TwitterAuthProvider();
+ if (scopes) {
+ scopes.forEach((scope) => provider.addScope(scope));
+ }
+ if (customOAuthParameters) {
+ provider.setCustomParameters(customOAuthParameters);
+ }
+ return provider;
+ };
+ return useSignInWithPopup(auth, createTwitterAuthProvider);
+};
+
+export const useSignInWithYahoo = (auth: Auth): SignInWithPopupHook => {
+ return useSignInWithOAuth(auth, 'yahoo.com');
+};
+
+const useSignInWithOAuth = (
+ auth: Auth,
+ providerId: string
+): SignInWithPopupHook => {
+ const createOAuthProvider = (
+ scopes?: string[],
+ customOAuthParameters?: CustomParameters
+ ) => {
+ const provider = new OAuthProvider(providerId);
+ if (scopes) {
+ scopes.forEach((scope) => provider.addScope(scope));
+ }
+ if (customOAuthParameters) {
+ provider.setCustomParameters(customOAuthParameters);
+ }
+ return provider;
+ };
+ return useSignInWithPopup(auth, createOAuthProvider);
+};
+
+const useSignInWithPopup = (
+ auth: Auth,
+ createProvider: (
+ scopes?: string[],
+ customOAuthParameters?: CustomParameters
+ ) => AuthProvider
+): SignInWithPopupHook => {
+ const [error, setError] = useState();
+ const [loggedInUser, setLoggedInUser] = useState();
+ const [loading, setLoading] = useState(false);
+
+ const signInWithGoogle = async (
+ scopes?: string[],
+ customOAuthParameters?: CustomParameters
+ ) => {
+ setLoading(true);
+ try {
+ const provider = createProvider(scopes, customOAuthParameters);
+ const user = await signInWithPopup(auth, provider);
+ setLoggedInUser(user);
+ } catch (err) {
+ setError(err as AuthError);
+ } finally {
+ setLoading(false);
+ }
+ };
+
+ const resArray: SignInWithPopupHook = [
+ signInWithGoogle,
+ loggedInUser,
+ loading,
+ error,
+ ];
+ return useMemo(() => resArray, resArray);
+};
diff --git a/auth/useUpdateUser.ts b/auth/useUpdateUser.ts
new file mode 100644
index 0000000..6c26f32
--- /dev/null
+++ b/auth/useUpdateUser.ts
@@ -0,0 +1,92 @@
+import {
+ Auth,
+ AuthError,
+ updateEmail as fbUpdateEmail,
+ updatePassword as fbUpdatePassword,
+ updateProfile as fbUpdateProfile,
+} from 'firebase/auth';
+import { useMemo, useState } from 'react';
+
+type Profile = {
+ displayName?: string | null;
+ photoURL?: string | null;
+};
+
+export type UpdateUserHook = [M, boolean, AuthError | Error | undefined];
+
+export type UpdateEmailHook = UpdateUserHook<(email: string) => Promise>;
+export type UpdatePasswordHook = UpdateUserHook<
+ (password: string) => Promise
+>;
+export type UpdateProfileHook = UpdateUserHook<
+ (profile: Profile) => Promise
+>;
+
+export const useUpdateEmail = (auth: Auth): UpdateEmailHook => {
+ const [error, setError] = useState();
+ const [loading, setLoading] = useState(false);
+
+ const updateEmail = async (email: string) => {
+ setLoading(true);
+ try {
+ if (auth.currentUser) {
+ await fbUpdateEmail(auth.currentUser, email);
+ } else {
+ setError(new Error('No user is logged in') as AuthError);
+ }
+ } catch (err) {
+ setError(err as AuthError);
+ } finally {
+ setLoading(false);
+ }
+ };
+
+ const resArray: UpdateEmailHook = [updateEmail, loading, error];
+ return useMemo(() => resArray, resArray);
+};
+
+export const useUpdatePassword = (auth: Auth): UpdatePasswordHook => {
+ const [error, setError] = useState();
+ const [loading, setLoading] = useState(false);
+
+ const updatePassword = async (password: string) => {
+ setLoading(true);
+ try {
+ if (auth.currentUser) {
+ await fbUpdatePassword(auth.currentUser, password);
+ } else {
+ setError(new Error('No user is logged in') as AuthError);
+ }
+ } catch (err) {
+ setError(err as AuthError);
+ } finally {
+ setLoading(false);
+ }
+ };
+
+ const resArray: UpdatePasswordHook = [updatePassword, loading, error];
+ return useMemo(() => resArray, resArray);
+};
+
+export const useUpdateProfile = (auth: Auth): UpdateProfileHook => {
+ const [error, setError] = useState();
+ const [loading, setLoading] = useState(false);
+
+ const updateProfile = async (profile: Profile) => {
+ setLoading(true);
+ try {
+ if (auth.currentUser) {
+ await fbUpdateProfile(auth.currentUser, profile);
+ } else {
+ setError(new Error('No user is logged in') as AuthError);
+ }
+ } catch (err) {
+ setError(err as AuthError);
+ } finally {
+ setLoading(false);
+ }
+ };
+
+ const resArray: UpdateProfileHook = [updateProfile, loading, error];
+ return useMemo(() => resArray, resArray);
+};
diff --git a/database/index.js.flow b/database/index.js.flow
deleted file mode 100644
index 948c997..0000000
--- a/database/index.js.flow
+++ /dev/null
@@ -1,26 +0,0 @@
-// @flow
-import type { DataSnapshot, Query } from 'firebase/database';
-
-type LoadingHook = [T | void, boolean, Error | void];
-
-export type ListHook = LoadingHook;
-export type ListKeysHook = LoadingHook;
-export type ListValsHook = LoadingHook;
-export type ObjectHook = LoadingHook;
-export type ObjectValHook = LoadingHook;
-
-declare export function useList(query?: Query | null): ListHook;
-declare export function useListKeys(query?: Query | null): ListKeysHook;
-declare export function useListVals(
- query?: Query | null,
- options?: {
- keyField?: string,
- }
-): ListValsHook;
-declare export function useObject(query?: Query | null): ObjectHook;
-declare export function useObjectVal(
- query?: Query | null,
- options?: {
- keyField?: string,
- }
-): ObjectValHook;
diff --git a/firestore/README.md b/firestore/README.md
index 4dfd357..ff7042d 100644
--- a/firestore/README.md
+++ b/firestore/README.md
@@ -19,16 +19,16 @@ import { useCollection } from 'react-firebase-hooks/firestore';
List of Cloud Firestore hooks:
- [React Firebase Hooks - Cloud Firestore](#react-firebase-hooks---cloud-firestore)
- - [useCollection](#usecollection)
- - [Full example](#full-example)
- - [useCollectionOnce](#usecollectiononce)
- - [useCollectionData](#usecollectiondata)
- - [useCollectionDataOnce](#usecollectiondataonce)
- - [useDocument](#usedocument)
- - [Full example](#full-example-1)
- - [useDocumentOnce](#usedocumentonce)
- - [useDocumentData](#usedocumentdata)
- - [useDocumentDataOnce](#usedocumentdataonce)
+ - [useCollection](#usecollection)
+ - [Full example](#full-example)
+ - [useCollectionOnce](#usecollectiononce)
+ - [useCollectionData](#usecollectiondata)
+ - [useCollectionDataOnce](#usecollectiondataonce)
+ - [useDocument](#usedocument)
+ - [Full example](#full-example-1)
+ - [useDocumentOnce](#usedocumentonce)
+ - [useDocumentData](#usedocumentdata)
+ - [useDocumentDataOnce](#usedocumentdataonce)
- [Transforming data](#transforming-data)
Additional functionality:
@@ -115,7 +115,8 @@ Returns:
### useCollectionData
```js
-const [values, loading, error] = useCollectionData (query, options);
+const [values, loading, error, snapshot] =
+ useCollectionData < T > (query, options);
```
As `useCollection`, but this hook extracts a typed list of the `firestore.QuerySnapshot.docs` values, rather than the
@@ -125,22 +126,21 @@ The `useCollectionData` hook takes the following parameters:
- `query`: (optional) `firestore.Query` for the data you would like to load
- `options`: (optional) `Object` with the following parameters:
- - `idField`: (optional) name of the field that should be populated with the `firestore.QuerySnapshot.id` property.
- - `refField`: (optional) name of the field that should be populated with the `firestore.QuerySnapshot.ref` property.
- `snapshotListenOptions`: (optional) `firestore.SnapshotListenOptions` to customise how the collection is loaded
- `snapshotOptions`: (optional) `firestore.SnapshotOptions` to customise how data is retrieved from snapshots
- - `transform`: (optional) a function that receives the raw `firestore.DocumentData` for each item in the collection to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
Returns:
- `values`: an array of `T`, or `undefined` if no query is supplied
- `loading`: a `boolean` to indicate if the data is still being loaded
- `error`: Any `firestore.FirestoreError` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `snapshot`: a `firestore.QuerySnapshot`, or `undefined` if no query is supplied. This allows access to the underlying snapshot if needed for any reason, e.g. to view the snapshot metadata
### useCollectionDataOnce
```js
-const [values, loading, error] = useCollectionDataOnce(query, options);
+const [values, loading, error, snapshot] =
+ useCollectionDataOnce < T > (query, options);
```
As `useCollectionData`, but this hook will only read the current value of the `firestore.Query`.
@@ -151,16 +151,14 @@ The `useCollectionDataOnce` hook takes the following parameters:
- `options`: (optional) `Object` with the following parameters:
- `getOptions`: (optional) `Object` to customise how the collection is loaded
- `source`: (optional): `'default' | 'server' | 'cache'` Describes whether we should get from server or cache.
- - `idField`: (optional) name of the field that should be populated with the `firestore.QuerySnapshot.id` property.
- - `refField`: (optional) name of the field that should be populated with the `firestore.QuerySnapshot.ref` property.
- `snapshotOptions`: (optional) `firestore.SnapshotOptions` to customise how data is retrieved from snapshots
- - `transform`: (optional) a function that receives the raw `firestore.DocumentData` for each item in the collection to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
Returns:
- `values`: an array of `T`, or `undefined` if no query is supplied
- `loading`: a `boolean` to indicate if the data is still being loaded
- `error`: Any `firestore.FirestoreError` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `snapshot`: a `firestore.QuerySnapshot`, or `undefined` if no query is supplied. This allows access to the underlying snapshot if needed for any reason, e.g. to view the snapshot metadata
### useDocument
@@ -190,7 +188,7 @@ import { useDocument } from 'react-firebase-hooks/firestore';
const FirestoreDocument = () => {
const [value, loading, error] = useDocument(
- doc(getFirestore(firebaseApp, 'hooks', 'nBShXiRGFAhuiPfBaGpt')),
+ doc(getFirestore(firebaseApp), 'hooks', 'nBShXiRGFAhuiPfBaGpt'),
{
snapshotListenOptions: { includeMetadataChanges: true },
}
@@ -210,7 +208,7 @@ const FirestoreDocument = () => {
### useDocumentOnce
```js
-const [snapshot, loading, error] = useDocumentOnce(reference, options);
+const [snapshot, loading, error, reload] = useDocumentOnce(reference, options);
```
Retrieve the current value of the `firestore.DocumentReference`.
@@ -227,11 +225,13 @@ Returns:
- `snapshot`: a `firestore.DocumentSnapshot`, or `undefined` if no reference is supplied
- `loading`: a `boolean` to indicate if the data is still being loaded
- `error`: Any `firestore.FirestoreError` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `reload()`: a function that can be called to trigger a reload of the data
### useDocumentData
```js
-const [value, loading, error] = useDocumentData(reference, options);
+const [value, loading, error, snapshot] =
+ useDocumentData < T > (reference, options);
```
As `useDocument`, but this hook extracts the typed contents of `firestore.DocumentSnapshot.data()`, rather than the
@@ -241,22 +241,21 @@ The `useDocumentData` hook takes the following parameters:
- `reference`: (optional) `firestore.DocumentReference` for the data you would like to load
- `options`: (optional) `Object` with the following parameters:
- - `idField`: (optional) name of the field that should be populated with the `firestore.DocumentSnapshot.id` property.
- - `refField`: (optional) name of the field that should be populated with the `firestore.QuerySnapshot.ref` property.
- `snapshotListenOptions`: (optional) `firestore.SnapshotListenOptions` to customise how the collection is loaded
- `snapshotOptions`: (optional) `firestore.SnapshotOptions` to customise how data is retrieved from snapshots
- - `transform`: (optional) a function that receives the raw `firestore.DocumentData` to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
Returns:
- `value`: `T`, or `undefined` if no query is supplied
- `loading`: a `boolean` to indicate if the data is still being loaded
- `error`: Any `firestore.FirestoreError` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `snapshot`: a `firestore.DocumentSnapshot`, or `undefined` if no query is supplied. This allows access to the underlying snapshot if needed for any reason, e.g. to view the snapshot metadata
### useDocumentDataOnce
```js
-const [value, loading, error] = useDocumentDataOnce (reference, options);
+const [value, loading, error, snapshot, reload] =
+ useDocumentDataOnce < T > (reference, options);
```
As `useDocument`, but this hook will only read the current value of the `firestore.DocumentReference`.
@@ -266,28 +265,19 @@ The `useDocumentDataOnce` hook takes the following parameters:
- `reference`: (optional) `firestore.DocumentReference` for the data you would like to load
- `options`: (optional) `Object` with the following parameters:
- `getOptions`: (optional) `Object` to customise how the collection is loaded
- - `source`: (optional): `'default' | 'server' | 'cache'` Describes whether we should get from server or cache.
- - `idField`: (optional) name of the field that should be populated with the `firestore.DocumentSnapshot.id` property.
- - `refField`: (optional) name of the field that should be populated with the `firestore.QuerySnapshot.ref` property.
+ - `source`: (optional): `'default' | 'server' | 'cache'` Describes whether we should get from server or cach
- `snapshotOptions`: (optional) `firestore.SnapshotOptions` to customise how data is retrieved from snapshots
- - `transform`: (optional) a function that receives the raw `firestore.DocumentData` to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
Returns:
- `value`: `T`, or `undefined` if no query is supplied
- `loading`: a `boolean` to indicate if the data is still being loaded
- `error`: Any `firestore.FirestoreError` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `snapshot`: a `firestore.DocumentSnapshot`, or `undefined` if no query is supplied. This allows access to the underlying snapshot if needed for any reason, e.g. to view the snapshot metadata
+- `reload()`: a function that can be called to trigger a reload of the data
## Transforming data
-Firestore allows a restricted number of data types in its store, which may not be flexible enough for your application. Both `useCollectionData` and `useDocumentData` support an optional `transform` function which allows the transformation of the underlying Firestore data into whatever format the application requires, e.g. a `Date` type.
-
-```js
-transform?: (val: any) => T;
-```
-
-The `transform` function is passed a single row of a data, so will be called once when used with `useDocumentData` and multiple times when used with `useCollectionData`.
-
-The `transform` function will not receive the `id` or `ref` values referenced in the properties named in the `idField` or `refField` options, nor it is expected to produce them. Either or both, if specified, will be merged afterwards.
+Firestore allows a restricted number of data types in its store, which may not be flexible enough for your application. As of Firebase 9, there is a built in FirestoreDataConverter which allows you to transform data as it leaves the Firestore database. This is described here: https://firebase.google.com/docs/reference/js/firestore_.firestoredataconverter
-If the `transform` function is defined within your React component, it is recomended that you memoize the function to prevent unnecessry renders.
+> This has replaced the `transform`, `idField` and `refField` options that were available in `react-firebase-hooks` v4 and earlier.
diff --git a/firestore/helpers/index.ts b/firestore/helpers/index.ts
index 9818d04..d803d9f 100644
--- a/firestore/helpers/index.ts
+++ b/firestore/helpers/index.ts
@@ -1,40 +1,12 @@
import {
CollectionReference,
- DocumentData,
DocumentReference,
- DocumentSnapshot,
Query,
queryEqual,
refEqual,
- SnapshotOptions,
} from 'firebase/firestore';
import { RefHook, useComparatorRef } from '../../util';
-export const snapshotToData = (
- snapshot: DocumentSnapshot,
- snapshotOptions?: SnapshotOptions,
- idField?: string,
- refField?: string,
- transform?: (val: any) => T
-) => {
- if (!snapshot.exists()) {
- return undefined;
- }
-
- let data = snapshot.data(snapshotOptions) as DocumentData;
- if (transform) {
- data = transform(data);
- }
- if (idField) {
- data[idField] = snapshot.id;
- }
- if (refField) {
- data[refField] = snapshot.ref;
- }
-
- return data;
-};
-
const isRefEqual = <
T extends DocumentReference | CollectionReference
>(
diff --git a/firestore/index.js.flow b/firestore/index.js.flow
deleted file mode 100644
index c7ca114..0000000
--- a/firestore/index.js.flow
+++ /dev/null
@@ -1,75 +0,0 @@
-// @flow
-import type {
- DocumentReference,
- DocumentSnapshot,
- Query,
- QuerySnapshot,
- SnapshotListenOptions,
-} from 'firebase/firestore';
-
-type LoadingHook = [T | void, boolean, Error | void];
-
-export type GetOptions = {
- source?: 'default' | 'server' | 'cache';
-};
-export type CollectionHook = LoadingHook;
-export type CollectionDataHook = LoadingHook;
-export type DocumentHook = LoadingHook;
-export type DocumentDataHook = LoadingHook;
-
-declare export function useCollection(
- query?: Query | null,
- options?: {
- snapshotListenOptions?: SnapshotListenOptions,
- }
-): CollectionHook;
-declare export function useCollectionOnce(
- query?: Query | null,
- options?: {
- getOptions?: GetOptions,
- }
-): CollectionHook;
-declare export function useCollectionData(
- query?: Query | null,
- options?: {
- idField?: string,
- refField?: string,
- snapshotListenOptions?: SnapshotListenOptions,
- }
-): CollectionDataHook;
-declare export function useCollectionDataOnce(
- query?: Query | null,
- options?: {
- getOptions?: GetOptions,
- idField?: string,
- refField?: string,
- }
-): CollectionDataHook;
-declare export function useDocument(
- ref?: DocumentReference | null,
- options?: {
- snapshotListenOptions?: SnapshotListenOptions,
- }
-): DocumentHook;
-declare export function useDocumentOnce(
- ref?: DocumentReference | null,
- options?: {
- getOptions?: GetOptions,
- }
-): DocumentHook;
-declare export function useDocumentData(
- ref?: DocumentReference | null,
- options?: {
- idField?: string,
- refField?: string,
- snapshotListenOptions?: SnapshotListenOptions,
- }
-): DocumentDataHook;
-declare export function useDocumentDataOnce(
- ref?: DocumentReference | null,
- options?: {
- getOptions?: GetOptions,
- idField?: string,
- refField?: string,
- }
-): DocumentDataHook;
diff --git a/firestore/types.ts b/firestore/types.ts
index da1e2d8..3fbb911 100644
--- a/firestore/types.ts
+++ b/firestore/types.ts
@@ -1,6 +1,5 @@
import {
DocumentData,
- DocumentReference,
DocumentSnapshot,
FirestoreError,
QuerySnapshot,
@@ -10,10 +9,7 @@ import {
import { LoadingHook } from '../util';
export type IDOptions = {
- idField?: string;
- refField?: string;
snapshotOptions?: SnapshotOptions;
- transform?: (val: any) => T;
};
export type Options = {
snapshotListenOptions?: SnapshotListenOptions;
@@ -26,28 +22,37 @@ export type GetOptions = {
source?: 'default' | 'server' | 'cache';
};
export type OnceDataOptions = OnceOptions & IDOptions;
-export type Data<
- T = DocumentData,
- IDField extends string = '',
- RefField extends string = ''
-> = T & Record & Record>;
export type CollectionHook = LoadingHook<
QuerySnapshot,
FirestoreError
>;
-export type CollectionDataHook<
- T = DocumentData,
- IDField extends string = '',
- RefField extends string = ''
-> = LoadingHook[], FirestoreError>;
+export type CollectionOnceHook = [
+ ...CollectionHook,
+ () => Promise
+];
+export type CollectionDataHook = [
+ ...LoadingHook,
+ QuerySnapshot | undefined
+];
+export type CollectionDataOnceHook = [
+ ...CollectionDataHook,
+ () => Promise
+];
export type DocumentHook = LoadingHook<
DocumentSnapshot,
FirestoreError
>;
-export type DocumentDataHook<
- T = DocumentData,
- IDField extends string = '',
- RefField extends string = ''
-> = LoadingHook, FirestoreError>;
+export type DocumentOnceHook = [
+ ...DocumentHook,
+ () => Promise
+];
+export type DocumentDataHook = [
+ ...LoadingHook,
+ DocumentSnapshot | undefined
+];
+export type DocumentDataOnceHook = [
+ ...DocumentDataHook,
+ () => Promise
+];
diff --git a/firestore/useCollection.ts b/firestore/useCollection.ts
index 98810be..d483a35 100644
--- a/firestore/useCollection.ts
+++ b/firestore/useCollection.ts
@@ -7,14 +7,16 @@ import {
onSnapshot,
Query,
QuerySnapshot,
+ SnapshotOptions,
} from 'firebase/firestore';
import { useEffect, useMemo } from 'react';
import { useLoadingValue } from '../util';
-import { snapshotToData, useIsFirestoreQueryEqual } from './helpers';
+import { useIsFirestoreQueryEqual } from './helpers';
import {
CollectionDataHook,
+ CollectionDataOnceHook,
CollectionHook,
- Data,
+ CollectionOnceHook,
DataOptions,
GetOptions,
OnceDataOptions,
@@ -26,129 +28,133 @@ export const useCollection = (
query?: Query | null,
options?: Options
): CollectionHook => {
- return useCollectionInternal(true, query, options);
-};
+ const { error, loading, reset, setError, setValue, value } = useLoadingValue<
+ QuerySnapshot,
+ FirestoreError
+ >();
+ const ref = useIsFirestoreQueryEqual>(query, reset);
-export const useCollectionOnce = (
- query?: Query | null,
- options?: OnceOptions
-): CollectionHook => {
- return useCollectionInternal(false, query, options);
-};
+ useEffect(() => {
+ if (!ref.current) {
+ setValue(undefined);
+ return;
+ }
+ const unsubscribe = options?.snapshotListenOptions
+ ? onSnapshot(
+ ref.current,
+ options.snapshotListenOptions,
+ setValue,
+ setError
+ )
+ : onSnapshot(ref.current, setValue, setError);
-export const useCollectionData = <
- T = DocumentData,
- IDField extends string = '',
- RefField extends string = ''
->(
- query?: Query | null,
- options?: DataOptions
-): CollectionDataHook => {
- return useCollectionDataInternal(true, query, options);
-};
+ return () => {
+ unsubscribe();
+ };
+ }, [ref.current, options]);
-export const useCollectionDataOnce = <
- T = DocumentData,
- IDField extends string = '',
- RefField extends string = ''
->(
- query?: Query | null,
- options?: OnceDataOptions
-): CollectionDataHook => {
- return useCollectionDataInternal(false, query, options);
+ const resArray: CollectionHook = [
+ value as QuerySnapshot,
+ loading,
+ error,
+ ];
+ return useMemo(() => resArray, resArray);
};
-const useCollectionInternal = (
- listen: boolean,
+export const useCollectionOnce = (
query?: Query | null,
- options?: Options & OnceOptions
-) => {
+ options?: OnceOptions
+): CollectionOnceHook => {
const { error, loading, reset, setError, setValue, value } = useLoadingValue<
QuerySnapshot,
FirestoreError
>();
+ let effectActive = true;
const ref = useIsFirestoreQueryEqual>(query, reset);
- useEffect(() => {
- if (!ref.current) {
+ const loadData = async (
+ query?: Query | null,
+ options?: Options & OnceOptions
+ ) => {
+ if (!query) {
setValue(undefined);
return;
}
- if (listen) {
- const listener =
- options && options.snapshotListenOptions
- ? onSnapshot(
- ref.current,
- options.snapshotListenOptions,
- setValue,
- setError
- )
- : onSnapshot(ref.current, setValue, setError);
+ const get = getDocsFnFromGetOptions(options?.getOptions);
- return () => {
- listener();
- };
- } else {
- const get = getDocsFnFromGetOptions(
- options ? options.getOptions : undefined
- );
- get(ref.current).then(setValue).catch(setError);
+ try {
+ const result = await get(query);
+ if (effectActive) {
+ setValue(result);
+ }
+ } catch (error) {
+ if (effectActive) {
+ setError(error as FirestoreError);
+ }
}
- }, [ref.current]);
+ };
- const resArray: CollectionHook = [
+ useEffect(() => {
+ loadData(ref.current, options);
+
+ return () => {
+ effectActive = false;
+ };
+ }, [ref.current, options]);
+
+ const resArray: CollectionOnceHook = [
value as QuerySnapshot,
loading,
error,
+ () => loadData(ref.current, options),
];
return useMemo(() => resArray, resArray);
};
-const useCollectionDataInternal = <
- T = DocumentData,
- IDField extends string = '',
- RefField extends string = ''
->(
- listen: boolean,
+export const useCollectionData = (
+ query?: Query | null,
+ options?: DataOptions
+): CollectionDataHook => {
+ const snapshotOptions = options?.snapshotOptions;
+ const [snapshots, loading, error] = useCollection(query, options);
+ const values = getValuesFromSnapshots(snapshots, snapshotOptions);
+ const resArray: CollectionDataHook = [values, loading, error, snapshots];
+ return useMemo(() => resArray, resArray);
+};
+
+export const useCollectionDataOnce = (
query?: Query | null,
- options?: DataOptions & OnceDataOptions
-): CollectionDataHook => {
- const idField = options ? options.idField : undefined;
- const refField = options ? options.refField : undefined;
- const snapshotOptions = options ? options.snapshotOptions : undefined;
- const transform = options ? options.transform : undefined;
- const [snapshots, loading, error] = useCollectionInternal(
- listen,
+ options?: OnceDataOptions
+): CollectionDataOnceHook => {
+ const snapshotOptions = options?.snapshotOptions;
+ const [snapshots, loading, error, loadData] = useCollectionOnce(
query,
options
);
- const values = useMemo(
- () =>
- (snapshots
- ? snapshots.docs.map((doc) =>
- snapshotToData(
- doc,
- snapshotOptions,
- idField,
- refField,
- transform
- )
- )
- : undefined) as Data[],
- [snapshots, snapshotOptions, idField, refField, transform]
- );
-
- const resArray: CollectionDataHook = [
+ const values = getValuesFromSnapshots(snapshots, snapshotOptions);
+ const resArray: CollectionDataOnceHook = [
values,
loading,
error,
+ snapshots,
+ loadData,
];
return useMemo(() => resArray, resArray);
};
-function getDocsFnFromGetOptions(
+const getValuesFromSnapshots = (
+ snapshots?: QuerySnapshot,
+ options?: SnapshotOptions
+) => {
+ return useMemo(() => snapshots?.docs.map((doc) => doc.data(options)) as T[], [
+ snapshots,
+ options,
+ ]);
+};
+
+const getDocsFnFromGetOptions = (
{ source }: GetOptions = { source: 'default' }
-) {
+) => {
switch (source) {
default:
case 'default':
@@ -158,4 +164,4 @@ function getDocsFnFromGetOptions(
case 'server':
return getDocsFromServer;
}
-}
+};
diff --git a/firestore/useDocument.ts b/firestore/useDocument.ts
index a9a3551..e4e34db 100644
--- a/firestore/useDocument.ts
+++ b/firestore/useDocument.ts
@@ -10,143 +10,153 @@ import {
} from 'firebase/firestore';
import { useEffect, useMemo } from 'react';
import { useLoadingValue } from '../util';
-import { snapshotToData, useIsFirestoreRefEqual } from './helpers';
+import { useIsFirestoreRefEqual } from './helpers';
import {
- Data,
DataOptions,
DocumentDataHook,
+ DocumentDataOnceHook,
DocumentHook,
+ DocumentOnceHook,
GetOptions,
OnceDataOptions,
OnceOptions,
Options,
} from './types';
+
export const useDocument = (
docRef?: DocumentReference | null,
options?: Options
): DocumentHook => {
- return useDocumentInternal(true, docRef, options);
-};
+ const { error, loading, reset, setError, setValue, value } = useLoadingValue<
+ DocumentSnapshot,
+ FirestoreError
+ >();
+ const ref = useIsFirestoreRefEqual>(docRef, reset);
-export const useDocumentOnce = (
- docRef?: DocumentReference | null,
- options?: OnceOptions
-): DocumentHook => {
- return useDocumentInternal(false, docRef, options);
-};
+ useEffect(() => {
+ if (!ref.current) {
+ setValue(undefined);
+ return;
+ }
+ const unsubscribe = options?.snapshotListenOptions
+ ? onSnapshot(
+ ref.current,
+ options.snapshotListenOptions,
+ setValue,
+ setError
+ )
+ : onSnapshot(ref.current, setValue, setError);
-export const useDocumentData = <
- T = DocumentData,
- IDField extends string = '',
- RefField extends string = ''
->(
- docRef?: DocumentReference | null,
- options?: DataOptions
-): DocumentDataHook => {
- return useDocumentDataInternal(true, docRef, options);
-};
+ return () => {
+ unsubscribe();
+ };
+ }, [ref.current, options]);
-export const useDocumentDataOnce = <
- T = DocumentData,
- IDField extends string = '',
- RefField extends string = ''
->(
- docRef?: DocumentReference | null,
- options?: OnceDataOptions
-): DocumentDataHook => {
- return useDocumentDataInternal(false, docRef, options);
+ const resArray: DocumentHook = [
+ value as DocumentSnapshot,
+ loading,
+ error,
+ ];
+ return useMemo(() => resArray, resArray);
};
-const useDocumentInternal = (
- listen: boolean,
+export const useDocumentOnce = (
docRef?: DocumentReference | null,
- options?: Options & OnceOptions
-): DocumentHook => {
+ options?: OnceOptions
+): DocumentOnceHook => {
const { error, loading, reset, setError, setValue, value } = useLoadingValue<
DocumentSnapshot,
FirestoreError
>();
+ let effectActive = true;
const ref = useIsFirestoreRefEqual>(docRef, reset);
+ const loadData = async (
+ reference?: DocumentReference | null,
+ options?: OnceOptions
+ ) => {
+ if (!reference) {
+ setValue(undefined);
+ return;
+ }
+ const get = getDocFnFromGetOptions(options?.getOptions);
+
+ try {
+ const result = await get(reference);
+ if (effectActive) {
+ setValue(result);
+ }
+ } catch (error) {
+ if (effectActive) {
+ setError(error as FirestoreError);
+ }
+ }
+ };
+
useEffect(() => {
if (!ref.current) {
setValue(undefined);
return;
}
- if (listen) {
- const listener =
- options && options.snapshotListenOptions
- ? onSnapshot(
- ref.current,
- options.snapshotListenOptions,
- setValue,
- setError
- )
- : onSnapshot(ref.current, setValue, setError);
-
- return () => {
- listener();
- };
- } else {
- const get = getDocFnFromGetOptions(
- options ? options.getOptions : undefined
- );
-
- get(ref.current).then(setValue).catch(setError);
- }
- }, [ref.current]);
- const resArray: DocumentHook = [
+ loadData(ref.current, options);
+
+ return () => {
+ effectActive = false;
+ };
+ }, [ref.current, options]);
+
+ const resArray: DocumentOnceHook = [
value as DocumentSnapshot,
loading,
error,
+ () => loadData(ref.current, options),
];
return useMemo(() => resArray, resArray);
};
-const useDocumentDataInternal = <
- T = DocumentData,
- IDField extends string = '',
- RefField extends string = ''
->(
- listen: boolean,
+export const useDocumentData = (
docRef?: DocumentReference | null,
options?: DataOptions
-): DocumentDataHook => {
- const idField = options ? options.idField : undefined;
- const refField = options ? options.refField : undefined;
- const snapshotOptions = options ? options.snapshotOptions : undefined;
- const transform = options ? options.transform : undefined;
- const [snapshot, loading, error] = useDocumentInternal(
- listen,
+): DocumentDataHook => {
+ const snapshotOptions = options?.snapshotOptions;
+ const [snapshot, loading, error] = useDocument(docRef, options);
+ const value = useMemo(() => snapshot?.data(snapshotOptions) as T, [
+ snapshot,
+ snapshotOptions,
+ ]);
+
+ const resArray: DocumentDataHook = [value, loading, error, snapshot];
+ return useMemo(() => resArray, resArray);
+};
+
+export const useDocumentDataOnce = (
+ docRef?: DocumentReference | null,
+ options?: OnceDataOptions
+): DocumentDataOnceHook => {
+ const snapshotOptions = options?.snapshotOptions;
+ const [snapshot, loading, error, loadData] = useDocumentOnce(
docRef,
options
);
- const value = useMemo(
- () =>
- (snapshot
- ? snapshotToData(
- snapshot,
- snapshotOptions,
- idField,
- refField,
- transform
- )
- : undefined) as Data,
- [snapshot, snapshotOptions, idField, refField, transform]
- );
+ const value = useMemo(() => snapshot?.data(snapshotOptions) as T, [
+ snapshot,
+ snapshotOptions,
+ ]);
- const resArray: DocumentDataHook = [
+ const resArray: DocumentDataOnceHook = [
value,
loading,
error,
+ snapshot,
+ loadData,
];
return useMemo(() => resArray, resArray);
};
-function getDocFnFromGetOptions(
+const getDocFnFromGetOptions = (
{ source }: GetOptions = { source: 'default' }
-) {
+) => {
switch (source) {
default:
case 'default':
@@ -156,4 +166,4 @@ function getDocFnFromGetOptions(
case 'server':
return getDocFromServer;
}
-}
+};
diff --git a/functions/README.md b/functions/README.md
new file mode 100644
index 0000000..5008942
--- /dev/null
+++ b/functions/README.md
@@ -0,0 +1,65 @@
+# React Firebase Hooks - Cloud Functions
+
+React Firebase Hooks provides a convenience hook for HttpsCallable functions, providing an `error` and `loading` property
+to give a complete lifecycle for executing a HttpsCallable function on Firebase Cloud Functions.
+
+All hooks can be imported from `react-firebase-hooks/functions`, e.g.
+
+```js
+import { useHttpsCallable } from 'react-firebase-hooks/functions';
+```
+
+List of Cloud Functions hooks:
+
+- [React Firebase Hooks - Cloud Functions](#react-firebase-hooks---cloud-functions)
+ - [useHttpsCallable](#usehttpscallable)
+ - [Full example](#full-example)
+
+### useHttpsCallable
+
+```js
+const [executeCallable, loading, error] = useHttpsCallable(functions, name);
+```
+
+Generate a callable function and monitor its execution.
+
+The `useHttpsCallable` hook takes the following parameters:
+
+- `functions`: `functions.Functions` instance for your Firebase app
+- `name`: A `string` representing the name of the function to call
+
+Returns:
+
+- `executeCallable(data)`: a function you can call to execute the HttpsCallable
+- `loading`: a `boolean` to indicate if the function is still being executed
+- `error`: Any `Error` returned by Firebase when trying to execute the function, or `undefined` if there is no error
+
+#### Full example
+
+```js
+import { getFunctions } from 'firebase/functions';
+import { useHttpsCallable } from 'react-firebase-hooks/functions';
+
+const HttpsCallable = () => {
+ const [executeCallable, executing, error] = useHttpsCallable(
+ getFunctions(firebaseApp),
+ 'myHttpsCallable'
+ );
+ return (
+
@@ -62,3 +61,61 @@ const DownloadURL = () => {
);
};
```
+
+### useUploadFile
+
+```js
+const [uploadFile, uploading, snapshot, error] = useUploadFile();
+```
+
+Upload a file to Firebase storage.
+
+The `useUploadFile` hook returns the following:
+
+- `uploadFile(ref, file, metadata)`: A function that can be called to upload a file, with attached metadata, to the storage reference supplied
+- `uploading`: A `boolean` to indicate whether the the file is currently being uploaded
+- `snapshot`: A `storage.UploadTaskSnapshot` to provide more detailed information about the upload
+- `error`: Any `storage.StorageError` returned by Firebase when trying to upload the file, or `undefined` if there is no error
+
+#### Full example
+
+```js
+import { getStorage, storageRef } from 'firebase/storage';
+import { useUploadFile } from 'react-firebase-hooks/storage';
+
+const storage = getStorage(firebaseApp);
+
+const UploadFile = () => {
+ const [uploadFile, uploading, snapshot, error] = useUploadFile();
+ const ref = storageRef(storage, 'file.jpg');
+ const [selectedFile, setSelectedFile] = useState();
+
+ const upload = async () => {
+ if (selectedFile) {
+ const result = await uploadFile(ref, selectedFile, {
+ contentType: 'image/jpeg'
+ });
+ alert(`Result: ${JSON.stringify(result)}`);
+ }
+ }
+
+ return (
+