@hyperspan/framework 1.0.0-alpha.1 → 1.0.0-alpha.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.4",
   "description": "Hyperspan Web Framework",
   "main": "src/server.ts",
   "types": "src/server.ts",
@@ -10,8 +10,8 @@
   },
   "exports": {
     ".": {
-      "types": "./src/server.ts",
-      "default": "./src/server.ts"
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
     },
     "./server": {
       "types": "./src/server.ts",
@@ -44,6 +44,10 @@
     "./plugins": {
       "types": "./src/plugins.ts",
       "default": "./src/plugins.ts"
+    },
+    "./actions": {
+      "types": "./src/actions.ts",
+      "default": "./src/actions.ts"
     }
   },
   "author": "Vance Lucas <vance@vancelucas.com>",

package/src/actions.test.ts

@@ -0,0 +1,206 @@
+import { test, expect, describe } from 'bun:test';
+import { formDataToJSON, createAction } from './actions';
+import { html, render, type HSHtml } from '@hyperspan/html';
+import { createContext } from './server';
+import type { Hyperspan as HS } from './types';
+import * as z from 'zod/v4';
+
+describe('formDataToJSON', () => {
+  test('formDataToJSON returns empty object for empty FormData', () => {
+    const formData = new FormData();
+    const result = formDataToJSON(formData);
+
+    expect(result).toEqual({});
+  });
+
+  test('formDataToJSON handles simple FormData object', () => {
+    const formData = new FormData();
+    formData.append('name', 'John Doe');
+    formData.append('email', 'john@example.com');
+    formData.append('age', '30');
+
+    const result = formDataToJSON(formData);
+
+    expect(result).toEqual({
+      name: 'John Doe',
+      email: 'john@example.com',
+      age: '30',
+    });
+  });
+
+  test('formDataToJSON handles complex FormData with nested fields', () => {
+    const formData = new FormData();
+    formData.append('user[firstName]', 'John');
+    formData.append('user[lastName]', 'Doe');
+    formData.append('user[email]', 'john@example.com');
+    formData.append('user[address][street]', '123 Main St');
+    formData.append('user[address][city]', 'New York');
+    formData.append('user[address][zip]', '10001');
+
+    const result = formDataToJSON(formData);
+
+    expect(result).toEqual({
+      user: {
+        firstName: 'John',
+        lastName: 'Doe',
+        email: 'john@example.com',
+        address: {
+          street: '123 Main St',
+          city: 'New York',
+          zip: '10001',
+        },
+      },
+    } as any);
+  });
+
+  test('formDataToJSON handles FormData with array of values', () => {
+    const formData = new FormData();
+    formData.append('tags', 'javascript');
+    formData.append('tags', 'typescript');
+    formData.append('tags', 'nodejs');
+    formData.append('colors[]', 'red');
+    formData.append('colors[]', 'green');
+    formData.append('colors[]', 'blue');
+
+    const result = formDataToJSON(formData);
+
+    expect(result).toEqual({
+      tags: ['javascript', 'typescript', 'nodejs'],
+      colors: ['red', 'green', 'blue'],
+    });
+  });
+});
+
+describe('createAction', () => {
+  test('creates an action with a simple form and no schema', async () => {
+    const action = createAction({
+      form: (c: HS.Context) => {
+        return html`
+          <form>
+            <input type="text" name="name" />
+            <button type="submit">Submit</button>
+          </form>
+        `;
+      },
+    });
+
+    expect(action).toBeDefined();
+    expect(action._kind).toBe('hsAction');
+    expect(action._route).toContain('/__actions/');
+
+    // Test render method
+    const request = new Request('http://localhost:3000/');
+    const context = createContext(request);
+    const rendered = render(action.render(context) as HSHtml);
+
+    expect(rendered).not.toBeNull();
+    const htmlString = rendered;
+    expect(htmlString).toContain('<hs-action');
+    expect(htmlString).toContain('name="name"');
+  });
+
+  test('creates an action with a Zod schema matching form inputs', async () => {
+    const schema = z.object({
+      name: z.string().min(1, 'Name is required'),
+      email: z.email('Invalid email address'),
+    });
+
+    const action = createAction({
+      schema,
+      form: (c: HS.Context, { data }) => {
+        return html`
+          <form>
+            <input type="text" name="name" value="${data?.name || ''}" />
+            <input type="email" name="email" value="${data?.email || ''}" />
+            <button type="submit">Submit</button>
+          </form>
+        `;
+      },
+    }).post(async (c: HS.Context, { data }) => {
+      return c.res.html(`
+        <p>Hello, ${data?.name}!</p>
+        <p>Your email is ${data?.email}.</p>
+      `);
+    });
+
+    expect(action).toBeDefined();
+    expect(action._kind).toBe('hsAction');
+    expect(action._route).toContain('/__actions/');
+
+    // Test render method
+    const request = new Request('http://localhost:3000/');
+    const context = createContext(request);
+    const rendered = action.render(context);
+
+    expect(rendered).not.toBeNull();
+    const htmlString = render(rendered as unknown as HSHtml);
+    expect(htmlString).toContain('name="name"');
+    expect(htmlString).toContain('name="email"');
+
+    // Test fetch method with POST request to trigger validation
+    const formData = new FormData();
+    formData.append('name', 'John Doe');
+    formData.append('email', 'john@example.com');
+
+    const postRequest = new Request(`http://localhost:3000${action._route}`, {
+      method: 'POST',
+      body: formData,
+    });
+
+    const response = await action.fetch(postRequest);
+    expect(response).toBeInstanceOf(Response);
+    expect(response.status).toBe(200);
+
+    const responseText = await response.text();
+    expect(responseText).toContain('Hello, John Doe!');
+    expect(responseText).toContain('Your email is john@example.com.');
+  });
+
+  test('re-renders form with error when schema validation fails', async () => {
+    const schema = z.object({
+      name: z.string().min(1, 'Name is required'),
+      email: z.email('Invalid email address'),
+    });
+
+    const action = createAction({
+      schema,
+      form: (c: HS.Context, { data, error }) => {
+        return html`
+          <form>
+            <input type="text" name="name" value="${data?.name || ''}" />
+            ${error ? html`<div class="error">Validation failed</div>` : ''}
+            <input type="email" name="email" value="${data?.email || ''}" />
+            <button type="submit">Submit</button>
+          </form>
+        `;
+      },
+    }).post(async (c: HS.Context, { data }) => {
+      return c.res.html(`
+        <p>Hello, ${data?.name}!</p>
+        <p>Your email is ${data?.email}.</p>
+      `);
+    });
+
+    // Test fetch method with invalid data (missing name, invalid email)
+    const formData = new FormData();
+    formData.append('email', 'not-an-email');
+
+    const postRequest = new Request(`http://localhost:3000${action._route}`, {
+      method: 'POST',
+      body: formData,
+    });
+
+    const response = await action.fetch(postRequest);
+    expect(response).toBeInstanceOf(Response);
+    expect(response.status).toBe(400);
+
+    const responseText = await response.text();
+    // Should re-render the form, not the post handler output
+    expect(responseText).toContain('name="name"');
+    expect(responseText).toContain('name="email"');
+    expect(responseText).toContain('Validation failed');
+    // Should NOT contain the success message from post handler
+    expect(responseText).not.toContain('Hello,');
+  });
+});
+

package/src/actions.ts

@@ -0,0 +1,187 @@
+import { html, HSHtml } from '@hyperspan/html';
+import { createRoute, returnHTMLResponse } from './server';
+import * as z from 'zod/v4';
+import type { Hyperspan as HS } from './types';
+import { assetHash } from './utils';
+import * as actionsClient from './client/_hs/hyperspan-actions.client';
+import { renderClientJS } from './client/js';
+
+/**
+ * Actions = Form + route handler
+ * Automatically handles and parses form data
+ *
+ * HOW THIS WORKS:
+ * ---
+ * 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
+ */
+export function createAction<T extends z.ZodTypeAny>(params: { name: string; schema?: T }): HS.Action<T> {
+  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;
+
+  const route = createRoute({ path, name })
+    .get((c: HS.Context) => api.render(c))
+    .post(async (c: HS.Context) => {
+      // Parse form data
+      const formData = await c.req.raw.formData();
+      const jsonData = formDataToJSON(formData) as Partial<z.infer<T>>;
+      const schemaData = schema ? schema.safeParse(jsonData) : null;
+      const data = schemaData?.success ? (schemaData.data as Partial<z.infer<T>>) : jsonData;
+      let error: z.ZodError | Error | null = null;
+
+      try {
+        if (schema && schemaData?.error) {
+          throw schemaData.error;
+        }
+
+        if (!_handler) {
+          throw new Error('Action POST handler not set! Every action must have a POST handler.');
+        }
+
+        const response = await _handler(c, { data });
+
+        if (response instanceof Response) {
+          // 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;
+      } catch (e) {
+        error = e as Error | z.ZodError;
+      }
+
+      if (error && _errorHandler) {
+        const errorHandler = _errorHandler; // Required for TypeScript to infer the correct type after narrowing
+        return await returnHTMLResponse(c, () => errorHandler(c, { data, error }), {
+          status: 400,
+        });
+      }
+
+      return await returnHTMLResponse(c, () => api.render(c, { data, error }), { status: 400 });
+    });
+
+  const api: HS.Action<T> = {
+    _kind: 'hsAction',
+    _config: route._config,
+    _path() {
+      return path;
+    },
+    _form: null,
+    /**
+     * Form to render
+     * This will be wrapped in a <hs-action> web component and submitted via fetch()
+     */
+    form(form: HS.ActionFormHandler<T>) {
+      api._form = form;
+      return api;
+    },
+    /**
+     * Process form data
+     *
+     * Returns result from form processing if successful
+     * Re-renders form with data and error information otherwise
+     */
+    post(handler) {
+      _handler = handler;
+      return api;
+    },
+    /**
+     * Get form renderer method
+     */
+    render(c: HS.Context, props?: HS.ActionProps<T>) {
+      const formContent = api._form ? api._form(c, props || {}) : null;
+      return formContent ? html`<hs-action url="${this._path()}">${formContent}</hs-action>${renderClientJS(actionsClient)}` : null;
+    },
+    errorHandler(handler) {
+      _errorHandler = handler;
+      return api;
+    },
+    middleware(middleware: Array<HS.MiddlewareFunction>) {
+      route.middleware(middleware);
+      return api;
+    },
+    fetch: route.fetch,
+  };
+
+  return api;
+}
+
+/**
+ * Return JSON data structure for a given FormData object
+ * Accounts for array fields (e.g. name="options[]" or <select multiple>)
+ *
+ * @link https://stackoverflow.com/a/75406413
+ */
+export function formDataToJSON(formData: FormData): Record<string, string | string[]> {
+  let object = {};
+
+  /**
+   * Parses FormData key xxx`[x][x][x]` fields into array
+   */
+  const parseKey = (key: string) => {
+    const subKeyIdx = key.indexOf('[');
+
+    if (subKeyIdx !== -1) {
+      const keys = [key.substring(0, subKeyIdx)];
+      key = key.substring(subKeyIdx);
+
+      for (const match of key.matchAll(/\[(?<key>.*?)]/gm)) {
+        if (match.groups) {
+          keys.push(match.groups.key);
+        }
+      }
+      return keys;
+    } else {
+      return [key];
+    }
+  };
+
+  /**
+   * Recursively iterates over keys and assigns key/values to object
+   */
+  const assign = (keys: string[], value: FormDataEntryValue, object: any): void => {
+    const key = keys.shift();
+
+    // When last key in the iterations
+    if (key === '' || key === undefined) {
+      return object.push(value);
+    }
+
+    if (Reflect.has(object, key)) {
+      // If key has been found, but final pass - convert the value to array
+      if (keys.length === 0) {
+        if (!Array.isArray(object[key])) {
+          object[key] = [object[key], value];
+          return;
+        }
+      }
+      // Recurse again with found object
+      return assign(keys, value, object[key]);
+    }
+
+    // Create empty object for key, if next key is '' do array instead, otherwise set value
+    if (keys.length >= 1) {
+      object[key] = keys[0] === '' ? [] : {};
+      return assign(keys, value, object[key]);
+    } else {
+      object[key] = value;
+    }
+  };
+
+  for (const pair of formData.entries()) {
+    assign(parseKey(pair[0]), pair[1], object);
+  }
+
+  return object;
+}

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

@@ -0,0 +1,98 @@
+import { Idiomorph } from './idiomorph';
+import { lazyLoadScripts } from './hyperspan-scripts.client';
+
+const actionFormObserver = new MutationObserver((list) => {
+  list.forEach((mutation) => {
+    mutation.addedNodes.forEach((node) => {
+      if (node && ('closest' in node || node instanceof HTMLFormElement)) {
+        bindHSActionForm(
+          (node as HTMLElement).closest('hs-action') as HSAction,
+          node instanceof HTMLFormElement
+            ? node
+            : ((node as HTMLElement | HTMLFormElement).querySelector('form') as HTMLFormElement)
+        );
+      }
+    });
+  });
+});
+
+/**
+ * Server action component to handle the client-side form submission and HTML replacement
+ */
+class HSAction extends HTMLElement {
+  constructor() {
+    super();
+  }
+
+  connectedCallback() {
+    actionFormObserver.observe(this, { childList: true, subtree: true });
+    bindHSActionForm(this, this.querySelector('form') as HTMLFormElement);
+  }
+}
+window.customElements.define('hs-action', HSAction);
+
+/**
+ * Bind the form inside an hs-action element to the action URL and submit handler
+ */
+function bindHSActionForm(hsActionElement: HSAction, form: HTMLFormElement) {
+  if (!hsActionElement || !form) {
+    return;
+  }
+
+  form.setAttribute('action', hsActionElement.getAttribute('url') || '');
+  const submitHandler = (e: Event) => {
+    e.preventDefault();
+    formSubmitToRoute(e, form as HTMLFormElement, {
+      afterResponse: () => bindHSActionForm(hsActionElement, form),
+    });
+    form.removeEventListener('submit', submitHandler);
+  };
+  form.addEventListener('submit', submitHandler);
+}
+
+/**
+ * Submit form data to route and replace contents with response
+ */
+type TFormSubmitOptons = { afterResponse: () => any };
+function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOptons) {
+  const formData = new FormData(form);
+  const formUrl = form.getAttribute('action') || '';
+  const method = form.getAttribute('method')?.toUpperCase() || 'POST';
+  const headers = {
+    Accept: 'text/html',
+    'X-Request-Type': 'partial',
+  };
+
+  const hsActionTag = form.closest('hs-action');
+  const submitBtn = form.querySelector('button[type=submit],input[type=submit]');
+  if (submitBtn) {
+    submitBtn.setAttribute('disabled', 'disabled');
+  }
+
+  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);
+        }
+        return '';
+      }
+
+      return res.text();
+    })
+    .then((content: string) => {
+      // No content = DO NOTHING (redirect or something else happened)
+      if (!content) {
+        return;
+      }
+
+      const target = content.includes('<html') ? window.document.body : hsActionTag || form;
+
+      Idiomorph.morph(target, content);
+      opts.afterResponse && opts.afterResponse();
+      lazyLoadScripts();
+    });
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Intersection observer for lazy loading <script> tags
+ */
+const lazyLoadScriptObserver = new IntersectionObserver(
+  (entries, observer) => {
+    entries
+      .filter((entry) => entry.isIntersecting)
+      .forEach((entry) => {
+        observer.unobserve(entry.target);
+        // @ts-ignore
+        if (entry.target.children[0]?.content) {
+          // @ts-ignore
+          entry.target.replaceWith(entry.target.children[0].content);
+        }
+      });
+  },
+  { rootMargin: '0px 0px -200px 0px' }
+);
+
+/**
+ * Lazy load <script> tags in the current document
+ */
+export function lazyLoadScripts() {
+  document
+    .querySelectorAll('div[data-loading=lazy]')
+    .forEach((el) => lazyLoadScriptObserver.observe(el));
+}
+
+window.addEventListener('load', () => {
+  lazyLoadScripts();
+});

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

