react-fate 0.0.7 → 0.1.0

package/README.md

@@ -18,7 +18,7 @@
 - **Async React:** fate uses modern Async React features like Actions, Suspense, and `use` to support concurrent rendering and enable a seamless user experience.
 - **Lists & Pagination:** fate provides built-in support for connection-style lists with cursor-based pagination, making it easy to implement infinite scrolling and "load-more" functionality.
 - **Optimistic Updates:** fate supports declarative optimistic updates for mutations, allowing the UI to update immediately while the server request is in-flight. If the request fails, the cache and its associated views are rolled back to their previous state.
-- **AI-Ready:** fate's minimal, predictable API and explicit data selection enable local reasoning, allowing AI tools to generate stable, type-safe data-fetching code.
+- **AI-Ready:** fate's minimal, predictable API and explicit data selection enable local reasoning, enabling humans and AI tools to generate stable, type-safe data-fetching code.
 
 ### A modern data client for React & tRPC
 
@@ -26,39 +26,60 @@
 
 GraphQL and Relay introduced several novel ideas: fragments co‑located with components, [a normalized cache](https://relay.dev/docs/principles-and-architecture/thinking-in-graphql/#caching-a-graph) keyed by global identifiers, and a compiler that hoists fragments into a single network request. These innovations made it possible to build large applications where data requirements are modular and self‑contained.
 
-Nakazawa Tech builds apps primarily with GraphQL and Relay. We advocate for these technologies in [talks](https://www.youtube.com/watch?v=rxPTEko8J7c&t=36s) and provide templates ([server](https://github.com/nkzw-tech/server-template), [client](https://github.com/nkzw-tech/web-app-template/tree/with-relay)) to help developers get started quickly.
+[Nakazawa Tech](https://nakazawa.tech) builds apps and [games](https://athenacrisis.com) primarily with GraphQL and Relay. We advocate for these technologies in [talks](https://www.youtube.com/watch?v=rxPTEko8J7c&t=36s) and provide templates ([server](https://github.com/nkzw-tech/server-template), [client](https://github.com/nkzw-tech/web-app-template/tree/with-relay)) to help developers get started quickly.
 
 However, GraphQL comes with its own type system and query language. If you are already using tRPC or another type‑safe RPC framework, it's a significant investment to adopt and implement GraphQL on the backend. This investment often prevents teams from adopting Relay on the frontend.
 
 Many React data frameworks lack Relay's ergonomics, especially fragment composition, co-located data requirements, predictable caching, and deep integration with modern React features. Optimistic updates usually require manually managing keys and imperative data updates, which is error-prone and tedious.
 
-fate takes the great ideas from Relay and puts them on top of tRPC. You get the best of both worlds: type safety between the client and server, and GraphQL-like ergonomics for data fetching.
+_fate_ takes the great ideas from Relay and puts them on top of tRPC. You get the best of both worlds: type safety between the client and server, and GraphQL-like ergonomics for data fetching. Using _fate_ usually looks like this:
 
-_[Learn more](/docs/guide/getting-started.md) about fate's core concepts and features._
+```tsx
+export const PostView = view<Post>()({
+  author: UserView,
+  content: true,
+  id: true,
+  title: true,
+});
+
+export const PostCard = ({ post: postRef }: { post: ViewRef<'Post'> }) => {
+  const post = useView(PostView, postRef);
+
+  return (
+    <Card>
+      <h2>{post.title}</h2>
+      <p>{post.content}</p>
+      <UserCard user={post.author} />
+    </Card>
+  );
+};
+```
+
+_[Learn more](/docs/guide/getting-started.md) about fate's core concepts or get started with [a ready-made template](https://github.com/nkzw-tech/fate-template#readme)._
 
 ## Getting Started
 
 ### Template
 
-Get started with [a ready-made template](https://github.com/nkzw-tech/fate-template) quickly:
+Get started with [a ready-made template](https://github.com/nkzw-tech/fate-template#readme) quickly:
 
 ::: code-group
 
-```npm
+```bash [npm]
 npx giget@latest gh:nkzw-tech/fate-template
 ```
 
-```pnpm
+```bash [pnpm]
 pnpx giget@latest gh:nkzw-tech/fate-template
 ```
 
-```yarn
+```bash [yarn]
 yarn dlx giget@latest gh:nkzw-tech/fate-template
 ```
 
 :::
 
-The `fate-template` comes with a simple tRPC backend and a React frontend using **_fate_**. It features modern tools to deliver an incredibly fast development experience. Follow its [README.md](https://github.com/nkzw-tech/fate-template#fate-quick-start-template) to get started.
+`fate-template` comes with a simple tRPC backend and a React frontend using **_fate_**. It features modern tools to deliver an incredibly fast development experience. Follow its [README.md](https://github.com/nkzw-tech/fate-template#fate-quick-start-template) to get started.
 
 ### Manual Installation
 
@@ -66,15 +87,15 @@ The `fate-template` comes with a simple tRPC backend and a React frontend using
 
 ::: code-group
 
-```npm
+```bash [npm]
 npm add react-fate
 ```
 
-```pnpm
+```bash [pnpm]
 pnpm add react-fate
 ```
 
-```yarn
+```bash [yarn]
 yarn add react-fate
 ```
 
@@ -84,15 +105,15 @@ And for your server, install the core `@nkzw/fate` package:
 
 ::: code-group
 
-```npm
+```bash [npm]
 npm add @nkzw/fate
 ```
 
-```pnpm
+```bash [pnpm]
 pnpm add @nkzw/fate
 ```
 
-```yarn
+```bash [yarn]
 yarn add @nkzw/fate
 ```
 
@@ -126,6 +147,9 @@ Traditionally, React apps are built with components and hooks. fate introduces a
 
 With fate, you no longer worry about _when_ to fetch data, how to coordinate loading states, or how to handle errors imperatively. You avoid overfetching, stop passing unnecessary data down the tree, and eliminate boilerplate types created solely for passing server data to child components.
 
+> [!NOTE]
+> Views in _fate_ are what fragments are in GraphQL.
+
 ## Views
 
 ### Defining Views
@@ -178,34 +202,20 @@ Components using `useView` listen to changes for all selected fields. When data
 
 ### Fetching Data with `useRequest`
 
-Now that we defined our view and component, we fetch the data from the server using the `useRequest` hook from fate. This hook allows us to declare what data we need for a specific screen or component tree. At the root of our `HomePage` component, we can request a list of posts like this:
+Now that we defined our view and component, we fetch the data from the server using the `useRequest` hook from fate. This hook allows us to declare what data we need for a specific screen or component tree. At the root of our app, we can request a list of posts like this:
 
 ```tsx
 import { useRequest } from 'react-fate';
 import { PostCard, PostView } from './PostCard.tsx';
 
-export function HomePage() {
-  const { posts } = useRequest({
-    posts: { root: PostView, type: 'Post' },
-  } as const);
+export function App() {
+  const { posts } = useRequest({ posts: { list: PostView } });
 
   return posts.map((post) => <PostCard key={post.id} post={post} />);
 }
 ```
 
-This component suspends or throws errors, which bubble up to the nearest error boundary. Wrap your component tree with `ErrorBoundary` and `Suspense` components to show error and loading states:
-
-```tsx
-<ErrorBoundary FallbackComponent={ErrorComponent}>
-  <Suspense fallback={<div>Loading…</div>}>
-    <HomePage />
-  </Suspense>
-</ErrorBoundary>
-```
-
-> [!NOTE]
->
-> `useRequest` might issue multiple requests which are automatically batched together by tRPC's [HTTP Batch Link](https://trpc.io/docs/client/links/httpBatchLink).
+_Learn more about `useRequest` in the [Requests Guide](/docs/guide/requests.md)._
 
 ### Composing Views
 
@@ -213,7 +223,7 @@ In the above example we are defining a single view for a `Post`. One of fate's c
 
 ```tsx
 import { Suspense } from 'react';
-import { useRequest, useView, ViewRef } from 'react-fate';
+import { useView, ViewRef } from 'react-fate';
 
 export const PostView = view<Post>()({
   author: {
@@ -419,23 +429,62 @@ const PostDetail = ({ post: postRef }: { post: ViewRef<'Post'> }) => {
 
 ViewRefs carry a set of view names they can resolve. `useView` throws if a ref does not include the required view.
 
-### Request Modes
+## Requests
 
-`useRequest` supports different request modes to control caching and data freshness. The available modes are:
+### Requesting Lists
 
-- `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.
+The `useRequest` hook can be used to declare our data needs for a specific screen or component tree. At the root of our app, we can request a list of posts like this:
 
-You can pass the request mode as an option to `useRequest`:
+```tsx
+import { useRequest } from 'react-fate';
+import { PostCard, PostView } from './PostCard.tsx';
+
+export function App() {
+  const { posts } = useRequest({ posts: { list: PostView } });
+  return posts.map((post) => <PostCard key={post.id} post={post} />);
+}
+```
+
+This component suspends or throws errors, which bubble up to the nearest error boundary. Wrap your component tree with `ErrorBoundary` and `Suspense` components to show error and loading states:
 
 ```tsx
-const { posts } = useRequest(
-  {
-    posts: { root: PostView, type: 'Post' },
-  },
-  { mode: 'stale-while-revalidate' },
-);
+<ErrorBoundary FallbackComponent={ErrorComponent}>
+  <Suspense fallback={<div>Loading…</div>}>
+    <App />
+  </Suspense>
+</ErrorBoundary>
+```
+
+> [!NOTE]
+>
+> `useRequest` might issue multiple requests which are automatically batched together by tRPC's [HTTP Batch Link](https://trpc.io/docs/client/links/httpBatchLink) into a single network request.
+
+### 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:
+
+```tsx
+const { post } = useRequest({
+  post: { id: '12', view: PostView },
+});
+```
+
+If you want to fetch multiple objects by their IDs, you can use the `ids` field:
+
+```tsx
+const { posts } = useRequest({
+  posts: { ids: ['6', '7'], view: PostView },
+});
+```
+
+### Other Types of Requests
+
+For any other queries, pass only the `type` and `view`:
+
+```tsx
+const { viewer } = useRequest({
+  viewer: { view: UserView },
+});
 ```
 
 ### Request Arguments
@@ -446,12 +495,32 @@ You can pass arguments to `useRequest` calls. This is useful for pagination, fil
 const { posts } = useRequest({
   posts: {
     args: { first: 10 },
-    root: PostView,
-    type: 'Post',
+    list: PostView,
   },
 });
 ```
 
+### 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`:
+
+```tsx
+const { posts } = useRequest(
+  {
+    posts: { list: PostView },
+  },
+  {
+    mode: 'stale-while-revalidate',
+  },
+);
+```
+
 ## List Views
 
 ### Pagination with `useListView`
@@ -473,7 +542,7 @@ const CommentConnectionView = {
   items: {
     node: CommentView,
   },
-} as const;
+};
 
 const PostView = view<Post>()({
   comments: CommentConnectionView,
@@ -525,6 +594,9 @@ Mutations in your tRPC backend are made available as actions and mutations by fa
 Let's assume that our `Post` entity has a tRPC mutation for liking a post called `post.like`. A `LikeButton` component using fate Actions and an async component library could then look like this:
 
 ```tsx
+import { useActionState } from 'react';
+import { useFateClient } from 'react-fate';
+
 const LikeButton = ({ post }: { post: { id: string; likes: number } }) => {
   const fate = useFateClient();
   const [result, like] = useActionState(fate.actions.post.like, null);
@@ -663,16 +735,17 @@ export const postRouter = router({
         view: postDataView,
       });
 
-      const updated = await ctx.prisma.post.update({
-        data: {
-          likes: {
-            increment: 1,
+      return resolve(
+        await ctx.prisma.post.update({
+          data: {
+            likes: {
+              increment: 1,
+            },
           },
-        },
-        select,
-        where: { id: input.id },
-      });
-      return resolve(updated as unknown as PostItem);
+          select,
+          where: { id: input.id },
+        } as PostUpdateArgs),
+      );
     }),
 });
 ```
@@ -741,6 +814,26 @@ useEffect(() => {
 }, [like, result]);
 ```
 
+### Controlling List Insertion Behavior
+
+When inserting new objects into lists, the default behavior is to append the new object to the list. You can provide an `insert` option with `before`, `after` or `none` values to customize this behavior and specify where the new object should be inserted in the list:
+
+```tsx
+addComment({
+  input: { content: 'New Comment text', postId: post.id },
+  insert: 'before', // Insert the new comment at the beginning of the list.
+});
+```
+
+Or, use the `none` option if you want to ignore inserting the new object into any lists:
+
+```tsx
+addComment({
+  input: { content: 'New Comment text', postId: post.id },
+  insert: 'none', // Do not insert the new comment into any lists.
+});
+```
+
 ## Server Integration
 
 Until now, we have focused on the client-side API of fate. You'll need a tRPC backend that follows some conventions so you can generate a typed client using fate's CLI. At the moment _fate_ is designed to work with tRPC and Prisma, but the framework is not coupled to any particular ORM or database, it's just what we are starting with.
@@ -787,35 +880,27 @@ _Note: Currently, fate provides helpers to integrate with Prisma, but the framew
 We can apply the above data view in our tRPC router and resolve the client's selection against it using `createResolver`. Here is an example implementation of the `byId` query for the `User` type which allows fetching multiple users by `id`:
 
 ```tsx
-import { connectionArgs, createResolver } from '@nkzw/fate/server';
+import { byIdInput, createResolver } from '@nkzw/fate/server';
 import { z } from 'zod';
 import type { UserFindManyArgs } from '../../prisma/prisma-client/models.ts';
 import { procedure, router } from '../init.ts';
 import { userDataView } from '../views.ts';
 
 export const userRouter = router({
-  byId: procedure
-    .input(
-      z.object({
-        args: connectionArgs,
-        ids: z.array(z.string().min(1)).nonempty(),
-        select: z.array(z.string()),
-      }),
-    )
-    .query(async ({ ctx, input }) => {
-      const { resolveMany, select } = createResolver({
-        ...input,
-        ctx,
-        view: userDataView,
-      });
-
-      const users = await ctx.prisma.user.findMany({
-        select: select,
-        where: { id: { in: input.ids } },
-      } as UserFindManyArgs);
-
-      return await resolveMany(users);
-    }),
+  byId: procedure.input(byIdInput).query(async ({ ctx, input }) => {
+    const { resolveMany, select } = createResolver({
+      ...input,
+      ctx,
+      view: userDataView,
+    });
+
+    const users = await ctx.prisma.user.findMany({
+      select: select,
+      where: { id: { in: input.ids } },
+    } as UserFindManyArgs);
+
+    return await resolveMany(users);
+  }),
 });
 ```
 
@@ -875,7 +960,7 @@ export const postDataView = dataView<PostItem>('Post')({
   content: true,
   id: true,
   title: true,
-} as const;
+});
 ```
 
 ### Data View Lists
@@ -896,30 +981,39 @@ export const postDataView = dataView<PostItem>('Post')({
 });
 ```
 
-We can also define root-level lists by exporting a `Lists` object from our `views.ts` file:
+We can define extra root-level lists and queries by exporting a `Root` object from our `views.ts` file using the same view syntax as everywhere else:
 
 ```tsx
-export const Lists = {
-  posts: postDataView,
+export const Root = {
+  categories: list(categoryDataView),
+  commentSearch: { procedure: 'search', view: list(commentDataView) },
+  events: list(eventDataView),
+  posts: list(postDataView),
+  viewer: userDataView,
 };
 ```
 
-This makes it possible to fetch a list of posts from the client using `useRequest`.
-
-#### Custom Root Lists
+Entries that wrap their view in `list(...)` are treated as list resolvers and use the `procedure` name when calling the corresponding router procedure, defaulting to `list`. If you omit `list(...)`, fate treats the entry as a standard query and uses the view type name to infer the router name.
 
-You might want to define custom root lists that don't directly map to a single data view. For example, a search endpoint that returns a list of posts based on a search query:
+For the above `Root` definitions, you can make the following requests using `useRequest`:
 
 ```tsx
-export const Lists = {
-  // …
-  postSearch: { procedure: 'search', view: postDataView },
-  // …
-};
+const query = 'Apple';
+
+const { posts, categories, viewer } = useRequest({
+  // Explicit Root queries:
+  categories: { list: categoryView },
+  commentSearch: { args: { query }, list: commentView },
+  events: { list: eventView },
+  posts: { list: postView },
+  viewer: { view: userView },
+
+  // Queries by id, if those entities have a `byId` query defined:
+  post: { id: '12', view: postView },
+  comment: { ids: ['6', '7'], view: commentView },
+});
 ```
 
-This maps the `postSearch` list to a `search` procedure on your post router.
-
 ### Data View Resolvers
 
 fate data views support resolvers for computed fields. If we want to add a `commentCount` field to our `Post` data view, we can use the `resolver` helper that defines a Prisma selection for the database query together with a `resolve` function:
@@ -927,19 +1021,33 @@ fate data views support resolvers for computed fields. If we want to add a `comm
 ```tsx
 export const postDataView = dataView<PostItem>('Post')({
   author: userDataView,
-  commentCount: resolver<PostItem>({
-    resolve: ({ item }) => item._count?.comments ?? 0,
+  commentCount: resolver<PostItem, number>({
+    resolve: ({ _count }) => _count?.comments ?? 0,
     select: () => ({
       _count: { select: { comments: true } },
     }),
   }),
   comments: list(commentDataView),
   id: true,
-} as const;
+});
 ```
 
 This definition makes the `commentCount` field available to your client-side views.
 
+### Authorization in Resolvers
+
+You might want to restrict access to certain fields based on the current user or other contextual information. You can do this by adding an `authorize` function to your resolver definition:
+
+```tsx
+export const userDataView = dataView<UserItem>('User')({
+  email: resolver<UserItem, string | null, { sessionUser: string }>({
+    authorize: ({ id }, context) => context?.sessionUserId === id,
+    resolve: ({ email }) => email,
+  }),
+  id: true,
+});
+```
+
 ### Generating a typed client
 
 Now that we have defined our client views and our tRPC server, we need to connect them with some glue code. We recommend using fate's CLI for convenience.
@@ -971,34 +1079,30 @@ _Note: fate uses the specified server module name to extract the server types it
 
 ### Creating a _fate_ Client
 
-Now that we have generated the client types, all that remains is creating the instance of the fate client, and using it in our React app using the `FateClient` context provider.
-
-Create a `fate.ts` file:
-
-```tsx
-import { createFateClient } from './lib/fate.generated';
-
-export const fate = createFateClient({
-  links: [
-    httpBatchLink({
-      fetch: (input, init) =>
-        fetch(input, {
-          ...init,
-          credentials: 'include',
-        }),
-      url: `${env('SERVER_URL')}/trpc`,
-    }),
-  ],
-});
-```
-
-Now wrap your app with the `FateClient` provider:
+Now that we have generated the client types, all that remains is creating an instance of the fate client, and using it in our React app using the `FateClient` context provider:
 
 ```tsx
+import { httpBatchLink } from '@trpc/client';
 import { FateClient } from 'react-fate';
-import { fate } from './fate.ts';
+import { createFateClient } from './fate.ts';
 
 export function App() {
+  const fate = useMemo(
+    () =>
+      createFateClient({
+        links: [
+          httpBatchLink({
+            fetch: (input, init) =>
+              fetch(input, {
+                ...init,
+                credentials: 'include',
+              }),
+            url: `${env('SERVER_URL')}/trpc`,
+          }),
+        ],
+      }),
+    [],
+  );
   return <FateClient client={fate}>{/* Components go here */}</FateClient>;
 }
 ```
@@ -1026,18 +1130,20 @@ Probably. One day. _Maybe._
 ### How was fate built?
 
 > [!NOTE]
-> 80% of _fate_'s code was written by OpenAI's Codex – four versions per task, carefully curated by a human. The remaining 20% was written by [@cnakazawa](https://x.com/cnakazawa). You get to decide which parts are the good ones. The docs were 100% written by a human.
+> 80% of _fate_'s code was written by OpenAI's Codex – four versions per task, carefully curated by a human. The remaining 20% was written by [@cnakazawa](https://x.com/cnakazawa). _You get to decide which parts are the good ones!_ The docs were 100% written by a human.
+>
+> If you contribute to _fate_, we [require you to disclose your use of AI tools](https://github.com/nkzw-tech/fate/blob/main/CONTRIBUTING.md#ai-assistance-notice).
 
 ## Future
 
-**_fate_** is not complete yet. It lacks core features such as garbage collection, a compiler to extract view definitions statically and ahead of time, and there is too much backend boilerplate. The current implementation of _fate_ is not tied to tRPC or Prisma, those are just the ones we are starting with. We welcome contributions and ideas to improve fate. Here are some features we'd like to add:
+**_fate_** is not complete yet. The library lacks core features such as garbage collection, a compiler to extract view definitions statically ahead of time, and there is too much backend boilerplate. The current implementation of _fate_ is not tied to tRPC or Prisma, those are just the ones we are starting with. We welcome contributions and ideas to improve fate. Here are some features we'd like to add:
 
 - Support for Drizzle
 - Support backends other than tRPC
+- Persistent storage for offline support
+- Implement garbage collection for the cache
 - Better code generation and less type repetition
 - Support for live views and real-time updates via `useLiveView` and SSE
-- Implement garbage collection for the cache
-- Add persistent storage for offline support
 
 ## Acknowledgements
 
@@ -1045,4 +1151,4 @@ Probably. One day. _Maybe._
 - [Ricky Hanlon](https://x.com/rickyfm) for guidance on Async React
 - [Anthony Powell](https://x.com/Cephalization) for testing fate and providing feedback
 
-**_fate_** was created by [@cnakazawa](https://x.com/cnakazawa) and is maintained by [Nakazawa Tech](https://nakazawa.tech/).
+**_fate_** was created by [@cnakazawa](https://x.com/cnakazawa) and is maintained by [Nakazawa Tech](https://nakazawa.tech/).

package/lib/index.d.mts

@@ -1,7 +1,18 @@
-import { ConnectionRef, FateClient as FateClient$1, FateMutations, Pagination, Request, RequestOptions, RequestResult, View, ViewData, ViewEntity, ViewEntityName, ViewRef, ViewRef as ViewRef$1, ViewSelection, createClient, createTRPCTransport, mutation, view } from "@nkzw/fate";
+import { ConnectionRef, FateClient as FateClient$1, FateMutations, FateRoots, Pagination, Request, RequestOptions, RequestResult, View, ViewData, ViewEntity, ViewEntityName, ViewRef, ViewRef as ViewRef$1, ViewSelection, clientRoot, createClient, createTRPCTransport, mutation, toEntityId, view } from "@nkzw/fate";
 import { ReactNode } from "react";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 
+//#region src/useRequest.d.ts
+type Roots = keyof ClientRoots extends never ? FateRoots : ClientRoots;
+/**
+ * Declares the data a screen needs and kicks off fetching, suspending while the
+ * request resolves.
+ *
+ * @example
+ * const { posts } = useRequest({ posts: { list: PostView } });
+ */
+declare function useRequest<R extends Request, O extends FateRoots = Roots>(request: R, options?: RequestOptions): RequestResult<O, R>;
+//#endregion
 //#region src/context.d.ts
 type Mutations = keyof ClientMutations extends never ? FateMutations : ClientMutations;
 /**
@@ -12,12 +23,12 @@ declare function FateClient({
   client
 }: {
   children: ReactNode;
-  client: FateClient$1<any>;
+  client: FateClient$1<any, any>;
 }): react_jsx_runtime0.JSX.Element;
 /**
  * Returns the nearest `FateClient` from context.
  */
-declare function useFateClient<M extends Mutations>(): FateClient$1<M>;
+declare function useFateClient<T extends [Roots, Mutations]>(): FateClient$1<T[0], T[1]>;
 //#endregion
 //#region src/useView.d.ts
 type ViewEntityWithTypename<V extends View<any, any>> = ViewEntity<V> & {
@@ -29,17 +40,7 @@ type ViewEntityWithTypename<V extends View<any, any>> = ViewEntity<V> & {
  * @example
  * const post = useView(PostView, postRef);
  */
-declare function useView<V extends View<any, any>>(view: V, ref: ViewRef$1<ViewEntityName<V>>): ViewData<ViewEntityWithTypename<V>, ViewSelection<V>>;
-//#endregion
-//#region src/useRequest.d.ts
-/**
- * Declares the data a screen needs and kicks off fetching, suspending while the
- * request resolves.
- *
- * @example
- * const { posts } = useRequest({ posts: { root: PostView, type: 'Post' } as const });
- */
-declare function useRequest<R extends Request>(request: R, options?: RequestOptions): RequestResult<R>;
+declare function useView<V extends View<any, any>, R extends ViewRef$1<ViewEntityName<V>> | null>(view: V, ref: R): R extends null ? null : ViewData<ViewEntityWithTypename<V>, ViewSelection<V>>;
 //#endregion
 //#region src/useListView.d.ts
 type ConnectionItems<C> = C extends {
@@ -62,5 +63,6 @@ declare function useListView<C extends {
 //#endregion
 //#region src/index.d.ts
 interface ClientMutations {}
+interface ClientRoots {}
 //#endregion
-export { ClientMutations, type ConnectionRef, FateClient, type ViewRef, createClient, createTRPCTransport, mutation, useFateClient, useListView, useRequest, useView, view };
+export { ClientMutations, ClientRoots, type ConnectionRef, FateClient, type ViewRef, clientRoot, createClient, createTRPCTransport, mutation, toEntityId, useFateClient, useListView, useRequest, useView, view };

package/lib/index.mjs

@@ -1,4 +1,4 @@
-import { ConnectionTag, createClient, createTRPCTransport, isViewTag, mutation, view } from "@nkzw/fate";
+import { ConnectionTag, clientRoot, createClient, createTRPCTransport, isViewTag, mutation, toEntityId, view } from "@nkzw/fate";
 import { createContext, use, useCallback, useDeferredValue, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
 import { jsx } from "react/jsx-runtime";
 
@@ -24,25 +24,34 @@ function useFateClient() {
 
 //#endregion
 //#region src/useView.tsx
-/**
-* Resolves a reference against a view and subscribes to updates for that selection.
-*
-* @example
-* const post = useView(PostView, postRef);
-*/
+const nullSnapshot = {
+	status: "fulfilled",
+	then(onfulfilled, onrejected) {
+		return Promise.resolve(null).then(onfulfilled, onrejected);
+	},
+	value: null
+};
 function useView(view$1, ref) {
 	const client = useFateClient();
 	const snapshotRef = useRef(null);
 	const getSnapshot = useCallback(() => {
-		const snapshot = client.readView(view$1, ref);
-		snapshotRef.current = snapshot.status === "fulfilled" ? snapshot.value : null;
-		return snapshot;
+		if (ref === null) {
+			snapshotRef.current = null;
+			return nullSnapshot;
+		}
+		const snapshot$1 = client.readView(view$1, ref);
+		snapshotRef.current = snapshot$1.status === "fulfilled" ? snapshot$1.value : null;
+		return snapshot$1;
 	}, [
 		client,
 		view$1,
 		ref
 	]);
-	return use(useDeferredValue(useSyncExternalStore(useCallback((onStoreChange) => {
+	const snapshot = use(useDeferredValue(useSyncExternalStore(useCallback((onStoreChange) => {
+		if (ref === null) {
+			snapshotRef.current = null;
+			return () => {};
+		}
 		const subscriptions = /* @__PURE__ */ new Map();
 		const onChange = () => {
 			updateSubscriptions();
@@ -68,7 +77,8 @@ function useView(view$1, ref) {
 			for (const unsubscribe of subscriptions.values()) unsubscribe();
 			subscriptions.clear();
 		};
-	}, [client.store]), getSnapshot, getSnapshot))).data;
+	}, [client.store, ref]), getSnapshot, getSnapshot)));
+	return snapshot ? snapshot.data : null;
 }
 
 //#endregion
@@ -78,7 +88,7 @@ function useView(view$1, ref) {
 * request resolves.
 *
 * @example
-* const { posts } = useRequest({ posts: { root: PostView, type: 'Post' } as const });
+* const { posts } = useRequest({ posts: { list: PostView } });
 */
 function useRequest(request, options) {
 	const client = useFateClient();
@@ -173,4 +183,4 @@ function useListView(selection, connection) {
 }
 
 //#endregion
-export { FateClient, createClient, createTRPCTransport, mutation, useFateClient, useListView, useRequest, useView, view };
+export { FateClient, clientRoot, createClient, createTRPCTransport, mutation, toEntityId, useFateClient, useListView, useRequest, useView, view };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-fate",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "description": "fate is a modern data client for React.",
   "homepage": "https://github.com/nkzw-tech/fate",
   "repository": {
@@ -28,7 +28,7 @@
     "lib"
   ],
   "dependencies": {
-    "@nkzw/fate": "^0.0.7"
+    "@nkzw/fate": "^0.1.0"
   },
   "devDependencies": {
     "@types/react": "^19.2.7",