feat: add realtime hook

Author: tmm

docs/pages/documentation/auth/use-auth-state-change.md

@@ -1,6 +1,6 @@
 # useAuthStateChange
 
-Receive a notification every time an auth event happens. Composed in the [User Context example](/documentation/recipes/user-context).
+Receive a notification every time an auth event happens. Composed in the [`useAuth` recipe](/recipes/use-auth).
 
 ```js highlight=4,5,6
 import { useAuthStateChange } from 'react-supabase'

docs/pages/documentation/data/use-select.md

@@ -1,5 +1,3 @@
-import Link from 'next/link'
-
 # useSelect
 
 Performs vertical filtering with SELECT.

docs/pages/documentation/realtime/meta.json

@@ -1,3 +1,4 @@
 {
-    "use-subscription": "useSubscription"
+    "use-subscription": "useSubscription",
+    "use-realtime": "useRealtime"
 }

docs/pages/documentation/realtime/use-realtime.md

@@ -0,0 +1,30 @@
+# useRealtime
+
+Fetch table and listen for changes.
+
+```js highlight=4
+import { useRealtime } from 'react-supabase'
+
+function Page() {
+  const [{ data, error, fetching }, refresh] = useRealtime('todos')
+
+  return ...
+}
+```
+
+## Compare function
+
+You can pass a function for comparing subscription event changes. By default, the compare function checks the `id` field.
+
+```js highlight=6
+import { useRealtime } from 'react-supabase'
+
+function Page() {
+  const [{ data, error, fetching }, refresh] = useRealtime(
+    'todos',
+    (data, payload) => data.username === payload.username,
+  )
+
+  return ...
+}
+```

docs/pages/documentation/realtime/use-subscription.md

@@ -1,6 +1,6 @@
 # useSubscription
 
-Subscribe to realtime changes to databse.
+Subscribe to database changes in realtime.
 
 ```js highlight=4,5,6
 import { useSubscription } from 'react-supabase'

docs/pages/recipes/meta.json

@@ -1,3 +1,3 @@
 {
-    "auth-context": "AuthContext"
+    "use-auth": "useAuth"
 }

docs/pages/recipes/auth-context.md docs/pages/recipes/use-auth.mddocs/pages/recipes/auth-context.md renamed to docs/pages/recipes/use-auth.md

@@ -1,8 +1,6 @@
-# Auth Context
+# useAuth
 
