@hyperspan/framework 1.0.9 → 1.0.11

package/package.json

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

package/src/actions.ts

@@ -109,12 +109,12 @@ export function createAction<T extends z.ZodObject<any, any>>(params: { name: st
       _errorHandler = handler;
       return api;
     },
-    use(middleware: HS.MiddlewareFunction) {
-      route.use(middleware);
+    use(middleware: HS.MiddlewareFunction, opts?: HS.MiddlewareMethodOptions) {
+      route.use(middleware, opts);
       return api;
     },
-    middleware(middleware: Array<HS.MiddlewareFunction>) {
-      route.middleware(middleware);
+    middleware(middleware: Array<HS.MiddlewareFunction>, opts?: HS.MiddlewareMethodOptions) {
+      route.middleware(middleware, opts);
       return api;
     },
     fetch: route.fetch,

package/src/middleware.ts

@@ -1,9 +1,9 @@
 import { formDataToJSON } from './utils';
 import { z, flattenError, prettifyError } from 'zod/v4';
+import { HTTPResponseException } from './server';
 
 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';
 
@@ -25,7 +25,7 @@ function inferValidationType(headers: Headers): TValidationType {
   return 'json';
 }
 
-export class ZodValidationError extends Error {
+export class ZodValidationError extends Error implements HS.ZodValidationError {
   public fieldErrors;
   public formErrors: unknown[];
   constructor(error: ZodError, schema: ZodObject | ZodAny) {
@@ -38,6 +38,9 @@ export class ZodValidationError extends Error {
   }
 }
 
+/**
+ * Validate the query parameters of the request using a Zod schema.
+ */
 export function validateQuery(schema: ZodObject | ZodAny): HS.MiddlewareFunction {
   return async (context: HS.Context, next: HS.NextFunction) => {
     const query = formDataToJSON(context.req.query);
@@ -55,6 +58,9 @@ export function validateQuery(schema: ZodObject | ZodAny): HS.MiddlewareFunction
   }
 }
 
+/**
+ * Validate the body of the request using a Zod schema. Type can be inferred from the Content-Type header or provided explicitly.
+ */
 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

package/src/server.ts

@@ -122,11 +122,11 @@ 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 = {
     _kind: 'hsRoute',
     _config: config,
+    _middleware: { GET: [], POST: [], PUT: [], PATCH: [], DELETE: [], HEAD: [], OPTIONS: [], '*': [] },
     _methods: () => Object.keys(_handlers),
     _path() {
       if (this._config.path) {
@@ -141,7 +141,7 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
      */
     get(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
       _handlers['GET'] = handler;
-      _middleware['GET'] = handlerOptions?.middleware || [];
+      api._middleware['GET'] = handlerOptions?.middleware || [];
       return api;
     },
     /**
@@ -149,7 +149,7 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
      */
     post(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
       _handlers['POST'] = handler;
-      _middleware['POST'] = handlerOptions?.middleware || [];
+      api._middleware['POST'] = handlerOptions?.middleware || [];
       return api;
     },
     /**
@@ -157,7 +157,7 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
      */
     put(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
       _handlers['PUT'] = handler;
-      _middleware['PUT'] = handlerOptions?.middleware || [];
+      api._middleware['PUT'] = handlerOptions?.middleware || [];
       return api;
     },
     /**
@@ -165,7 +165,7 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
      */
     patch(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
       _handlers['PATCH'] = handler;
-      _middleware['PATCH'] = handlerOptions?.middleware || [];
+      api._middleware['PATCH'] = handlerOptions?.middleware || [];
       return api;
     },
     /**
@@ -173,7 +173,7 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
      */
     delete(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
       _handlers['DELETE'] = handler;
-      _middleware['DELETE'] = handlerOptions?.middleware || [];
+      api._middleware['DELETE'] = handlerOptions?.middleware || [];
       return api;
     },
     /**
@@ -181,7 +181,7 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
      */
     options(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
       _handlers['OPTIONS'] = handler;
-      _middleware['OPTIONS'] = handlerOptions?.middleware || [];
+      api._middleware['OPTIONS'] = handlerOptions?.middleware || [];
       return api;
     },
     /**
@@ -189,7 +189,7 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
      */
     all(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
       _handlers['*'] = handler;
-      _middleware['*'] = handlerOptions?.middleware || [];
+      api._middleware['*'] = handlerOptions?.middleware || [];
       return api;
     },
     /**
@@ -202,16 +202,24 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
     /**
      * Add a middleware function to this route (for all HTTP methods) (non-destructive)
      */
-    use(middleware: HS.MiddlewareFunction) {
-      _middleware['*'].push(middleware);
+    use(middleware: HS.MiddlewareFunction, opts: { method?: HS.MiddlewareMethod } = {}) {
+      if (opts.method) {
+        api._middleware[opts.method].push(middleware);
+      } else {
+        api._middleware['*'].push(middleware);
+      }
       return api;
     },
     /**
      * Set the complete middleware stack for this route (for all HTTP methods) (destructive)
      * NOTE: This will override the middleware stack for this route
      */
-    middleware(middleware: Array<HS.MiddlewareFunction>) {
-      _middleware['*'] = middleware;
+    middleware(middleware: Array<HS.MiddlewareFunction>, opts: { method?: HS.MiddlewareMethod } = {}) {
+      if (opts.method) {
+        api._middleware[opts.method] = middleware;
+      } else {
+        api._middleware['*'] = middleware;
+      }
       return api;
     },
 
@@ -220,9 +228,9 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
      */
     async fetch(request: Request) {
       const context = createContext(request, api);
-      const method = context.req.method;
-      const globalMiddleware = _middleware['*'] || [];
-      const methodMiddleware = _middleware[method] || [];
+      const method = context.req.method as HS.MiddlewareMethod;
+      const globalMiddleware = api._middleware['*'] || [];
+      const methodMiddleware = api._middleware[method] || [];
 
       const methodHandler = async (context: HS.Context) => {
         // Handle CORS preflight requests (if no OPTIONS handler is defined)
@@ -253,8 +261,18 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
           return context.res.error(new Error('Method not allowed'), { status: 405 });
         }
 
-        // @TODO: Handle errors from route handler
-        const routeContent = await handler(context);
+        // Run the route handler
+        let routeContent: unknown;
+        try {
+          routeContent = await handler(context);
+        } catch (e) {
+          // Return the response from the HTTPResponseException if it exists
+          if (e instanceof HTTPResponseException) {
+            routeContent = e._response;
+          } else {
+            throw e;
+          }
+        }
 
         // Return Response if returned from route handler
         if (routeContent instanceof Response) {
@@ -296,7 +314,6 @@ export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
  * Creates a server object that can compose routes and middleware
  */
 export async function createServer(config: HS.Config = {} as HS.Config): Promise<HS.Server> {
-  const _middleware: HS.MiddlewareFunction[] = [];
   const _routes: HS.Route[] = [];
 
   // Load plugins, if any
@@ -307,9 +324,13 @@ export async function createServer(config: HS.Config = {} as HS.Config): Promise
   const api: HS.Server = {
     _config: config,
     _routes: _routes,
-    _middleware: _middleware,
-    use(middleware: HS.MiddlewareFunction) {
-      _middleware.push(middleware);
+    _middleware: { GET: [], POST: [], PUT: [], PATCH: [], DELETE: [], HEAD: [], OPTIONS: [], '*': [] },
+    use(middleware: HS.MiddlewareFunction, opts?: HS.MiddlewareMethodOptions) {
+      if (opts?.method) {
+        api._middleware[opts.method].push(middleware);
+      } else {
+        api._middleware['*'].push(middleware);
+      }
       return this;
     },
     get(path: string, handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {

package/src/types.ts

@@ -1,5 +1,4 @@
 import { HSHtml } from '@hyperspan/html';
-import { ZodValidationError } from './middleware';
 import * as z from 'zod/v4';
 
 /**
@@ -9,8 +8,8 @@ export namespace Hyperspan {
   export interface Server {
     _config: Hyperspan.Config;
     _routes: Array<Hyperspan.Route>;
-    _middleware: Array<Hyperspan.MiddlewareFunction>;
-    use: (middleware: Hyperspan.MiddlewareFunction) => Hyperspan.Server;
+    _middleware: Record<Hyperspan.MiddlewareMethod, Array<Hyperspan.MiddlewareFunction>>;
+    use: (middleware: Hyperspan.MiddlewareFunction, opts?: Hyperspan.MiddlewareMethodOptions) => Hyperspan.Server;
     get: (path: string, handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
     post: (path: string, handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
     put: (path: string, handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
@@ -134,11 +133,16 @@ export namespace Hyperspan {
     context: Hyperspan.Context,
     next: Hyperspan.NextFunction
   ) => Promise<Response> | Response;
+  export type MiddlewareMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | '*';
+  export type MiddlewareMethodOptions = {
+    method?: Hyperspan.MiddlewareMethod;
+  };
 
   export interface Route {
     _kind: 'hsRoute';
     _config: Partial<Hyperspan.RouteConfig>;
     _serverConfig?: Hyperspan.Config;
+    _middleware: Record<MiddlewareMethod, Array<Hyperspan.MiddlewareFunction>>;
     _path(): string;
     _methods(): string[];
     get: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
@@ -149,8 +153,8 @@ export namespace Hyperspan {
     options: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
     all: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
     errorHandler: (handler: Hyperspan.ErrorHandler) => Hyperspan.Route;
-    use: (middleware: Hyperspan.MiddlewareFunction) => Hyperspan.Route;
-    middleware: (middleware: Array<Hyperspan.MiddlewareFunction>) => Hyperspan.Route;
+    use: (middleware: Hyperspan.MiddlewareFunction, opts?: Hyperspan.MiddlewareMethodOptions) => Hyperspan.Route;
+    middleware: (middleware: Array<Hyperspan.MiddlewareFunction>, opts?: Hyperspan.MiddlewareMethodOptions) => Hyperspan.Route;
     fetch: (request: Request) => Promise<Response>;
   };
 
@@ -179,8 +183,8 @@ export namespace Hyperspan {
     render: (c: Context, props?: ActionFormProps<T>) => ActionFormResponse;
     post: (handler: ActionFormHandler<T>) => Action<T>;
     errorHandler: (handler: ActionFormHandler<T>) => Action<T>;
-    use: (middleware: Hyperspan.MiddlewareFunction) => Action<T>;
-    middleware: (middleware: Array<Hyperspan.MiddlewareFunction>) => Action<T>;
+    use: (middleware: Hyperspan.MiddlewareFunction, opts?: Hyperspan.MiddlewareMethodOptions) => Action<T>;
+    middleware: (middleware: Array<Hyperspan.MiddlewareFunction>, opts?: Hyperspan.MiddlewareMethodOptions) => Action<T>;
     fetch: (request: Request) => Promise<Response>;
   }
 
@@ -198,4 +202,12 @@ export namespace Hyperspan {
      */
     renderScriptTag: (loadScript?: ((module: unknown) => HSHtml | string | void) | string) => HSHtml;
   }
+
+  /**
+   * Zod validation error type. Used in actions and validation middleware.
+   */
+  export interface ZodValidationError extends Error {
+    fieldErrors: Record<string, string[] | undefined>;
+    formErrors: unknown[];
+  }
 }