@hyperspan/framework 0.3.2 → 0.3.4

package/build.ts

@@ -1,6 +1,6 @@
 import { build } from 'bun';
 
-const entrypoints = ['./src/server.ts', './src/assets.ts'];
+const entrypoints = ['./src/server.ts', './src/assets.ts', './src/middleware.ts'];
 const external = ['@hyperspan/html'];
 const outdir = './dist';
 const target = 'node';

package/dist/assets.js

@@ -1,3 +1,5 @@
+import"./chunk-atw8cdg1.js";
+
 // src/assets.ts
 import { html } from "@hyperspan/html";
 import { createHash } from "node:crypto";

package/dist/chunk-atw8cdg1.js

@@ -0,0 +1,19 @@
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+
+export { __toESM, __commonJS };

package/dist/middleware.js

@@ -0,0 +1,178 @@
+import {
+  __commonJS,
+  __toESM
+} from "./chunk-atw8cdg1.js";
+
+// ../../node_modules/timestring/index.js
+var require_timestring = __commonJS((exports, module) => {
+  module.exports = parseTimestring;
+  var DEFAULT_OPTS = {
+    hoursPerDay: 24,
+    daysPerWeek: 7,
+    weeksPerMonth: 4,
+    monthsPerYear: 12,
+    daysPerYear: 365.25
+  };
+  var UNIT_MAP = {
+    ms: ["ms", "milli", "millisecond", "milliseconds"],
+    s: ["s", "sec", "secs", "second", "seconds"],
+    m: ["m", "min", "mins", "minute", "minutes"],
+    h: ["h", "hr", "hrs", "hour", "hours"],
+    d: ["d", "day", "days"],
+    w: ["w", "week", "weeks"],
+    mth: ["mon", "mth", "mths", "month", "months"],
+    y: ["y", "yr", "yrs", "year", "years"]
+  };
+  function parseTimestring(value, returnUnit, opts) {
+    opts = Object.assign({}, DEFAULT_OPTS, opts || {});
+    if (typeof value === "number" || value.match(/^[-+]?[0-9.]+$/g)) {
+      value = parseInt(value) + "ms";
+    }
+    let totalSeconds = 0;
+    const unitValues = getUnitValues(opts);
+    const groups = value.toLowerCase().replace(/[^.\w+-]+/g, "").match(/[-+]?[0-9.]+[a-z]+/g);
+    if (groups === null) {
+      throw new Error(`The value [${value}] could not be parsed by timestring`);
+    }
+    groups.forEach((group) => {
+      const value2 = group.match(/[0-9.]+/g)[0];
+      const unit = group.match(/[a-z]+/g)[0];
+      totalSeconds += getSeconds(value2, unit, unitValues);
+    });
+    if (returnUnit) {
+      return convert(totalSeconds, returnUnit, unitValues);
+    }
+    return totalSeconds;
+  }
+  function getUnitValues(opts) {
+    const unitValues = {
+      ms: 0.001,
+      s: 1,
+      m: 60,
+      h: 3600
+    };
+    unitValues.d = opts.hoursPerDay * unitValues.h;
+    unitValues.w = opts.daysPerWeek * unitValues.d;
+    unitValues.mth = opts.daysPerYear / opts.monthsPerYear * unitValues.d;
+    unitValues.y = opts.daysPerYear * unitValues.d;
+    return unitValues;
+  }
+  function getUnitKey(unit) {
+    for (const key of Object.keys(UNIT_MAP)) {
+      if (UNIT_MAP[key].indexOf(unit) > -1) {
+        return key;
+      }
+    }
+    throw new Error(`The unit [${unit}] is not supported by timestring`);
+  }
+  function getSeconds(value, unit, unitValues) {
+    return value * unitValues[getUnitKey(unit)];
+  }
+  function convert(value, unit, unitValues) {
+    return value / unitValues[getUnitKey(unit)];
+  }
+});
+
+// ../../node_modules/hono/dist/middleware/etag/digest.js
+var mergeBuffers = (buffer1, buffer2) => {
+  if (!buffer1) {
+    return buffer2;
+  }
+  const merged = new Uint8Array(buffer1.byteLength + buffer2.byteLength);
+  merged.set(new Uint8Array(buffer1), 0);
+  merged.set(buffer2, buffer1.byteLength);
+  return merged;
+};
+var generateDigest = async (stream, generator) => {
+  if (!stream) {
+    return null;
+  }
+  let result = undefined;
+  const reader = stream.getReader();
+  for (;; ) {
+    const { value, done } = await reader.read();
+    if (done) {
+      break;
+    }
+    result = await generator(mergeBuffers(result, value));
+  }
+  if (!result) {
+    return null;
+  }
+  return Array.prototype.map.call(new Uint8Array(result), (x) => x.toString(16).padStart(2, "0")).join("");
+};
+
+// ../../node_modules/hono/dist/middleware/etag/index.js
+var RETAINED_304_HEADERS = [
+  "cache-control",
+  "content-location",
+  "date",
+  "etag",
+  "expires",
+  "vary"
+];
+function etagMatches(etag2, ifNoneMatch) {
+  return ifNoneMatch != null && ifNoneMatch.split(/,\s*/).indexOf(etag2) > -1;
+}
+function initializeGenerator(generator) {
+  if (!generator) {
+    if (crypto && crypto.subtle) {
+      generator = (body) => crypto.subtle.digest({
+        name: "SHA-1"
+      }, body);
+    }
+  }
+  return generator;
+}
+var etag = (options) => {
+  const retainedHeaders = options?.retainedHeaders ?? RETAINED_304_HEADERS;
+  const weak = options?.weak ?? false;
+  const generator = initializeGenerator(options?.generateDigest);
+  return async function etag2(c, next) {
+    const ifNoneMatch = c.req.header("If-None-Match") ?? null;
+    await next();
+    const res = c.res;
+    let etag3 = res.headers.get("ETag");
+    if (!etag3) {
+      if (!generator) {
+        return;
+      }
+      const hash = await generateDigest(res.clone().body, generator);
+      if (hash === null) {
+        return;
+      }
+      etag3 = weak ? `W/"${hash}"` : `"${hash}"`;
+    }
+    if (etagMatches(etag3, ifNoneMatch)) {
+      c.res = new Response(null, {
+        status: 304,
+        statusText: "Not Modified",
+        headers: {
+          ETag: etag3
+        }
+      });
+      c.res.headers.forEach((_, key) => {
+        if (retainedHeaders.indexOf(key.toLowerCase()) === -1) {
+          c.res.headers.delete(key);
+        }
+      });
+    } else {
+      c.res.headers.set("ETag", etag3);
+    }
+  };
+};
+
+// src/middleware.ts
+var import_timestring = __toESM(require_timestring(), 1);
+function cacheTime(timeStrOrSeconds) {
+  return (c, next) => etag()(c, () => {
+    if (c.req.method.toUpperCase() === "GET") {
+      const timeInSeconds = typeof timeStrOrSeconds === "number" ? timeStrOrSeconds : import_timestring.default(timeStrOrSeconds);
+      c.header("Cache-Control", `public, max-age=${timeInSeconds}`);
+    }
+    return next();
+  });
+}
+export {
+  cacheTime
+};

