@nkzw/fate 0.1.2 → 1.0.0-rc.0

package/docs/guide/core-concepts.md

@@ -0,0 +1,22 @@
+# Core Concepts
+
+**_fate_** has a minimal API surface and is aimed at reducing data fetching complexity.
+
+## Thinking in Views
+
+In fate, each component declares the data it needs using views. Views are composed upward through the component tree until they reach a root, where the actual request is made. fate fetches all required data in a single request. React Suspense manages loading states, and any data-fetching errors naturally bubble up to React error boundaries. This eliminates the need for imperative loading logic or manual error handling.
+
+Traditionally, React apps are built with components and hooks. fate introduces a third primitive: views – a declarative way for components to express their data requirements. An app built with fate looks more like this:
+
+<p align="center">
+  <picture class="fate-tree">
+    <source media="(prefers-color-scheme: dark)" srcset="/public/fate-tree-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="/public/fate-tree.svg">
+    <img alt="Tree" src="/public/fate-tree.svg" width="90%">
+  </picture>
+</p>
+
+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.

package/docs/guide/getting-started.md

@@ -0,0 +1,57 @@
+# Getting Started
+
+## Template
+
+Create a new fate app with Vite+:
+
+```bash
+vp create fate my-app
+```
+
+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 a React client, install `react-fate`:
+
+::: code-group
+
+```bash [npm]
+npm add react-fate
+```
+
+```bash [pnpm]
+pnpm add react-fate
+```
+
+```bash [yarn]
+yarn add react-fate
+```
+
+:::
+
+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
+
+```bash [npm]
+npm add @nkzw/fate
+```
+
+```bash [pnpm]
+pnpm add @nkzw/fate
+```
+
+```bash [yarn]
+yarn add @nkzw/fate
+```
+
+:::
+
+> [!WARNING]
+>
+> **_fate_** is currently in alpha and not production ready. If something doesn't work for you, please open a pull request.
+
+If you'd like to try the example app in GitHub Codespaces, click the button below:
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?repo=nkzw-tech/fate)

package/docs/guide/list-views.md

@@ -0,0 +1,86 @@
+# 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`:
+
+```tsx
+import { useListView, ViewRef } from 'react-fate';
+
+const CommentView = view<Comment>()({
+  content: true,
+  id: true,
+});
+
+const CommentConnectionView = {
+  args: { first: 10 },
+  items: {
+    node: CommentView,
+  },
+};
+
+const PostView = view<Post>()({
+  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:
+
+```tsx
+export function PostCard({ detail, post: postRef }: { detail?: boolean; post: ViewRef<'Post'> }) {
+  const post = useView(PostView, postRef);
+  const [comments, loadNext] = useListView(CommentConnectionView, post.comments);
+
+  return (
+    <div>
+      {comments.map(({ node }) => (
+        <CommentCard comment={node} key={node.id} post={post} />
+      ))}
+      {loadNext ? (
+        <Button onClick={loadNext} variant="ghost">
+          Load more comments
+        </Button>
+      ) : null}
+    </div>
+  );
+}
+```
+
+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.

package/docs/guide/live-views.md

@@ -0,0 +1,245 @@
+# 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.

package/docs/guide/requests.md

@@ -0,0 +1,130 @@
+# Requests
+
+## Requesting Lists
+
+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:
+
+```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
+<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
+
+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:
+
+```tsx
+const { posts } = useRequest({
+  posts: {
+    args: { first: 10 },
+    list: PostView,
+  },
+});
+```
+
+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`:
+
+```tsx
+const { posts } = useRequest(
+  {
+    posts: { list: PostView },
+  },
+  {
+    mode: 'stale-while-revalidate',
+  },
+);
+```
+
+## 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.