Skip to content

Commit 765be69

Browse files
EhespEhesp
authored
feat(react): implement Realtime Database hooks (#233)
1 parent 387a460 commit 765be69

74 files changed

Lines changed: 2114 additions & 16 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.changeset/real-database-hooks.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
"@tanstack-query-firebase/react": minor
3+
---
4+
5+
Add Firebase Realtime Database hooks via `@tanstack-query-firebase/react/database`.
6+
7+
- Query hooks: `useGetQuery`, `useOnValueQuery`, and child event listeners (`useOnChildAddedQuery`, `useOnChildChangedQuery`, `useOnChildMovedQuery`, `useOnChildRemovedQuery`)
8+
- Mutation hooks: `useSetMutation`, `useUpdateMutation`, `useRemoveMutation`, `usePushMutation`, `useRunTransactionMutation`, and priority helpers
9+
- Connection hooks: `useGoOnlineMutation`, `useGoOfflineMutation`
10+
- OnDisconnect hooks: `useOnDisconnectSetMutation`, `useOnDisconnectUpdateMutation`, `useOnDisconnectRemoveMutation`, `useOnDisconnectCancelMutation`, and priority variants

‎.github/workflows/test-react-firebase-v12.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,15 +36,15 @@ jobs:
3636
uses: actions/setup-java@v4
3737
with:
3838
distribution: "temurin"
39-
java-version: "17"
39+
java-version: "21"
4040

4141
- name: Install Firebase CLI
4242
uses: nick-invision/retry@v3
4343
with:
4444
timeout_minutes: 10
4545
retry_wait_seconds: 60
4646
max_attempts: 3
47-
command: npm i -g firebase-tools@latest
47+
command: pnpm add -g firebase-tools@14
4848

4949
- name: Update to Firebase v12
5050
run: |

‎docs.json‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -164,6 +164,101 @@
164164
}
165165
]
166166
},
167+
{
168+
"tab": "react",
169+
"group": "Realtime Database",
170+
"pages": [
171+
{
172+
"title": "Getting Started",
173+
"href": "/react/database"
174+
},
175+
{
176+
"group": "Hooks",
177+
"pages": [
178+
{
179+
"href": "/react/database/hooks/useGetQuery",
180+
"title": "useGetQuery"
181+
},
182+
{
183+
"href": "/react/database/hooks/useGoOfflineMutation",
184+
"title": "useGoOfflineMutation"
185+
},
186+
{
187+
"href": "/react/database/hooks/useGoOnlineMutation",
188+
"title": "useGoOnlineMutation"
189+
},
190+
{
191+
"href": "/react/database/hooks/useOnChildAddedQuery",
192+
"title": "useOnChildAddedQuery"
193+
},
194+
{
195+
"href": "/react/database/hooks/useOnChildChangedQuery",
196+
"title": "useOnChildChangedQuery"
197+
},
198+
{
199+
"href": "/react/database/hooks/useOnChildMovedQuery",
200+
"title": "useOnChildMovedQuery"
201+
},
202+
{
203+
"href": "/react/database/hooks/useOnChildRemovedQuery",
204+
"title": "useOnChildRemovedQuery"
205+
},
206+
{
207+
"href": "/react/database/hooks/useOnDisconnectCancelMutation",
208+
"title": "useOnDisconnectCancelMutation"
209+
},
210+
{
211+
"href": "/react/database/hooks/useOnDisconnectRemoveMutation",
212+
"title": "useOnDisconnectRemoveMutation"
213+
},
214+
{
215+
"href": "/react/database/hooks/useOnDisconnectSetMutation",
216+
"title": "useOnDisconnectSetMutation"
217+
},
218+
{
219+
"href": "/react/database/hooks/useOnDisconnectSetWithPriorityMutation",
220+
"title": "useOnDisconnectSetWithPriorityMutation"
221+
},
222+
{
223+
"href": "/react/database/hooks/useOnDisconnectUpdateMutation",
224+
"title": "useOnDisconnectUpdateMutation"
225+
},
226+
{
227+
"href": "/react/database/hooks/useOnValueQuery",
228+
"title": "useOnValueQuery"
229+
},
230+
{
231+
"href": "/react/database/hooks/usePushMutation",
232+
"title": "usePushMutation"
233+
},
234+
{
235+
"href": "/react/database/hooks/useRemoveMutation",
236+
"title": "useRemoveMutation"
237+
},
238+
{
239+
"href": "/react/database/hooks/useRunTransactionMutation",
240+
"title": "useRunTransactionMutation"
241+
},
242+
{
243+
"href": "/react/database/hooks/useSetMutation",
244+
"title": "useSetMutation"
245+
},
246+
{
247+
"href": "/react/database/hooks/useSetPriorityMutation",
248+
"title": "useSetPriorityMutation"
249+
},
250+
{
251+
"href": "/react/database/hooks/useSetWithPriorityMutation",
252+
"title": "useSetWithPriorityMutation"
253+
},
254+
{
255+
"href": "/react/database/hooks/useUpdateMutation",
256+
"title": "useUpdateMutation"
257+
}
258+
]
259+
}
260+
]
261+
},
167262
{
168263
"tab": "react",
169264
"group": "Firestore",

‎docs/react-query-firebase.mdx‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -39,16 +39,13 @@ although initially only React is supported.
3939
Altough still in development, the API is designed to work with the newer object-based API of TanStack Query,
4040
and also supports newer Firebase services such as Data Connect.
4141

42-
### Realtime Subscription Issues
42+
### Realtime Subscription Hooks
4343

44-
Firebase supports realtime event subscriptions for many of its services, such as Firestore, Realtime Database and
45-
Authentication.
44+
Firebase supports realtime event subscriptions for many of its services, such as Firestore, Realtime Database, and Authentication.
4645

47-
The `react-query-firebase` package had a [limitation](https://github.com/invertase/tanstack-query-firebase/issues/25) whereby the hooks
48-
would not resubscribe whenever a component re-mounted.
46+
The `react-query-firebase` package had a [limitation](https://github.com/invertase/tanstack-query-firebase/issues/25) whereby the hooks would not resubscribe whenever a component re-mounted.
4947

50-
The initial version of `tanstack-query-firebase` currently opts-out of any realtime subscription hooks. This issue will be re-addressed
51-
once the core API is stable supporting all Firebase services.
48+
TanStack Query Firebase now provides Realtime Database listener hooks (such as `useOnValueQuery` and the `useOnChild*` hooks) via `@tanstack-query-firebase/react/database`. Other services may add subscription hooks over time as the core API stabilizes.
5249

5350
## Migration Steps
5451

‎docs/react/database/hooks/useGetQuery.mdx‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: useGetQuery
3+
---
4+
5+
Read data once from a Realtime Database location.
6+
7+
## Usage
8+
9+
```tsx
10+
import { ref } from "firebase/database";
11+
import { useGetQuery } from "@tanstack-query-firebase/react/database";
12+
13+
const userRef = ref(database, `users/${uid}`);
14+
const { data: snapshot, isLoading } = useGetQuery(userRef, {
15+
queryKey: ["database", "users", uid],
16+
});
17+
const value = snapshot?.val();
18+
```

‎docs/react/database/hooks/useGoOfflineMutation.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: useGoOfflineMutation
3+
---
4+
5+
Disconnect the Realtime Database client from the server.
6+
7+
## Usage
8+
9+
```tsx
10+
import { useGoOfflineMutation } from "@tanstack-query-firebase/react/database";
11+
12+
const { mutate } = useGoOfflineMutation(database);
13+
mutate();
14+
```

‎docs/react/database/hooks/useGoOnlineMutation.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: useGoOnlineMutation
3+
---
4+
5+
Reconnect the Realtime Database client to the server.
6+
7+
## Usage
8+
9+
```tsx
10+
import { useGoOnlineMutation } from "@tanstack-query-firebase/react/database";
11+
12+
const { mutate } = useGoOnlineMutation(database);
13+
mutate();
14+
```

‎docs/react/database/hooks/useOnChildAddedQuery.mdx‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: useOnChildAddedQuery
3+
---
4+
5+
Subscribe to `child_added` events on a Realtime Database query.
6+
7+
## Usage
8+
9+
```tsx
10+
import { ref } from "firebase/database";
11+
import { useOnChildAddedQuery } from "@tanstack-query-firebase/react/database";
12+
13+
const messagesRef = ref(database, "messages");
14+
const { data: snapshot } = useOnChildAddedQuery(messagesRef, {
15+
queryKey: ["database", "childAdded", "messages"],
16+
});
17+
```

‎docs/react/database/hooks/useOnChildChangedQuery.mdx‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: useOnChildChangedQuery
3+
---
4+
5+
Subscribe to `child_changed` events on a Realtime Database query.
6+
7+
## Usage
8+
9+
```tsx
10+
import { ref } from "firebase/database";
11+
import { useOnChildChangedQuery } from "@tanstack-query-firebase/react/database";
12+
13+
const messagesRef = ref(database, "messages");
14+
const { data: snapshot } = useOnChildChangedQuery(messagesRef, {
15+
queryKey: ["database", "childChanged", "messages"],
16+
});
17+
```

‎docs/react/database/hooks/useOnChildMovedQuery.mdx‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: useOnChildMovedQuery
3+
---
4+
5+
Subscribe to `child_moved` events. Requires a query ordered with `orderByPriority()`.
6+
7+
## Usage
8+
9+
```tsx
10+
import { orderByPriority, query, ref } from "firebase/database";
11+
import { useOnChildMovedQuery } from "@tanstack-query-firebase/react/database";
12+
13+
const tasksRef = query(ref(database, "tasks"), orderByPriority());
14+
const { data: snapshot } = useOnChildMovedQuery(tasksRef, {
15+
queryKey: ["database", "childMoved", "tasks"],
16+
});
17+
```

0 commit comments

Comments
 (0)