@nkzw/fate 1.0.3 → 1.2.0

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 @@
 # @nkzw/fate Docs
 
 - [Guides](guide/getting-started.md)
+- [Integrations](integrations/server.md)
 - [API Reference](api/index.md)

package/docs/integrations/graphql.md

@@ -0,0 +1,345 @@
+# GraphQL Integration
+
+_fate_ can use an existing GraphQL API as its transport. This keeps the adapter APIs, view composition, normalized cache, masking, requests, list views, live views, and mutations the same while replacing the native or tRPC backend with GraphQL operations.
+
+Use the GraphQL transport when your backend already exposes GraphQL and you want fate's client model without adding fate's native server protocol.
+
+## Template
+
+Create a client for an existing GraphQL server with:
+
+```bash
+vp create fate my-app --template graphql-client
+```
+
+Create a full GraphQL + Prisma example app with:
+
+```bash
+vp create fate my-app --template graphql
+```
+
+The client-only template is the smallest reference for the integration. It contains a `src/fate/graphql.ts` file that maps your GraphQL schema to fate views and roots.
+
+## GraphQL Schema Shape
+
+The GraphQL transport expects a schema with Relay-style object identity and pagination:
+
+- Entity objects include `id` and `__typename`.
+- Object fetches go through a `nodes(ids:)` field.
+- List fields return Relay connections with `edges`, `cursor`, `node`, and `pageInfo`.
+- Root queries and mutations return the entity type selected by the fate view.
+
+For example, a `Post` list can be exposed as a normal GraphQL connection:
+
+```graphql
+type Query {
+  posts(first: Int, after: String): PostConnection!
+  viewer: User
+  nodes(ids: [ID!]!): [Node]!
+}
+
+type PostConnection {
+  edges: [PostEdge!]!
+  pageInfo: PageInfo!
+}
+```
+
+If your schema uses different root field names, keep the fate names you want on the client and map them with `fateGraphQL.roots`.
+
+## Mapping Your Schema
+
+Create a module that exports data views, `Root`, and an optional `fateGraphQL` config. The Vite plugin reads this module during development and build time, generates the client wiring, and leaves your runtime GraphQL server unchanged.
+
+```tsx
+import { graphqlMutation } from '@nkzw/fate';
+import { dataView, list, type Entity } from '@nkzw/fate/server';
+
+type GraphQLUser = {
+  id: string;
+  name?: string | null;
+  username?: string | null;
+};
+
+type GraphQLPost = {
+  author?: GraphQLUser | null;
+  id: string;
+  title: string;
+};
+
+export const userDataView = dataView<GraphQLUser>('User')({
+  id: true,
+  name: true,
+  username: true,
+});
+
+export const postDataView = dataView<GraphQLPost>('Post')({
+  author: userDataView,
+  id: true,
+  title: true,
+});
+
+export type User = Entity<typeof userDataView, 'User'>;
+export type Post = Entity<
+  typeof postDataView,
+  'Post',
+  {
+    author: User | null;
+  }
+>;
+
+export const Root = {
+  posts: list(postDataView),
+  viewer: userDataView,
+};
+
+export const fateGraphQL = {
+  roots: {
+    posts: { field: 'posts' },
+    viewer: { field: 'viewer' },
+  },
+} as const;
+```
+
+The data views describe the fields client components are allowed to select. `Root` describes the root operations available to `useRequest`. `fateGraphQL.roots` maps those root names to actual GraphQL fields. If the GraphQL field has the same name as the fate root, the `field` entry can be omitted.
+
+## Vite Plugin
+
+Configure the fate Vite plugin with the GraphQL transport and point it at the mapping module:
+
+::: code-group
+
+```tsx [React]
+import { fate } from 'react-fate/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    fate({
+      module: './src/fate/graphql.ts',
+      transport: 'graphql',
+    }),
+  ],
+});
+```
+
+```ts [Vue]
+import vue from '@vitejs/plugin-vue';
+import { fate } from 'vue-fate/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    fate({
+      module: './src/fate/graphql.ts',
+      transport: 'graphql',
+    }),
+  ],
+});
+```
+
+:::
+
+The plugin generates a typed `createFateClient` helper from your views, roots, and GraphQL mapping. It also watches the mapping module and the files it imports during development.
+
+## Creating a Client
+
+Create the client with your GraphQL endpoint and provide it through the `FateClient` provider:
+
+::: code-group
+
+```tsx [React]
+import { FateClient } from 'react-fate';
+import { createFateClient } from 'react-fate/client';
+
+const fate = createFateClient({
+  headers: () => ({
+    authorization: `Bearer ${token}`,
+  }),
+  url: 'https://api.example.com/graphql',
+});
+
+export function App() {
+  return <FateClient client={fate}>{/* Components go here */}</FateClient>;
+}
+```
+
+```vue [Vue]
+<script setup lang="ts">
+import { FateClient } from 'vue-fate';
+import { createFateClient } from 'vue-fate/client';
+import AppRoutes from './AppRoutes.vue';
+
+const fate = createFateClient({
+  headers: () => ({
+    authorization: `Bearer ${token}`,
+  }),
+  url: 'https://api.example.com/graphql',
+});
+</script>
+
+<template>
+  <FateClient :client="fate">
+    <AppRoutes />
+  </FateClient>
+</template>
+```
+
+:::
+
+Use `fetch` when you need to customize credentials or reuse an application fetch wrapper:
+
+```tsx
+const fate = createFateClient({
+  fetch: (input, init) =>
+    fetch(input, {
+      ...init,
+      credentials: 'include',
+    }),
+  url: `${env('SERVER_URL')}/graphql`,
+});
+```
+
+GraphQL operations issued in the same microtask are batched into a single GraphQL query or mutation document with aliased fields.
+
+Deferred view fields work with the GraphQL transport through the same normalized cache flow as native HTTP: the eager query omits `defer(...)` fields, and `useView`, `useListView`, or `useLiveListView` fetches the missing selection through `nodes(ids:)` when the deferred handle is read. GraphQL `@defer` is the natural wire format for this feature, but fate's GraphQL transport currently expects one JSON result per operation and does not consume incremental multipart patches yet.
+
+## Object IDs
+
+The transport converts between fate entity IDs and GraphQL node IDs. By default, it sends IDs as `${type}-${id}` and strips that prefix from returned IDs. Override this if your schema uses Relay global IDs, raw database IDs, or another encoding:
+
+```tsx
+const fate = createFateClient({
+  decodeNodeId: (type, id) => {
+    const [nodeType, nodeId] = atob(String(id)).split(':');
+    if (nodeType !== type) {
+      throw new Error(`Expected a ${type} node id.`);
+    }
+    return nodeId;
+  },
+  encodeNodeId: (type, id) => btoa(`${type}:${id}`),
+  url: '/graphql',
+});
+```
+
+If your GraphQL API already accepts and returns the same IDs you use in the app, return `id` from both functions.
+
+## Requests and Arguments
+
+Client code keeps using `useRequest` with the same shape as the other transports:
+
+```tsx
+const { posts, viewer } = useRequest({
+  posts: {
+    args: { first: 10 },
+    list: PostView,
+  },
+  viewer: { view: UserView },
+});
+```
+
+Root arguments are sent to the root GraphQL field. Nested relation arguments are scoped by relation name:
+
+```tsx
+const { posts } = useRequest({
+  posts: {
+    args: {
+      comments: { first: 3 },
+      first: 10,
+    },
+    list: PostWithCommentsView,
+  },
+});
+```
+
+This produces a root `posts(first: 10)` field and a nested `comments(first: 3)` field in the generated GraphQL selection.
+
+## Mutations
+
+Map fate mutation names to GraphQL mutation fields with `graphqlMutation`:
+
+```tsx
+export const fateGraphQL = {
+  mutations: {
+    'post.like': graphqlMutation<Post, { id: string }, Post>('Post', {
+      field: 'postLike',
+    }),
+  },
+  roots: {
+    posts: { field: 'posts' },
+  },
+} as const;
+```
+
+By default, the input is sent as an `input` argument:
+
+```graphql
+mutation {
+  postLike(input: { id: "12" }) {
+    id
+    likes
+  }
+}
+```
+
+Use `inputArg` when your schema uses a different argument name, or `inputArg: false` when the input object should be spread into field arguments:
+
+```tsx
+export const fateGraphQL = {
+  mutations: {
+    'post.like': graphqlMutation<Post, { id: string }, Post>('Post', {
+      field: 'likePost',
+      inputArg: 'payload',
+    }),
+    'user.follow': graphqlMutation<User, { id: string }, User>('User', {
+      field: 'followUser',
+      inputArg: false,
+    }),
+  },
+} as const;
+```
+
+Mutations use the same `mutation(...)` API described in the [Actions Guide](../guide/actions.md). React clients can also expose those mutations as Actions for `useActionState`.
+
+## Live Views
+
+GraphQL live views use [GraphQL SSE](https://github.com/enisdenjo/graphql-sse). Install `graphql-sse` in the client package and leave `live` enabled, or pass `live: false` when your schema does not support subscriptions.
+
+```tsx
+const fate = createFateClient({
+  live: {
+    url: 'https://api.example.com/graphql/stream',
+  },
+  url: 'https://api.example.com/graphql',
+});
+```
+
+The default subscription fields are `fateLiveNode` for `useLiveView` and `fateLiveConnection` for `useLiveListView`. Rename them with `entityField` and `connectionField`:
+
+```tsx
+const fate = createFateClient({
+  live: {
+    connectionField: 'liveConnection',
+    entityField: 'liveNode',
+    url: '/graphql/stream',
+  },
+  url: '/graphql',
+});
+```
+
+The live node subscription returns `{ data, delete, id, select }`. The live connection subscription returns events such as `appendNode`, `prependNode`, `deleteEdge`, and `invalidate`. These payloads match fate's live transport events, so the cache update behavior is the same as the native transport.
+
+If you do not need live views, disable them explicitly:
+
+```tsx
+const fate = createFateClient({
+  live: false,
+  url: '/graphql',
+});
+```
+
+## Existing Servers
+
+The GraphQL transport is intentionally a mapping layer. It does not require `createFateServer`, the Prisma adapter, or the Drizzle adapter. Your GraphQL server remains responsible for authorization, validation, resolver behavior, cursor pagination, and mutation side effects.
+
+Use data views to expose only the fields the client should be able to select, keep GraphQL schema authorization in your server, and treat `src/fate/graphql.ts` as the contract between your GraphQL API and fate's client.