feat: better defaults for wait and reset

BREAKING CHANGE: `wait` option now defaults to `true` to better align
with SSR. Similarly, the `reset` option now defaults to `false` to
better align with declarative usage of `useDocument()` and others. If
you want to keep the old behavior, you can still override the defaults
globally (refer to global options in the docs).

Author: posva

src/database/optionsApi.ts

@@ -7,6 +7,7 @@ import {
   bindAsObject,
   rtdbOptions,
   _DatabaseRefOptions,
+  _GlobalDatabaseRefOptions,
 } from './subscribe'
 
 /**
@@ -21,20 +22,17 @@ function getRef(refOrQuery: DatabaseReference | Query): DatabaseReference {
 /**
  * Options for the Firebase Database Plugin that enables the Options API such as `$rtdbBind` and `$rtdbUnbind`.
  */
-export interface DatabasePluginOptions {
+export interface DatabasePluginOptions
+  extends Partial<_GlobalDatabaseRefOptions> {
   bindName?: string
   unbindName?: string
-  serialize?: _DatabaseRefOptions['serialize']
-  reset?: _DatabaseRefOptions['reset']
-  wait?: _DatabaseRefOptions['wait']
 }
 
-const databasePluginDefaults: Readonly<Required<DatabasePluginOptions>> = {
+const databasePluginDefaults: Readonly<
+  Required<Omit<DatabasePluginOptions, keyof _GlobalDatabaseRefOptions>>
+> = {
   bindName: '$rtdbBind',
   unbindName: '$rtdbUnbind',
-  serialize: rtdbOptions.serialize,
-  reset: rtdbOptions.reset,
-  wait: rtdbOptions.wait,
 }
 
 declare module '@vue/runtime-core' {

src/database/subscribe.ts

@@ -3,7 +3,7 @@ import {
   indexForKey,
   DatabaseSnapshotSerializer,
 } from './utils'
-import { OperationsType, ResetOption } from '../shared'
+import { OperationsType, ResetOption, _DataSourceOptions } from '../shared'
 import { ref, Ref, unref } from 'vue-demi'
 import type { Query, DatabaseReference } from 'firebase/database'
 import {
@@ -15,24 +15,29 @@ import {
 } from 'firebase/database'
 
 // TODO: rename to match where it's used
-export interface _DatabaseRefOptions {
-  reset?: ResetOption
+export interface _DatabaseRefOptions extends _DataSourceOptions {
   serialize?: DatabaseSnapshotSerializer
-  wait?: boolean
 
   initialValue?: unknown
 }
 
 export interface _GlobalDatabaseRefOptions extends _DatabaseRefOptions {
+  /**
+   * @defaultValue `false`
+   */
   reset: ResetOption
-  serialize: DatabaseSnapshotSerializer
+  /**
+   * @defaultValue `true`
+   */
   wait: boolean
+
+  serialize: DatabaseSnapshotSerializer
 }
 
 const DEFAULT_OPTIONS: _GlobalDatabaseRefOptions = {
-  reset: true,
+  reset: false,
   serialize: createRecordFromDatabaseSnapshot,
-  wait: false,
+  wait: true,
 }
 
 // TODO: rename rtdbDefaults databaseDefaults

src/firestore/index.ts

@@ -31,7 +31,7 @@ import {
   bindCollection,
   bindDocument,
   firestoreOptions,
-  FirestoreOptions,
+  FirestoreRefOptions,
 } from './subscribe'
 
 export const ops: OperationsType = {
@@ -42,7 +42,10 @@ export const ops: OperationsType = {
 
 type UnbindType = ReturnType<typeof bindCollection | typeof bindDocument>
 
-export interface _UseFirestoreRefOptions extends FirestoreOptions {
+export interface _UseFirestoreRefOptions extends FirestoreRefOptions {
+  /**
+   * Use the `target` ref instead of creating one.
+   */
   target?: Ref<unknown>
 }
 
@@ -81,8 +84,8 @@ export function _useFirestoreRef(
       }
 
       _unbind = (isDocumentRef(docRefValue) ? bindDocument : bindCollection)(
+        // @ts-expect-error: cannot type with the ternary
         data,
-        // @ts-expect-error: the type is good because of the ternary
         docRefValue,
         ops,
         resolve,
@@ -246,15 +249,15 @@ export function internalUnbind(
   unbinds:
     | Record<string, ReturnType<typeof bindCollection | typeof bindDocument>>
     | undefined,
-  reset?: FirestoreOptions['reset']
+  reset?: FirestoreRefOptions['reset']
 ) {
   if (unbinds && unbinds[key]) {
     unbinds[key](reset)
     delete unbinds[key]
   }
 }
 
-export const unbind = (target: Ref, reset?: FirestoreOptions['reset']) =>
+export const unbind = (target: Ref, reset?: FirestoreRefOptions['reset']) =>
   internalUnbind('', firestoreUnbinds.get(target), reset)
 
 /**

src/firestore/optionsApi.ts

@@ -10,9 +10,11 @@ import {
   bindCollection,
   bindDocument,
   firestoreOptions,
-  FirestoreOptions,
+  FirestoreRefOptions,
+  _GlobalFirestoreRefOptions,
 } from './subscribe'
 import { internalUnbind, _useFirestoreRef } from '.'
+import { ResetOption } from '../shared'
 
 export type FirestoreOption = VueFirestoreObject | (() => VueFirestoreObject)
 
@@ -32,20 +34,17 @@ export const firestoreUnbinds = new WeakMap<
  * Options for the Firebase Database Plugin that enables the Options API such as `$firestoreBind` and
  * `$firestoreUnbind`.
  */
-export interface FirestorePluginOptions {
+export interface FirestorePluginOptions
+  extends Partial<_GlobalFirestoreRefOptions> {
   bindName?: string
   unbindName?: string
-  converter?: FirestoreOptions['converter']
-  reset?: FirestoreOptions['reset']
-  wait?: FirestoreOptions['wait']
 }
 
-const firestorePluginDefaults: Readonly<Required<FirestorePluginOptions>> = {
+const firestorePluginDefaults: Readonly<
+  Required<Omit<FirestorePluginOptions, keyof _GlobalFirestoreRefOptions>>
+> = {
   bindName: '$firestoreBind',
   unbindName: '$firestoreUnbind',
-  converter: firestoreOptions.converter,
-  reset: firestoreOptions.reset,
-  wait: firestoreOptions.wait,
 }
 
 /**
@@ -76,7 +75,7 @@ export const firestorePlugin = function firestorePlugin(
 
   GlobalTarget[unbindName] = function firestoreUnbind(
     key: string,
-    reset?: FirestoreOptions['reset']
+    reset?: FirestoreRefOptions['reset']
   ) {
     internalUnbind(key, firestoreUnbinds.get(this), reset)
     delete this.$firestoreRefs[key]
@@ -86,7 +85,7 @@ export const firestorePlugin = function firestorePlugin(
     this: ComponentPublicInstance,
     key: string,
     docOrCollectionRef: Query | CollectionReference | DocumentReference,
-    userOptions?: FirestoreOptions
+    userOptions?: FirestoreRefOptions
   ) {
     const options = Object.assign({}, globalOptions, userOptions)
     const target = toRef(this.$data as any, key)
@@ -163,26 +162,27 @@ declare module '@vue/runtime-core' {
       name: string,
       // TODO: create proper overloads with generics like in the composition API
       reference: Query<unknown> | CollectionReference<unknown>,
-      options?: FirestoreOptions
+      options?: FirestoreRefOptions
+      // TODO: match the promise with the type of internalBind
     ): Promise<DocumentData[]>
 
     $firestoreBind(
       name: string,
       // TODO: create proper overloads with generics like in the composition API
       reference: DocumentReference<unknown>,
-      options?: FirestoreOptions
+      options?: FirestoreRefOptions
     ): Promise<DocumentData>
 
     /**
      * Unbinds a bound reference
      */
-    $firestoreUnbind: (name: string, reset?: FirestoreOptions['reset']) => void
+    $firestoreUnbind: (name: string, reset?: ResetOption) => void
 
     /**
      * Bound firestore references
      */
     $firestoreRefs: Readonly<
-      Record<string, DocumentReference | CollectionReference>
+      Record<string, DocumentReference<unknown> | CollectionReference<unknown>>
     >
     // _firestoreSources: Readonly<
     //   Record<string, CollectionReference | Query | DocumentReference>

src/firestore/subscribe.ts

@@ -5,6 +5,7 @@ import {
   OperationsType,
   _MaybeRef,
   ResetOption,
+  _DataSourceOptions,
 } from '../shared'
 import { ref, Ref, unref } from 'vue-demi'
 import type {
@@ -20,12 +21,15 @@ import type {
 } from 'firebase/firestore'
 import { onSnapshot } from 'firebase/firestore'
 
-export interface FirestoreOptions {
+/**
+ * Options when binding a Firestore document or collection.
+ */
+export interface FirestoreRefOptions extends _DataSourceOptions {
+  /**
+   * The maximum depth to bind nested refs. A nested ref that isn't bound will stay as the ref path while a bound ref
+   * will contain the same data as if the ref was bound directly.
+   */
   maxRefDepth?: number
-  reset?: ResetOption
-
-  // FIXME: should only be possible in global options
-  converter?: FirestoreDataConverter<unknown>
 
   initialValue?: unknown
 
@@ -35,26 +39,38 @@ export interface FirestoreOptions {
    * @inheritDoc {SnapshotListenOptions}
    */
   snapshotListenOptions?: SnapshotListenOptions
-
-  wait?: boolean
 }
 
-export interface _GlobalFirestoreOptions extends FirestoreOptions {
-  maxRefDepth: number
+/**
+ * Type of the global options for firestore refs. Some values cannot be `undefined`.
+ * @internal
+ */
+export interface _GlobalFirestoreRefOptions extends FirestoreRefOptions {
+  /**
+   * @defaultValue `false`
+   */
   reset: ResetOption
-  converter: FirestoreDataConverter<unknown>
+  /**
+   * @defaultValue `true`
+   */
   wait: boolean
-}
 
-export interface VueFireFirestoreOptions extends FirestoreOptions {
-  converter?: FirestoreDataConverter<unknown>
+  /**
+   * @defaultValue `2`
+   */
+  maxRefDepth: number
+
+  /**
+   * Default Firestore converter to use with snapshots.
+   */
+  converter: FirestoreDataConverter<unknown>
 }
 
-const DEFAULT_OPTIONS: _GlobalFirestoreOptions = {
+const DEFAULT_OPTIONS: _GlobalFirestoreRefOptions = {
+  reset: false,
+  wait: true,
   maxRefDepth: 2,
-  reset: true,
   converter: firestoreDefaultConverter,
-  wait: false,
 }
 export { DEFAULT_OPTIONS as firestoreOptions }
 
@@ -74,7 +90,7 @@ function unsubscribeAll(subs: Record<string, FirestoreSubscription>) {
 }
 
 function updateDataFromDocumentSnapshot<T>(
-  options: _GlobalFirestoreOptions,
+  options: _GlobalFirestoreRefOptions,
   target: Ref<T>,
   path: string,
   snapshot: DocumentSnapshot<T>,
@@ -94,8 +110,8 @@ function updateDataFromDocumentSnapshot<T>(
   subscribeToRefs(options, target, path, subs, refs, ops, depth, resolve)
 }
 
-interface SubscribeToDocumentParamater {
-  target: CommonBindOptionsParameter['target']
+interface SubscribeToDocumentParameter {
+  target: Ref<unknown>
   path: string
   depth: number
   resolve: () => void
@@ -104,8 +120,8 @@ interface SubscribeToDocumentParamater {
 }
 
 function subscribeToDocument(
-  { ref, target, path, depth, resolve, ops }: SubscribeToDocumentParamater,
-  options: _GlobalFirestoreOptions
+  { ref, target, path, depth, resolve, ops }: SubscribeToDocumentParameter,
+  options: _GlobalFirestoreRefOptions
 ) {
   const subs = Object.create(null)
   const unbind = onSnapshot(ref, (snapshot) => {
@@ -132,22 +148,12 @@ function subscribeToDocument(
   }
 }
 
-// interface SubscribeToRefsParameter {
-//   subs: Record<string, FirestoreSubscription>
-//   target: CommonBindOptionsParameter['vm']
-//   refs: Record<string, DocumentReference>
-//   path: string | number
-//   depth: number
-//   resolve: CommonBindOptionsParameter['resolve']
-//   ops: CommonBindOptionsParameter['ops']
-// }
-
 // NOTE: not convinced by the naming of subscribeToRefs and subscribeToDocument
 // first one is calling the other on every ref and subscribeToDocument may call
 // updateDataFromDocumentSnapshot which may call subscribeToRefs as well
 function subscribeToRefs(
-  options: _GlobalFirestoreOptions,
-  target: CommonBindOptionsParameter['target'],
+  options: _GlobalFirestoreRefOptions,
+  target: Ref<unknown>,
   path: string | number,
   subs: Record<string, FirestoreSubscription>,
   refs: Record<string, DocumentReference>,
@@ -219,12 +225,12 @@ interface CommonBindOptionsParameter {
 }
 
 export function bindCollection<T = unknown>(
-  target: CommonBindOptionsParameter['target'],
+  target: Ref<unknown[]>,
   collection: CollectionReference<T> | Query<T>,
   ops: CommonBindOptionsParameter['ops'],
   resolve: CommonBindOptionsParameter['resolve'],
   reject: CommonBindOptionsParameter['reject'],
-  extraOptions?: FirestoreOptions
+  extraOptions?: FirestoreRefOptions
 ) {
   // FIXME: can be removed now
   const options = Object.assign({}, DEFAULT_OPTIONS, extraOptions) // fill default values
@@ -348,7 +354,7 @@ export function bindCollection<T = unknown>(
     reject
   )
 
-  return (reset?: FirestoreOptions['reset']) => {
+  return (reset?: FirestoreRefOptions['reset']) => {
     unbind()
     if (reset !== false) {
       const value = typeof reset === 'function' ? reset() : []
@@ -368,12 +374,12 @@ interface BindDocumentParameter extends CommonBindOptionsParameter {
  * @param extraOptions
  */
 export function bindDocument<T>(
-  target: BindDocumentParameter['target'],
+  target: Ref<unknown>,
   document: DocumentReference<T>,
   ops: BindDocumentParameter['ops'],
   resolve: BindDocumentParameter['resolve'],
   reject: BindDocumentParameter['reject'],
-  extraOptions?: FirestoreOptions
+  extraOptions?: FirestoreRefOptions
 ) {
   const options = Object.assign({}, DEFAULT_OPTIONS, extraOptions) // fill default values
   const key = 'value'
@@ -406,7 +412,7 @@ export function bindDocument<T>(
     reject
   )
 
-  return (reset?: FirestoreOptions['reset']) => {
+  return (reset?: FirestoreRefOptions['reset']) => {
     _unbind()
     if (reset !== false) {
       const value = typeof reset === 'function' ? reset() : null