@hyperspan/framework 0.5.5 → 1.0.0-alpha.1

package/src/server.ts

@@ -1,129 +1,200 @@
-import { buildClientJS, buildClientCSS, assetHash } from './assets';
-import { clientJSPlugin } from './plugins';
 import { HSHtml, html, isHSHtml, renderStream, renderAsync, render } from '@hyperspan/html';
-import { readdir } from 'node:fs/promises';
-import { basename, extname, join } from 'node:path';
-import { isbot } from 'isbot';
-import { Hono, type Context } from 'hono';
-import { serveStatic } from 'hono/bun';
-import { HTTPException } from 'hono/http-exception';
-import { csrf } from 'hono/csrf';
-
-import type { HandlerResponse, MiddlewareHandler } from 'hono/types';
-import type { ContentfulStatusCode } from 'hono/utils/http-status';
+import { executeMiddleware } from './middleware';
+import type { Hyperspan as HS } from './types';
+import { clientJSPlugin } from './plugins';
+export type { HS as Hyperspan };
 
 export const IS_PROD = process.env.NODE_ENV === 'production';
 const CWD = process.cwd();
 
+export class HTTPException extends Error {
+  constructor(public status: number, message?: string) {
+    super(message);
+  }
+}
+
 /**
- * Types
+ * Ensures a valid config object is returned, even with an empty object or partial object passed in
  */
-export type THSContext = Context<any, any, {}>;
-export type THSResponseTypes = HSHtml | Response | string | null;
-export type THSRouteHandler = (context: THSContext) => THSResponseTypes | Promise<THSResponseTypes>;
-export type THSAPIRouteHandler = (context: THSContext) => Promise<any> | any;
-
-export type THSRoute = {
-  _kind: 'hsRoute';
-  get: (handler: THSRouteHandler) => THSRoute;
-  post: (handler: THSRouteHandler) => THSRoute;
-  middleware: (middleware: Array<MiddlewareHandler>) => THSRoute;
-  _getRouteHandlers: () => Array<
-    MiddlewareHandler | ((context: THSContext) => 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: THSContext) => HandlerResponse<any>)
-  >;
-};
-
-export function createConfig(config: THSServerConfig): THSServerConfig {
-  return config;
+export function createConfig(config: Partial<HS.Config> = {}): HS.Config {
+  return {
+    ...config,
+    appDir: config.appDir ?? './app',
+    publicDir: config.publicDir ?? './public',
+    plugins: [clientJSPlugin(), ...(config.plugins ?? [])],
+  };
 }
 
+/**
+ * Creates a context object for a request
+ */
+export function createContext(req: Request, route?: HS.Route): HS.Context {
+  const url = new URL(req.url);
+  const query = new URLSearchParams(url.search);
+  const method = req.method.toUpperCase();
+  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 || {};
+
+  return {
+    route: {
+      path,
+      params: params,
+    },
+    req: {
+      raw: req,
+      url,
+      method,
+      headers,
+      query,
+      body: req.body,
+    },
+    res: {
+      raw: new Response(),
+      html: (html: string, options?: { status?: number; headers?: Headers | Record<string, string> }) => 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> }) => new Response(JSON.stringify(json), { ...options, headers: { 'Content-Type': 'application/json', ...options?.headers } }),
+      text: (text: string, options?: { status?: number; headers?: Headers | Record<string, string> }) => 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> }) => new Response(null, { status: 302, headers: { Location: url, ...options?.headers } }),
+      error: (error: Error, options?: { status?: number; headers?: Headers | Record<string, string> }) => new Response(error.message, { status: 500, ...options }),
+      notFound: (options?: { status?: number; headers?: Headers | Record<string, string> }) => new Response('Not Found', { status: 404, ...options }),
+    },
+  };
+}
+
+
 /**
  * Define a route that can handle a direct HTTP request.
  * Route handlers should return a HSHtml or Response object
  */
