Querying

useList

Fetch and cache a paginated collection list.

import { useList } from "@bunbase/react-sdk";

function PostList() {
  const { data, loading, isRefetching, error, refetch } = useList<Post>("posts", {
    filter: { status: "published" },
    sort: "-_created_at",
    limit: 20,
    search: "hello world",   // full-text search (FTS5)
  });

  if (loading) return <p>Loading…</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <>
      {isRefetching && <p>Updating…</p>}
      {data?.items.map((post) => <PostCard key={post._id} post={post} />)}
      <button onClick={refetch}>Refresh</button>
    </>
  );
}

Query params

The second argument to useList is a ListQuery object. All fields are optional:

Field	Description
filter	Record of { field: value } equality filters, or FieldFilter[] for advanced ops (eq, ne, gt, lt, gte, lte, like, in)
sort	Field name to sort by. Prefix with - for descending: "-_created_at". Array for multi-sort.
limit	Max records per page (default 50, max 500)
page	Page number (1-based)
after	Cursor: _id of last record — faster than page for large datasets
fields	Comma-separated field names to return
expand	Array of relation field names to inline
include_deleted	true to include soft-deleted records
search	Full-text search query using SQLite FTS5 — see below

Full-text search

Pass search to filter results by text across all user-defined fields:

const { data } = useList<Post>("posts", {
  search: "bun native",
  filter: { status: "published" },
  sort: "-_created_at",
});

FTS5 query syntax is supported:

• Prefix: bun* matches bun, buns, bundle, etc.
• Phrase: "bun native" — exact phrase
• Boolean: bun AND fast, bun OR deno, bun NOT slow

search composes with filter, sort, and limit — all applied together.

Hook options

Option	Default	Description
staleTime	30_000	ms before cached data is considered stale
refetchInterval	—	ms between automatic background re-fetches
enabled	true	Set false to skip fetching (e.g. wait for a dependency)
realtime	false	Subscribe to collection events and sync the cache automatically

Return value

Field	Type	Description
data	ListResult<T> | undefined	Cached result — may be stale while isRefetching is true
loading	boolean	True only on the very first fetch (no cached data yet)
isRefetching	boolean	True when a background refetch is running with stale data visible
error	Error | null	Last fetch error
refetch	() => void	Manually invalidate and re-fetch

Cache pre-population

After every successful fetch, useList writes each record into {collection}:get:{id}. This means navigating to a detail page with useRecord will load instantly from cache — no loading state, no extra round-trip.

---

useRecord

Fetch and cache a single record by ID.

import { useRecord } from "@bunbase/react-sdk";

function PostDetail({ id }: { id: string }) {
  const { data: post, loading, error } = useRecord<Post>("posts", id);

  if (loading) return <p>Loading…</p>;
  if (error) return <p>Not found</p>;

  return <article>{post?.title}</article>;
}

Pass null or undefined as id to skip fetching entirely — useful when the ID comes from a route param that may not be resolved yet:

const { data } = useRecord<Post>("posts", router.params.id ?? null);

Options

Option	Default	Description
staleTime	30_000	ms before cached data is considered stale
expand	—	Inline related records declared via the relations API

First paint from cache

When you navigate from a list page to a detail page:

1. useList("posts") fetched and cached
   └─ also wrote posts:get:abc123 via pre-population

2. navigate to /posts/abc123
   useRecord("posts", "abc123")
   └─ finds posts:get:abc123 in cache → loading: false, data shown immediately
   └─ background refetch runs to revalidate (if stale)
   └─ if server returns same data → shallow equal → no re-render
   └─ if server returns updated data → re-render with latest

Controlling stale time

// Always background-refetch on navigation
useRecord("posts", id, { staleTime: 0 });

// Cache aggressively for 5 minutes
useRecord("posts", id, { staleTime: 5 * 60_000 });

useRecord subscribes to record-level realtime updates automatically whenever id is provided. There is currently no separate realtime toggle on this hook.