nkzw-tech/fate: fate is a modern data client for React.

> [!NOTE]
>
> useRequest may issue multiple operations in the same render pass. fate transports can batch those operations into fewer network requests: the native HTTP transport batches same-microtask operations into one POST /fate request, and the tRPC adapter can use tRPC's HTTP Batch Link.

Requesting Objects by ID
If you want to fetch data for a single object instead of a list, you can specify the id and the associated view like this:

If you want to fetch multiple objects by their IDs, you can use the ids field:

### Other Types of Requests

For any other queries, pass only the type and view:

### Request Arguments

You can pass arguments to useRequest calls. This is useful for pagination, filtering, or sorting. For example, to fetch the first 10 posts, you can do the following:

Request arguments are part of the cache key. Two list requests for the same root with different filters or sorting arguments keep separate list state, and cursor arguments are merged into the same list when you load more pages. The selected view is part of the key as well: requesting PostCardView and PostDetailView can share normalized records, but fate still tracks whether the specific fields for each request are present.

Request Modes
useRequest supports different request modes to control caching and data freshness. The available modes are:

cache-first (_default_): Returns data from the cache if available, otherwise fetches from the network.

stale-while-revalidate: Returns data from the cache and simultaneously fetches fresh data from the network.

network-only: Always fetches data from the network, bypassing the cache.

You can pass the request mode as an option to useRequest:

### Cache Lifetime
fate stores records in a normalized cache keyed by __typename and id. Lists and root queries point at those records, and views read from the normalized cache. When a useRequest call is mounted, fate retains the request so the records and lists needed by that screen stay in memory. When the component unmounts, the request is released and fate schedules garbage collection.

Released requests are kept in a small release buffer before their data becomes collectible. This makes common route transitions cheap: navigating away from a screen and quickly coming back usually reuses the cached records instead of refetching them. The default release buffer stores the 10 most recently released requests.
You can tune the buffer when creating the client:

Set gcReleaseBufferSize to 0 in tests or very memory-sensitive environments when released screens should be collected immediately.

cache-first request handles are stable while their request is cached. If garbage collection later removes the data for a fulfilled request, the next cache-first request automatically fetches it again rather than returning stale references.

If you call fate.request(...) outside React and need the result to stay in memory across manual gc() calls, retain the same request for the lifetime of that work:

