fate

https://fate.technology/
Admin
fate is a modern data client for React that combines view composition, normalized caching, data...
Tokens:136,535
Snippets:1,143
Trust Score:6.7
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Run the GraphQL server

Source: https://fate.technology/example/server-graphql/README

Run these commands from the example directory to set up and start the server. The server defaults to http://localhost:9021/graphql.

```sh
vp run dev:setup
vp run prisma migrate dev
vp run dev
```

--------------------------------

### Client setup with createFateClient

Source: https://fate.technology/guide/live-views

Configure the native transport and point the client at your fate endpoint. Live views use `GET /fate/live` for the SSE stream and `POST /fate/live` for control messages.

```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>;
}
```

--------------------------------

### Postgres database setup SQL

Source: https://fate.technology/CONTRIBUTING

SQL commands to create the 'fate' role and database, and set the database owner. Run after starting Postgres via docker-compose or local setup.

```sql
CREATE ROLE fate WITH LOGIN PASSWORD 'echo';
CREATE DATABASE fate;
ALTER DATABASE fate OWNER TO fate;
```

--------------------------------

### useLiveView example

Source: https://fate.technology/api/react-fate/functions/useLiveView

Resolves a reference against a view and subscribes to live server updates for that selection. The example appears twice in the source, once for each call signature overload.

```ts
const post = useLiveView(PostView, postRef);
```

--------------------------------

### Install @nkzw/fate with npm, pnpm, and yarn

Source: https://fate.technology/guide/getting-started

Install the core `@nkzw/fate` package. Use this on the server if it's a separate package, or on the client for a barebones integration without a framework adapter.

```bash
npm add @nkzw/fate
```

```bash
pnpm add @nkzw/fate
```

```bash
yarn add @nkzw/fate
```

--------------------------------

### Create a new Void app with the Void template

Source: https://fate.technology/integrations/void

Use this command to scaffold a new Void app with the Void template, which includes client, routes, Drizzle setup, live transport, auth wiring, and generated fate client setup.

```sh
vp create fate my-app --template void
```

--------------------------------

### Install vue-fate with pnpm

Source: https://fate.technology/packages/fate/docs/guide/vue

No description

```bash
pnpm add vue-fate
```

--------------------------------

### Create full GraphQL + Prisma template

Source: https://fate.technology/packages/fate/docs/integrations/graphql

Creates a full GraphQL + Prisma example app. Use this template when you want a complete reference implementation.

```bash
vp create fate my-app --template graphql
```

--------------------------------

### Install vue-fate with yarn

Source: https://fate.technology/packages/fate/docs/guide/vue

No description

```bash
yarn add vue-fate
```

--------------------------------

### Install vue-fate with npm, pnpm, and yarn

Source: https://fate.technology/guide/getting-started

Install the Vue client package `vue-fate` using your preferred package manager.

```bash
npm add vue-fate
```

```bash
pnpm add vue-fate
```

```bash
yarn add vue-fate
```

--------------------------------

### Install vue-fate with npm

Source: https://fate.technology/packages/fate/docs/guide/vue

No description

```bash
npm add vue-fate
```

--------------------------------

### Add IndexedDB adapter with vp add

Source: https://fate.technology/guide/persistence

Install the IndexedDB storage adapter for the persistence layer.

```sh
vp add @nkzw/fate-indexeddb
```

--------------------------------

### useView example (TypeScript)

Source: https://fate.technology/api/react-fate/functions/useView

Example usage of useView() with a view and a reference. The function subscribes to updates for the selection.

```ts
const post = useView(PostView, postRef);
```

--------------------------------

### Install react-fate with npm, pnpm, and yarn

Source: https://fate.technology/guide/getting-started

Install the React client package `react-fate` using your preferred package manager. Requires React 19.2+.

```bash
npm add react-fate
```

```bash
pnpm add react-fate
```

```bash
yarn add react-fate
```

--------------------------------

### Install FateClient as a Vue plugin

Source: https://fate.technology/guide/vue

Install the FateClient as a Vue plugin using createFatePlugin. This is an alternative to using the FateClient provider component.

```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');
```

--------------------------------

### Add packages to an existing Void project (React)

Source: https://fate.technology/integrations/void

Install the required packages for a React-based Void project.

```sh
pnpm add @nkzw/fate react-fate void-fate void @void/react
```

--------------------------------

### Create a fate client with FateClient provider (React and Vue)

Source: https://fate.technology/packages/fate/docs/integrations/server

