Add transform option for realtime database hooks. Fixes #91

Author: chrisbianca

database/README.md

@@ -14,12 +14,16 @@ import { useList } from 'react-firebase-hooks/database';
 
 List of Realtime Database hooks:
 
-- [useList](#uselistref)
+- [useList](#uselist)
 - [useListKeys](#uselistkeys)
 - [useListVals](#uselistvals)
 - [useObject](#useobject)
 - [useObjectVal](#useobjectval)
 
+Additional functionality:
+
+- [Transforming data](#transforming-data)
+
 ### useList
 
 ```js
@@ -100,6 +104,7 @@ The `useListVals` hook takes the following parameters:
 - `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.
 
 Returns:
 
@@ -160,9 +165,63 @@ The `useObjectVal` hook takes the following parameters:
 - `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()` 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:
 
 - `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
+
+## Transforming data
+
+Firebase allows a restricted number of data types in its store. The application, on the other hand, might require converting some of these types into whatever it really needs, `Date` types being a common case.
+
+Both `useListVals` and `useObjectVal` support an optional `transform` function which allows the transformation of the underlying Firebase data into whatever format the application requires.
+
+```js
+transform?: (val: any) => T;
+```
+
+The `transform` function is passed a single row of a data, so will be called once when used with `useObjectVal` and multiple times, when used with `useListVals`.
+
+The `transform` function will not receive the `id` or `ref` values referenced in the properties named in the `keyField` or `refField` options, nor it is expected to produce them. Either or both, if specified, will be merged afterwards.
+
+#### Full Example
+
+```js
+type SaleType = {
+  idSale: string,
+  date: Date, // <== it is declared as type Date which Firebase does not support.
+  // ...Other fields
+};
+const options = {
+  keyField: 'idSale',
+  transform: (val) => ({
+    ...val,
+    date: new Date(val.date),
+  }),
+};
+export const useSale: (
+  idSale: string
+) => [SaleType | undefined, boolean, any] = (idSale) =>
+  useObjectVal < SaleType > (database.ref(`sales/${idSale}`), options);
+export const useSales: () => [SaleType[] | undefined, boolean, any] = () =>
+  useListVals < SaleType > (database.ref('sales'), options);
+```
+
+The `transform` function might be used for various purposes:
+
+```js
+transform: ({ firstName, lastName, someBool, ...val }) => ({
+  // Merge in default values, declared elsewhere:
+  ...defaultValues,
+  // Override them with the actual values
+  ...val,
+  // Create new fields from existing values
+  fullName: `${firstName} ${lastName}`,
+  // Ensure a field is a proper boolean instead of truish or falsy:
+  someBool: !!someBool,
+  // Same goes for any other poorly represented data type
+});
+```

database/helpers/index.ts

@@ -1,17 +1,19 @@
 import firebase from 'firebase/app';
 
-export type ValOptions = {
+export type ValOptions<T> = {
   keyField?: string;
   refField?: string;
+  transform?: (val: any) => T;
 };
 
 const isObject = (val: any) =>
   val != null && typeof val === 'object' && Array.isArray(val) === false;
 
-export const snapshotToData = (
+export const snapshotToData = <T>(
   snapshot: firebase.database.DataSnapshot,
   keyField?: string,
-  refField?: string
+  refField?: string,
+  transform?: (val: any) => T
 ) => {
   if (!snapshot.exists) {
     return undefined;
@@ -20,7 +22,7 @@ export const snapshotToData = (
   const val = snapshot.val();
   if (isObject(val)) {
     return {
-      ...val,
+      ...(transform ? transform(val) : val),
       ...(keyField ? { [keyField]: snapshot.key } : null),
       ...(refField ? { [refField]: snapshot.ref } : null),
     };

database/useList.ts

@@ -139,16 +139,17 @@ export const useListVals = <
   RefField extends string = ''
 >(
   query?: firebase.database.Query | null,
-  options?: ValOptions
+  options?: ValOptions<T>
 ): ListValsHook<T, KeyField, RefField> => {
   const keyField = options ? options.keyField : undefined;
   const refField = options ? options.refField : undefined;
+  const transform = options ? options.transform : undefined;
   const [snapshots, loading, error] = useList(query);
   const values = useMemo(
     () =>
       (snapshots
         ? snapshots.map((snapshot) =>
-            snapshotToData(snapshot, keyField, refField)
+            snapshotToData(snapshot, keyField, refField, transform)
           )
         : undefined) as Val<T, KeyField, RefField>[],
     [snapshots, keyField, refField]

database/useObject.ts

@@ -37,15 +37,16 @@ export const useObjectVal = <
   RefField extends string = ''
 >(
   query?: firebase.database.Query | null,
-  options?: ValOptions
+  options?: ValOptions<T>
 ): ObjectValHook<T, KeyField, RefField> => {
   const keyField = options ? options.keyField : undefined;
   const refField = options ? options.refField : undefined;
+  const transform = options ? options.transform : undefined;
   const [snapshot, loading, error] = useObject(query);
   const value = useMemo(
     () =>
       (snapshot
-        ? snapshotToData(snapshot, keyField, refField)
+        ? snapshotToData(snapshot, keyField, refField, transform)
         : undefined) as Val<T, KeyField, RefField>,
     [snapshot, keyField, refField]
   );