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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.3",
   "description": "Hyperspan Web Framework",
   "main": "src/server.ts",
   "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,226 @@
+import { html, HSHtml } from '@hyperspan/html';
+import { createRoute, parsePath, returnHTMLResponse } from './server';
+import * as z from 'zod/v4';
+import type { Hyperspan as HS } from './types';
+import { assetHash } from './utils';
+
+/**
+ * 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
+ */;
+type HSActionResponse = HSHtml | void | null | Promise<HSHtml | void | null> | Response | Promise<Response>;
+export type HSFormHandler<T extends z.ZodTypeAny> = (
+  c: HS.Context,
+  { data, error }: { data?: Partial<z.infer<T>>; error?: z.ZodError | Error }
+) => HSActionResponse;
+export interface HSAction<T extends z.ZodTypeAny> {
+  _kind: 'hsAction';
+  _name: string;
+  _path(): string;
+  _form: null | HSFormHandler<T>;
+  form(form: HSFormHandler<T>): HSAction<T>;
+  post(
+    handler: (
+      c: HS.Context,
+      { data }: { data?: Partial<z.infer<T>> }
+    ) => HSActionResponse
+  ): HSAction<T>;
+  error(
+    handler: (
+      c: HS.Context,
+      { data, error }: { data?: Partial<z.infer<T>>; error?: z.ZodError | Error }
+    ) => HSActionResponse
+  ): HSAction<T>;
+  render(
+    c: HS.Context,
+    props?: { data?: Partial<z.infer<T>>; error?: z.ZodError | Error }
+  ): HSActionResponse;
+  middleware: (middleware: Array<HS.MiddlewareFunction>) => HSAction<T>;
+  fetch(request: Request): Response | Promise<Response>;
+}
+
+export function createAction<T extends z.ZodTypeAny>(params: { name: string; schema?: T }) {
+  const { name, schema } = params;
+
+  let _handler: Parameters<HSAction<T>['post']>[0] | null = null;
+  let _errorHandler: Parameters<HSAction<T>['error']>[0] | null = null;
+
+  const route = createRoute()
+    .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: HSAction<T> = {
+    _kind: 'hsAction',
+    _name: name,
+    _path() {
+      return `/__actions/${assetHash(name)}`;
+    },
+    _form: null,
+    /**
+     * Form to render
+     * This will be wrapped in a <hs-action> web component and submitted via fetch()
+     */
+    form(form: HSFormHandler<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;
+    },
+    /**
+     * 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) {
+      route.middleware(middleware);
+      return api;
+    },
+    /**
+     * Get form renderer method
+     */
+    render(c: HS.Context, props?: { data?: Partial<z.infer<T>>; error?: z.ZodError | Error }) {
+      const formContent = api._form ? api._form(c, props || {}) : null;
+      return formContent ? html`<hs-action url="${this._path()}">${formContent}</hs-action>` : null;
+    },
+    /**
+     * Run action route handler
+     */
+    fetch(request: Request) {
+      return route.fetch(request);
+    },
+  };
+
+  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/js.ts

@@ -1,7 +1,6 @@
 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';
 export const JS_IMPORT_MAP = new Map<string, string>();

package/src/plugins.ts

@@ -65,7 +65,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';
+import { functionToString } from '@hyperspan/framework/client/js';
 
 // Original file contents
 ${contents}

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

@@ -2,10 +2,10 @@ import { HSHtml, html, isHSHtml, renderStream, renderAsync, render } from '@hype
 import { executeMiddleware } from './middleware';
 import type { Hyperspan as HS } from './types';
 import { clientJSPlugin } from './plugins';
+import { CSS_ROUTE_MAP } from './client/css';
 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 +38,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 +53,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 } }),
@@ -145,12 +148,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(

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"]
 }