@hyperspan/framework 1.0.17 → 1.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "Hyperspan Web Framework",
   "main": "src/server.ts",
   "types": "src/server.ts",

package/src/server.test.ts

@@ -15,6 +15,28 @@ test('route fetch() returns a Response', async () => {
   expect(await response.text()).toBe('<h1>Hello World</h1>');
 });
 
+test('route handler returning undefined or null yields 204 No Content', async () => {
+  const withHeader = createRoute().get((context: HS.Context) => {
+    context.res.headers.set('X-Empty', '1');
+  });
+
+  const req = new Request('http://localhost:3000/');
+  let response = await withHeader.fetch(req);
+  expect(response).toBeInstanceOf(Response);
+  expect(response.status).toBe(204);
+  expect(response.headers.get('X-Empty')).toBe('1');
+  expect(await response.text()).toBe('');
+
+  const explicitNull = createRoute().get(() => null);
+  response = await explicitNull.fetch(req);
+  expect(response.status).toBe(204);
+  expect(await response.text()).toBe('');
+
+  const asyncVoid = createRoute().get(async () => undefined);
+  response = await asyncVoid.fetch(req);
+  expect(response.status).toBe(204);
+});
+
 test('server with two routes can return Response from one', async () => {
   const server = await createServer({
     appDir: './app',
@@ -214,6 +236,52 @@ test('createContext() merge() function preserves custom headers with json() meth
   expect(response.headers.get('Content-Type')).toBe('application/json');
 });
 
+test('route returning ReadableStream produces a streaming response', async () => {
+  const route = createRoute().get((_context: HS.Context) => {
+    return new ReadableStream({
+      start(controller) {
+        const enc = new TextEncoder();
+        controller.enqueue(enc.encode('alpha'));
+        controller.enqueue(enc.encode('beta'));
+        controller.close();
+      },
+    });
+  });
+
+  const request = new Request('http://localhost:3000/');
+  const response = await route.fetch(request);
+
+  expect(response).toBeInstanceOf(Response);
+  expect(response.status).toBe(200);
+  expect(response.body).toBeInstanceOf(ReadableStream);
+  expect(response.headers.get('Transfer-Encoding')).toBe('chunked');
+  expect(response.headers.get('Content-Encoding')).toBe('Identity');
+  expect(response.headers.get('Content-Type')).toBe('application/octet-stream');
+  expect(await response.text()).toBe('alphabeta');
+});
+
+test('route returning ReadableStream respects Content-Type set on context.res.headers', async () => {
+  const route = createRoute().get((context: HS.Context) => {
+    context.res.headers.set('Content-Type', 'text/plain; charset=UTF-8');
+    return new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode('ok'));
+        controller.close();
+      },
+    });
+  });
+
+  const request = new Request('http://localhost:3000/');
+  const response = await route.fetch(request);
+
+  expect(response).toBeInstanceOf(Response);
+  expect(response.status).toBe(200);
+  expect(response.headers.get('Transfer-Encoding')).toBe('chunked');
+  expect(response.headers.get('Content-Encoding')).toBe('Identity');
+  expect(response.headers.get('Content-Type')).toBe('text/plain; charset=UTF-8');
+  expect(await response.text()).toBe('ok');
+});
+
 test('route returning AsyncGenerator produces a streaming response', async () => {
   async function* streamingHandler() {
     yield '<h1>Hello</h1>';

package/src/server.ts

@@ -114,10 +114,20 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
   return context;
 }
 
+/**
+ * 204 No Content when the route handler returns `undefined` or `null`.
+ */
+function noContentResponse(context: HS.Context): Response {
+  return new Response(null, {
+    status: 204,
+    headers: context.res.headers,
+  });
+}
 
 /**
  * Define a route that can handle a direct HTTP request.
- * Route handlers should return a HSHtml or Response object
+ * Route handlers should return HSHtml, a Response, a stream, a generator, etc.
+ * Returning `undefined` or `null` sends 204 No Content (with merged `context.res` headers).
  */
 export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
   const _handlers: Record<string, HS.RouteHandler> = {};
@@ -236,7 +246,7 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
       const globalMiddleware = api._middleware['*'] || [];
       const methodMiddleware = api._middleware[method] || [];
 
-      const methodHandler = async (context: HS.Context) => {
+      const methodHandler: HS.RouteHandler = async (context) => {
         // Handle CORS preflight requests (if no OPTIONS handler is defined)
         if (method === 'OPTIONS' && !_handlers['OPTIONS']) {
           return context.res.html(
@@ -289,12 +299,25 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
           return returnHTMLResponse(context, () => routeContent, responseOptions);
         }
 
+        const streamOptions = {
+          status: context.res.status ?? 200,
+          headers: Object.fromEntries(context.res.headers.entries()),
+        };
+
         const contentType = _typeOf(routeContent);
         if (contentType === 'generator') {
-          return new StreamResponse(routeContent as AsyncGenerator, { headers: Object.fromEntries(context.res.headers.entries()) });
+          return new StreamResponse(routeContent as AsyncGenerator, streamOptions);
         }
 
-        return routeContent;
+        if (routeContent instanceof ReadableStream) {
+          return new StreamResponse(routeContent, streamOptions);
+        }
+
+        if (routeContent === undefined || routeContent === null) {
+          return noContentResponse(context);
+        }
+
+        return routeContent as HS.RouteHandlerReturn;
       };
 
       // Run the route handler and any middleware
@@ -537,17 +560,28 @@ async function showErrorReponse(
 
 
 /**
- * Streaming HTML Response
+ * Streaming response: chunked transfer with Transfer-Encoding and Content-Encoding.
+ * Pass an async iterator (HTML chunks) or a ReadableStream; default Content-Type is HTML for iterators
+ * and application/octet-stream for readable streams. Optional headers override defaults.
  */
 export class StreamResponse extends Response {
-  constructor(iterator: AsyncIterator<unknown>, options: { status?: number; headers?: Record<string, string> } = {}) {
+  constructor(
+    body: AsyncIterator<unknown> | ReadableStream,
+    options: { status?: number; headers?: Record<string, string> } = {}
+  ) {
     super();
     const { status, headers, ...restOptions } = options;
-    const stream = createReadableStreamFromAsyncGenerator(iterator as AsyncGenerator);
+    const stream =
+      body instanceof ReadableStream
+        ? body
+        : createReadableStreamFromAsyncGenerator(body as AsyncGenerator);
+
+    const defaultContentType =
+      body instanceof ReadableStream ? 'application/octet-stream' : 'text/html; charset=UTF-8';
 
     const mergedHeaders = new Headers({
       'Transfer-Encoding': 'chunked',
-      'Content-Type': 'text/html; charset=UTF-8',
+      'Content-Type': defaultContentType,
       'Content-Encoding': 'Identity',
     });
     if (headers) {

package/src/types.ts

@@ -100,7 +100,21 @@ export namespace Hyperspan {
       disableStreaming?: (context: Hyperspan.Context) => boolean;
     };
   };
-  export type RouteHandler = (context: Hyperspan.Context) => unknown;
+
+  export type RouteHandlerReturn =
+    | Response
+    | HSHtml
+    | string
+    | ReadableStream
+    | AsyncIterable<unknown>
+    | Iterable<unknown>
+    | undefined
+    | null
+    | void;
+
+  export type RouteHandler = (
+    context: Hyperspan.Context
+  ) => RouteHandlerReturn | Promise<RouteHandlerReturn>;
   export type RouteHandlerOptions = {
     middleware?: Hyperspan.MiddlewareFunction[];
   }