react-fate 1.3.0 → 1.3.1

package/README.md

@@ -2676,7 +2676,23 @@ _And you are all set. Happy building!_
 Use this integration when your app runs on Void and you want the example app's
 setup without copying its adapter glue.
 
-### Install
+### New Project
+
+For a new Void app, start from the Void template. It includes the client, Void routes, Drizzle setup, live transport, auth wiring, and generated fate client setup.
+
+```sh
+vp create fate my-app --template void
+```
+
+Use Vue instead of React with:
+
+```sh
+vp create fate my-app --template void --framework vue
+```
+
+### Existing Project
+
+For an existing Void project, add the packages directly:
 
 ::: code-group
 
@@ -2919,6 +2935,168 @@ 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.
 
+## 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.
+
+### New Project
+
+For a new Cloudflare Workers app, start from the Cloudflare template. It includes the client, Worker server, D1 migrations, Wrangler config, Durable Object live transport, auth wiring, and generated fate client setup.
+
+```sh
+vp create fate my-app --template cloudflare
+```
+
+Use Vue instead of React with:
+
+```sh
+vp create fate my-app --template cloudflare --framework vue
+```
+
+### Existing Project
+
+For an existing Cloudflare Workers project, add the packages directly:
+
+```sh
+pnpm add @nkzw/fate react-fate cf-fate drizzle-orm
+pnpm add -D wrangler
+```
+
+For Vue clients, replace `react-fate` with `vue-fate`.
+
+### 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.
+
 ## Frequently Asked Questions
 
 ### Is this serious software?

package/docs/api/functions/FateClient.md

@@ -2,7 +2,7 @@
 
 > **FateClient**(`__namedParameters`): `Element`
 
