Using Queries

import { useQuery } from '@cerberus/signals'

Usage

useQuery allows you use a query factory (via createQuery) within the scope of a React component.

The return of useQuery is a read-only value which is the result of the query fetcher.

Query's have built in support for Suspense and Error Boundaries with no extra effort.

Using Queries

To use query factories within React components, simply pass in the defined query to the hook and bind the value in your JSX.

Loading example...

Initial Data

If you would like to bypass the initial fetch with pre-loaded data that matches the return of the query factory being used (e.g., parent server component fetch) - add and options Object as the last argument with the property initialData.

Loading example...

With Suspense

To utilize the native React Suspense API with your query, wrap the parent of the component using the query in Suspense as per requirements of the React API.

To learn more about Suspense, read the React docs.

With Error Boundaries

If a query errors out, createQuery will throw an error that will natively trigger an Error Boundary if you have one established.

To learn more about Error Boundaries, see the Error Boundary library on NPM.

API

useQuery accepts the following options:

Params	Required	Description
`Accessor<QueryState<T>>`	Yes	The query to utilize.
`QueryOptions<T>`	No	Additional options to use for the query factory.

Return

useQuery returns the value of the Promise defined in createQuery.

Query Options

The QueryOption Object contains the following properties:

Params	Required	Description
`initialData`	No	When provided will bypass the initial query fetch and instead return the value of `initialData`.

Initial Data

'use client'

import { useQuery } from '@cerberus/react/signals'
import { queryUser } from './queries'
import { type User } from './db'

interface Props {
  id: string
  initialData: User
}

export function UserProfile(props: Props) {
  // 1. Cerberus sees `initialData`, instantly seeds the $O(1) Map,
  // and mounts the component with zero loading spinners or network waterfalls.
  const user = useQuery(queryUser(props.id), { initialData: props.initialData })

  if (!user) return null

  return <h1>{user.name}</h1>
}

Loading example...

API

useQuery accepts the following options:

Params	Required	Description
`Accessor<QueryState<T>>`	Yes	The query to utilize.
`QueryOptions<T>`	No	Additional options to use for the query factory.

Return

useQuery returns the value of the Promise defined in createQuery.

Query Options

The QueryOption Object contains the following properties:

Params	Required	Description
`initialData`	No	When provided will bypass the initial query fetch and instead return the value of `initialData`.