Create a fate client instance and provide it to your app with the FateClient provider. The React example uses useMemo and the Vue example uses computed. Both configure httpBatchLink with credentials: 'include' and the SERVER_URL environment variable.

```tsx
import { httpBatchLink } from '@trpc/client';
import { FateClient } from 'react-fate';
import { createFateClient } from 'react-fate/client';

export function App() {
  const fate = useMemo(
    () =>
      createFateClient({
        links: [
          httpBatchLink({
            fetch: (input, init) =>
              fetch(input, {
                ...init,
                credentials: 'include',
              }),
            url: `${env('SERVER_URL')}/trpc`,
          }),
        ],
      }),
    [],
  );
  return <FateClient client={fate}>{/* Components go here */}</FateClient>;
}
```

```vue
<script setup lang="ts">
import { httpBatchLink } from '@trpc/client';
import { computed } from 'vue';
import { FateClient } from 'vue-fate';
import { createFateClient } from 'vue-fate/client';
import AppRoutes from './AppRoutes.vue';

const fate = computed(() =>
  createFateClient({
    links: [
      httpBatchLink({
        fetch: (input, init) =>
          fetch(input, {
            ...init,
            credentials: 'include',
          }),
        url: `${env('SERVER_URL')}/trpc`,
      }),
    ],
  }),
);
</script>

<template>
  <FateClient :client="fate">
    <AppRoutes />
  </FateClient>
</template>
```

--------------------------------

### Create fate app with GraphQL templates

Source: https://fate.technology/integrations/graphql

Two CLI commands to scaffold a fate app: the first creates a client-only GraphQL integration template, the second creates a full GraphQL + Prisma example app. The client-only template is the smallest reference for the integration.

```bash
vp create fate my-app --template graphql-client
```

```bash
vp create fate my-app --template graphql
```

--------------------------------

### Add packages to an existing Void project (Vue)

Source: https://fate.technology/integrations/void

Install the required packages for a Vue-based Void project.

```sh
pnpm add @nkzw/fate vue-fate void-fate void @void/vue
```

--------------------------------

### Prisma tRPC Setup with createPrismaFate

Source: https://fate.technology/integrations/server

Sets up the Prisma tRPC integration by creating a router and procedure, then creating fate with createPrismaFate.

```tsx
import { initTRPC } from '@trpc/server';
import { createPrismaFate } from '@nkzw/fate/server/prisma';
import type { AppContext } from './context.ts';
import { Root } from './views.ts';

const t = initTRPC.context<AppContext>().create();

export const router = t.router;
export const procedure = t.procedure;

export const fate = createPrismaFate<AppContext, typeof procedure>({
  procedure,
  views: Root,
});
```

--------------------------------

### Create a new Void project with fate template

Source: https://fate.technology/integrations/cloudflare

Use the Void CLI to create a new project with the fate template. The command creates a project named 'my-app' using the 'void' template. After creation, run the setup and development commands. Add '--framework vue' to use Vue instead of React.

```sh
vp create fate my-app --template void
cd my-app
vp run dev:setup
vp run dev
```

--------------------------------

### Set up live event bus and expose native handler

Source: https://fate.technology/guide/live-views

Creates a live event bus and passes it to createFateServer, then exposes the native handler via app.all. This is required for live views to work.

```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));
```

--------------------------------

### createFateServer()

Source: https://fate.technology/api/@nkzw/fate/server/functions/createFateServer

Documentation for the createFateServer function, including its signature, type parameters, parameters, and return type.

```APIDOC
## createFateServer()

### Description
Creates a FateServer instance with the provided options, enabling the server to handle queries, lists, and mutations defined by the user.

### Signature
`createFateServer<Context, Roots, Queries, Lists, Mutations, AdapterContext>(__namedParameters): FateServer<NativeFateAPI<Roots, Queries, Lists, Mutations>, AdapterContext>`

### Type Parameters
- **Context** (`unknown`) - Default: `unknown` - The context type for the server.
- **Roots** (`RootMap`) - Default: `RootMap` - The root map type.
- **Queries** (`Record<string, QueryDefinition<Context, any, any>>`) - Default: `Record<never, never>` - The query definitions.
- **Lists** (`Record<string, ListDefinition<Context, any, any>>`) - Default: `Record<never, never>` - The list definitions.
- **Mutations** (`Record<string, MutationDefinition<Context, any, any>>`) - Default: `Record<never, never>` - The mutation definitions.
- **AdapterContext** (`unknown`) - Default: `unknown` - The adapter context type.

### Parameters
- **__namedParameters** (`FateServerOptions<Context, Roots, Queries, Lists, Mutations, AdapterContext>`) - Required - The options for creating the FateServer.

### Returns
- **FateServer<NativeFateAPI<Roots, Queries, Lists, Mutations>, AdapterContext>** - The created FateServer instance.

### Defined in
`fate/src/server/http.ts:630`
```