@@ -0,0 +1,94 @@
+import { Idiomorph } from './idiomorph';
+import { lazyLoadScripts } from './hyperspan-scripts.client';
+
+/**
+ * Used for streaming content from the server to the client.
+ */
+function htmlAsyncContentObserver() {
+  if (typeof MutationObserver != 'undefined') {
+    // Hyperspan - Async content loader
+    // Puts streamed content in its place immediately after it is added to the DOM
+    const asyncContentObserver = new MutationObserver((list) => {
+      const asyncContent = list
+        .map((mutation) =>
+          Array.from(mutation.addedNodes).find((node: any) => {
+            if (!node || !node?.id || typeof node.id !== 'string') {
+              return false;
+            }
+            return node.id?.startsWith('async_loading_') && node.id?.endsWith('_content');
+          })
+        )
+        .filter((node: any) => node);
+
+      asyncContent.forEach((templateEl: any) => {
+        try {
+          // Also observe for content inside the template content (shadow DOM is separate)
+          asyncContentObserver.observe(templateEl.content, { childList: true, subtree: true });
+
+          const slotId = templateEl.id.replace('_content', '');
+          const slotEl = document.getElementById(slotId);
+
+          if (slotEl) {
+            // Content AND slot are present - let's insert the content into the slot
+            // Ensure the content is fully done streaming in before inserting it into the slot
+            waitForContent(templateEl.content, (el2) => {
+              return Array.from(el2.childNodes).find(
+                (node) => node.nodeType === Node.COMMENT_NODE && node.nodeValue === 'end'
+              );
+            })
+              .then((endComment) => {
+                templateEl.content.removeChild(endComment);
+                const content = templateEl.content.cloneNode(true);
+                Idiomorph.morph(slotEl, content);
+                templateEl.parentNode.removeChild(templateEl);
+                lazyLoadScripts();
+              })
+              .catch(console.error);
+          } else {
+            // Slot is NOT present - wait for it to be added to the DOM so we can insert the content into it
+            waitForContent(document.body, () => {
+              return document.getElementById(slotId);
+            }).then((slotEl) => {
+              Idiomorph.morph(slotEl, templateEl.content.cloneNode(true));
+              lazyLoadScripts();
+            });
+          }
+        } catch (e) {
+          console.error(e);
+        }
+      });
+    });
+    asyncContentObserver.observe(document.body, { childList: true, subtree: true });
+  }
+}
+htmlAsyncContentObserver();
+
+/**
+ * Wait until ALL of the content inside an element is present from streaming in.
+ * Large chunks of content can sometimes take more than a single tick to write to DOM.
+ */
+async function waitForContent(
+  el: HTMLElement,
+  waitFn: (
+    node: HTMLElement
+  ) => HTMLElement | HTMLTemplateElement | Node | ChildNode | null | undefined,
+  options: { timeoutMs?: number; intervalMs?: number } = { timeoutMs: 10000, intervalMs: 20 }
+): Promise<HTMLElement | HTMLTemplateElement | Node | ChildNode | null | undefined> {
+  return new Promise((resolve, reject) => {
+    let timeout: NodeJS.Timeout;
+    const interval = setInterval(() => {
+      const content = waitFn(el);
+      if (content) {
+        if (timeout) {
+          clearTimeout(timeout);
+        }
+        clearInterval(interval);
+        resolve(content);
+      }
+    }, options.intervalMs || 20);
+    timeout = setTimeout(() => {
+      clearInterval(interval);
+      reject(new Error(`[Hyperspan] Timeout waiting for end of streaming content ${el.id}`));
+    }, options.timeoutMs || 10000);
+  });
+}

