@hyperspan/framework 0.2.0 → 0.3.1

package/build.ts

@@ -1,7 +1,7 @@
 import { build } from 'bun';
 
 const entrypoints = ['./src/server.ts', './src/assets.ts'];
-const external = ['@hyperspan/html', 'preact', 'preact-render-to-string'];
+const external = ['@hyperspan/html'];
 const outdir = './dist';
 const target = 'node';
 const splitting = true;

package/dist/server.js

@@ -1833,6 +1833,7 @@ function createConfig(config) {
 }
 function createRoute(handler) {
   let _handlers = {};
+  let _middleware = [];
   if (handler) {
     _handlers["GET"] = handler;
   }
@@ -1858,34 +1859,52 @@ function createRoute(handler) {
       _handlers["PATCH"] = handler2;
       return api;
     },
-    async run(method, context) {
-      const handler2 = _handlers[method];
-      if (!handler2) {
-        throw new HTTPException(405, { message: "Method not allowed" });
-      }
-      const routeContent = await handler2(context);
-      if (routeContent instanceof Response) {
-        return routeContent;
-      }
-      const userIsBot = isbot(context.req.header("User-Agent"));
-      const streamOpt = context.req.query("__nostream");
-      const streamingEnabled = !userIsBot && (streamOpt !== undefined ? streamOpt : true);
-      const routeKind = typeof routeContent;
-      if (isHSHtml(routeContent)) {
-        if (streamingEnabled) {
-          return new StreamResponse(renderStream(routeContent));
-        } else {
-          const output = await renderAsync(routeContent);
-          return context.html(output);
+    middleware(middleware) {
+      _middleware = middleware;
+      return api;
+    },
+    _getRouteHandlers() {
+      return [
+        ..._middleware,
+        async (context) => {
+          const method = context.req.method.toUpperCase();
+          try {
+            const handler2 = _handlers[method];
+            if (!handler2) {
+              throw new HTTPException(405, { message: "Method not allowed" });
+            }
+            const routeContent = await handler2(context);
+            if (routeContent instanceof Response) {
+              return routeContent;
+            }
+            const userIsBot = isbot(context.req.header("User-Agent"));
+            const streamOpt = context.req.query("__nostream");
+            const streamingEnabled = !userIsBot && (streamOpt !== undefined ? streamOpt : true);
+            if (isHSHtml(routeContent)) {
+              if (streamingEnabled) {
+                return new StreamResponse(renderStream(routeContent));
+              } else {
+                const output = await renderAsync(routeContent);
+                return context.html(output);
+              }
+            }
+            if (routeContent instanceof Response) {
+              return routeContent;
+            }
+            return context.text(String(routeContent));
+          } catch (e) {
+            !IS_PROD && console.error(e);
+            return await showErrorReponse(context, e);
+          }
         }
-      }
-      return context.text(String(routeContent));
+      ];
     }
   };
   return api;
 }
 function createAPIRoute(handler) {
   let _handlers = {};
+  let _middleware = [];
   if (handler) {
     _handlers["GET"] = handler;
   }
@@ -1911,30 +1930,46 @@ function createAPIRoute(handler) {
       _handlers["PATCH"] = handler2;
       return api;
     },
-    async run(method, context) {
-      const handler2 = _handlers[method];
-      if (!handler2) {
-        throw new Error("Method not allowed");
-      }
-      try {
-        const response = await handler2(context);
-        if (response instanceof Response) {
-          return response;
-        }
-        return context.json({ meta: { success: true, dtResponse: new Date }, data: response }, { status: 200 });
-      } catch (err) {
-        const e = err;
-        console.error(e);
-        return context.json({
-          meta: { success: false, dtResponse: new Date },
-          data: {},
-          error: {
-            message: e.message,
-            stack: IS_PROD ? undefined : e.stack?.split(`
+    middleware(middleware) {
+      _middleware = middleware;
+      return api;
+    },
+    _getRouteHandlers() {
+      return [
+        ..._middleware,
+        async (context) => {
+          const method = context.req.method.toUpperCase();
+          const handler2 = _handlers[method];
+          if (!handler2) {
+            return context.json({
+              meta: { success: false, dtResponse: new Date },
+              data: {},
+              error: {
+                message: "Method not allowed"
+              }
+            }, { status: 405 });
+          }
+          try {
+            const response = await handler2(context);
+            if (response instanceof Response) {
+              return response;
+            }
+            return context.json({ meta: { success: true, dtResponse: new Date }, data: response }, { status: 200 });
+          } catch (err) {
+            const e = err;
+            !IS_PROD && console.error(e);
+            return context.json({
+              meta: { success: false, dtResponse: new Date },
+              data: {},
+              error: {
+                message: e.message,
+                stack: IS_PROD ? undefined : e.stack?.split(`
 `)
+              }
+            }, { status: 500 });
           }
-        }, { status: 500 });
-      }
+        }
+      ];
     }
   };
   return api;
@@ -1950,13 +1985,10 @@ function getRunnableRoute(route) {
   if (kind === "object" && "default" in route) {
     return getRunnableRoute(route.default);
   }
-  throw new Error('Route not runnable. Use "export default createRoute()" to create a Hyperspan route.');
+  throw new Error(`Route not runnable. Use "export default createRoute()" to create a Hyperspan route. Exported methods found were: ${Object.keys(route).join(", ")}`);
 }
 function isRunnableRoute(route) {
-  return typeof route === "object" && "run" in route;
-}
-function createLayout(layout) {
-  return layout;
+  return typeof route === "object" && "_getRouteHandlers" in route;
 }
 async function showErrorReponse(context, err) {
   const output = render(html`
@@ -2009,20 +2041,8 @@ async function buildRoutes(config) {
   return routes;
 }
 function createRouteFromModule(RouteModule) {
-  return async (context) => {
-    const reqMethod = context.req.method.toUpperCase();
-    try {
-      const runnableRoute = getRunnableRoute(RouteModule);
-      const content = await runnableRoute.run(reqMethod, context);
-      if (content instanceof Response) {
-        return content;
-      }
-      return context.text(String(content));
-    } catch (e) {
-      console.error(e);
-      return await showErrorReponse(context, e);
-    }
-  };
+  const route = getRunnableRoute(RouteModule);
+  return route._getRouteHandlers();
 }
 async function createServer(config) {
   await Promise.all([buildClientJS(), buildClientCSS()]);
@@ -2035,7 +2055,8 @@ async function createServer(config) {
     const fullRouteFile = join(CWD, route.file);
     const routePattern = normalizePath(route.route);
     routeMap.push({ route: routePattern, file: route.file });
-    app.all(routePattern, createRouteFromModule(await import(fullRouteFile)));
+    const routeHandlers = createRouteFromModule(await import(fullRouteFile));
+    app.all(routePattern, ...routeHandlers);
   }
   if (routeMap.length === 0) {
     app.get("/", (context) => {
@@ -2101,7 +2122,6 @@ export {
   createRouteFromModule,
   createRoute,
   createReadableStreamFromAsyncGenerator,
-  createLayout,
   createConfig,
   createAPIRoute,
   buildRoutes,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@hyperspan/framework",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Hyperspan Web Framework",
-  "main": "dist/server.js",
+  "main": "dist/server.ts",
   "types": "src/server.ts",
   "public": true,
   "publishConfig": {
@@ -63,6 +63,6 @@
     "@hyperspan/html": "^0.1.7",
     "hono": "^4.7.10",
     "isbot": "^5.1.28",
-    "zod": "^3.25.28"
+    "zod": "^3.25.42"
   }
 }

package/src/server.ts

@@ -6,6 +6,7 @@ import { buildClientJS, buildClientCSS } from './assets';
 import { Hono, type Context } from 'hono';
 import { serveStatic } from 'hono/bun';
 import { HTTPException } from 'hono/http-exception';
+import type { HandlerResponse, MiddlewareHandler } from 'hono/types';
 
 export const IS_PROD = process.env.NODE_ENV === 'production';
 const CWD = process.cwd();
@@ -15,8 +16,7 @@ const CWD = process.cwd();
  */
 export type THSResponseTypes = HSHtml | Response | string | null;
 export type THSRouteHandler = (context: Context) => THSResponseTypes | Promise<THSResponseTypes>;
-export type THSAPIResponseTypes = Response | Record<any, any> | void;
-export type THSAPIRouteHandler = (context: Context) => THSResponseTypes | Promise<THSResponseTypes>;
+export type THSAPIRouteHandler = (context: Context) => Promise<any> | any;
 
 export type THSRoute = {
   _kind: 'hsRoute';
@@ -25,7 +25,18 @@ export type THSRoute = {
   put: (handler: THSRouteHandler) => THSRoute;
   delete: (handler: THSRouteHandler) => THSRoute;
   patch: (handler: THSRouteHandler) => THSRoute;
-  run: (method: string, context: Context) => Promise<Response>;
+  middleware: (middleware: Array<MiddlewareHandler>) => THSRoute;
+  _getRouteHandlers: () => Array<MiddlewareHandler | ((context: Context) => HandlerResponse<any>)>;
+};
+export type THSAPIRoute = {
+  _kind: 'hsAPIRoute';
+  get: (handler: THSAPIRouteHandler) => THSAPIRoute;
+  post: (handler: THSAPIRouteHandler) => THSAPIRoute;
+  put: (handler: THSAPIRouteHandler) => THSAPIRoute;
+  delete: (handler: THSAPIRouteHandler) => THSAPIRoute;
+  patch: (handler: THSAPIRouteHandler) => THSAPIRoute;
+  middleware: (middleware: Array<MiddlewareHandler>) => THSAPIRoute;
+  _getRouteHandlers: () => Array<MiddlewareHandler | ((context: Context) => HandlerResponse<any>)>;
 };
 
 export function createConfig(config: THSServerConfig): THSServerConfig {
@@ -38,6 +49,7 @@ export function createConfig(config: THSServerConfig): THSServerConfig {
  */
 export function createRoute(handler?: THSRouteHandler): THSRoute {
   let _handlers: Record<string, THSRouteHandler> = {};
+  let _middleware: Array<MiddlewareHandler> = [];
 
   if (handler) {
     _handlers['GET'] = handler;
@@ -65,37 +77,57 @@ export function createRoute(handler?: THSRouteHandler): THSRoute {
       _handlers['PATCH'] = handler;
       return api;
     },
-    async run(method: string, context: Context): Promise<Response> {
-      const handler = _handlers[method];
-      if (!handler) {
-        throw new HTTPException(405, { message: 'Method not allowed' });
-      }
-
-      const routeContent = await handler(context);
-
-      // Return Response if returned from route handler
-      if (routeContent instanceof Response) {
-        return routeContent;
-      }
-
-      // @TODO: Move this to config or something...
-      const userIsBot = isbot(context.req.header('User-Agent'));
-      const streamOpt = context.req.query('__nostream');
-      const streamingEnabled = !userIsBot && (streamOpt !== undefined ? streamOpt : true);
-      const routeKind = typeof routeContent;
-
-      // Render HSHtml if returned from route handler
-      if (isHSHtml(routeContent)) {
-        if (streamingEnabled) {
-          return new StreamResponse(renderStream(routeContent as HSHtml)) as Response;
-        } else {
-          const output = await renderAsync(routeContent as HSHtml);
-          return context.html(output);
-        }
-      }
-
-      // Return unknown content - not specifically handled above
-      return context.text(String(routeContent));
+    middleware(middleware: Array<MiddlewareHandler>) {
+      _middleware = middleware;
+      return api;
+    },
+    _getRouteHandlers() {
+      return [
+        ..._middleware,
+        async (context: Context) => {
+          const method = context.req.method.toUpperCase();
+
+          try {
+            const handler = _handlers[method];
+            if (!handler) {
+              throw new HTTPException(405, { message: 'Method not allowed' });
+            }
+
+            const routeContent = await handler(context);
+
+            // Return Response if returned from route handler
+            if (routeContent instanceof Response) {
+              return routeContent;
+            }
+
+            // @TODO: Move this to config or something...
+            const userIsBot = isbot(context.req.header('User-Agent'));
+            const streamOpt = context.req.query('__nostream');
+            const streamingEnabled = !userIsBot && (streamOpt !== undefined ? streamOpt : true);
+
+            // Render HSHtml if returned from route handler
+            if (isHSHtml(routeContent)) {
+              if (streamingEnabled) {
+                return new StreamResponse(renderStream(routeContent as HSHtml)) as Response;
+              } else {
+                const output = await renderAsync(routeContent as HSHtml);
+                return context.html(output);
+              }
+            }
+
+            // Return custom Response if returned from route handler
+            if (routeContent instanceof Response) {
+              return routeContent;
+            }
+
+            // Return unknown content - not specifically handled above
+            return context.text(String(routeContent));
+          } catch (e) {
+            !IS_PROD && console.error(e);
+            return await showErrorReponse(context, e as Error);
+          }
+        },
+      ];
     },
   };
 
@@ -106,14 +138,15 @@ export function createRoute(handler?: THSRouteHandler): THSRoute {
  * Create new API Route
  * API Route handlers should return a JSON object or a Response
  */
-export function createAPIRoute(handler?: THSAPIRouteHandler): THSRoute {
+export function createAPIRoute(handler?: THSAPIRouteHandler): THSAPIRoute {
   let _handlers: Record<string, THSAPIRouteHandler> = {};
+  let _middleware: Array<MiddlewareHandler> = [];
 
   if (handler) {
     _handlers['GET'] = handler;
   }
 
-  const api: THSRoute = {
+  const api: THSAPIRoute = {
     _kind: 'hsRoute',
     get(handler: THSAPIRouteHandler) {
       _handlers['GET'] = handler;
@@ -135,39 +168,59 @@ export function createAPIRoute(handler?: THSAPIRouteHandler): THSRoute {
       _handlers['PATCH'] = handler;
       return api;
     },
-    async run(method: string, context: Context): Promise<Response> {
-      const handler = _handlers[method];
-      if (!handler) {
-        throw new Error('Method not allowed');
-      }
-
-      try {
-        const response = await handler(context);
-
-        if (response instanceof Response) {
-          return response;
-        }
+    middleware(middleware: Array<MiddlewareHandler>) {
+      _middleware = middleware;
+      return api;
+    },
+    _getRouteHandlers() {
+      return [
+        ..._middleware,
+        async (context: Context) => {
+          const method = context.req.method.toUpperCase();
+          const handler = _handlers[method];
+
+          if (!handler) {
+            return context.json(
+              {
+                meta: { success: false, dtResponse: new Date() },
+                data: {},
+                error: {
+                  message: 'Method not allowed',
+                },
+              },
+              { status: 405 }
+            );
+          }
 
-        return context.json(
-          { meta: { success: true, dtResponse: new Date() }, data: response },
-          { status: 200 }
-        );
-      } catch (err) {
-        const e = err as Error;
-        console.error(e);
-
-        return context.json(
-          {
-            meta: { success: false, dtResponse: new Date() },
-            data: {},
-            error: {
-              message: e.message,
-              stack: IS_PROD ? undefined : e.stack?.split('\n'),
-            },
-          },
-          { status: 500 }
-        );
-      }
+          try {
+            const response = await handler(context);
+
+            if (response instanceof Response) {
+              return response;
+            }
+
+            return context.json(
+              { meta: { success: true, dtResponse: new Date() }, data: response },
+              { status: 200 }
+            );
+          } catch (err) {
+            const e = err as Error;
+            !IS_PROD && console.error(e);
+
+            return context.json(
+              {
+                meta: { success: false, dtResponse: new Date() },
+                data: {},
+                error: {
+                  message: e.message,
+                  stack: IS_PROD ? undefined : e.stack?.split('\n'),
+                },
+              },
+              { status: 500 }
+            );
+          }
+        },
+      ];
     },
   };
 
@@ -199,21 +252,13 @@ export function getRunnableRoute(route: unknown): THSRoute {
 
   // No route -> error
   throw new Error(
-    'Route not runnable. Use "export default createRoute()" to create a Hyperspan route.'
+    `Route not runnable. Use "export default createRoute()" to create a Hyperspan route. Exported methods found were: ${Object.keys(route as {}).join(', ')}`
   );
 }
 
 export function isRunnableRoute(route: unknown): boolean {
   // @ts-ignore
-  return typeof route === 'object' && 'run' in route;
-}
-
-/**
- * Create a layout for a Hyperspan app. Passthrough for now.
- * Future intent is to be able to conditionally render a layout for full page content vs. partial content.
- */
-export function createLayout<T>(layout: (props: T) => HSHtml | Promise<HSHtml>) {
-  return layout;
+  return typeof route === 'object' && '_getRouteHandlers' in route;
 }
 
 /**
@@ -305,24 +350,11 @@ export async function buildRoutes(config: THSServerConfig): Promise<THSRouteMap[
 /**
  * Run route from file
  */
-export function createRouteFromModule(RouteModule: any): (context: Context) => Promise<Response> {
-  return async (context: Context) => {
-    const reqMethod = context.req.method.toUpperCase();
-
-    try {
-      const runnableRoute = getRunnableRoute(RouteModule);
-      const content = await runnableRoute.run(reqMethod, context);
-
-      if (content instanceof Response) {
-        return content;
-      }
-
-      return context.text(String(content));
-    } catch (e) {
-      console.error(e);
-      return await showErrorReponse(context, e as Error);
-    }
-  };
+export function createRouteFromModule(
+  RouteModule: any
+): Array<MiddlewareHandler | ((context: Context) => HandlerResponse<any>)> {
+  const route = getRunnableRoute(RouteModule);
+  return route._getRouteHandlers();
 }
 
 /**
@@ -349,7 +381,8 @@ export async function createServer(config: THSServerConfig): Promise<Hono> {
     routeMap.push({ route: routePattern, file: route.file });
 
     // Import route
-    app.all(routePattern, createRouteFromModule(await import(fullRouteFile)));
+    const routeHandlers = createRouteFromModule(await import(fullRouteFile));
+    app.all(routePattern, ...routeHandlers);
   }
 
   // Help route if no routes found
@@ -386,6 +419,7 @@ export async function createServer(config: THSServerConfig): Promise<Hono> {
   );
 
   app.notFound((context) => {
+    // @TODO: Add a custom 404 route
     return context.text('Not... found?', { status: 404 });
   });