Merge pull request #20 from CSFrequency/v2.0.x

v2.0 - Return arrays rather than objects

auth/README.md

@@ -0,0 +1,71 @@
+# React Firebase Hooks - Auth
+
+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.
+
+All hooks can be imported from `react-firebase-hooks/auth`, e.g.
+
+```
+import { useAuthState } from 'react-firebase-hooks/auth';
+```
+
+List of Auth hooks:
+
+- [useAuthState](#useauthstate)
+
+### useAuthState
+
+```
+const [user, loading, error] = useAuthState(auth);
+```
+
+Retrieve and monitor the authentication state from Firebase.
+
+The `useAuthState` hook takes the following parameters:
+
+- `auth`: `firebase.auth.Auth` instance for the app you would like to monitor
+
+Returns:
+
+- `user`: The `firebase.User` if logged in, or `void` if not
+- `loading`: A `boolean` to indicate whether the the authentication state is still being loaded
+- `error`: Any `firebase.auth.Error` returned by Firebase when trying to load the user, or `void` if there is no error
+
+#### Full Example
+
+```js
+import { useAuthState } from 'react-firebase-hooks/auth';
+
+const CurrentUser = () => {
+  const [user, initialising, error] = useAuthState(firebase.auth());
+  const login = () => {
+    firebase.auth().signInWithEmailAndPassword('[email protected]', 'password');
+  };
+  const logout = () => {
+    firebase.auth().signOut();
+  };
+
+  if (initialising) {
+    return (
+      <div>
+        <p>Initialising User...</p>
+      </div>
+    );
+  }
+  if (error) {
+    return (
+      <div>
+        <p>Error: {error}>/p>
+      </div>
+    )
+  }
+  if (user) {
+    return (
+      <div>
+        <p>Current User: {user.email}</p>
+        <button onClick={logout}>Log out</button>
+      </div>
+    );
+  }
+  return <button onClick={login}>Log in</button>;
+};
+```

auth/index.js.flow

@@ -1,8 +1,9 @@
 // @flow
 import type { FirebaseUser as User } from 'firebase';
 import type { Auth } from 'firebase/auth';
-export type AuthStateHook = {
-  user?: User,
-  initialising: boolean,
-};
+import typeof { Error as AuthError } from 'firebase/auth';
+
+type LoadingHook<T> = [T | void, boolean, AuthError | void];
+
+export type AuthStateHook = LoadingHook<User>;
 declare export function useAuthState(auth: Auth): AuthStateHook;

auth/useAuthState.ts

@@ -1,20 +1,18 @@
 import { auth, User } from 'firebase';
 import { useEffect } from 'react';
-import useLoadingValue from '../util/useLoadingValue';
+import { LoadingHook, useLoadingValue } from '../util';
 
-export type AuthStateHook = {
-  user?: firebase.User;
-  initialising: boolean;
-};
+export type AuthStateHook = LoadingHook<User, auth.Error>;
 
 export default (auth: auth.Auth): AuthStateHook => {
-  const { loading, setValue, value } = useLoadingValue<User>(
-    () => auth.currentUser
-  );
+  const { error, loading, setError, setValue, value } = useLoadingValue<
+    User,
+    auth.Error
+  >(() => auth.currentUser);
 
   useEffect(
     () => {
-      const listener = auth.onAuthStateChanged(setValue);
+      const listener = auth.onAuthStateChanged(setValue, setError);
 
       return () => {
         listener();
@@ -23,8 +21,5 @@ export default (auth: auth.Auth): AuthStateHook => {
     [auth]
   );
 
-  return {
-    initialising: loading,
-    user: value,
-  };
+  return [value, loading, error];
 };

database/README.md

@@ -0,0 +1,166 @@
+# React Firebase Hooks - Realtime Database
+
+React Firebase Hooks provides convenience listeners for lists and values stored within the
+Firebase Realtime Database. The hooks wrap around the `firebase.database().ref().on()` method.
+
+In addition to returning the list or value, the hooks provide an `error` and `loading` property
+to give a complete lifecycle for loading and listening to the Realtime Database.
+
+All hooks can be imported from `react-firebase-hooks/database`, e.g.
+
+```
+import { useList } from 'react-firebase-hooks/database';
+```
+
+List of Realtime Database hooks:
+
+- [useList](#uselistref)
+- [useListKeys](#uselistkeys)
+- [useListVals](#uselistvals)
+- [useObject](#useobjectref)
+- [useObjectVal](#useobjectval)
+
+### useList
+
+```
+const [snapshots, loading, error] = useList(reference);
+```
+
+Retrieve and monitor a list value in the Firebase Realtime Database.
+
+The `useList` hook takes the following parameters:
+
+- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
+
+Returns:
+
+- `snapshots`: an array of `firebase.database.DataSnapshot`, or `void` 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 `void` if there is no error
+
+#### Full Example
+
+```js
+import { useList } from 'react-firebase-hooks/database';
+
+const DatabaseList = () => {
+  const [snapshots, loading, error] = useList(firebase.database().ref('list'));
+
+  return (
+    <div>
+      <p>
+        {error && <strong>Error: {error}</strong>}
+        {loading && <span>List: Loading...</span>}
+        {!loading && value && (
+          <React.Fragment>
+            <span>
+              List:{' '}
+              {value.map(v => (
+                <React.Fragment key={v.key}>{v.val()}, </React.Fragment>
+              ))}
+            </span>
+          </React.Fragment>
+        )}
+      </p>
+    </div>
+  );
+};
+```
+
+### useListKeys
+
+```
+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.
+
+The `useListKeys` hook takes the following parameters:
+
+- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
+
+Returns:
+
+- `keys`: an array of `string`, or `void` 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 `void` if there is no error
+
+### useListVals
+
+```
+const [values, loading, error] = useListVals<T>(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.
+
+The `useListVals` hook takes the following parameters:
+
+- `reference`: (optional) `firebase.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.firestore.QuerySnapshot.id` property in the returned values
+
+Returns:
+
+- `values`: an array of `T`, or `void` 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 `void` if there is no error
+
+### useObject
+
+```
+const [snapshot, loading, error] = useObject(reference);
+```
+
+Retrieve and monitor an object or primitive value in the Firebase Realtime Database.
+
+The `useObject` hook takes the following parameters:
+
+- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
+
+Returns:
+
+- `snapshot`: a `firebase.database.DataSnapshot`, or `void` 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 `void` if there is no error
+
+#### Full Example
+
+```js
+import { useObject } from 'react-firebase-hooks/database';
+
+const DatabaseValue = () => {
+  const [value, loading, error] = useObject(firebase.database().ref('value'));
+
+  return (
+    <div>
+      <p>
+        {error && <strong>Error: {error}</strong>}
+        {loading && <span>Value: Loading...</span>}
+        {value && <span>Value: {value.val()}</span>}
+      </p>
+    </div>
+  );
+};
+```
+
+### useObjectVal
+
+```
+const [value, loading, error] = useObjectVal<T>(reference, options);
+```
+
+As `useObject`, but this hook returns the typed contents of `firebase.database.DataSnapshot.val()`, rather than the the
+`firebase.database.DataSnapshot` itself.
+
+The `useObjectVal` hook takes the following parameters:
+
+- `reference`: (optional) `firebase.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.
+
+Returns:
+
+- `value`: a `T`, or `void` 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 `void` if there is no error