package/src/client/js.ts

@@ -1,6 +1,4 @@
 import { html } from '@hyperspan/html';
-import type { Hyperspan as HS } from '../types';
-
 
 export const JS_PUBLIC_PATH = '/_hs/js';
 export const JS_ISLAND_PUBLIC_PATH = '/_hs/js/islands';
@@ -60,23 +58,4 @@ export function functionToString(fn: any) {
   }
 
   return str;
-}
-
-/**
- * Island defaults
- */
-export const ISLAND_DEFAULTS: () => HS.ClientIslandOptions = () => ({
-  ssr: true,
-  loading: undefined,
-});
-
-export function renderIsland(Component: any, props: any, options = ISLAND_DEFAULTS()) {
-  // Render island with its own logic
-  if (Component.__HS_ISLAND?.render) {
-    return html.raw(Component.__HS_ISLAND.render(props, options));
-  }
-
-  throw new Error(
-    `Module ${Component.name} was not loaded with an island plugin! Did you forget to install an island plugin and add it to the 'islandPlugins' option in your hyperspan.config.ts file?`
-  );
 }

package/src/index.ts

@@ -0,0 +1,2 @@
+export { createConfig, createContext, createRoute, createServer, getRunnableRoute, StreamResponse } from './server';
+export type { Hyperspan } from './types';

