docs: notes about converter and serialize

Close #1083

Author: posva

docs/guide/global-options.md

@@ -19,3 +19,36 @@ globalFirestoreOptions.converter = ...
 </FirestoreExample>
 
 Changing these options will affect all calls to `useDocument()`, `useObject()`, ... in your application **and the Options API usage** as well (`$firestoreBind()`, `$rtdbBind()`).
+
+In both scenarios, you need to make sure the returned objects contain their original `id` so other VueFire functionalities can work correctly. The easies way to do this is by reusing the default `serialize`/`converter`:
+
+<FirestoreExample>
+
+```ts
+import { globalDatabaseOptions } from 'vuefire'
+
+const defaultSerialize = globalDatabaseOptions.serialize
+globalDatabaseOptions.serialize = (snapshot) => {
+  const data = defaultSerialize(snapshot)
+  // add anything custom to the returned object
+  data.metadata = snapshot.metadata
+  return data
+}
+```
+
+```ts
+import { globalFirestoreOptions } from 'vuefire'
+
+const defaultConverter = globalFirestoreOptions.converter
+globalFirestoreOptions.converter = {
+  toFirestore: defaultConverter.toFirestore,
+  fromFirestore: (snapshot, options) => {
+    const data = defaultConverter.fromFirestore(snapshot, options)
+    // add anything custom to the returned object
+    data.metadata = snapshot.metadata
+    return data
+  },
+}
+```
+
+</FirestoreExample>

src/database/subscribe.ts

@@ -30,7 +30,8 @@ import type { Query, DatabaseReference, DataSnapshot } from 'firebase/database'
  */
 export interface _DatabaseRefOptions extends _DataSourceOptions {
   /**
-   * Function to transform snapshots into data. By default it will
+   * Function to transform snapshots into data. Make sure to reuse the original serializer to add the object id. See
+   * https://vuefire.vuejs.org/guide/global-options.html
    */
   serialize?: DatabaseSnapshotSerializer
 }

src/firestore/index.ts

@@ -49,7 +49,12 @@ export const ops: OperationsType = {
   remove: (array, index) => array.splice(index, 1),
 }
 
-export interface _UseFirestoreRefOptions extends FirestoreRefOptions {}
+export interface _UseFirestoreRefOptions extends FirestoreRefOptions {
+  /**
+   * @deprecated: use `.withConverter()` instead
+   */
+  converter?: any
+}
 
 /**
  * Internal version of `useDocument()` and `useCollection()`.

src/firestore/subscribe.ts

@@ -71,7 +71,8 @@ interface _FirestoreRefOptionsWithDefaults extends FirestoreRefOptions {
   maxRefDepth: number
 
   /**
-   * Default Firestore converter to use with snapshots.
+   * Default Firestore converter to use with snapshots. Make sure to reuse the original serializer to add the object id.
+   * See https://vuefire.vuejs.org/guide/global-options.html
    */
   converter: FirestoreDataConverter<unknown>
 }