react-fate 1.0.2 → 1.1.0

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

@@ -0,0 +1,19 @@
+# Type Alias: GraphQLMutationDefinition\<T, Input, Output\>
+
+> **GraphQLMutationDefinition**\<`T`, `Input`, `Output`\> = `Readonly`\<\{ `__fateGraphQLMutation?`: \{ `input`: `Input`; `output`: `Output`; \}; `entity`: `T`\[`"__typename"`\]; `field`: `string`; `inputArg?`: `false` \| `string`; \}\>
+
+Defined in: packages/fate/lib/graphqlTransport-DbRHbYtb.d.mts:20
+
+## Type Parameters
+
+### T
+
+`T` *extends* `Entity` = `Entity`
+
+### Input
+
+`Input` = `unknown`
+
+### Output
+
+`Output` = `unknown`

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

@@ -0,0 +1,11 @@
+# Type Alias: GraphQLMutationInput\<Definition\>
+
+> **GraphQLMutationInput**\<`Definition`\> = `Definition` *extends* [`GraphQLMutationDefinition`](GraphQLMutationDefinition.md)\<`any`, infer Input, `any`\> ? `Input` : `never`
+
+Defined in: packages/fate/lib/graphqlTransport-DbRHbYtb.d.mts:29
+
+## Type Parameters
+
+### Definition
+
+`Definition`

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

@@ -0,0 +1,11 @@
+# Type Alias: GraphQLMutationMap\<Mutations\>
+
+> **GraphQLMutationMap**\<`Mutations`\> = `Mutations` *extends* `Record`\<`string`, [`GraphQLMutationDefinition`](GraphQLMutationDefinition.md)\> ? `{ [K in keyof Mutations]: { input: GraphQLMutationInput<Mutations[K]>; output: GraphQLMutationOutput<Mutations[K]> } }` : `EmptyTransportMutations`
+
+Defined in: packages/fate/lib/graphqlTransport-DbRHbYtb.d.mts:31
+
+## Type Parameters
+
+### Mutations
+
+`Mutations`

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

@@ -0,0 +1,11 @@
+# Type Alias: GraphQLMutationOutput\<Definition\>
+
+> **GraphQLMutationOutput**\<`Definition`\> = `Definition` *extends* [`GraphQLMutationDefinition`](GraphQLMutationDefinition.md)\<`any`, `any`, infer Output\> ? `Output` : `never`
+
+Defined in: packages/fate/lib/graphqlTransport-DbRHbYtb.d.mts:30
+
+## Type Parameters
+
+### Definition
+
+`Definition`

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

