@hyperspan/framework 1.0.0-alpha.14 → 1.0.0-alpha.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "1.0.0-alpha.14",
+  "version": "1.0.0-alpha.15",
   "description": "Hyperspan Web Framework",
   "main": "src/server.ts",
   "types": "src/server.ts",
@@ -73,6 +73,7 @@
   },
   "dependencies": {
     "@hyperspan/html": "^1.0.0-alpha",
+    "isbot": "^5.1.32",
     "zod": "^4.1.12"
   }
 }

package/src/actions.ts

@@ -1,10 +1,12 @@
-import { html, HSHtml } from '@hyperspan/html';
+import { html } from '@hyperspan/html';
 import { createRoute, 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 } 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)}`;
 
@@ -30,7 +32,7 @@ export function createAction<T extends z.ZodTypeAny>(params: { name: string; sch
     .get((c: HS.Context) => api.render(c))
     .post(async (c: HS.Context) => {
       // Parse form data
-      const formData = await c.req.raw.formData();
+      const formData = await c.req.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;
@@ -69,7 +71,10 @@ export function createAction<T extends z.ZodTypeAny>(params: { name: string; sch
       }
 
       return await returnHTMLResponse(c, () => api.render(c, { data, error }), { status: 400 });
-    });
+    }, { middleware: schema ? [validateBody(schema)] : [] });
+
+  // Set the name of the action for the route
+  route._config.name = name;
 
   const api: HS.Action<T> = {
     _kind: 'hsAction',
@@ -101,7 +106,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/js.ts

@@ -1,6 +1,7 @@
-import { HSHtml, html } from '@hyperspan/html';
-import { assetHash } from '../utils';
+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';
@@ -11,23 +12,15 @@ 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;
 
-type ClientJSModuleReturn = {
-  esmName: string;
-  jsId: string;
-  publicPath: string;
-  renderScriptTag: (loadScript?: ((module: unknown) => HSHtml | string) | string) => HSHtml;
-}
-
 /**
- * Load a client JS module
+ * Build a client JS module and return a Hyperspan.ClientJSBuildResult object
  */
-export async function loadClientJS(modulePathResolved: string): Promise<ClientJSModuleReturn> {
+export async function buildClientJS(modulePathResolved: string): Promise<HS.ClientJSBuildResult> {
   const modulePath = modulePathResolved.replace('file://', '');
-  const jsId = assetHash(modulePath);
+  const assetHash = assetHashFn(modulePath);
 
   // Cache: Avoid re-processing the same file
-  if (!CLIENT_JS_CACHE.has(jsId)) {
-
+  if (!CLIENT_JS_CACHE.has(assetHash)) {
     // Build the client JS module
     const result = await Bun.build({
       entrypoints: [modulePath],
@@ -62,31 +55,31 @@ export async function loadClientJS(modulePathResolved: string): Promise<ClientJS
         '}';
     }
     const fnArgs = exports.replace(/(\w+)\s*as\s*(\w+)/g, '$1: $2');
-    CLIENT_JS_CACHE.set(jsId, { esmName, exports, fnArgs, publicPath });
+    CLIENT_JS_CACHE.set(assetHash, { esmName, exports, fnArgs, publicPath });
   }
 
-  const { esmName, exports, fnArgs, publicPath } = CLIENT_JS_CACHE.get(jsId)!;
+  const { esmName, exports, fnArgs, publicPath } = CLIENT_JS_CACHE.get(assetHash)!;
 
   return {
+    assetHash,
     esmName,
-    jsId,
     publicPath,
     renderScriptTag: (loadScript) => {
       const t = typeof loadScript;
 
       if (t === 'string') {
         return html`
-          <script type="module" data-source-id="${jsId}">import ${exports} from "${esmName}";\n(${html.raw(loadScript as string)})(${fnArgs});</script>
+          <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="${jsId}">import ${exports} from "${esmName}";\n(${html.raw(functionToString(loadScript))})(${fnArgs});</script>
+          <script type="module" data-source-id="${assetHash}">import ${exports} from "${esmName}";\n(${html.raw(functionToString(loadScript))})(${fnArgs});</script>
         `;
       }
 
       return html`
