react-fate 1.1.0 → 1.3.0

package/docs/api/type-aliases/Pagination.md

@@ -2,7 +2,7 @@
 
 > **Pagination** = `object`
 
-Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:1086
+Defined in: packages/fate/lib/transport-BjGm\_\_3t.d.mts:1100
 
 Pagination state returned alongside connection lists.
 
@@ -12,7 +12,7 @@ Pagination state returned alongside connection lists.
 
 > **hasNext**: `boolean`
 
-Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:1087
+Defined in: packages/fate/lib/transport-BjGm\_\_3t.d.mts:1101
 
 ***
 
@@ -20,7 +20,7 @@ Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:1087
 
 > **hasPrevious**: `boolean`
 
-Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:1088
+Defined in: packages/fate/lib/transport-BjGm\_\_3t.d.mts:1102
 
 ***
 
@@ -28,7 +28,7 @@ Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:1088
 
 > `optional` **nextCursor?**: `string`
 
-Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:1089
+Defined in: packages/fate/lib/transport-BjGm\_\_3t.d.mts:1103
 
 ***
 
@@ -36,4 +36,4 @@ Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:1089
 
 > `optional` **previousCursor?**: `string`
 
-Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:1090
+Defined in: packages/fate/lib/transport-BjGm\_\_3t.d.mts:1104

package/docs/api/type-aliases/ViewRef.md

@@ -2,7 +2,7 @@
 
 > **ViewRef**\<`TName`\> = `Readonly`\<\{ `__typename`: `TName`; `[ViewsTag]`: `Set`\<`string`\>; `id`: `string` \| `number`; \}\>
 
-Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:1068
+Defined in: packages/fate/lib/transport-BjGm\_\_3t.d.mts:1082
 
 Reference to a normalized entity instance that can be resolved against one or more view tags.
 

package/docs/api/variables/toEntityId.md

@@ -2,7 +2,7 @@
 
 > `const` **toEntityId**: (`type`, `rawId`) => `EntityId`
 
-Defined in: packages/fate/lib/index.d.mts:76
+Defined in: packages/fate/lib/index.d.mts:81
 
 Builds the canonical cache ID for an entity.
 

package/docs/guide/actions.md

@@ -7,9 +7,9 @@ fate does not provide hooks for mutations like traditional data fetching librari
 
 Server mutations are exposed automatically as actions and mutations by fate's Vite plugin. The transport determines where those mutations are declared:
 
