@hyperspan/framework 1.0.0-alpha.9 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "1.0.0-alpha.9",
+  "version": "1.0.1",
   "description": "Hyperspan Web Framework",
   "main": "src/server.ts",
   "types": "src/server.ts",
@@ -37,10 +37,6 @@
       "types": "./src/client/js.ts",
       "default": "./src/client/js.ts"
     },
-    "./plugins": {
-      "types": "./src/plugins.ts",
-      "default": "./src/plugins.ts"
-    },
     "./actions": {
       "types": "./src/actions.ts",
       "default": "./src/actions.ts"
@@ -76,7 +72,8 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@hyperspan/html": "^1.0.0-alpha",
+    "@hyperspan/html": "^1.0.0",
+    "isbot": "^5.1.32",
     "zod": "^4.1.12"
   }
 }

package/src/actions.test.ts

@@ -126,7 +126,7 @@ describe('createAction', () => {
     const formData = new FormData();
     formData.append('email', 'not-an-email');
 
-    const postRequest = new Request(`http://localhost:3000${action._route}`, {
+    const postRequest = new Request(`http://localhost:3000${action._path()}`, {
       method: 'POST',
       body: formData,
     });
@@ -143,5 +143,56 @@ describe('createAction', () => {
     // Should NOT contain the success message from post handler
     expect(responseText).not.toContain('Hello,');
   });
+
+  test('uses custom error handler when provided', async () => {
+    const schema = z.object({
+      name: z.string().min(1, 'Name is required'),
+      email: z.email('Invalid email address'),
+    });
+
+    const action = createAction({
+      name: 'test',
+      schema,
+    }).form((c, { data, error }) => {
+      return html`
+          <form>
+            <input type="text" name="name" value="${data?.name || ''}" />
+            ${error ? html`<div class="error">Validation failed</div>` : ''}
+            <input type="email" name="email" value="${data?.email || ''}" />
+            <button type="submit">Submit</button>
+          </form>
+        `;
+    }).post(async (c, { data }) => {
+      return c.res.html(`
+        <p>Hello, ${data?.name}!</p>
+        <p>Your email is ${data?.email}.</p>
+      `);
+    }).errorHandler(async (c, { data, error }) => {
+      return c.res.html(`
+        <p>Caught error in custom error handler: ${error?.message}</p>
+        <p>Data: ${JSON.stringify(data)}</p>
+      `);
+    });
+
+    // Test fetch method with invalid data (missing name, invalid email)
+    const formData = new FormData();
+    formData.append('email', 'not-an-email');
+
+    const postRequest = new Request(`http://localhost:3000${action._path()}`, {
+      method: 'POST',
+      body: formData,
+    });
+
+    const response = await action.fetch(postRequest);
+    expect(response).toBeInstanceOf(Response);
+    expect(response.status).toBe(400);
+
+    const responseText = await response.text();
+    // Should render the custom error handler
+    expect(responseText).toContain('Caught error in custom error handler: Input validation error(s)');
+    expect(responseText).toContain('Data: {"email":"not-an-email"}');
+    // Should NOT contain the success message from post handler
+    expect(responseText).not.toContain('Hello,');
+  });
 });
 

package/src/actions.ts

@@ -1,10 +1,12 @@
-import { html, HSHtml } from '@hyperspan/html';
-import { createRoute, returnHTMLResponse } from './server';
+import { html } from '@hyperspan/html';
+import { createRoute, HTTPResponseException, returnHTMLResponse } from './server';
 import * as z from 'zod/v4';
 import type { Hyperspan as HS } from './types';
 import { assetHash, formDataToJSON } from './utils';
-import * as actionsClient from './client/_hs/hyperspan-actions.client';
-import { renderClientJS } from './client/js';
+import { buildClientJS } from './client/js';
+import { validateBody, ZodValidationError } from './middleware';
+
+const actionsClientJS = await buildClientJS(import.meta.resolve('./client/_hs/hyperspan-actions.client'));
 
 /**
  * Actions = Form + route handler
@@ -19,7 +21,7 @@ import { renderClientJS } from './client/js';
  * 5. Replaces form content in place with HTML response content from server via the Idiomorph library
  * 6. Handles any Exception thrown on server as error displayed back to user on the page
  */
-export function createAction<T extends z.ZodTypeAny>(params: { name: string; schema?: T }): HS.Action<T> {
+export function createAction<T extends z.ZodObject<any, any>>(params: { name: string; schema?: T }): HS.Action<T> {
   const { name, schema } = params;
   const path = `/__actions/${assetHash(name)}`;
 
@@ -29,48 +31,41 @@ export function createAction<T extends z.ZodTypeAny>(params: { name: string; sch
   const route = createRoute({ path, name })
     .get((c: HS.Context) => api.render(c))
     .post(async (c: HS.Context) => {
-      // Parse form data
-      const formData = await c.req.raw.formData();
-      const jsonData = formDataToJSON(formData) as Partial<z.infer<T>>;
-      const schemaData = schema ? schema.safeParse(jsonData) : null;
-      const data = schemaData?.success ? (schemaData.data as Partial<z.infer<T>>) : jsonData;
-      let error: z.ZodError | Error | null = null;
-
-      try {
-        if (schema && schemaData?.error) {
-          throw schemaData.error;
-        }
-
-        if (!_handler) {
-          throw new Error('Action POST handler not set! Every action must have a POST handler.');
-        }
+      if (!_handler) {
+        throw new Error('Action POST handler not set! Every action must have a POST handler.');
+      }
 
-        const response = await _handler(c, { data });
+      const response = await _handler(c, { data: c.vars.body });
 
-        if (response instanceof Response) {
-          // Replace redirects with special header because fetch() automatically follows redirects
-          // and we want to redirect the user to the actual full page instead
-          if ([301, 302, 307, 308].includes(response.status)) {
-            response.headers.set('X-Redirect-Location', response.headers.get('Location') || '/');
-            response.headers.delete('Location');
-          }
+      if (response instanceof Response) {
+        // Replace redirects with special header because fetch() automatically follows redirects
+        // and we want to redirect the user to the actual full page instead
+        if ([301, 302, 307, 308].includes(response.status)) {
+          response.headers.set('X-Redirect-Location', response.headers.get('Location') || '/');
+          response.headers.delete('Location');
         }
-
-        return response;
-      } catch (e) {
-        error = e as Error | z.ZodError;
       }
 
-      if (error && _errorHandler) {
-        const errorHandler = _errorHandler; // Required for TypeScript to infer the correct type after narrowing
-        return await returnHTMLResponse(c, () => errorHandler(c, { data, error }), {
-          status: 400,
-        });
-      }
+      return response;
+    }, { middleware: schema ? [validateBody(schema)] : [] })
+    /**
+     * Custom error handler for the action since validateBody() throws a HTTPResponseException
+     */
+    .errorHandler(async (c: HS.Context, err: HTTPResponseException) => {
+      const data = c.vars.body as Partial<z.infer<T>>;
+      const error = err._error as ZodValidationError;
+
+      // Set the status to 400 by default
+      c.res.status = 400;
 
-      return await returnHTMLResponse(c, () => api.render(c, { data, error }), { status: 400 });
+      return await returnHTMLResponse(c, () => {
+        return _errorHandler ? _errorHandler(c, { data, error }) : api.render(c, { data, error });
+      }, { status: 400 });
     });
 
+  // Set the name of the action for the route
+  route._config.name = name;
+
   const api: HS.Action<T> = {
     _kind: 'hsAction',
     _config: route._config,
@@ -101,7 +96,7 @@ export function createAction<T extends z.ZodTypeAny>(params: { name: string; sch
      */
     render(c: HS.Context, props?: HS.ActionProps<T>) {
       const formContent = api._form ? api._form(c, props || {}) : null;
-      return formContent ? html`<hs-action url="${this._path()}">${formContent}</hs-action>${renderClientJS(actionsClient)}` : null;
+      return formContent ? html`<hs-action url="${this._path()}">${formContent}</hs-action>${actionsClientJS.renderScriptTag()}` : null;
     },
     errorHandler(handler) {
       _errorHandler = handler;

package/src/client/_hs/hyperspan-streaming.client.ts

@@ -1,68 +1,5 @@
-import { Idiomorph } from './idiomorph';
 import { lazyLoadScripts } from './hyperspan-scripts.client';
 
-/**
- * Used for streaming content from the server to the client.
- */
-function htmlAsyncContentObserver() {
-  if (typeof MutationObserver != 'undefined') {
-    // Hyperspan - Async content loader
-    // Puts streamed content in its place immediately after it is added to the DOM
-    const asyncContentObserver = new MutationObserver((list) => {
-      const asyncContent = list
-        .map((mutation) =>
-          Array.from(mutation.addedNodes).find((node: any) => {
-            if (!node || !node?.id || typeof node.id !== 'string') {
-              return false;
-            }
-            return node.id?.startsWith('async_loading_') && node.id?.endsWith('_content');
-          })
-        )
-        .filter((node: any) => node);
-
-      asyncContent.forEach((templateEl: any) => {
-        try {
-          // Also observe for content inside the template content (shadow DOM is separate)
-          asyncContentObserver.observe(templateEl.content, { childList: true, subtree: true });
-
-          const slotId = templateEl.id.replace('_content', '');
-          const slotEl = document.getElementById(slotId);
-
-          if (slotEl) {
-            // Content AND slot are present - let's insert the content into the slot
-            // Ensure the content is fully done streaming in before inserting it into the slot
-            waitForContent(templateEl.content, (el2) => {
-              return Array.from(el2.childNodes).find(
-                (node) => node.nodeType === Node.COMMENT_NODE && node.nodeValue === 'end'
-              );
-            })
-              .then((endComment) => {
-                templateEl.content.removeChild(endComment);
-                const content = templateEl.content.cloneNode(true);
-                Idiomorph.morph(slotEl, content);
-                templateEl.parentNode.removeChild(templateEl);
-                lazyLoadScripts();
-              })
-              .catch(console.error);
-          } else {
-            // Slot is NOT present - wait for it to be added to the DOM so we can insert the content into it
-            waitForContent(document.body, () => {
-              return document.getElementById(slotId);
-            }).then((slotEl) => {
-              Idiomorph.morph(slotEl, templateEl.content.cloneNode(true));
-              lazyLoadScripts();
-            });
-          }
-        } catch (e) {
-          console.error(e);
-        }
-      });
-    });
-    asyncContentObserver.observe(document.body, { childList: true, subtree: true });
-  }
-}
-htmlAsyncContentObserver();
-
 /**
  * Wait until ALL of the content inside an element is present from streaming in.
  * Large chunks of content can sometimes take more than a single tick to write to DOM.
@@ -91,4 +28,39 @@ async function waitForContent(
       reject(new Error(`[Hyperspan] Timeout waiting for end of streaming content ${el.id}`));
     }, options.timeoutMs || 10000);
   });
-}
+}
+
+function renderStreamChunk(chunk: { id: string }) {
+  const slotId = chunk.id;
+  const slotEl = document.getElementById(slotId);
+  const templateEl = document.getElementById(`${slotId}_content`) as HTMLTemplateElement;
+
+  if (slotEl) {
+    // Content AND slot are present - let's insert the content into the slot
+    // Ensure the content is fully done streaming in before inserting it into the slot
+    waitForContent(templateEl.content as unknown as HTMLElement, (el2) => {
+      return Array.from(el2.childNodes).find(
+        (node) => node.nodeType === Node.COMMENT_NODE && node.nodeValue === 'end'
+      );
+    })
+      .then((endComment) => {
+        templateEl.content.removeChild(endComment as Node);
+        const content = templateEl.content.cloneNode(true);
+        slotEl.replaceWith(content);
+        templateEl.parentNode?.removeChild(templateEl);
+        lazyLoadScripts();
+      })
+      .catch(console.error);
+  } else {
+    // Slot is NOT present - wait for it to be added to the DOM so we can insert the content into it
+    waitForContent(document.body, () => {
+      return document.getElementById(slotId);
+    }).then((slotEl) => {
+      (slotEl as HTMLElement)?.replaceWith(templateEl.content.cloneNode(true));
+      lazyLoadScripts();
+    });
+  }
+}
+
+// @ts-ignore
+window._hscc = renderStreamChunk;

package/src/client/js.ts

@@ -1,61 +1,94 @@
 import { html } from '@hyperspan/html';
+import { assetHash as assetHashFn } from '../utils';
+import { join } from 'node:path';
+import type { Hyperspan as HS } from '../types';
+
+const CWD = process.cwd();
+const IS_PROD = process.env.NODE_ENV === 'production';
 
 export const JS_PUBLIC_PATH = '/_hs/js';
 export const JS_ISLAND_PUBLIC_PATH = '/_hs/js/islands';
 export const JS_IMPORT_MAP = new Map<string, string>();
+const CLIENT_JS_CACHE = new Map<string, { esmName: string, exports: string, fnArgs: string, publicPath: string }>();
+const EXPORT_REGEX = /export\{(.*)\}/g;
 
 /**
- * Render a client JS module as a script tag
+ * Build a client JS module and return a Hyperspan.ClientJSBuildResult object
  */
-export function renderClientJS<T>(module: T, loadScript?: ((module: T) => void) | string) {
-  // @ts-ignore
-  if (!module.__CLIENT_JS) {
-    throw new Error(
-      `[Hyperspan] Client JS was not loaded by Hyperspan! Ensure the filename ends with .client.ts to use this render method.`
-    );
-  }
+export async function buildClientJS(modulePathResolved: string): Promise<HS.ClientJSBuildResult> {
+  const modulePath = modulePathResolved.replace('file://', '');
+  const assetHash = assetHashFn(modulePath);
 
-  return html.raw(
-    // @ts-ignore
-    module.__CLIENT_JS.renderScriptTag({
-      loadScript: loadScript
-        ? typeof loadScript === 'string'
-          ? loadScript
-          : functionToString(loadScript)
-        : undefined,
-    })
-  );
-}
+  // Cache: Avoid re-processing the same file
+  if (!CLIENT_JS_CACHE.has(assetHash)) {
+    // Build the client JS module
+    const result = await Bun.build({
+      entrypoints: [modulePath],
+      outdir: join(CWD, './public', JS_PUBLIC_PATH), // @TODO: Make this configurable... should be read from config file...
+      naming: IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined,
+      external: Array.from(JS_IMPORT_MAP.keys()),
+      minify: true,
+      format: 'esm',
+      target: 'browser',
+      env: 'APP_PUBLIC_*',
+    });
 
-/**
- * Convert a function to a string (results in loss of context!)
- * Handles named, async, and arrow functions
- */
-export function functionToString(fn: any) {
-  let str = fn.toString().trim();
-
-  // Ensure consistent output & handle async
-  if (!str.includes('function ')) {
-    if (str.includes('async ')) {
-      str = 'async function ' + str.replace('async ', '');
-    } else {
-      str = 'function ' + str;
+    // Add output file to import map
+    const esmName = String(result.outputs[0].path.split('/').reverse()[0]).replace('.js', '');
+    const publicPath = `${JS_PUBLIC_PATH}/${esmName}.js`;
+    JS_IMPORT_MAP.set(esmName, publicPath);
+
+    // Get the contents of the file to extract the exports
+    const contents = await result.outputs[0].text();
+    const exportLine = EXPORT_REGEX.exec(contents);
+
+    let exports = '{}';
+    if (exportLine) {
+      const exportName = exportLine[1];
+      exports =
+        '{' +
+        exportName
+          .split(',')
+          .map((name) => name.trim().split(' as '))
+          .map(([name, alias]) => `${alias === 'default' ? 'default as ' + name : alias}`)
+          .join(', ') +
+        '}';
     }
+    const fnArgs = exports.replace(/(\w+)\s*as\s*(\w+)/g, '$1: $2');
+    CLIENT_JS_CACHE.set(assetHash, { esmName, exports, fnArgs, publicPath });
   }
 
-  const lines = str.split('\n');
-  const firstLine = lines[0];
-  const lastLine = lines[lines.length - 1];
+  const { esmName, exports, fnArgs, publicPath } = CLIENT_JS_CACHE.get(assetHash)!;
 
-  // Arrow function conversion
-  if (!lastLine?.includes('}')) {
-    return str.replace('=> ', '{ return ') + '; }';
-  }
+  return {
+    assetHash,
+    esmName,
+    publicPath,
+    renderScriptTag: (loadScript) => {
+      const t = typeof loadScript;
+
+      if (t === 'string') {
+        return html`
+          <script type="module" data-source-id="${assetHash}">import ${exports} from "${esmName}";\n(${html.raw(loadScript as string)})(${fnArgs});</script>
+        `;
+      }
+      if (t === 'function') {
+        return html`
+          <script type="module" data-source-id="${assetHash}">import ${exports} from "${esmName}";\n(${html.raw(functionToString(loadScript))})(${fnArgs});</script>
+        `;
+      }
 
-  // Cleanup arrow function
-  if (firstLine.includes('=>')) {
-    return str.replace('=> ', '');
+      return html`
+        <script type="module" data-source-id="${assetHash}">import "${esmName}";</script>
+      `;
+    }
   }
+}
 
-  return str;
+/**
+ * Convert a function to a string (results in loss of context!)
+ * Handles named, async, and arrow functions
+ */
+export function functionToString(fn: any) {
+  return fn.toString().trim();
 }

package/src/cookies.ts

@@ -42,7 +42,7 @@ export class Cookies implements HS.Cookies {
     if (this._encrypt) {
       value = this._encrypt(value);
     }
-    this._responseHeaders.set('Set-Cookie', serialize(name, value, options));
+    this._responseHeaders.append('Set-Cookie', serialize(name, value, options));
   }
 
   delete(name: string) {

package/src/index.ts

@@ -1,2 +1,2 @@
-export { createConfig, createContext, createRoute, createServer, getRunnableRoute, StreamResponse, IS_PROD, HTTPException } from './server';
+export { createConfig, createContext, createRoute, createServer, getRunnableRoute, StreamResponse, IS_PROD, HTTPResponseException } from './server';
 export type { Hyperspan } from './types';

package/src/layout.ts

@@ -1,8 +1,10 @@
 import { html } from '@hyperspan/html';
-import { JS_IMPORT_MAP } from './client/js';
+import { JS_IMPORT_MAP, buildClientJS } from './client/js';
 import { CSS_PUBLIC_PATH, CSS_ROUTE_MAP } from './client/css';
 import type { Hyperspan as HS } from './types';
 
+const clientStreamingJS = await buildClientJS(import.meta.resolve('./client/_hs/hyperspan-streaming.client'));
+
 /**
  * Output the importmap for the client so we can use ESModules on the client to load JS files on demand
  */
@@ -11,6 +13,27 @@ export function hyperspanScriptTags() {
     <script type="importmap">
       {"imports": ${Object.fromEntries(JS_IMPORT_MAP)}}
     </script>
+    <script id="hyperspan-streaming-script">
+      // [Hyperspan] Streaming - Load the client streaming JS module only when the first chunk is loaded
+      window._hsc = window._hsc || [];
+      var hscc = function(e) {
+        if (window._hscc !== undefined) {
+          window._hscc(e);
+        }
+      };
+      window._hsc.push = function(e) {
+        Array.prototype.push.call(window._hsc, e);
+        if (window._hsc.length === 1) {
+          const script = document.createElement('script');
+          script.src = "${clientStreamingJS.publicPath}";
+          document.body.appendChild(script);
+          script.onload = function() {
+            hscc(e);
+          };
+        }
+        hscc(e);
+      };
+    </script>
   `;
 }
 

package/src/middleware.ts

@@ -1,4 +1,90 @@
+import { formDataToJSON } from './utils';
+import { z, flattenError } from 'zod/v4';
+
+import type { ZodAny, ZodObject, ZodError } from 'zod/v4';
 import type { Hyperspan as HS } from './types';
+import { HTTPResponseException } from './server';
+
+export type TValidationType = 'json' | 'form' | 'urlencoded';
+
+/**
+ * Infer the validation type from the request Content-Type header
+ */
+function inferValidationType(headers: Headers): TValidationType {
+  const contentType = headers.get('content-type')?.toLowerCase() || '';
+
+  if (contentType.includes('application/json')) {
+    return 'json';
+  } else if (contentType.includes('multipart/form-data')) {
+    return 'form';
+  } else if (contentType.includes('application/x-www-form-urlencoded')) {
+    return 'urlencoded';
+  }
+
+  // Default to json if content-type is not recognized
+  return 'json';
+}
+
+export class ZodValidationError extends Error {
+  constructor(flattened: ReturnType<typeof flattenError>) {
+    super('Input validation error(s)');
+    this.name = 'ZodValidationError';
+
+    // Copy all properties from flattened error
+    Object.assign(this, flattened);
+  }
+}
+
+export function validateQuery(schema: ZodObject | ZodAny): HS.MiddlewareFunction {
+  return async (context: HS.Context, next: HS.NextFunction) => {
+    const query = formDataToJSON(context.req.query);
+    const validated = schema.safeParse(query);
+
+    // Store the validated query in the context variables
+    context.vars.query = validated.data as z.infer<typeof schema>;
+
+    if (!validated.success) {
+      const err = formatZodError(validated.error);
+      return context.res.error(err, { status: 400 });
+    }
+
+    return next();
+  }
+}
+
+export function validateBody(schema: ZodObject | ZodAny, type?: TValidationType): HS.MiddlewareFunction {
+  return async (context: HS.Context, next: HS.NextFunction) => {
+    // Infer type from Content-Type header if not provided
+    const validationType = type || inferValidationType(context.req.headers);
+
+    let body: unknown = {};
+    if (validationType === 'json') {
+      body = await context.req.raw.json();
+    } else if (validationType === 'form') {
+      const formData = await context.req.formData();
+      body = formDataToJSON(formData as FormData);
+    } else if (validationType === 'urlencoded') {
+      const urlencoded = await context.req.urlencoded();
+      body = formDataToJSON(urlencoded);
+    }
+
+    context.vars.body = body as z.infer<typeof schema>;
+    const validated = schema.safeParse(body);
+
+    if (!validated.success) {
+      const err = formatZodError(validated.error);
+      throw new HTTPResponseException(err, { status: 400 });
+      //return context.res.error(err, { status: 400 });
+    }
+
+    return next();
+  }
+}
+
+export function formatZodError(error: ZodError): ZodValidationError {
+  const zodError = flattenError(error);
+  return new ZodValidationError(zodError);
+}
 
 /**
  * Type guard to check if a handler is a middleware function
@@ -55,4 +141,3 @@ export async function executeMiddleware(
   // Start execution from the first handler
   return await createNext(0)();
 }
-

package/src/server.test.ts

@@ -113,7 +113,7 @@ test('createContext() can get and set cookies', () => {
   expect(setCookieHeader).toBeTruthy();
   expect(setCookieHeader).toContain('newCookie=newValue');
 
-  // Test setting a cookie with options (this will overwrite the previous Set-Cookie header)
+  // Test setting a cookie with options (this should NOT overwrite the previous Set-Cookie header)
   context.res.cookies.set('secureCookie', 'secureValue', {
     httpOnly: true,
     secure: true,
@@ -125,13 +125,7 @@ test('createContext() can get and set cookies', () => {
   setCookieHeader = context.res.headers.get('Set-Cookie');
   expect(setCookieHeader).toBeTruthy();
   expect(setCookieHeader).toContain('secureCookie=secureValue');
-  expect(setCookieHeader).toContain('HttpOnly');
-  expect(setCookieHeader).toContain('Secure');
-  expect(setCookieHeader).toContain('SameSite=Strict');
-  expect(setCookieHeader).toContain('Max-Age=3600');
-
-  // Verify the previous cookie was overwritten
-  expect(setCookieHeader).not.toContain('newCookie=newValue');
+  expect(setCookieHeader).toContain('newCookie=newValue');
 
   // Test deleting a cookie
   context.res.cookies.delete('sessionId');

package/src/server.ts

@@ -1,6 +1,6 @@
-import { HSHtml, html, isHSHtml, renderStream, renderAsync, render } from '@hyperspan/html';
+import { HSHtml, html, isHSHtml, renderStream, renderAsync, render, _typeOf } from '@hyperspan/html';
+import { isbot } from 'isbot';
 import { executeMiddleware } from './middleware';
-import { clientJSPlugin } from './plugins';
 import { parsePath } from './utils';
 import { Cookies } from './cookies';
 
@@ -8,9 +8,13 @@ import type { Hyperspan as HS } from './types';
 
 export const IS_PROD = process.env.NODE_ENV === 'production';
 
-export class HTTPException extends Error {
-  constructor(public status: number, message?: string) {
-    super(message);
+export class HTTPResponseException extends Error {
+  public _error?: Error;
+  public _response?: Response;
+  constructor(body: string | Error | undefined, options?: ResponseInit) {
+    super(body instanceof Error ? body.message : body);
+    this._error = body instanceof Error ? body : undefined;
+    this._response = new Response(body instanceof Error ? body.message : body, options);
   }
 }
 
@@ -18,11 +22,22 @@ export class HTTPException extends Error {
  * Ensures a valid config object is returned, even with an empty object or partial object passed in
  */
 export function createConfig(config: Partial<HS.Config> = {}): HS.Config {
+  const defaultConfig: HS.Config = {
+    appDir: './app',
+    publicDir: './public',
+    plugins: [],
+    responseOptions: {
+      // Disable streaming for bots by default
+      disableStreaming: (c) => isbot(c.req.raw.headers.get('user-agent') ?? ''),
+    },
+  };
   return {
+    ...defaultConfig,
     ...config,
-    appDir: config.appDir ?? './app',
-    publicDir: config.publicDir ?? './public',
-    plugins: [clientJSPlugin(), ...(config.plugins ?? [])],
+    responseOptions: {
+      ...defaultConfig.responseOptions,
+      ...config.responseOptions,
+    },
   };
 }
 
@@ -36,7 +51,18 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
   const headers = new Headers(req.headers);
   const path = route?._path() || '/';
   // @ts-ignore - Bun will put 'params' on the Request object even though it's not standardized
-  const params: HS.RouteParamsParser<path> = req?.params || {};
+  const params: HS.RouteParamsParser<path> & Record<string, string | undefined> = Object.assign({}, req?.params || {}, route?._config.params || {});
+
+  // Replace catch-all param with the value from the URL path
+  const catchAllParam = Object.keys(params).find(key => key.startsWith('...'));
+  if (catchAllParam && path.includes('/*')) {
+    const catchAllValue = url.pathname.split(path.replace('/*', '/')).pop();
+    params[catchAllParam.replace('...', '')] = catchAllValue;
+    delete params[catchAllParam];
+  }
+
+  // Status override for the response. Will use if set. (e.g. c.res.status = 400)
+  let status: number | undefined = undefined;
 
   const merge = (response: Response) => {
     // Convert headers to plain objects and merge (response headers override context headers)
@@ -46,14 +72,15 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
     };
 
     return new Response(response.body, {
-      status: response.status,
+      status: context.res.status ?? response.status,
       headers: mergedHeaders,
     });
   };
 
-  return {
+  const context: HS.Context = {
     vars: {},
     route: {
+      name: route?._config.name || undefined,
       path,
       params: params,
       cssImports: route ? route._config.cssImports ?? [] : [],
@@ -65,24 +92,26 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
       headers,
       query,
       cookies: new Cookies(req),
-      async text() { return req.text() },
-      async json<T = unknown>() { return await req.json() as T },
-      async formData<T = unknown>() { return await req.formData() as T },
-      async urlencoded() { return new URLSearchParams(await req.text()) },
+      async text() { return req.clone().text() },
+      async json<T = unknown>() { return await req.clone().json() as T },
+      async formData<T = unknown>() { return await req.clone().formData() as T },
+      async urlencoded() { return new URLSearchParams(await req.clone().text()) },
     },
     res: {
       cookies: new Cookies(req, headers),
       headers,
-      raw: new Response(),
-      html: (html: string, options?: { status?: number; headers?: Headers | Record<string, string> }) => merge(new Response(html, { ...options, headers: { 'Content-Type': 'text/html; charset=UTF-8', ...options?.headers } })),
-      json: (json: any, options?: { status?: number; headers?: Headers | Record<string, string> }) => merge(new Response(JSON.stringify(json), { ...options, headers: { 'Content-Type': 'application/json', ...options?.headers } })),
-      text: (text: string, options?: { status?: number; headers?: Headers | Record<string, string> }) => merge(new Response(text, { ...options, headers: { 'Content-Type': 'text/plain; charset=UTF-8', ...options?.headers } })),
-      redirect: (url: string, options?: { status?: number; headers?: Headers | Record<string, string> }) => merge(new Response(null, { status: 302, headers: { Location: url, ...options?.headers } })),
-      error: (error: Error, options?: { status?: number; headers?: Headers | Record<string, string> }) => merge(new Response(error.message, { status: 500, ...options })),
-      notFound: (options?: { status?: number; headers?: Headers | Record<string, string> }) => merge(new Response('Not Found', { status: 404, ...options })),
+      status,
+      html: (html: string, options?: ResponseInit) => merge(new Response(html, { ...options, headers: { 'Content-Type': 'text/html; charset=UTF-8', ...options?.headers } })),
+      json: (json: any, options?: ResponseInit) => merge(new Response(JSON.stringify(json), { ...options, headers: { 'Content-Type': 'application/json', ...options?.headers } })),
+      text: (text: string, options?: ResponseInit) => merge(new Response(text, { ...options, headers: { 'Content-Type': 'text/plain; charset=UTF-8', ...options?.headers } })),
+      redirect: (url: string, options?: ResponseInit) => merge(new Response(null, { status: 302, headers: { Location: url, ...options?.headers } })),
+      error: (error: Error, options?: ResponseInit) => merge(new Response(error.message, { status: 500, ...options })),
+      notFound: (options?: ResponseInit) => merge(new Response('Not Found', { status: 404, ...options })),
       merge,
     },
   };
+
+  return context;
 }
 
 
@@ -90,8 +119,9 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
  * Define a route that can handle a direct HTTP request.
  * Route handlers should return a HSHtml or Response object
  */
-export function createRoute(config: HS.RouteConfig = {}): HS.Route {
+export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
   const _handlers: Record<string, HS.RouteHandler> = {};
+  let _errorHandler: HS.ErrorHandler | undefined = undefined;
   let _middleware: Record<string, Array<HS.MiddlewareFunction>> = { '*': [] };
 
   const api: HS.Route = {
@@ -130,14 +160,6 @@ export function createRoute(config: HS.RouteConfig = {}): HS.Route {
       _middleware['PUT'] = handlerOptions?.middleware || [];
       return api;
     },
-    /**
-     * Add a DELETE route handler (typically to delete existing data)
-     */
-    delete(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
-      _handlers['DELETE'] = handler;
-      _middleware['DELETE'] = handlerOptions?.middleware || [];
-      return api;
-    },
     /**
      * Add a PATCH route handler (typically to update existing data)
      */
@@ -146,6 +168,14 @@ export function createRoute(config: HS.RouteConfig = {}): HS.Route {
       _middleware['PATCH'] = handlerOptions?.middleware || [];
       return api;
     },
+    /**
+     * Add a DELETE route handler (typically to delete existing data)
+     */
+    delete(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
+      _handlers['DELETE'] = handler;
+      _middleware['DELETE'] = handlerOptions?.middleware || [];
+      return api;
+    },
     /**
      * Add a OPTIONS route handler (typically to handle CORS preflight requests)
      */
@@ -154,8 +184,11 @@ export function createRoute(config: HS.RouteConfig = {}): HS.Route {
       _middleware['OPTIONS'] = handlerOptions?.middleware || [];
       return api;
     },
-    errorHandler(handler: HS.RouteHandler) {
-      _handlers['_ERROR'] = handler;
+    /**
+     * Set a custom error handler for this route to fall back to if the route handler throws an error
+     */
+    errorHandler(handler: HS.ErrorHandler) {
+      _errorHandler = handler;
       return api;
     },
     /**
@@ -213,7 +246,14 @@ export function createRoute(config: HS.RouteConfig = {}): HS.Route {
         }
 
         if (isHTMLContent(routeContent)) {
-          return returnHTMLResponse(context, () => routeContent);
+          // Merge server and route-specific response options
+          const responseOptions = { ...(api._serverConfig?.responseOptions ?? {}), ...(api._config?.responseOptions ?? {}) };
+          return returnHTMLResponse(context, () => routeContent, responseOptions);
+        }
+
+        const contentType = _typeOf(routeContent);
+        if (contentType === 'generator') {
+          return new StreamResponse(routeContent as AsyncGenerator);
         }
 
         return routeContent;
@@ -224,8 +264,9 @@ export function createRoute(config: HS.RouteConfig = {}): HS.Route {
       try {
         return await executeMiddleware(context, [...globalMiddleware, ...methodMiddleware, methodHandler]);
       } catch (e) {
-        if (_handlers['_ERROR']) {
-          return await (_handlers['_ERROR'](context) as Promise<Response>);
+        if (_errorHandler !== undefined) {
+          const responseOptions = { ...(api._serverConfig?.responseOptions ?? {}), ...(api._config?.responseOptions ?? {}) };
+          return returnHTMLResponse(context, () => (_errorHandler as HS.ErrorHandler)(context, e as Error), responseOptions);
         }
         throw e;
       }
@@ -313,7 +354,7 @@ function isHTMLContent(response: unknown): response is Response {
 export async function returnHTMLResponse(
   context: HS.Context,
   handlerFn: () => unknown,
-  responseOptions?: { status?: number; headers?: Record<string, string> }
+  responseOptions?: { status?: number; headers?: Record<string, string>; disableStreaming?: (context: HS.Context) => boolean }
 ): Promise<Response> {
   try {
     const routeContent = await handlerFn();
@@ -325,14 +366,22 @@ export async function returnHTMLResponse(
 
     // Render HSHtml if returned from route handler
     if (isHSHtml(routeContent)) {
-      // @TODO: Move this to config or something...
-      const streamOpt = context.req.query.get('__nostream');
-      const streamingEnabled = (streamOpt !== undefined ? streamOpt : true);
+      const disableStreaming = responseOptions?.disableStreaming?.(context) ?? false;
 
       // Stream only if enabled and there is async content to stream
-      if (streamingEnabled && (routeContent as HSHtml).asyncContent?.length > 0) {
+      if (!disableStreaming && (routeContent as HSHtml).asyncContent?.length > 0) {
         return new StreamResponse(
-          renderStream(routeContent as HSHtml),
+          renderStream(routeContent as HSHtml, {
+            renderChunk: (chunk) => {
+              return html`
+              <template id="${chunk.id}_content">${html.raw(chunk.content)}<!--end--></template>
+              <script>
+                window._hsc = window._hsc || [];
+                window._hsc.push({id: "${chunk.id}" });
+              </script>
+            `;
+            }
+          }),
           responseOptions
         ) as Response;
       } else {
@@ -398,8 +447,8 @@ async function showErrorReponse(
   const message = err.message || 'Internal Server Error';
 
   // Send correct status code if HTTPException
-  if (err instanceof HTTPException) {
-    status = err.status;
+  if (err instanceof HTTPResponseException) {
+    status = err._response?.status ?? 500;
   }
 
   const stack = !IS_PROD && err.stack ? err.stack.split('\n').slice(1).join('\n') : '';

package/src/types.ts

@@ -27,6 +27,9 @@ export namespace Hyperspan {
     // For customizing the routes and adding your own...
     beforeRoutesAdded?: (server: Hyperspan.Server) => void;
     afterRoutesAdded?: (server: Hyperspan.Server) => void;
+    responseOptions?: {
+      disableStreaming?: (context: Hyperspan.Context) => boolean;
+    };
   };
 
   export type CookieOptions = {
@@ -49,37 +52,37 @@ export namespace Hyperspan {
     delete: (name: string) => void;
   }
 
+  export type HSRequest = {
+    url: URL;
+    raw: Request;
+    method: string; // Always uppercase
+    headers: Headers; // Case-insensitive
+    query: URLSearchParams;
+    cookies: Hyperspan.Cookies;
+    text: () => Promise<string>;
+    json<T = unknown>(): Promise<T>;
+    formData(): Promise<FormData>;
+    urlencoded(): Promise<URLSearchParams>;
+  };
+
+  export type HSResponse = {
+    cookies: Hyperspan.Cookies;
+    headers: Headers; // Headers to merge with final outgoing response
+    status: number | undefined;
+    html: (html: string, options?: ResponseInit) => Response
+    json: (json: any, options?: ResponseInit) => Response;
+    text: (text: string, options?: ResponseInit) => Response;
+    redirect: (url: string, options?: ResponseInit) => Response;
+    error: (error: Error, options?: ResponseInit) => Response;
+    notFound: (options?: ResponseInit) => Response;
+    merge: (response: Response) => Response;
+  };
+
   export interface Context {
     vars: Record<string, any>;
-    route: {
-      path: string;
-      params: Record<string, string>;
-      cssImports?: string[];
-    }
-    req: {
-      url: URL;
-      raw: Request;
-      method: string; // Always uppercase
-      headers: Headers; // Case-insensitive
-      query: URLSearchParams;
-      cookies: Hyperspan.Cookies;
-      text: () => Promise<string>;
-      json<T = unknown>(): Promise<T>;
-      formData(): Promise<FormData>;
-      urlencoded(): Promise<URLSearchParams>;
-    };
-    res: {
-      cookies: Hyperspan.Cookies;
-      headers: Headers; // Headers to merge with final outgoing response
-      html: (html: string, options?: { status?: number; headers?: Record<string, string> }) => Response
-      json: (json: any, options?: { status?: number; headers?: Record<string, string> }) => Response;
-      text: (text: string, options?: { status?: number; headers?: Record<string, string> }) => Response;
-      redirect: (url: string, options?: { status?: number; headers?: Record<string, string> }) => Response;
-      error: (error: Error, options?: { status?: number; headers?: Record<string, string> }) => Response;
-      notFound: (options?: { status?: number; headers?: Record<string, string> }) => Response;
-      merge: (response: Response) => Response;
-      raw: Response;
-    };
+    route: RouteConfig;
+    req: HSRequest;
+    res: HSResponse;
   };
 
   export type ClientIslandOptions = {
@@ -88,9 +91,13 @@ export namespace Hyperspan {
   };
 
   export type RouteConfig = {
-    name?: string;
-    path?: string;
-    cssImports?: string[];
+    name: string | undefined;
+    path: string;
+    params: Record<string, string | undefined>;
+    cssImports: string[];
+    responseOptions?: {
+      disableStreaming?: (context: Hyperspan.Context) => boolean;
+    };
   };
   export type RouteHandler = (context: Hyperspan.Context) => unknown;
   export type RouteHandlerOptions = {
@@ -112,6 +119,11 @@ export namespace Hyperspan {
    */
   export type NextFunction = () => Promise<Response>;
 
+  /**
+   * Error handler function signature
+   */
+  export type ErrorHandler = (context: Hyperspan.Context, error: Error) => unknown | undefined;
+
   /**
    * Middleware function signature
    * Accepts context and next function, returns a Response
@@ -123,7 +135,8 @@ export namespace Hyperspan {
 
   export interface Route {
     _kind: 'hsRoute';
-    _config: Hyperspan.RouteConfig;
+    _config: Partial<Hyperspan.RouteConfig>;
+    _serverConfig?: Hyperspan.Config;
     _path(): string;
     _methods(): string[];
     get: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
@@ -132,7 +145,7 @@ export namespace Hyperspan {
     patch: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
     delete: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
     options: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
-    errorHandler: (handler: Hyperspan.RouteHandler) => Hyperspan.Route;
+    errorHandler: (handler: Hyperspan.ErrorHandler) => Hyperspan.Route;
     middleware: (middleware: Array<Hyperspan.MiddlewareFunction>) => Hyperspan.Route;
     fetch: (request: Request) => Promise<Response>;
   };
@@ -147,7 +160,7 @@ export namespace Hyperspan {
   ) => ActionResponse;
   export interface Action<T extends z.ZodTypeAny> {
     _kind: 'hsAction';
-    _config: Hyperspan.RouteConfig;
+    _config: Partial<Hyperspan.RouteConfig>;
     _path(): string;
     _form: null | ActionFormHandler<T>;
     form(form: ActionFormHandler<T>): Action<T>;
@@ -157,4 +170,19 @@ export namespace Hyperspan {
     middleware: (middleware: Array<Hyperspan.MiddlewareFunction>) => Action<T>;
     fetch: (request: Request) => Promise<Response>;
   }
+
+  /**
+   * Client JS Module = ESM Module + Public Path + Render Script Tag
+   */
+  export type ClientJSBuildResult = {
+    assetHash: string; // Asset hash of the module path
+    esmName: string; // Filename of the built JavaScript file without the extension
+    publicPath: string; // Full public path of the built JavaScript file
+    /**
+     * Render a <script type="module"> tag for the JS module
+     * @param loadScript - A function that loads the module or a string of code to load the module
+     * @returns HSHtml Template with the <script type="module"> tag
+     */
+    renderScriptTag: (loadScript?: ((module: unknown) => HSHtml | string) | string) => HSHtml;
+  }
 }

package/src/utils.test.ts

@@ -149,13 +149,13 @@ describe('parsePath', () => {
   test('parsePath handles catch-all param with spread', () => {
     const result = parsePath('users/[...slug]');
     expect(result.path).toBe('/users/*');
-    expect(result.params).toEqual(['slug']);
+    expect(result.params).toEqual(['...slug']);
   });
 
   test('parsePath handles catch-all param at root', () => {
     const result = parsePath('[...slug]');
     expect(result.path).toBe('/*');
-    expect(result.params).toEqual(['slug']);
+    expect(result.params).toEqual(['...slug']);
   });
 
   test('parsePath preserves param names in path but converts format', () => {

package/src/utils.ts

@@ -33,7 +33,7 @@ export function parsePath(urlPath: string): { path: string, params: string[] } {
   // Dynamic params
   if (ROUTE_SEGMENT_REGEX.test(urlPath)) {
     urlPath = urlPath.replace(ROUTE_SEGMENT_REGEX, (match: string) => {
-      const paramName = match.replace(/[^a-zA-Z_\.]+/g, '').replace('...', '');
+      const paramName = match.replace(/[^a-zA-Z_\.]+/g, '');
       params.push(paramName);
 
       if (match.includes('...')) {

package/src/plugins.ts

@@ -1,94 +0,0 @@
-import type { Hyperspan as HS } from './types';
-import { JS_PUBLIC_PATH, JS_IMPORT_MAP } from './client/js';
-import { assetHash } from './utils';
-import { IS_PROD } from './server';
-import { join } from 'node:path';
-
-export const CSS_PUBLIC_PATH = '/_hs/css';
-const CLIENT_JS_CACHE = new Map<string, string>();
-const EXPORT_REGEX = /export\{(.*)\}/g;
-
-/**
- * Hyperspan Client JS Plugin
- */
-export function clientJSPlugin(): HS.Plugin {
-  return async (config: HS.Config) => {
-    // Define a Bun plugin to handle .client.ts files
-    await Bun.plugin({
-      name: 'Hyperspan Client JS Loader',
-      async setup(build) {
-        // when a .client.ts file is imported...
-        build.onLoad({ filter: /\.client\.ts$/ }, async (args) => {
-          const jsId = assetHash(args.path);
-
-          // Cache: Avoid re-processing the same file
-          if (IS_PROD && CLIENT_JS_CACHE.has(jsId)) {
-            return {
-              contents: CLIENT_JS_CACHE.get(jsId) || '',
-              loader: 'js',
-            };
-          }
-
-          // We need to build the file to ensure we can ship it to the client with dependencies
-          // Ironic, right? Calling Bun.build() inside of a plugin that runs on Bun.build()?
-          const result = await Bun.build({
-            entrypoints: [args.path],
-            outdir: join(config.publicDir, JS_PUBLIC_PATH),
-            naming: IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined,
-            external: Array.from(JS_IMPORT_MAP.keys()),
-            minify: IS_PROD,
-            format: 'esm',
-            target: 'browser',
-            env: 'APP_PUBLIC_*',
-          });
-
-          // Add output file to import map
-          const esmName = String(result.outputs[0].path.split('/').reverse()[0]).replace('.js', '');
-          JS_IMPORT_MAP.set(esmName, `${JS_PUBLIC_PATH}/${esmName}.js`);
-
-          // Get the contents of the file to extract the exports
-          const contents = await result.outputs[0].text();
-          const exportLine = EXPORT_REGEX.exec(contents);
-
-          let exports = '{}';
-          if (exportLine) {
-            const exportName = exportLine[1];
-            exports =
-              '{' +
-              exportName
-                .split(',')
-                .map((name) => name.trim().split(' as '))
-                .map(([name, alias]) => `${alias === 'default' ? 'default as ' + name : alias}`)
-                .join(', ') +
-              '}';
-          }
-          const fnArgs = exports.replace(/(\w+)\s*as\s*(\w+)/g, '$1: $2');
-
-          // Export a special object that can be used to render the client JS as a script tag
-          const moduleCode = `// hyperspan:processed
-import { functionToString } from '@hyperspan/framework/client/js';
-
-// hyperspan:client-js-plugin
-export const __CLIENT_JS = {
-  id: "${jsId}",
-  esmName: "${esmName}",
-  sourceFile: "${args.path}",
-  outputFile: "${result.outputs[0].path}",
-  renderScriptTag: ({ loadScript }) => {
-    const fn = loadScript ? (typeof loadScript === 'string' ? loadScript : \`const fn = \${functionToString(loadScript)}; fn(${fnArgs});\`) : '';
-    return \`<script type="module" data-source-id="${jsId}">import ${exports} from "${esmName}";\n\${fn}</script>\`;
-  },
-}
-`;
-
-          CLIENT_JS_CACHE.set(jsId, moduleCode);
-
-          return {
-            contents: moduleCode,
-            loader: 'js',
-          };
-        });
-      },
-    });
-  };
-}