-        <script type="module" data-source-id="${jsId}">import "${esmName}";</script>
+        <script type="module" data-source-id="${assetHash}">import "${esmName}";</script>
       `;
     }
   }
@@ -97,7 +90,5 @@ export async function loadClientJS(modulePathResolved: string): Promise<ClientJS
  * Handles named, async, and arrow functions
  */
 export function functionToString(fn: any) {
-  let str = fn.toString().trim();
-
-  return str;
+  return fn.toString().trim();
 }

package/src/layout.ts

@@ -1,9 +1,9 @@
 import { html } from '@hyperspan/html';
-import { JS_IMPORT_MAP, loadClientJS } 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 loadClientJS(import.meta.resolve('./client/_hs/hyperspan-streaming.client'));
+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

package/src/middleware.ts

@@ -1,4 +1,91 @@
+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);
+
+    if (!validated.success) {
+      const err = formatZodError(validated.error);
+      return context.res.error(err, { status: 400 });
+    }
+
+    // Store the validated query in the context variables
+    context.vars.query = validated.data as z.infer<typeof schema>;
+
+    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);
+    }
+    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 });
+    }
+
+    // Store the validated body in the context variables
+    context.vars.body = validated.data as z.infer<typeof schema>;
+
+    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 +142,3 @@ export async function executeMiddleware(
   // Start execution from the first handler
   return await createNext(0)();
 }
-

package/src/server.ts

@@ -1,4 +1,5 @@
 import { HSHtml, html, isHSHtml, renderStream, renderAsync, render, _typeOf } from '@hyperspan/html';
+import { isbot } from 'isbot';
 import { executeMiddleware } from './middleware';
 import { parsePath } from './utils';
 import { Cookies } from './cookies';
@@ -8,10 +9,12 @@ import type { Hyperspan as HS } from './types';
 export const IS_PROD = process.env.NODE_ENV === 'production';
 
 export class HTTPResponseException extends Error {
+  public _error?: Error;
   public _response?: Response;
-  constructor(body: string | undefined, options?: ResponseInit) {
-    super(body);
-    this._response = new Response(body, options);
+  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);
   }
 }
 
@@ -19,11 +22,22 @@ export class HTTPResponseException 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: config.plugins ?? [],
+    responseOptions: {
+      ...defaultConfig.responseOptions,
+      ...config.responseOptions,
+    },
   };
 }
 
@@ -102,6 +116,7 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
  */
 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 = {
@@ -140,14 +155,6 @@ export function createRoute(config: Partial<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)
      */
@@ -156,6 +163,14 @@ export function createRoute(config: Partial<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)
      */
@@ -164,8 +179,11 @@ export function createRoute(config: Partial<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;
     },
     /**
@@ -223,7 +241,9 @@ export function createRoute(config: Partial<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);
@@ -239,8 +259,9 @@ export function createRoute(config: Partial<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;
       }
@@ -328,7 +349,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();
@@ -340,12 +361,10 @@ export async function returnHTMLResponse(
 
     // Render HSHtml if returned from route handler
     if (isHSHtml(routeContent)) {
-      // @TODO: Move this to config or something...
-      const disableStreaming = context.req.query.get('__nostream') ?? '0';
-      const streamingEnabled = disableStreaming !== '1';
+      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, {
             renderChunk: (chunk) => {

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 = {
@@ -92,6 +95,9 @@ export namespace Hyperspan {
     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 = {
@@ -113,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
@@ -125,6 +136,7 @@ export namespace Hyperspan {
   export interface Route {
     _kind: 'hsRoute';
     _config: Partial<Hyperspan.RouteConfig>;
+    _serverConfig?: Hyperspan.Config;
     _path(): string;
     _methods(): string[];
     get: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
@@ -133,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>;
   };
@@ -148,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>;
@@ -158,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;
+  }
 }