feat: Add .json()/.text()/.html()/.stream() context helpers

marvinhagemeister · marvinhagemeister · commit b2b784e9a401 · 2025-11-11T15:31:45.000+01:00
diff --git a/packages/fresh/src/context.ts b/packages/fresh/src/context.ts
@@ -27,6 +27,7 @@ import {
   renderRouteComponent,
 } from "./render.ts";
 import { renderToString } from "preact-render-to-string";
+import { isAsyncIterable, isIterable, isThenable } from "./utils.ts";
 
 export interface Island {
   file: string;
@@ -258,11 +259,7 @@ export class Context<State> {
       appVNode = appChild ?? h(Fragment, null);
     }
 
-    const headers = init.headers !== undefined
-      ? init.headers instanceof Headers
-        ? init.headers
-        : new Headers(init.headers)
-      : new Headers();
+    const headers = getHeadersFromInit(init);
 
     headers.set("Content-Type", "text/html; charset=utf-8");
     const responseInit: ResponseInit = {
@@ -376,4 +373,165 @@ export class Context<State> {
     });
     return new Response(html, responseInit);
   }
+
+  /**
+   * Respond with text. Sets `Content-Type: text/plain`.
+   * ```tsx
+   * ctx.text("Hello World!");
+   * ```
+   */
+  text(content: string, init?: ResponseInit) {
+    const headers = getHeadersFromInit(init);
+    headers.set("Content-Type", "text/plain; charset=utf-8");
+
+    return new Response(content, { ...init, headers });
+  }
+
+  /**
+   * Respond with html string. Sets `Content-Type: text/html`.
+   * ```tsx
+   * ctx.html("<h1>foo</h1>");
+   * ```
+   */
+  html(content: string, init?: ResponseInit) {
+    const headers = getHeadersFromInit(init);
+    headers.set("Content-Type", "text/html; charset=utf-8");
+
+    return new Response(content, { ...init, headers });
+  }
+
+  /**
+   * Respond with json string, same as `Response.json()`. Sets
+   * `Content-Type: application/json`.
+   * ```tsx
+   * ctx.json({ foo: 123 });
+   * ```
+   */
+  // deno-lint-ignore no-explicit-any
+  json(content: any, init?: ResponseInit) {
+    return Response.json(content, init);
+  }
+
+  /**
+   * Helper to manually enqueue chunks. Encodes text automatically
+   * ```tsx
+   * ctx.stream((controller) => {
+   *   controller.enqueue("foo");
+   *   controller.enqueue("bar");
+   * });
+   * ```
+   * Async works too:
+   *
+   * ```tsx
+   * ctx.stream(async (controller, signal) => {
+   *   controller.enqueue("foo");
+   *   await new Promise(r => setTimeout(r, 1000));
+   *   if (signal.aborted) return;
+   *   controller.enqueue("bar");
+   * });
+   * ```
+   *
+   * Can also be used with sync and async generator
+   * ```tsx
+   * ctx.stream(function* gen() {
+   *   yield "foo";
+   *   yield "bar";
+   * });
+   * ```
+   */
+  stream<U extends string | Uint8Array>(
+    stream: StreamFn<U>,
+    init?: ResponseInit,
+  ): Response {
+    const body = runStreamFn(stream, this.req.signal);
+    return new Response(body, init);
+  }
+}
+
+function getHeadersFromInit(init?: ResponseInit) {
+  if (init === undefined) {
+    return new Headers();
+  }
+
+  return init.headers !== undefined
+    ? init.headers instanceof Headers ? init.headers : new Headers(init.headers)
+    : new Headers();
+}
+
+export type StreamFn<T> = (
+  controller: ReadableStreamDefaultController<T>,
+  signal: AbortSignal,
+) =>
+  | void
+  | Iterable<T, void, unknown>
+  | Promise<void>
+  | AsyncIterable<T, void, unknown>;
+
+type ChunkEncodeFn<T> = (
+  controller: ReadableStreamDefaultController<Uint8Array<ArrayBuffer>>,
+  chunk: T | undefined,
+) => void;
+
+function runStreamFn<T>(
+  fn: StreamFn<T>,
+  signal: AbortSignal,
+): ReadableStream<Uint8Array<ArrayBuffer>> {
+  return new ReadableStream<Uint8Array<ArrayBuffer>>({
+    async start(controller) {
+      const wrapped = wrapStreamController(
+        controller,
+        enqueueEncodedChunk,
+      );
+      const result = fn(wrapped, signal);
+
+      if (isIterable(result)) {
+        for (const chunk of result) {
+          enqueueEncodedChunk(controller, chunk);
+        }
+      } else if (isAsyncIterable(result)) {
+        for await (const chunk of result) {
+          enqueueEncodedChunk(controller, chunk);
+        }
+      } else if (isThenable(result)) {
+        await result;
+      }
+
+      controller.close();
+    },
+  });
+}
+
+function wrapStreamController<T>(
+  controller: ReadableStreamDefaultController<Uint8Array<ArrayBuffer>>,
+  encode: ChunkEncodeFn<T>,
+): ReadableStreamDefaultController<T> {
+  return {
+    get desiredSize() {
+      return controller.desiredSize;
+    },
+    close: () => controller.close,
+    enqueue(chunk) {
+      encode(controller, chunk);
+    },
+    error: (err) => controller.error(err),
+  };
+}
+
+const ENCODER = new TextEncoder();
+
+function enqueueEncodedChunk<T>(
+  controller: ReadableStreamDefaultController<Uint8Array<ArrayBuffer>>,
+  chunk: T | undefined,
+) {
+  if (chunk === undefined) {
+    return controller.enqueue(undefined);
+  }
+
+  if (chunk instanceof Uint8Array) {
+    // deno-lint-ignore no-explicit-any
+    controller.enqueue(chunk as any);
+  } else {
+    const raw = ENCODER.encode(String(chunk));
+    controller.enqueue(raw);
+  }
 }