--------------------------------

### createFateClient with live URL

Source: https://fate.technology/integrations/graphql

Configures GraphQL live views using GraphQL SSE. Requires `graphql-sse` in the client package and `live` enabled.

```tsx
const fate = createFateClient({
  live: {
    url: 'https://api.example.com/graphql/stream',
  },
  url: 'https://api.example.com/graphql',
});
```

--------------------------------

### getScopedArgs

Source: https://fate.technology/api/%40nkzw/fate/server

Gets scoped arguments for a source.

```APIDOC
## getScopedArgs

### Description
Gets scoped arguments for a source.

### Signature
```ts
import { getScopedArgs } from '@nkzw/fate/server';
```

### Parameters
- `args` (Object) - Required - The arguments.
- `scope` (Object) - Required - The scope.

### Returns
- `Object` - The scoped arguments.
```

--------------------------------

### Create Void live adapter and Fate server

Source: https://fate.technology/integrations/void

Sets up a Void live adapter with createVoidFateLive, passes its live event bus to createFateServer, and exports the adapter. Requires a Drizzle source adapter and a context factory.

```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,
});
```

--------------------------------

### Set up native fate server with Prisma and Hono

Source: https://fate.technology/integrations/server

Sets up the native fate protocol with a Prisma source adapter, `createFateServer`, and a Hono handler. Exposes `POST /fate` and `POST /fate/live` endpoints.

```tsx
import { createFateServer, createHonoFateHandler } from '@nkzw/fate/server';
import { createPrismaSourceAdapter } from '@nkzw/fate/server/prisma';
import { Hono } from 'hono';
import type { AppContext } from './context.ts';
import { prisma } from './prisma.ts';
import { Root, userDataView } from './views.ts';

export { Root } from './views.ts';

const sources = createPrismaSourceAdapter<AppContext>({
  prisma: (ctx) => ctx.prisma,
  views: Root,
});

export const fate = createFateServer({
  context: async ({ adapterContext }) => ({
    prisma,
    request: adapterContext.req.raw,
    sessionUser: await getSessionUser(adapterContext.req.raw),
  }),
  queries: {
    viewer: {
      resolve: ({ ctx, select }) =>
        sources.resolveById({
          ctx,
          id: ctx.sessionUser.id,
          input: { select },
          view: userDataView,
        }),
    },
  },
  roots: Root,
  sources,
});

const app = new Hono();
const handler = createHonoFateHandler(fate);

app.post('/fate', handler);
app.post('/fate/live', handler);
```

--------------------------------

### getNestedSelection

Source: https://fate.technology/api/%40nkzw/fate/server

Gets nested selection from a selection set.

```APIDOC
## getNestedSelection

### Description
Gets nested selection from a selection set.

### Signature
```ts
import { getNestedSelection } from '@nkzw/fate/server';
```

### Parameters
- `selection` (FieldSelection) - Required - The selection set.

### Returns
- `FieldSelection` - The nested selection.
```

--------------------------------

### createFateServer

Source: https://fate.technology/api/%40nkzw/fate/server

Creates a Fate server instance.

```APIDOC
## createFateServer

### Description
Creates a Fate server instance.

### Signature
```ts
import { createFateServer } from '@nkzw/fate/server';
```

### Parameters
- `manifest` (FateServerManifest) - Required - The server manifest.

### Returns
- `FateServer` - The created Fate server instance.
```

--------------------------------

### createClient()

Source: https://fate.technology/packages/react-fate/docs/api/functions/createClient

Documentation for the createClient function, including its signature, type parameters, parameters, and return type.

```APIDOC
## Function: createClient()

### Description
Creates a Fate client instance with the provided options. The client is typed with the given roots and mutations, and supports a hydration scope.

### Signature
`createClient<T, HydrationScope>(options): FateClient<T[0], T[1], HydrationScope>`

### Type Parameters
- **T** - Extends `[FateRoots, FateMutations]`, defaults to `[Record<never, RootDefinition<any, any>>, Record<never, MutationDefinition<any, any, any>>]`
- **HydrationScope** - Extends `string`, defaults to `string`

### Parameters
- **options** (`FateClientOptions<T[0], T[1], HydrationScope>`) - The client options.

### Returns
- `FateClient<T[0], T[1], HydrationScope>` - The created Fate client.
```

