Return arrays rather than objects from all hooks

Author: chrisbianca

auth/README.md

@@ -2,29 +2,35 @@
 
 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](#useauthstateauth)
+- [useAuthState](#useauthstate)
 
-### `useAuthState(auth)`
+### useAuthState
 
-Parameters:
+```
+const [user, loading, error] = useAuthState(auth);
+```
 
-- `auth`: `firebase.auth.Auth`
+Returns the `firebase.User` (if logged in), a boolean to indicate whether the the user is still being loaded and any `firebase.FirebaseError` returned by Firebase when trying to load the user.
 
-Returns:
-`AuthStateHook` containing:
+The `useAuthState` hook takes the following parameters:
 
-- `initialising`: If the listener is still waiting for the user to be loaded
-- `user`: The `firebase.User`, or `null`, if no user is logged in
+- `auth`: `firebase.auth.Auth` instance for the app you would like to monitor
 
-#### Example
+#### Full Example
 
 ```js
 import { useAuthState } from 'react-firebase-hooks/auth';
 
 const CurrentUser = () => {
-  const { initialising, user } = useAuthState(firebase.auth());
+  const [user, initialising, error] = useAuthState(firebase.auth());
   const login = () => {
     firebase.auth().signInWithEmailAndPassword('[email protected]', 'password');
   };
@@ -39,6 +45,13 @@ const CurrentUser = () => {
       </div>
     );
   }
+  if (error) {
+    return (
+      <div>
+        <p>Error: {error}>/p>
+      </div>
+    )
+  }
   if (user) {
     return (
       <div>

auth/helpers/index.ts

@@ -0,0 +1,10 @@
+import { auth, FirebaseError } from 'firebase';
+
+export const transformError = (error: auth.Error): FirebaseError => {
+  return {
+    message: error.message,
+    stack: '',
+    name: '',
+    code: error.code,
+  };
+};

auth/index.js.flow

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

auth/useAuthState.ts

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

database/README.md

@@ -6,34 +6,39 @@ Firebase Realtime Database. The hooks wrap around the `firebase.database().ref()
 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](#uselistkeystref)
-- [useListVals](#uselistvalstref-keyfield)
+- [useListKeys](#uselistkeyst)
+- [useListVals](#uselistvals)
 - [useObject](#useobjectref)
-- [useObjectVal](#useobjectvaltref)
+- [useObjectVal](#useobjectval)
 
-### `useList(ref)`
+### useList
 
-Parameters:
+```
+const [snapshots, loading, error] = useList(reference);
+```
 
-- `ref`: `firebase.database.Reference`
+Returns an array of `firebase.database.DataSnapshot` (if a reference is specified), a `boolean` to indicate if the data is still being loaded and any `firebase.FirebaseError` returned by Firebase when trying to load the data.
 
-Returns:
-`ListHook` containing
+The `useList` hook takes the following parameters:
 
-- `error`: An optional error object returned by Firebase
-- `loading`: A `boolean` to indicate if the listener is still being loaded
-- `value`: A list of `firebase.database.DataSnapshot`
+- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
 
-#### Example
+#### Full Example
 
 ```js
 import { useList } from 'react-firebase-hooks/database';
 
 const DatabaseList = () => {
-  const { error, loading, value } = useList(firebase.database().ref('list'));
+  const [snapshots, loading, error] = useList(firebase.database().ref('list'));
 
   return (
     <div>
@@ -56,59 +61,51 @@ const DatabaseList = () => {
 };
 ```
 
-### `useListKeys<T>(ref)`
+### useListKeys
 
-As above, but this hook returns a list of the `DataSnapshot.key` values, rather than the the
-`DataSnapshot`s themselves.
+```
+const [keys, loading, error] = useListKeys(reference);
+```
 
-Parameters:
+As `useList`, but this hook returns a list of the `firebase.database.DataSnapshot.key` values, rather than the the `firebase.database.DataSnapshot`s themselves.
 
-- `ref`: `firebase.database.Reference`
+The `useListKeys` hook takes the following parameters:
 
-Returns:
-`ListKeysHook` containing
+- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
 
-- `error`: An optional error object returned by Firebase
-- `loading`: A `boolean` to indicate if the listener is still being loaded
-- `value`: A list of `firebase.database.DataSnapshot.key` values
+### useListVals
 
-### `useListVals<T>(ref, keyField)`
+```
+const [values, loading, error] = useListVals<T>(reference, keyField);
+```
 
-Similar to `useList`, but this hook returns a typed list of the `DataSnapshot.val()` values, rather than the the
+As `useList`, but this hook returns a typed list of the `firebase.database.DataSnapshot.val()` values, rather than the the
 `DataSnapshot`s themselves.
 
-Parameters:
-
-- `ref`: `firebase.database.Reference`
-- `keyField`: (Optional) Name of field that should be populated with the `DataSnapshot.key` property
-
-Returns:
-`ListValsHook` containing
+The `useListVals` hook takes the following parameters:
 
-- `error`: An optional error object returned by Firebase
-- `loading`: A `boolean` to indicate if the listener is still being loaded
-- `value`: A list of `firebase.database.DataSnapshot.val()` values, combined with the optional key field
+- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
+- `keyField`: (optional) `string` field name that should be populated with the `firebase.database.DataSnapshot.key` property in the returned value.
 
-### `useObject(ref)`
+### useObject
 
-Parameters:
+```
+const [snapshot, loading, error] = useObject(reference);
+```
 
-- `ref`: `firebase.database.Reference`
+Returns a `firebase.database.DataSnapshot` (if a reference is specified), a `boolean` to indicate if the data is still being loaded and any `firebase.FirebaseError` returned by Firebase when trying to load the data.
 
-Returns:
-`ObjectHook` containing
+The `useObject` hook takes the following parameters:
 
-- `error`: An optional error object returned by Firebase
-- `loading`: A `boolean` to indicate if the listener is still being loaded
-- `value`: A `firebase.database.DataSnapshot`
+- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
 
-#### Example
+#### Full Example
 
 ```js
 import { useObject } from 'react-firebase-hooks/database';
 
 const DatabaseValue = () => {
-  const { error, loading, value } = useObject(firebase.database().ref('value'));
+  const [value, loading, error] = useObject(firebase.database().ref('value'));
 
   return (
     <div>
@@ -122,19 +119,16 @@ const DatabaseValue = () => {
 };
 ```
 
-### `useObjectVal<T>(ref)`
+### useObjectVal
 
-As above, but this hook returns the typed contents of `DataSnapshot.val()` rather than the
-`DataSnapshot` itself.
-
-Parameters:
+```
+const [value, loading, error] = useObjectVal<T>(reference, keyField);
+```
 
-- `ref`: `firebase.database.Reference`
-- `keyField`: (Optional) Name of field that should be populated with the `DataSnapshot.key` property
+As `useObject`, but this hook returns the typed contents of `DataSnapshot.val()` rather than the
+`DataSnapshot` itself.
 
-Returns:
-`ObjectValHook` containing
+The `useObjectVal` hook takes the following parameters:
 
-- `error`: An optional error object returned by Firebase
-- `loading`: A `boolean` to indicate if the listener is still being loaded
-- `value`: The contents of `firebase.database.DataSnapshot.val()`, combined with the optional key field
+- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
+- `keyField`: (optional) `string` field name that should be populated with the `firebase.database.DataSnapshot.key` property in the returned value.