@nkzw/fate 0.1.2 → 1.0.0-rc.0

package/docs/guide/views.md

@@ -0,0 +1,278 @@
+# Views
+
+## Defining Views
+
+Let's start by defining a simple view for a blog's `Post` component. fate requires you to explicitly "select" each field that you plan to use in your components. Here is how you can define a view for a `Post` entity that has `title` and `content` fields:
+
+```tsx
+import { view } from 'react-fate';
+
+type Post = {
+  content: string;
+  id: string;
+  title: string;
+};
+
+export const PostView = view<Post>()({
+  content: true,
+  id: true,
+  title: true,
+});
+```
+
+Fields are selected by setting them to `true` in the view definition. This tells **_fate_** that these fields should be fetched from the server and made available to components that use this view.
+
+> [!NOTE]
+> The `Post` type above is an example. In a real application, this type is defined on the server and imported into your client code.
+
+## Resolving a View with `useView`
+
+Now we can use the view that we defined in a `PostCard` React component to resolve the data against a reference of an individual `Post`:
+
+```tsx
+import { useView, ViewRef } from 'react-fate';
+
+export const PostCard = ({ post: postRef }: { post: ViewRef<'Post'> }) => {
+  const post = useView(PostView, postRef);
+
+  return (
+    <Card>
+      <h2>{post.title}</h2>
+      <p>{post.content}</p>
+    </Card>
+  );
+};
+```
+
+A `ViewRef` is a reference to a concrete object of a specific type, for example a `Post` with id `7`. It contains the unique ID of the object, the type name (as `__typename`) and some fate-specific metadata. fate creates and manages these references for you, and you can pass them around your components as needed.
+
+Components using `useView` listen to changes for all selected fields. When data changes, fate re-renders all of the fields that depend on that data. For example, if the `title` of the `Post` changes, the `PostCard` component re-renders with new data. However, if a different field such as `likes` that isn't selected in `PostView` changes, the `PostCard` component will not re-render.
+
+## 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 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} />);
+}
+```
+
+_Learn more about `useRequest` in the [Requests Guide](requests.md)._
+
+## Composing Views
+
+In the above example we are defining a single view for a `Post`. One of fate's core strengths is view composition. Let's say we want to show the author's name along with the post. A simple way to do this is by adding an `author` field to the `PostView` with a concrete selection:
+
+```tsx
+import { Suspense } from 'react';
+import { useView, ViewRef } from 'react-fate';
+
+export const PostView = view<Post>()({
+  author: {
+    id: true,
+    name: true,
+  },
+  content: true,
+  id: true,
+  title: true,
+});
+
+const PostCard = ({ postRef }: { postRef: ViewRef<'Post'> }) => {
+  const post = useView(PostView, postRef);
+  return (
+    <Card>
+      <h2>{post.title}</h2>
+      <p>by {post.author.name}</p>
+      <p>{post.content}</p>
+    </Card>
+  );
+};
+```
+
+This code fetches the author associated with the Post and makes it available to the `PostCard` component. However, this approach has some downsides:
+
+1. The `author` selection is tightly coupled to the `PostView`. If we want to use the author's data in another component, we would need to duplicate the field selection.
+1. If the `author` has more fields that we want to use in other components, we would need to add them to the `PostView`, leading to overfetching.
+1. We cannot reuse the `author` field selection in other views or components.
+
+In fate, views are composable and reusable. Instead of inlining the selection, we can define a `UserView` and compose it into the `PostView` like this:
+
+```tsx
+import type { Post, User } from '@your-org/server/trpc/views';
+import { view } from 'react-fate';
+
+export const UserView = view<User>()({
+  id: true,
+  name: true,
+  profilePicture: true,
+});
+
+export const PostView = view<Post>()({
+  author: UserView,
+  content: true,
+  id: true,
+  title: true,
+});
+```
+
+Now we can create a separate `UserCard` component that uses our `UserView`:
+
+```tsx
+import { useView, ViewRef } from 'react-fate';
+
+export const UserCard = ({ user: userRef }: { user: ViewRef<'User'> }) => {
+  const user = useView(UserView, userRef);
+
+  return (
+    <div>
+      <img src={user.profilePicture} alt={user.name} />
+      <p>{user.name}</p>
+    </div>
+  );
+};
+```
+
+And update `PostCard` to use our `UserCard` component:
+
+```tsx
+import { UserCard } from './UserCard.tsx';
+
+export const PostCard = ({ post: postRef }: { post: ViewRef<'Post'> }) => {
+  const post = useView(PostView, postRef);
+
+  return (
+    <Card>
+      <h2>{post.title}</h2>
+      <UserCard user={post.author} />
+      <p>{post.content}</p>
+    </Card>
+  );
+};
+```
+
+## View Spreads
+
+When building complex UIs, you will often build multiple components that share the same data requirements. In fate, you can use view spreads to compose such views together. This is similar to GraphQL fragment spreads, but works with plain JavaScript objects.
+
+Let's assume we want to fetch and display additional information about the author in the `PostCard`, such as their bio. Instead of directly assigning our `UserView` to the `author` field, we can instead spread it and add the `bio` field:
+
+```tsx
+export const PostView = view<Post>()({
+  author: {
+    ...UserView,
+    bio: true,
+  },
+  content: true,
+  id: true,
+  title: true,
+});
+```
+
+Now the `PostCard` component can access the `bio` field of the author:
+
+```tsx
+export const PostCard = ({ post: postRef }: { post: ViewRef<'Post'> }) => {
+  const post = useView(PostView, postRef);
+
+  return (
+    <Card>
+      <h2>{post.title}</h2>
+      <UserCard author={post.author} />
+      {/* Accessing the bio field */}
+      <p>{post.author.bio}</p>
+      <p>{post.content}</p>
+    </Card>
+  );
+};
+```
+
+We can also spread multiple views together. For example, if we have another view called `UserStatsView` that selects some statistics about the user, we can include it in the `PostView` like this:
+
+```tsx
+export const UserStatsView = view<User>()({
+  followerCount: true,
+  postCount: true,
+});
+
+export const PostView = view<Post>()({
+  author: {
+    ...UserView,
+    ...UserStatsView,
+    bio: true,
+  },
+  content: true,
+  id: true,
+  title: true,
+});
+```
+
+Views are opaque objects. Even if you select the same field multiple times through different views, the composed object won't have conflicting fields or result in TypeScript errors. fate automatically deduplicates fields during runtime and ensures that each field is only fetched once.
+
+## `useView` and Suspense
+
+We learned that `useRequest` is responsible for fetching data from the server and `useView` is used for reading data from the cache. In some situations data may not be available in the cache and `useView` might need to suspend the component to fetch only the missing data. Once that data is fetched and written to the cache, the component resumes rendering.
+
+_Tip: You can test this behavior in development mode with Fast Refresh (HMR) enabled in your bundler. When you edit the selection of a view, components using that view will suspend, fetch the missing data, and then resume rendering._
+
+## Type Safety and Data Masking
+
+fate provides guarantees through TypeScript and during runtime that prevent you from accessing data that wasn't selected in a component. This ensures that you declare all the data dependencies at the right level in your component tree, and prevents accidental coupling between components.
+
+In the below example, we forgot to select the `content` of a `Post`. As a result, type-checks fail and the `content` field is undefined during runtime:
+
+```tsx
+const PostView = view<Post>()({
+  id: true,
+  title: true,
+  // `content: true` is omitted.
+});
+
+const PostCard = ({ post: postRef }: { post: ViewRef<'Post'> }) => {
+  const post = useView(PostView, postRef);
+
+  return (
+    <Card>
+      <h2>{post.title}</h2>
+      {/* TypeScript errors here, and `post.content` is undefined during runtime */}
+      <p>{post.content}</p>
+    </Card>
+  );
+};
+```
+
+Views can only be resolved against refs that include that view directly or via view spreads. If a component tries to resolve a view against a ref that isn't linked, it will throw an error during runtime:
+
+```tsx
+const PostDetailView = view<Post>()({
+  content: true,
+});
+
+const AnotherPostView = view<Post>()({
+  content: true,
+});
+
+const PostView = view<Post>()({
+  id: true,
+  title: true,
+  ...AnotherPostView,
+});
+
+const PostCard = ({ post: postRef }: { post: ViewRef<'Post'> }) => {
+  const post = useView(PostView, postRef);
+  return <PostDetail post={post} />;
+};
+
+const PostDetail = ({ post: postRef }: { post: ViewRef<'Post'> }) => {
+  // This throws because the post reference passed into this component
+  // is of type `AnotherPostView`, not `PostDetailView`.
+  const post = useView(PostDetailView, postRef);
+};
+```
+
+ViewRefs carry a set of view names they can resolve. `useView` throws if a ref does not include the required view.

package/docs/guide/void-integration.md

@@ -0,0 +1,167 @@
+# Void Integration
+
+`void-fate` is the first-class [Void](https://void.cloud) adapter for fate to ease integration with the Void SDK and for deploying to the Void platform.
+
+Use this integration when your app runs on Void and you want the example app's
+setup without copying its adapter glue.
+
+## Install
+
+```sh
+pnpm add @nkzw/fate react-fate void-fate void
+```
+
+## Vite
+
+Use the regular `react-fate` Vite plugin with the Void transport:
+
+```tsx
+import { voidReact } from '@void/react/plugin';
+import { fate } from 'react-fate/vite';
+import { defineConfig } from 'vite-plus';
+import { voidPlugin } from 'void';
+
+export default defineConfig({
+  plugins: [
+    voidPlugin(),
+    voidReact(),
+    fate({
+      module: './src/fate/server.ts',
+      transport: 'void',
+    }),
+  ],
+});
+```
+
+The generated client uses `/fate` for RPC requests and `/fate-live` for live
+updates by default. In SSR, it calls the exported fate server directly. In the
+browser, it uses fetch and the SSE live endpoint.
+
+## Server Setup
+
+Create a Void live adapter with `createVoidFateLive`, pass its `live` event bus
+to `createFateServer`, and export the adapter next to your fate server.
+
+```tsx
+import { createFateServer } from '@nkzw/fate/server';
+import { createDrizzleSourceAdapter } from '@nkzw/fate/server/drizzle';
+import { createVoidFateLive } from 'void-fate/server';
+import { db } from 'void/db';
+import schema from '../db/schema.ts';
+import { createContext } from './context.ts';
+import { Root } from './views.ts';
+
+const sources = createDrizzleSourceAdapter({
+  db,
+  schema,
+  views: Root,
+});
+
+export const fateLive = createVoidFateLive();
+export const { live } = fateLive;
+
+export const fateServer = createFateServer({
+  context: ({ request }) => createContext({ request }),
+  live,
+  roots: Root,
+  sources,
+});
+```
+
+Your app can publish live updates through the normal fate live bus:
+
+```tsx
+live.update('Post', postId, { changed: ['likes'] });
+live.connection('Post.comments', { id: postId }).appendNode('Comment', commentId, {
+  node: comment,
+});
+```
+
+`changed` is optional. Void still uses generic topic fanout, while fate uses the changed field paths to refetch or write only the selected fields affected by the event.
+
+## Routes
+
+Add one route for fate RPC requests:
+
+```tsx
+// routes/fate.ts
+import { defineVoidFateRoute } from 'void-fate/server';
+import { fateLive, fateServer } from '../src/fate/server.ts';
+
+export const { GET, POST } = defineVoidFateRoute(fateServer, fateLive);
+```
+
+Add a second route for the live SSE transport:
+
+```tsx
+// routes/fate-live.ts
+import { defineVoidFateLiveRoute } from 'void-fate/server';
+import { fateLive, fateServer } from '../src/fate/server.ts';
+
+export const { GET, POST } = defineVoidFateLiveRoute(fateServer, fateLive);
+```
+
+The live route handles `GET /fate-live` SSE connections and `POST /fate-live`
+control messages. `void-fate` does not use WebSockets.
+
+## React Layout
+
+Wrap your app with `VoidFateClient` from `void-fate/react`. It creates the
+generated fate client and provides it through `react-fate`:
+
+```tsx
+import { useShared } from '@void/react';
+import type { ReactNode } from 'react';
+import { VoidFateClient } from 'void-fate/react';
+import type { SharedData } from '../src/lib/shared.ts';
+
+export default function Layout({ children }: { children: ReactNode }) {
+  const shared = useShared<SharedData>();
+  const userId = shared.auth.user?.id;
+  const origin = typeof window === 'undefined' ? shared.origin : window.location.origin;
+
+  return (
+    <VoidFateClient origin={origin} userId={userId}>
+      {children}
+    </VoidFateClient>
+  );
+}
+```
+
+`userId` is optional, but passing it lets `VoidFateClient` recreate the client
+when the signed-in user changes. Browser requests include credentials when a
+`userId` is present.
+
+## Custom Paths
+
+The default route pair is `/fate` and `/fate-live`. If your Void app uses
+different paths, configure the same values on the live adapter and client.
+
+```tsx
+export const fateLive = createVoidFateLive({
+  livePath: '/custom-fate-live',
+});
+```
+
+```tsx
+<VoidFateClient livePath="/custom-fate-live" origin={origin} rpcPath="/custom-fate" userId={userId}>
+  {children}
+</VoidFateClient>
+```
+
+The route helper does not own the route path. Make sure your Void route filename
+or router configuration matches the paths you pass to the client.
+
+## Live Transport
+
+Void can run separate request handlers for mutations and long-lived SSE
+connections. `createVoidFateLive` bridges those handlers by publishing live
+events from the request that changed data to the live route.
+
+In local development, `void-fate` uses a development token for that internal
+publish request. Outside local development, Void must provide `__VOID_PROXY_TOKEN`
+in the route environment. If no internal publish token is available, the adapter
+falls back to the in-memory live bus for the current request context.
+
+The live transport is best-effort and does not replay missed events after a
+client reconnects. This matches fate's default in-memory live event bus.

package/docs/index.md

@@ -0,0 +1,4 @@
+# @nkzw/fate Docs
+
+- [Guides](guide/getting-started.md)
+- [API Reference](api/index.md)