@nkzw/fate 1.2.0 → 1.3.0

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

@@ -2,7 +2,7 @@
 
 > **RequestResult**\<`R`, `Q`\> = `{ [K in keyof Q]: K extends keyof R ? ListResult<Q[K], RootType<R[K]>, RootResult<R[K]>> : never }`
 
-Defined in: [packages/fate/src/types.ts:424](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L424)
+Defined in: [packages/fate/src/types.ts:424](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L424)
 
 The result of a `FateClient.request` and `useRequest` call, mapping each
 request key to its corresponding result.

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

@@ -2,7 +2,7 @@
 
 > **Selection**\<`T`\> = `SelectionShape`\<`T`\> & `SelectionViewSpread`\<`T`\>
 
-Defined in: [packages/fate/src/types.ts:229](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L229)
+Defined in: [packages/fate/src/types.ts:229](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L229)
 
 Declarative selection of the fields a view needs from an entity.
 

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

@@ -2,6 +2,6 @@
 
 > **Snapshot** = `Readonly`\<\{ `mask?`: `FieldMask`; `record?`: [`FateRecord`](FateRecord.md); \}\>
 
-Defined in: [packages/fate/src/types.ts:513](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L513)
+Defined in: [packages/fate/src/types.ts:513](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L513)
 
 Snapshot captured before mutating the cache, used to roll back on errors.

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

@@ -2,7 +2,7 @@
 
 > **TypeConfig** = `object`
 
-Defined in: [packages/fate/src/types.ts:124](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L124)
+Defined in: [packages/fate/src/types.ts:124](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L124)
 
 Configuration for a server entity type used by the client cache.
 
@@ -12,7 +12,7 @@ Configuration for a server entity type used by the client cache.
 
 > `optional` **fields?**: `Record`\<`string`, `RelationDescriptor`\>
 
-Defined in: [packages/fate/src/types.ts:125](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L125)
+Defined in: [packages/fate/src/types.ts:125](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L125)
 
 ***
 