@@ -0,0 +1,119 @@
+# Type Alias: GraphQLTransportOptions\<Mutations\>
+
+> **GraphQLTransportOptions**\<`Mutations`\> = `object`
+
+Defined in: packages/fate/lib/graphqlTransport-DbRHbYtb.d.mts:46
+
+## Type Parameters
+
+### Mutations
+
+`Mutations` *extends* `TransportMutations` = `EmptyTransportMutations`
+
+## Properties
+
+### decodeNodeId?
+
+> `optional` **decodeNodeId?**: (`type`, `id`) => `string` \| `number`
+
+Defined in: packages/fate/lib/graphqlTransport-DbRHbYtb.d.mts:47
+
+#### Parameters
+
+##### type
+
+`string`
+
+##### id
+
+`string` \| `number`
+
+#### Returns
+
+`string` \| `number`
+
+***
+
+### encodeNodeId?
+
+> `optional` **encodeNodeId?**: (`type`, `id`) => `string` \| `number`
+
+Defined in: packages/fate/lib/graphqlTransport-DbRHbYtb.d.mts:48
+
+#### Parameters
+
+##### type
+
+`string`
+
+##### id
+
+`string` \| `number`
+
+#### Returns
+
+`string` \| `number`
+
+***
+
+### eventSource?
+
+> `optional` **eventSource?**: `EventSourceConstructor`
+
+Defined in: packages/fate/lib/graphqlTransport-DbRHbYtb.d.mts:49
+
+***
+
+### fetch?
+
+> `optional` **fetch?**: `FetchLike`
+
+Defined in: packages/fate/lib/graphqlTransport-DbRHbYtb.d.mts:50
+
+***
+
+### headers?
+
+> `optional` **headers?**: `HeadersFactory`
+
+Defined in: packages/fate/lib/graphqlTransport-DbRHbYtb.d.mts:51
+
+***
+
+### live?
+
+> `optional` **live?**: `boolean` \| `GraphQLLiveOptions`
+
+Defined in: packages/fate/lib/graphqlTransport-DbRHbYtb.d.mts:52
+
+***
+
+### mutations?
+
+> `optional` **mutations?**: `Record`\<`Extract`\<keyof `Mutations`, `string`\>, `GraphQLMutationRuntimeConfig`\>
+
+Defined in: packages/fate/lib/graphqlTransport-DbRHbYtb.d.mts:53
+
+***
+
+### roots?
+
+> `optional` **roots?**: `Record`\<`string`, `GraphQLRootConfig`\>
+
+Defined in: packages/fate/lib/graphqlTransport-DbRHbYtb.d.mts:54
+
+***
+
+### types
+
+> **types**: `ReadonlyArray`\<`Omit`\<`TypeConfig`, `"getId"`\> & `Partial`\<`Pick`\<`TypeConfig`, `"getId"`\>\>\>
+
+Defined in: packages/fate/lib/graphqlTransport-DbRHbYtb.d.mts:55
+
+***
+
+### url
+
+> **url**: `string` \| `URL`
+
+Defined in: packages/fate/lib/graphqlTransport-DbRHbYtb.d.mts:56

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

@@ -0,0 +1,7 @@
+# Type Alias: HydrateOptions
+
+> **HydrateOptions** = `Readonly`\<\{ `merge?`: `"preserve-existing"` \| `"replace"`; \}\>
+
+Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:692
+
+Controls how `FateClient.hydrate()` reconciles a snapshot with browser cache state.

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

@@ -0,0 +1,7 @@
+# Type Alias: HydrationLimits
+
+> **HydrationLimits** = `Readonly`\<\{ `maxCollectionLength`: `number`; `maxNodes`: `number`; `maxStringLength`: `number`; \}\>
+
+Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:702
+
+Resource limits applied while encoding and decoding hydration snapshots.

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

@@ -2,7 +2,7 @@
 
 > **InferFateAPI**\<`Server`\> = `Server` *extends* `object` ? `API` : `never`
 
-Defined in: packages/fate/lib/record-CirbfZWX.d.mts:207
+Defined in: packages/fate/lib/record-BtdKzEGI.d.mts:207
 
 ## Type Parameters
 

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

@@ -0,0 +1,39 @@
+# Type Alias: Pagination
+
+> **Pagination** = `object`
+
+Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:1086
+
+Pagination state returned alongside connection lists.
+
+## Properties
+
+### hasNext
+
+> **hasNext**: `boolean`
+
+Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:1087
+
+***
+
+### hasPrevious
+
+> **hasPrevious**: `boolean`
+
+Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:1088
+
+***
+
+### nextCursor?
+
+> `optional` **nextCursor?**: `string`
+
+Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:1089
+
+***
+
+### previousCursor?
+
+> `optional` **previousCursor?**: `string`
+
+Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:1090

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/types-Dz46PXr3.d.mts:1107
+Defined in: packages/fate/lib/transport-BTgtSwOM.d.mts:1068
 
 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:75
+Defined in: packages/fate/lib/index.d.mts:76
 
 Builds the canonical cache ID for an entity.
 

package/docs/guide/getting-started.md

@@ -8,7 +8,7 @@ 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 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.
+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.
 
 ## Manual Installation
 

package/docs/guide/graphql-integration.md