try { const { posts } = await fate.request(request); // Use posts while this request is retained. } finally { retained.dispose(); }

Garbage collection waits for active optimistic updates to settle before sweeping records. This keeps temporary optimistic records and their list positions stable while mutations are still pending.

SSR and Hydration
Create a request-scoped fate client on the server, preload the route data, and dehydrate its normalized cache:

return { fate: fate.dehydrate(), };

Transport the returned value through your framework's loader serialization, React Server Component props, or a safely escaped JSON bootstrap script. The snapshot contains plain serializable values, so serializers such as Seroval can carry it without fate-specific integration. Treat the snapshot as opaque: hydrate it through fate rather than reading or editing its internal data.

On the browser, hydrate the new client before rendering components that call useRequest:

hydrateRoot( document, , );

Hydrated cache-first requests resolve from the normalized cache without refetching. Hydration restores records, selected-field coverage, root queries, and list pagination state. It intentionally does not restore active requests, subscriptions, retainers, timers, or optimistic mutation state.

Snapshots carry a hydration scope and are rejected by clients with a different scope. Generated clients set a stable scope automatically. When constructing a client directly, pass hydrationScope and rotate it when deploying an incompatible cache schema or when separating cache namespaces:

Use hydrationLimits when an application needs stricter bootstrap payload limits. fate applies conservative defaults for total encoded values, collection sizes, and string lengths.

By default, hydration preserves values already present in the browser cache while adding missing server data. Pass { merge: 'replace' } only when the snapshot should authoritatively reset the durable cache:

preserve-existing recursively combines plain scalar objects while keeping browser values on conflicts. Arrays, dates, entity references, and list windows are atomic: an existing browser value wins as a whole. Replaying a snapshot is safe and does not notify subscribers when durable cache state is unchanged.

Do not reuse request-scoped snapshots across users. Dehydrate after awaited route preloading: snapshots are point-in-time values and do not stream cache patches for data that resolves later. Hydration and dehydration reject clients with in-flight requests, so hydrate the initial snapshot before rendering.
Deferred Views
Use defer when a field should not block the parent view. The parent view receives a deferred handle immediately after the eager fields are available, and the component that reads that handle with useView, useListView, or useLiveListView decides which Suspense boundary handles the loading state.

const CommentView = view()({ content: true, id: true, });

const CommentConnectionView = { args: { first: 3 }, items: { node: CommentView }, };

const PostView = view()({ comments: defer(CommentConnectionView), content: true, id: true, title: true, });

function PostCard({ post: postRef }: { post: ViewRef<'Post'> }) { const post = useView(PostView, postRef);

return (

function PostComments({ comments, }: { comments: Deferred<{ items: ReadonlyArray<{ node: ViewRef<'Comment'> }> }>; }) { const [items, loadNext] = useListView(CommentConnectionView, comments);

return (

Deferred fields are not optional data. They are explicit handles that existing view APIs can read. If the deferred selection is missing from the normalized cache, fate fetches only that missing selection and suspends the component that tried to resolve it.

This keeps parent components simple: eager fields like title and content are available when useView(PostView, postRef) returns, while slower or secondary fields such as comments can load under their own boundary.

GraphQL transports use the same client semantics today. The deferred field is omitted from the eager request and fetched when the deferred handle is resolved. GraphQL @defer is the natural transport representation for this feature, but consuming incremental multipart patches requires additional transport support before fate can safely normalize streamed patches from a single GraphQL response.

List Views
Pagination with useListView

You can wrap a list of references using useListView to enable connection-style lists with pagination support.

For example, you can define a CommentView and reuse it inside of a CommentConnectionView:

const CommentView = view()({ content: true, id: true, });

const CommentConnectionView = { args: { first: 10 }, items: { node: CommentView, }, };

const PostView = view()({ comments: CommentConnectionView, });

Now you can apply the useListView hook inside of your PostCard component to read the list of comments and load more comments when needed:

return (

If loadNext is undefined, it means there are no more comments to load. If you want to instead load previous comments, you can use the third argument returned by useListView, which is loadPrevious. Similarly, if there are no previous comments to load, loadPrevious will be undefined.

Pagination Arguments
Connection views can define default arguments, and useListView carries those arguments forward when loading more pages:

When loadNext runs, fate sends the next cursor as after and keeps the page size in first. When loadPrevious runs, fate sends the previous cursor as before and uses last for the page size. This lets the server distinguish forward and backward pagination while keeping the component API small.

Additional arguments on a root request are scoped to that root list:

The categoryId list above has its own cache entry and pagination state. Loading another page for that list does not update a different posts request with another category or search query.

Live Views
useLiveView resolves a ViewRef just like useView, but also keeps the selected object up to date through the native live SSE transport.

export const PostCard = ({ post: postRef }: { post: ViewRef<'Post'> }) => { const post = useLiveView(PostView, postRef);

return (

{post.title}

{post.likes} likes

The API mirrors useView: pass a view and a ref, and get back the same masked data shape. A null ref returns null and does not subscribe.

How Live Updates Work
The native HTTP transport opens one Server-Sent Events (SSE) connection per fate client. When components mount or unmount live views, the client sends subscribe and unsubscribe control messages to the server. The server keeps those selections on the connection and sends updates only for records that connection subscribed to.
When the server sends an update, fate normalizes the selected record into the same cache used by requests, actions, and mutations. Components that read affected fields re-render automatically.
For example, if PostView selects likes, a live update that changes likes re-renders the PostCard. If another component only selected title, it does not re-render for a likes change.

Live deletion events remove the record from the normalized cache in the same way as mutations, and any lists or object fields that reference it are pruned.
Client Setup
Configure the native transport and point the client at your fate endpoint: