void 0.7.2 → 0.7.4

package/dist/runtime/sse.mjs

@@ -0,0 +1,172 @@
+//#region src/runtime/sse.ts
+const DEFAULT_KEEP_ALIVE_INTERVAL_MS = 15e3;
+const DEFAULT_KEEP_ALIVE_COMMENT = "keep-alive";
+var SseStreamClosedError = class extends Error {
+	constructor(message = "sse: stream is closed.") {
+		super(message);
+		this.name = "SseStreamClosedError";
+	}
+};
+function formatSse(message) {
+	const textMessage = {
+		event: message.event,
+		id: message.id,
+		retry: message.retry
+	};
+	if ("data" in message) textMessage.data = serializeData(message.data);
+	return formatSseText(textMessage);
+}
+function formatSseText(message) {
+	const lines = [];
+	if (message.id != null) {
+		assertControlField("id", message.id);
+		lines.push(`id: ${message.id}`);
+	}
+	if (message.event != null) {
+		assertControlField("event", message.event);
+		lines.push(`event: ${message.event}`);
+	}
+	if (message.retry != null) {
+		assertRetry(message.retry);
+		lines.push(`retry: ${message.retry}`);
+	}
+	if ("data" in message) {
+		if (typeof message.data !== "string") throw new Error("sse: data must be a string.");
+		for (const line of splitLines(message.data)) lines.push(`data: ${line}`);
+	}
+	return `${lines.join("\n")}\n\n`;
+}
+function getLastEventId(request) {
+	return request.headers.get("Last-Event-ID");
+}
+function eventStream(start, options = {}) {
+	const encoder = new TextEncoder();
+	const { readable, writable } = new TransformStream();
+	const writer = writable.getWriter();
+	const signalController = new AbortController();
+	const headers = buildSseHeaders(options.headers);
+	const keepAlive = normalizeKeepAlive(options.keepAlive);
+	let keepAliveTimer;
+	let closedOnce = false;
+	let closeResolve;
+	const closed = new Promise((resolve) => {
+		closeResolve = resolve;
+	});
+	const markClosed = () => {
+		if (closedOnce) return;
+		closedOnce = true;
+		if (!signalController.signal.aborted) signalController.abort();
+		if (keepAliveTimer != null) {
+			clearInterval(keepAliveTimer);
+			keepAliveTimer = void 0;
+		}
+		closeResolve();
+	};
+	async function close() {
+		if (closedOnce) return;
+		markClosed();
+		await writer.close().catch(() => {});
+	}
+	async function fail(error) {
+		if (closedOnce) return;
+		markClosed();
+		await writer.abort(error).catch(() => {});
+	}
+	async function write(text) {
+		if (closedOnce) throw new SseStreamClosedError();
+		try {
+			await writer.write(encoder.encode(text));
+		} catch {
+			await close();
+			throw new SseStreamClosedError();
+		}
+	}
+	const stream = {
+		signal: signalController.signal,
+		closed,
+		send(message) {
+			return write(formatSse(message));
+		},
+		comment(text = "") {
+			return write(formatComment(text));
+		},
+		close
+	};
+	writer.closed.catch(() => {
+		close();
+	});
+	if (options.signal?.aborted) close();
+	else options.signal?.addEventListener("abort", () => void close(), { once: true });
+	if (keepAlive) keepAliveTimer = setInterval(() => {
+		stream.comment(keepAlive.comment).catch(() => close());
+	}, keepAlive.intervalMs);
+	queueMicrotask(() => {
+		(async () => {
+			try {
+				await start(stream);
+				await close();
+			} catch (error) {
+				await fail(error);
+			}
+		})();
+	});
+	return new Response(readable, { headers });
+}
+function buildSseHeaders(headers) {
+	const result = new Headers(headers);
+	if (!result.has("Content-Type")) result.set("Content-Type", "text/event-stream; charset=utf-8");
+	if (!result.has("Cache-Control")) result.set("Cache-Control", "no-cache, no-transform");
+	if (!result.has("X-Accel-Buffering")) result.set("X-Accel-Buffering", "no");
+	return result;
+}
+function normalizeKeepAlive(keepAlive) {
+	if (keepAlive === false) return null;
+	if (keepAlive === true || keepAlive == null) return {
+		intervalMs: DEFAULT_KEEP_ALIVE_INTERVAL_MS,
+		comment: DEFAULT_KEEP_ALIVE_COMMENT
+	};
+	const intervalMs = keepAlive.intervalMs ?? DEFAULT_KEEP_ALIVE_INTERVAL_MS;
+	if (!Number.isFinite(intervalMs) || intervalMs <= 0) throw new Error("sse: keepAlive.intervalMs must be a positive finite number.");
+	return {
+		intervalMs,
+		comment: keepAlive.comment ?? DEFAULT_KEEP_ALIVE_COMMENT
+	};
+}
+function formatComment(text) {
+	if (typeof text !== "string") throw new Error("sse: comment text must be a string.");
+	return `${splitLines(text).map((line) => `: ${line}`).join("\n")}\n\n`;
+}
+function assertControlField(name, value) {
+	if (typeof value !== "string") throw new Error(`sse: ${name} must be a string.`);
+	if (hasControlFieldSeparator(value)) throw new Error(`sse: ${name} must not contain CR, LF, or NUL characters.`);
+}
+function hasControlFieldSeparator(value) {
+	return value.includes("\r") || value.includes("\n") || value.includes("\0");
+}
+function assertRetry(value) {
+	if (!Number.isInteger(value) || value < 0) throw new Error("sse: retry must be a non-negative integer.");
+}
+function isBinaryData(data) {
+	return data instanceof ArrayBuffer || ArrayBuffer.isView(data) || typeof Blob !== "undefined" && data instanceof Blob || typeof File !== "undefined" && data instanceof File;
+}
+function serializeData(data) {
+	if (typeof data === "string") return data;
+	if (data == null) return data === null ? "null" : throwDataSerializationError(data);
+	if (typeof data === "function" || typeof data === "symbol") return throwDataSerializationError(data);
+	if (isBinaryData(data)) throw new Error("sse: binary data is not supported.");
+	try {
+		const serialized = JSON.stringify(data);
+		if (typeof serialized !== "string") return throwDataSerializationError(data);
+		return serialized;
+	} catch (error) {
+		throw new Error(`sse: data must be JSON-serializable. ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+function throwDataSerializationError(data) {
+	throw new Error(`sse: unsupported data value ${String(data)}.`);
+}
+function splitLines(value) {
+	return value.split(/\r\n|\r|\n/);
+}
+//#endregion
+export { SseStreamClosedError, eventStream, formatSse, formatSseText, getLastEventId };

package/dist/{scan-C6HMEIdW.mjs → scan-QtRTdh94.mjs}

@@ -1,6 +1,6 @@
 import { a as join, t as basename } from "./pathe.M-eThtNZ-D-kmWkCS.mjs";
 import { n as globSync, t as glob } from "./dist-DUyXJLkq.mjs";
-import { d as isIdentifier, f as isLiteral, m as isObjectExpression, u as isCallExpression } from "./plugin-inference-oZ6Ybu2_.mjs";
+import { d as isCallExpression, f as isIdentifier, h as isObjectExpression, p as isLiteral } from "./plugin-inference-CCtRkt9O.mjs";
 import { o as parseRouteFilename, s as parseWebSocketFilename, t as scanPages } from "./scan-Ba4hFwlH.mjs";
 import { readFileSync } from "node:fs";
 import { parseSync } from "vite";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "void",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/voidzero-dev/void.git",
@@ -31,6 +31,11 @@
     "#self/remote/binding-handler": "./dist/runtime/remote/binding-handler.mjs",
     "#self/response": "./dist/runtime/response.mjs",
     "#self/sandbox": "./dist/runtime/sandbox.mjs",
+    "#self/sse": "./dist/runtime/sse.mjs",
+    "#self/sse/client": "./dist/runtime/sse-client.mjs",
+    "#self/live": "./dist/runtime/live.mjs",
+    "#self/live/client": "./dist/runtime/live-client.mjs",
+    "#self/runtime/live-server": "./dist/runtime/live-server.mjs",
     "#self/runtime/fetch": "./dist/runtime/fetch.mjs",
     "#self/runtime/fetch-stream": "./dist/runtime/fetch-stream.mjs",
     "#self/runtime/migration-handler": "./dist/runtime/migration-handler.mjs",
@@ -86,6 +91,26 @@
       "import": "./dist/runtime/fetch-stream.mjs",
       "require": "./dist/runtime/fetch-stream.mjs"
     },
+    "./sse": {
+      "types": "./dist/runtime/sse.d.mts",
+      "import": "./dist/runtime/sse.mjs",
+      "require": "./dist/runtime/sse.mjs"
+    },
+    "./sse/client": {
+      "types": "./dist/runtime/sse-client.d.mts",
+      "import": "./dist/runtime/sse-client.mjs",
+      "require": "./dist/runtime/sse-client.mjs"
+    },
+    "./live": {
+      "types": "./dist/runtime/live.d.mts",
+      "import": "./dist/runtime/live.mjs",
+      "require": "./dist/runtime/live.mjs"
+    },
+    "./live/client": {
+      "types": "./dist/runtime/live-client.d.mts",
+      "import": "./dist/runtime/live-client.mjs",
+      "require": "./dist/runtime/live-client.mjs"
+    },
     "./ws": {
       "types": "./dist/runtime/ws.d.mts",
       "import": "./dist/runtime/ws.mjs",
@@ -261,15 +286,10 @@
       "require": "./dist/runtime/db-pg.mjs"
     }
   },
-  "scripts": {
-    "build": "node scripts/sync-skill-docs.mjs && vp pack",
-    "dev": "vp pack --watch",
-    "typecheck": "tsgo --noEmit"
-  },
   "dependencies": {
     "@cloudflare/sandbox": "^0.10.0",
     "@cloudflare/vite-plugin": "^1.36.3",
-    "@cloudflare/workers-types": "catalog:",
+    "@cloudflare/workers-types": "^4.20260508.1",
     "@hono/oauth-providers": "^0.8.5",
     "@napi-rs/keyring": "1.3.0",
     "better-auth": "^1.6.9",
@@ -284,35 +304,35 @@
     "ignore": "^7.0.5",
     "jsonc-parser": "3.3.1",
     "pg": "^8.20.0",
-    "wrangler": "catalog:"
+    "wrangler": "^4.90.0"
   },
   "devDependencies": {
-    "@clack/prompts": "catalog:",
+    "@clack/prompts": "^1.3.0",
     "@electric-sql/pglite": "0.4.5",
     "@types/better-sqlite3": "^7.6.13",
-    "@types/node": "catalog:",
+    "@types/node": "^25.6.2",
     "@types/pg": "^8.20.0",
-    "@typescript/native-preview": "catalog:",
+    "@typescript/native-preview": "7.0.0-dev.20260507.1",
     "arktype": "^2.2.0",
     "es-module-lexer": "^2.1.0",
     "estree-walker": "^3.0.3",
     "magic-string": "^0.30.21",
     "ofetch": "2.0.0-alpha.3",
-    "pathe": "catalog:",
+    "pathe": "^2.0.3",
     "pglite-server": "0.1.5",
     "picocolors": "^1.1.1",
     "tinyglobby": "^0.2.16",
     "valibot": "^1.4.0",
-    "vite": "catalog:",
-    "vite-plus": "catalog:",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.1.20",
+    "vite-plus": "^0.1.20",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@void/md": "workspace:*",
     "arktype": ">=2.0.0",
     "valibot": ">=1.0.0-beta.7",
     "vite": "^8.0.0",
-    "zod": "^3.25.0 || ^4.0.0"
+    "zod": "^3.25.0 || ^4.0.0",
+    "@void/md": "0.7.4"
   },
   "peerDependenciesMeta": {
     "@void/md": {
@@ -327,5 +347,10 @@
     "zod": {
       "optional": true
     }
+  },
+  "scripts": {
+    "build": "node scripts/sync-skill-docs.mjs && vp pack",
+    "dev": "vp pack --watch",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/skills/void/docs/guide/live.md

@@ -0,0 +1,230 @@
+---
+outline: deep
+---
+
+# Live Event Streams
+
+`void/live` provides Durable Object-backed fanout over Server-Sent Events. Use it
+when one browser tab needs a single SSE connection that can subscribe and
+unsubscribe from many application topics over time.
+
+Use `void/sse` for request-owned streams where the producer lives inside the same
+route handler. Use `void/live` when later requests, mutations, scheduled jobs, or
+queue consumers need to publish to clients that are already connected.
+
+## Define A Stream
+
+Create a server-only live stream descriptor:
+
+```ts
+// src/live.ts
+import { defineLiveStream } from 'void/live';
+
+export const live = defineLiveStream({
+  id: 'app',
+  allowAnonymousControl: true,
+});
+```
+
+Expose it from a normal route:
+
+```ts
+// routes/live.ts
+import { defineHandler } from 'void';
+import { live } from '../src/live';
+
+export const GET = defineHandler((c) => live.connect(c));
+export const POST = defineHandler((c) => live.control(c));
+```
+
+`GET` opens the SSE connection. `POST` accepts subscribe and unsubscribe control
+operations for that connection.
+
+## Subscribe From The Browser
+
+Use the browser helper from `void/live/client`:
+
+```ts
+import { connectLiveStream } from 'void/live/client';
+
+const stream = connectLiveStream('/live', {
+  withCredentials: true,
+  retryDelay: 1_000,
+  onError(error) {
+    console.error(error);
+  },
+});
+
+const unsubscribePost = await stream.subscribe({
+  id: 'post-card',
+  topic: 'post:12',
+  onEvent(event) {
+    if (event.type === 'updated') {
+      console.log(event.data);
+    }
+  },
+});
+
+const unsubscribeComments = await stream.subscribe({
+  id: 'comments',
+  topic: 'comment:2323',
+});
+
+await unsubscribeComments();
+await unsubscribePost();
+stream.close();
+```
+
+The helper opens one native `EventSource`, waits for it to open, then sends
+batched `POST` control operations. Subscription ids are scoped to the
+connection. Reusing an id replaces the previous subscription with that id. If
+the transport drops, the helper reconnects and resubmits active subscriptions
+with their latest `eventId` as `lastEventId`.
+
+## Publish
+
+Publish from any server-side code that has a Void runtime env:
+
+```ts
+import { live } from '../src/live';
+
+await live.publish(
+  'post:12',
+  { title: 'Updated title' },
+  { type: 'updated', eventId: 'post-12-v8' },
+);
+```
+
+Topics are opaque strings. Payloads are application-owned JSON. `type` and
+`eventId` are copied into the JSON envelope; `void/live` does not interpret
+them, persist them, or use native SSE `id` fields.
+
+If you are outside an active request/runtime context, pass env explicitly:
+
+```ts
+await live.withEnv(env).publish('post:12', { title: 'Updated title' });
+```
+
+## Authorization
+
+Every live connection has an owner. The owner is the identity allowed to send
+control operations for that SSE connection. `connect()` resolves and stores the
+owner; `control()` resolves the owner again and rejects the request if it does
+not match.
+
+The quickstart uses an anonymous stream:
+
+```ts
+export const live = defineLiveStream({
+  id: 'app',
+  allowAnonymousControl: true,
+});
+```
+
+For authenticated streams, pass the same owner key to `connect()` and
+`control()`:
+
+```ts
+return live.connect(c, { owner: `user:${session.userId}` });
+return live.control(c, { owner: `user:${session.userId}` });
+```
+
+If every route should derive ownership the same way, define it once with
+`identifyConnection`:
+
+```ts
+export const live = defineLiveStream({
+  id: 'app',
+  async identifyConnection(ctx) {
+    const session = await getSession(ctx.request);
+    return session ? `user:${session.userId}` : null;
+  },
+});
+```
+
+Then the route handlers can stay thin:
+
+```ts
+export const GET = defineHandler((c) => live.connect(c));
+export const POST = defineHandler((c) => live.control(c));
+```
+
+When `identifyConnection` returns `null` or `undefined`, Void falls back to the
+current authenticated user and uses `user:${user.id}` when the user has a string
+`id`. If neither path produces an owner and `allowAnonymousControl` is not set,
+the request is rejected with `403`.
+
+For stream-local subscription rules, use `onSubscribe`:
+
+```ts
+export const live = defineLiveStream({
+  id: 'app',
+  async onSubscribe(ctx) {
+    const match = /^post:(.+)$/.exec(ctx.topic);
+    if (match && !(await canReadPost(ctx.env, ctx.user, match[1]))) {
+      return new Response('Forbidden', { status: 403 });
+    }
+  },
+});
+```
+
+## Limits
+
+`void/live` is designed for small and medium fanout. By default, a stream allows:
+
+- `256` active subscriptions per browser connection
+- `256` active subscriptions per topic
+- `100` subscribe or unsubscribe operations per control request
+- `100` queued events per connection
+- `64 KiB` per encoded event envelope
+
+A topic is the unit of fanout. For example, if each blog post uses a topic like
+`post:${postId}`, then each post can have up to `256` active live subscribers at
+one time. Other posts use separate topics and have separate limits.
+
+Streams can have many possible topics. Topics are created on demand when clients
+subscribe or publishers send events, so an app with thousands of posts, rooms, or
+documents can use one topic per entity without provisioning them ahead of time.
+The limit applies to each active topic, not to the total number of topic names
+your app might use.
+
+For example, a blog with `10,000` posts can model its live capacity as
+`10,000 posts × up to 256 active subscribers per post topic`.
+
+That shape works because each post topic is independent. A single post with more
+than `256` active live subscribers would need a larger broadcast design.
+
+These limits apply to live subscriptions, not total users or total page views.
+One user with two open tabs may count twice. Disconnected subscriptions are
+pruned, but they can count until the runtime observes that they are stale.
+
+You can lower limits per stream:
+
+```ts
+export const live = defineLiveStream({
+  id: 'app',
+  limits: {
+    maxSubscriptionsPerTopic: 64,
+  },
+});
+```
+
+`maxSubscriptionsPerTopic` cannot be raised above `256`. For larger broadcast
+workloads, shard topics in userland or use a dedicated realtime system.
+
+## Delivery Semantics
+
+`void/live` is an at-most-once live fanout primitive:
+
+- one SSE connection can hold many topic subscriptions
+- publish cost is proportional to subscribers of the topic
+- events are ordered within one topic
+- clients using the raw HTTP protocol must resubscribe after reconnect
+- deploys, rollbacks, Worker restarts, browser reconnects, and network changes
+  can drop live state
+- durable replay, cache invalidation, live queries, and client state management
+  belong in userland
+
+Use an application database, queue, or custom Durable Object for replay. Use
+`eventId` and caller-provided `lastEventId` values as application protocol
+fields when you build that layer.