package/dist/server.js

@@ -1,7 +1,9 @@
 import {
+  assetHash,
   buildClientCSS,
   buildClientJS
 } from "./assets.js";
+import"./chunk-atw8cdg1.js";
 
 // src/server.ts
 import { readdir } from "node:fs/promises";
@@ -1856,34 +1858,13 @@ function createRoute(handler) {
         ..._middleware,
         async (context) => {
           const method = context.req.method.toUpperCase();
-          try {
+          return returnHTMLResponse(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);
-            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 handler2(context);
+          });
         }
       ];
     }
@@ -1962,6 +1943,29 @@ function createAPIRoute(handler) {
   };
   return api;
 }
+async function returnHTMLResponse(context, handlerFn, responseOptions) {
+  try {
+    const routeContent = await handlerFn();
+    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 && routeContent.asyncContent?.length > 0) {
+        return new StreamResponse(renderStream(routeContent), responseOptions);
+      } else {
+        const output = await renderAsync(routeContent);
+        return context.html(output, responseOptions);
+      }
+    }
+    return context.html(String(routeContent), responseOptions);
+  } catch (e) {
+    !IS_PROD && console.error(e);
+    return await showErrorReponse(context, e, responseOptions);
+  }
+}
 function getRunnableRoute(route) {
   if (isRunnableRoute(route)) {
     return route;
@@ -1983,7 +1987,7 @@ function isRunnableRoute(route) {
   const runnableKind = ["hsRoute", "hsAPIRoute", "hsAction"].includes(obj?._kind);
   return runnableKind && "_getRouteHandlers" in obj;
 }
-async function showErrorReponse(context, err) {
+async function showErrorReponse(context, err, responseOptions) {
   let status = 500;
   const message = err.message || "Internal Server Error";
   if (err instanceof HTTPException) {
@@ -1992,6 +1996,16 @@ async function showErrorReponse(context, err) {
   const stack = !IS_PROD && err.stack ? err.stack.split(`
 `).slice(1).join(`
 `) : "";
+  if (context.req.header("X-Request-Type") === "partial") {
+    const output2 = render(html`
+      <section style="padding: 20px;">
+        <p style="margin-bottom: 10px;"><strong>Error</strong></p>
+        <strong>${message}</strong>
+        ${stack ? html`<pre>${stack}</pre>` : ""}
+      </section>
+    `);
+    return context.html(output2, Object.assign({ status }, responseOptions));
+  }
   const output = render(html`
     <!DOCTYPE html>
     <html lang="en">
@@ -2009,7 +2023,7 @@ async function showErrorReponse(context, err) {
       </body>
     </html>
   `);
-  return context.html(output, { status });
+  return context.html(output, Object.assign({ status }, responseOptions));
 }
 var ROUTE_SEGMENT = /(\[[a-zA-Z_\.]+\])/g;
 async function buildRoutes(config) {
@@ -2041,11 +2055,35 @@ async function buildRoutes(config) {
     }
     routes.push({
       file: join("./", routesDir, file),
-      route: route || "/",
+      route: normalizePath(route || "/"),
       params
     });
   }
-  return routes;
+  return await Promise.all(routes.map(async (route) => {
+    route.module = (await import(join(CWD, route.file))).default;
+    return route;
+  }));
+}
+async function buildActions(config) {
+  const routesDir = join(config.appDir, "actions");
+  const files = await readdir(routesDir, { recursive: true });
+  const routes = [];
+  for (const file of files) {
+    if (!file.includes(".") || basename(file).startsWith(".")) {
+      continue;
+    }
+    let route = assetHash("/" + file.replace(extname(file), ""));
+    routes.push({
+      file: join("./", routesDir, file),
+      route: `/__actions/${route}`,
+      params: []
+    });
+  }
+  return await Promise.all(routes.map(async (route) => {
+    route.module = (await import(join(CWD, route.file))).default;
+    route.route = route.module._route;
+    return route;
+  }));
 }
 function createRouteFromModule(RouteModule) {
   const route = getRunnableRoute(RouteModule);
@@ -2055,15 +2093,17 @@ async function createServer(config) {
   await Promise.all([buildClientJS(), buildClientCSS()]);
   const app = new Hono2;
   config.beforeRoutesAdded && config.beforeRoutesAdded(app);
-  const fileRoutes = await buildRoutes(config);
+  const [routes, actions] = await Promise.all([buildRoutes(config), buildActions(config)]);
+  const fileRoutes = routes.concat(actions);
   const routeMap = [];
   for (let i = 0;i < fileRoutes.length; i++) {
     let route = fileRoutes[i];
-    const fullRouteFile = join(CWD, route.file);
-    const routePattern = normalizePath(route.route);
-    routeMap.push({ route: routePattern, file: route.file });
-    const routeHandlers = createRouteFromModule(await import(fullRouteFile));
-    app.all(routePattern, ...routeHandlers);
+    routeMap.push({ route: route.route, file: route.file });
+    if (!route.module) {
+      throw new Error(`Route module not loaded! File: ${route.file}`);
+    }
+    const routeHandlers = createRouteFromModule(route.module);
+    app.all(route.route, ...routeHandlers);
   }
   if (routeMap.length === 0) {
     app.get("/", (context) => {
@@ -2122,6 +2162,7 @@ function normalizePath(urlPath) {
   return (urlPath.endsWith("/") ? urlPath.substring(0, urlPath.length - 1) : urlPath).toLowerCase() || "/";
 }
 export {
+  returnHTMLResponse,
   normalizePath,
   isRunnableRoute,
   getRunnableRoute,
@@ -2132,6 +2173,7 @@ export {
   createConfig,
   createAPIRoute,
   buildRoutes,
+  buildActions,
   StreamResponse,
   IS_PROD
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Hyperspan Web Framework",
   "main": "dist/server.ts",
   "types": "src/server.ts",
@@ -17,13 +17,17 @@
       "types": "./src/server.ts",
       "default": "./dist/server.js"
     },
-    "./actions": {
-      "types": "./src/actions.ts",
-      "default": "./src/actions.ts"
-    },
     "./assets": {
       "types": "./src/assets.ts",
       "default": "./dist/assets.js"
+    },
+    "./middleware": {
+      "types": "./src/middleware.ts",
+      "default": "./dist/middleware.js"
+    },
+    "./unstable/actions": {
+      "types": "./src/actions.ts",
+      "default": "./src/actions.ts"
     }
   },
   "author": "Vance Lucas <vance@vancelucas.com>",
@@ -56,6 +60,7 @@
     "@types/bun": "^1.2.14",
     "@types/node": "^22.15.20",
     "@types/react": "^19.1.5",
+    "@types/timestring": "^7.0.0",
     "prettier": "^3.5.3",
     "typescript": "^5.8.3"
   },
@@ -63,6 +68,7 @@
     "@hyperspan/html": "^0.1.7",
     "hono": "^4.7.10",
     "isbot": "^5.1.28",
-    "zod": "^3.25.42"
+    "timestring": "^7.0.0",
+    "zod": "^3.25.67"
   }
 }

package/src/actions.test.ts

@@ -1,5 +1,5 @@
-import z from 'zod/v4';
-import { createAction } from './actions';
+import { z } from 'zod';
+import { unstable__createAction } from './actions';
 import { describe, it, expect } from 'bun:test';
 import { html, render, type HSHtml } from '@hyperspan/html';
 import type { Context } from 'hono';
@@ -22,7 +22,7 @@ describe('createAction', () => {
       const schema = z.object({
         name: z.string(),
       });
-      const action = createAction(schema, formWithNameOnly);
+      const action = unstable__createAction(schema, formWithNameOnly);
 
       const formResponse = render(action.render({ data: { name: 'John' } }) as HSHtml);
       expect(formResponse).toContain('value="John"');
@@ -34,7 +34,7 @@ describe('createAction', () => {
       const schema = z.object({
         name: z.string().nonempty(),
       });
-      const action = createAction(schema, formWithNameOnly)
+      const action = unstable__createAction(schema, formWithNameOnly)
         .post((c, { data }) => {
           return html`<div>Thanks for submitting the form, ${data?.name}!</div>`;
         })
@@ -45,6 +45,7 @@ describe('createAction', () => {
       // Mock context to run action
       const mockContext = {
         req: {
+          method: 'POST',
           formData: async () => {
             const formData = new FormData();
             formData.append('name', 'John');
@@ -53,7 +54,7 @@ describe('createAction', () => {
         },
       } as Context;
 
-      const response = await action.run('POST', mockContext);
+      const response = await action.run(mockContext);
 
       const formResponse = render(response as HSHtml);
       expect(formResponse).toContain('Thanks for submitting the form, John!');
@@ -65,7 +66,7 @@ describe('createAction', () => {
       const schema = z.object({
         name: z.string().nonempty(),
       });
-      const action = createAction(schema)
+      const action = unstable__createAction(schema)
         .form(formWithNameOnly)
         .post((c, { data }) => {
           return html`<div>Thanks for submitting the form, ${data?.name}!</div>`;
@@ -77,6 +78,7 @@ describe('createAction', () => {
       // Mock context to run action
       const mockContext = {
         req: {
+          method: 'POST',
           formData: async () => {
             const formData = new FormData();
             formData.append('name', ''); // No name = error
@@ -85,7 +87,7 @@ describe('createAction', () => {
         },
       } as Context;
 
-      const response = await action.run('POST', mockContext);
+      const response = await action.run(mockContext);
 
       const formResponse = render(response as HSHtml);
       expect(formResponse).toContain('There was an error!');

package/src/actions.ts

@@ -2,51 +2,80 @@ import { html, HSHtml } from '@hyperspan/html';
 import * as z from 'zod/v4';
 import { HTTPException } from 'hono/http-exception';
 
-import type { THSResponseTypes } from './server';
-import type { Context } from 'hono';
+import { IS_PROD, returnHTMLResponse, type THSResponseTypes } from './server';
+import type { Context, MiddlewareHandler } from 'hono';
+import type { HandlerResponse, Next, TypedResponse } from 'hono/types';
+import { assetHash } from './assets';
 
 /**
  * Actions = Form + route handler
  * Automatically handles and parses form data
  *
- * INITIAL IDEA OF HOW THIS WILL WORK:
+ * HOW THIS WORKS:
  * ---
- * 1. Renders component as initial form markup for GET request
- * 2. Bind form onSubmit function to custom client JS handling
- * 3. Submits form with JavaScript fetch()
- * 4. Replaces form content with content from server
- * 5. All validation and save logic is on the server
- * 6. Handles any Exception thrown on server as error displayed in client
+ * 1. Renders in any template as initial form markup with action.render()
+ * 2. Binds form onSubmit function to custom client JS handling via <hs-action> web component
+ * 3. Submits form with JavaScript fetch() + FormData as normal POST form submission
+ * 4. All validation and save logic is run on the server
+ * 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
  */
+type TActionResponse = THSResponseTypes | HandlerResponse<any> | TypedResponse<any, any, any>;
 export interface HSAction<T extends z.ZodTypeAny> {
   _kind: string;
-  form(renderForm: ({ data }: { data?: z.infer<T> }) => HSHtml): HSAction<T>;
-  post(handler: (c: Context, { data }: { data?: z.infer<T> }) => THSResponseTypes): HSAction<T>;
+  _route: string;
+  _form: Parameters<HSAction<T>['form']>[0];
+  form(
+    renderForm: ({ data, error }: { data?: z.infer<T>; error?: z.ZodError | Error }) => HSHtml
+  ): HSAction<T>;
+  post(
+    handler: (
+      c: Context<any, any, {}>,
+      { data }: { data?: z.infer<T> }
+    ) => TActionResponse | Promise<TActionResponse>
+  ): HSAction<T>;
   error(
     handler: (
-      c: Context,
+      c: Context<any, any, {}>,
       { data, error }: { data?: z.infer<T>; error?: z.ZodError | Error }
-    ) => THSResponseTypes
+    ) => TActionResponse
   ): HSAction<T>;
-  render(props?: { data?: z.infer<T>; error?: z.ZodError | Error }): THSResponseTypes;
-  run(method: 'GET' | 'POST', c: Context): Promise<THSResponseTypes>;
+  render(props?: { data?: z.infer<T>; error?: z.ZodError | Error }): TActionResponse;
+  run(c: Context<any, any, {}>): TActionResponse | Promise<TActionResponse>;
+  middleware: (
+    middleware: Array<
+      | MiddlewareHandler
+      | ((context: Context<any, string, {}>) => TActionResponse | Promise<TActionResponse>)
+    >
+  ) => HSAction<T>;
+  _getRouteHandlers: () => Array<
+    | MiddlewareHandler
+    | ((context: Context, next: Next) => TActionResponse | Promise<TActionResponse>)
+    | ((context: Context) => TActionResponse | Promise<TActionResponse>)
+  >;
 }
 
-export function createAction<T extends z.ZodTypeAny>(
+export function unstable__createAction<T extends z.ZodTypeAny>(
   schema: T | null = null,
-  form: Parameters<HSAction<T>['form']>[0] | null = null
+  form: Parameters<HSAction<T>['form']>[0]
 ) {
   let _handler: Parameters<HSAction<T>['post']>[0] | null = null,
-    _form: Parameters<HSAction<T>['form']>[0] | null = form,
-    _errorHandler: Parameters<HSAction<T>['error']>[0] | null = null;
+    _form: Parameters<HSAction<T>['form']>[0] = form,
+    _errorHandler: Parameters<HSAction<T>['error']>[0] | null = null,
+    _middleware: Array<
+      | MiddlewareHandler
+      | ((context: Context, next: Next) => TActionResponse | Promise<TActionResponse>)
+      | ((context: Context) => TActionResponse | Promise<TActionResponse>)
+    > = [];
 
   const api: HSAction<T> = {
     _kind: 'hsAction',
+    _route: `/__actions/${assetHash(_form.toString())}`,
+    _form,
     form(renderForm) {
       _form = renderForm;
       return api;
     },
-
     /**
      * Process form data
      *
@@ -57,18 +86,44 @@ export function createAction<T extends z.ZodTypeAny>(
       _handler = handler;
       return api;
     },
-
+    /**
+     * Cusotm error handler if you want to display something other than the default
+     */
     error(handler) {
       _errorHandler = handler;
       return api;
     },
-
+    /**
+     * Add middleware specific to this route
+     */
+    middleware(middleware) {
+      _middleware = middleware;
+      return api;
+    },
     /**
      * Get form renderer method
      */
     render(formState?: { data?: z.infer<T>; error?: z.ZodError | Error }) {
       const form = _form ? _form(formState || {}) : null;
-      return form ? html`<hs-action>${form}</hs-action>` : null;
+      return form ? html`<hs-action url="${this._route}">${form}</hs-action>` : null;
+    },
+
+    _getRouteHandlers() {
+      return [
+        ..._middleware,
+        async (c: Context) => {
+          const response = await returnHTMLResponse(c, () => api.run(c));
+
+          // 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;
+        },
+      ];
     },
 
     /**
@@ -77,9 +132,11 @@ export function createAction<T extends z.ZodTypeAny>(
      * Returns result from form processing if successful
      * Re-renders form with data and error information otherwise
      */
-    async run(method: 'GET' | 'POST', c: Context) {
+    async run(c) {
+      const method = c.req.method;
+
       if (method === 'GET') {
-        return api.render();
+        return await api.render();
       }
 
       if (method !== 'POST') {
@@ -87,9 +144,9 @@ export function createAction<T extends z.ZodTypeAny>(
       }
 
       const formData = await c.req.formData();
-      const jsonData = formDataToJSON(formData);
+      const jsonData = unstable__formDataToJSON(formData);
       const schemaData = schema ? schema.safeParse(jsonData) : null;
-      const data = schemaData?.success ? (schemaData.data as z.infer<T>) : undefined;
+      const data = schemaData?.success ? (schemaData.data as z.infer<T>) : jsonData;
       let error: z.ZodError | Error | null = null;
 
       try {
@@ -101,16 +158,20 @@ export function createAction<T extends z.ZodTypeAny>(
           throw new Error('Action POST handler not set! Every action must have a POST handler.');
         }
 
-        return _handler(c, { data });
+        return await _handler(c, { data });
       } catch (e) {
         error = e as Error | z.ZodError;
+        !IS_PROD && console.error(error);
       }
 
       if (error && _errorHandler) {
-        return _errorHandler(c, { data, error });
+        // @ts-ignore
+        return await returnHTMLResponse(c, () => _errorHandler(c, { data, error }), {
+          status: 400,
+        });
       }
 
-      return api.render({ data, error });
+      return await returnHTMLResponse(c, () => api.render({ data, error }), { status: 400 });
     },
   };
 
@@ -128,7 +189,7 @@ export type THSHandlerResponse = (context: Context) => THSResponseTypes | Promis
  *
  * @link https://stackoverflow.com/a/75406413
  */
-export function formDataToJSON(formData: FormData): Record<string, string | string[]> {
+export function unstable__formDataToJSON(formData: FormData): Record<string, string | string[]> {
   let object = {};
 
   /**

package/src/clientjs/hyperspan-client.ts

@@ -1,5 +1,5 @@
 import { html } from '@hyperspan/html';
-import { Idiomorph } from './idiomorph.esm';
+import { Idiomorph } from './idiomorph';
 
 /**
  * Used for streaming content from the server to the client.
@@ -72,15 +72,22 @@ class HSAction extends HTMLElement {
     super();
   }
 
-  // Element is mounted in the DOM
   connectedCallback() {
-    const form = this.querySelector('form');
-
-    if (form) {
-      form.addEventListener('submit', (e) => {
-        formSubmitToRoute(e, form as HTMLFormElement);
-      });
-    }
+    // Have to run this code AFTER it is added to the DOM...
+    setTimeout(() => {
+      const form = this.querySelector('form');
+
+      if (form) {
+        form.setAttribute('action', this.getAttribute('url') || '');
+        const submitHandler = (e: Event) => {
+          formSubmitToRoute(e, form as HTMLFormElement, {
+            afterResponse: () => this.connectedCallback(),
+          });
+          form.removeEventListener('submit', submitHandler);
+        };
+        form.addEventListener('submit', submitHandler);
+      }
+    });
   }
 }
 window.customElements.define('hs-action', HSAction);
@@ -88,24 +95,32 @@ window.customElements.define('hs-action', HSAction);
 /**
  * Submit form data to route and replace contents with response
  */
-function formSubmitToRoute(e: Event, form: HTMLFormElement) {
+type TFormSubmitOptons = { afterResponse: () => any };
+function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOptons) {
   e.preventDefault();
 
   const formUrl = form.getAttribute('action') || '';
   const formData = new FormData(form);
   const method = form.getAttribute('method')?.toUpperCase() || 'POST';
+  const headers = {
+    Accept: 'text/html',
+    'X-Request-Type': 'partial',
+  };
 
   let response: Response;
 
-  fetch(formUrl, { body: formData, method })
-    .then((res: Response) => {
-      // @TODO: Handle redirects with some custom server thing?
-      // This... actually won't work, because fetch automatically follows all redirects (a 3xx response will never be returned to the client)
-      const isRedirect = [301, 302].includes(res.status);
+  const hsActionTag = form.closest('hs-action');
+  const submitBtn = form.querySelector('button[type=submit],input[type=submit]');
+  if (submitBtn) {
+    submitBtn.setAttribute('disabled', 'disabled');
+  }
 
-      // Is response a redirect? If so, let's follow it in the client!
-      if (isRedirect) {
-        const newUrl = res.headers.get('Location');
+  fetch(formUrl, { body: formData, method, headers })
+    .then((res: Response) => {
+      // Look for special header that indicates a redirect.
+      // fetch() automatically follows 3xx redirects, so we need to handle this manually to redirect the user to the full page
+      if (res.headers.has('X-Redirect-Location')) {
+        const newUrl = res.headers.get('X-Redirect-Location');
         if (newUrl) {
           window.location.assign(newUrl);
         }
@@ -121,7 +136,10 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement) {
         return;
       }
 
-      Idiomorph.morph(form, content);
+      const target = content.includes('<html') ? window.document.body : hsActionTag || form;
+
+      Idiomorph.morph(target, content);
+      opts.afterResponse && opts.afterResponse();
     });
 }
 

package/src/clientjs/{idiomorph.esm.js → idiomorph.ts}

@@ -1,3 +1,4 @@
+// @ts-nocheck
 /**
  * @typedef {object} ConfigHead
  *
@@ -206,9 +207,8 @@ var Idiomorph = (function () {
    */
   function saveAndRestoreFocus(ctx, fn) {
     if (!ctx.config.restoreFocus) return fn();
-    let activeElement = /** @type {HTMLInputElement|HTMLTextAreaElement|null} */ (
-      document.activeElement
-    );
+    let activeElement =
+      /** @type {HTMLInputElement|HTMLTextAreaElement|null} */ document.activeElement;
 
     // don't bother if the active element is not an input or textarea
     if (
@@ -324,7 +324,7 @@ var Idiomorph = (function () {
       if (ctx.callbacks.beforeNodeAdded(newChild) === false) return null;
       if (ctx.idMap.has(newChild)) {
         // node has children with ids with possible state so create a dummy elt of same type and apply full morph algorithm
-        const newEmptyChild = document.createElement(/** @type {Element} */ (newChild).tagName);
+        const newEmptyChild = document.createElement(/** @type {Element} */ newChild.tagName);
         oldParent.insertBefore(newEmptyChild, insertionPoint);
         morphNode(newEmptyChild, newChild, ctx);
         ctx.callbacks.afterNodeAdded(newEmptyChild);
@@ -431,8 +431,8 @@ var Idiomorph = (function () {
        */
       function isSoftMatch(oldNode, newNode) {
         // ok to cast: if one is not element, `id` and `tagName` will be undefined and we'll just compare that.
-        const oldElt = /** @type {Element} */ (oldNode);
-        const newElt = /** @type {Element} */ (newNode);
+        const oldElt = /** @type {Element} */ oldNode;
+        const newElt = /** @type {Element} */ newNode;
 
         return (
           oldElt.nodeType === newElt.nodeType &&
@@ -483,7 +483,7 @@ var Idiomorph = (function () {
       let cursor = startInclusive;
       // remove nodes until the endExclusive node
       while (cursor && cursor !== endExclusive) {
-        let tempNode = /** @type {Node} */ (cursor);
+        let tempNode = /** @type {Node} */ cursor;
         cursor = cursor.nextSibling;
         removeNode(ctx, tempNode);
       }
@@ -503,11 +503,9 @@ var Idiomorph = (function () {
     function moveBeforeById(parentNode, id, after, ctx) {
       const target =
         /** @type {Element} - will always be found */
-        (
-          (ctx.target.id === id && ctx.target) ||
-            ctx.target.querySelector(`[id="${id}"]`) ||
-            ctx.pantry.querySelector(`[id="${id}"]`)
-        );
+        (ctx.target.id === id && ctx.target) ||
+        ctx.target.querySelector(`[id="${id}"]`) ||
+        ctx.pantry.querySelector(`[id="${id}"]`);
       removeElementFromAncestorsIdMaps(target, ctx);
       moveBefore(parentNode, target, after);
       return target;
@@ -587,7 +585,7 @@ var Idiomorph = (function () {
         // ignore the head element
       } else if (oldNode instanceof HTMLHeadElement && ctx.head.style !== 'morph') {
         // ok to cast: if newContent wasn't also a <head>, it would've got caught in the `!isSoftMatch` branch above
-        handleHeadElement(oldNode, /** @type {HTMLHeadElement} */ (newContent), ctx);
+        handleHeadElement(oldNode, /** @type {HTMLHeadElement} */ newContent, ctx);
       } else {
         morphAttributes(oldNode, newContent, ctx);
         if (!ignoreValueOfActiveElement(oldNode, ctx)) {
@@ -613,8 +611,8 @@ var Idiomorph = (function () {
       // if is an element type, sync the attributes from the
       // new node into the new node
       if (type === 1 /* element type */) {
-        const oldElt = /** @type {Element} */ (oldNode);
-        const newElt = /** @type {Element} */ (newNode);
+        const oldElt = /** @type {Element} */ oldNode;
+        const newElt = /** @type {Element} */ newNode;
 
         const oldAttributes = oldElt.attributes;
         const newAttributes = newElt.attributes;
@@ -868,9 +866,9 @@ var Idiomorph = (function () {
     let promises = [];
     for (const newNode of nodesToAppend) {
       // TODO: This could theoretically be null, based on type
-      let newElt = /** @type {ChildNode} */ (
-        document.createRange().createContextualFragment(newNode.outerHTML).firstChild
-      );
+      let newElt = /** @type {ChildNode} */ document
+        .createRange()
+        .createContextualFragment(newNode.outerHTML).firstChild;
       if (ctx.callbacks.beforeNodeAdded(newElt) !== false) {
         if (('href' in newElt && newElt.href) || ('src' in newElt && newElt.src)) {
           /** @type {(result?: any) => void} */ let resolve;
@@ -1116,16 +1114,16 @@ var Idiomorph = (function () {
         return document.createElement('div'); // dummy parent element
       } else if (typeof newContent === 'string') {
         return normalizeParent(parseContent(newContent));
-      } else if (generatedByIdiomorph.has(/** @type {Element} */ (newContent))) {
+      } else if (generatedByIdiomorph.has(/** @type {Element} */ newContent)) {
         // the template tag created by idiomorph parsing can serve as a dummy parent
-        return /** @type {Element} */ (newContent);
+        return /** @type {Element} */ newContent;
       } else if (newContent instanceof Node) {
         if (newContent.parentNode) {
           // we can't use the parent directly because newContent may have siblings
           // that we don't want in the morph, and reparenting might be expensive (TODO is it?),
           // so instead we create a fake parent node that only sees a slice of its children.
           /** @type {Element} */
-          return /** @type {any} */ (new SlicedParentNode(newContent));
+          return /** @type {any} */ new SlicedParentNode(newContent);
         } else {
           // a single node is added as a child to a dummy parent
           const dummyParent = document.createElement('div');
@@ -1154,7 +1152,7 @@ var Idiomorph = (function () {
       /** @param {Node} node */
       constructor(node) {
         this.originalNode = node;
-        this.realParentNode = /** @type {Element} */ (node.parentNode);
+        this.realParentNode = /** @type {Element} */ node.parentNode;
         this.previousSibling = node.previousSibling;
         this.nextSibling = node.nextSibling;
       }
@@ -1178,16 +1176,19 @@ var Idiomorph = (function () {
        * @returns {Element[]}
        */
       querySelectorAll(selector) {
-        return this.childNodes.reduce((results, node) => {
-          if (node instanceof Element) {
-            if (node.matches(selector)) results.push(node);
-            const nodeList = node.querySelectorAll(selector);
-            for (let i = 0; i < nodeList.length; i++) {
-              results.push(nodeList[i]);
+        return this.childNodes.reduce(
+          (results, node) => {
+            if (node instanceof Element) {
+              if (node.matches(selector)) results.push(node);
+              const nodeList = node.querySelectorAll(selector);
+              for (let i = 0; i < nodeList.length; i++) {
+                results.push(nodeList[i]);
+              }
             }
-          }
-          return results;
-        }, /** @type {Element[]} */ ([]));
+            return results;
+          },
+          /** @type {Element[]} */ []
+        );
       }
 
       /**
@@ -1255,9 +1256,8 @@ var Idiomorph = (function () {
           '<body><template>' + newContent + '</template></body>',
           'text/html'
         );
-        let content = /** @type {HTMLTemplateElement} */ (
-          responseDoc.body.querySelector('template')
-        ).content;
+        let content =
+          /** @type {HTMLTemplateElement} */ responseDoc.body.querySelector('template').content;
         generatedByIdiomorph.add(content);
         return content;
       }

package/src/middleware.ts

@@ -0,0 +1,19 @@
+import { Context, Next } from 'hono';
+import { etag } from 'hono/etag';
+import timestring from 'timestring';
+
+/**
+ * Cache the response for a given time length ('30s', '1d', '1w', '1m', etc) or given number of seconds
+ */
+export function cacheTime(timeStrOrSeconds: string | number) {
+  return (c: Context, next: Next) =>
+    etag()(c, () => {
+      // Only cache GET requests
+      if (c.req.method.toUpperCase() === 'GET') {
+        const timeInSeconds =
+          typeof timeStrOrSeconds === 'number' ? timeStrOrSeconds : timestring(timeStrOrSeconds);
+        c.header('Cache-Control', `public, max-age=${timeInSeconds}`);
+      }
+      return next();
+    });
+}

package/src/server.ts

@@ -2,10 +2,11 @@ import { readdir } from 'node:fs/promises';
 import { basename, extname, join } from 'node:path';
 import { HSHtml, html, isHSHtml, renderStream, renderAsync, render } from '@hyperspan/html';
 import { isbot } from 'isbot';
-import { buildClientJS, buildClientCSS } from './assets';
+import { buildClientJS, buildClientCSS, assetHash } 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';
 import type { ContentfulStatusCode } from 'hono/utils/http-status';
 
@@ -55,14 +56,23 @@ export function createRoute(handler?: THSRouteHandler): THSRoute {
 
   const api: THSRoute = {
     _kind: 'hsRoute',
+    /**
+     * Add a GET route handler (primary page display)
+     */
     get(handler: THSRouteHandler) {
       _handlers['GET'] = handler;
       return api;
     },
+    /**
+     * Add a POST route handler (typically to process form data)
+     */
     post(handler: THSRouteHandler) {
       _handlers['POST'] = handler;
       return api;
     },
+    /**
+     * Add middleware specific to this route
+     */
     middleware(middleware: Array<MiddlewareHandler>) {
       _middleware = middleware;
       return api;
@@ -73,45 +83,14 @@ export function createRoute(handler?: THSRouteHandler): THSRoute {
         async (context: Context) => {
           const method = context.req.method.toUpperCase();
 
-          try {
+          return returnHTMLResponse(context, () => {
             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);
-          }
+            return handler(context);
+          });
         },
       ];
     },
@@ -213,6 +192,49 @@ export function createAPIRoute(handler?: THSAPIRouteHandler): THSAPIRoute {
   return api;
 }
 
+/**
+ * Return HTML response from userland route handler
+ */
+export async function returnHTMLResponse(
+  context: Context,
+  handlerFn: () => unknown,
+  responseOptions?: { status?: ContentfulStatusCode; headers?: Headers | Record<string, string> }
+): Promise<Response> {
+  try {
+    const routeContent = await handlerFn();
+
+    // 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)) {
+      // Stream only if enabled and there is async content to stream
+      if (streamingEnabled && (routeContent as HSHtml).asyncContent?.length > 0) {
+        return new StreamResponse(
+          renderStream(routeContent as HSHtml),
+          responseOptions
+        ) as Response;
+      } else {
+        const output = await renderAsync(routeContent as HSHtml);
+        return context.html(output, responseOptions);
+      }
+    }
+
+    // Return unknown content as string - not specifically handled above
+    return context.html(String(routeContent), responseOptions);
+  } catch (e) {
+    !IS_PROD && console.error(e);
+    return await showErrorReponse(context, e as Error, responseOptions);
+  }
+}
+
 /**
  * Get a Hyperspan runnable route from a module import
  * @throws Error if no runnable route found
@@ -260,7 +282,11 @@ export function isRunnableRoute(route: unknown): boolean {
  * Basic error handling
  * @TODO: Should check for and load user-customizeable template with special name (app/__error.ts ?)
  */
-async function showErrorReponse(context: Context, err: Error) {
+async function showErrorReponse(
+  context: Context,
+  err: Error,
+  responseOptions?: { status?: ContentfulStatusCode; headers?: Headers | Record<string, string> }
+) {
   let status: ContentfulStatusCode = 500;
   const message = err.message || 'Internal Server Error';
 
@@ -271,6 +297,18 @@ async function showErrorReponse(context: Context, err: Error) {
 
   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') {
+    const output = render(html`
+      <section style="padding: 20px;">
+        <p style="margin-bottom: 10px;"><strong>Error</strong></p>
+        <strong>${message}</strong>
+        ${stack ? html`<pre>${stack}</pre>` : ''}
+      </section>
+    `);
+    return context.html(output, Object.assign({ status }, responseOptions));
+  }
+
   const output = render(html`
     <!DOCTYPE html>
     <html lang="en">
@@ -289,7 +327,7 @@ async function showErrorReponse(context: Context, err: Error) {
     </html>
   `);
 
-  return context.html(output, { status });
+  return context.html(output, Object.assign({ status }, responseOptions));
 }
 
 export type THSServerConfig = {
@@ -306,6 +344,7 @@ export type THSRouteMap = {
   file: string;
   route: string;
   params: string[];
+  module?: any;
 };
 
 /**
@@ -352,12 +391,54 @@ export async function buildRoutes(config: THSServerConfig): Promise<THSRouteMap[
 
     routes.push({
       file: join('./', routesDir, file),
-      route: route || '/',
+      route: normalizePath(route || '/'),
       params,
     });
   }
 
-  return routes;
+  // 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
+    if (!file.includes('.') || basename(file).startsWith('.')) {
+      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;
+    })
+  );
 }
 
 /**
@@ -382,20 +463,24 @@ export async function createServer(config: THSServerConfig): Promise<Hono> {
   // [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 = await buildRoutes(config);
+  const fileRoutes = routes.concat(actions);
   const routeMap = [];
 
   for (let i = 0; i < fileRoutes.length; i++) {
     let route = fileRoutes[i];
-    const fullRouteFile = join(CWD, route.file);
-    const routePattern = normalizePath(route.route);
 
-    routeMap.push({ route: routePattern, file: route.file });
+    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}`);
+    }
 
-    // Import route
-    const routeHandlers = createRouteFromModule(await import(fullRouteFile));
-    app.all(routePattern, ...routeHandlers);
+    const routeHandlers = createRouteFromModule(route.module);
+    app.all(route.route, ...routeHandlers);
   }
 
   // Help route if no routes found