react-fate 0.1.3 → 1.0.0

package/docs/guide/actions.md

@@ -0,0 +1,263 @@
+# Actions
+
+fate does not provide hooks for mutations like traditional data fetching libraries do. Instead, mutations are exposed in two ways:
+
+- `fate.actions` for use with [`useActionState`](https://react.dev/reference/react/useActionState) and React Actions.
+- `fate.mutations` for traditional imperative mutation calls.
+
+Mutations in your tRPC backend are made available as actions and mutations by fate's generated client.
+
+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);
+
+  return (
+    <Button action={() => like({ input: { id: post.id } })}>
+      {result?.error ? 'Oops!' : 'Like'}
+    </Button>
+  );
+};
+```
+
+If you are not using an async component library, you can use React's `useTransition` to start the action in a transition:
+
+```tsx
+const LikeButton = ({ post }: { post: { id: string; likes: number } }) => {
+  const fate = useFateClient();
+  const [, startTransition] = useTransition();
+  const [result, like, isPending] = useActionState(fate.actions.post.like, null);
+
+  return (
+    <button
+      disabled={isPending}
+      onClick={() => {
+        startTransition(() =>
+          like({
+            input: { id: post.id },
+          }),
+        );
+      }}
+    >
+      {result?.error ? 'Oops!' : 'Like'}
+    </button>
+  );
+};
+```
+
+By using `useActionState`, fate Actions integrate with Suspense and concurrent rendering.
+
+## Optimistic Updates
+
+fate Actions support optimistic updates out of the box. For example, to update the post's like count optimistically, you can pass an `optimistic` object to the action call. This will immediately update the cache with the new like count and re-render all views that select the `likes` field:
+
+```tsx
+like({
+  input: { id: post.id },
+  optimistic: { likes: post.likes + 1 },
+});
+```
+
+When data changes through optimistic updates or otherwise, fate only re-renders the views that select the changed fields. In the above example, only views that select the `likes` field will re-render. If a view only selects the `title` field, it won't re-render when the `likes` field changes.
+
+If a mutation fails, the cache will be rolled back to its previous state and any views depending on the mutated data will be updated.
+
+## Inserting New Objects
+
+When a mutation inserts a new object, you can provide an optimistic object with a temporary ID to represent the new object in the cache until the server responds with the actual ID. For example, to add a new comment to a post optimistically, you can do the following:
+
+```tsx
+const content = 'New Comment text';
+addComment({
+  input: { content, postId: post.id },
+  optimistic: {
+    author: { id: user.id, name: user.name },
+    content,
+    id: `optimistic:${Date.now().toString(36)}`,
+    post: { commentCount: post.commentCount + 1, id: post.id },
+  },
+});
+```
+
+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:
+
+```tsx
+addComment({
+  input: { content: 'New Comment text', postId: post.id },
+  view: view<Comment>()({
+    ...CommentView,
+    post: { commentCount: true },
+  }),
+});
+```
+
+The server will return the selected fields and fate updates the cache and re-renders all views that depend on the changed data. The action result contains the newly added comment with the selected fields:
+
+```tsx
+const [result, addComment] = useActionState(fate.actions.comment.add, null);
+
+const newComment = result?.result;
+if (newComment) {
+  // All the fields selected in the view are available on `newComment`:
+  console.log(newComment.post.commentCount);
+}
+```
+
+## Mutations
+
+fate Actions are the recommended way to execute server mutations in React components. However, there are cases where you might want to call mutations imperatively, outside of React components, or without waiting for previous actions to finish like `useActionState` does. For such cases, you can use `fate.mutations` to call mutations imperatively:
+
+```tsx
+const result = await fate.mutations.comment.add({
+  input: { content, postId: post.id },
+});
+```
+
+You can call mutations from anywhere, and without waiting for previous mutations to finish. The mutation API matches the API of fate Actions, including optimistic updates and view selection. With mutations, you'll need to handle loading states and errors manually, and the result is returned as a promise.
+
+## Mutation Server Implementation
+
+fate Actions & Mutations are backed by regular tRPC mutations on the server. Here is an example implementation of the `like` mutation in the `postRouter`.
+
+```tsx
+import { z } from 'zod';
+import { connectionArgs, createResolver } from '@nkzw/fate/server';
+import { procedure, router } from '../init.ts';
+import { postDataView, PostItem } from '../views.ts';
+
+export const postRouter = router({
+  like: procedure
+    .input(
+      z.object({
+        args: connectionArgs,
+        id: z.string().min(1, 'Post id is required.'),
+        select: z.array(z.string()),
+      }),
+    )
+    .mutation(async ({ ctx, input }) => {
+      const { resolve, select } = createResolver({
+        ...input,
+        ctx,
+        view: postDataView,
+      });
+
+      return resolve(
+        await ctx.prisma.post.update({
+          data: {
+            likes: {
+              increment: 1,
+            },
+          },
+          select,
+          where: { id: input.id },
+        } as PostUpdateArgs),
+      );
+    }),
+});
+```
+
+See the [Server Integration](#server-integration) section for more details on how to integrate tRPC routers with fate.
+
+## Action & Mutation Error Handling
+
+fate Actions & Mutations separate error handling into two scopes: "call site" and "boundary". Call site errors are expected to be handled at the location where the action or mutation is called. Boundary errors are unexpected errors that should be handled by a higher-level error boundary.
+
+If your server returns a `NOT_FOUND` error with code `404`, the result of an Action or Mutation will contain an error object that you can handle at the call site:
+
+```tsx
+const [result] = useActionState(fate.actions.post.delete, null);
+
+if (result?.error) {
+  if (result.error.code === 'NOT_FOUND') {
+    // Handle not found error at call site.
+  } else {
+    // Handle other *expected* errors.
+  }
+}
+```
+
+However, if an `INTERNAL_SERVER_ERROR` error with code `500` occurs, it will be thrown and can be caught by the nearest React error boundary:
+
+```tsx
+<ErrorBoundary FallbackComponent={ErrorComponent}>
+  <Suspense fallback={<div>Loading…</div>}>
+    <PostPage postId={postId} />
+  </Suspense>
+</ErrorBoundary>
+```
+
+You can find the error classification behavior in [`mutation.ts`](https://github.com/nkzw-tech/fate/blob/main/packages/fate/src/mutation.ts#L227-L254).
+
+## Deleting Records
+
+When you want to delete a record using fate Actions, you can pass a `delete: true` flag to the action call. This flag removes the object from the cache and re-renders all views that depend on the deleted data:
+
+```tsx
+const [result, deleteAction] = useActionState(fate.actions.post.delete, null);
+
+deleteAction({
+  input: { id: post.id },
+  delete: true,
+});
+```
+
+## Resetting Action State
+
+When using `useActionState`, the result of the action is cached until the component using the action is unmounted. When a mutation fails with an error, you might want to clear the error state without invoking the action again. fate Actions take a `'reset'` token to reset the action state:
+
+```tsx
+const [result, like] = useActionState(fate.actions.post.like, null);
+
+useEffect(() => {
+  if (result?.error) {
+    // Reset the action state after 3 seconds.
+    const timeout = setTimeout(() => startTransition(() => like('reset')), 3000);
+    return () => clearTimeout(timeout);
+  }
+}, [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.
+});
+```

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.