@hyperspan/framework 1.0.20 → 1.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "Hyperspan Web Framework",
   "main": "src/server.ts",
   "types": "src/server.ts",
@@ -84,6 +84,6 @@
     "@hyperspan/html": "^1.0.1",
     "debug": "^4.4.3",
     "isbot": "^5.1.32",
-    "zod": "^4.1.12"
+    "zod": "^4.4.3"
   }
 }

package/src/actions.test.ts

@@ -2,7 +2,7 @@ import { test, expect, describe } from 'bun:test';
 import { createAction } from './actions';
 import { html, render, type HSHtml } from '@hyperspan/html';
 import { createContext } from './server';
-import * as z from 'zod/v4';
+import * as z from 'zod';
 
 describe('createAction', () => {
   test('creates an action with a simple form and no schema', async () => {

package/src/actions.ts

@@ -1,6 +1,6 @@
 import { html } from '@hyperspan/html';
 import { createRoute, HTTPResponseException, returnHTMLResponse } from './server';
-import * as z from 'zod/v4';
+import * as z from 'zod';
 import type { Hyperspan as HS } from './types';
 import { assetHash, formDataToJSON } from './utils';
 import { buildClientJS } from './client/js';
@@ -23,12 +23,20 @@ const actionsClientJS = await buildClientJS(import.meta.resolve('./client/_hs/hy
  * 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
  */
-export function createAction<T extends z.ZodObject<any, any>>(params: { name: string; schema?: T }): HS.Action<T> {
+export function createAction<S extends z.ZodType>(
+  params: { name: string; schema: S }
+): HS.Action<S>;
+export function createAction(
+  params: { name: string; schema?: undefined }
+): HS.Action<undefined>;
+export function createAction<S extends z.ZodType>(
+  params: { name: string; schema?: S }
+): HS.Action<S | undefined> {
   const { name, schema } = params;
   const path = `/__actions/${assetHash(name)}`;
 
-  let _handler: Parameters<HS.Action<T>['post']>[0] | null = null;
-  let _errorHandler: Parameters<HS.Action<T>['errorHandler']>[0] | null = null;
+  let _handler: Parameters<HS.Action<S | undefined>['post']>[0] | null = null;
+  let _errorHandler: Parameters<HS.Action<S | undefined>['errorHandler']>[0] | null = null;
 
   const route = createRoute({ path, name })
     .get((c: HS.Context) => api.render(c))
@@ -37,7 +45,7 @@ export function createAction<T extends z.ZodObject<any, any>>(params: { name: st
         throw new Error('Action POST handler not set! Every action must have a POST handler.');
       }
 
-      const data = c.vars.body as z.infer<T> || formDataToJSON(await c.req.formData()) || {};
+      const data = c.vars.body as HS.InferActionData<S> || formDataToJSON(await c.req.formData()) || {};
       log('POST handler', { data });
       const response = await _handler(c, { data });
       log('POST handler response', { response });
@@ -57,7 +65,7 @@ export function createAction<T extends z.ZodObject<any, any>>(params: { name: st
      * Custom error handler for the action since validateBody() throws a HTTPResponseException
      */
     .errorHandler(async (c: HS.Context, err: HTTPResponseException) => {
-      const data = c.vars.body as z.infer<T> || formDataToJSON(await c.req.formData()) || {};
+      const data = c.vars.body as HS.InferActionData<S> || formDataToJSON(await c.req.formData()) || {};
       const error = err._error as ZodValidationError || err;
 
       // Set the status to 400 if it's a ZodValidationError, otherwise 500 (Error thrown by user POST handler)
@@ -73,7 +81,7 @@ export function createAction<T extends z.ZodObject<any, any>>(params: { name: st
   // Set the name of the action for the route
   route._config.name = name;
 
-  const api: HS.Action<T> = {
+  const api: HS.Action<S | undefined> = {
     _kind: 'hsAction',
     _config: route._config,
     _path() {

package/src/client/_hs/hyperspan-actions.client.ts

@@ -99,7 +99,7 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
   }
 
   fetch(formUrl, { body: formData, method, headers })
-    .then((res: Response) => {
+    .then(async (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')) {
@@ -109,21 +109,20 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
 
           // If the new URL is the same as the current URL, we can just fetch the new HTML and apply it
           if (resolved.pathname === window.location.pathname) {
-            return fetch(resolved.href, {
+            const pageRes = await fetch(resolved.href, {
               headers: { Accept: 'text/html' },
-            })
-              .then((r) => r.text());
+            });
+            await consumeStreamingHtmlResponse(pageRes, applyResponseHtml);
+            return;
           }
 
           // If the new URL is different, we need to redirect the user to the new URL
           window.location.assign(newUrl);
         }
-        return '';
+        return;
       }
 
-      return res.text();
-    })
-    .then((content: string) => {
+      const content = await res.text();
       // No content = DO NOTHING (redirect or something else happened)
       if (!content) {
         return;
@@ -134,4 +133,94 @@ function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOpt
     .catch((error) => {
       console.error('[Hyperspan] Error submitting form action:', error);
     });
+}
+
+/** Streaming async chunks use template ids ending in `_content`. */
+const STREAM_CHUNK_MARKER = /<template id="[^"]+_content">/;
+
+function splitInitialStreamHtml(html: string): { initial: string; streamTail: string | null } {
+  const match = STREAM_CHUNK_MARKER.exec(html);
+  if (!match || match.index === 0) {
+    return { initial: html, streamTail: null };
+  }
+  return {
+    initial: html.slice(0, match.index),
+    streamTail: html.slice(match.index),
+  };
+}
+
+/** Append streamed HTML to body and run any inline scripts (e.g. window._hsc.push). */
+function appendHtmlToBody(html: string) {
+  if (!html) {
+    return;
+  }
+
+  const template = document.createElement('template');
+  template.innerHTML = html;
+  const scripts: HTMLScriptElement[] = [];
+  template.content.querySelectorAll('script').forEach((script) => {
+    scripts.push(script);
+    script.remove();
+  });
+  document.body.appendChild(template.content);
+  for (const script of scripts) {
+    const executable = document.createElement('script');
+    if (script.src) {
+      executable.src = script.src;
+    } else {
+      executable.textContent = script.textContent;
+    }
+    document.body.appendChild(executable);
+  }
+}
+
+/**
+ * Read a (possibly streaming) HTML response: Idiomorph the initial page HTML, then append
+ * later stream chunks to document.body so streaming scripts run and placeholders resolve.
+ */
+async function consumeStreamingHtmlResponse(
+  res: Response,
+  applyInitialHtml: (html: string) => void
+) {
+  const body = res.body;
+  if (!body) {
+    const text = await res.text();
+    if (text) {
+      applyInitialHtml(text);
+    }
+    return;
+  }
+
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let isFirstChunk = true;
+
+  function processChunk(html: string) {
+    if (!html) {
+      return;
+    }
+
+    if (isFirstChunk) {
+      isFirstChunk = false;
+      const { initial, streamTail } = splitInitialStreamHtml(html);
+      if (initial) {
+        applyInitialHtml(initial);
+      }
+      if (streamTail) {
+        appendHtmlToBody(streamTail);
+      }
+      return;
+    }
+
+    appendHtmlToBody(html);
+  }
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      processChunk(decoder.decode());
+      break;
+    }
+    processChunk(decoder.decode(value, { stream: true }));
+  }
 }

package/src/middleware.ts

@@ -1,8 +1,8 @@
 import { formDataToJSON } from './utils';
-import { z, flattenError, prettifyError } from 'zod/v4';
+import { z, flattenError, prettifyError } from 'zod';
 import { HTTPResponseException } from './server';
 
-import type { ZodAny, ZodObject, ZodError } from 'zod/v4';
+import type { ZodAny, ZodObject, ZodError } from 'zod';
 import type { Hyperspan as HS } from './types';
 
 export type TValidationType = 'json' | 'form' | 'urlencoded';

package/src/types.ts

@@ -1,5 +1,5 @@
 import { HSHtml } from '@hyperspan/html';
-import * as z from 'zod/v4';
+import * as z from 'zod';
 
 /**
  * Hyperspan Types
@@ -175,30 +175,41 @@ export namespace Hyperspan {
   /**
    * Action = Form + route handler
    */
+  /** Raw form field values when an action has no schema */
+  export type ActionFormValues = Record<string, string | string[]>;
+  /** Infer validated action data from an optional schema */
+  export type InferActionData<S extends z.ZodType | undefined> =
+    S extends z.ZodType ? z.output<S> : ActionFormValues;
   // Form renderer
   export type ActionFormResponse = HSHtml | void | null | Promise<HSHtml | void | null>;
-  export type ActionFormProps<T extends z.ZodTypeAny> = { data?: Partial<z.infer<T>>; error?: ZodValidationError };
-  export type ActionForm<T extends z.ZodTypeAny> = (
-    c: Context, props: ActionFormProps<T>
+  export type ActionFormProps<S extends z.ZodType | undefined = undefined> = {
+    data?: Partial<InferActionData<S>>;
+    error?: ZodValidationError;
+  };
+  export type ActionForm<S extends z.ZodType | undefined = undefined> = (
+    c: Context, props: ActionFormProps<S>
   ) => ActionFormResponse;
   // Form handler
   export type ActionFormHandlerResponse = ActionFormResponse | Response | Promise<Response>;
-  export type ActionFormHandlerProps<T extends z.ZodTypeAny> = { data: z.infer<T>; error?: ZodValidationError | Error };
-  export type ActionFormHandler<T extends z.ZodTypeAny> = (
-    c: Context, props: ActionFormHandlerProps<T>
+  export type ActionFormHandlerProps<S extends z.ZodType | undefined = undefined> = {
+    data: InferActionData<S>;
+    error?: ZodValidationError | Error;
+  };
+  export type ActionFormHandler<S extends z.ZodType | undefined = undefined> = (
+    c: Context, props: ActionFormHandlerProps<S>
   ) => ActionFormHandlerResponse;
   // Action API
-  export interface Action<T extends z.ZodTypeAny> {
+  export interface Action<S extends z.ZodType | undefined = undefined> {
     _kind: 'hsAction';
     _config: Partial<Hyperspan.RouteConfig>;
     _path(): string;
-    _form: null | ActionForm<T>;
-    form(form: ActionForm<T>): Action<T>;
-    render: (c: Context, props?: ActionFormProps<T>) => ActionFormResponse;
-    post: (handler: ActionFormHandler<T>) => Action<T>;
-    errorHandler: (handler: ActionFormHandler<T>) => Action<T>;
-    use: (middleware: Hyperspan.MiddlewareFunction, opts?: Hyperspan.MiddlewareMethodOptions) => Action<T>;
-    middleware: (middleware: Array<Hyperspan.MiddlewareFunction>, opts?: Hyperspan.MiddlewareMethodOptions) => Action<T>;
+    _form: null | ActionForm<S>;
+    form(form: ActionForm<S>): Action<S>;
+    render: (c: Context, props?: ActionFormProps<S>) => ActionFormResponse;
+    post: (handler: ActionFormHandler<S>) => Action<S>;
+    errorHandler: (handler: ActionFormHandler<S>) => Action<S>;
+    use: (middleware: Hyperspan.MiddlewareFunction, opts?: Hyperspan.MiddlewareMethodOptions) => Action<S>;
+    middleware: (middleware: Array<Hyperspan.MiddlewareFunction>, opts?: Hyperspan.MiddlewareMethodOptions) => Action<S>;
     fetch: (request: Request) => Promise<Response>;
   }