-Defined in: [packages/react-fate/src/context.tsx:17](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/react-fate/src/context.tsx#L17)
+Defined in: [packages/react-fate/src/context.tsx:17](https://github.com/nkzw-tech/fate/blob/bdff68417591ff0372c03c214bbc7c722cdf13a2/packages/react-fate/src/context.tsx#L17)
 
 Provider component that supplies a configured `FateClient` to React hooks.
 

package/docs/api/functions/useFateClient.md

@@ -2,7 +2,7 @@
 
 > **useFateClient**\<`T`\>(): `FateClient`\<`T`\[`0`\], `T`\[`1`\]\>
 
-Defined in: [packages/react-fate/src/context.tsx:30](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/react-fate/src/context.tsx#L30)
+Defined in: [packages/react-fate/src/context.tsx:30](https://github.com/nkzw-tech/fate/blob/bdff68417591ff0372c03c214bbc7c722cdf13a2/packages/react-fate/src/context.tsx#L30)
 
 Returns the nearest `FateClient` from context.
 

package/docs/api/functions/useListView.md

@@ -2,7 +2,7 @@
 
 > **useListView**\<`C`\>(`selection`, `connection`): \[`ConnectionItems`\<`ResolvedConnection`\<`C`\>\>, `LoadMoreFn` \| `null`, `LoadMoreFn` \| `null`\]
 
-Defined in: [packages/react-fate/src/useListView.tsx:19](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/react-fate/src/useListView.tsx#L19)
+Defined in: [packages/react-fate/src/useListView.tsx:19](https://github.com/nkzw-tech/fate/blob/bdff68417591ff0372c03c214bbc7c722cdf13a2/packages/react-fate/src/useListView.tsx#L19)
 
 Subscribes to a connection field, returning the current items and pagination
 helpers to load the next or previous page.

package/docs/api/functions/useLiveListView.md

@@ -2,7 +2,7 @@
 
 > **useLiveListView**\<`C`\>(`selection`, `connection`): \[`ConnectionItems`\<`ResolvedConnection`\<`C`\>\>, `LoadMoreFn` \| `null`, `LoadMoreFn` \| `null`\]
 
-Defined in: [packages/react-fate/src/useLiveListView.tsx:19](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/react-fate/src/useLiveListView.tsx#L19)
+Defined in: [packages/react-fate/src/useLiveListView.tsx:19](https://github.com/nkzw-tech/fate/blob/bdff68417591ff0372c03c214bbc7c722cdf13a2/packages/react-fate/src/useLiveListView.tsx#L19)
 
 Subscribes to a connection field, returning live-updating items and pagination
 helpers to load the next or previous page.

package/docs/api/functions/useLiveView.md

@@ -4,7 +4,7 @@
 
 > **useLiveView**\<`V`, `R`\>(`view`, `ref`): `R` *extends* `null` ? `null` : `Readonly`\<`ViewSelection`\<`V`\> *extends* `Selection`\<`ViewEntityWithTypename`\<`V`\>\> ? `Mask`\<`ViewEntityWithTypename`\<`V`\>, \{ \[K in string \| number \| symbol as K extends "\_\_typename" ? never : K\]?: DeferrableSelectionFieldValue\<ViewEntityWithTypename\<V\>, K\> \} & `object` & `SelectionViewSpread`\<`ViewEntityWithTypename`\<`V`\>\> & `ViewSelection`\<`V`\>\> : `ViewEntityWithTypename`\<`V`\> & `object`\>
 
-Defined in: [packages/react-fate/src/useLiveView.tsx:27](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/react-fate/src/useLiveView.tsx#L27)
+Defined in: [packages/react-fate/src/useLiveView.tsx:27](https://github.com/nkzw-tech/fate/blob/bdff68417591ff0372c03c214bbc7c722cdf13a2/packages/react-fate/src/useLiveView.tsx#L27)
 
 Resolves a reference against a view and subscribes to live server updates for
 that selection.
@@ -43,7 +43,7 @@ const post = useLiveView(PostView, postRef);
 
 > **useLiveView**\<`V`, `R`\>(`view`, `ref`): `R` *extends* `null` ? `null` : `Readonly`\<`ViewSelection`\<`V`\> *extends* `Selection`\<`ViewEntityWithTypename`\<`V`\>\> ? `Mask`\<`ViewEntityWithTypename`\<`V`\>, \{ \[K in string \| number \| symbol as K extends "\_\_typename" ? never : K\]?: DeferrableSelectionFieldValue\<ViewEntityWithTypename\<V\>, K\> \} & `object` & `SelectionViewSpread`\<`ViewEntityWithTypename`\<`V`\>\> & `ViewSelection`\<`V`\>\> : `ViewEntityWithTypename`\<`V`\> & `object`\>
 
-Defined in: [packages/react-fate/src/useLiveView.tsx:31](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/react-fate/src/useLiveView.tsx#L31)
+Defined in: [packages/react-fate/src/useLiveView.tsx:31](https://github.com/nkzw-tech/fate/blob/bdff68417591ff0372c03c214bbc7c722cdf13a2/packages/react-fate/src/useLiveView.tsx#L31)
 
 Resolves a reference against a view and subscribes to live server updates for
 that selection.

package/docs/api/functions/useRequest.md

@@ -2,7 +2,7 @@
 
 > **useRequest**\<`R`, `O`\>(`request`, `options?`): `RequestResult`\<`O`, `R`\>
 
-Defined in: [packages/react-fate/src/useRequest.tsx:25](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/react-fate/src/useRequest.tsx#L25)
+Defined in: [packages/react-fate/src/useRequest.tsx:25](https://github.com/nkzw-tech/fate/blob/bdff68417591ff0372c03c214bbc7c722cdf13a2/packages/react-fate/src/useRequest.tsx#L25)
 
 Declares the data a screen needs and kicks off fetching, suspending while the
 request resolves.

package/docs/api/functions/useView.md

@@ -4,7 +4,7 @@
 
 > **useView**\<`V`, `R`\>(`view`, `ref`): `R` *extends* `null` ? `null` : `Readonly`\<`ViewSelection`\<`V`\> *extends* `Selection`\<`ViewEntityWithTypename`\<`V`\>\> ? `Mask`\<`ViewEntityWithTypename`\<`V`\>, \{ \[K in string \| number \| symbol as K extends "\_\_typename" ? never : K\]?: DeferrableSelectionFieldValue\<ViewEntityWithTypename\<V\>, K\> \} & `object` & `SelectionViewSpread`\<`ViewEntityWithTypename`\<`V`\>\> & `ViewSelection`\<`V`\>\> : `ViewEntityWithTypename`\<`V`\> & `object`\>
 
-Defined in: [packages/react-fate/src/useView.tsx:40](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/react-fate/src/useView.tsx#L40)
+Defined in: [packages/react-fate/src/useView.tsx:40](https://github.com/nkzw-tech/fate/blob/bdff68417591ff0372c03c214bbc7c722cdf13a2/packages/react-fate/src/useView.tsx#L40)
 
 Resolves a reference against a view and subscribes to updates for that selection.
 
@@ -42,7 +42,7 @@ const post = useView(PostView, postRef);
 
 > **useView**\<`V`, `R`\>(`view`, `ref`): `R` *extends* `null` ? `null` : `Readonly`\<`ViewSelection`\<`V`\> *extends* `Selection`\<`ViewEntityWithTypename`\<`V`\>\> ? `Mask`\<`ViewEntityWithTypename`\<`V`\>, \{ \[K in string \| number \| symbol as K extends "\_\_typename" ? never : K\]?: DeferrableSelectionFieldValue\<ViewEntityWithTypename\<V\>, K\> \} & `object` & `SelectionViewSpread`\<`ViewEntityWithTypename`\<`V`\>\> & `ViewSelection`\<`V`\>\> : `ViewEntityWithTypename`\<`V`\> & `object`\>
 
-Defined in: [packages/react-fate/src/useView.tsx:44](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/react-fate/src/useView.tsx#L44)
+Defined in: [packages/react-fate/src/useView.tsx:44](https://github.com/nkzw-tech/fate/blob/bdff68417591ff0372c03c214bbc7c722cdf13a2/packages/react-fate/src/useView.tsx#L44)
 
 Resolves a reference against a view and subscribes to updates for that selection.
 
@@ -80,7 +80,7 @@ const post = useView(PostView, postRef);
 
 > **useView**\<`V`\>(`view`, `ref`): `Readonly`\<`ViewSelection`\<`V`\> *extends* `Selection`\<`ViewEntityWithTypename`\<`V`\>\> ? `Mask`\<`ViewEntityWithTypename`\<`V`\>, \{ \[K in string \| number \| symbol as K extends "\_\_typename" ? never : K\]?: DeferrableSelectionFieldValue\<ViewEntityWithTypename\<V\>, K\> \} & `object` & `SelectionViewSpread`\<`ViewEntityWithTypename`\<`V`\>\> & `ViewSelection`\<`V`\>\> : `ViewEntityWithTypename`\<`V`\> & `object`\> \| `null`
 
-Defined in: [packages/react-fate/src/useView.tsx:48](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/react-fate/src/useView.tsx#L48)
+Defined in: [packages/react-fate/src/useView.tsx:48](https://github.com/nkzw-tech/fate/blob/bdff68417591ff0372c03c214bbc7c722cdf13a2/packages/react-fate/src/useView.tsx#L48)
 
 Resolves a reference against a view and subscribes to updates for that selection.
 

package/docs/integrations/cloudflare.md

@@ -4,13 +4,31 @@
 
 Use it when your backend runs directly on Cloudflare Workers and you want fate live views without adopting the Void platform.
 
-## Install
+## New Project
+
+For a new Cloudflare Workers app, start from the Cloudflare template. It includes the client, Worker server, D1 migrations, Wrangler config, Durable Object live transport, auth wiring, and generated fate client setup.
+
+```sh
+vp create fate my-app --template cloudflare
+```
+
+Use Vue instead of React with:
+
+```sh
+vp create fate my-app --template cloudflare --framework vue
+```
+
+## Existing Project
+
+For an existing Cloudflare Workers project, add the packages directly:
 
 ```sh
 pnpm add @nkzw/fate react-fate cf-fate drizzle-orm
 pnpm add -D wrangler
 ```
 
+For Vue clients, replace `react-fate` with `vue-fate`.
+
 ## Server Setup
 
 Create a Cloudflare live stream and pass its Fate live facade to `createFateServer`.

package/docs/integrations/void.md

@@ -5,7 +5,23 @@
 Use this integration when your app runs on Void and you want the example app's
 setup without copying its adapter glue.
 
-## Install
+## New Project
+
+For a new Void app, start from the Void template. It includes the client, Void routes, Drizzle setup, live transport, auth wiring, and generated fate client setup.
+
+```sh
+vp create fate my-app --template void
+```
+
+Use Vue instead of React with:
+
+```sh
+vp create fate my-app --template void --framework vue
+```
+
+## Existing Project
+
+For an existing Void project, add the packages directly:
 
 ::: code-group
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-fate",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "fate is a modern data client for React.",
   "homepage": "https://github.com/nkzw-tech/fate",
   "license": "MIT",
@@ -40,7 +40,7 @@
     }
   },
   "dependencies": {
-    "@nkzw/fate": "^1.3.0"
+    "@nkzw/fate": "^1.3.1"
   },
   "devDependencies": {
     "@types/react": "^19.2.16",