package/src/plugins.ts

@@ -46,6 +46,7 @@ export function clientJSPlugin(): HS.Plugin {
           const esmName = String(result.outputs[0].path.split('/').reverse()[0]).replace('.js', '');
           JS_IMPORT_MAP.set(esmName, `${JS_PUBLIC_PATH}/${esmName}.js`);
 
+          // Get the contents of the file to extract the exports
           const contents = await result.outputs[0].text();
           const exportLine = EXPORT_REGEX.exec(contents);
 
@@ -65,10 +66,7 @@ export function clientJSPlugin(): HS.Plugin {
 
           // Export a special object that can be used to render the client JS as a script tag
           const moduleCode = `// hyperspan:processed
-import { functionToString } from '@hyperspan/framework/assets';
-
-// Original file contents
-${contents}
+import { functionToString } from '@hyperspan/framework/client/js';
 
 // hyperspan:client-js-plugin
 export const __CLIENT_JS = {

package/src/server.test.ts

@@ -3,7 +3,7 @@ import { createRoute, createServer } from './server';
 import type { Hyperspan as HS } from './types';
 
 test('route fetch() returns a Response', async () => {
-  const route = createRoute().get((context) => {
+  const route = createRoute().get((context: HS.Context) => {
     return context.res.html('<h1>Hello World</h1>');
   });
 
@@ -16,24 +16,25 @@ test('route fetch() returns a Response', async () => {
 });
 
 test('server with two routes can return Response from one', async () => {
-  const server = createServer({
+  const server = await createServer({
     appDir: './app',
-    staticFileRoot: './public',
+    publicDir: './public',
+    plugins: [],
   });
 
   // Add two routes to the server
-  server.get('/users', (context) => {
+  server.get('/users', (context: HS.Context) => {
     return context.res.html('<h1>Users Page</h1>');
   });
 
-  server.get('/posts', (context) => {
+  server.get('/posts', (context: HS.Context) => {
     return context.res.html('<h1>Posts Page</h1>');
   });
 
 
   // Test that we can get a Response from one of the routes
   const request = new Request('http://localhost:3000/users');
-  const testRoute = server._routes.find((route) => route._path === '/users');
+  const testRoute = server._routes.find((route: HS.Route) => route._path() === '/users');
   const response = await testRoute!.fetch(request);
 
   expect(response).toBeInstanceOf(Response);
@@ -42,22 +43,23 @@ test('server with two routes can return Response from one', async () => {
 });
 
 test('server returns a route with a POST request', async () => {
-  const server = createServer({
+  const server = await createServer({
     appDir: './app',
-    staticFileRoot: './public',
+    publicDir: './public',
+    plugins: [],
   });
 
   // Add two routes to the server
-  server.get('/users', (context) => {
+  server.get('/users', (context: HS.Context) => {
     return context.res.html('<h1>GET /users</h1>');
   });
 
-  server.post('/users', (context) => {
+  server.post('/users', (context: HS.Context) => {
     return context.res.html('<h1>POST /users</h1>');
   });
 
-  const route = server._routes.find((route) => route._path === '/users' && route._methods().includes('POST')) as HS.Route;
-  const request = new Request('http://localhost:3000/', { method: 'POST' });
+  const route = server._routes.find((route: HS.Route) => route._path() === '/users' && route._methods().includes('POST')) as HS.Route;
+  const request = new Request('http://localhost:3000/users', { method: 'POST' });
   const response = await route.fetch(request);
 
   expect(response).toBeInstanceOf(Response);
@@ -66,18 +68,19 @@ test('server returns a route with a POST request', async () => {
 });
 
 test('returns 405 when route path matches but HTTP method does not', async () => {
-  const server = createServer({
+  const server = await createServer({
     appDir: './app',
-    staticFileRoot: './public',
+    publicDir: './public',
+    plugins: [],
   });
 
   // Route registered for GET only
-  server.get('/users', (context) => {
+  server.get('/users', (context: HS.Context) => {
     return context.res.html('<h1>Users Page</h1>');
   });
 
   // Attempt to POST to /users, which should return 405
-  const route = server._routes.find((route) => route._path === '/users')!;
+  const route = server._routes.find((route: HS.Route) => route._path() === '/users')!;
   const request = new Request('http://localhost:3000/users', { method: 'POST' });
   const response = await route.fetch(request);
 

package/src/server.ts

@@ -5,7 +5,6 @@ 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) {
@@ -38,9 +37,11 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
   const params: HS.RouteParamsParser<path> = req?.params || {};
 
   return {
+    vars: {},
     route: {
       path,
       params: params,
+      cssImports: route ? route._config.cssImports ?? [] : [],
     },
     req: {
       raw: req,
@@ -51,6 +52,7 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
       body: req.body,
     },
     res: {
+      headers: new Headers(),
       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 } }),
@@ -132,6 +134,10 @@ export function createRoute(config: HS.RouteConfig = {}): HS.Route {
       _middleware['OPTIONS'] = handlerOptions?.middleware || [];
       return api;
     },
+    errorHandler(handler: HS.RouteHandler) {
+      _handlers['_ERROR'] = handler;
+      return api;
+    },
     /**
      * Add middleware specific to this route
      */
@@ -145,12 +151,11 @@ export function createRoute(config: HS.RouteConfig = {}): HS.Route {
      */
     async fetch(request: Request) {
       const context = createContext(request, api);
+      const method = context.req.method;
       const globalMiddleware = _middleware['*'] || [];
-      const methodMiddleware = _middleware[context.req.method] || [];
+      const methodMiddleware = _middleware[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(
@@ -194,7 +199,16 @@ export function createRoute(config: HS.RouteConfig = {}): HS.Route {
         return routeContent;
       };
 
-      return executeMiddleware(context, [...globalMiddleware, ...methodMiddleware, methodHandler]);
+      // Run the route handler and any middleware
+      // If an error occurs, run the error handler if it exists
+      try {
+        return await executeMiddleware(context, [...globalMiddleware, ...methodMiddleware, methodHandler]);
+      } catch (e) {
+        if (_handlers['_ERROR']) {
+          return await (_handlers['_ERROR'](context) as Promise<Response>);
+        }
+        throw e;
+      }
     },
   };
 
@@ -327,11 +341,6 @@ export function getRunnableRoute(route: unknown, routeConfig?: HS.RouteConfig):
 
   const kind = typeof route;
 
-  // Plain function - wrap in createRoute()
-  if (kind === 'function') {
-    return createRoute(routeConfig).get(route as HS.RouteHandler);
-  }
-
   // Module - get default and use it
   // @ts-ignore
   if (kind === 'object' && 'default' in route) {
@@ -353,7 +362,7 @@ export function isRunnableRoute(route: unknown): boolean {
   }
 
   const obj = route as { _kind: string; fetch: (request: Request) => Promise<Response> };
-  return 'hsRoute' === obj?._kind && 'fetch' in obj;
+  return typeof obj?._kind === 'string' && 'fetch' in obj;
 }
 
 /**
@@ -363,7 +372,7 @@ export function isValidRoutePath(path: string): boolean {
   const isHiddenRoute = path.includes('/__');
   const isTestFile = path.includes('.test') || path.includes('.spec');
 
-  return !isHiddenRoute && !isTestFile;
+  return !isHiddenRoute && !isTestFile && Boolean(path);
 }
 
 /**

package/src/types.ts

@@ -1,3 +1,6 @@
+import { HSHtml } from '@hyperspan/html';
+import * as z from 'zod/v4';
+
 /**
  * Hyperspan Types
  */
@@ -94,7 +97,6 @@ export namespace Hyperspan {
 
   export interface Route {
     _kind: 'hsRoute';
-    _name: string | undefined;
     _config: Hyperspan.RouteConfig;
     _path(): string;
     _methods(): string[];
@@ -104,7 +106,29 @@ export namespace Hyperspan {
     patch: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
     delete: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
     options: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
+    errorHandler: (handler: Hyperspan.RouteHandler) => Hyperspan.Route;
     middleware: (middleware: Array<Hyperspan.MiddlewareFunction>) => Hyperspan.Route;
     fetch: (request: Request) => Promise<Response>;
   };
+
+  /**
+   * Action = Form + route handler
+   */
+  export type ActionResponse = HSHtml | void | null | Promise<HSHtml | void | null> | Response | Promise<Response>;
+  export type ActionProps<T extends z.ZodTypeAny> = { data?: Partial<z.infer<T>>; error?: z.ZodError | Error };
+  export type ActionFormHandler<T extends z.ZodTypeAny> = (
+    c: Context, props: ActionProps<T>
+  ) => ActionResponse;
+  export interface Action<T extends z.ZodTypeAny> {
+    _kind: 'hsAction';
+    _config: Hyperspan.RouteConfig;
+    _path(): string;
+    _form: null | ActionFormHandler<T>;
+    form(form: ActionFormHandler<T>): Action<T>;
+    render: (c: Context, props?: ActionProps<T>) => ActionResponse;
+    post: (handler: ActionFormHandler<T>) => Action<T>;
+    errorHandler: (handler: ActionFormHandler<T>) => Action<T>;
+    middleware: (middleware: Array<Hyperspan.MiddlewareFunction>) => Action<T>;
+    fetch: (request: Request) => Promise<Response>;
+  }
 }

package/src/utils.ts

@@ -1,5 +1,9 @@
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 
 export function assetHash(content: string): string {
   return createHash('md5').update(content).digest('hex');
+}
+
+export function randomHash(): string {
+  return createHash('md5').update(randomBytes(32).toString('hex')).digest('hex');
 }

package/tsconfig.json

@@ -1,7 +1,6 @@
 {
   "compileOnSave": true,
   "compilerOptions": {
-    "rootDir": "src",
     "outDir": "dist",
     "target": "es2019",
     "lib": ["ESNext", "dom", "dom.iterable"],
@@ -25,5 +24,6 @@
       "@hyperspan/html": ["../html/src/html.ts"]
     }
   },
+  "references": [{ "path": "../html" }],
   "exclude": ["node_modules", "__tests__", "*.test.ts"]
 }

package/src/clientjs/hyperspan-client.ts

@@ -1,224 +0,0 @@
-import { html } from '@hyperspan/html';
-import { Idiomorph } from './idiomorph';
-
-/**
- * Used for streaming content from the server to the client.
- */
-function htmlAsyncContentObserver() {
-  if (typeof MutationObserver != 'undefined') {
-    // Hyperspan - Async content loader
-    // Puts streamed content in its place immediately after it is added to the DOM
-    const asyncContentObserver = new MutationObserver((list) => {
-      const asyncContent = list
-        .map((mutation) =>
-          Array.from(mutation.addedNodes).find((node: any) => {
-            if (!node || !node?.id || typeof node.id !== 'string') {
-              return false;
-            }
-            return node.id?.startsWith('async_loading_') && node.id?.endsWith('_content');
-          })
-        )
-        .filter((node: any) => node);
-
-      asyncContent.forEach((templateEl: any) => {
-        try {
-          // Also observe for content inside the template content (shadow DOM is separate)
-          asyncContentObserver.observe(templateEl.content, { childList: true, subtree: true });
-
-          const slotId = templateEl.id.replace('_content', '');
-          const slotEl = document.getElementById(slotId);
-
-          if (slotEl) {
-            // Content AND slot are present - let's insert the content into the slot
-            // Ensure the content is fully done streaming in before inserting it into the slot
-            waitForContent(templateEl.content, (el2) => {
-              return Array.from(el2.childNodes).find(
-                (node) => node.nodeType === Node.COMMENT_NODE && node.nodeValue === 'end'
-              );
-            })
-              .then((endComment) => {
-                templateEl.content.removeChild(endComment);
-                const content = templateEl.content.cloneNode(true);
-                Idiomorph.morph(slotEl, content);
-                templateEl.parentNode.removeChild(templateEl);
-                lazyLoadScripts();
-              })
-              .catch(console.error);
-          } else {
-            // Slot is NOT present - wait for it to be added to the DOM so we can insert the content into it
-            waitForContent(document.body, () => {
-              return document.getElementById(slotId);
-            }).then((slotEl) => {
-              Idiomorph.morph(slotEl, templateEl.content.cloneNode(true));
-              lazyLoadScripts();
-            });
-          }
-        } catch (e) {
-          console.error(e);
-        }
-      });
-    });
-    asyncContentObserver.observe(document.body, { childList: true, subtree: true });
-  }
-}
-htmlAsyncContentObserver();
-
-/**
- * Wait until ALL of the content inside an element is present from streaming in.
- * Large chunks of content can sometimes take more than a single tick to write to DOM.
- */
-async function waitForContent(
-  el: HTMLElement,
-  waitFn: (
-    node: HTMLElement
-  ) => HTMLElement | HTMLTemplateElement | Node | ChildNode | null | undefined,
-  options: { timeoutMs?: number; intervalMs?: number } = { timeoutMs: 10000, intervalMs: 20 }
-): Promise<HTMLElement | HTMLTemplateElement | Node | ChildNode | null | undefined> {
-  return new Promise((resolve, reject) => {
-    let timeout: NodeJS.Timeout;
-    const interval = setInterval(() => {
-      const content = waitFn(el);
-      if (content) {
-        if (timeout) {
-          clearTimeout(timeout);
-        }
-        clearInterval(interval);
-        resolve(content);
-      }
-    }, options.intervalMs || 20);
-    timeout = setTimeout(() => {
-      clearInterval(interval);
-      reject(new Error(`[Hyperspan] Timeout waiting for end of streaming content ${el.id}`));
-    }, options.timeoutMs || 10000);
-  });
-}
-
-/**
- * Server action component to handle the client-side form submission and HTML replacement
- */
-class HSAction extends HTMLElement {
-  constructor() {
-    super();
-  }
-
-  connectedCallback() {
-    actionFormObserver.observe(this, { childList: true, subtree: true });
-    bindHSActionForm(this, this.querySelector('form') as HTMLFormElement);
-  }
-}
-window.customElements.define('hs-action', HSAction);
-const actionFormObserver = new MutationObserver((list) => {
-  list.forEach((mutation) => {
-    mutation.addedNodes.forEach((node) => {
-      if (node && ('closest' in node || node instanceof HTMLFormElement)) {
-        bindHSActionForm(
-          (node as HTMLElement).closest('hs-action') as HSAction,
-          node instanceof HTMLFormElement
-            ? node
-            : ((node as HTMLElement | HTMLFormElement).querySelector('form') as HTMLFormElement)
-        );
-      }
-    });
-  });
-});
-
-/**
- * Bind the form inside an hs-action element to the action URL and submit handler
- */
-function bindHSActionForm(hsActionElement: HSAction, form: HTMLFormElement) {
-  if (!hsActionElement || !form) {
-    return;
-  }
-
-  form.setAttribute('action', hsActionElement.getAttribute('url') || '');
-  const submitHandler = (e: Event) => {
-    e.preventDefault();
-    formSubmitToRoute(e, form as HTMLFormElement, {
-      afterResponse: () => bindHSActionForm(hsActionElement, form),
-    });
-    form.removeEventListener('submit', submitHandler);
-  };
-  form.addEventListener('submit', submitHandler);
-}
-
-/**
- * Submit form data to route and replace contents with response
- */
-type TFormSubmitOptons = { afterResponse: () => any };
-function formSubmitToRoute(e: Event, form: HTMLFormElement, opts: TFormSubmitOptons) {
-  const formData = new FormData(form);
-  const formUrl = form.getAttribute('action') || '';
-  const method = form.getAttribute('method')?.toUpperCase() || 'POST';
-  const headers = {
-    Accept: 'text/html',
-    'X-Request-Type': 'partial',
-  };
-
-  const hsActionTag = form.closest('hs-action');
-  const submitBtn = form.querySelector('button[type=submit],input[type=submit]');
-  if (submitBtn) {
-    submitBtn.setAttribute('disabled', 'disabled');
-  }
-
-  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);
-        }
-        return '';
-      }
-
-      return res.text();
-    })
-    .then((content: string) => {
-      // No content = DO NOTHING (redirect or something else happened)
-      if (!content) {
-        return;
-      }
-
-      const target = content.includes('<html') ? window.document.body : hsActionTag || form;
-
-      Idiomorph.morph(target, content);
-      opts.afterResponse && opts.afterResponse();
-      lazyLoadScripts();
-    });
-}
-
-/**
- * Intersection observer for lazy loading <script> tags
- */
-const lazyLoadScriptObserver = new IntersectionObserver(
-  (entries, observer) => {
-    entries
-      .filter((entry) => entry.isIntersecting)
-      .forEach((entry) => {
-        observer.unobserve(entry.target);
-        // @ts-ignore
-        if (entry.target.children[0]?.content) {
-          // @ts-ignore
-          entry.target.replaceWith(entry.target.children[0].content);
-        }
-      });
-  },
-  { rootMargin: '0px 0px -200px 0px' }
-);
-
-/**
- * Lazy load <script> tags in the current document
- */
-function lazyLoadScripts() {
-  document
-    .querySelectorAll('div[data-loading=lazy]')
-    .forEach((el) => lazyLoadScriptObserver.observe(el));
-}
-
-window.addEventListener('load', () => {
-  lazyLoadScripts();
-});
-
-// @ts-ignore
-window.html = html;