@@ -77,40 +85,40 @@ const DatabaseList = () => {
const [keys, loading, error] = useListKeys(reference);
```
-As `useList`, but this hooks extracts the `firebase.database.DataSnapshot.key` values, rather than the the `firebase.database.DataSnapshot`s themselves.
+As `useList`, but this hooks extracts the `database.DataSnapshot.key` values, rather than the the `database.DataSnapshot`s themselves.
The `useListKeys` hook takes the following parameters:
-- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
+- `reference`: (optional) `database.Reference` for the data you would like to load
Returns:
- `keys`: an array of `string`, or `undefined` if no reference is supplied
- `loading`: a `boolean` to indicate if the data is still being loaded
-- `error`: Any `firebase.FirebaseError` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `error`: Any `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
### useListVals
```js
-const [values, loading, error] = useListVals < T > (reference, options);
+const [values, loading, error] = useListVals
(reference, options);
```
-As `useList`, but this hook extracts a typed list of the `firebase.database.DataSnapshot.val()` values, rather than the the
-`firebase.database.DataSnapshot`s themselves.
+As `useList`, but this hook extracts a typed list of the `database.DataSnapshot.val()` values, rather than the the
+`database.DataSnapshot`s themselves.
The `useListVals` hook takes the following parameters:
-- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
+- `reference`: (optional) `database.Reference` for the data you would like to load
- `options`: (optional) `Object` with the following parameters:
- - `keyField`: (optional) `string` field name that should be populated with the `firebase.database.DataSnapshot.id` property in the returned values.
- - `refField`: (optional) `string` field name that should be populated with the `firebase.database.DataSnapshot.ref` property.
- - `transform`: (optional) a function that receives the raw `firebase.database.DataSnapshot.val()` for each item in the list to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
+ - `keyField`: (optional) `string` field name that should be populated with the `database.DataSnapshot.id` property in the returned values.
+ - `refField`: (optional) `string` field name that should be populated with the `database.DataSnapshot.ref` property.
+ - `transform`: (optional) a function that receives the raw `database.DataSnapshot.val()` for each item in the list 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 reference is supplied
- `loading`: a `boolean` to indicate if the data is still being loaded
-- `error`: Any `firebase.FirebaseError` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `error`: Any `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
### useObject
@@ -122,28 +130,31 @@ Retrieve and monitor an object or primitive value in the Firebase Realtime Datab
The `useObject` hook takes the following parameters:
-- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
+- `reference`: (optional) `database.Reference` for the data you would like to load
Returns:
-- `snapshot`: a `firebase.database.DataSnapshot`, or `undefined` if no reference is supplied
+- `snapshot`: a `database.DataSnapshot`, or `undefined` if no reference is supplied
- `loading`: a `boolean` to indicate if the data is still being loaded
-- `error`: Any `firebase.FirebaseError` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `error`: Any `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
#### Full Example
```js
+import { ref, getDatabase } from 'firebase/database';
import { useObject } from 'react-firebase-hooks/database';
+const database = getDatabase(firebaseApp);
+
const DatabaseValue = () => {
- const [value, loading, error] = useObject(firebase.database().ref('value'));
+ const [snapshot, loading, error] = useObject(ref(database, 'value'));
return (
{error && Error: {error}}
{loading && Value: Loading...}
- {value && Value: {value.val()}}
+ {snapshot && Value: {snapshot.val()}}
);
@@ -153,25 +164,25 @@ const DatabaseValue = () => {
### useObjectVal
```js
-const [value, loading, error] = useObjectVal < T > (reference, options);
+const [value, loading, error] = useObjectVal (reference, options);
```
-As `useObject`, but this hook returns the typed contents of `firebase.database.DataSnapshot.val()`, rather than the the
-`firebase.database.DataSnapshot` itself.
+As `useObject`, but this hook returns the typed contents of `database.DataSnapshot.val()`, rather than the the
+`database.DataSnapshot` itself.
The `useObjectVal` hook takes the following parameters:
-- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
+- `reference`: (optional) `database.Reference` for the data you would like to load
- `options`: (optional) `Object` with the following parameters:
- - `keyField`: (optional) `string` field name that should be populated with the `firebase.database.DataSnapshot.key` property in the returned value.
- - `refField`: (optional) `string` field name that should be populated with the `firebase.database.DataSnapshot.ref` property.
- - `transform`: (optional) a function that receives the raw `firebase.database.DataSnapshot.val()` to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
+ - `keyField`: (optional) `string` field name that should be populated with the `database.DataSnapshot.key` property in the returned value.
+ - `refField`: (optional) `string` field name that should be populated with the `database.DataSnapshot.ref` property.
+ - `transform`: (optional) a function that receives the raw `database.DataSnapshot.val()` to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
Returns:
- `value`: a `T`, or `undefined` if no reference is supplied
- `loading`: a `boolean` to indicate if the data is still being loaded
-- `error`: Any `firebase.FirebaseError` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `error`: Any `FirebaseError` returned by Firebase when trying to load the data, or `undefined` if there is no error
## Transforming data
diff --git a/database/helpers/index.ts b/database/helpers/index.ts
index 09c3fc3..81bde8e 100644
--- a/database/helpers/index.ts
+++ b/database/helpers/index.ts
@@ -1,4 +1,4 @@
-import firebase from 'firebase/app';
+import { DataSnapshot } from 'firebase/database';
export type ValOptions = {
keyField?: string;
@@ -10,7 +10,7 @@ const isObject = (val: any) =>
val != null && typeof val === 'object' && Array.isArray(val) === false;
export const snapshotToData = (
- snapshot: firebase.database.DataSnapshot,
+ snapshot: DataSnapshot,
keyField?: string,
refField?: string,
transform?: (val: any) => T
diff --git a/database/helpers/useListReducer.ts b/database/helpers/useListReducer.ts
index 6d85bd6..c60ef70 100644
--- a/database/helpers/useListReducer.ts
+++ b/database/helpers/useListReducer.ts
@@ -1,13 +1,13 @@
-import firebase from 'firebase/app';
+import { DataSnapshot } from 'firebase/database';
import { useReducer } from 'react';
type KeyValueState = {
keys?: string[];
- values?: firebase.database.DataSnapshot[];
+ values?: DataSnapshot[];
};
type ReducerState = {
- error?: firebase.FirebaseError;
+ error?: Error;
loading: boolean;
value: KeyValueState;
};
@@ -15,25 +15,25 @@ type ReducerState = {
type AddAction = {
type: 'add';
previousKey?: string | null;
- snapshot: firebase.database.DataSnapshot | null;
+ snapshot: DataSnapshot | null;
};
type ChangeAction = {
type: 'change';
- snapshot: firebase.database.DataSnapshot | null;
+ snapshot: DataSnapshot | null;
};
type EmptyAction = { type: 'empty' };
-type ErrorAction = { type: 'error'; error: firebase.FirebaseError };
+type ErrorAction = { type: 'error'; error: Error };
type MoveAction = {
type: 'move';
previousKey?: string | null;
- snapshot: firebase.database.DataSnapshot | null;
+ snapshot: DataSnapshot | null;
};
type RemoveAction = {
type: 'remove';
- snapshot: firebase.database.DataSnapshot | null;
+ snapshot: DataSnapshot | null;
};
type ResetAction = { type: 'reset' };
-type ValueAction = { type: 'value'; snapshots: firebase.database.DataSnapshot[] | null };
+type ValueAction = { type: 'value'; snapshots: DataSnapshot[] | null };
type ReducerAction =
| AddAction
| ChangeAction
@@ -126,7 +126,7 @@ const listReducer = (
}
};
-const setValue = (snapshots: firebase.database.DataSnapshot[] | null): KeyValueState => {
+const setValue = (snapshots: DataSnapshot[] | null): KeyValueState => {
if (!snapshots) {
return {
keys: [],
@@ -135,7 +135,7 @@ const setValue = (snapshots: firebase.database.DataSnapshot[] | null): KeyValueS
}
const keys: string[] = [];
- const values: firebase.database.DataSnapshot[] = [];
+ const values: DataSnapshot[] = [];
snapshots.forEach((snapshot) => {
if (!snapshot.key) {
return;
@@ -152,7 +152,7 @@ const setValue = (snapshots: firebase.database.DataSnapshot[] | null): KeyValueS
const addChild = (
currentState: KeyValueState,
- snapshot: firebase.database.DataSnapshot,
+ snapshot: DataSnapshot,
previousKey?: string | null
): KeyValueState => {
if (!snapshot.key) {
@@ -182,7 +182,7 @@ const addChild = (
const changeChild = (
currentState: KeyValueState,
- snapshot: firebase.database.DataSnapshot
+ snapshot: DataSnapshot
): KeyValueState => {
if (!snapshot.key) {
return currentState;
@@ -199,7 +199,7 @@ const changeChild = (
const removeChild = (
currentState: KeyValueState,
- snapshot: firebase.database.DataSnapshot
+ snapshot: DataSnapshot
): KeyValueState => {
if (!snapshot.key) {
return currentState;
@@ -217,7 +217,7 @@ const removeChild = (
const moveChild = (
currentState: KeyValueState,
- snapshot: firebase.database.DataSnapshot,
+ snapshot: DataSnapshot,
previousKey?: string | null
): KeyValueState => {
// Remove the child from it's previous location
diff --git a/database/index.js.flow b/database/index.js.flow
deleted file mode 100644
index 0a4201d..0000000
--- a/database/index.js.flow
+++ /dev/null
@@ -1,27 +0,0 @@
-// @flow
-import typeof { FirebaseError } from 'firebase';
-import type { DataSnapshot, Query } from 'firebase/database';
-
-type LoadingHook = [T | void, boolean, FirebaseError | 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/database/types.ts b/database/types.ts
index c99e88a..0ec2446 100644
--- a/database/types.ts
+++ b/database/types.ts
@@ -1,29 +1,23 @@
-import firebase from 'firebase/app';
+import { DatabaseReference, DataSnapshot } from 'firebase/database';
import { LoadingHook } from '../util';
export type Val<
T,
KeyField extends string = '',
RefField extends string = ''
-> = T & Record & Record;
+> = T & Record & Record;
-export type ObjectHook = LoadingHook<
- firebase.database.DataSnapshot,
- firebase.FirebaseError
->;
+export type ObjectHook = LoadingHook;
export type ObjectValHook<
T,
KeyField extends string = '',
RefField extends string = ''
-> = LoadingHook, firebase.FirebaseError>;
+> = LoadingHook, Error>;
-export type ListHook = LoadingHook<
- firebase.database.DataSnapshot[],
- firebase.FirebaseError
->;
-export type ListKeysHook = LoadingHook;
+export type ListHook = LoadingHook;
+export type ListKeysHook = LoadingHook;
export type ListValsHook<
T,
KeyField extends string = '',
RefField extends string = ''
-> = LoadingHook[], firebase.FirebaseError>;
+> = LoadingHook[], Error>;
diff --git a/database/useList.ts b/database/useList.ts
index ab4d08c..02e5170 100644
--- a/database/useList.ts
+++ b/database/useList.ts
@@ -1,15 +1,24 @@
-import firebase from 'firebase/app';
+import {
+ DataSnapshot,
+ off,
+ onChildAdded as firebaseOnChildAdded,
+ onChildChanged as firebaseOnChildChanged,
+ onChildMoved as firebaseOnChildMoved,
+ onChildRemoved as firebaseOnChildRemoved,
+ onValue as firebaseOnValue,
+ Query,
+} from 'firebase/database';
import { useEffect, useMemo } from 'react';
+import { useIsEqualRef } from '../util';
import { snapshotToData, ValOptions } from './helpers';
import useListReducer from './helpers/useListReducer';
import { ListHook, ListKeysHook, ListValsHook, Val } from './types';
-import { useIsEqualRef } from '../util';
-export const useList = (query?: firebase.database.Query | null): ListHook => {
+export const useList = (query?: Query | null): ListHook => {
const [state, dispatch] = useListReducer();
const queryRef = useIsEqualRef(query, () => dispatch({ type: 'reset' }));
- const ref: firebase.database.Query | null | undefined = queryRef.current;
+ const ref: Query | null | undefined = queryRef.current;
useEffect(() => {
if (!ref) {
@@ -18,41 +27,37 @@ export const useList = (query?: firebase.database.Query | null): ListHook => {
}
const onChildAdded = (
- snapshot: firebase.database.DataSnapshot | null,
+ snapshot: DataSnapshot | null,
previousKey?: string | null
) => {
dispatch({ type: 'add', previousKey, snapshot });
};
- const onChildChanged = (
- snapshot: firebase.database.DataSnapshot | null
- ) => {
+ const onChildChanged = (snapshot: DataSnapshot | null) => {
dispatch({ type: 'change', snapshot });
};
const onChildMoved = (
- snapshot: firebase.database.DataSnapshot | null,
+ snapshot: DataSnapshot | null,
previousKey?: string | null
) => {
dispatch({ type: 'move', previousKey, snapshot });
};
- const onChildRemoved = (
- snapshot: firebase.database.DataSnapshot | null
- ) => {
+ const onChildRemoved = (snapshot: DataSnapshot | null) => {
dispatch({ type: 'remove', snapshot });
};
- const onError = (error: firebase.FirebaseError) => {
+ const onError = (error: Error) => {
dispatch({ type: 'error', error });
};
- const onValue = (snapshots: firebase.database.DataSnapshot[] | null) => {
+ const onValue = (snapshots: DataSnapshot[] | null) => {
dispatch({ type: 'value', snapshots });
};
- let childAddedHandler: ReturnType | undefined;
- const onInitialLoad = (snapshot: firebase.database.DataSnapshot) => {
+ let childAddedHandler: ReturnType | undefined;
+ const onInitialLoad = (snapshot: DataSnapshot) => {
const snapshotVal = snapshot.val();
let childrenToProcess = snapshotVal
? Object.keys(snapshot.val()).length
@@ -60,14 +65,14 @@ export const useList = (query?: firebase.database.Query | null): ListHook => {
// If the list is empty then initialise the hook and use the default `onChildAdded` behaviour
if (childrenToProcess === 0) {
- childAddedHandler = ref.on('child_added', onChildAdded, onError);
+ childAddedHandler = firebaseOnChildAdded(ref, onChildAdded, onError);
onValue([]);
} else {
// Otherwise, we load the first batch of children all to reduce re-renders
- const children: firebase.database.DataSnapshot[] = [];
+ const children: DataSnapshot[] = [];
const onChildAddedWithoutInitialLoad = (
- addedChild: firebase.database.DataSnapshot,
+ addedChild: DataSnapshot,
previousKey?: string | null
) => {
if (childrenToProcess > 0) {
@@ -81,45 +86,42 @@ export const useList = (query?: firebase.database.Query | null): ListHook => {
return;
}
- onChildAdded(snapshot, previousKey);
+ onChildAdded(addedChild, previousKey);
};
- childAddedHandler = ref.on(
- 'child_added',
+ childAddedHandler = firebaseOnChildAdded(
+ ref,
onChildAddedWithoutInitialLoad,
onError
);
}
};
- ref.once('value', onInitialLoad, onError);
- const childChangedHandler = ref.on(
- 'child_changed',
+ firebaseOnValue(ref, onInitialLoad, onError, { onlyOnce: true });
+ const childChangedHandler = firebaseOnChildChanged(
+ ref,
onChildChanged,
onError
);
- const childMovedHandler = ref.on('child_moved', onChildMoved, onError);
- const childRemovedHandler = ref.on(
- 'child_removed',
+ const childMovedHandler = firebaseOnChildMoved(ref, onChildMoved, onError);
+ const childRemovedHandler = firebaseOnChildRemoved(
+ ref,
onChildRemoved,
onError
);
return () => {
- ref.off('child_added', childAddedHandler);
- ref.off('child_changed', childChangedHandler);
- ref.off('child_moved', childMovedHandler);
- ref.off('child_removed', childRemovedHandler);
+ off(ref, 'child_added', childAddedHandler);
+ off(ref, 'child_changed', childChangedHandler);
+ off(ref, 'child_moved', childMovedHandler);
+ off(ref, 'child_removed', childRemovedHandler);
};
}, [dispatch, ref]);
- const resArray: ListHook = [state.value.values, state.loading, state.error];
- return useMemo(() => resArray, resArray);
+ return [state.value.values, state.loading, state.error];
};
-export const useListKeys = (
- query?: firebase.database.Query | null
-): ListKeysHook => {
+export const useListKeys = (query?: Query | null): ListKeysHook => {
const [snapshots, loading, error] = useList(query);
const values = useMemo(
() =>
@@ -128,9 +130,8 @@ export const useListKeys = (
: undefined,
[snapshots]
);
- const resArray: ListKeysHook = [values, loading, error];
- return useMemo(() => resArray, resArray);
+ return [values, loading, error];
};
export const useListVals = <
@@ -138,12 +139,16 @@ export const useListVals = <
KeyField extends string = '',
RefField extends string = ''
>(
- query?: firebase.database.Query | null,
+ query?: Query | null,
options?: ValOptions
): ListValsHook => {
- const keyField = options ? options.keyField : undefined;
- const refField = options ? options.refField : undefined;
- const transform = options ? options.transform : undefined;
+ // Breaking this out in both `useList` and `useObject` rather than
+ // within the `snapshotToData` prevents the developer needing to ensure
+ // that `options` is memoized. If `options` was passed directly then it
+ // would cause the values to be recalculated every time the whole
+ // `options object changed
+ const { keyField, refField, transform } = options ?? {};
+
const [snapshots, loading, error] = useList(query);
const values = useMemo(
() =>
@@ -155,10 +160,5 @@ export const useListVals = <
[snapshots, keyField, refField, transform]
);
- const resArray: ListValsHook = [
- values,
- loading,
- error,
- ];
- return useMemo(() => resArray, resArray);
+ return [values, loading, error];
};
diff --git a/database/useObject.ts b/database/useObject.ts
index 2315854..7346d82 100644
--- a/database/useObject.ts
+++ b/database/useObject.ts
@@ -1,15 +1,13 @@
-import firebase from 'firebase/app';
+import { DataSnapshot, off, onValue, Query } from 'firebase/database';
import { useEffect, useMemo } from 'react';
+import { useIsEqualRef, useLoadingValue } from '../util';
import { snapshotToData, ValOptions } from './helpers';
import { ObjectHook, ObjectValHook, Val } from './types';
-import { useIsEqualRef, useLoadingValue } from '../util';
-export const useObject = (
- query?: firebase.database.Query | null
-): ObjectHook => {
+export const useObject = (query?: Query | null): ObjectHook => {
const { error, loading, reset, setError, setValue, value } = useLoadingValue<
- firebase.database.DataSnapshot,
- firebase.FirebaseError
+ DataSnapshot,
+ Error
>();
const ref = useIsEqualRef(query, reset);
@@ -20,15 +18,14 @@ export const useObject = (
return;
}
- query.on('value', setValue, setError);
+ onValue(query, setValue, setError);
return () => {
- query.off('value', setValue);
+ off(query, 'value', setValue);
};
}, [ref.current]);
- const resArray: ObjectHook = [value, loading, error];
- return useMemo(() => resArray, resArray);
+ return [value, loading, error];
};
export const useObjectVal = <
@@ -36,12 +33,16 @@ export const useObjectVal = <
KeyField extends string = '',
RefField extends string = ''
>(
- query?: firebase.database.Query | null,
+ query?: Query | null,
options?: ValOptions
): ObjectValHook => {
- const keyField = options ? options.keyField : undefined;
- const refField = options ? options.refField : undefined;
- const transform = options ? options.transform : undefined;
+ // Breaking this out in both `useList` and `useObject` rather than
+ // within the `snapshotToData` prevents the developer needing to ensure
+ // that `options` is memoized. If `options` was passed directly then it
+ // would cause the values to be recalculated every time the whole
+ // `options object changed
+ const { keyField, refField, transform } = options ?? {};
+
const [snapshot, loading, error] = useObject(query);
const value = useMemo(
() =>
@@ -51,10 +52,5 @@ export const useObjectVal = <
[snapshot, keyField, refField, transform]
);
- const resArray: ObjectValHook = [
- value,
- loading,
- error,
- ];
- return useMemo(() => resArray, resArray);
+ return [value, loading, error];
};
diff --git a/firebase.json b/firebase.json
new file mode 100644
index 0000000..4711254
--- /dev/null
+++ b/firebase.json
@@ -0,0 +1,18 @@
+{
+ "functions": {
+ "runtime": "node16"
+ },
+ "firestore": {
+ "rules": "firestore.rules",
+ "indexes": "firestore.indexes.json"
+ },
+ "emulators": {
+ "firestore": {
+ "port": 8080
+ },
+ "ui": {
+ "enabled": false
+ },
+ "singleProjectMode": true
+ }
+}
diff --git a/firestore.indexes.json b/firestore.indexes.json
new file mode 100644
index 0000000..4ff4fab
--- /dev/null
+++ b/firestore.indexes.json
@@ -0,0 +1,26 @@
+{
+ // Example:
+ //
+ // "indexes": [
+ // {
+ // "collectionGroup": "widgets",
+ // "queryScope": "COLLECTION",
+ // "fields": [
+ // { "fieldPath": "foo", "arrayConfig": "CONTAINS" },
+ // { "fieldPath": "bar", "mode": "DESCENDING" }
+ // ]
+ // },
+ //
+ // "fieldOverrides": [
+ // {
+ // "collectionGroup": "widgets",
+ // "fieldPath": "baz",
+ // "indexes": [
+ // { "order": "ASCENDING", "queryScope": "COLLECTION" }
+ // ]
+ // },
+ // ]
+ // ]
+ "indexes": [],
+ "fieldOverrides": []
+}
\ No newline at end of file
diff --git a/firestore.rules b/firestore.rules
new file mode 100644
index 0000000..c3c1733
--- /dev/null
+++ b/firestore.rules
@@ -0,0 +1,8 @@
+rules_version = '2';
+service cloud.firestore {
+ match /databases/{database}/documents {
+ match /{document=**} {
+ allow read, write: if true;
+ }
+ }
+}
diff --git a/firestore/README.md b/firestore/README.md
index fc65993..04091cc 100644
--- a/firestore/README.md
+++ b/firestore/README.md
@@ -1,8 +1,6 @@
# React Firebase Hooks - Cloud Firestore
-React Firebase Hooks provides convenience listeners for Collections and Documents stored with
-Cloud Firestore. The hooks wrap around the `firebase.firestore.collection().onSnapshot()`
-and `firebase.firestore().doc().onSnapshot()` methods.
+React Firebase Hooks provides convenience listeners for Collections and Documents stored with Cloud Firestore. The hooks wrap around the `firestore.onSnapshot(...)` method.
In addition to returning the snapshot value, the hooks provide an `error` and `loading` property
to give a complete lifecycle for loading and listening to Cloud Firestore.
@@ -20,14 +18,18 @@ import { useCollection } from 'react-firebase-hooks/firestore';
List of Cloud Firestore hooks:
-- [useCollection](#usecollection)
-- [useCollectionOnce](#usecollectiononce)
-- [useCollectionData](#usecollectiondata)
-- [useCollectionDataOnce](#usecollectiondataonce)
-- [useDocument](#usedocument)
-- [useDocumentOnce](#usedocumentonce)
-- [useDocumentData](#usedocumentdata)
-- [useDocumentDataOnce](#usedocumentdataonce)
+- [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)
+ - [Transforming data](#transforming-data)
Additional functionality:
@@ -41,28 +43,29 @@ const [snapshot, loading, error] = useCollection(query, options);
Retrieve and monitor a collection value in Cloud Firestore.
-Returns a `firebase.firestore.QuerySnapshot` (if a query is specified), a `boolean` to indicate if the data is still being loaded and any `Error` returned by Firebase when trying to load the data.
+Returns a `firestore.QuerySnapshot` (if a query is specified), a `boolean` to indicate if the data is still being loaded and any `firestore.FirestoreError` returned by Firebase when trying to load the data.
The `useCollection` hook takes the following parameters:
-- `query`: (optional) `firebase.firestore.Query` for the data you would like to load
+- `query`: (optional) `firestore.Query` for the data you would like to load
- `options`: (optional) `Object` with the following parameters:
- - `snapshotListenOptions`: (optional) `firebase.firestore.SnapshotListenOptions` to customise how the query is loaded
+ - `snapshotListenOptions`: (optional) `firestore.SnapshotListenOptions` to customise how the query is loaded
Returns:
-- `snapshot`: a `firebase.firestore.QuerySnapshot`, or `undefined` if no query is supplied
+- `snapshot`: a `firestore.QuerySnapshot`, or `undefined` if no query is supplied
- `loading`: a `boolean` to indicate if the data is still being loaded
-- `error`: Any `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `error`: Any `firestore.FirestoreError` returned by Firebase when trying to load the data, or `undefined` if there is no error
#### Full example
```js
+import { getFirestore, collection } from 'firebase/firestore';
import { useCollection } from 'react-firebase-hooks/firestore';
const FirestoreCollection = () => {
const [value, loading, error] = useCollection(
- firebase.firestore().collection('hooks'),
+ collection(getFirestore(firebaseApp), 'hooks'),
{
snapshotListenOptions: { includeMetadataChanges: true },
}
@@ -94,68 +97,76 @@ const FirestoreCollection = () => {
const [snapshot, loading, error] = useCollectionOnce(query, options);
```
-Retrieve the current value of the `firebase.firestore.Query`.
+Retrieve the current value of the `firestore.Query`.
The `useCollectionOnce` hook takes the following parameters:
-- `query`: (optional) `firebase.firestore.Query` for the data you would like to load
+- `query`: (optional) `firestore.Query` for the data you would like to load
- `options`: (optional) `Object` with the following parameters:
- - `getOptions`: (optional) `firebase.firestore.GetOptions` to customise how the collection is loaded
+ - `getOptions`: (optional) `Object` to customise how the collection is loaded
+ - `source`: (optional): `'default' | 'server' | 'cache'` Describes whether we should get from server or cache.
Returns:
-- `snapshot`: a `firebase.firestore.QuerySnapshot`, or `undefined` if no query is supplied
+- `snapshot`: a `firestore.QuerySnapshot`, or `undefined` if no query is supplied
- `loading`: a `boolean` to indicate if the data is still being loaded
-- `error`: Any `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `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
### useCollectionData
```js
-const [values, loading, error] = useCollectionData < T > (query, options);
+const [values, loading, error, snapshot] =
+ useCollectionData < T > (query, options);
```
-As `useCollection`, but this hook extracts a typed list of the `firebase.firestore.QuerySnapshot.docs` values, rather than the
-`firebase.firestore.QuerySnapshot` itself.
+As `useCollection`, but this hook extracts a typed list of the `firestore.QuerySnapshot.docs` values, rather than the
+`firestore.QuerySnapshot` itself.
The `useCollectionData` hook takes the following parameters:
-- `query`: (optional) `firebase.firestore.Query` for the data you would like to load
+- `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 `firebase.firestore.QuerySnapshot.id` property.
- - `refField`: (optional) name of the field that should be populated with the `firebase.firestore.QuerySnapshot.ref` property.
- - `snapshotListenOptions`: (optional) `firebase.firestore.SnapshotListenOptions` to customise how the collection is loaded
- - `snapshotOptions`: (optional) `firebase.firestore.SnapshotOptions` to customise how data is retrieved from snapshots
- - `transform`: (optional) a function that receives the raw `firebase.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.
+ - `initialValue`: (optional) the initial value returned by the hook, until data from the firestore query has loaded
+ - `snapshotListenOptions`: (optional) `firestore.SnapshotListenOptions` to customise how the collection is loaded
+ - `snapshotOptions`: (optional) `firestore.SnapshotOptions` to customise how data is retrieved from snapshots
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 `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `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
+
+See [Transforming data](#transforming-data) for how to transform data as it leaves Firestore and access the underlying `id` and `ref` fields of the snapshot.
### useCollectionDataOnce
```js
-const [values, loading, error] = useCollectionDataOnce < T > (query, options);
+const [values, loading, error, snapshot] =
+ useCollectionDataOnce < T > (query, options);
```
-As `useCollectionData`, but this hook will only read the current value of the `firebase.firestore.Query`.
+As `useCollectionData`, but this hook will only read the current value of the `firestore.Query`.
The `useCollectionDataOnce` hook takes the following parameters:
-- `query`: (optional) `firebase.firestore.Query` for the data you would like to load
+- `query`: (optional) `firestore.Query` for the data you would like to load
- `options`: (optional) `Object` with the following parameters:
- - `getOptions`: (optional) `firebase.firestore.GetOptions` to customise how the collection is loaded
- - `idField`: (optional) name of the field that should be populated with the `firebase.firestore.QuerySnapshot.id` property.
- - `refField`: (optional) name of the field that should be populated with the `firebase.firestore.QuerySnapshot.ref` property.
- - `snapshotOptions`: (optional) `firebase.firestore.SnapshotOptions` to customise how data is retrieved from snapshots
- - `transform`: (optional) a function that receives the raw `firebase.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.
+ - `getOptions`: (optional) `Object` to customise how the collection is loaded
+ - `source`: (optional): `'default' | 'server' | 'cache'` Describes whether we should get from server or cache.
+ - `initialValue`: (optional) the initial value returned by the hook, until data from the firestore query has loaded
+ - `snapshotOptions`: (optional) `firestore.SnapshotOptions` to customise how data is retrieved from snapshots
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 `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `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
+- `reload()`: a function that can be called to trigger a reload of the data
+
+See [Transforming data](#transforming-data) for how to transform data as it leaves Firestore and access the underlying `id` and `ref` fields of the snapshot.
### useDocument
@@ -167,24 +178,25 @@ Retrieve and monitor a document value in Cloud Firestore.
The `useDocument` hook takes the following parameters:
-- `reference`: (optional) `firebase.firestore.DocumentReference` for the data you would like to load
+- `reference`: (optional) `firestore.DocumentReference` for the data you would like to load
- `options`: (optional) `Object` with the following parameters:
- - `snapshotListenOptions`: (optional) `firebase.firestore.SnapshotListenOptions` to customise how the query is loaded
+ - `snapshotListenOptions`: (optional) `firestore.SnapshotListenOptions` to customise how the query is loaded
Returns:
-- `snapshot`: a `firebase.firestore.DocumentSnapshot`, or `undefined` if no query is supplied
+- `snapshot`: a `firestore.DocumentSnapshot`, or `undefined` if no query is supplied
- `loading`: a `boolean` to indicate if the data is still being loaded
-- `error`: Any `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `error`: Any `firestore.FirestoreError` returned by Firebase when trying to load the data, or `undefined` if there is no error
#### Full example
```js
+import { getFirestore, doc } from 'firebase/firestore';
import { useDocument } from 'react-firebase-hooks/firestore';
const FirestoreDocument = () => {
const [value, loading, error] = useDocument(
- firebase.firestore().doc('hooks/nBShXiRGFAhuiPfBaGpt'),
+ doc(getFirestore(firebaseApp), 'hooks', 'nBShXiRGFAhuiPfBaGpt'),
{
snapshotListenOptions: { includeMetadataChanges: true },
}
@@ -204,82 +216,114 @@ 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 `firebase.firestore.DocumentReference`.
+Retrieve the current value of the `firestore.DocumentReference`.
The `useDocumentOnce` hook takes the following parameters:
-- `reference`: (optional) `firebase.firestore.DocumentReference` for the data you would like to load
+- `reference`: (optional) `firestore.DocumentReference` for the data you would like to load
- `options`: (optional) `Object` with the following parameters:
- - `getOptions`: (optional) `firebase.firestore.GetOptions` to customise how the collection is loaded
+ - `getOptions`: (optional) `Object` to customise how the collection is loaded
+ - `source`: (optional): `'default' | 'server' | 'cache'` Describes whether we should get from server or cache.
Returns:
-- `snapshot`: a `firebase.firestore.DocumentSnapshot`, or `undefined` if no reference is supplied
+- `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 `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `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 < T > (reference, options);
+const [value, loading, error, snapshot] =
+ useDocumentData < T > (reference, options);
```
-As `useDocument`, but this hook extracts the typed contents of `firebase.firestore.DocumentSnapshot.val()`, rather than the
-`firebase.firestore.DocumentSnapshot` itself.
+As `useDocument`, but this hook extracts the typed contents of `firestore.DocumentSnapshot.data()`, rather than the
+`firestore.DocumentSnapshot` itself.
The `useDocumentData` hook takes the following parameters:
-- `reference`: (optional) `firebase.firestore.DocumentReference` for the data you would like to load
+- `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 `firebase.firestore.DocumentSnapshot.id` property.
- - `refField`: (optional) name of the field that should be populated with the `firebase.firestore.QuerySnapshot.ref` property.
- - `snapshotListenOptions`: (optional) `firebase.firestore.SnapshotListenOptions` to customise how the collection is loaded
- - `snapshotOptions`: (optional) `firebase.firestore.SnapshotOptions` to customise how data is retrieved from snapshots
- - `transform`: (optional) a function that receives the raw `firebase.firestore.DocumentData` to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
+ - `initialValue`: (optional) the initial value returned by the hook, until data from the firestore query has loaded
+ - `snapshotListenOptions`: (optional) `firestore.SnapshotListenOptions` to customise how the collection is loaded
+ - `snapshotOptions`: (optional) `firestore.SnapshotOptions` to customise how data is retrieved from snapshots
Returns:
- `value`: `T`, or `undefined` if no query is supplied
- `loading`: a `boolean` to indicate if the data is still being loaded
-- `error`: Any `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `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
+
+See [Transforming data](#transforming-data) for how to transform data as it leaves Firestore and access the underlying `id` and `ref` fields of the snapshot.
### useDocumentDataOnce
```js
-const [value, loading, error] = useDocumentDataOnce < T > (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 `firebase.firestore.DocumentReference`.
+As `useDocument`, but this hook will only read the current value of the `firestore.DocumentReference`.
The `useDocumentDataOnce` hook takes the following parameters:
-- `reference`: (optional) `firebase.firestore.DocumentReference` for the data you would like to load
+- `reference`: (optional) `firestore.DocumentReference` for the data you would like to load
- `options`: (optional) `Object` with the following parameters:
- - `getOptions`: (optional) `firebase.firestore.GetOptions` to customise how the collection is loaded
- - `idField`: (optional) name of the field that should be populated with the `firebase.firestore.DocumentSnapshot.id` property.
- - `refField`: (optional) name of the field that should be populated with the `firebase.firestore.QuerySnapshot.ref` property.
- - `snapshotOptions`: (optional) `firebase.firestore.SnapshotOptions` to customise how data is retrieved from snapshots
- - `transform`: (optional) a function that receives the raw `firebase.firestore.DocumentData` to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
+ - `getOptions`: (optional) `Object` to customise how the collection is loaded
+ - `source`: (optional): `'default' | 'server' | 'cache'` Describes whether we should get from server or cache
+ - `initialValue`: (optional) the initial value returned by the hook, until data from the firestore query has loaded
+ - `snapshotOptions`: (optional) `firestore.SnapshotOptions` to customise how data is retrieved from snapshots
Returns:
- `value`: `T`, or `undefined` if no query is supplied
- `loading`: a `boolean` to indicate if the data is still being loaded
-- `error`: Any `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
+- `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
+
+See [Transforming data](#transforming-data) for how to transform data as it leaves Firestore and access the underlying `id` and `ref` fields of the snapshot.
## 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.
+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, as well as access the `id` and `ref` fields of the underlying snapshot. This is described here: https://firebase.google.com/docs/reference/js/firestore_.firestoredataconverter
-```js
-transform?: (val: any) => T;
-```
+> NOTE: This replaces the `transform`, `idField` and `refField` options that were available in `react-firebase-hooks` v4 and earlier.
-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`.
+### Example
-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.
+```js
+type Post = {
+ author: string,
+ id: string,
+ ref: DocumentReference,
+ title: string,
+};
-If the `transform` function is defined within your React component, it is recomended that you memoize the function to prevent unnecessry renders.
+const postConverter: FirestoreDataConverter = {
+ toFirestore(post: WithFieldValue): DocumentData {
+ return { author: post.author, title: post.title };
+ },
+ fromFirestore(
+ snapshot: QueryDocumentSnapshot,
+ options: SnapshotOptions
+ ): Post {
+ const data = snapshot.data(options);
+ return {
+ author: data.author,
+ id: snapshot.id,
+ ref: snapshot.ref,
+ title: data.title,
+ };
+ },
+};
+
+const ref = collection(firestore, 'posts').withConverter(postConverter);
+const [data, loading, error] = useCollectionData(ref);
+```
diff --git a/firestore/helpers/index.ts b/firestore/helpers/index.ts
index 014eedb..d803d9f 100644
--- a/firestore/helpers/index.ts
+++ b/firestore/helpers/index.ts
@@ -1,21 +1,44 @@
-import firebase from 'firebase/app';
+import {
+ CollectionReference,
+ DocumentReference,
+ Query,
+ queryEqual,
+ refEqual,
+} from 'firebase/firestore';
+import { RefHook, useComparatorRef } from '../../util';
-export const snapshotToData = (
- snapshot: firebase.firestore.DocumentSnapshot,
- snapshotOptions?: firebase.firestore.SnapshotOptions,
- idField?: string,
- refField?: string,
- transform?: (val: any) => T
-) => {
- if (!snapshot.exists) {
- return undefined;
- }
+const isRefEqual = <
+ T extends DocumentReference | CollectionReference
+>(
+ v1: T | null | undefined,
+ v2: T | null | undefined
+): boolean => {
+ const bothNull: boolean = !v1 && !v2;
+ const equal: boolean = !!v1 && !!v2 && refEqual(v1, v2);
+ return bothNull || equal;
+};
+
+export const useIsFirestoreRefEqual = <
+ T extends DocumentReference | CollectionReference
+>(
+ value: T | null | undefined,
+ onChange?: () => void
+): RefHook => {
+ return useComparatorRef(value, isRefEqual, onChange);
+};
+
+const isQueryEqual = >(
+ v1: T | null | undefined,
+ v2: T | null | undefined
+): boolean => {
+ const bothNull: boolean = !v1 && !v2;
+ const equal: boolean = !!v1 && !!v2 && queryEqual(v1, v2);
+ return bothNull || equal;
+};
- return {
- ...(transform
- ? transform(snapshot.data(snapshotOptions))
- : snapshot.data(snapshotOptions)),
- ...(idField ? { [idField]: snapshot.id } : null),
- ...(refField ? { [refField]: snapshot.ref } : null),
- };
+export const useIsFirestoreQueryEqual = >(
+ value: T | null | undefined,
+ onChange?: () => void
+): RefHook => {
+ return useComparatorRef(value, isQueryEqual, onChange);
};
diff --git a/firestore/index.js.flow b/firestore/index.js.flow
deleted file mode 100644
index 0ff6164..0000000
--- a/firestore/index.js.flow
+++ /dev/null
@@ -1,73 +0,0 @@
-// @flow
-import type {
- DocumentReference,
- DocumentSnapshot,
- GetOptions,
- Query,
- QuerySnapshot,
- SnapshotListenOptions,
-} from 'firebase/firestore';
-
-type LoadingHook = [T | void, boolean, Error | void];
-
-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 1962007..e28ab41 100644
--- a/firestore/types.ts
+++ b/firestore/types.ts
@@ -1,42 +1,61 @@
-import firebase from 'firebase/app';
+import {
+ DocumentData,
+ DocumentSnapshot,
+ FirestoreError,
+ QuerySnapshot,
+ SnapshotListenOptions,
+ SnapshotOptions,
+} from 'firebase/firestore';
import { LoadingHook } from '../util';
-type IDOptions = {
- idField?: string;
- refField?: string;
- snapshotOptions?: firebase.firestore.SnapshotOptions;
- transform?: (val: any) => T;
+export type IDOptions = {
+ snapshotOptions?: SnapshotOptions;
};
export type Options = {
- snapshotListenOptions?: firebase.firestore.SnapshotListenOptions;
+ snapshotListenOptions?: SnapshotListenOptions;
+};
+export type InitialValueOptions = {
+ initialValue?: T;
};
export type DataOptions = Options & IDOptions;
export type OnceOptions = {
- getOptions?: firebase.firestore.GetOptions;
+ getOptions?: GetOptions;
+};
+export type GetOptions = {
+ source?: 'default' | 'server' | 'cache';
};
export type OnceDataOptions = OnceOptions & IDOptions;
-export type Data<
- T = firebase.firestore.DocumentData,
- IDField extends string = '',
- RefField extends string = ''
-> = T & Record & Record;
-export type CollectionHook = LoadingHook<
- firebase.firestore.QuerySnapshot,
- firebase.FirebaseError
+export type CollectionHook = LoadingHook<
+ QuerySnapshot,
+ FirestoreError
>;
-export type CollectionDataHook<
- T = firebase.firestore.DocumentData,
- IDField extends string = '',
- RefField extends string = ''
-> = LoadingHook[], firebase.FirebaseError>;
+export type CollectionOnceHook = [
+ ...CollectionHook,
+ () => Promise
+];
+export type CollectionDataHook = [
+ ...LoadingHook,
+ QuerySnapshot | undefined
+];
+export type CollectionDataOnceHook = [
+ ...CollectionDataHook,
+ () => Promise
+];
-export type DocumentHook = LoadingHook<
- firebase.firestore.DocumentSnapshot,
- firebase.FirebaseError
+export type DocumentHook = LoadingHook<
+ DocumentSnapshot,
+ FirestoreError
>;
-export type DocumentDataHook<
- T = firebase.firestore.DocumentData,
- IDField extends string = '',
- RefField extends string = ''
-> = LoadingHook, firebase.FirebaseError>;
+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 ccae055..48084d0 100644
--- a/firestore/useCollection.ts
+++ b/firestore/useCollection.ts
@@ -1,136 +1,165 @@
-import firebase from 'firebase/app';
-import { useEffect, useMemo } from 'react';
-import { snapshotToData } from './helpers';
import {
- CollectionHook,
+ DocumentData,
+ FirestoreError,
+ getDocs,
+ getDocsFromCache,
+ getDocsFromServer,
+ onSnapshot,
+ Query,
+ QuerySnapshot,
+ SnapshotOptions,
+} from 'firebase/firestore';
+import { useCallback, useEffect, useMemo } from 'react';
+import { useLoadingValue } from '../util';
+import useIsMounted from '../util/useIsMounted';
+import { useIsFirestoreQueryEqual } from './helpers';
+import {
CollectionDataHook,
- Data,
+ CollectionDataOnceHook,
+ CollectionHook,
+ CollectionOnceHook,
DataOptions,
- OnceOptions,
+ GetOptions,
+ InitialValueOptions,
OnceDataOptions,
+ OnceOptions,
Options,
} from './types';
-import { useIsEqualRef, useLoadingValue } from '../util';
-export const useCollection = (
- query?: firebase.firestore.Query | null,
+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?: firebase.firestore.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 = firebase.firestore.DocumentData,
- IDField extends string = '',
- RefField extends string = ''
->(
- query?: firebase.firestore.Query | null,
- options?: DataOptions
-): CollectionDataHook => {
- return useCollectionDataInternal(true, query, options);
-};
+ return () => {
+ unsubscribe();
+ };
+ }, [ref.current]);
-export const useCollectionDataOnce = <
- T = firebase.firestore.DocumentData,
- IDField extends string = '',
- RefField extends string = ''
->(
- query?: firebase.firestore.Query | null,
- options?: OnceDataOptions
-): CollectionDataHook => {
- return useCollectionDataInternal(false, query, options);
+ return [value as QuerySnapshot, loading, error];
};
-const useCollectionInternal = (
- listen: boolean,
- query?: firebase.firestore.Query | null,
- options?: Options & OnceOptions
-) => {
+export const useCollectionOnce = (
+ query?: Query | null,
+ options?: OnceOptions
+): CollectionOnceHook => {
const { error, loading, reset, setError, setValue, value } = useLoadingValue<
- firebase.firestore.QuerySnapshot,
- firebase.FirebaseError
+ QuerySnapshot,
+ FirestoreError
>();
- const ref = useIsEqualRef(query, reset);
+ const isMounted = useIsMounted();
+ const ref = useIsFirestoreQueryEqual>(query, reset);
+
+ const loadData = useCallback(
+ async (query?: Query | null, options?: Options & OnceOptions) => {
+ if (!query) {
+ setValue(undefined);
+ return;
+ }
+ const get = getDocsFnFromGetOptions(options?.getOptions);
+
+ try {
+ const result = await get(query);
+ if (isMounted) {
+ setValue(result);
+ }
+ } catch (error) {
+ if (isMounted) {
+ setError(error as FirestoreError);
+ }
+ }
+ },
+ []
+ );
+
+ const reloadData = useCallback(() => loadData(ref.current, options), [
+ loadData,
+ ref.current,
+ ]);
useEffect(() => {
- if (!ref.current) {
- setValue(undefined);
- return;
- }
- if (listen) {
- const listener =
- options && options.snapshotListenOptions
- ? ref.current.onSnapshot(
- options.snapshotListenOptions,
- setValue,
- setError
- )
- : ref.current.onSnapshot(setValue, setError);
-
- return () => {
- listener();
- };
- } else {
- ref.current
- .get(options ? options.getOptions : undefined)
- .then(setValue)
- .catch(setError);
- }
+ loadData(ref.current, options);
}, [ref.current]);
- const resArray: CollectionHook = [
- value as firebase.firestore.QuerySnapshot,
- loading,
- error,
- ];
- return useMemo(() => resArray, resArray);
+ return [value as QuerySnapshot, loading, error, reloadData];
+};
+
+export const useCollectionData = (
+ query?: Query | null,
+ options?: DataOptions & InitialValueOptions
+): CollectionDataHook => {
+ const [snapshots, loading, error] = useCollection(query, options);
+
+ const values = getValuesFromSnapshots(
+ snapshots,
+ options?.snapshotOptions,
+ options?.initialValue
+ );
+
+ return [values, loading, error, snapshots];
};
-const useCollectionDataInternal = <
- T = firebase.firestore.DocumentData,
- IDField extends string = '',
- RefField extends string = ''
->(
- listen: boolean,
- query?: firebase.firestore.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,
+export const useCollectionDataOnce = (
+ query?: Query | null,
+ options?: OnceDataOptions & InitialValueOptions
+): CollectionDataOnceHook => {
+ const [snapshots, loading, error, reloadData] = useCollectionOnce(
query,
options
);
- const values = useMemo(
+
+ const values = getValuesFromSnapshots(
+ snapshots,
+ options?.snapshotOptions,
+ options?.initialValue
+ );
+
+ return [values, loading, error, snapshots, reloadData];
+};
+
+const getValuesFromSnapshots = (
+ snapshots: QuerySnapshot | undefined,
+ options?: SnapshotOptions,
+ initialValue?: T[]
+): T[] | undefined => {
+ return useMemo(
() =>
- (snapshots
- ? snapshots.docs.map((doc) =>
- snapshotToData(
- doc,
- snapshotOptions,
- idField,
- refField,
- transform
- )
- )
- : undefined) as Data[],
- [snapshots, snapshotOptions, idField, refField, transform]
+ (snapshots?.docs.map((doc) => doc.data(options)) ?? initialValue) as
+ | T[]
+ | undefined,
+ [snapshots, options]
);
+};
- const resArray: CollectionDataHook = [
- values,
- loading,
- error,
- ];
- return useMemo(() => resArray, resArray);
+const getDocsFnFromGetOptions = (
+ { source }: GetOptions = { source: 'default' }
+) => {
+ switch (source) {
+ default:
+ case 'default':
+ return getDocs;
+ case 'cache':
+ return getDocsFromCache;
+ case 'server':
+ return getDocsFromServer;
+ }
};
diff --git a/firestore/useDocument.test.ts b/firestore/useDocument.test.ts
new file mode 100644
index 0000000..cfed328
--- /dev/null
+++ b/firestore/useDocument.test.ts
@@ -0,0 +1,40 @@
+import { addDoc, collection, doc } from 'firebase/firestore';
+
+import { db } from '../test/firebase';
+import { renderHook } from '@testing-library/react-hooks';
+import { useDocument } from './useDocument';
+
+describe('useDocument hook', () => {
+ test('begins in loading state', async () => {
+ // arrange
+ const { id } = await addDoc(collection(db, 'test'), {});
+
+ // act
+ const { result, unmount } = renderHook(() =>
+ useDocument(doc(collection(db, 'test'), id))
+ );
+
+ //assert
+ expect(result.current[1]).toBeTruthy();
+
+ // clean up
+ unmount();
+ });
+
+ test('loads and returns data from server', async () => {
+ // arrange
+ const { id } = await addDoc(collection(db, 'test'), { name: 'bo' });
+
+ // act
+ const { result, waitFor, unmount } = renderHook(() =>
+ useDocument(doc(collection(db, 'test'), id))
+ );
+ await waitFor(() => result.current[1] === false);
+
+ // assert
+ expect(result.current[0]?.data()).toEqual({ name: 'bo' });
+
+ // clean up
+ unmount();
+ });
+});
diff --git a/firestore/useDocument.ts b/firestore/useDocument.ts
index f987a27..cfd8645 100644
--- a/firestore/useDocument.ts
+++ b/firestore/useDocument.ts
@@ -1,134 +1,167 @@
-import firebase from 'firebase/app';
-import { useEffect, useMemo } from 'react';
-import { snapshotToData } from './helpers';
import {
- Data,
+ DocumentData,
+ DocumentReference,
+ DocumentSnapshot,
+ FirestoreError,
+ getDoc,
+ getDocFromCache,
+ getDocFromServer,
+ onSnapshot,
+ SnapshotOptions,
+} from 'firebase/firestore';
+import { useCallback, useEffect, useMemo } from 'react';
+import { useLoadingValue } from '../util';
+import useIsMounted from '../util/useIsMounted';
+import { useIsFirestoreRefEqual } from './helpers';
+import {
DataOptions,
- DocumentHook,
DocumentDataHook,
- OnceOptions,
+ DocumentDataOnceHook,
+ DocumentHook,
+ DocumentOnceHook,
+ GetOptions,
+ InitialValueOptions,
OnceDataOptions,
+ OnceOptions,
Options,
} from './types';
-import { useIsEqualRef, useLoadingValue } from '../util';
-export const useDocument = (
- docRef?: firebase.firestore.DocumentReference | null,
+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?: firebase.firestore.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 = firebase.firestore.DocumentData,
- IDField extends string = '',
- RefField extends string = ''
->(
- docRef?: firebase.firestore.DocumentReference | null,
- options?: DataOptions
-): DocumentDataHook => {
- return useDocumentDataInternal(true, docRef, options);
-};
+ return () => {
+ unsubscribe();
+ };
+ }, [ref.current]);
-export const useDocumentDataOnce = <
- T = firebase.firestore.DocumentData,
- IDField extends string = '',
- RefField extends string = ''
->(
- docRef?: firebase.firestore.DocumentReference | null,
- options?: OnceDataOptions
-): DocumentDataHook => {
- return useDocumentDataInternal(false, docRef, options);
+ return [value as DocumentSnapshot, loading, error];
};
-const useDocumentInternal = (
- listen: boolean,
- docRef?: firebase.firestore.DocumentReference | null,
- options?: Options & OnceOptions
-): DocumentHook => {
+export const useDocumentOnce = (
+ docRef?: DocumentReference | null,
+ options?: OnceOptions
+): DocumentOnceHook => {
const { error, loading, reset, setError, setValue, value } = useLoadingValue<
- firebase.firestore.DocumentSnapshot,
- firebase.FirebaseError
+ DocumentSnapshot,
+ FirestoreError
>();
- const ref = useIsEqualRef(docRef, reset);
+ const isMounted = useIsMounted();
+ const ref = useIsFirestoreRefEqual