-export function createRoute(handler?: THSRouteHandler): THSRoute {
-  let _handlers: Record<string, THSRouteHandler> = {};
-  let _middleware: Array<MiddlewareHandler> = [];
+export function createRoute(config: HS.RouteConfig = {}): HS.Route {
+  const _handlers: Record<string, HS.RouteHandler> = {};
+  let _middleware: Record<string, Array<HS.MiddlewareFunction>> = { '*': [] };
 
-  if (handler) {
-    _handlers['GET'] = handler;
-  }
-
-  const api: THSRoute = {
+  const api: HS.Route = {
     _kind: 'hsRoute',
+    _name: config.name,
+    _config: config,
+    _methods: () => Object.keys(_handlers),
+    _path() {
+      if (this._config.path) {
+        const { path } = parsePath(this._config.path);
+        return path;
+      }
+
+      return '/';
+    },
     /**
      * Add a GET route handler (primary page display)
      */
-    get(handler: THSRouteHandler) {
+    get(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
       _handlers['GET'] = handler;
+      _middleware['GET'] = handlerOptions?.middleware || [];
       return api;
     },
     /**
      * Add a POST route handler (typically to process form data)
      */
-    post(handler: THSRouteHandler) {
+    post(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
       _handlers['POST'] = handler;
+      _middleware['POST'] = handlerOptions?.middleware || [];
+      return api;
+    },
+    /**
+     * Add a PUT route handler (typically to update existing data)
+     */
+    put(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
+      _handlers['PUT'] = handler;
+      _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)
+     */
+    patch(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
+      _handlers['PATCH'] = handler;
+      _middleware['PATCH'] = handlerOptions?.middleware || [];
+      return api;
+    },
+    /**
+     * Add a OPTIONS route handler (typically to handle CORS preflight requests)
+     */
+    options(handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
+      _handlers['OPTIONS'] = handler;
+      _middleware['OPTIONS'] = handlerOptions?.middleware || [];
       return api;
     },
     /**
      * Add middleware specific to this route
      */
-    middleware(middleware: Array<MiddlewareHandler>) {
-      _middleware = middleware;
+    middleware(middleware: Array<HS.MiddlewareFunction>) {
+      _middleware['*'] = middleware;
       return api;
     },
-    _getRouteHandlers() {
-      return [
-        ..._middleware,
-        async (context: THSContext) => {
-          const method = context.req.method.toUpperCase();
-
-          // Handle CORS preflight requests
-          if (method === 'OPTIONS') {
-            return context.html(
-              render(html`
+
+    /**
+     * Fetch - handle a direct HTTP request
+     */
+    async fetch(request: Request) {
+      const context = createContext(request, api);
+      const globalMiddleware = _middleware['*'] || [];
+      const methodMiddleware = _middleware[context.req.method] || [];
+
+      const methodHandler = async (context: HS.Context) => {
+        const method = context.req.method;
+
+        // Handle CORS preflight requests (if no OPTIONS handler is defined)
+        if (method === 'OPTIONS' && !_handlers['OPTIONS']) {
+          return context.res.html(
+            render(html`
                 <!DOCTYPE html>
                 <html lang="en"></html>
               `),
-              {
-                status: 200,
-                headers: {
-                  'Access-Control-Allow-Origin': '*',
-                  'Access-Control-Allow-Methods': [
-                    'HEAD',
-                    'OPTIONS',
-                    ...Object.keys(_handlers),
-                  ].join(', '),
-                  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
-                },
-              }
-            );
-          }
-
-          // Handle other requests, HEAD is GET with no body
-          return returnHTMLResponse(context, () => {
-            const handler = method === 'HEAD' ? _handlers['GET'] : _handlers[method];
-
-            if (!handler) {
-              throw new HTTPException(405, { message: 'Method not allowed' });
+            {
+              status: 200,
+              headers: {
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Methods': [
+                  'HEAD',
+                  'OPTIONS',
+                  ...Object.keys(_handlers),
+                ].join(', '),
+                'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+              },
             }
+          );
+        }
+
+        const handler = method === 'HEAD' ? _handlers['GET'] : _handlers[method];
 
-            return handler(context);
-          });
-        },
-      ];
+        if (!handler) {
+          return context.res.error(new Error('Method not allowed'), { status: 405 });
+        }
+
+        // @TODO: Handle errors from route handler
+        const routeContent = await handler(context);
+
+        // Return Response if returned from route handler
+        if (routeContent instanceof Response) {
+          return routeContent;
+        }
+
+        if (isHTMLContent(routeContent)) {
+          return returnHTMLResponse(context, () => routeContent);
+        }
+
+        return routeContent;
+      };
+
+      return executeMiddleware(context, [...globalMiddleware, ...methodMiddleware, methodHandler]);
     },
   };
 
@@ -131,129 +202,84 @@ export function createRoute(handler?: THSRouteHandler): THSRoute {
 }
 
 /**
- * Create new API Route
- * API Route handlers should return a JSON object or a Response
+ * Creates a server object that can compose routes and middleware
  */
-export function createAPIRoute(handler?: THSAPIRouteHandler): THSAPIRoute {
-  let _handlers: Record<string, THSAPIRouteHandler> = {};
-  let _middleware: Array<MiddlewareHandler> = [];
+export async function createServer(config: HS.Config = {} as HS.Config): Promise<HS.Server> {
+  const _middleware: HS.MiddlewareFunction[] = [];
+  const _routes: HS.Route[] = [];
 
-  if (handler) {
-    _handlers['GET'] = handler;
+  // Load plugins, if any
+  if (config.plugins && config.plugins.length > 0) {
+    await Promise.all(config.plugins.map(plugin => plugin(config)));
   }
 
-  const api: THSAPIRoute = {
-    _kind: 'hsAPIRoute',
-    get(handler: THSAPIRouteHandler) {
-      _handlers['GET'] = handler;
-      return api;
+  const api: HS.Server = {
+    _config: config,
+    _routes: _routes,
+    _middleware: _middleware,
+    use(middleware: HS.MiddlewareFunction) {
+      _middleware.push(middleware);
+      return this;
     },
-    post(handler: THSAPIRouteHandler) {
-      _handlers['POST'] = handler;
-      return api;
+    get(path: string, handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
+      const route = createRoute().get(handler, handlerOptions);
+      route._config.path = path;
+      _routes.push(route);
+      return route;
     },
-    put(handler: THSAPIRouteHandler) {
-      _handlers['PUT'] = handler;
-      return api;
+    post(path: string, handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
+      const route = createRoute().post(handler, handlerOptions);
+      route._config.path = path;
+      _routes.push(route);
+      return route;
     },
-    delete(handler: THSAPIRouteHandler) {
-      _handlers['DELETE'] = handler;
-      return api;
+    put(path: string, handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
+      const route = createRoute().put(handler, handlerOptions);
+      route._config.path = path;
+      _routes.push(route);
+      return route;
     },
-    patch(handler: THSAPIRouteHandler) {
-      _handlers['PATCH'] = handler;
-      return api;
+    delete(path: string, handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
+      const route = createRoute().delete(handler, handlerOptions);
+      route._config.path = path;
+      _routes.push(route);
+      return route;
     },
-    middleware(middleware: Array<MiddlewareHandler>) {
-      _middleware = middleware;
-      return api;
+    patch(path: string, handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
+      const route = createRoute().patch(handler, handlerOptions);
+      route._config.path = path;
+      _routes.push(route);
+      return route;
     },
-    _getRouteHandlers() {
-      return [
-        ..._middleware,
-        async (context: THSContext) => {
-          const method = context.req.method.toUpperCase();
-
-          // Handle CORS preflight requests
-          if (method === 'OPTIONS') {
-            return context.json(
-              {
-                meta: { success: true, dtResponse: new Date() },
-                data: {},
-              },
-              {
-                status: 200,
-                headers: {
-                  'Access-Control-Allow-Origin': '*',
-                  'Access-Control-Allow-Methods': [
-                    'HEAD',
-                    'OPTIONS',
-                    ...Object.keys(_handlers),
-                  ].join(', '),
-                  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
-                },
-              }
-            );
-          }
-
-          // Handle other requests, HEAD is GET with no body
-          const handler = method === 'HEAD' ? _handlers['GET'] : _handlers[method];
-
-          if (!handler) {
-            return context.json(
-              {
-                meta: { success: false, dtResponse: new Date() },
-                data: {},
-                error: {
-                  message: 'Method not allowed',
-                },
-              },
-              { status: 405 }
-            );
-          }
-
-          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 }
-            );
-          }
-        },
-      ];
+    options(path: string, handler: HS.RouteHandler, handlerOptions?: HS.RouteHandlerOptions) {
+      const route = createRoute().options(handler, handlerOptions);
+      route._config.path = path;
+      _routes.push(route);
+      return route;
     },
   };
 
   return api;
 }
 
+/**
+ * Checks if a response is HTML content
+ */
+function isHTMLContent(response: unknown): response is Response {
+  const hasHTMLContentType = response instanceof Response && response.headers.get('Content-Type') === 'text/html';
+  const isHTMLTemplate = isHSHtml(response);
+  const isHTMLString = typeof response === 'string' && response.trim().startsWith('<');
+
+  return hasHTMLContentType || isHTMLTemplate || isHTMLString;
+}
+
 /**
  * Return HTML response from userland route handler
  */
 export async function returnHTMLResponse(
-  context: THSContext,
+  context: HS.Context,
   handlerFn: () => unknown,
-  responseOptions?: { status?: ContentfulStatusCode; headers?: Headers | Record<string, string> }
+  responseOptions?: { status?: number; headers?: Record<string, string> }
 ): Promise<Response> {
   try {
     const routeContent = await handlerFn();
@@ -263,13 +289,12 @@ export async function returnHTMLResponse(
       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)) {
+      // @TODO: Move this to config or something...
+      const streamOpt = context.req.query.get('__nostream');
+      const streamingEnabled = (streamOpt !== undefined ? streamOpt : true);
+
       // Stream only if enabled and there is async content to stream
       if (streamingEnabled && (routeContent as HSHtml).asyncContent?.length > 0) {
         return new StreamResponse(
@@ -278,12 +303,12 @@ export async function returnHTMLResponse(
         ) as Response;
       } else {
         const output = await renderAsync(routeContent as HSHtml);
-        return context.html(output, responseOptions);
+        return context.res.html(output, responseOptions);
       }
     }
 
     // Return unknown content as string - not specifically handled above
-    return context.html(String(routeContent), responseOptions);
+    return context.res.html(String(routeContent), responseOptions);
   } catch (e) {
     !IS_PROD && console.error(e);
     return await showErrorReponse(context, e as Error, responseOptions);
@@ -294,23 +319,23 @@ export async function returnHTMLResponse(
  * Get a Hyperspan runnable route from a module import
  * @throws Error if no runnable route found
  */
-export function getRunnableRoute(route: unknown): THSRoute {
+export function getRunnableRoute(route: unknown, routeConfig?: HS.RouteConfig): HS.Route {
   // Runnable already? Just return it
   if (isRunnableRoute(route)) {
-    return route as THSRoute;
+    return route as HS.Route;
   }
 
   const kind = typeof route;
 
   // Plain function - wrap in createRoute()
   if (kind === 'function') {
-    return createRoute(route as THSRouteHandler);
+    return createRoute(routeConfig).get(route as HS.RouteHandler);
   }
 
   // Module - get default and use it
   // @ts-ignore
   if (kind === 'object' && 'default' in route) {
-    return getRunnableRoute(route.default);
+    return getRunnableRoute(route.default, routeConfig);
   }
 
   // No route -> error
@@ -327,10 +352,18 @@ export function isRunnableRoute(route: unknown): boolean {
     return false;
   }
 
-  const obj = route as { _kind: string; _getRouteHandlers: any };
-  const runnableKind = ['hsRoute', 'hsAPIRoute', 'hsAction'].includes(obj?._kind);
+  const obj = route as { _kind: string; fetch: (request: Request) => Promise<Response> };
+  return 'hsRoute' === obj?._kind && 'fetch' in obj;
+}
 
-  return runnableKind && '_getRouteHandlers' in obj;
+/**
+ * Is valid route path to add to server?
+ */
+export function isValidRoutePath(path: string): boolean {
+  const isHiddenRoute = path.includes('/__');
+  const isTestFile = path.includes('.test') || path.includes('.spec');
+
+  return !isHiddenRoute && !isTestFile;
 }
 
 /**
@@ -338,22 +371,22 @@ export function isRunnableRoute(route: unknown): boolean {
  * @TODO: Should check for and load user-customizeable template with special name (app/__error.ts ?)
  */
 async function showErrorReponse(
-  context: THSContext,
+  context: HS.Context,
   err: Error,
-  responseOptions?: { status?: ContentfulStatusCode; headers?: Headers | Record<string, string> }
+  responseOptions?: { status?: number; headers?: Record<string, string> }
 ) {
-  let status: ContentfulStatusCode = 500;
+  let status: number = 500;
   const message = err.message || 'Internal Server Error';
 
   // Send correct status code if HTTPException
   if (err instanceof HTTPException) {
-    status = err.status as ContentfulStatusCode;
+    status = err.status;
   }
 
   const stack = !IS_PROD && err.stack ? err.stack.split('\n').slice(1).join('\n') : '';
 
   // Partial request (no layout - usually from actions)
-  if (context.req.header('X-Request-Type') === 'partial') {
+  if (context.req.headers.get('X-Request-Type') === 'partial') {
     const output = render(html`
       <section style="padding: 20px;">
         <p style="margin-bottom: 10px;"><strong>Error</strong></p>
@@ -361,7 +394,7 @@ async function showErrorReponse(
         ${stack ? html`<pre>${stack}</pre>` : ''}
       </section>
     `);
-    return context.html(output, Object.assign({ status }, responseOptions));
+    return context.res.html(output, Object.assign({ status }, responseOptions));
   }
 
   const output = render(html`
@@ -382,233 +415,28 @@ async function showErrorReponse(
     </html>
   `);
 
-  return context.html(output, Object.assign({ status }, responseOptions));
-}
-
-export type THSServerConfig = {
-  appDir: string;
-  staticFileRoot: string;
-  rewrites?: Array<{ source: string; destination: string }>;
-  islandPlugins?: Array<any>; // Loaders for client islands
-  // For customizing the routes and adding your own...
-  beforeRoutesAdded?: (app: Hono) => void;
-  afterRoutesAdded?: (app: Hono) => void;
-};
-
-export type THSRouteMap = {
-  file: string;
-  route: string;
-  params: string[];
-  module?: any;
-};
-
-/**
- * Build routes
- */
-const ROUTE_SEGMENT = /(\[[a-zA-Z_\.]+\])/g;
-export async function buildRoutes(config: THSServerConfig): Promise<THSRouteMap[]> {
-  // Walk all pages and add them as routes
-  const routesDir = join(config.appDir, 'routes');
-  const files = await readdir(routesDir, { recursive: true });
-  const routes: THSRouteMap[] = [];
-
-  for (const file of files) {
-    // No directories or test files
-    if (
-      !file.includes('.') ||
-      basename(file).startsWith('.') ||
-      file.includes('.test.') ||
-      file.includes('.spec.')
-    ) {
-      continue;
-    }
-
-    let route = '/' + file.replace(extname(file), '');
-
-    // Index files
-    if (route.endsWith('index')) {
-      route = route === 'index' ? '/' : route.substring(0, route.length - 6);
-    }
-
-    // Dynamic params
-    let params: string[] = [];
-    const dynamicPaths = ROUTE_SEGMENT.test(route);
-
-    if (dynamicPaths) {
-      params = [];
-      route = route.replace(ROUTE_SEGMENT, (match: string) => {
-        const paramName = match.replace(/[^a-zA-Z_\.]+/g, '');
-
-        if (match.includes('...')) {
-          params.push(paramName.replace('...', ''));
-          return '*';
-        } else {
-          params.push(paramName);
-          return ':' + paramName;
-        }
-      });
-    }
-
-    routes.push({
-      file: join('./', routesDir, file),
-      route: normalizePath(route || '/'),
-      params,
-    });
-  }
-
-  // Import all routes at once
-  return await Promise.all(
-    routes.map(async (route) => {
-      route.module = (await import(join(CWD, route.file))).default;
-
-      return route;
-    })
-  );
-}
-
-/**
- * Build Hyperspan Actions
- */
-export async function buildActions(config: THSServerConfig): Promise<THSRouteMap[]> {
-  // Walk all pages and add them as routes
-  const routesDir = join(config.appDir, 'actions');
-  const files = await readdir(routesDir, { recursive: true });
-  const routes: THSRouteMap[] = [];
-
-  for (const file of files) {
-    // No directories or test files
-    if (
-      !file.includes('.') ||
-      basename(file).startsWith('.') ||
-      file.includes('.test.') ||
-      file.includes('.spec.')
-    ) {
-      continue;
-    }
-
-    let route = assetHash('/' + file.replace(extname(file), ''));
-
-    routes.push({
-      file: join('./', routesDir, file),
-      route: `/__actions/${route}`,
-      params: [],
-    });
-  }
-
-  // Import all routes at once
-  return await Promise.all(
-    routes.map(async (route) => {
-      route.module = (await import(join(CWD, route.file))).default;
-      route.route = route.module._route;
-
-      return route;
-    })
-  );
-}
-
-/**
- * Run route from file
- */
-export function createRouteFromModule(
-  RouteModule: any
-): Array<MiddlewareHandler | ((context: THSContext) => HandlerResponse<any>)> {
-  const route = getRunnableRoute(RouteModule);
-  return route._getRouteHandlers();
+  return context.res.html(output, Object.assign({ status }, responseOptions));
 }
 
-/**
- * Create and start Bun HTTP server
- */
-export async function createServer(config: THSServerConfig): Promise<Hono> {
-  // Build client JS and CSS bundles so they are available for templates when streaming starts
-  await Promise.all([buildClientJS(), buildClientCSS(), clientJSPlugin(config)]);
-
-  const app = new Hono();
-
-  app.use(csrf());
-
-  // [Customization] Before routes added...
-  config.beforeRoutesAdded && config.beforeRoutesAdded(app);
-
-  const [routes, actions] = await Promise.all([buildRoutes(config), buildActions(config)]);
-
-  // Scan routes folder and add all file routes to the router
-  const fileRoutes = routes.concat(actions);
-  const routeMap = [];
-
-  for (let i = 0; i < fileRoutes.length; i++) {
-    let route = fileRoutes[i];
-
-    routeMap.push({ route: route.route, file: route.file });
-
-    // Ensure route module was imported and exists (it should...)
-    if (!route.module) {
-      throw new Error(`Route module not loaded! File: ${route.file}`);
-    }
-
-    const routeHandlers = createRouteFromModule(route.module);
-    app.all(route.route, ...routeHandlers);
-  }
-
-  // Help route if no routes found
-  if (routeMap.length === 0) {
-    app.get('/', (context) => {
-      return context.text(
-        'No routes found. Add routes to app/routes. Example: `app/routes/index.ts`',
-        { status: 404 }
-      );
-    });
-  }
-
-  // Display routing table for dev env
-  if (!IS_PROD) {
-    console.log('[Hyperspan] File system routes (in app/routes):');
-    console.table(routeMap);
-  }
-
-  // [Customization] After routes added...
-  config.afterRoutesAdded && config.afterRoutesAdded(app);
-
-  // Static files and catchall
-  app.use(
-    '*',
-    serveStatic({
-      root: config.staticFileRoot,
-      onFound: IS_PROD
-        ? (_, c) => {
-            // Cache static assets in prod (default 30 days)
-            c.header('Cache-Control', 'public, max-age=2592000');
-          }
-        : undefined,
-    })
-  );
-
-  app.notFound((context) => {
-    // @TODO: Add a custom 404 route
-    return context.text('Not... found?', { status: 404 });
-  });
-
-  return app;
-}
 
 /**
  * Streaming HTML Response
  */
 export class StreamResponse extends Response {
-  constructor(iterator: AsyncIterator<unknown>, options = {}) {
+  constructor(iterator: AsyncIterator<unknown>, options: { status?: number; headers?: Record<string, string> } = {}) {
     super();
+    const { status, headers, ...restOptions } = options;
     const stream = createReadableStreamFromAsyncGenerator(iterator as AsyncGenerator);
 
     return new Response(stream, {
-      status: 200,
+      status: status ?? 200,
       headers: {
         'Transfer-Encoding': 'chunked',
         'Content-Type': 'text/html; charset=UTF-8',
         'Content-Encoding': 'Identity',
-        // @ts-ignore
-        ...(options?.headers ?? {}),
+        ...(headers ?? {}),
       },
-      ...options,
+      ...restOptions,
     });
   }
 }
@@ -638,9 +466,48 @@ export function createReadableStreamFromAsyncGenerator(output: AsyncGenerator) {
  * Normalize URL path
  * Removes trailing slash and lowercases path
  */
-export function normalizePath(urlPath: string): string {
-  return (
-    (urlPath.endsWith('/') ? urlPath.substring(0, urlPath.length - 1) : urlPath).toLowerCase() ||
-    '/'
-  );
+const ROUTE_SEGMENT_REGEX = /(\[[a-zA-Z_\.]+\])/g;
+export function parsePath(urlPath: string): { path: string, params: string[] } {
+  const params: string[] = [];
+  urlPath = urlPath.replace('index', '').replace('.ts', '').replace('.js', '');
+
+  if (urlPath.startsWith('/')) {
+    urlPath = urlPath.substring(1);
+  }
+
+  if (urlPath.endsWith('/')) {
+    urlPath = urlPath.substring(0, urlPath.length - 1);
+  }
+
+  if (!urlPath) {
+    return { path: '/', params: [] };
+  }
+
+  // Dynamic params
+  if (ROUTE_SEGMENT_REGEX.test(urlPath)) {
+    urlPath = urlPath.replace(ROUTE_SEGMENT_REGEX, (match: string) => {
+      const paramName = match.replace(/[^a-zA-Z_\.]+/g, '');
+      params.push(paramName);
+
+      if (match.includes('...')) {
+        return '*';
+      } else {
+        return ':' + paramName;
+      }
+    });
+  }
+
+  // Only lowercase non-param segments (do not lowercase after ':')
+  return {
+    path: (
+      '/' +
+      urlPath
+        .split('/')
+        .map((segment) =>
+          segment.startsWith(':') || segment === '*' ? segment : segment.toLowerCase()
+        )
+        .join('/')
+    ),
+    params,
+  };
 }