feat(firestore): allow setting the ref value to null

Author: posva

src/firestore/index.ts

@@ -4,6 +4,7 @@ import type {
   Query,
   FirestoreError,
   DocumentData,
+  FirestoreDataConverter,
 } from 'firebase/firestore'
 import {
   getCurrentScope,
@@ -23,6 +24,7 @@ import {
   ResetOption,
   walkSet,
   _MaybeRef,
+  _Nullable,
   _RefWithState,
 } from '../shared'
 import { addPendingPromise } from '../ssr/plugin'
@@ -56,11 +58,13 @@ export interface _UseFirestoreRefOptions extends FirestoreRefOptions {
  */
 export function _useFirestoreRef(
   docOrCollectionRef: _MaybeRef<
-    DocumentReference<unknown> | Query<unknown> | CollectionReference<unknown>
+    _Nullable<
+      DocumentReference<unknown> | Query<unknown> | CollectionReference<unknown>
+    >
   >,
   localOptions?: _UseFirestoreRefOptions
 ) {
-  let _unbind!: UnbindType
+  let _unbind: UnbindType = noop
   const options = Object.assign({}, firestoreOptions, localOptions)
 
   // TODO: allow passing pending and error refs as option for when this is called using the options api
@@ -74,8 +78,19 @@ export function _useFirestoreRef(
   let removePendingPromise = noop
 
   function bindFirestoreRef() {
+    let docRefValue = unref(docOrCollectionRef)
+
     const p = new Promise<unknown | null>((resolve, reject) => {
-      let docRefValue = unref(docOrCollectionRef)
+      // stop the previous subscription
+      _unbind(options.reset)
+      // skip if the ref is null or undefined
+      // we still want to create the new promise
+      if (!docRefValue) {
+        _unbind = noop
+        // TODO: maybe we shouldn't resolve this at all?
+        return resolve(null)
+      }
+
       if (!docRefValue.converter) {
         docRefValue = docRefValue.withConverter(
           // @ts-expect-error: seems like a ts error
@@ -95,9 +110,9 @@ export function _useFirestoreRef(
     })
 
     // only add the first promise to the pending ones
-    if (!isPromiseAdded) {
+    if (!isPromiseAdded && docRefValue) {
       // TODO: is there a way to make this only for the first render?
-      removePendingPromise = addPendingPromise(p, unref(docOrCollectionRef))
+      removePendingPromise = addPendingPromise(p, docRefValue)
       isPromiseAdded = true
     }
     promise.value = p
@@ -173,7 +188,7 @@ export function useCollection<
   R extends CollectionReference<unknown> | Query<unknown>
 >(
   // TODO: add MaybeRef
-  collectionRef: _MaybeRef<R>,
+  collectionRef: _MaybeRef<_Nullable<R>>,
   options?: UseCollectionOptions
 ): _RefFirestore<_InferReferenceType<R>[]>
 
@@ -186,17 +201,20 @@ export function useCollection<
  * @param options - optional options
  */
 export function useCollection<T>(
-  collectionRef: _MaybeRef<CollectionReference | Query>,
+  collectionRef: _MaybeRef<_Nullable<CollectionReference | Query>>,
   options?: UseCollectionOptions
 ): _RefFirestore<VueFirestoreQueryData<T>>
 
 export function useCollection<T>(
-  collectionRef: _MaybeRef<CollectionReference<unknown> | Query<unknown>>,
+  collectionRef: _MaybeRef<
+    _Nullable<CollectionReference<unknown> | Query<unknown>>
+  >,
   options?: UseCollectionOptions
 ): _RefFirestore<VueFirestoreQueryData<T>> {
-  return _useFirestoreRef(collectionRef, options) as _RefFirestore<
-    VueFirestoreQueryData<T>
-  >
+  return _useFirestoreRef(collectionRef, {
+    target: ref([]),
+    ...options,
+  }) as _RefFirestore<VueFirestoreQueryData<T>>
 }
 
 // TODO: split document and collection into two different parts
@@ -213,7 +231,7 @@ export function useDocument<
   // explicit generic as unknown to allow arbitrary types like numbers or strings
   R extends DocumentReference<unknown>
 >(
-  documentRef: _MaybeRef<R>,
+  documentRef: _MaybeRef<_Nullable<R>>,
   options?: UseDocumentOptions
 ): _RefFirestore<_InferReferenceType<R>> // this one can't be null or should be specified in the converter
 
@@ -226,12 +244,12 @@ export function useDocument<
  * @param options - optional options
  */
 export function useDocument<T>(
-  documentRef: _MaybeRef<DocumentReference>,
+  documentRef: _MaybeRef<_Nullable<DocumentReference>>,
   options?: UseDocumentOptions
 ): _RefFirestore<VueFirestoreDocumentData<T>>
 
 export function useDocument<T>(
-  documentRef: _MaybeRef<DocumentReference<unknown>>,
+  documentRef: _MaybeRef<_Nullable<DocumentReference<unknown>>>,
   options?: UseDocumentOptions
 ):
   | _RefFirestore<VueFirestoreDocumentData<T> | null>

src/firestore/subscribe.ts

@@ -6,6 +6,7 @@ import {
   _MaybeRef,
   ResetOption,
   _DataSourceOptions,
+  noop,
 } from '../shared'
 import { ref, Ref, unref } from 'vue-demi'
 import type {
@@ -298,7 +299,7 @@ export function bindCollection<T = unknown>(
     },
   }
 
-  const unbind = onSnapshot(
+  const stopOnSnapshot = onSnapshot(
     collection,
     (snapshot) => {
       // console.log('pending', metadata.hasPendingWrites)
@@ -330,7 +331,7 @@ export function bindCollection<T = unknown>(
               }
               originalResolve(unref(arrayRef))
               // reset resolve to noop
-              resolve = () => {}
+              resolve = noop
             }
           }
         }
@@ -355,7 +356,7 @@ export function bindCollection<T = unknown>(
   )
 
   return (reset?: FirestoreRefOptions['reset']) => {
-    unbind()
+    stopOnSnapshot()
     if (reset !== false) {
       const value = typeof reset === 'function' ? reset() : []
       ops.set(target, key, value)
@@ -390,7 +391,7 @@ export function bindDocument<T>(
   // bind here the function so it can be resolved anywhere
   // this is specially useful for refs
   resolve = callOnceWithArg(resolve, () => walkGet(target, key))
-  const _unbind = onSnapshot(
+  const stopOnSnapshot = onSnapshot(
     document,
     (snapshot) => {
       if (snapshot.exists()) {
@@ -413,7 +414,7 @@ export function bindDocument<T>(
   )
 
   return (reset?: FirestoreRefOptions['reset']) => {
-    _unbind()
+    stopOnSnapshot()
     if (reset !== false) {
       const value = typeof reset === 'function' ? reset() : null
       ops.set(target, key, value)

src/shared.ts

@@ -30,6 +30,11 @@ export interface OperationsType {
  */
 export type ResetOption = boolean | (() => unknown)
 
+/**
+ * @internal
+ */
+export type _Nullable<T> = T | null | undefined
+
 export type TODO = any
 /**
  * Walks a path inside an object

tests/firestore/collection.spec.ts

@@ -16,7 +16,7 @@ import {
   UseCollectionOptions,
   VueFirestoreQueryData,
 } from '../../src'
-import { _MaybeRef } from '../../src/shared'
+import { _MaybeRef, _Nullable } from '../../src/shared'
 
 describe(
   'Firestore collections',
@@ -29,7 +29,7 @@ describe(
       ref = collection(),
     }: {
       options?: UseCollectionOptions
-      ref?: _MaybeRef<CollectionReference<T>>
+      ref?: _MaybeRef<_Nullable<CollectionReference<T>>>
     } = {}) {
       let data!: _RefFirestore<VueFirestoreQueryData<T>>
 
@@ -47,7 +47,8 @@ describe(
 
       return {
         wrapper,
-        listRef: unref(ref),
+        // to simplify types
+        listRef: unref(ref)!,
         // non enumerable properties cannot be spread
         data: data.data,
         pending: data.pending,
@@ -62,7 +63,7 @@ describe(
       ref,
     }: {
       options?: UseCollectionOptions
-      ref?: _MaybeRef<CollectionReference<T> | Query<T>>
+      ref?: _MaybeRef<_Nullable<CollectionReference<T> | Query<T>>>
     } = {}) {
       let data!: _RefFirestore<VueFirestoreQueryData<T>>
 
@@ -71,7 +72,7 @@ describe(
         setup() {
           // @ts-expect-error: generic forced
           data = useCollection(
-            // @ts-expect-error: generic forced
+            // split for ts
             ref,
             options
           )
@@ -263,19 +264,35 @@ describe(
       expect(data.value).toEqual([{ name: 'a' }])
     })
 
-    it('can be bound to a ref of a query', async () => {
+    async function createFilteredLists() {
       const listRef = collection<{ text: string; finished: boolean }>()
       const finishedListRef = query(listRef, where('finished', '==', true))
       const unfinishedListRef = query(listRef, where('finished', '==', false))
-      const showFinished = ref(false)
+      const showFinished = ref<boolean | null>(false)
       const listToDisplay = computed(() =>
-        showFinished.value ? finishedListRef : unfinishedListRef
+        showFinished.value
+          ? finishedListRef
+          : showFinished.value === false
+          ? unfinishedListRef
+          : null
       )
       await addDoc(listRef, { text: 'task 1', finished: false })
       await addDoc(listRef, { text: 'task 2', finished: false })
       await addDoc(listRef, { text: 'task 3', finished: true })
       await addDoc(listRef, { text: 'task 4', finished: false })
 
+      return {
+        listRef,
+        finishedListRef,
+        unfinishedListRef,
+        showFinished,
+        listToDisplay,
+      }
+    }
+
+    it('can be bound to a ref of a query', async () => {
+      const { showFinished, listToDisplay } = await createFilteredLists()
+
       const { wrapper, data, promise } = factoryQuery({
         ref: listToDisplay,
       })
@@ -294,6 +311,30 @@ describe(
       expect(data.value).toContainEqual({ text: 'task 3', finished: true })
     })
 
+    it('can be bound to a null ref', async () => {
+      const { showFinished, listToDisplay } = await createFilteredLists()
+      showFinished.value = null
+
+      const { data, promise } = factory({
+        // @ts-expect-error
+        ref: listToDisplay,
+      })
+      await promise.value
+
+      expect(data.value).toHaveLength(0)
+
+      showFinished.value = false
+      await nextTick()
+      await promise.value
+      expect(data.value).toHaveLength(3)
+
+      showFinished.value = null
+      await nextTick()
+      await promise.value
+      // it stays the same
+      expect(data.value).toHaveLength(3)
+    })
+
     tds(() => {
       interface TodoI {
         text: string

tests/firestore/document.spec.ts

@@ -7,7 +7,7 @@ import {
   FirestoreError,
 } from 'firebase/firestore'
 import { expectType, setupFirestoreRefs, tds, firestore } from '../utils'
-import { unref, type Ref } from 'vue'
+import { nextTick, shallowRef, unref, type Ref } from 'vue'
 import { _MaybeRef } from '../../src/shared'
 import {
   useDocument,
@@ -153,6 +153,73 @@ describe(
       })
     })
 
+    it('can be bound to a ref of a document', async () => {
+      const aRef = doc()
+      const bRef = doc()
+      await setDoc(aRef, { name: 'a' })
+      await setDoc(bRef, { name: 'b' })
+      const targetRef = shallowRef(bRef)
+
+      const { data, promise } = factory({ ref: targetRef })
+      await promise.value
+
+      expect(data.value).toEqual({ name: 'b' })
+
+      targetRef.value = aRef
+      await nextTick()
+      await promise.value
+      expect(data.value).toEqual({ name: 'a' })
+    })
+
+    it('can be bound to a null ref', async () => {
+      const aRef = doc()
+      const bRef = doc()
+      await setDoc(aRef, { name: 'a' })
+      await setDoc(bRef, { name: 'b' })
+      const targetRef = shallowRef()
+
+      const { data, promise } = factory({ ref: targetRef })
+      await promise.value
+
+      expect(data.value).toBeFalsy()
+
+      targetRef.value = aRef
+      expect(data.value).toBeFalsy()
+      await nextTick()
+      await promise.value
+      expect(data.value).toEqual({ name: 'a' })
+
+      targetRef.value = null
+      await nextTick()
+      await promise.value
+      // it stays the same
+      expect(data.value).toEqual({ name: 'a' })
+
+      targetRef.value = bRef
+      await nextTick()
+      await promise.value
+      // it stays the same
+      expect(data.value).toEqual({ name: 'b' })
+    })
+
+    it('can be set to a null ref', async () => {
+      const aRef = doc()
+      const bRef = doc()
+      await setDoc(aRef, { name: 'a' })
+      await setDoc(bRef, { name: 'b' })
+      const targetRef = shallowRef()
+
+      const { data, promise } = factory({ ref: targetRef })
+      await promise.value
+
+      expect(data.value).toBeFalsy()
+
+      targetRef.value = aRef
+      await nextTick()
+      await promise.value
+      expect(data.value).toEqual({ name: 'a' })
+    })
+
     tds(() => {
       const db = firestore
       const doc = originalDoc