void-fate 0.0.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Nakazawa Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# void-fate
+
+Void adapter for [fate](https://github.com/nkzw-tech/fate).
+
+`void-fate` contains the server route helpers, SSE live transport, and React
+client wrapper needed to use fate in a Void app without keeping adapter glue in
+application code.
+
+## Install
+
+```sh
+pnpm add @nkzw/fate react-fate void-fate void
+```
+
+## Vite
+
+Use the regular `react-fate` Vite plugin with the Void transport.
+
+```ts
+import { fate } from 'react-fate/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    fate({
+      module: './src/fate/server.ts',
+      transport: 'void',
+    }),
+  ],
+});
+```
+
+## Server
+
+Create a Fate live publish facade and pass its `live` instance to the fate
+server. Define the Void stream separately so `defineLiveStream` is called once
+from a single server-only module.
+
+```ts
+// src/fate/live.ts
+import { defineLiveStream } from 'void/live';
+
+export const fateStream = defineLiveStream({
+  allowAnonymousControl: true,
+  id: 'fate',
+});
+```
+
+```ts
+// src/fate/server.ts
+import { createFateServer } from '@nkzw/fate/server';
+import { createVoidFateLive } from 'void-fate/server';
+
+export const fateLive = createVoidFateLive();
+
+export const fateServer = createFateServer({
+  live: fateLive.live,
+  // context,
+  // roots,
+  // sources,
+});
+```
+
+## Routes
+
+Add one route for RPC requests and one route for the SSE live transport.
+
+```ts
+// routes/fate.ts
+import { defineVoidFateRoute } from 'void-fate/server';
+import { fateStream } from '../src/fate/live.ts';
+import { fateLive, fateServer } from '../src/fate/server.ts';
+
+export const { GET, POST } = defineVoidFateRoute(fateServer, fateLive, {
+  stream: fateStream,
+});
+```
+
+```ts
+// routes/fate-live.ts
+import { defineVoidFateLiveRoute } from 'void-fate/server';
+import { fateStream } from '../src/fate/live.ts';
+
+export const { GET, POST } = defineVoidFateLiveRoute(fateStream);
+```
+
+The default paths are `/fate` for RPC and `/fate-live` for live updates.
+
+## React
+
+Use `VoidFateClient` in your app layout. The generated fate client is still
+provided by the `react-fate` Vite plugin.
+
+```tsx
+import type { ReactNode } from 'react';
+import { VoidFateClient } from 'void-fate/react';
+
+export default function Layout({
+  children,
+  origin,
+  userId,
+}: {
+  children: ReactNode;
+  origin: string;
+  userId?: string;
+}) {
+  return (
+    <VoidFateClient origin={origin} userId={userId}>
+      {children}
+    </VoidFateClient>
+  );
+}
+```
+
+## Custom Paths
+
+The defaults are intended to work without configuration. If your Void routes use
+different paths, pass the same values to the server and client helpers.
+
+```tsx
+<VoidFateClient livePath="/custom-live" origin={origin} rpcPath="/custom-fate" userId={userId}>
+  {children}
+</VoidFateClient>
+```
+
+`void-fate` uses Server-Sent Events for live updates. It does not use
+WebSockets.

package/lib/index.d.mts

@@ -0,0 +1,2 @@
+import { VoidFateLive, VoidFateLiveOptions, VoidFateRouteOptions, createVoidFateLive, defaultVoidFateLivePath, defaultVoidFateRpcPath, defineVoidFateLiveRoute, defineVoidFateRoute } from "./server.mjs";
+export { type VoidFateLive, type VoidFateLiveOptions, type VoidFateRouteOptions, createVoidFateLive, defaultVoidFateLivePath, defaultVoidFateRpcPath, defineVoidFateLiveRoute, defineVoidFateRoute };

package/lib/index.mjs

@@ -0,0 +1,2 @@
+import { createVoidFateLive, defaultVoidFateLivePath, defaultVoidFateRpcPath, defineVoidFateLiveRoute, defineVoidFateRoute } from "./server.mjs";
+export { createVoidFateLive, defaultVoidFateLivePath, defaultVoidFateRpcPath, defineVoidFateLiveRoute, defineVoidFateRoute };

package/lib/react.d.mts

@@ -0,0 +1,32 @@
+import { ReactNode } from "react";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/react.d.ts
+type VoidFateClientProps = {
+  children: ReactNode;
+  fetch?: typeof fetch;
+  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+  livePath?: string;
+  liveRetryMs?: number;
+  liveUrl?: string | URL;
+  onLiveError?: (error: unknown) => void;
+  origin?: string | URL;
+  rpcPath?: string;
+  url?: string | URL;
+  userId?: null | string;
+};
+declare function VoidFateClient({
+  children,
+  fetch,
+  headers,
+  livePath,
+  liveRetryMs,
+  liveUrl,
+  onLiveError,
+  origin,
+  rpcPath,
+  url,
+  userId
+}: VoidFateClientProps): _$react_jsx_runtime0.JSX.Element;
+//#endregion
+export { VoidFateClient, VoidFateClientProps };

package/lib/react.mjs

@@ -0,0 +1,35 @@
+import { useMemo } from "react";
+import { FateClient } from "react-fate";
+import { createFateClient } from "react-fate/client";
+import { jsx } from "react/jsx-runtime";
+//#region src/react.tsx
+function VoidFateClient({ children, fetch, headers, livePath, liveRetryMs, liveUrl, onLiveError, origin, rpcPath, url, userId }) {
+	return /* @__PURE__ */ jsx(FateClient, {
+		client: useMemo(() => createFateClient({
+			fetch,
+			headers,
+			livePath,
+			liveRetryMs,
+			liveUrl,
+			onLiveError,
+			origin,
+			rpcPath,
+			url,
+			userId
+		}), [
+			fetch,
+			headers,
+			livePath,
+			liveRetryMs,
+			liveUrl,
+			onLiveError,
+			origin,
+			rpcPath,
+			url,
+			userId
+		]),
+		children
+	}, userId ?? void 0);
+}
+//#endregion
+export { VoidFateClient };

package/lib/server.d.mts

@@ -0,0 +1,42 @@
+import { FateServer, LiveEventBus } from "@nkzw/fate/server";
+import * as _$void from "void";
+
+//#region src/server.d.ts
+type VoidEnv = Record<string, unknown>;
+type VoidFatePublishOptions = {
+  eventId?: string;
+  type?: string;
+};
+type VoidFateLiveStream = {
+  connect(context: unknown, options?: unknown): Promise<Response>;
+  control(context: unknown, options?: unknown): Promise<Response>;
+  withEnv(env: unknown): {
+    publish(topic: string, data: unknown, options?: VoidFatePublishOptions): Promise<void>;
+  };
+};
+type FateLiveContext = {
+  env: VoidEnv;
+  pending: Array<Promise<void>>;
+  stream: VoidFateLiveStream;
+};
+type VoidFateLiveOptions = Record<never, never>;
+type VoidFateRouteOptions = {
+  stream: VoidFateLiveStream;
+};
+type VoidFateLive = Readonly<{
+  live: LiveEventBus;
+  withContext: <T>(context: Omit<FateLiveContext, 'pending'>, callback: () => T) => T;
+}>;
+declare const defaultVoidFateRpcPath = "/fate";
+declare const defaultVoidFateLivePath = "/fate-live";
+declare function createVoidFateLive(_options?: VoidFateLiveOptions): VoidFateLive;
+declare function defineVoidFateRoute<AdapterContext>(server: FateServer<unknown, AdapterContext>, live: VoidFateLive, options: VoidFateRouteOptions): {
+  GET: _$void.TypedHandler<{}, never>;
+  POST: _$void.TypedHandler<{}, never>;
+};
+declare function defineVoidFateLiveRoute(stream: VoidFateLiveStream): {
+  GET: _$void.TypedHandler<{}, never>;
+  POST: _$void.TypedHandler<{}, never>;
+};
+//#endregion
+export { VoidFateLive, VoidFateLiveOptions, VoidFateLiveStream, VoidFateRouteOptions, createVoidFateLive, defaultVoidFateLivePath, defaultVoidFateRpcPath, defineVoidFateLiveRoute, defineVoidFateRoute };

package/lib/server.mjs

@@ -0,0 +1,154 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createFateFetchHandler, liveConnectionTopic, liveEntityTopic, liveGlobalConnectionTopic } from "@nkzw/fate/server";
+import { defineHandler } from "void";
+//#region src/server.ts
+const defaultVoidFateRpcPath = "/fate";
+const defaultVoidFateLivePath = "/fate-live";
+const isPromiseLike = (value) => (typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function";
+function createVoidFateLive(_options = {}) {
+	const contextStore = new AsyncLocalStorage();
+	const publish = (topic, data, options) => {
+		const context = contextStore.getStore();
+		if (!context) return;
+		const promise = context.stream.withEnv(context.env).publish(topic, data, options).catch(() => void 0);
+		context.pending.push(promise);
+	};
+	const publishEntity = (type, id, options = {}) => {
+		publish(liveEntityTopic(type, id), {
+			changed: options.changed,
+			data: options.data,
+			id
+		}, {
+			eventId: options.eventId,
+			type: options.type ?? "update"
+		});
+	};
+	const publishConnection = (procedure, args, type, options = {}) => {
+		publish(args ? liveConnectionTopic(procedure, args) : liveGlobalConnectionTopic(procedure), {
+			cursor: options.cursor,
+			id: options.id,
+			node: options.node,
+			nodeType: options.nodeType,
+			targetCursor: options.targetCursor
+		}, {
+			eventId: options.eventId,
+			type
+		});
+	};
+	const withContext = (context, callback) => contextStore.run({
+		...context,
+		pending: []
+	}, () => {
+		const liveContext = contextStore.getStore();
+		const result = callback();
+		if (isPromiseLike(result) || liveContext.pending.length > 0) return Promise.resolve(result).then(async (value) => {
+			if (liveContext.pending.length > 0) await Promise.allSettled(liveContext.pending);
+			return value;
+		});
+		return result;
+	});
+	return {
+		live: {
+			connection(procedure, args) {
+				return {
+					appendEdge(nodeType, id, options) {
+						publishConnection(procedure, args, "appendEdge", {
+							...options,
+							id,
+							nodeType
+						});
+					},
+					appendNode(nodeType, id, options) {
+						publishConnection(procedure, args, "appendNode", {
+							...options,
+							id,
+							nodeType
+						});
+					},
+					deleteEdge(nodeType, id, options) {
+						publishConnection(procedure, args, "deleteEdge", {
+							...options,
+							id,
+							nodeType
+						});
+					},
+					emit(type, options) {
+						publishConnection(procedure, args, type, options);
+					},
+					insertEdgeAfter(nodeType, id, targetCursor, options) {
+						publishConnection(procedure, args, "insertEdgeAfter", {
+							...options,
+							id,
+							nodeType,
+							targetCursor
+						});
+					},
+					insertEdgeBefore(nodeType, id, targetCursor, options) {
+						publishConnection(procedure, args, "insertEdgeBefore", {
+							...options,
+							id,
+							nodeType,
+							targetCursor
+						});
+					},
+					invalidate(options) {
+						publishConnection(procedure, args, "invalidate", options);
+					},
+					prependEdge(nodeType, id, options) {
+						publishConnection(procedure, args, "prependEdge", {
+							...options,
+							id,
+							nodeType
+						});
+					},
+					prependNode(nodeType, id, options) {
+						publishConnection(procedure, args, "prependNode", {
+							...options,
+							id,
+							nodeType
+						});
+					}
+				};
+			},
+			delete(type, id, options) {
+				publishEntity(type, id, {
+					...options,
+					type: "delete"
+				});
+			},
+			emit: publishEntity,
+			subscribe() {
+				throw new Error("void-fate: direct live subscriptions are handled by void/live.");
+			},
+			subscribeConnection() {
+				throw new Error("void-fate: direct live subscriptions are handled by void/live.");
+			},
+			update(type, id, options) {
+				publishEntity(type, id, {
+					...options,
+					type: "update"
+				});
+			}
+		},
+		withContext
+	};
+}
+function defineVoidFateRoute(server, live, options) {
+	const handleFate = createFateFetchHandler(server);
+	const handle = (context) => live.withContext({
+		env: context.env,
+		stream: options.stream
+	}, () => handleFate(context.req.raw, context));
+	return {
+		GET: defineHandler(handle),
+		POST: defineHandler(handle)
+	};
+}
+function defineVoidFateLiveRoute(stream) {
+	return {
+		GET: defineHandler((context) => stream.connect(context)),
+		POST: defineHandler((context) => stream.control(context))
+	};
+}
+//#endregion
+export { createVoidFateLive, defaultVoidFateLivePath, defaultVoidFateRpcPath, defineVoidFateLiveRoute, defineVoidFateRoute };

package/package.json

@@ -1,7 +1,65 @@
 {
   "name": "void-fate",
-  "version": "0.0.0",
-  "description": "",
+  "version": "1.0.0",
+  "description": "Void adapter for fate.",
+  "homepage": "https://github.com/nkzw-tech/fate",
+  "license": "MIT",
+  "author": {
+    "name": "Christoph Nakazawa",
+    "email": "christoph.pojer@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nkzw-tech/fate",
+    "directory": "packages/void-fate"
+  },
+  "files": [
+    "lib"
+  ],
   "type": "module",
-  "main": "index.js"
+  "main": "./lib/index.mjs",
+  "types": "./lib/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.mts",
+      "@nkzw/source": "./src/index.ts",
+      "default": "./lib/index.mjs"
+    },
+    "./react": {
+      "types": "./lib/react.d.mts",
+      "@nkzw/source": "./src/react.tsx",
+      "default": "./lib/react.mjs"
+    },
+    "./server": {
+      "types": "./lib/server.d.mts",
+      "@nkzw/source": "./src/server.ts",
+      "default": "./lib/server.mjs"
+    }
+  },
+  "dependencies": {
+    "@nkzw/fate": "^1.0.0",
+    "react-fate": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "react": "^19.2.6",
+    "void": "^0.7.5"
+  },
+  "peerDependencies": {
+    "@nkzw/fate": "^1.0.0-rc.0",
+    "react": "^19.2.0",
+    "react-fate": "^1.0.0-rc.0",
+    "void": "^0.7.5"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-fate": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "vp pack -d lib --target=node24 src/index.ts src/react.tsx src/server.ts"
+  }
 }