Tweak error responses and API structure

Author: chrisbianca

auth/README.md

@@ -18,12 +18,18 @@ List of Auth hooks:
 const [user, loading, error] = useAuthState(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.
+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

auth/helpers/index.ts

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

auth/index.js.flow

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

auth/useAuthState.ts

@@ -15,7 +15,7 @@ import { useList } from 'react-firebase-hooks/database';
 List of Realtime Database hooks:
 
 - [useList](#uselistref)
-- [useListKeys](#uselistkeyst)
+- [useListKeys](#uselistkeys)
 - [useListVals](#uselistvals)
 - [useObject](#useobjectref)
 - [useObjectVal](#useobjectval)
@@ -26,12 +26,18 @@ List of Realtime Database hooks:
 const [snapshots, loading, error] = useList(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.
+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
@@ -67,38 +73,57 @@ const DatabaseList = () => {
 const [keys, loading, error] = useListKeys(reference);
 ```
 
-As `useList`, but this hook returns a list of the `firebase.database.DataSnapshot.key` values, rather than the the `firebase.database.DataSnapshot`s themselves.
+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, keyField);
+const [values, loading, error] = useListVals<T>(reference, options);
 ```
 
-As `useList`, but this hook returns a typed list of the `firebase.database.DataSnapshot.val()` values, rather than the the
-`DataSnapshot`s themselves.
+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
-- `keyField`: (optional) `string` field name that should be populated with the `firebase.database.DataSnapshot.key` property in the returned value.
+- `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);
 ```
 
-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.
+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
@@ -122,13 +147,20 @@ const DatabaseValue = () => {
 ### useObjectVal
 
 ```
-const [value, loading, error] = useObjectVal<T>(reference, keyField);
+const [value, loading, error] = useObjectVal<T>(reference, options);
 ```
 
-As `useObject`, but this hook returns the typed contents of `DataSnapshot.val()` rather than the
-`DataSnapshot` itself.
+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
-- `keyField`: (optional) `string` field name that should be populated with the `firebase.database.DataSnapshot.key` property in the returned value.
+- `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

database/README.md

@@ -14,7 +14,14 @@ declare export function useList(query?: Query | null): ListHook;
 declare export function useListKeys(query?: Query | null): ListKeysHook;
 declare export function useListVals<T>(
   query?: Query | null,
-  keyField?: string
+  options?: {
+    keyField?: string,
+  }
 ): ListValsHook<T>;
 declare export function useObject(query?: Query | null): ObjectHook;
-declare export function useObjectVal<T>(query?: Query | null): ObjectValHook<T>;
+declare export function useObjectVal<T>(
+  query?: Query | null,
+  options?: {
+    keyField?: string,
+  }
+): ObjectValHook<T>;

database/index.js.flow

@@ -81,12 +81,16 @@ export const useListKeys = (query?: database.Query | null): ListKeysHook => {
 
 export const useListVals = <T>(
   query?: database.Query | null,
-  keyField?: string
+  options?: {
+    keyField?: string;
+  }
 ): ListValsHook<T> => {
   const [value, loading, error] = useList(query);
   return [
     value
-      ? value.map(snapshot => snapshotToData(snapshot, keyField))
+      ? value.map(snapshot =>
+          snapshotToData(snapshot, options ? options.keyField : undefined)
+        )
       : undefined,
     loading,
     error,

database/useList.ts

@@ -8,7 +8,8 @@ export type ObjectValHook<T> = LoadingHook<T, FirebaseError>;
 
 export const useObject = (query?: database.Query | null): ObjectHook => {
   const { error, loading, reset, setError, setValue, value } = useLoadingValue<
-    database.DataSnapshot
+    database.DataSnapshot,
+    FirebaseError
   >();
   const ref = useIsEqualRef(query, reset);
 
@@ -34,8 +35,16 @@ export const useObject = (query?: database.Query | null): ObjectHook => {
 
 export const useObjectVal = <T>(
   query?: database.Query | null,
-  keyField?: string
+  options?: {
+    keyField?: string;
+  }
 ): ObjectValHook<T> => {
   const [value, loading, error] = useObject(query);
-  return [value ? snapshotToData(value, keyField) : undefined, loading, error];
+  return [
+    value
+      ? snapshotToData(value, options ? options.keyField : undefined)
+      : undefined,
+    loading,
+    error,
+  ];
 };