@hyperspan/framework 1.0.17 → 1.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "description": "Hyperspan Web Framework",
   "main": "src/server.ts",
   "types": "src/server.ts",
@@ -40,6 +40,14 @@
     "./actions": {
       "types": "./src/actions.ts",
       "default": "./src/actions.ts"
+    },
+    "./ssr/install-server-dom-mock": {
+      "types": "./src/ssr/install-server-dom-mock.ts",
+      "default": "./src/ssr/install-server-dom-mock.ts"
+    },
+    "./ssr/mock-dom": {
+      "types": "./src/ssr/mock-dom.ts",
+      "default": "./src/ssr/mock-dom.ts"
     }
   },
   "author": "Vance Lucas <vance@vancelucas.com>",

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

@@ -1,3 +1,4 @@
+import './ssr/install-server-dom-mock';
 import { HSHtml, html, isHSHtml, renderStream, renderAsync, render, _typeOf } from '@hyperspan/html';
 import { isbot } from 'isbot';
 import { executeMiddleware } from './middleware';
@@ -114,10 +115,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 +247,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 +300,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 +561,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/ssr/install-server-dom-mock.ts

@@ -0,0 +1,9 @@
+/**
+ * Side-effect entry: install mock `window` / `document` before other framework imports run.
+ * Imported first from `server.ts` so `document` / `window` references in user or 3p code do not throw on SSR.
+ *
+ * Opt out with `HYPERSPAN_DISABLE_MOCK_DOM=1` or `true`.
+ */
+import { installMockDom } from './mock-dom';
+
+installMockDom();

package/src/ssr/mock-dom.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test';
+import { MOCK_DOM_MARK, installMockDom, stubElement } from './mock-dom';
+
+describe('stubElement', () => {
+  test('exposes DOM-like fields and nests children via appendChild', () => {
+    const el = stubElement('article');
+    expect(el.tagName).toBe('ARTICLE');
+    expect(el.nodeType).toBe(1);
+    expect(typeof el.appendChild).toBe('function');
+
+    const inner = stubElement('span');
+    el.appendChild(inner);
+    expect((el.childNodes as unknown[]).length).toBe(1);
+  });
+});
+
+describe('installMockDom', () => {
+  test('runs without throwing and can be invoked repeatedly', () => {
+    expect(() => installMockDom()).not.toThrow();
+    expect(() => installMockDom()).not.toThrow();
+  });
+
+  test('respects HYPERSPAN_DISABLE_MOCK_DOM', () => {
+    const prev = process.env.HYPERSPAN_DISABLE_MOCK_DOM;
+    try {
+      process.env.HYPERSPAN_DISABLE_MOCK_DOM = '1';
+      expect(installMockDom()).toBe(false);
+    } finally {
+      process.env.HYPERSPAN_DISABLE_MOCK_DOM = prev;
+    }
+  });
+
+  test('when a mock document is installed, it is annotated with MOCK_DOM_MARK', () => {
+    const doc = globalThis.document as Record<string, unknown> | undefined;
+    if (!doc?.[MOCK_DOM_MARK]) return;
+    expect(doc[MOCK_DOM_MARK]).toBe(true);
+  });
+});

package/src/ssr/mock-dom.ts

