From 31a91a35cab9561a7d71b745f0696f34f2160f8d Mon Sep 17 00:00:00 2001
From: David Stack <2013388+davidstackio@users.noreply.github.com>
Date: Mon, 13 Mar 2023 13:13:05 -0400
Subject: [PATCH 1/4] docs: add fetching once tip
---
docs/guide/realtime-data.md | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/docs/guide/realtime-data.md b/docs/guide/realtime-data.md
index e10090f9..32ea69ea 100644
--- a/docs/guide/realtime-data.md
+++ b/docs/guide/realtime-data.md
@@ -6,7 +6,13 @@ If you are looking for the VueFire Options API guide, make sure to **also check*
In VueFire, subscriptions to data changes are handled transparently. That's why we always talk about _binding_: you only provide the _data source_ (Collection, Query or Document), and VueFire takes care of the rest!
-When using Firebase Database and Firestore, you can either retrieve the data once or _subscribe_ to changes with methods like `onSnapshot()` and `onValue()`. VueFire will automatically handle the subscription for you, and update the data when it changes by internally using these functions, greatly simplifying the whole process of connecting your Vue Data to the realtime data from Firebase. It exposes a few [composables](https://vuejs.org/guide/reusability/composables.html#composables) to create these realtime bindings, it's important to note that, like other composables, these functions are meant to be used within a `setup()` function or a `<script setup>`. You can still use them outside of these contexts for advanced scenarios [like Vuex/Pinia](../cookbook/subscriptions-external.md) or global bindings but we will focus on the most common use case here. You can also use the [Options API equivalent](./options-api-realtime-data.md), in this section of the docs we will focus on the Composition API version and give you the equivalent for the Options API.
+When using Firebase Database and Firestore, you can either retrieve the data once or _subscribe_ to changes with methods like `onSnapshot()` and `onValue()`. VueFire will automatically handle the subscription for you, and update the data when it changes by internally using these functions, greatly simplifying the whole process of connecting your Vue Data to the realtime data from Firebase.
+
+::: tip
+To fetch data only _once_, use the [`once`](https://vuefire.vuejs.org/api/interfaces/UseDocumentOptions.html#once) option, which will retrieve a snapshot of the data. For example, `useDocument(q, { once: true })` or `useCollection(q, { once: true })`.
+:::
+
+VueFire exposes a few [composables](https://vuejs.org/guide/reusability/composables.html#composables) to create these realtime bindings, it's important to note that, like other composables, these functions are meant to be used within a `setup()` function or a `<script setup>`. You can still use them outside of these contexts for advanced scenarios [like Vuex/Pinia](../cookbook/subscriptions-external.md) or global bindings but we will focus on the most common use case here. You can also use the [Options API equivalent](./options-api-realtime-data.md), in this section of the docs we will focus on the Composition API version and give you the equivalent for the Options API.
## Declarative realtime data
From 64584730090ffaa659decf8a2d8c807ba14ab0b8 Mon Sep 17 00:00:00 2001
From: David Stack <2013388+davidstackio@users.noreply.github.com>
Date: Wed, 5 Jul 2023 16:35:06 -0400
Subject: [PATCH 2/4] add requested section
---
docs/guide/realtime-data.md | 44 +++++++++++++++++++++++++++++++++++++
1 file changed, 44 insertions(+)
diff --git a/docs/guide/realtime-data.md b/docs/guide/realtime-data.md
index e87aa685..533cd1c6 100644
--- a/docs/guide/realtime-data.md
+++ b/docs/guide/realtime-data.md
@@ -118,6 +118,50 @@ Notice how we rename `data` to whatever makes more sense for the context.
All of the properties that can be defined on the `Ref` are defined as [non-enumerable properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty) which means they won't be copied over when using the spread operator e.g. `const { data, ...rest } = useDocument(contactSource)`. This is to ensure they are completely ignored and do not create problems in other places like devtools.
:::
+### Fetching data once
+
+To fetch data only _once_, use the [`once`](https://vuefire.vuejs.org/api/interfaces/UseDocumentOptions.html#once) option, which will retrieve a snapshot of the data:
+
+<FirebaseExample>
+
+```vue
+<script setup>
+import { useDatabaseList } from 'vuefire'
+import { ref as dbRef } from 'firebase/database'
+
+const todos = useDatabaseList(dbRef(db, 'todos'), { once: true })
+const someTodo = useDatabaseObject(dbRef(db, 'todos', 'someId'), { once: true })
+</script>
+
+<template>
+ <ul>
+ <li v-for="todo in todos" :key="todo.id">
+ <span>{{ todo.text }}</span>
+ </li>
+ </ul>
+</template>
+```
+
+```vue
+<script setup>
+import { useCollection, useDocument } from 'vuefire'
+import { collection, doc } from 'firebase/firestore'
+
+const todos = useCollection(collection(db, 'todos'), { once: true })
+const someTodo = useDocument(doc(collection(db, 'todos'), 'someId'), { once: true })
+</script>
+
+<template>
+ <ul>
+ <li v-for="todo in todos" :key="todo.id">
+ <span>{{ todo.text }}</span>
+ </li>
+ </ul>
+</template>
+```
+
+</FirebaseExample>
+
## VueFire additions
VueFire adds a few properties to the data snapshot to make it easier to work with.
From ef4f3df6a065a8a352b58a9bd143d14a571b1361 Mon Sep 17 00:00:00 2001
From: David Stack <2013388+davidstackio@users.noreply.github.com>
Date: Wed, 5 Jul 2023 16:35:30 -0400
Subject: [PATCH 3/4] Revert "docs: add fetching once tip"
This reverts commit 31a91a35cab9561a7d71b745f0696f34f2160f8d.
---
docs/guide/realtime-data.md | 8 +-------
1 file changed, 1 insertion(+), 7 deletions(-)
diff --git a/docs/guide/realtime-data.md b/docs/guide/realtime-data.md
index 533cd1c6..8929d60b 100644
--- a/docs/guide/realtime-data.md
+++ b/docs/guide/realtime-data.md
@@ -6,13 +6,7 @@ If you are looking for the VueFire Options API guide, make sure to **also check*
In VueFire, subscriptions to data changes are handled transparently. That's why we always talk about _binding_: you only provide the _data source_ (Collection, Query or Document), and VueFire takes care of the rest!
-When using Firebase Database and Firestore, you can either retrieve the data once or _subscribe_ to changes with methods like `onSnapshot()` and `onValue()`. VueFire will automatically handle the subscription for you, and update the data when it changes by internally using these functions, greatly simplifying the whole process of connecting your Vue Data to the realtime data from Firebase.
-
-::: tip
-To fetch data only _once_, use the [`once`](https://vuefire.vuejs.org/api/interfaces/UseDocumentOptions.html#once) option, which will retrieve a snapshot of the data. For example, `useDocument(q, { once: true })` or `useCollection(q, { once: true })`.
-:::
-
-VueFire exposes a few [composables](https://vuejs.org/guide/reusability/composables.html#composables) to create these realtime bindings, it's important to note that, like other composables, these functions are meant to be used within a `setup()` function or a `<script setup>`. You can still use them outside of these contexts for advanced scenarios [like Vuex/Pinia](../cookbook/subscriptions-external.md) or global bindings but we will focus on the most common use case here. You can also use the [Options API equivalent](./options-api-realtime-data.md), in this section of the docs we will focus on the Composition API version and give you the equivalent for the Options API.
+When using Firebase Database and Firestore, you can either retrieve the data once or _subscribe_ to changes with methods like `onSnapshot()` and `onValue()`. VueFire will automatically handle the subscription for you, and update the data when it changes by internally using these functions, greatly simplifying the whole process of connecting your Vue Data to the realtime data from Firebase. It exposes a few [composables](https://vuejs.org/guide/reusability/composables.html#composables) to create these realtime bindings, it's important to note that, like other composables, these functions are meant to be used within a `setup()` function or a `<script setup>`. You can still use them outside of these contexts for advanced scenarios [like Vuex/Pinia](../cookbook/subscriptions-external.md) or global bindings but we will focus on the most common use case here. You can also use the [Options API equivalent](./options-api-realtime-data.md), in this section of the docs we will focus on the Composition API version and give you the equivalent for the Options API.
## Declarative realtime data
From c23631190726626a2d2747219c7237af88ec0c72 Mon Sep 17 00:00:00 2001
From: Eduardo San Martin Morote <posva@users.noreply.github.com>
Date: Thu, 6 Jul 2023 07:30:24 +0200
Subject: [PATCH 4/4] Apply suggestions from code review
---
docs/guide/realtime-data.md | 28 ++++------------------------
1 file changed, 4 insertions(+), 24 deletions(-)
diff --git a/docs/guide/realtime-data.md b/docs/guide/realtime-data.md
index 8929d60b..d92f54db 100644
--- a/docs/guide/realtime-data.md
+++ b/docs/guide/realtime-data.md
@@ -114,44 +114,24 @@ All of the properties that can be defined on the `Ref` are defined as [non-enume
### Fetching data once
-To fetch data only _once_, use the [`once`](https://vuefire.vuejs.org/api/interfaces/UseDocumentOptions.html#once) option, which will retrieve a snapshot of the data:
+To fetch data only _once_, pass the [`once`](https://vuefire.vuejs.org/api/interfaces/UseDocumentOptions.html#once) option, which will automatically destroy the subscription as soon as the document or collection is completely fetched:
<FirebaseExample>
-```vue
-<script setup>
-import { useDatabaseList } from 'vuefire'
+```ts{3,4}
+import { useDatabaseList, useDatabaseObject } from 'vuefire'
import { ref as dbRef } from 'firebase/database'
const todos = useDatabaseList(dbRef(db, 'todos'), { once: true })
const someTodo = useDatabaseObject(dbRef(db, 'todos', 'someId'), { once: true })
-</script>
-
-<template>
- <ul>
- <li v-for="todo in todos" :key="todo.id">
- <span>{{ todo.text }}</span>
- </li>
- </ul>
-</template>
```
-```vue
-<script setup>
+```ts{3,4}
import { useCollection, useDocument } from 'vuefire'
import { collection, doc } from 'firebase/firestore'
const todos = useCollection(collection(db, 'todos'), { once: true })
const someTodo = useDocument(doc(collection(db, 'todos'), 'someId'), { once: true })
-</script>
-
-<template>
- <ul>
- <li v-for="todo in todos" :key="todo.id">
- <span>{{ todo.text }}</span>
- </li>
- </ul>
-</template>
```
</FirebaseExample>