feat(react): add usePowerSyncStatus hook (#137)

Co-authored-by: DominicGBauer <dominic@nomanini.com>

Author: DominicGBauer

.changeset/blue-cameras-flash.md

@@ -0,0 +1,5 @@
+---
+"@journeyapps/powersync-react": minor
+---
+
+Add `usePowerSyncStatus` hook

README.md

@@ -40,10 +40,12 @@ _Bad connectivity is everywhere, and we're tired of it. PowerSync is on a missio
 Demo applications are located in the [`demos/`](./demos/) directory. Also see our [Demo Apps / Example Projects](https://docs.powersync.com/resources/demo-apps-example-projects) gallery which lists all projects by the backend and client-side framework they use.
 
 ### React Native
+
 - [demos/react-native-supabase-todolist](./demos/react-native-supabase-todolist): A React Native to-do list example app using a Supabase backend.
 - [demos/django-react-native-todolist](./demos/django-react-native-todolist) A React Native to-do list example app using a Django backend.
 
 ### Web
+
 - [demos/react-supabase-todolist](./demos/react-supabase-todolist/README.md): A React to-do list example app using the PowerSync Web SDK and a Supabase backend.
 - [demos/yjs-react-supabase-text-collab](./demos/yjs-react-supabase-text-collab/README.md): A React real-time text editing collaboration example app powered by [Yjs](https://github.com/yjs/yjs) CRDTs and [Tiptap](https://tiptap.dev/), using the PowerSync Web SDK and a Supabase backend.
 - [demos/vue-supabase-todolist](./demos/vue-supabase-todolist/README.md): A Vue to-do list example app using the PowerSync Web SDK and a Supabase backend.

demos/django-react-native-todolist/library/widgets/HeaderWidget.tsx

@@ -3,6 +3,7 @@ import { Alert, Text } from 'react-native';
 import { Icon } from 'react-native-elements';
 import { useNavigation } from 'expo-router';
 import { useSystem } from '../stores/system';
+import { usePowerSyncStatus } from '@journeyapps/powersync-react';
 import { Header } from 'react-native-elements';
 import { observer } from 'mobx-react-lite';
 import { DrawerActions } from '@react-navigation/native';
@@ -12,7 +13,9 @@ export const HeaderWidget: React.FC<{
 }> = observer((props) => {
   const { title } = props;
   const { powersync } = useSystem();
+  const status = usePowerSyncStatus();
   const navigation = useNavigation();
+
   return (
     <Header
       leftComponent={
@@ -28,16 +31,15 @@ export const HeaderWidget: React.FC<{
       }
       rightComponent={
         <Icon
-          name={powersync.connected ? 'wifi' : 'wifi-off'}
+          name={status.connected ? 'wifi' : 'wifi-off'}
           type="material-community"
           color="black"
           size={20}
           style={{ padding: 5 }}
           onPress={() => {
             Alert.alert(
               'Status',
-              `${powersync.connected ? 'Connected' : 'Disconnected'}. \nLast Synced at ${
-                powersync.currentStatus?.lastSyncedAt.toISOString() ?? '-'
+              `${status.connected ? 'Connected' : 'Disconnected'}. \nLast Synced at ${status.lastSyncedAt?.toISOString() ?? '-'
               }\nVersion: ${powersync.sdkVersion}`
             );
           }}

demos/react-native-supabase-todolist/library/widgets/HeaderWidget.tsx

@@ -3,6 +3,7 @@ import { Alert, Text } from 'react-native';
 import { Icon } from 'react-native-elements';
 import { useNavigation } from 'expo-router';
 import { Header } from 'react-native-elements';
+import { usePowerSyncStatus } from '@journeyapps/powersync-react';
 import { DrawerActions } from '@react-navigation/native';
 import { useSystem } from '../powersync/system';
 
@@ -12,15 +13,7 @@ export const HeaderWidget: React.FC<{
   const system = useSystem();
   const { powersync } = system;
   const navigation = useNavigation();
-  const [connected, setConnected] = React.useState(powersync.connected);
-
-  React.useEffect(() => {
-    return powersync.registerListener({
-      statusChanged: (status) => {
-        setConnected(status.connected);
-      }
-    });
-  }, [powersync]);
+  const status = usePowerSyncStatus();
 
   const { title } = props;
   return (
@@ -38,7 +31,7 @@ export const HeaderWidget: React.FC<{
       }
       rightComponent={
         <Icon
-          name={connected ? 'wifi' : 'wifi-off'}
+          name={status.connected ? 'wifi' : 'wifi-off'}
           type="material-community"
           color="black"
           size={20}
@@ -47,8 +40,7 @@ export const HeaderWidget: React.FC<{
             system.attachmentQueue.trigger();
             Alert.alert(
               'Status',
-              `${connected ? 'Connected' : 'Disconnected'}. \nLast Synced at ${
-                powersync.currentStatus?.lastSyncedAt.toISOString() ?? '-'
+              `${status.connected ? 'Connected' : 'Disconnected'}. \nLast Synced at ${status?.lastSyncedAt?.toISOString() ?? '-'
               }\nVersion: ${powersync.sdkVersion}`
             );
           }}

demos/react-supabase-todolist/src/app/views/layout.tsx

@@ -25,16 +25,16 @@ import React from 'react';
 
 import { useNavigationPanel } from '@/components/navigation/NavigationPanelContext';
 import { useSupabase } from '@/components/providers/SystemProvider';
-import { usePowerSync } from '@journeyapps/powersync-react';
+import { usePowerSync, usePowerSyncStatus } from '@journeyapps/powersync-react';
 import { useNavigate } from 'react-router-dom';
 import { LOGIN_ROUTE, SQL_CONSOLE_ROUTE, TODO_LISTS_ROUTE } from '@/app/router';
 
 export default function ViewsLayout({ children }: { children: React.ReactNode }) {
   const powerSync = usePowerSync();
+  const status = usePowerSyncStatus();
   const supabase = useSupabase();
   const navigate = useNavigate();
 
-  const [syncStatus, setSyncStatus] = React.useState(powerSync.currentStatus);
   const [openDrawer, setOpenDrawer] = React.useState(false);
   const { title } = useNavigationPanel();
 
@@ -63,15 +63,6 @@ export default function ViewsLayout({ children }: { children: React.ReactNode })
     [powerSync, supabase]
   );
 
-  React.useEffect(() => {
-    const l = powerSync.registerListener({
-      statusChanged: (status) => {
-        setSyncStatus(status);
-      }
-    });
-    return () => l?.();
-  }, [powerSync]);
-
   return (
     <S.MainBox>
       <S.TopBar position="static">
@@ -89,12 +80,9 @@ export default function ViewsLayout({ children }: { children: React.ReactNode })
           <Box sx={{ flexGrow: 1 }}>
             <Typography>{title}</Typography>
           </Box>
-          <NorthIcon
-            sx={{ marginRight: '-10px' }}
-            color={syncStatus?.dataFlowStatus.uploading ? 'primary' : 'inherit'}
-          />
-          <SouthIcon color={syncStatus?.dataFlowStatus.downloading ? 'primary' : 'inherit'} />
-          {syncStatus?.connected ? <WifiIcon /> : <SignalWifiOffIcon />}
+          <NorthIcon sx={{ marginRight: '-10px' }} color={status?.dataFlowStatus.uploading ? 'primary' : 'inherit'} />
+          <SouthIcon color={status?.dataFlowStatus.downloading ? 'primary' : 'inherit'} />
+          {status?.connected ? <WifiIcon /> : <SignalWifiOffIcon />}
         </Toolbar>
       </S.TopBar>
       <Drawer anchor={'left'} open={openDrawer} onClose={() => setOpenDrawer(false)}>

packages/powersync-react/README.md

@@ -8,6 +8,7 @@ Configure a PowerSync DB connection and add it to a context provider.
 // App.jsx
 import { PowerSyncDatabase } from '@journeyapps/powersync-react-native';
 import { PowerSyncContext } from "@journeyapps/powersync-react";
+
 export const App = () => {
     const powerSync = React.useMemo(() => {
         // Setup PowerSync client
@@ -42,6 +43,22 @@ export const TodoListDisplay = () => {
     }
 ```
 
+### Accessing PowerSync Status
+
+The provided PowerSync client status is available with the `usePowerSyncStatus` hook.
+
+```JSX
+import { usePowerSyncStatus } from "@journeyapps/powersync-react";
+
+const Component = () => {
+  const status = usePowerSyncStatus();
+
+  return <div>
+    status.connected ? 'wifi' : 'wifi-off'
+  </div>
+};
+```
+
 ### Watched Queries
 
 Watched queries will automatically update when a dependant table is updated.

packages/powersync-react/package.json

@@ -14,6 +14,7 @@
   "scripts": {
     "build": "tsc -b",
     "clean": "rm -rf lib tsconfig.tsbuildinfo",
+    "test": "vitest",
     "watch": "tsc -b -w"
   },
   "repository": {
@@ -33,7 +34,10 @@
     "react": "*"
   },
   "devDependencies": {
+    "@testing-library/react": "^15.0.2",
+    "@testing-library/react-hooks": "^8.0.1",
     "@types/react": "^18.2.34",
+    "jsdom": "^24.0.0",
     "react": "18.2.0",
     "typescript": "^5.1.3"
   }

packages/powersync-react/src/hooks/usePowerSyncStatus.ts

@@ -0,0 +1,31 @@
+import { useContext, useEffect, useState } from 'react';
+import { PowerSyncContext } from './PowerSyncContext';
+
+/**
+ * Custom hook that provides access to the current status of PowerSync.
+ * @returns The PowerSync Database status.
+ * @example
+ * const Component = () => {
+ *   const status = usePowerSyncStatus();
+ *
+ *   return <div>
+ *     status.connected ? 'wifi' : 'wifi-off'
+ *   </div>
+ * };
+ */
+export const usePowerSyncStatus = () => {
+  const powerSync = useContext(PowerSyncContext);
+  const [syncStatus, setSyncStatus] = useState(powerSync.currentStatus);
+
+  useEffect(() => {
+    const listener = powerSync.registerListener({
+      statusChanged: (status) => {
+        setSyncStatus(status);
+      }
+    });
+
+    return () => listener?.();
+  }, [powerSync]);
+
+  return syncStatus;
+};

packages/powersync-react/src/index.ts

@@ -1,3 +1,4 @@
 export * from './hooks/PowerSyncContext';
-export * from './hooks/usePowerSyncQuery';
-export * from './hooks/usePowerSyncWatchedQuery';
+export { usePowerSyncQuery } from './hooks/usePowerSyncQuery';
+export { usePowerSyncWatchedQuery } from './hooks/usePowerSyncWatchedQuery';
+export { usePowerSyncStatus } from './hooks/usePowerSyncStatus';

packages/powersync-react/tests/PowerSyncContext.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import * as SUT from '../src/hooks/PowerSyncContext';
+
+describe('PowerSyncContext', () => {
+  describe('usePowerSync', () => {
+    it('should retrieve the PowerSync DB from the context and display the test text', async () => {
+      const TestComponent = () => {
+        const powerSyncDb = SUT.usePowerSync() as any;
+        return <div>{powerSyncDb.testText}</div>;
+      };
+
+      const { findByText } = render(
+        <SUT.PowerSyncContext.Provider value={{ testText: 'Test Text' } as any}>
+          <TestComponent />
+        </SUT.PowerSyncContext.Provider>
+      );
+      const hello = await findByText('Test Text');
+
+      expect(hello).toBeDefined;
+    });
+  });
+});