diff --git a/packages/fresh/src/context_test.tsx b/packages/fresh/src/context_test.tsx
@@ -106,3 +106,113 @@ Deno.test("ctx.route - should contain matched route", async () => {
   await server.get("/foo/123");
   expect(route).toEqual("/foo/:id");
 });
+
+Deno.test("ctx.text()", async () => {
+  const app = new App()
+    .get("/", (ctx) => ctx.text("foobar"));
+
+  const server = new FakeServer(app.handler());
+  const res = await server.get("/");
+
+  expect(res.headers.get("Content-Type")).toEqual("text/plain; charset=utf-8");
+  const text = await res.text();
+  expect(text).toEqual("foobar");
+});
+
+Deno.test("ctx.html()", async () => {
+  const app = new App()
+    .get("/", (ctx) => ctx.html("<h1>foo</h1>"));
+
+  const server = new FakeServer(app.handler());
+  const res = await server.get("/");
+
+  expect(res.headers.get("Content-Type")).toEqual("text/html; charset=utf-8");
+  const text = await res.text();
+  expect(text).toEqual("<h1>foo</h1>");
+});
+
+Deno.test("ctx.json()", async () => {
+  const app = new App()
+    .get("/", (ctx) => ctx.json({ foo: 123 }));
+
+  const server = new FakeServer(app.handler());
+  const res = await server.get("/");
+
+  expect(res.headers.get("Content-Type")).toEqual("application/json");
+  const text = await res.text();
+  expect(text).toEqual('{"foo":123}');
+});
+
+Deno.test("ctx.stream() - empty callback", async () => {
+  const app = new App()
+    .get("/", (ctx) => ctx.stream(() => {}));
+
+  const server = new FakeServer(app.handler());
+  const res = await server.get("/");
+  const text = await res.text();
+  expect(text).toEqual("");
+});
+
+Deno.test("ctx.stream() - enqueue values", async () => {
+  const app = new App()
+    .get("/", (ctx) =>
+      ctx.stream((controller) => {
+        controller.enqueue("foo");
+        controller.enqueue(new TextEncoder().encode("bar"));
+      }));
+
+  const server = new FakeServer(app.handler());
+  const res = await server.get("/");
+  const text = await res.text();
+  expect(text).toEqual("foobar");
+});
+
+Deno.test("ctx.stream() - enqueue sync", async () => {
+  const app = new App()
+    .get("/", (ctx) =>
+      ctx.stream((controller) => {
+        controller.enqueue("foo");
+        controller.enqueue("bar");
+      }));
+
+  const server = new FakeServer(app.handler());
+  const res = await server.get("/");
+  const text = await res.text();
+  expect(text).toEqual("foobar");
+});
+
+Deno.test("ctx.stream() - enqueue async", async () => {
+  const app = new App()
+    .get("/", (ctx) =>
+      ctx.stream(async (controller) => {
+        controller.enqueue("foo");
+        await new Promise((r) => setTimeout(r, 50));
+        controller.enqueue("bar");
+      }));
+
+  const server = new FakeServer(app.handler());
+  const res = await server.get("/");
+  const text = await res.text();
+  expect(text).toEqual("foobar");
+});
+
+Deno.test("ctx.stream() - support cancelling stream", async () => {
+  const app = new App()
+    .get("/", (ctx) =>
+      ctx.stream(async (controller, signal) => {
+        controller.enqueue("foo");
+        await new Promise((r) => setTimeout(r, 300));
+        if (signal.aborted) return;
+        controller.enqueue("bar");
+      }));
+
+  const server = new FakeServer(app.handler());
+  const abort = new AbortController();
+  const res = await server.get("/", { signal: abort.signal });
+
+  const p = res.text();
+  await new Promise((r) => setTimeout(r, 100));
+  abort.abort();
+
+  expect(await p).toEqual("foo");
+});
diff --git a/packages/fresh/src/mod.ts b/packages/fresh/src/mod.ts
@@ -15,7 +15,7 @@ export { csrf, type CsrfOptions } from "./middlewares/csrf.ts";
 export { cors, type CORSOptions } from "./middlewares/cors.ts";
 export { csp, type CSPOptions } from "./middlewares/csp.ts";
 export type { FreshConfig, ResolvedFreshConfig } from "./config.ts";
-export type { Context, FreshContext, Island } from "./context.ts";
+export type { Context, FreshContext, Island, StreamFn } from "./context.ts";
 export { createDefine, type Define } from "./define.ts";
 export type { Method } from "./router.ts";
 export { HttpError } from "./error.ts";
diff --git a/packages/fresh/src/utils.ts b/packages/fresh/src/utils.ts
@@ -283,3 +283,22 @@ function maybeDot(spec: string): string {
 export function isLazy<T>(value: MaybeLazy<T>): value is Lazy<T> {
   return typeof value === "function";
 }
+
+export function isThenable(value: unknown): value is Promise<unknown> {
+  return value !== null && typeof value === "object" && "then" in value &&
+    typeof value.then === "function";
+}
+
+export function isIterable<T>(value: unknown): value is Iterable<T> {
+  return value !== null && typeof value === "object" &&
+    Symbol.iterator in value &&
+    typeof value[Symbol.iterator] === "function";
+}
+
+export function isAsyncIterable<T>(
+  value: unknown,
+): value is AsyncIterable<T> {
+  return value !== null && typeof value === "object" &&
+    Symbol.asyncIterator in value &&
+    typeof value[Symbol.asyncIterator] === "function";
+}