@@ -20,7 +20,7 @@ Defined in: [packages/fate/src/types.ts:125](https://github.com/nkzw-tech/fate/b
 
 > **getId**: (`record`) => `string` \| `number`
 
-Defined in: [packages/fate/src/types.ts:126](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L126)
+Defined in: [packages/fate/src/types.ts:126](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L126)
 
 #### Parameters
 
@@ -38,4 +38,4 @@ Defined in: [packages/fate/src/types.ts:126](https://github.com/nkzw-tech/fate/b
 
 > **type**: `string`
 
-Defined in: [packages/fate/src/types.ts:127](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L127)
+Defined in: [packages/fate/src/types.ts:127](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L127)

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

@@ -2,7 +2,7 @@
 
 > **View**\<`T`, `S`\> = `Readonly`\<\{\[`viewTag`: `` `__fate-view__${string}` ``\]: `Readonly`\<\{ `[ViewKind]`: `true`; `select`: `S`; \}\>; \}\> & `__ViewEntityAnchor`\<`T`\> & `__ViewSelectionAnchor`\<`S`\>
 
-Defined in: [packages/fate/src/types.ts:245](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L245)
+Defined in: [packages/fate/src/types.ts:245](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L245)
 
 Definition of a view over an entity type, including the selection of fields.
 

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

@@ -2,7 +2,7 @@
 
 > **ViewData**\<`T`, `S`\> = `Readonly`\<`S` *extends* [`Selection`](Selection.md)\<`T`\> ? [`Mask`](Mask.md)\<`T`, `S`\> : `T` & `object`\>
 
-Defined in: [packages/fate/src/types.ts:261](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L261)
+Defined in: [packages/fate/src/types.ts:261](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L261)
 
 Data returned from a resolved view with masking applied and view tags
 attached for downstream composition.

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

@@ -2,7 +2,7 @@
 
 > **ViewEntity**\<`V`\> = `V` *extends* [`View`](View.md)\<infer T, `any`\> ? `T` : `never`
 
-Defined in: [packages/fate/src/types.ts:335](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L335)
+Defined in: [packages/fate/src/types.ts:335](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L335)
 
 Entity type captured from a view definition.
 

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

@@ -2,7 +2,7 @@
 
 > **ViewEntityName**\<`V`\> = [`ViewEntity`](ViewEntity.md)\<`V`\>\[`"__typename"`\] & `string`
 
-Defined in: [packages/fate/src/types.ts:338](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L338)
+Defined in: [packages/fate/src/types.ts:338](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L338)
 
 Name of the entity type captured from a view definition.
 

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/src/types.ts:108](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L108)
+Defined in: [packages/fate/src/types.ts:108](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L108)
 
 Reference to a normalized entity instance that can be resolved against one or more view tags.
 

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

@@ -2,7 +2,7 @@
 
 > **ViewSelection**\<`V`\> = `V` *extends* `object` ? `S` : `never`
 
-Defined in: [packages/fate/src/types.ts:341](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L341)
+Defined in: [packages/fate/src/types.ts:341](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L341)
 
 Selection captured from a view definition.
 

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

@@ -2,7 +2,7 @@
 
 > **ViewSnapshot**\<`T`, `S`\> = `Readonly`\<\{ `coverage`: `ReadonlyArray`\<readonly \[[`EntityId`](EntityId.md), `ReadonlySet`\<`string`\>\]\>; `data`: [`ViewData`](ViewData.md)\<`T`, `S`\>; \}\>
 
-Defined in: [packages/fate/src/types.ts:271](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L271)
+Defined in: [packages/fate/src/types.ts:271](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L271)
 
 Snapshot returned by the cache for a view, including the masked data and all
 referenced entity IDs.

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

@@ -2,6 +2,6 @@
 
 > **ViewTag** = `` `__fate-view__${string}` ``
 
-Defined in: [packages/fate/src/types.ts:56](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L56)
+Defined in: [packages/fate/src/types.ts:56](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L56)
 
 Unique key that identifies a view composition entry inside a selection or reference.

package/docs/api/variables/ConnectionTag.md

@@ -2,6 +2,6 @@
 
 > `const` **ConnectionTag**: *typeof* `ConnectionTag`
 
-Defined in: [packages/fate/src/types.ts:20](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L20)
+Defined in: [packages/fate/src/types.ts:20](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L20)
 
 Symbol attached to connection results so pagination helpers can find their metadata.

package/docs/api/variables/DeferTag.md

@@ -2,6 +2,6 @@
 
 > `const` **DeferTag**: *typeof* `DeferTag`
 
-Defined in: [packages/fate/src/types.ts:23](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L23)
+Defined in: [packages/fate/src/types.ts:23](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L23)
 
 Symbol used to mark a selection as deferred.

package/docs/api/variables/DeferredTag.md

@@ -2,6 +2,6 @@
 
 > `const` **DeferredTag**: *typeof* `DeferredTag`
 
-Defined in: [packages/fate/src/types.ts:26](https://github.com/nkzw-tech/fate/blob/92f28ac4263e4f242ab8546c3bc2123a24b18461/packages/fate/src/types.ts#L26)
+Defined in: [packages/fate/src/types.ts:26](https://github.com/nkzw-tech/fate/blob/4876b00b02cd1ef9ae7fd82b8a3c27d82fc6c232/packages/fate/src/types.ts#L26)
 
 Symbol attached to deferred values returned from masked views.

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.

package/lib/vite.d.mts

@@ -1,7 +1,7 @@
 import { Plugin } from "vite";
 
 //#region src/viteTypes.d.ts
-type FateViteTransport = 'graphql' | 'native' | 'trpc' | 'void';
+type FateViteTransport = 'cloudflare' | 'graphql' | 'native' | 'trpc' | 'void';
 //#endregion
 //#region src/vite.d.ts
 type ClientRuntime = '@nkzw/fate' | 'react-fate' | 'vue-fate';

package/lib/vite.mjs

@@ -87,11 +87,20 @@ const createClientSource = ({ clientModule = "react-fate", moduleExports, module
 	});
 	if (transport === "native" || transport === "void") return createNativeClientSource({
 		clientModule,
+		cloudflareTransport: false,
 		moduleExports,
 		moduleName,
 		runtimeModuleName,
 		voidTransport: transport === "void"
 	});
+	if (transport === "cloudflare") return createNativeClientSource({
+		clientModule,
+		cloudflareTransport: true,
+		moduleExports,
+		moduleName,
+		runtimeModuleName,
+		voidTransport: false
+	});
 	const { appRouter, Root } = moduleExports;
 	const { roots, types } = createSchema(Object.values(moduleExports).filter(isDataView), Root ?? {});
 	const routerRecord = appRouter._def?.record ?? {};
@@ -412,7 +421,7 @@ type GeneratedCreateFateClient = typeof createFateClient;
 ${generatedClientTypes}
 `;
 };
-const createNativeClientSource = ({ clientModule, moduleExports, moduleName, runtimeModuleName, voidTransport }) => {
+const createNativeClientSource = ({ clientModule, cloudflareTransport, moduleExports, moduleName, runtimeModuleName, voidTransport }) => {
 	const { Root } = moduleExports;
 	const fateExportName = moduleExports.fate?.manifest ? "fate" : moduleExports.fateServer?.manifest ? "fateServer" : null;
 	const fateServer = fateExportName ? moduleExports[fateExportName] : null;
@@ -510,7 +519,17 @@ const createVoidFetch = (options: {
     });
 };
 ` : "";
-	const createClientOptions = voidTransport ? `options: {
+	const cloudflareHelpers = cloudflareTransport ? `
+const defaultCloudflareFateRpcPath = '/fate';
+const defaultCloudflareFateLivePath = '/fate-live';
+
+const getDefaultOrigin = () =>
+  typeof window === 'undefined' ? 'http://localhost' : window.location.origin;
+
+const toEndpointUrl = (url: string | URL | undefined, path: string, origin: string | URL) =>
+  url ?? new URL(path, origin);
+` : "";
+	const createClientOptions = voidTransport || cloudflareTransport ? `options: {
   fetch?: typeof fetch;
   headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
   livePath?: string;
@@ -529,7 +548,7 @@ const createVoidFetch = (options: {
   onLiveError?: (error: unknown) => void;
   url: string | URL;
 }`;
-	const clientSetup = voidTransport ? ` => {
+	const clientSetup = voidTransport || cloudflareTransport ? ` => {
   const origin = options.origin ?? getDefaultOrigin();
 
   return createClient<[GeneratedClientRoots, GeneratedClientMutations], typeof hydrationScope>({
@@ -538,16 +557,16 @@ const createVoidFetch = (options: {
     onLiveError: options.onLiveError,
     roots,
     transport: createHTTPTransport<FateAPI>({
-      fetch: createVoidFetch(options),
+      fetch: ${voidTransport ? "createVoidFetch(options)" : "options.fetch"},
       headers: options.headers,
-      live: ${hasLive ? "connectLiveStream" : "false"},
+      live: ${hasLive ? voidTransport ? "connectLiveStream" : "connectCloudflareFateStream" : "false"},
       liveRetryMs: options.liveRetryMs,
       liveUrl: toEndpointUrl(
         options.liveUrl,
-        options.livePath ?? defaultVoidFateLivePath,
+        options.livePath ?? ${voidTransport ? "defaultVoidFateLivePath" : "defaultCloudflareFateLivePath"},
         origin,
       ),
-      url: toEndpointUrl(options.url, options.rpcPath ?? defaultVoidFateRpcPath, origin),
+      url: toEndpointUrl(options.url, options.rpcPath ?? ${voidTransport ? "defaultVoidFateRpcPath" : "defaultCloudflareFateRpcPath"}, origin),
     }),
     types: ${typesBlock.trimStart()},
   });
@@ -581,6 +600,7 @@ declare module '${clientDeclarationModule}' {
 import type { ${importedTypes.join(", ")} } from '${moduleName}';
 import { clientRoot, createClient, createHTTPTransport, mutation, type InferFateAPI } from '${clientModule}';
 ${voidTransport && hasLive ? "import { connectLiveStream } from 'void/live/client';\n" : ""}${voidServerFetch}
+${cloudflareTransport && hasLive ? "import { connectCloudflareFateStream } from 'cf-fate/client';\n" : ""}${cloudflareHelpers}
 
 type FateAPI = InferFateAPI<typeof fateServer>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nkzw/fate",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "fate is a modern data client for React.",
   "homepage": "https://github.com/nkzw-tech/fate",
   "license": "MIT",