Add transform option to Firestore hooks. Closes #62

Author: chrisbianca

firestore/README.md

@@ -29,6 +29,10 @@ List of Cloud Firestore hooks:
 - [useDocumentData](#usedocumentdata)
 - [useDocumentDataOnce](#usedocumentdataonce)
 
+Additional functionality:
+
+- [Transforming data](#transforming-data)
+
 ### useCollection
 
 ```js
@@ -121,6 +125,7 @@ The `useCollectionData` hook takes the following parameters:
   - `refField`: (optional) name of the field that should be populated with the `firebase.firestore.QuerySnapshot.ref` property.
   - `snapshotListenOptions`: (optional) `firebase.firestore.SnapshotListenOptions` to customise how the collection is loaded
   - `snapshotOptions`: (optional) `firebase.firestore.SnapshotOptions` to customise how data is retrieved from snapshots
+  - `transform`: (optional) a function that receives the raw `firebase.firestore.DocumentData` for each item in the collection to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
 
 Returns:
 
@@ -144,6 +149,7 @@ The `useCollectionDataOnce` hook takes the following parameters:
   - `idField`: (optional) name of the field that should be populated with the `firebase.firestore.QuerySnapshot.id` property.
   - `refField`: (optional) name of the field that should be populated with the `firebase.firestore.QuerySnapshot.ref` property.
   - `snapshotOptions`: (optional) `firebase.firestore.SnapshotOptions` to customise how data is retrieved from snapshots
+  - `transform`: (optional) a function that receives the raw `firebase.firestore.DocumentData` for each item in the collection to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
 
 Returns:
 
@@ -232,6 +238,7 @@ The `useDocumentData` hook takes the following parameters:
   - `refField`: (optional) name of the field that should be populated with the `firebase.firestore.QuerySnapshot.ref` property.
   - `snapshotListenOptions`: (optional) `firebase.firestore.SnapshotListenOptions` to customise how the collection is loaded
   - `snapshotOptions`: (optional) `firebase.firestore.SnapshotOptions` to customise how data is retrieved from snapshots
+  - `transform`: (optional) a function that receives the raw `firebase.firestore.DocumentData` to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
 
 Returns:
 
@@ -255,9 +262,24 @@ The `useDocumentDataOnce` hook takes the following parameters:
   - `idField`: (optional) name of the field that should be populated with the `firebase.firestore.DocumentSnapshot.id` property.
   - `refField`: (optional) name of the field that should be populated with the `firebase.firestore.QuerySnapshot.ref` property.
   - `snapshotOptions`: (optional) `firebase.firestore.SnapshotOptions` to customise how data is retrieved from snapshots
+  - `transform`: (optional) a function that receives the raw `firebase.firestore.DocumentData` to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
 
 Returns:
 
 - `value`: `T`, or `undefined` if no query is supplied
 - `loading`: a `boolean` to indicate if the data is still being loaded
 - `error`: Any `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
+
+## Transforming data
+
+Firestore 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 `useCollectionData` and `useDocumentData` support an optional `transform` function which allows the transformation of the underlying Firestore 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 `useDocumentData` and multiple times when used with `useCollectionData`.
+
+The `transform` function will not receive the `id` or `ref` values referenced in the properties named in the `idField` or `refField` options, nor it is expected to produce them. Either or both, if specified, will be merged afterwards.

firestore/helpers/index.ts

@@ -1,17 +1,20 @@
 import firebase from 'firebase/app';
 
-export const snapshotToData = (
+export const snapshotToData = <T>(
   snapshot: firebase.firestore.DocumentSnapshot,
   snapshotOptions?: firebase.firestore.SnapshotOptions,
   idField?: string,
-  refField?: string
+  refField?: string,
+  transform?: (val: any) => T
 ) => {
   if (!snapshot.exists) {
     return undefined;
   }
 
   return {
-    ...snapshot.data(snapshotOptions),
+    ...(transform
+      ? transform(snapshot.data(snapshotOptions))
+      : snapshot.data(snapshotOptions)),
     ...(idField ? { [idField]: snapshot.id } : null),
     ...(refField ? { [refField]: snapshot.ref } : null),
   };

firestore/types.ts

@@ -1,19 +1,20 @@
 import firebase from 'firebase/app';
 import { LoadingHook } from '../util';
 
-type IDOptions = {
+type IDOptions<T> = {
   idField?: string;
   refField?: string;
   snapshotOptions?: firebase.firestore.SnapshotOptions;
+  transform?: (val: any) => T;
 };
 export type Options = {
   snapshotListenOptions?: firebase.firestore.SnapshotListenOptions;
 };
-export type DataOptions = Options & IDOptions;
+export type DataOptions<T> = Options & IDOptions<T>;
 export type OnceOptions = {
   getOptions?: firebase.firestore.GetOptions;
 };
-export type OnceDataOptions = OnceOptions & IDOptions;
+export type OnceDataOptions<T> = OnceOptions & IDOptions<T>;
 export type Data<
   T = firebase.firestore.DocumentData,
   IDField extends string = '',

firestore/useCollection.ts

@@ -32,7 +32,7 @@ export const useCollectionData = <
   RefField extends string = ''
 >(
   query?: firebase.firestore.Query<T> | null,
-  options?: DataOptions
+  options?: DataOptions<T>
 ): CollectionDataHook<T, IDField, RefField> => {
   return useCollectionDataInternal(true, query, options);
 };
@@ -43,7 +43,7 @@ export const useCollectionDataOnce = <
   RefField extends string = ''
 >(
   query?: firebase.firestore.Query<T> | null,
-  options?: OnceDataOptions
+  options?: OnceDataOptions<T>
 ): CollectionDataHook<T, IDField, RefField> => {
   return useCollectionDataInternal(false, query, options);
 };
@@ -100,11 +100,12 @@ const useCollectionDataInternal = <
 >(
   listen: boolean,
   query?: firebase.firestore.Query<T> | null,
-  options?: DataOptions & OnceDataOptions
+  options?: DataOptions<T> & OnceDataOptions<T>
 ): CollectionDataHook<T, IDField, RefField> => {
   const idField = options ? options.idField : undefined;
   const refField = options ? options.refField : undefined;
   const snapshotOptions = options ? options.snapshotOptions : undefined;
+  const transform = options ? options.transform : undefined;
   const [snapshots, loading, error] = useCollectionInternal<T>(
     listen,
     query,
@@ -114,10 +115,16 @@ const useCollectionDataInternal = <
     () =>
       (snapshots
         ? snapshots.docs.map((doc) =>
-            snapshotToData(doc, snapshotOptions, idField, refField)
+            snapshotToData<T>(
+              doc,
+              snapshotOptions,
+              idField,
+              refField,
+              transform
+            )
           )
         : undefined) as Data<T, IDField, RefField>[],
-    [snapshots, idField, refField]
+    [snapshots, idField, refField, transform]
   );
 
   const resArray: CollectionDataHook<T, IDField, RefField> = [

firestore/useDocument.ts

@@ -32,7 +32,7 @@ export const useDocumentData = <
   RefField extends string = ''
 >(
   docRef?: firebase.firestore.DocumentReference<T> | null,
-  options?: DataOptions
+  options?: DataOptions<T>
 ): DocumentDataHook<T, IDField, RefField> => {
   return useDocumentDataInternal(true, docRef, options);
 };
@@ -43,7 +43,7 @@ export const useDocumentDataOnce = <
   RefField extends string = ''
 >(
   docRef?: firebase.firestore.DocumentReference<T> | null,
-  options?: OnceDataOptions
+  options?: OnceDataOptions<T>
 ): DocumentDataHook<T, IDField, RefField> => {
   return useDocumentDataInternal(false, docRef, options);
 };
@@ -100,11 +100,12 @@ const useDocumentDataInternal = <
 >(
   listen: boolean,
   docRef?: firebase.firestore.DocumentReference<T> | null,
-  options?: DataOptions
+  options?: DataOptions<T>
 ): DocumentDataHook<T, IDField, RefField> => {
   const idField = options ? options.idField : undefined;
   const refField = options ? options.refField : undefined;
   const snapshotOptions = options ? options.snapshotOptions : undefined;
+  const transform = options ? options.transform : undefined;
   const [snapshot, loading, error] = useDocumentInternal<T>(
     listen,
     docRef,
@@ -113,7 +114,13 @@ const useDocumentDataInternal = <
   const value = useMemo(
     () =>
       (snapshot
-        ? snapshotToData(snapshot, snapshotOptions, idField, refField)
+        ? snapshotToData(
+            snapshot,
+            snapshotOptions,
+            idField,
+            refField,
+            transform
+          )
         : undefined) as Data<T, IDField, RefField>,
     [snapshot, idField, refField]
   );