@@ -0,0 +1,362 @@
+/** Stamped on our mock `document` so reloads don't stack duplicates */
+export const MOCK_DOM_MARK = '__hyperspan_mock_dom';
+
+function markedMockDocument(d: unknown): boolean {
+  return Boolean(d && typeof d === 'object' && (d as Record<string, unknown>)[MOCK_DOM_MARK] === true);
+}
+
+/** Minimal element-like node for the mock DOM; not a spec-compliant implementation */
+export function stubElement(tag: string): any {
+  const children: unknown[] = [];
+  const node: Record<string, unknown> = {
+    tagName: String(tag).toUpperCase(),
+    nodeType: 1,
+    nodeName: String(tag).toLowerCase(),
+    id: '',
+    className: '',
+    textContent: '',
+    innerHTML: '',
+    childNodes: children,
+    get children(): unknown[] {
+      return children;
+    },
+    style: {},
+    dataset: {},
+    parentNode: null,
+    parentElement: null,
+    classList: {
+      contains: () => false,
+      add() {},
+      remove() {},
+      toggle() {
+        return false;
+      },
+    },
+    appendChild(child: any) {
+      children.push(child);
+      child.parentNode = node as unknown as ParentNode;
+      child.parentElement = node as unknown as ParentNode & Element | null;
+      return child;
+    },
+    insertBefore(child: unknown, ref: unknown | null) {
+      const ch = node.childNodes as unknown[];
+      const refIx = ref == null ? -1 : ch.indexOf(ref);
+      if (refIx < 0) children.push(child);
+      else children.splice(refIx, 0, child);
+      (child as Record<string, unknown>).parentNode = node as ParentNode as unknown as ParentNode;
+      (child as Record<string, unknown>).parentElement = node as ParentNode & Element | null as unknown as Element | null;
+      return child as ChildNode as unknown as HTMLElement;
+    },
+    removeChild(child: unknown): unknown {
+      const ix = children.indexOf(child);
+      if (ix >= 0) children.splice(ix, 1);
+      const c = child as Record<string, unknown>;
+      c.parentElement = undefined;
+      c.parentNode = undefined;
+      return child as ChildNode;
+    },
+    addEventListener() {},
+    removeEventListener() {},
+    dispatchEvent() {
+      return true;
+    },
+    setAttribute() {},
+    removeAttribute() {},
+    hasAttribute(): boolean {
+      return false;
+    },
+    getAttribute(): null | string {
+      return null;
+    },
+    cloneNode(): unknown {
+      return stubElement(tag);
+    },
+    getBoundingClientRect: () =>
+      ({
+        x: 0,
+        y: 0,
+        width: 0,
+        height: 0,
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        toJSON() {
+          return '{}';
+        },
+      }) as DOMRect,
+    blur() {},
+    focus() {},
+    click() {},
+  };
+  return node;
+}
+
+function memoryStorage(): Storage {
+  const m = new Map<string, string>();
+  return {
+    get length() {
+      return m.size;
+    },
+    key(i: number) {
+      const keys = [...m.keys()];
+      return keys[i] ?? null;
+    },
+    clear() {
+      m.clear();
+    },
+    getItem(key: string) {
+      return m.get(String(key)) ?? null;
+    },
+    setItem(key: string, value: string) {
+      m.set(String(key), String(value));
+    },
+    removeItem(key: string) {
+      m.delete(String(key));
+    },
+  } as Storage;
+}
+
+/**
+ * Installs minimal mock `window` / `document` globals for SSR on runtimes without a real DOM (e.g. Bun server).
+ *
+ * Skips installing when a real-ish `document` already exists unless it carries {@link MOCK_DOM_MARK}.
+ *
+ * Set `HYPERSPAN_DISABLE_MOCK_DOM=1` or `true` to opt out.
+ */
+export function installMockDom(): boolean {
+  const env = typeof process !== 'undefined' ? process.env : {};
+  const disabled = env.HYPERSPAN_DISABLE_MOCK_DOM === '1' || env.HYPERSPAN_DISABLE_MOCK_DOM === 'true';
+  if (disabled) return false;
+
+  const g = globalThis as unknown as Record<string, unknown>;
+
+  if (markedMockDocument(g.document)) return false;
+
+  if (typeof g.document !== 'undefined' && g.document !== null && !markedMockDocument(g.document)) {
+    try {
+      const d = g.document as Partial<Document>;
+      if (d.body !== undefined && typeof d.createElement === 'function') {
+        return false;
+      }
+    } catch {
+      /* install mocks */
+    }
+  }
+
+  const htmlEl = stubElement('html');
+  const body = stubElement('body');
+  const head = stubElement('head');
+  (htmlEl as any).appendChild(head);
+  (htmlEl as any).appendChild(body);
+
+  const navigatorStub = {
+    userAgent: 'HyperspanSSR/1.0',
+    language: 'en-US',
+    languages: ['en-US'],
+    platform: 'server',
+    onLine: true,
+    maxTouchPoints: 0,
+  };
+
+  let rafId = 1;
+  const scheduleRaf = (cb: FrameRequestCallback) => {
+    queueMicrotask(() => cb(performance.now()));
+    return rafId++;
+  };
+
+  const win: Record<string, unknown> = {
+    name: '',
+    innerWidth: 1024,
+    innerHeight: 768,
+    outerWidth: 1024,
+    outerHeight: 768,
+    devicePixelRatio: 1,
+    scrollX: 0,
+    scrollY: 0,
+    scrollTo() {},
+    navigator: navigatorStub,
+    localStorage: memoryStorage(),
+    sessionStorage: memoryStorage(),
+    history: {
+      length: 1,
+      state: null,
+      scrollRestoration: 'auto' as ScrollRestoration,
+      replaceState() {},
+      pushState() {},
+      forward() {},
+      back() {},
+      go() {},
+    },
+    location: new URL('http://localhost/ssr'),
+    resizeTo() {},
+    resizeBy() {},
+    addEventListener() {},
+    removeEventListener() {},
+    dispatchEvent() {
+      return true;
+    },
+    alert() {},
+    matchMedia(query: string) {
+      const media = String(query);
+      return {
+        media,
+        matches: false,
+        addListener() {},
+        removeListener() {},
+        addEventListener() {},
+        removeEventListener() {},
+        dispatchEvent() {
+          return false;
+        },
+        onchange: null,
+      };
+    },
+    getComputedStyle: () =>
+      ({
+        getPropertyValue: () => '',
+        setProperty() {},
+      }) as unknown as CSSStyleDeclaration,
+    requestIdleCallback(cb: IdleRequestCallback) {
+      queueMicrotask(() =>
+        cb({ didTimeout: false, timeRemaining: () => Number.MAX_SAFE_INTEGER }),
+      );
+      return 1;
+    },
+    cancelIdleCallback() {},
+    requestAnimationFrame: scheduleRaf,
+    cancelAnimationFrame() {},
+    MutationObserver:
+      typeof globalThis.MutationObserver !== 'undefined'
+        ? globalThis.MutationObserver
+        : (class {
+            constructor(_callback: MutationCallback) {}
+            disconnect() {}
+            observe() {}
+            takeRecords(): MutationRecord[] {
+              return [];
+            }
+          } as unknown as typeof MutationObserver),
+    IntersectionObserver:
+      typeof globalThis.IntersectionObserver !== 'undefined'
+        ? globalThis.IntersectionObserver
+        : (class {
+            constructor(_cb: IntersectionObserverCallback, _opts?: unknown) {}
+            unobserve() {}
+            disconnect() {}
+            observe() {}
+            takeRecords() {
+              return [];
+            }
+            root = null;
+            rootMargin = '';
+            thresholds = [];
+          } as unknown as typeof IntersectionObserver),
+    ResizeObserver:
+      typeof globalThis.ResizeObserver !== 'undefined'
+        ? globalThis.ResizeObserver
+        : (class {
+            constructor(_callback: ResizeObserverCallback) {}
+            disconnect() {}
+            observe() {}
+            unobserve() {}
+          } as unknown as typeof ResizeObserver),
+  };
+
+  win.self = win as unknown as Window & typeof globalThis;
+  win.window = win as unknown as Window & typeof globalThis;
+
+  const documentStub: Record<string, unknown> = {
+    [MOCK_DOM_MARK]: true,
+    nodeType: 9,
+    defaultView: null as unknown as Window | null,
+    compatibilityMode: 'CSS1Compat',
+    documentElement: htmlEl as unknown as HTMLElement,
+    body: body as unknown as HTMLElement,
+    head: head as unknown as HTMLHeadElement,
+    cookie: '',
+    readyState: 'complete',
+    URL: 'http://localhost/ssr/',
+    referrer: '',
+    hidden: false,
+    visibilityState: 'visible' as DocumentVisibilityState,
+    parentElement: null,
+    appendChild(...args: unknown[]) {
+      return (body.appendChild as (...a: unknown[]) => unknown)(...args);
+    },
+    querySelector(sel: unknown) {
+      const s = String(sel).toLowerCase();
+      if (s === 'body' || s === 'html body') return body as unknown as HTMLElement | null;
+      if (s === 'html') return htmlEl as unknown as HTMLElement | null;
+      return null;
+    },
+    querySelectorAll() {
+      return {
+        length: 0,
+        item() {
+          return null;
+        },
+        forEach() {},
+        *[Symbol.iterator]() {},
+      };
+    },
+    getElementById(id: unknown) {
+      const sid = String(id);
+      const e: Record<string, unknown> = stubElement('div');
+      e.id = sid;
+      e.getAttribute = (k: string) => (k === 'id' ? sid : null);
+      e.hasAttribute = (k: string) => k === 'id';
+      return e as unknown as HTMLElement;
+    },
+    getElementsByTagName() {
+      return [];
+    },
+    getElementsByClassName() {
+      return [];
+    },
+    createElement(tag: unknown) {
+      return stubElement(String(tag ?? 'div')) as unknown as HTMLElement;
+    },
+    createTextNode(data: unknown) {
+      const v = String(data ?? '');
+      return { nodeType: 3, nodeValue: v, nodeName: '#text', textContent: v } as unknown as Text;
+    },
+    createDocumentFragment() {
+      const frag: Record<string, unknown> = {
+        nodeType: 11,
+        childNodes: [] as unknown[],
+        appendChild(child: unknown) {
+          (frag.childNodes as unknown[]).push(child);
+          return child;
+        },
+      };
+      return frag as unknown as DocumentFragment;
+    },
+    elementFromPoint: () => null,
+    caretRangeFromPoint: () => null,
+    addEventListener() {},
+    removeEventListener() {},
+    dispatchEvent() {
+      return true;
+    },
+  };
+
+  documentStub.defaultView = win as unknown as Window;
+  win.document = documentStub;
+
+  g.window = win as unknown as Window & typeof globalThis;
+  g.document = documentStub as unknown as Document;
+
+  try {
+    (globalThis as any).navigator = navigatorStub as Navigator;
+  } catch {
+    /* empty */
+  }
+
+  if (typeof globalThis.requestAnimationFrame !== 'function')
+    globalThis.requestAnimationFrame = scheduleRaf as typeof requestAnimationFrame;
+  if (typeof globalThis.cancelAnimationFrame !== 'function')
+    globalThis.cancelAnimationFrame = (() => {}) as typeof cancelAnimationFrame;
+
+  return true;
+}

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[];
   }