@nkzw/fate 0.1.2 → 1.0.0-rc.0

package/README.md

@@ -8,7 +8,7 @@
   </picture>
 </p>
 
-**_fate_** is a modern data client for React and tRPC inspired by [Relay](https://relay.dev/) and [GraphQL](https://graphql.org/). It combines view composition, normalized caching, data masking, Async React features, and tRPC's type safety.
+**_fate_** is a modern data client for React inspired by [Relay](https://relay.dev/) and [GraphQL](https://graphql.org/). It combines view composition, normalized caching, data masking, Async React features, and type-safe data fetching.
 
 ### Features
 
@@ -18,9 +18,10 @@
 - **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.
+- **Live Views:** fate can keep individual view refs up to date through a single native Server-Sent Events stream, merging updates into the normalized cache.
 - **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
+### A modern data client for React
 
 **_fate_** is designed to make data fetching and state management in React applications more composable, declarative, and predictable. The framework has a minimal API, no DSL, and no magic—_it's just JavaScript_.
 
@@ -32,7 +33,7 @@ However, GraphQL comes with its own type system and query language. If you are a
 
 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. Using _fate_ usually looks like this:
+_fate_ takes the great ideas from Relay and applies them to plain TypeScript data fetching. You get type safety between the client and server, a native protocol with optional adapters such as tRPC, and GraphQL-like ergonomics for data fetching. Using _fate_ usually looks like this:
 
 ```tsx
 export const PostView = view<Post>()({
@@ -55,35 +56,23 @@ export const PostCard = ({ post: postRef }: { post: ViewRef<'Post'> }) => {
 };
 ```
 
-_[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)._
+_[Learn more](/docs/guide/getting-started.md) about fate's core concepts or create an app from one of the templates._
 
 ## Getting Started
 
 ### Template
 
-Get started with [a ready-made template](https://github.com/nkzw-tech/fate-template#readme) quickly:
+Create a new fate app with Vite+:
 
-::: code-group
-
-```bash [npm]
-npx giget@latest gh:nkzw-tech/fate-template
-```
-
-```bash [pnpm]
-pnpx giget@latest gh:nkzw-tech/fate-template
-```
-
-```bash [yarn]
-yarn dlx giget@latest gh:nkzw-tech/fate-template
+```bash
+vp create fate my-app
 ```
 
-:::
-
-`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.
+The template selector can create a Void app with Drizzle, a tRPC app with Drizzle, or a tRPC app with Prisma. The template sources live in the fate repo under [`packages/create-fate/templates/fate`](https://github.com/nkzw-tech/fate/tree/main/packages/create-fate/templates/fate). They feature modern tools to deliver an incredibly fast development experience.
 
 ### Manual Installation
 
-**_fate_** requires React 19.2+. For your client you need to install `react-fate`:
+**_fate_** requires React 19.2+. For a React client, install `react-fate`:
 
 ::: code-group
 
@@ -101,7 +90,7 @@ yarn add react-fate
 
 :::
 
-And for your server, install the core `@nkzw/fate` package:
+If your server is a separate package, install `@nkzw/fate` there as a runtime dependency too. Install `@nkzw/fate` on the client only for a barebones integration without React:
 
 ::: code-group
 
@@ -500,6 +489,8 @@ const { posts } = useRequest({
 });
 ```
 
+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:
@@ -521,6 +512,43 @@ const { posts } = 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:
+
+```tsx
+const fate = createClient({
+  gcReleaseBufferSize: 20,
+  roots,
+  transport,
+  types,
+});
+```
+
+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:
+
+```tsx
+const request = { posts: { list: PostView } };
+const retained = fate.retain(request);
+
+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.
+
 ## List Views
 
 ### Pagination with `useListView`
@@ -573,6 +601,287 @@ export function PostCard({ detail, post: postRef }: { detail?: boolean; post: Vi
 
 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:
+
+```tsx
+const CommentConnectionView = {
+  args: { first: 10 },
+  items: {
+    cursor: true,
+    node: CommentView,
+  },
+  pagination: {
+    hasNext: true,
+    hasPrevious: true,
+    nextCursor: true,
+    previousCursor: true,
+  },
+};
+```
+
+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:
+
+```tsx
+const { posts } = useRequest({
+  posts: {
+    args: { categoryId: category.id, first: 20 },
+    list: PostConnectionView,
+  },
+});
+```
+
+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.
+
+```tsx
+import { useLiveView, ViewRef } from 'react-fate';
+
+export const PostCard = ({ post: postRef }: { post: ViewRef<'Post'> }) => {
+  const post = useLiveView(PostView, postRef);
+
+  return (
+    <Card>
+      <h2>{post.title}</h2>
+      {/* Updates automatically! */}
+      <p>{post.likes} likes</p>
+    </Card>
+  );
+};
+```
+
+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
+
+Generate the client with the native transport and point it at your Fate endpoint:
+
+```tsx
+import { FateClient } from 'react-fate';
+import { createFateClient } from 'react-fate/client';
+
+export function App() {
+  const fate = useMemo(
+    () =>
+      createFateClient({
+        fetch: (input, init) =>
+          fetch(input, {
+            ...init,
+            credentials: 'include',
+          }),
+        url: `${env('SERVER_URL')}/fate`,
+      }),
+    [],
+  );
+
+  return <FateClient client={fate}>{/* Components go here */}</FateClient>;
+}
+```
+
+> [!NOTE]
+>
+> Live views use `GET /fate/live` for the single SSE stream and `POST /fate/live` for subscribe/unsubscribe control messages.
+
+### Server Setup
+
+Live views use an event bus. By default, the bus signals that an object changed and fate refetches the selected object through the same data view pipeline used by `byId` queries before sending it to the client. Update events can also include changed field paths so fate only resolves the intersection of those paths and each active subscription.
+
+Pass a live event bus to `createFateServer` and expose the native handler:
+
+```tsx
+import { createFateServer, createHonoFateHandler, createLiveEventBus } from '@nkzw/fate/server';
+import type { AppContext } from './context.ts';
+import { sources } from './sources.ts';
+import { Root } from './views.ts';
+
+export const live = createLiveEventBus();
+
+export const fate = createFateServer<AppContext>({
+  live,
+  roots: Root,
+  sources,
+});
+
+app.all('/fate/*', createHonoFateHandler(fate));
+```
+
+Once this is in place, components can switch from `useView` to `useLiveView` without changing their view definitions or return types.
+
+### Live List Views
+
+`useLiveListView` mirrors `useListView`, but subscribes to live connection events for the connection it receives:
+
+```tsx
+import { useLiveListView, useLiveView, ViewRef } from 'react-fate';
+
+export function PostCard({ post: postRef }: { post: ViewRef<'Post'> }) {
+  const post = useLiveView(PostView, postRef);
+  const [comments, loadNext] = useLiveListView(CommentConnectionView, post.comments);
+
+  return (
+    <>
+      {comments.map(({ node }) => (
+        <CommentCard comment={node} key={node.id} />
+      ))}
+      {loadNext ? <button onClick={loadNext}>Load more</button> : null}
+    </>
+  );
+}
+```
+
+The hook returns the same tuple as `useListView`: items, `loadNext`, and `loadPrevious`. Live events append, prepend, insert, or delete edges from one connection without deleting the underlying records.
+
+By default, live appends and prepends respect pagination boundaries. If the relevant edge still has more pages, fate keeps the incoming node attached to that edge instead of expanding the loaded window. For chat or activity streams where new items should keep appearing immediately, opt into visible live insertion on the connection view:
+
+```tsx
+const MessageConnectionView = {
+  args: { first: 30 },
+  items: {
+    node: MessageView,
+  },
+  live: {
+    append: 'visible',
+  },
+};
+```
+
+Emit connection events on the server when list membership changes:
+
+```tsx
+live.connection('Post.comments', { id: postId }).prependNode('Comment', comment.id);
+live.connection('Post.comments', { id: postId }).deleteEdge('Comment', comment.id);
+```
+
+For root lists, use the generated root procedure name:
+
+```tsx
+live.connection('posts', { categoryId }).prependNode('Post', post.id);
+```
+
+If the changed list cannot be described precisely, invalidate the active connection and fate will refetch it:
+
+```tsx
+live.connection('posts', { categoryId }).invalidate();
+```
+
+Connection identity follows Relay's model: pagination args like `first`, `last`, `after`, and `before` are ignored for live connection matching, while filter args such as `categoryId` are part of the identity.
+
+### Emitting Events
+
+After a mutation changes an object, emit an update event for that object:
+
+```tsx
+export const postRouter = router({
+  ...fate.procedures({
+    view: postDataView,
+  }),
+  like: procedure.input(likeInput).mutation(async ({ ctx, input }) => {
+    const post = await ctx.prisma.post.update({
+      data: {
+        likes: {
+          increment: 1,
+        },
+      },
+      where: { id: input.id },
+    });
+
+    live.update('Post', input.id);
+
+    return post;
+  }),
+});
+```
+
+This tells fate that the `Post` changed. Every active live view for that post refreshes using the selection it subscribed with.
+
+If you know which fields changed, pass them with `changed` to reduce the amount of data sent to each subscriber:
+
+```tsx
+live.update('Post', input.id, { changed: ['likes'] });
+```
+
+With this version, a live view that selected `likes` refreshes only `likes`, while a live view that only selected unrelated fields is skipped entirely.
+
+If a mutation changes a related object, emit for the object whose live view should refresh. For example, adding a comment usually changes the post's `commentCount` and `comments` list, so emit for the `Post`:
+
+```tsx
+export const commentRouter = router({
+  add: procedure.input(addCommentInput).mutation(async ({ ctx, input }) => {
+    const comment = await ctx.prisma.comment.create({
+      data: {
+        content: input.content,
+        postId: input.postId,
+      },
+    });
+
+    live.update('Post', input.postId, { changed: ['commentCount', 'comments'] });
+
+    return comment;
+  }),
+});
+```
+
+For deletions, emit a delete event for the deleted object if clients may be subscribed to it:
+
+```tsx
+live.delete('Comment', input.id);
+```
+
+If deleting the object also changes another object, emit an update for that object too:
+
+```tsx
+live.update('Post', postId, { changed: ['commentCount', 'comments'] });
+```
+
+You can pass an `eventId` when emitting. fate sends it on the native SSE event and includes the last received event ID when it resubscribes after a reconnect:
+
+```tsx
+live.update('Post', input.id, {
+  changed: ['likes'],
+  eventId: `post:${input.id}:${Date.now()}`,
+});
+```
+
+The default `createLiveEventBus` is an in-memory fanout bus and does not replay events that were emitted while a client was disconnected. Use a durable custom live bus if your deployment needs reconnects to catch up from `lastEventId`; otherwise the client receives future live events after it reconnects.
+
+### Error Handling
+
+Live subscription errors are reported out of band. They do not replace the last cached data or throw through the component that called `useLiveView`.
+
+Pass `onLiveError` when creating the client to send those failures to your logger or monitoring system:
+
+```tsx
+const fate = createFateClient({
+  fetch: (input, init) =>
+    fetch(input, {
+      ...init,
+      credentials: 'include',
+    }),
+  onLiveError(error) {
+    captureException(error);
+  },
+  url: `${env('SERVER_URL')}/fate`,
+});
+```
+
+The handler runs in a microtask after the subscription reports the error. Components continue to read whatever data is currently available in the fate cache.
+
 ## Actions
 
 fate does not provide hooks for mutations like traditional data fetching libraries do. Instead, mutations are exposed in two ways:
@@ -659,6 +968,24 @@ addComment({
 });
 ```
 
+By default, fate inserts new records after existing items in matching root lists and nested lists. For a newest-first list, pass `insert: 'before'` so optimistic records appear at the beginning:
+
+```tsx
+addComment({
+  input: { content, postId: post.id },
+  insert: 'before',
+  optimistic: {
+    content,
+    id: `optimistic:${Date.now().toString(36)}`,
+    post: { id: post.id },
+  },
+});
+```
+
+Insertion respects pagination boundaries. If you append to a list that still has a next page, fate keeps the new record attached to the unresolved trailing edge instead of mixing it into the loaded page. As you load more pages, the inserted record stays at the end until the server returns the canonical item or the list reaches the edge. The same behavior applies to prepends while `hasPrevious` is true.
+
+Multiple pending optimistic inserts keep their visible order. For example, two `insert: 'before'` calls on a newest-first feed show the second optimistic item before the first, matching what users expect from newly created content.
+
 ### Selecting a View with Actions
 
 Mutations may change data that is not directly specified in the mutation result. For example, adding a comment increases the post's comment count. For such cases, you can provide a `view` to an action that specifies which fields to fetch as part of the mutation:
@@ -821,31 +1148,36 @@ addComment({
 
 ## 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.
+Until now, we have focused on the client-side API of fate. You'll need a backend that follows fate's data protocol so the Vite plugin can provide a typed client module. _fate_ currently ships two server paths:
+
+- The native Fate protocol, which is transport-agnostic and can be hosted by any Fetch-compatible server.
+- The tRPC adapter, which keeps compatibility with existing tRPC backends.
+
+_fate_ currently provides database adapters for Prisma and Drizzle, but the framework itself is not coupled to a particular ORM. The adapters plug into the same source execution runtime and can be exposed through the native protocol or through tRPC.
 
 ### Conventions & Object Identity
 
-fate expects that data is served by a tRPC backend that follows these conventions:
+fate expects that data is served by a backend that follows these conventions:
 
 - A `byId` query for each data type to fetch individual objects by their unique identifier (`id`).
 - A `list` query for fetching lists of objects with support for pagination.
 
 Objects are identified by their ID and type name (`__typename`, e.g. `Post`, `User`), and stored by `__typename:id` (e.g. "Post:123") in the client cache. fate keeps list orderings under stable keys derived from the backend procedure and args. Relations are stored as IDs and returned to components as ViewRef tokens.
 
-fate's type definitions might seem verbose at first glance. However, with fate's minimal API surface, AI tools can easily generate this code for you. For example, fate has a minimal CLI that generates types for the client, but you can also let your LLM write it by hand if you prefer.
+fate's type definitions might seem verbose at first glance. However, with fate's minimal API surface, AI tools can easily generate this code for you, or you can let the Vite plugin provide the typed client module for your app.
 
 > [!NOTE]
 > You can adopt _fate_ incrementally in an existing tRPC codebase without changing your existing schema by adding these queries alongside your existing procedures.
 
 ### Data Views
 
-To continue with our client example, let's assume we have a `post.ts` file with a tRPC router that exposes a `byId` query for selecting objects by id, and a root `list` query to fetch a list of posts.
-
 Since clients can send arbitrary selection objects to the server, we need to implement a way to translate these selection objects into database queries without exposing raw database queries and private data to the client. On the client, we define views to select fields on each type. We can do the same on the server using fate data views and the `dataView` function from `@nkzw/fate/server`.
 
-Create a `views.ts` file next to your root tRPC router that exports the data views for each type. Here is how you can define a `User` data view for Prisma's `User` model:
+Create a `views.ts` file next to your server entry that exports the data views for each type. The same data view shape works with both Prisma model types and Drizzle row types:
 
-```tsx
+::: code-group
+
+```tsx [Prisma]
 import { dataView, type Entity } from '@nkzw/fate/server';
 import type { User as PrismaUser } from '../prisma/prisma-client/client.ts';
 
@@ -858,37 +1190,21 @@ export const userDataView = dataView<PrismaUser>('User')({
 export type User = Entity<typeof userDataView, 'User'>;
 ```
 
-_Note: Currently, fate provides helpers to integrate with Prisma, but the framework is not coupled to any particular ORM or database. We hope to provide more direct integrations in the future, and are always open to contributions._
-
-### tRPC Router Implementation
-
-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 { 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(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);
+```tsx [Drizzle]
+import { dataView, type Entity } from '@nkzw/fate/server';
+import type { UserRow } from '../drizzle/schema.ts';
 
-    return await resolveMany(users);
-  }),
+export const userDataView = dataView<UserRow>('User')({
+  id: true,
+  name: true,
+  username: true,
 });
+
+export type User = Entity<typeof userDataView, 'User'>;
 ```
 
+:::
+
 Now that we apply `userDataView` to the `byId` query, the server limits the selection to the fields defined in the data view, keeping private fields hidden from the client, and providing type safety for client views:
 
 ```tsx
@@ -898,43 +1214,6 @@ const UserData = view<User>()({
 });
 ```
 
-### tRPC List Implementation
-
-To implement the `list` query for fetching a paginated list of posts, we can use fate's `createConnectionProcedure` helper. This helper simplifies the implementation of pagination. Here is an example implementation of the `postRouter` with a `list` query:
-
-```tsx
-import { createResolver } from '@nkzw/fate/server';
-import type { PostFindManyArgs } from '../../prisma/prisma-client/models.ts';
-import { createConnectionProcedure } from '../connection.ts';
-import { router } from '../init.ts';
-import { postDataView } from '../views.ts';
-
-export const postRouter = router({
-  list: createConnectionProcedure({
-    query: async ({ ctx, cursor, direction, input, skip, take }) => {
-      const { resolveMany, select } = createResolver({
-        ...input,
-        ctx,
-        view: postDataView,
-      });
-      const findOptions: PostFindManyArgs = {
-        orderBy: { createdAt: 'desc' },
-        select,
-        take: direction === 'forward' ? take : -take,
-      };
-
-      if (cursor) {
-        findOptions.cursor = { id: cursor };
-        findOptions.skip = skip;
-      }
-
-      const items = await ctx.prisma.post.findMany(findOptions);
-      return resolveMany(direction === 'forward' ? items : items.reverse());
-    },
-  }),
-});
-```
-
 ### Data View Composition
 
 Similar to client-side views, data views can be composed of other data views:
@@ -962,7 +1241,7 @@ export const commentDataView = dataView<CommentItem>('Comment')({
 
 export const postDataView = dataView<PostItem>('Post')({
   author: userDataView,
-  comments: list(commentDataView),
+  comments: list(commentDataView, { orderBy: [{ createdAt: 'asc' }, { id: 'asc' }] }),
 });
 ```
 
@@ -970,15 +1249,20 @@ We can define extra root-level lists and queries by exporting a `Root` object fr
 
 ```tsx
 export const Root = {
-  categories: list(categoryDataView),
-  commentSearch: { procedure: 'search', view: list(commentDataView) },
-  events: list(eventDataView),
-  posts: list(postDataView),
+  categories: list(categoryDataView, { orderBy: [{ createdAt: 'asc' }, { id: 'asc' }] }),
+  commentSearch: {
+    procedure: 'search',
+    view: list(commentDataView, { orderBy: [{ createdAt: 'desc' }, { id: 'desc' }] }),
+  },
+  events: list(eventDataView, { orderBy: [{ startAt: 'asc' }, { id: 'asc' }] }),
+  posts: list(postDataView, { orderBy: { createdAt: 'desc', id: 'desc' } }),
   viewer: userDataView,
 };
 ```
 
-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.
+Entries that wrap their view in `list(...)` are treated as list resolvers. In the native protocol, the root key is the operation name sent by the generated client. In the tRPC adapter, `procedure` can point that root at a specific router procedure. If you omit `list(...)`, fate treats the entry as a standard query.
+
+You can pass default list options such as `orderBy` to `list(...)`. Ordering is scoped to that specific list wrapper: `Root.posts` can order posts by `createdAt desc`, while `categoryDataView.posts` or `postDataView.comments` can choose their own order. If no order is provided, Fate orders by `id asc`. Fate always appends `id asc` as a tie-breaker when no `id` order is present; include `id` yourself when you need a different tie-breaker direction such as `id desc`. Use the array form when ordering by multiple fields so the priority is unambiguous.
 
 For the above `Root` definitions, you can make the following requests using `useRequest`:
 
@@ -999,43 +1283,421 @@ const { posts, categories, viewer } = useRequest({
 });
 ```
 
-### Data View Resolvers
+### Native Fate Protocol
 
-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:
+The native protocol keeps tRPC optional. Create a source adapter from your ORM integration, pass it to `createFateServer`, and expose the returned server through a Fetch-compatible handler.
 
 ```tsx
-export const postDataView = dataView<PostItem>('Post')({
-  author: userDataView,
-  commentCount: resolver<PostItem, number>({
-    resolve: ({ _count }) => _count?.comments ?? 0,
-    select: () => ({
-      _count: { select: { comments: true } },
+import { createFateServer, createHonoFateHandler } from '@nkzw/fate/server';
+import { createPrismaSourceAdapter } from '@nkzw/fate/server/prisma';
+import { Hono } from 'hono';
+import type { AppContext } from './context.ts';
+import { prisma } from './prisma.ts';
+import { Root, userDataView } from './views.ts';
+
+export { Root } from './views.ts';
+
+const sources = createPrismaSourceAdapter<AppContext>({
+  prisma: (ctx) => ctx.prisma,
+  views: Root,
+});
+
+export const fate = createFateServer({
+  context: async ({ adapterContext }) => ({
+    prisma,
+    request: adapterContext.req.raw,
+    sessionUser: await getSessionUser(adapterContext.req.raw),
+  }),
+  queries: {
+    viewer: {
+      resolve: ({ ctx, select }) =>
+        sources.resolveById({
+          ctx,
+          id: ctx.sessionUser.id,
+          input: { select },
+          view: userDataView,
+        }),
+    },
+  },
+  roots: Root,
+  sources,
+});
+
+const app = new Hono();
+const handler = createHonoFateHandler(fate);
+
+app.post('/fate', handler);
+app.post('/fate/live', handler);
+```
+
+Configure the Vite plugin with the native transport:
+
+```tsx
+import { fate } from 'react-fate/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    fate({
+      module: '@your-org/server/fate.ts',
+      transport: 'native',
     }),
+  ],
+});
+```
+
+The generated client uses `createHTTPTransport`:
+
+```tsx
+import { createFateClient } from 'react-fate/client';
+
+const client = createFateClient({
+  url: '/fate',
+});
+```
+
+The HTTP transport batches operations issued in the same microtask into one `POST /fate` request. Live views use one `GET /fate/live` SSE stream per Fate client and `POST /fate/live` control messages when views subscribe or unsubscribe.
+
+#### Custom Queries
+
+Root query entries such as `viewer` need an explicit resolver because fate cannot infer application-specific behavior like "current user" from a data view:
+
+```tsx
+export const fate = createFateServer({
+  context,
+  queries: {
+    viewer: {
+      resolve: ({ ctx, select }) =>
+        sources.resolveById({
+          ctx,
+          id: ctx.sessionUser.id,
+          input: { select },
+          view: userDataView,
+        }),
+    },
+  },
+  roots: Root,
+  sources,
+});
+```
+
+#### Custom Mutations
+
+Mutations declare the entity type they return and receive the selected fields requested by the client. Resolve the updated record through the source adapter so the response has the same masking and relation behavior as regular view requests:
+
+```tsx
+export const fate = createFateServer({
+  mutations: {
+    'post.like': {
+      input: likeInput,
+      resolve: async ({ ctx, input, select }) => {
+        await ctx.prisma.post.update({
+          data: { likes: { increment: 1 } },
+          where: { id: input.id },
+        });
+
+        return sources.resolveById({
+          ctx,
+          id: input.id,
+          input: { select },
+          view: postDataView,
+        });
+      },
+      type: 'Post',
+    },
+  },
+  roots: Root,
+  sources,
+});
+```
+
+#### Live Views
+
+Pass a live event bus to enable `useLiveView` over the native SSE endpoint:
+
+```tsx
+import { createLiveEventBus } from '@nkzw/fate/server';
+
+export const live = createLiveEventBus();
+
+export const fate = createFateServer({
+  live,
+  queries: {
+    viewer: {
+      resolve: ({ ctx, select }) =>
+        sources.resolveById({
+          ctx,
+          id: ctx.sessionUser.id,
+          input: { select },
+          view: userDataView,
+        }),
+    },
+  },
+  roots: Root,
+  sources,
+});
+
+live.update('Post', post.id, {
+  changed: ['likes'],
+  eventId: `post:${post.id}:${Date.now()}`,
+});
+```
+
+`changed` is optional. When provided, fate resolves only the changed fields selected by each live subscription and skips subscriptions that do not select those fields. `createLiveEventBus` is an in-memory fanout bus. It forwards `eventId` to SSE clients, but it does not replay events after reconnects. If your app needs lossless reconnect behavior, provide a durable live bus implementation that uses the `lastEventId` passed to `listen`, `listenConnection`, `subscribe`, and `subscribeConnection`.
+
+### tRPC Fate Setup
+
+The Prisma and Drizzle tRPC integrations connect your data views to your database, bind fate's standard tRPC procedures, and expose helpers for custom queries and mutations.
+
+Pass the `Root` export from `views.ts` to Fate in your tRPC `init.ts` file. Fate walks that view graph to find the data views it needs. `id` defaults to `"id"`, and Fate uses it as the fallback ordering for cursor pagination. Relations are inferred from the data view and ORM schema: a nested data view is loaded as a singular relation, `list(view)` is loaded as a list relation, and Drizzle join tables are discovered from relation metadata.
+
+#### Prisma
+
+Use `createPrismaFate` from `@nkzw/fate/server/prisma` next to your tRPC helpers. By default, Fate reads Prisma delegates from `ctx.prisma` using each data view's type name:
+
+```tsx
+import { initTRPC } from '@trpc/server';
+import { createPrismaFate } from '@nkzw/fate/server/prisma';
+import type { AppContext } from './context.ts';
+import { Root } from './views.ts';
+
+const t = initTRPC.context<AppContext>().create();
+
+export const router = t.router;
+export const procedure = t.procedure;
+
+export const fate = createPrismaFate<AppContext, typeof procedure>({
+  procedure,
+  views: Root,
+});
+```
+
+If your Prisma client is not stored at `ctx.prisma`, pass `prisma: (ctx) => ctx.db`.
+
+The Prisma integration translates view requests into Prisma `select`, `where`, `cursor`, `skip`, and `take` options. It also hydrates computed `count(...)` dependencies using Prisma `groupBy` when needed.
+
+For custom Prisma queries and mutations, use `fate.createPlan` with `toPrismaSelect`:
+
+```tsx
+import { toPrismaSelect } from '@nkzw/fate/server';
+
+const plan = fate.createPlan({
+  ...input,
+  ctx,
+  view: postDataView,
+});
+
+const post = await ctx.prisma.post.update({
+  data: {
+    likes: {
+      increment: 1,
+    },
+  },
+  select: toPrismaSelect(plan),
+  where: { id: input.id },
+});
+
+return plan.resolve(post);
+```
+
+#### Drizzle
+
+Use `createDrizzleFate` from `@nkzw/fate/server/drizzle`. Fate matches data view type names to Drizzle tables from your schema. The `db` option can be a Drizzle database object or a function that receives your tRPC context and returns a request-scoped database object:
+
+```tsx
+import { initTRPC } from '@trpc/server';
+import { createDrizzleFate } from '@nkzw/fate/server/drizzle';
+import db from '../drizzle/db.ts';
+import schema from '../drizzle/schema.ts';
+import type { AppContext } from './context.ts';
+import { Root } from './views.ts';
+
+const t = initTRPC.context<AppContext>().create();
+
+export const router = t.router;
+export const procedure = t.procedure;
+
+export const fate = createDrizzleFate<AppContext, typeof procedure>({
+  db,
+  procedure,
+  schema,
+  views: Root,
+});
+```
+
+If your database lives on the request context, pass a function instead:
+
+```tsx
+import schema from '../drizzle/schema.ts';
+import { Root } from './views.ts';
+
+export const fate = createDrizzleFate<AppContext, typeof procedure>({
+  db: (ctx) => ctx.db,
+  procedure,
+  schema,
+  views: Root,
+});
+```
+
+The Drizzle adapter builds SQL queries from your registered data views. It selects only requested columns, hydrates singular, list, and many-to-many relations, supports nested cursor pagination, and hydrates computed `count(...)` dependencies with SQL grouped counts. Count filters may be plain equality objects or Drizzle SQL predicates written as `(columns) => eq(columns.status, 'GOING')`.
+
+For request-specific sorting, prefer a custom root query that validates and translates explicit sort args.
+
+For many-to-many relations, define the join table relations in your Drizzle schema. Fate discovers a join table that points at both the source table and the target table:
+
+```tsx
+export const fate = createDrizzleFate<AppContext, typeof procedure>({
+  db,
+  procedure,
+  schema,
+  views: Root,
+});
+```
+
+You can still provide explicit join metadata when the schema is ambiguous:
+
+```tsx
+{
+  manyToMany: {
+    tags: {
+      foreignColumn: postToTag.tagId,
+      localColumn: postToTag.postId,
+      table: postToTag,
+    },
+  },
+  relations: {
+    tags: {
+      foreignKey: 'id',
+      localKey: 'id',
+      through: {
+        foreignKey: 'tagId',
+        localKey: 'postId',
+      },
+    },
+  },
+  table: post,
+  view: postDataView,
+}
+```
+
+Drizzle writes should stay ordinary Drizzle code. After creating or updating a row, use `fate.resolveById` to return the selected shape that the client asked for:
+
+```tsx
+const postId = await createPostRecord({
+  authorId: ctx.sessionUser.id,
+  content: input.content,
+  title: input.title,
+});
+
+const post = await fate.resolveById({
+  ctx,
+  id: postId,
+  input,
+  view: postDataView,
+});
+
+return post;
+```
+
+### tRPC Procedures
+
+Use `fate.procedures` to build the standard `byId` and `list` procedures expected by the generated fate client:
+
+```tsx
+import { fate, router } from '../init.ts';
+import { postDataView } from '../views.ts';
+
+export const postRouter = router({
+  ...fate.procedures(postDataView),
+});
+```
+
+You can disable the generated `list` procedure if a view should only be fetched by id:
+
+```tsx
+export const commentRouter = router({
+  ...fate.procedures({
+    list: false,
+    view: commentDataView,
+  }),
+});
+```
+
+### Custom Queries
+
+You can add custom root queries next to generated procedures. Define the root in `Root`, implement a matching tRPC procedure, and call `fate.resolveConnection`:
+
+```tsx
+export const Root = {
+  commentSearch: { procedure: 'search', view: list(commentDataView) },
+};
+```
+
+```tsx
+import { ilike } from 'drizzle-orm';
+import { fate } from '../init.ts';
+
+export const commentRouter = router({
+  ...fate.procedures({
+    list: false,
+    view: commentDataView,
+  }),
+  search: fate.connection({
+    input: z.object({
+      query: z.string().min(1, 'Search query is required'),
+    }),
+    query: ({ ctx, cursor, direction, input, take }) =>
+      fate.resolveConnection({
+        ctx,
+        cursor,
+        direction,
+        extra: {
+          where: ilike(comment.content, `%${input.args.query}%`),
+        },
+        input,
+        take,
+        view: commentDataView,
+      }),
   }),
-  comments: list(commentDataView),
-  id: true,
 });
 ```
 
-This definition makes the `commentCount` field available to your client-side views.
+For Prisma, pass Prisma query options such as `{ where: { ... } }` in `extra` instead of a Drizzle SQL expression.
 
-### Authorization in Resolvers
+### Data View 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:
+fate data views support computed fields. Use `computed`, `field`, and `count` to describe the hidden data needed to resolve a public field:
 
 ```tsx
+import { computed, count, field } from '@nkzw/fate/server';
+
 export const userDataView = dataView<UserItem>('User')({
-  email: resolver<UserItem, string | null, { sessionUser: string }>({
-    authorize: ({ id }, context) => context?.sessionUserId === id,
-    resolve: ({ email }) => email,
+  email: computed<UserItem, string | null, AppContext>({
+    authorize: ({ id }, context) => context?.sessionUser?.id === id,
+    select: {
+      email: field('email'),
+    },
+    resolve: (_item, deps) => (deps.email as string | null) ?? null,
+  }),
+  id: true,
+});
+
+export const postDataView = dataView<PostItem>('Post')({
+  commentCount: computed<PostItem, number>({
+    select: {
+      count: count('comments'),
+    },
+    resolve: (_item, deps) => (deps.count as number) ?? 0,
   }),
   id: true,
 });
 ```
 
-### Generating a typed client
+The adapters fetch the hidden `field(...)` and `count(...)` dependencies for you. This keeps private fields like `email` available to the resolver without exposing them to the client selection.
 
-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.
+### Configuring the 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 Vite plugin for convenience.
 
 First, make sure our tRPC `router.ts` file exports the `appRouter` object, `AppRouter` type and all the views we have defined:
 
@@ -1054,22 +1716,43 @@ export type AppRouter = typeof appRouter;
 export * from './views.ts';
 ```
 
-_Note: We try to keep magic to a minimum and you can handwrite the [generated client](https://github.com/nkzw-tech/fate/blob/main/example/client/src/fate.ts) if you prefer._
+Configure the fate Vite plugin with your server module:
 
-```bash
-pnpm fate generate @your-org/server/trpc/router.ts client/src/fate.ts
+```tsx
+import { fate } from 'react-fate/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    fate({
+      module: '@your-org/server/trpc/router.ts',
+    }),
+  ],
+});
 ```
 
-_Note: fate uses the specified server module name to extract the server types it needs and uses the same module name to import the views into the generated client. Make sure that the module is available both at the root where you are running the CLI and in the client package._
+_Note: fate uses the specified server module name to extract the server types it needs and uses the same module name in the generated client. Make sure that the module is available to the client package's Vite config._
+
+During development, the plugin watches the server module and the files it imports. When one of those files changes, fate regenerates the project-local client and invalidates `@nkzw/fate/client` in Vite's module graph.
+
+For a barebones client without React, import the plugin from `@nkzw/fate/vite` and the generated client from `@nkzw/fate/client`. The plugin writes the project-local client for the selected client module path.
+
+The plugin writes project-local types under `.fate/`. If your TypeScript config does not already include dot-directories, extend the generated config:
+
+```json
+{
+  "extends": "./.fate/tsconfig.json"
+}
+```
 
 ### Creating a _fate_ Client
 
-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:
+Now that the Vite plugin provides 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 { createFateClient } from './fate.ts';
+import { createFateClient } from 'react-fate/client';
 
 export function App() {
   const fate = useMemo(
@@ -1100,7 +1783,7 @@ _And you are all set. Happy building!_
 
 [In an alternate reality](https://github.com/phacility/javelin), _fate_ can be described like this:
 
-**_fate_** is an ambitious React data library that tries to blend Relay-style ideas with tRPC, held together by equal parts vision and vibes. It aims to fix problems you definitely wouldn't have if you enjoy writing the same fetch logic in three different places with imperative loading state and error handling. fate promises predictable data flow, minimal APIs, and "no magic", though you may occasionally suspect otherwise.
+**_fate_** is an ambitious React data library that tries to blend Relay-style ideas with type-safe data fetching, held together by equal parts vision and vibes. It aims to fix problems you definitely wouldn't have if you enjoy writing the same fetch logic in three different places with imperative loading state and error handling. fate promises predictable data flow, minimal APIs, and "no magic", though you may occasionally suspect otherwise.
 
 **_fate_** is almost certainly worse than actual sync engines, but will hopefully be better than existing React data-fetching libraries eventually. Use it if you have a high tolerance for pain and want to help shape the future of data fetching in React.
 
@@ -1121,14 +1804,12 @@ Probably. One day. _Maybe._
 
 ## Future
 
-**_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:
+**_fate_** is not complete yet. The current implementation of _fate_ ships with tRPC, Prisma, and Drizzle support, but the core ideas are not tied to a particular transport or database. 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
+- Live views for pagination
+- Additional backend adapters
 - 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
 
 ## Acknowledgements