-- With the [native HTTP transport](server-integration.md#native-fate-protocol), mutations come from the `mutations` object passed to `createFateServer`.
-- With the [tRPC adapter](server-integration.md#trpc-fate-setup), mutations come from tRPC mutation procedures exposed through your fate-enabled router.
-- With [Void](void-integration.md), mutations use the same native fate server shape and are exposed through the Void route helpers.
+- With the [native HTTP transport](../integrations/server.md#native-fate-protocol), mutations come from the `mutations` object passed to `createFateServer`.
+- With the [tRPC adapter](../integrations/server.md#trpc-fate-setup), mutations come from tRPC mutation procedures exposed through your fate-enabled router.
+- With [Void](../integrations/void.md), mutations use the same native fate server shape and are exposed through the Void route helpers.
 
 If you have a mutation named `post.like`, a `LikeButton` component using fate Actions and an async component library could look like this:
 
@@ -148,9 +148,9 @@ You can call mutations from anywhere, and without waiting for previous mutations
 
 fate Actions & Mutations are backed by regular server mutations. If you already know how your fate server is wired, the client-side API above is the same regardless of transport. If not, start with the server setup for your environment:
 
-- [Native HTTP custom mutations](server-integration.md#custom-mutations) use `createFateServer({ mutations })`.
-- [tRPC fate setup](server-integration.md#trpc-fate-setup) wires fate into your tRPC router; custom writes can use the same `fate.createPlan` and `fate.resolveById` helpers shown there.
-- [Void integration](void-integration.md) exposes a native fate server from Void routes; define mutations with the native `createFateServer({ mutations })` API and serve them through `defineVoidFateRoute`.
+- [Native HTTP custom mutations](../integrations/server.md#custom-mutations) use `createFateServer({ mutations })`.
+- [tRPC fate setup](../integrations/server.md#trpc-fate-setup) wires fate into your tRPC router; custom writes can use the same `fate.createPlan` and `fate.resolveById` helpers shown there.
+- [Void integration](../integrations/void.md) exposes a native fate server from Void routes; define mutations with the native `createFateServer({ mutations })` API and serve them through `defineVoidFateRoute`.
 
 Here is a native HTTP mutation for `post.like`:
 
@@ -223,7 +223,7 @@ export const postRouter = router({
 });
 ```
 
-See [Server Integration](server-integration.md) for complete native HTTP and tRPC setup examples, and [Void Integration](void-integration.md) for route helpers when your app runs on Void.
+See [Server Integration](../integrations/server.md) for complete native HTTP and tRPC setup examples, and [Void Integration](../integrations/void.md) for route helpers when your app runs on Void.
 
 ## Action & Mutation Error Handling
 

package/docs/guide/deferred-views.md

@@ -0,0 +1,62 @@
+# Deferred Views
+
+Use `defer` when a field should not block the parent view. The parent view receives a deferred handle immediately after the eager fields are available, and the component that reads that handle with `useView`, `useListView`, or `useLiveListView` decides which `Suspense` boundary handles the loading state.
+
+```tsx
+import { Suspense } from 'react';
+import { defer, useListView, useView, view, Deferred, ViewRef } from 'react-fate';
+
+const CommentView = view<Comment>()({
+  content: true,
+  id: true,
+});
+
+const CommentConnectionView = {
+  args: { first: 3 },
+  items: { node: CommentView },
+};
+
+const PostView = view<Post>()({
+  comments: defer(CommentConnectionView),
+  content: true,
+  id: true,
+  title: true,
+});
+
+function PostCard({ post: postRef }: { post: ViewRef<'Post'> }) {
+  const post = useView(PostView, postRef);
+
+  return (
+    <article>
+      <h2>{post.title}</h2>
+      <p>{post.content}</p>
+      <Suspense fallback={<CommentsSkeleton />}>
+        <PostComments comments={post.comments} />
+      </Suspense>
+    </article>
+  );
+}
+
+function PostComments({
+  comments,
+}: {
+  comments: Deferred<{ items: ReadonlyArray<{ node: ViewRef<'Comment'> }> }>;
+}) {
+  const [items, loadNext] = useListView(CommentConnectionView, comments);
+
+  return (
+    <section>
+      {items.map(({ node }) => (
+        <CommentCard comment={node} key={node.id} />
+      ))}
+      {loadNext ? <button onClick={loadNext}>Load more</button> : null}
+    </section>
+  );
+}
+```
+
+Deferred fields are not optional data. They are explicit handles that existing view APIs can read. If the deferred selection is missing from the normalized cache, fate fetches only that missing selection and suspends the component that tried to resolve it.
+
+This keeps parent components simple: eager fields like `title` and `content` are available when `useView(PostView, postRef)` returns, while slower or secondary fields such as `comments` can load under their own boundary.
+
+GraphQL transports use the same client semantics today. The deferred field is omitted from the eager request and fetched when the deferred handle is resolved. GraphQL `@defer` is the natural transport representation for this feature, but consuming incremental multipart patches requires additional transport support before fate can safely normalize streamed patches from a single GraphQL response.

package/docs/guide/getting-started.md

@@ -8,11 +8,11 @@ Create a new fate app with Vite+:
 vp create fate my-app
 ```
 
-The template selector can create a Void app with Drizzle, a tRPC app with Drizzle or Prisma, a GraphQL app with Prisma, or a fate client for an existing GraphQL server. 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.
+The template selector can create a React or Vue client for a Void app with Drizzle, a tRPC app with Drizzle or Prisma, a GraphQL app with Prisma, or a fate client for an existing GraphQL server. React is the default UI framework; pass `--framework vue` or choose Vue in the template selector to create a Vue app. 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`:
+For a React client, install `react-fate`. It requires React 19.2+:
 
 ::: code-group
 
@@ -30,7 +30,25 @@ 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:
+For a Vue client, install `vue-fate`:
+
+::: code-group
+
+```bash [npm]
+npm add vue-fate
+```
+
+```bash [pnpm]
+pnpm add vue-fate
+```
+
+```bash [yarn]
+yarn add vue-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 a framework adapter:
 
 ::: code-group
 

package/docs/guide/vue.md

@@ -0,0 +1,256 @@
+# Vue
+
+_fate_ also supports Vue through `vue-fate`. It exports the same core primitives as `react-fate` where Vue has a natural equivalent: `view`, `useRequest`, `useView`, `useListView`, `useLiveView`, `useLiveListView`, `useFateClient`, and the `FateClient` provider.
+
+Vue components use fate through Vue resources built from refs, computed values, watchers, and `<Suspense>`. The view model, generated client, normalized cache, masking, request shapes, list views, live views, and mutations are shared with the React adapter.
+
+## Installation
+
+Install `vue-fate` in your Vue client:
+
+::: code-group
+
+```bash [npm]
+npm add vue-fate
+```
+
+```bash [pnpm]
+pnpm add vue-fate
+```
+
+```bash [yarn]
+yarn add vue-fate
+```
+
+:::
+
+If your server lives in a separate package, install `@nkzw/fate` there as a runtime dependency too.
+
+## Vite Plugin
+
+Use the Vue adapter's Vite plugin in the client app:
+
+```ts
+import { fate } from 'vue-fate/vite';
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    fate({
+      module: '@your-org/server/fate.ts',
+      transport: 'native',
+    }),
+  ],
+});
+```
+
+The plugin generates `vue-fate/client`, which contains the typed `createFateClient` helper for your app. The `module` and `transport` options are the same options used by the React adapter.
+
+## Providing the Client
+
+Create a client with `createFateClient` and provide it with `FateClient`:
+
+```vue
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { FateClient } from 'vue-fate';
+import { createFateClient } from 'vue-fate/client';
+import AppRoutes from './AppRoutes.vue';
+
+const token = ref<string | null>(null);
+
+const fate = computed(() =>
+  createFateClient({
+    headers: () => ({
+      authorization: token.value ? `Bearer ${token.value}` : '',
+    }),
+    url: '/fate',
+  }),
+);
+</script>
+
+<template>
+  <FateClient :client="fate">
+    <Suspense>
+      <AppRoutes />
+    </Suspense>
+  </FateClient>
+</template>
+```
+
+The `client` prop accepts a plain client, a ref, a computed value, or a getter. Descendants always read the current client, so switching credentials, endpoints, or transports does not require remounting the provider.
+
+You can also install the client as a Vue plugin:
+
+```ts
+import { createApp } from 'vue';
+import { createFatePlugin } from 'vue-fate';
+import { createFateClient } from 'vue-fate/client';
+import App from './App.vue';
+
+const fate = createFateClient({ url: '/fate' });
+
+createApp(App).use(createFatePlugin(fate)).mount('#app');
+```
+
+## Defining Views
+
+Views are plain TypeScript values and can live anywhere. In Vue apps, it is usually best to define shared views in `.ts` modules and import them from single-file components:
+
+```ts
+import type { Post, User } from '@your-org/server/views';
+import { view } from 'vue-fate';
+
+export const UserView = view<User>()({
+  id: true,
+  name: true,
+  username: true,
+});
+
+export const PostView = view<Post>()({
+  author: UserView,
+  id: true,
+  title: true,
+});
+```
+
+Vue can import values across components, but single-file components have one default component export. Keeping reusable views in `.ts` files avoids coupling your data model to component files and makes view composition straightforward.
+
+## Requests
+
+`useRequest` declares the data a route, page, or component tree needs. It returns a resource with `data`, `pending`, `error`, `ready`, `refresh`, and `dispose`:
+
+```vue
+<script setup lang="ts">
+import { useListView, useRequest } from 'vue-fate';
+import { PostCardView } from '../fateViews';
+import PostCard from '../ui/PostCard.vue';
+
+const request = useRequest({
+  posts: {
+    args: { first: 20 },
+    list: PostCardView,
+  },
+});
+
+const { posts } = await request.ready();
+const [postItems, loadNext] = useListView(PostCardView, posts);
+</script>
+
+<template>
+  <PostCard v-for="{ node } in postItems" :key="node.id" :post="node" />
+  <button v-if="loadNext" @click="loadNext()">Load more</button>
+</template>
+```
+
+Awaiting `ready()` in `<script setup>` participates in Vue Suspense. If you do not await it, read `request.data.value`, `request.pending.value`, and `request.error.value` in script, or use the refs directly in templates.
+
+## Views in Components
+
+Use `useView` to read a `ViewRef` from the normalized cache and subscribe to updates for the selected fields:
+
+```vue
+<script setup lang="ts">
+import type { ViewRef } from 'vue-fate';
+import { useView } from 'vue-fate';
+import { PostCardView, UserView } from '../fateViews';
+import UserCard from './UserCard.vue';
+
+const props = defineProps<{
+  post: ViewRef<'Post'>;
+}>();
+
+const post = useView(PostCardView, () => props.post);
+const author = useView(UserView, () => post.value?.author ?? null);
+</script>
+
+<template>
+  <article v-if="post">
+    <h2>{{ post.title }}</h2>
+    <UserCard v-if="author" :user="author" />
+  </article>
+</template>
+```
+
+Pass reactive props through a getter so fate tracks prop changes. In script, resources are refs and need `.value`. In templates, Vue unwraps them automatically.
+
+## Lists and Live Views
+
+`useListView` subscribes to a connection returned from `useRequest` or from a nested view field:
+
+```ts
+const [comments, loadNextCommentPage] = useListView(CommentView, () => post.value?.comments);
+```
+
+`useLiveView` and `useLiveListView` have the same resource shape as `useView` and `useListView`, but they also subscribe to server-pushed updates when the selected transport supports live views:
+
+```ts
+const post = useLiveView(PostCardView, () => props.post);
+const [comments] = useLiveListView(CommentView, () => post.value?.comments);
+```
+
+Manual cleanup works through `dispose()`:
+
+```ts
+const post = useLiveView(PostCardView, () => props.post);
+
+onBeforeUnmount(() => {
+  post.dispose();
+});
+```
+
+Vue scope disposal also cleans up resources automatically.
+
+## Mutations
+
+Use `useFateClient` to access generated mutations:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useFateClient } from 'vue-fate';
+
+const props = defineProps<{
+  post: { id: string; likes: number };
+}>();
+
+const fate = useFateClient();
+const pending = ref(false);
+const error = ref<unknown>(null);
+
+const like = async () => {
+  pending.value = true;
+  error.value = null;
+
+  try {
+    await fate.mutations.post.like({
+      input: { id: props.post.id },
+      optimistic: { likes: props.post.likes + 1 },
+    });
+  } catch (caughtError) {
+    error.value = caughtError;
+  } finally {
+    pending.value = false;
+  }
+};
+</script>
+
+<template>
+  <button :disabled="pending" @click="like">Like</button>
+</template>
+```
+
+The mutation call shape is the same as `react-fate`: `input`, `optimistic`, `insert`, and `view` work the same way. Vue does not have React Actions or `useActionState`, so Vue components should model pending and error state with Vue refs or your application state library.
+
+## API Differences from React
+
+The names intentionally mirror `react-fate` where Vue has an equivalent API. The main differences are Vue framework differences:
+
+- `useRequest`, `useView`, and list hooks return Vue resources instead of throwing promises from render.
+- Async setup and `<Suspense>` replace React's async component model.
+- Mutations use `fate.mutations` directly; React-only `fate.actions` and `useActionState` patterns do not apply.
+- Shared views are best kept in `.ts` modules instead of exporting named views from component files.
+
+The generated client, server integrations, cache behavior, masking, pagination, optimistic updates, and live transport behavior are shared across adapters.

package/docs/index.md

@@ -1,4 +1,5 @@
 # react-fate Docs
 
 - [Guides](guide/getting-started.md)
+- [Integrations](integrations/server.md)
 - [API Reference](api/index.md)

package/docs/integrations/cloudflare.md

@@ -0,0 +1,143 @@
+# Cloudflare Integration
+
+`cf-fate` is the first-class Cloudflare Workers adapter for Fate native HTTP transport and live views.
+
+Use it when your backend runs directly on Cloudflare Workers and you want fate live views without adopting the Void platform.
+
+## Install
+
+```sh
+pnpm add @nkzw/fate react-fate cf-fate drizzle-orm
+pnpm add -D wrangler
+```
+
+## Server Setup
+
+Create a Cloudflare live stream and pass its Fate live facade to `createFateServer`.
+
+```ts
+// src/fate/live.ts
+import { defineCloudflareFateLiveStream } from 'cf-fate/server';
+
+export const fateStream = defineCloudflareFateLiveStream({
+  allowAnonymousControl: true,
+  binding: 'FATE_LIVE',
+  id: 'fate',
+});
+```
+
+```ts
+// src/fate/server.ts
+import { createFateServer } from '@nkzw/fate/server';
+import { createCloudflareFateLive } from 'cf-fate/server';
+
+export const fateLive = createCloudflareFateLive();
+export const { live } = fateLive;
+
+export const fateServer = createFateServer({
+  live,
+  // context,
+  // roots,
+  // sources,
+});
+```
+
+Publish from mutations through the normal Fate live bus:
+
+```ts
+live.update('Post', postId, { changed: ['likes'] });
+live.connection('Post.comments', { id: postId }).appendNode('Comment', commentId);
+```
+
+## Worker Routes
+
+Expose one route for Fate RPC and one route for the SSE live stream.
+
+```ts
+import {
+  createCloudflareFateLiveDurableObject,
+  defineCloudflareFateLiveRoute,
+  defineCloudflareFateRoute,
+} from 'cf-fate/server';
+import { fateStream } from './fate/live';
+import { fateLive, fateServer } from './fate/server';
+
+const fateRoute = defineCloudflareFateRoute(fateServer, fateLive, { stream: fateStream });
+const fateLiveRoute = defineCloudflareFateLiveRoute(fateStream);
+
+export const FateLiveDurableObject = createCloudflareFateLiveDurableObject({
+  binding: 'FATE_LIVE',
+});
+
+export default {
+  fetch(request, env, ctx) {
+    const url = new URL(request.url);
+    if (url.pathname === '/fate') {
+      return fateRoute.fetch(request, env, ctx);
+    }
+    if (url.pathname === '/fate-live') {
+      return fateLiveRoute.fetch(request, env, ctx);
+    }
+    return new Response('Not Found', { status: 404 });
+  },
+};
+```
+
+## Wrangler
+
+Add a Durable Object binding and migration. `cf-fate` uses `node:async_hooks`, so the Worker must enable Node compatibility.
+
+```jsonc
+{
+  "compatibility_flags": ["nodejs_compat"],
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "FATE_LIVE",
+        "class_name": "FateLiveDurableObject",
+      },
+    ],
+  },
+  "migrations": [
+    {
+      "tag": "fate-live-v1",
+      "new_sqlite_classes": ["FateLiveDurableObject"],
+    },
+  ],
+}
+```
+
+## Client
+
+Use the Cloudflare transport in the Fate Vite plugin:
+
+```ts
+import { fate } from 'react-fate/vite';
+
+fate({
+  module: './src/fate/server.ts',
+  transport: 'cloudflare',
+});
+```
+
+Then point the generated client at the Worker endpoints:
+
+```tsx
+import { FateClient } from 'react-fate';
+import { createFateClient } from 'react-fate/client';
+
+const fate = createFateClient({
+  liveUrl: 'http://localhost:8787/fate-live',
+  url: 'http://localhost:8787/fate',
+});
+
+export function App({ children }) {
+  return <FateClient client={fate}>{children}</FateClient>;
+}
+```
+
+## Semantics
+
+`cf-fate` uses one browser `EventSource` per Fate client and multiplexes entity and connection topics over that stream. Durable Objects keep connection and topic subscription state so later requests, mutations, scheduled handlers, and queue consumers can publish to already-connected clients.
+
+Delivery is at-most-once. Events are ordered within one topic, but events are not durably replayed after a disconnect. Use authoritative refetching or application-owned replay storage if missed events must be recovered.