Skip to content

Commit 003e2be

Browse files
chrisbiancachrisbianca
authored
Merge pull request #20 from CSFrequency/v2.0.x
v2.0 - Return arrays rather than objects
2 parents 5b7c3cf + 862b68c commit 003e2be

31 files changed

+1081
-990
lines changed

‎README.md

Lines changed: 8 additions & 441 deletions
Large diffs are not rendered by default.

‎auth/README.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# React Firebase Hooks - Auth
2+
3+
React Firebase Hooks provides a convenience listener for Firebase Auth's auth state. The hook wraps around the `firebase.auth().onAuthStateChange()` method to ensure that it is always up to date.
4+
5+
All hooks can be imported from `react-firebase-hooks/auth`, e.g.
6+
7+
```
8+
import { useAuthState } from 'react-firebase-hooks/auth';
9+
```
10+
11+
List of Auth hooks:
12+
13+
- [useAuthState](#useauthstate)
14+
15+
### useAuthState
16+
17+
```
18+
const [user, loading, error] = useAuthState(auth);
19+
```
20+
21+
Retrieve and monitor the authentication state from Firebase.
22+
23+
The `useAuthState` hook takes the following parameters:
24+
25+
- `auth`: `firebase.auth.Auth` instance for the app you would like to monitor
26+
27+
Returns:
28+
29+
- `user`: The `firebase.User` if logged in, or `void` if not
30+
- `loading`: A `boolean` to indicate whether the the authentication state is still being loaded
31+
- `error`: Any `firebase.auth.Error` returned by Firebase when trying to load the user, or `void` if there is no error
32+
33+
#### Full Example
34+
35+
```js
36+
import { useAuthState } from 'react-firebase-hooks/auth';
37+
38+
const CurrentUser = () => {
39+
const [user, initialising, error] = useAuthState(firebase.auth());
40+
const login = () => {
41+
firebase.auth().signInWithEmailAndPassword('[email protected]', 'password');
42+
};
43+
const logout = () => {
44+
firebase.auth().signOut();
45+
};
46+
47+
if (initialising) {
48+
return (
49+
<div>
50+
<p>Initialising User...</p>
51+
</div>
52+
);
53+
}
54+
if (error) {
55+
return (
56+
<div>
57+
<p>Error: {error}>/p>
58+
</div>
59+
)
60+
}
61+
if (user) {
62+
return (
63+
<div>
64+
<p>Current User: {user.email}</p>
65+
<button onClick={logout}>Log out</button>
66+
</div>
67+
);
68+
}
69+
return <button onClick={login}>Log in</button>;
70+
};
71+
```

‎auth/index.js.flow

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
// @flow
22
import type { FirebaseUser as User } from 'firebase';
33
import type { Auth } from 'firebase/auth';
4-
export type AuthStateHook = {
5-
user?: User,
6-
initialising: boolean,
7-
};
4+
import typeof { Error as AuthError } from 'firebase/auth';
5+
6+
type LoadingHook<T> = [T | void, boolean, AuthError | void];
7+
8+
export type AuthStateHook = LoadingHook<User>;
89
declare export function useAuthState(auth: Auth): AuthStateHook;

‎auth/useAuthState.ts

Lines changed: 8 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,18 @@
11
import { auth, User } from 'firebase';
22
import { useEffect } from 'react';
3-
import useLoadingValue from '../util/useLoadingValue';
3+
import { LoadingHook, useLoadingValue } from '../util';
44

5-
export type AuthStateHook = {
6-
user?: firebase.User;
7-
initialising: boolean;
8-
};
5+
export type AuthStateHook = LoadingHook<User, auth.Error>;
96

107
export default (auth: auth.Auth): AuthStateHook => {
11-
const { loading, setValue, value } = useLoadingValue<User>(
12-
() => auth.currentUser
13-
);
8+
const { error, loading, setError, setValue, value } = useLoadingValue<
9+
User,
10+
auth.Error
11+
>(() => auth.currentUser);
1412

1513
useEffect(
1614
() => {
17-
const listener = auth.onAuthStateChanged(setValue);
15+
const listener = auth.onAuthStateChanged(setValue, setError);
1816

1917
return () => {
2018
listener();
@@ -23,8 +21,5 @@ export default (auth: auth.Auth): AuthStateHook => {
2321
[auth]
2422
);
2523

26-
return {
27-
initialising: loading,
28-
user: value,
29-
};
24+
return [value, loading, error];
3025
};

‎database/README.md

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# React Firebase Hooks - Realtime Database
2+
3+
React Firebase Hooks provides convenience listeners for lists and values stored within the
4+
Firebase Realtime Database. The hooks wrap around the `firebase.database().ref().on()` method.
5+
6+
In addition to returning the list or value, the hooks provide an `error` and `loading` property
7+
to give a complete lifecycle for loading and listening to the Realtime Database.
8+
9+
All hooks can be imported from `react-firebase-hooks/database`, e.g.
10+
11+
```
12+
import { useList } from 'react-firebase-hooks/database';
13+
```
14+
15+
List of Realtime Database hooks:
16+
17+
- [useList](#uselistref)
18+
- [useListKeys](#uselistkeys)
19+
- [useListVals](#uselistvals)
20+
- [useObject](#useobjectref)
21+
- [useObjectVal](#useobjectval)
22+
23+
### useList
24+
25+
```
26+
const [snapshots, loading, error] = useList(reference);
27+
```
28+
29+
Retrieve and monitor a list value in the Firebase Realtime Database.
30+
31+
The `useList` hook takes the following parameters:
32+
33+
- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
34+
35+
Returns:
36+
37+
- `snapshots`: an array of `firebase.database.DataSnapshot`, or `void` if no reference is supplied
38+
- `loading`: a `boolean` to indicate if the data is still being loaded
39+
- `error`: Any `firebase.FirebaseError` returned by Firebase when trying to load the data, or `void` if there is no error
40+
41+
#### Full Example
42+
43+
```js
44+
import { useList } from 'react-firebase-hooks/database';
45+
46+
const DatabaseList = () => {
47+
const [snapshots, loading, error] = useList(firebase.database().ref('list'));
48+
49+
return (
50+
<div>
51+
<p>
52+
{error && <strong>Error: {error}</strong>}
53+
{loading && <span>List: Loading...</span>}
54+
{!loading && value && (
55+
<React.Fragment>
56+
<span>
57+
List:{' '}
58+
{value.map(v => (
59+
<React.Fragment key={v.key}>{v.val()}, </React.Fragment>
60+
))}
61+
</span>
62+
</React.Fragment>
63+
)}
64+
</p>
65+
</div>
66+
);
67+
};
68+
```
69+
70+
### useListKeys
71+
72+
```
73+
const [keys, loading, error] = useListKeys(reference);
74+
```
75+
76+
As `useList`, but this hooks extracts the `firebase.database.DataSnapshot.key` values, rather than the the `firebase.database.DataSnapshot`s themselves.
77+
78+
The `useListKeys` hook takes the following parameters:
79+
80+
- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
81+
82+
Returns:
83+
84+
- `keys`: an array of `string`, or `void` if no reference is supplied
85+
- `loading`: a `boolean` to indicate if the data is still being loaded
86+
- `error`: Any `firebase.FirebaseError` returned by Firebase when trying to load the data, or `void` if there is no error
87+
88+
### useListVals
89+
90+
```
91+
const [values, loading, error] = useListVals<T>(reference, options);
92+
```
93+
94+
As `useList`, but this hook extracts a typed list of the `firebase.database.DataSnapshot.val()` values, rather than the the
95+
`firebase.database.DataSnapshot`s themselves.
96+
97+
The `useListVals` hook takes the following parameters:
98+
99+
- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
100+
- `options`: (optional) `Object` with the following parameters:
101+
- `keyField`: (optional) `string` field name that should be populated with the `firebase.firestore.QuerySnapshot.id` property in the returned values
102+
103+
Returns:
104+
105+
- `values`: an array of `T`, or `void` if no reference is supplied
106+
- `loading`: a `boolean` to indicate if the data is still being loaded
107+
- `error`: Any `firebase.FirebaseError` returned by Firebase when trying to load the data, or `void` if there is no error
108+
109+
### useObject
110+
111+
```
112+
const [snapshot, loading, error] = useObject(reference);
113+
```
114+
115+
Retrieve and monitor an object or primitive value in the Firebase Realtime Database.
116+
117+
The `useObject` hook takes the following parameters:
118+
119+
- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
120+
121+
Returns:
122+
123+
- `snapshot`: a `firebase.database.DataSnapshot`, or `void` if no reference is supplied
124+
- `loading`: a `boolean` to indicate if the data is still being loaded
125+
- `error`: Any `firebase.FirebaseError` returned by Firebase when trying to load the data, or `void` if there is no error
126+
127+
#### Full Example
128+
129+
```js
130+
import { useObject } from 'react-firebase-hooks/database';
131+
132+
const DatabaseValue = () => {
133+
const [value, loading, error] = useObject(firebase.database().ref('value'));
134+
135+
return (
136+
<div>
137+
<p>
138+
{error && <strong>Error: {error}</strong>}
139+
{loading && <span>Value: Loading...</span>}
140+
{value && <span>Value: {value.val()}</span>}
141+
</p>
142+
</div>
143+
);
144+
};
145+
```
146+
147+
### useObjectVal
148+
149+
```
150+
const [value, loading, error] = useObjectVal<T>(reference, options);
151+
```
152+
153+
As `useObject`, but this hook returns the typed contents of `firebase.database.DataSnapshot.val()`, rather than the the
154+
`firebase.database.DataSnapshot` itself.
155+
156+
The `useObjectVal` hook takes the following parameters:
157+
158+
- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
159+
- `options`: (optional) `Object` with the following parameters:
160+
- `keyField`: (optional) `string` field name that should be populated with the `firebase.database.DataSnapshot.key` property in the returned value.
161+
162+
Returns:
163+
164+
- `value`: a `T`, or `void` if no reference is supplied
165+
- `loading`: a `boolean` to indicate if the data is still being loaded
166+
- `error`: Any `firebase.FirebaseError` returned by Firebase when trying to load the data, or `void` if there is no error

0 commit comments

Comments
 (0)