--------------------------------

### useRequest

Source: https://fate.technology/packages/react-fate/docs/api/functions/useRequest

Documentation for the useRequest function, including its signature, parameters, return type, and an example.

```APIDOC
## useRequest<R, O>(request, options?): RequestResult<O, R>

### Description
Declares the data a screen needs and kicks off fetching, suspending while the request resolves.

### Signature
`useRequest<R, O>(request, options?): RequestResult<O, R>`

### Type Parameters
- **R** - extends `Request$1`
- **O** - extends `FateRoots` = `FateRoots`

### Parameters
- **request** (`R`) - Required - The request object describing the data needed.
- **options?** (`Readonly<{ mode?: RequestMode; persist?: Readonly<{ maxAge: number; }>; }>`) - Optional - Configuration options for the request.

### Returns
`RequestResult<O, R>`

### Example
```ts
const { posts } = useRequest({ posts: { list: PostView } });
```
```

--------------------------------

### Create a new Void app with Vue framework

Source: https://fate.technology/integrations/void

Use this command to create a new Void app with the Vue framework instead of React.

```sh
vp create fate my-app --template void --framework vue
```

--------------------------------

### Import dataView from @nkzw/fate/server

Source: https://fate.technology/api/%40nkzw/fate/server

Shows how to import the dataView function from the @nkzw/fate/server library. This is the only code example on the page.

```typescript
import { dataView } from '@nkzw/fate/server';
```

--------------------------------

### Replace useView with useLiveView

Source: https://fate.technology/posts/fate-1.0

Shows the diff to switch from useView to useLiveView for real-time updates via SSE.

```diff
- const post = useView(PostView, postRef);
+ const post = useLiveView(PostView, postRef);
```

--------------------------------

### Import view from @nkzw/fate

Source: https://fate.technology/api/%40nkzw/fate

Shows how to import the view function from the @nkzw/fate core library. This is the only code example on the page.

```typescript
import { view } from '@nkzw/fate';
```

--------------------------------

### dataView() usage example

Source: https://fate.technology/api/%40nkzw/fate/server/functions/dataView

Declares a server data view for a PostItem, exposing the 'id' and 'title' fields to the client.

```typescript
const Post = dataView<PostItem>('Post')({
  id: true,
  title: true,
});
```

--------------------------------

### useRequest with arguments for pagination

Source: https://fate.technology/guide/requests

Pass arguments to useRequest for pagination, filtering, or sorting. Example fetches the first 10 posts.

```tsx
const { posts } = useRequest({
  posts: {
    args: { first: 10 },
    list: PostView,
  },
});
```

--------------------------------

### useRequest() example

Source: https://fate.technology/api/react-fate/functions/useRequest

Declares a request for posts using the PostView component and destructures the result. The hook suspends while the request resolves.

```ts
const { posts } = useRequest({ posts: { list: PostView } });
```

--------------------------------

### new FateClient(options)

Source: https://fate.technology/api/%40nkzw/fate/classes/FateClient

Creates a new FateClient instance with the provided options. The constructor initializes the client with roots, mutations, and hydration scope.

```APIDOC
## Constructor

### Description
Creates a new FateClient instance.

### Signature
`new FateClient<Roots, Mutations, HydrationScope>(options: FateClientOptions<Roots, Mutations, HydrationScope>): FateClient<Roots, Mutations, HydrationScope>`

### Parameters
- **options** (`FateClientOptions<Roots, Mutations, HydrationScope>`) - Required - Configuration options for the client.

### Returns
`FateClient<Roots, Mutations, HydrationScope>`
```

--------------------------------

### Create a new fate app with Vite+

Source: https://fate.technology/guide/getting-started

Run this command to scaffold a new fate project. The template selector can create React or Vue clients for Void, tRPC, GraphQL, or a fate client for an existing GraphQL server. React is the default UI framework; pass `--framework vue` to choose Vue.

```bash
vp create fate my-app
```

--------------------------------

### Define CommentView and CommentConnectionView for useListView

Source: https://fate.technology/guide/list-views

Defines a CommentView and a CommentConnectionView with args and items, then uses them in a PostView. This setup is required before using the useListView hook.

```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,
});
```

--------------------------------

### Configure Vite plugin for Vue with native transport

Source: https://fate.technology/integrations/server

Configures the Vite plugin for Vue with the native transport. The plugin handles the HTTP transport setup.

```ts
import vue from '@vitejs/plugin-vue';
import { fate } from 'vue-fate/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    vue(),
    fate({
      module: '@your-org/server/fate.ts',
      transport: 'native',
    }),
  ],
});
```