@@ -0,0 +1,298 @@
+# GraphQL Integration
+
+_fate_ can use an existing GraphQL API as its transport. This keeps the React APIs, view composition, normalized cache, masking, requests, list views, live views, and actions 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 React 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:
+
+```tsx
+import { fate } from 'react-fate/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    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:
+
+```tsx
+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>;
+}
+```
+
+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.
+
+## 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;
+```
+
+Actions use the same `mutation(...)` and `useActionState` APIs described in the [Actions Guide](actions.md).
+
+## 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 React client.

package/docs/guide/requests.md

@@ -128,3 +128,55 @@ try {
 ```
 
 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.
+
+## SSR and Hydration
+
+Create a request-scoped fate client on the server, preload the route data, and dehydrate its normalized cache:
+
+```tsx
+const fate = createFateClient();
+await fate.request({ post: { id: '12', view: PostView } });
+
+return {
+  fate: fate.dehydrate(),
+};
+```
+
+Transport the returned value through your framework's loader serialization, React Server Component props, or a safely escaped JSON bootstrap script. The snapshot contains plain serializable values, so serializers such as Seroval can carry it without fate-specific integration. Treat the snapshot as opaque: hydrate it through fate rather than reading or editing its internal data.
+
+On the browser, hydrate the new client before rendering components that call `useRequest`:
+
+```tsx
+const fate = createFateClient();
+fate.hydrate(loaderData.fate);
+
+hydrateRoot(
+  document,
+  <FateClient client={fate}>
+    <App />
+  </FateClient>,
+);
+```
+
+Hydrated `cache-first` requests resolve from the normalized cache without refetching. Hydration restores records, selected-field coverage, root queries, and list pagination state. It intentionally does not restore active requests, subscriptions, retainers, timers, or optimistic mutation state.
+
+Snapshots carry a hydration scope and are rejected by clients with a different scope. Generated clients set a stable scope automatically. When constructing a client directly, pass `hydrationScope` and rotate it when deploying an incompatible cache schema or when separating cache namespaces:
+
+```tsx
+const fate = createClient({
+  hydrationScope: 'storefront-v2',
+  // ...
+});
+```
+
+Use `hydrationLimits` when an application needs stricter bootstrap payload limits. fate applies conservative defaults for total encoded values, collection sizes, and string lengths.
+
+By default, hydration preserves values already present in the browser cache while adding missing server data. Pass `{ merge: 'replace' }` only when the snapshot should authoritatively reset the durable cache:
+
+```tsx
+fate.hydrate(loaderData.fate, { merge: 'replace' });
+```
+
+`preserve-existing` recursively combines plain scalar objects while keeping browser values on conflicts. Arrays, dates, entity references, and list windows are atomic: an existing browser value wins as a whole. Replaying a snapshot is safe and does not notify subscribers when durable cache state is unchanged.
+
+Do not reuse request-scoped snapshots across users. Dehydrate after awaited route preloading: snapshots are point-in-time values and do not stream cache patches for data that resolves later. Hydration and dehydration reject clients with in-flight requests, so hydrate the initial snapshot before rendering.

package/docs/guide/server-integration.md

@@ -1,9 +1,10 @@
 # Server Integration
 
-Until now, we have focused on the client-side API of fate. You'll need a backend that follows fate's data protocol so the Vite plugin can wire the typed fate APIs into your app. _fate_ currently ships two server paths:
+Until now, we have focused on the client-side API of fate. You'll need a backend that can be wired into fate's typed request model so the Vite plugin can connect the typed fate APIs to your app. _fate_ currently ships three integration paths:
 
 - The native fate protocol, which is transport-agnostic and can be hosted by any Fetch-compatible server.
 - The tRPC adapter, which keeps compatibility with existing tRPC backends.
+- The [GraphQL transport](graphql-integration.md), which maps fate views and roots to an existing GraphQL schema.
 
 _fate_ currently provides database adapters for Prisma and Drizzle, but the framework itself is not coupled to a particular ORM. The adapters plug into the same source execution runtime and can be exposed through the native protocol or through tRPC.