React Hooks

The @requence/socketql/client/react module provides the SocketQLProvider and Suspense-ready hooks built on top of URQL.

Setup

Wrap your app with SocketQLProvider to connect and provide the client to all hooks:

import { createClient } from '@requence/socketql/client'
import { SocketQLProvider } from '@requence/socketql/client/react'

const client = createClient({
  auth: () => ({ token: getAccessToken() }),
})

function App() {
  return (
    <ErrorBoundary fallback={<LoginPage />}>
      <SocketQLProvider client={client}>
        <Main />
      </SocketQLProvider>
    </ErrorBoundary>
  )
}

useQuery

A thin wrapper around URQL’s useQuery that throws on errors (for error boundaries) and returns a [data, reexecute] tuple:

import { useQuery } from '@requence/socketql/client/react'

function UserList() {
  const [data, reexecute] = useQuery({
    query: UsersDocument,
  })

  return (
    <>
      <button onClick={() => reexecute({ requestPolicy: 'network-only' })}>
        Refresh
      </button>
      <ul>
        {data.users.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </>
  )
}

useMutation

A wrapper around URQL’s useMutation with built-in Suspense support and cache invalidation:

import { useMutation } from '@requence/socketql/client/react'

function CreateUser() {
  const [result, execute] = useMutation({
    query: CreateUserDocument,
    invalidate: 'Users',     // invalidate cached "Users" query
    waitOn: 'Users',         // wait for the Users query to re-resolve
  })

  return (
    <button onClick={() => execute({ name: 'Alice' })}>
      Create User
    </button>
  )
}

Options

Option	Type	Description
query	DocumentInput	The mutation document
invalidate	string | DocumentNode | Array	Queries to invalidate after mutation
suspense	boolean	Whether to trigger Suspense (default: true)
waitOn	string | DocumentNode | Array	Wait for these queries to re-resolve before un-suspending
waitOnTimeout	number	Timeout in milliseconds to resolve the wait lock early

useSubscription

A thin wrapper around URQL’s useSubscription that throws on errors (for error boundaries) and returns a [data, execute] tuple:

import { useSubscription } from '@requence/socketql/client/react'

function ChatMessages() {
  const [message] = useSubscription({
    query: OnNewMessageDocument,
    variables: { channelId: 'general' },
  })

  if (!message) return <p>Waiting for messages…</p>

  return <p>Latest: {message.text}</p>
}

Accumulating Events

Pass a handler function to accumulate data across subscription events — useful for building lists from a stream:

function MessageList() {
  const [messages] = useSubscription(
    { query: OnNewMessageDocument },
    (prev = [], event) => [...prev, event],
  )

  return (
    <ul>
      {messages?.map(msg => (
        <li key={msg.id}>{msg.text}</li>
      ))}
    </ul>
  )
}