--------------------------------

### createFateFetchHandler()

Source: https://fate.technology/api/%40nkzw/fate/server/functions/createFateFetchHandler

Creates a fetch handler for a FateServer instance. The handler processes incoming requests and returns a Response.

```APIDOC
## Function: createFateFetchHandler()

### Description
Creates a fetch handler for a FateServer instance. The returned handler processes a request and returns a Promise resolving to a Response.

### Signature
`createFateFetchHandler<AdapterContext>(server): (request, adapterContext?) => Promise<Response>`

### Type Parameters
- **AdapterContext** - The adapter context type.

### Parameters
- **server** (`FateServer<unknown, AdapterContext>`) - The FateServer instance to create the handler for.

### Returns
A function that takes a `request` and an optional `adapterContext` and returns a `Promise<Response>`.

### Defined in
fate/src/server/http.ts:1466
```

--------------------------------

### Configure Vite plugin for React with native transport

Source: https://fate.technology/integrations/server

Configures the Vite plugin for React with the native transport. The plugin handles the HTTP transport setup.

```tsx
import { fate } from 'react-fate/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    fate({
      module: '@your-org/server/fate.ts',
      transport: 'native',
    }),
  ],
});
```

--------------------------------

### LikeButton with useTransition and fate.actions

Source: https://fate.technology/guide/actions

Use fate.actions.post.like with useActionState and useTransition when not using an async component library. The action is started in a transition, and the button is disabled while pending.

```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>
  );
};
```

--------------------------------

### liveConnectionTopic(procedure, args?)

Source: https://fate.technology/api/%40nkzw/fate/functions/liveConnectionTopic

Generates a topic string for live connections based on a procedure name and optional arguments.

```APIDOC
## Function: liveConnectionTopic()

### Description
Generates a topic string for live connections based on a procedure name and optional arguments.

### Signature
`liveConnectionTopic(procedure: string, args?: Record<string, unknown>): string`

### Parameters
- **procedure** (`string`) - Required - The procedure name.
- **args** (`Record<string, unknown>`) - Optional - Additional arguments for the topic.

### Returns
`string` - The generated topic string.

### Source
Defined in: fate/src/liveTopics.ts:20
```

--------------------------------

### useRequest with stale-while-revalidate mode

Source: https://fate.technology/guide/requests

Pass a request mode as an option to useRequest. This example uses stale-while-revalidate to return cached data and fetch fresh data in the background.

```tsx
const { posts } = useRequest(
  {
    posts: { list: PostView },
  },
  {
    mode: 'stale-while-revalidate',
  },
);
```

--------------------------------

### Request multiple objects by IDs with useRequest

Source: https://fate.technology/guide/requests

Fetches multiple objects by specifying an array of ids and a view. The example requests posts with ids '6' and '7'.

```tsx
const { posts } = useRequest({
  posts: { ids: ['6', '7'], view: PostView },
});
```

--------------------------------

### createFateServer()

Source: https://fate.technology/api/%40nkzw/fate/server/functions/createFateServer

Creates a FateServer instance with a native Fate API. The function accepts a FateServerOptions object and returns a FateServer instance.

```APIDOC
## Function: createFateServer()

### Description
Creates a FateServer instance with a native Fate API. The function accepts a FateServerOptions object and returns a FateServer instance.

### Signature
`createFateServer<Context, Roots, Queries, Lists, Mutations, AdapterContext>(__namedParameters): FateServer<NativeFateAPI<Roots, Queries, Lists, Mutations>, AdapterContext>`

### Type Parameters
- **Context** (`unknown`) - Default: `unknown`
- **Roots** (`RootMap`) - Default: `RootMap`
- **Queries** (`Record<string, QueryDefinition<Context, any, any>>`) - Default: `Record<never, never>`
- **Lists** (`Record<string, ListDefinition<Context, any, any>>`) - Default: `Record<never, never>`
- **Mutations** (`Record<string, MutationDefinition<Context, any, any>>`) - Default: `Record<never, never>`
- **AdapterContext** (`unknown`) - Default: `unknown`

### Parameters
- **__namedParameters** (`FateServerOptions<Context, Roots, Queries, Lists, Mutations, AdapterContext>`) - Required - The options for creating the FateServer.

### Returns
- **FateServer<NativeFateAPI<Roots, Queries, Lists, Mutations>, AdapterContext>** - The created FateServer instance.

### Defined in
fate/src/server/http.ts:630
```
Tokens:
Raw