-Keep track of the authenticated user using the [Context API](https://reactjs.org/docs/context.html) and `useAuthStateChange` hook.
-
-First, create a context and user hook:
+Keep track of the authenticated session with the [Context API](https://reactjs.org/docs/context.html) and [`useAuthStateChange`](/documentation/auth/use-auth-state-change) hook. First, create a new React Context:
 
 ```js
 import { createContext, useEffect, useState } from 'react'
@@ -11,7 +9,7 @@ import { useAuthStateChange, useClient } from 'react-supabase'
 const initialState = { session: null, user: null }
 export const AuthContext = createContext(initialState)
 
-export const AuthProvider = ({ children }) => {
+export function AuthProvider({ children }) {
   const client = useClient()
   const [state, setState] = useState(initialState)
 
@@ -25,25 +23,27 @@ export const AuthProvider = ({ children }) => {
     setState({ session, user: session?.user ?? null })
   })
 
-  return (
-    <AuthContext.Provider value={state}>
-      {children}
-    </AuthContext.Provider>
-  )
+  return <AuthContext.Provider value={state}>{children}</AuthContext.Provider>
 }
+```
+
+And auth hook:
+
+```js
+import { AuthContext } from 'path/to/auth/context'
 
-export const useAuth = () => {
+export function useAuth() {
   const context = useContext(AuthContext)
   if (context === undefined) {
     throw Error('useAuth must be used within AuthProvider')
   return context
 }
 ```
 
-Wrap your app in `AuthProvider` and use the `useAuth` hook in your components:
+Then, wrap your app in `AuthProvider` and use the `useAuth` hook in your components:
 
 ```js highlight=4
-import { useAuth } from 'path/to/auth'
+import { useAuth } from 'path/to/auth/hook'
 
 function Page() {
   const { session, user } = useAuth()

src/hooks/realtime/index.ts

@@ -1 +1,2 @@
 export * from './use-subscription'
+export * from './use-realtime'

src/hooks/realtime/use-realtime.ts

@@ -0,0 +1,103 @@
+import { useEffect, useReducer } from 'react'
+import { SupabaseRealtimePayload } from '@supabase/supabase-js'
+
+import { UseSelectState, useSelect } from '../data'
+import { useSubscription } from './use-subscription'
+
+export type UseRealtimeState<Data = any> = Omit<
+    UseSelectState<Data>,
+    'count'
+> & {
+    old?: Data[] | null
+}
+
+export type UseRealtimeResponse<Data = any> = [
+    UseRealtimeState<Data>,
+    () => Promise<Pick<UseSelectState<Data>, 'count' | 'data' | 'error'>>,
+]
+
+export type UseRealtimeAction<Data = any> =
+    | { type: 'FETCH'; payload: UseSelectState<Data> }
+    | { type: 'SUBSCRIPTION'; payload: SupabaseRealtimePayload<Data> }
+
+export type UseRealtimeCompareFn<Data = any> = (
+    data: Data,
+    payload: Data,
+) => boolean
+
+export function useRealtime<Data = any>(
+    table: string,
+    compareFn: UseRealtimeCompareFn = (a, b) => a.id === b.id,
+): UseRealtimeResponse<Data> {
+    if (table === '*')
+        throw Error(
+            'Must specify table or row. Cannot listen for all database changes.',
+        )
+
+    const [result, reexecute] = useSelect<Data>(table)
+    const [state, dispatch] = useReducer<
+        React.Reducer<UseRealtimeState<Data>, UseRealtimeAction<Data>>
+    >(reducer(compareFn), result)
+
+    useSubscription((payload) => dispatch({ type: 'SUBSCRIPTION', payload }), {
+        table,
+    })
+
+    useEffect(() => {
+        dispatch({ type: 'FETCH', payload: result })
+    }, [result])
+
+    return [state, reexecute]
+}
+
+const reducer = <Data = any>(compareFn: UseRealtimeCompareFn) => (
+    state: UseRealtimeState<Data>,
+    action: UseRealtimeAction<Data>,
+): UseRealtimeState<Data> => {
+    const old = state.data
+    switch (action.type) {
+        case 'FETCH':
+            return { ...state, old, ...action.payload }
+        case 'SUBSCRIPTION':
+            switch (action.payload.eventType) {
+                case 'DELETE':
+                    return {
+                        ...state,
+                        data: state.data?.filter(
+                            (x) => !compareFn(x, action.payload.old),
+                        ),
+                        fetching: false,
+                        old,
+                    }
+                case 'INSERT':
+                    return {
+                        ...state,
+                        data: [...(old ?? []), action.payload.new],
+                        fetching: false,
+                        old,
+                    }
+                case 'UPDATE': {
+                    const data = old ?? []
+                    const index = data.findIndex((x) =>
+                        compareFn(x, action.payload.new),
+                    )
+                    return {
+                        ...state,
+                        data: [
+                            ...data.slice(0, index),
+                            action.payload.new,
+                            ...data.slice(index + 1),
+                        ],
+                        fetching: false,
+                        old,
+                    }
+                }
+                default:
+                    throw Error(
+                        `eventType "${action.payload.eventType}" does not exist.`,
+                    )
+            }
+        default:
+            throw Error('Action type does not exist.')
+    }
+}

src/hooks/use-client.ts

@@ -3,7 +3,7 @@ import { useContext } from 'react'
 
 import { Context } from '../context'
 
-export const useClient = (): SupabaseClient => {
+export function useClient(): SupabaseClient {
     const client = useContext(Context)
     if (client === undefined)
         throw Error('No client has been specified using Provider.')