feat: add toStream

Author: rossrobino

.changeset/yummy-yaks-attend.md

@@ -0,0 +1,5 @@
+---
+"ovr": minor
+---
+
+feat: Add `toStream` helper function to create a `ReadableStream` from a `JSX.Element`.

apps/docs/src/server/docs/02-components.md

@@ -123,7 +123,7 @@ function Component() {
 
 ## Running components
 
-To evaluate components (for example, if you aren't using `App` or need to call them separately), you can use the `toGenerator` and `toString` functions.
+To evaluate components (for example, if you aren't using `App` or need to call them separately), you can use these functions.
 
 ### toGenerator
 
@@ -141,6 +141,22 @@ for await (const chunk of gen) {
 }
 ```
 
+### toStream
+
+Turn a `JSX.Element` into a `ReadableStream<Uint8Array>`, this pipes the result of `toGenerator` into a `ReadableStream`.
+
+```tsx
+import { toStream } from "ovr";
+
+const Component = () => <p>element</p>;
+
+const stream = toStream(Component);
+
+const response = new Response(stream, {
+	"Content-Type": "text/html; charset=utf-8",
+});
+```
+
 ### toString
 
 Convert any `JSX.Element` into a `string` of HTML with `toString`. This runs `toGenerator` joins the results into a single string.

packages/ovr/src/app/context.ts

@@ -1,5 +1,5 @@
 import { Chunk } from "../jsx/chunk/index.js";
-import { type JSX, toGenerator } from "../jsx/index.js";
+import { type JSX, toStream } from "../jsx/index.js";
 import type { Params, Route } from "../trie/index.js";
 import { hash } from "../util/hash.js";
 import {
@@ -80,9 +80,6 @@ export class Context<P extends Params = Params> {
 	/** Check if the `Response` has been built already */
 	#finalized = false;
 
-	/** Used across requests */
-	static readonly #encoder = new TextEncoder();
-
 	static readonly #headClose = "</head>";
 	static readonly #bodyClose = "</body>";
 
@@ -242,7 +239,7 @@ export class Context<P extends Params = Params> {
 			Page = this.#layouts[i]!({ children: Page });
 		}
 
-		let gen: AsyncGenerator<Chunk, void>;
+		let stream: ReadableStream<Uint8Array>;
 
 		if (this.base) {
 			// inject into base
@@ -265,37 +262,17 @@ export class Context<P extends Params = Params> {
 			elements[3] = bodyParts[0];
 			elements.push(Page, Context.#bodyClose + bodyParts[1]);
 
-			gen = toGenerator(
+			stream = toStream(
 				elements.map((el) =>
 					typeof el === "string" ? new Chunk(el, true) : el,
 				),
 			);
 		} else {
 			// HTML partial - just use the layouts + page
-			gen = toGenerator(Page);
+			stream = toStream(Page);
 		}
 
-		this.html(
-			new ReadableStream<Uint8Array>({
-				async pull(c) {
-					const result = await gen.next();
-
-					if (result.done) {
-						c.close();
-						gen.return();
-						return;
-					}
-
-					// need to encode for Node JS (ex: during prerendering)
-					c.enqueue(Context.#encoder.encode(result.value.value));
-				},
-
-				cancel() {
-					gen.return();
-				},
-			}),
-			status,
-		);
+		this.html(stream, status);
 	}
 
 	/**

packages/ovr/src/index.ts

@@ -1,4 +1,4 @@
-export { jsx, toGenerator, toString, type JSX } from "./jsx/index.js";
+export { jsx, toGenerator, toStream, toString, type JSX } from "./jsx/index.js";
 export { Chunk } from "./jsx/chunk/index.js";
 export { Trie, Route } from "./trie/index.js";
 export { App, type Middleware } from "./app/index.js";

packages/ovr/src/jsx/index.ts

@@ -109,7 +109,7 @@ export async function* Fragment(props: { children?: JSX.Element } = {}) {
 
 /**
  * @param element
- * @yields Chunks of HTML as the `Element` resolves.
+ * @yields `Chunk`s of HTML as the `Element` resolves.
  */
 export async function* toGenerator(
 	element: JSX.Element,
@@ -233,3 +233,39 @@ export async function* toGenerator(
  */
 export const toString = async (element: JSX.Element) =>
 	(await Array.fromAsync(toGenerator(element))).join("");
+
+/** Single encoder to use across requests. */
+const encoder = new TextEncoder();
+
+/**
+ * `toGenerator` piped into a `ReadableStream`.
+ * Use `toGenerator` when possible to avoid the overhead of the stream.
+ *
+ * @param element
+ * @returns `ReadableStream` of HTML
+ */
+export const toStream = (element: JSX.Element) => {
+	const gen = toGenerator(element);
+
+	return new ReadableStream<Uint8Array>({
+		async pull(c) {
+			const result = await gen.next();
+
+			if (result.done) {
+				c.close();
+				gen.return();
+				return;
+			}
+
+			c.enqueue(
+				// need to encode for Node JS (ex: during prerendering)
+				// faster than piping through a `TextEncoderStream`
+				encoder.encode(result.value.value),
+			);
+		},
+
+		cancel() {
+			gen.return();
+		},
+	});
+};