@hyperspan/framework 0.3.2 → 0.3.3

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

@@ -2,6 +2,7 @@ import {
   buildClientCSS,
   buildClientJS
 } from "./assets.js";
+import"./chunk-atw8cdg1.js";
 
 // src/server.ts
 import { readdir } from "node:fs/promises";
@@ -1869,7 +1870,7 @@ function createRoute(handler) {
             const streamOpt = context.req.query("__nostream");
             const streamingEnabled = !userIsBot && (streamOpt !== undefined ? streamOpt : true);
             if (isHSHtml(routeContent)) {
-              if (streamingEnabled) {
+              if (streamingEnabled && routeContent.asyncContent?.length > 0) {
                 return new StreamResponse(renderStream(routeContent));
               } else {
                 const output = await renderAsync(routeContent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "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>`;
         })
@@ -65,7 +65,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>`;

package/src/actions.ts

@@ -32,7 +32,7 @@ export interface HSAction<T extends z.ZodTypeAny> {
   run(method: 'GET' | 'POST', c: Context): Promise<THSResponseTypes>;
 }
 
-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
 ) {
@@ -87,7 +87,7 @@ 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;
       let error: z.ZodError | Error | null = null;
@@ -128,7 +128,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.

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

@@ -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';
 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;
@@ -93,7 +103,8 @@ export function createRoute(handler?: THSRouteHandler): THSRoute {
 
             // Render HSHtml if returned from route handler
             if (isHSHtml(routeContent)) {
-              if (streamingEnabled) {
+              // 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)) as Response;
               } else {
                 const output = await renderAsync(routeContent as HSHtml);