@hyperspan/framework 1.0.24 → 1.0.26

package/.claude/settings.local.json

@@ -1,7 +1,5 @@
 {
   "permissions": {
-    "allow": [
-      "Bash(bun test:*)"
-    ]
+    "allow": ["Bash(bun test:*)"]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "1.0.24",
+  "version": "1.0.26",
   "description": "Hyperspan Web Framework",
   "main": "src/server.ts",
   "types": "src/server.ts",

package/src/actions.test.ts

@@ -1,6 +1,7 @@
 import { test, expect, describe } from 'bun:test';
 import { createAction } from './actions';
-import { html, render, type HSHtml } from '@hyperspan/html';
+import { createRoute } from './server';
+import { html, render, placeholder, type HSHtml } from '@hyperspan/html';
 import { createContext } from './server';
 import * as z from 'zod';
 
@@ -11,18 +12,20 @@ describe('createAction', () => {
       schema: z.object({
         name: z.string().min(1, 'Name is required'),
       }),
-    }).form((c) => {
-      return html`
+    })
+      .form((c) => {
+        return html`
           <form>
             <input type="text" name="name" />
             <button type="submit">Submit</button>
           </form>
         `;
-    }).post(async (c, { data }) => {
-      return c.res.html(`
+      })
+      .post(async (c, { data }) => {
+        return c.res.html(`
           <p>Hello, ${data?.name}!</p>
         `);
-    });
+      });
 
     expect(action).toBeDefined();
     expect(action._kind).toBe('hsAction');
@@ -42,18 +45,20 @@ describe('createAction', () => {
   test('creates an action with a simple form and no schema that returns HTML on POST', async () => {
     const action = createAction({
       name: 'test',
-    }).form((c) => {
-      return html`
+    })
+      .form((c) => {
+        return html`
           <form>
             <input type="text" name="name" />
             <button type="submit">Submit</button>
           </form>
         `;
-    }).post(async (c, { data }) => {
-      return c.res.html(`
+      })
+      .post(async (c, { data }) => {
+        return c.res.html(`
           <p>Hello, ${data?.name}!</p>
         `);
-    });
+      });
 
     // Build form data
     const formData = new FormData();
@@ -74,16 +79,18 @@ describe('createAction', () => {
   test('returns HSHtml directly from POST handler', async () => {
     const action = createAction({
       name: 'test',
-    }).form((c) => {
-      return html`
+    })
+      .form((c) => {
+        return html`
           <form>
             <input type="text" name="name" />
             <button type="submit">Submit</button>
           </form>
         `;
-    }).post(async (c, { data }) => {
-      return html`<p>Hello, ${data?.name}!</p>`;
-    });
+      })
+      .post(async (c, { data }) => {
+        return html`<p>Hello, ${data?.name}!</p>`;
+      });
 
     const formData = new FormData();
     formData.append('name', 'Jane Doe');
@@ -102,22 +109,22 @@ describe('createAction', () => {
   test('errors thrown on POST handler provided by user are caught and rendered', async () => {
     const action = createAction({
       name: 'test',
-    }).form((c, { error }) => {
-      if (error) {
-        return html`
-          <p>Error: ${error.message}</p>
-        `;
-      }
+    })
+      .form((c, { error }) => {
+        if (error) {
+          return html` <p>Error: ${error.message}</p> `;
+        }
 
-      return html`
+        return html`
           <form>
             <input type="text" name="name" />
             <button type="submit">Submit</button>
           </form>
         `;
-    }).post(async (c, { data }) => {
-      throw new Error('Test error');
-    });
+      })
+      .post(async (c, { data }) => {
+        throw new Error('Test error');
+      });
 
     // Build form data
     const formData = new FormData();
@@ -144,20 +151,22 @@ describe('createAction', () => {
     const action = createAction({
       name: 'test',
       schema,
-    }).form((c, { data }) => {
-      return html`
+    })
+      .form((c, { data }) => {
+        return html`
           <form>
             <input type="text" name="name" />
             <input type="email" name="email" />
             <button type="submit">Submit</button>
           </form>
         `;
-    }).post(async (c, { data }) => {
-      return c.res.html(`
+      })
+      .post(async (c, { 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');
@@ -201,8 +210,9 @@ describe('createAction', () => {
     const action = createAction({
       name: 'test',
       schema,
-    }).form((c, { data, error }) => {
-      return html`
+    })
+      .form((c, { data, error }) => {
+        return html`
           <form>
             <input type="text" name="name" value="${data?.name || ''}" />
             ${error ? html`<div class="error">Validation failed</div>` : ''}
@@ -210,12 +220,13 @@ describe('createAction', () => {
             <button type="submit">Submit</button>
           </form>
         `;
-    }).post(async (c, { data }) => {
-      return c.res.html(`
+      })
+      .post(async (c, { 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();
@@ -248,8 +259,9 @@ describe('createAction', () => {
     const action = createAction({
       name: 'test',
       schema,
-    }).form((c, { data, error }) => {
-      return html`
+    })
+      .form((c, { data, error }) => {
+        return html`
           <form>
             <input type="text" name="name" value="${data?.name || ''}" />
             ${error ? html`<div class="error">Validation failed</div>` : ''}
@@ -257,17 +269,19 @@ describe('createAction', () => {
             <button type="submit">Submit</button>
           </form>
         `;
-    }).post(async (c, { data }) => {
-      return html`
-        <p>Hello, ${data?.name}!</p>
-        <p>Your email is ${data?.email}.</p>
-      `;
-    }).errorHandler(async (c, { data, error }) => {
-      return html`
-        <p>Caught error in custom error handler: ${error?.message}</p>
-        <p>Data: ${JSON.stringify(data)}</p>
-      `;
-    });
+      })
+      .post(async (c, { data }) => {
+        return html`
+          <p>Hello, ${data?.name}!</p>
+          <p>Your email is ${data?.email}.</p>
+        `;
+      })
+      .errorHandler(async (c, { data, error }) => {
+        return html`
+          <p>Caught error in custom error handler: ${error?.message}</p>
+          <p>Data: ${JSON.stringify(data)}</p>
+        `;
+      });
 
     // Test fetch method with invalid data (missing name, invalid email)
     const formData = new FormData();
@@ -288,5 +302,209 @@ describe('createAction', () => {
     // Should NOT contain the success message from post handler
     expect(responseText).not.toContain('Hello,');
   });
-});
 
+  describe('when streaming is disabled', () => {
+    test('action POST returns resolved placeholder content on the route', async () => {
+      const action = createAction({ name: 'async-placeholder-action-route' })
+        .form(() => html`<form><button type="submit">Submit</button></form>`)
+        .post(async () => {
+          return html`<div>
+            ${placeholder(
+              html`<span>Saving...</span>`,
+              (async () => {
+                await new Promise((resolve) => setTimeout(resolve, 10));
+                return html`<p>Action complete</p>`;
+              })()
+            )}
+          </div>`;
+        });
+
+      action._config.responseOptions = {
+        disableStreaming: () => true,
+      };
+
+      const request = new Request(`http://localhost:3000${action._path()}`, {
+        method: 'POST',
+        headers: {
+          Accept: 'text/html',
+          'X-Request-Type': 'partial',
+        },
+        body: new FormData(),
+      });
+
+      const response = await action.fetch(request);
+
+      expect(response).toBeInstanceOf(Response);
+      expect(response.status).toBe(200);
+      expect(response.headers.get('Transfer-Encoding')).not.toBe('chunked');
+
+      const text = await response.text();
+      expect(text).toContain('<p>Action complete</p>');
+      expect(text).not.toContain('Saving...');
+      expect(text).not.toContain('hs:loading');
+    });
+
+    test('action POST returns resolved placeholder content on the server', async () => {
+      const action = createAction({ name: 'async-placeholder-action-server' })
+        .form(() => html`<form><button type="submit">Submit</button></form>`)
+        .post(async () => {
+          return html`<div>
+            ${placeholder(
+              html`<span>Saving...</span>`,
+              (async () => {
+                await new Promise((resolve) => setTimeout(resolve, 10));
+                return html`<p>Action complete</p>`;
+              })()
+            )}
+          </div>`;
+        });
+
+      action._serverConfig = {
+        appDir: './app',
+        publicDir: './public',
+        plugins: [],
+        responseOptions: {
+          disableStreaming: () => true,
+        },
+      };
+
+      const request = new Request(`http://localhost:3000${action._path()}`, {
+        method: 'POST',
+        headers: {
+          Accept: 'text/html',
+          'X-Request-Type': 'partial',
+        },
+        body: new FormData(),
+      });
+
+      const response = await action.fetch(request);
+
+      expect(response).toBeInstanceOf(Response);
+      expect(response.status).toBe(200);
+      expect(response.headers.get('Transfer-Encoding')).not.toBe('chunked');
+
+      const text = await response.text();
+      expect(text).toContain('<p>Action complete</p>');
+      expect(text).not.toContain('Saving...');
+      expect(text).not.toContain('hs:loading');
+    });
+
+    test('action GET returns resolved placeholder content on the server', async () => {
+      const action = createAction({ name: 'async-placeholder-action-get' })
+        .form(() => {
+          return html`<div>
+            ${placeholder(html`<span>Loading...</span>`, Promise.resolve(html`<p>Form ready</p>`))}
+          </div>`;
+        })
+        .post(async () => html`<p>Action complete</p>`);
+
+      action._serverConfig = {
+        appDir: './app',
+        publicDir: './public',
+        plugins: [],
+        responseOptions: {
+          disableStreaming: () => true,
+        },
+      };
+
+      const response = await action.fetch(new Request(`http://localhost:3000${action._path()}`));
+
+      expect(response.status).toBe(200);
+      expect(response.headers.get('Transfer-Encoding')).not.toBe('chunked');
+
+      const text = await response.text();
+      expect(text).toContain('<p>Form ready</p>');
+      expect(text).not.toContain('Loading...');
+      expect(text).not.toContain('hs:loading');
+    });
+
+    test('embedded action.render() uses the parent page route streaming config, not the action server config', async () => {
+      const action = createAction({ name: 'embedded-action-streaming' })
+        .form(() => {
+          return html`<div>
+            ${placeholder(html`<span>Loading...</span>`, Promise.resolve(html`<p>Form ready</p>`))}
+          </div>`;
+        })
+        .post(async () => html`<p>Action complete</p>`);
+
+      action._serverConfig = {
+        appDir: './app',
+        publicDir: './public',
+        plugins: [],
+        responseOptions: {
+          disableStreaming: () => true,
+        },
+      };
+
+      const pageRoute = createRoute().get((c) => html`<main>${action.render(c)}</main>`);
+      let pageResponse = await pageRoute.fetch(new Request('http://localhost:3000/'));
+      expect(pageResponse.headers.get('Transfer-Encoding')).toBe('chunked');
+      expect(await pageResponse.text()).toContain('Loading...');
+
+      pageRoute._serverConfig = {
+        appDir: './app',
+        publicDir: './public',
+        plugins: [],
+        responseOptions: {
+          disableStreaming: () => true,
+        },
+      };
+
+      pageResponse = await pageRoute.fetch(new Request('http://localhost:3000/'));
+      expect(pageResponse.headers.get('Transfer-Encoding')).not.toBe('chunked');
+
+      const text = await pageResponse.text();
+      expect(text).toContain('<p>Form ready</p>');
+      expect(text).not.toContain('Loading...');
+    });
+
+    test('action validation error re-render returns resolved placeholder content', async () => {
+      const schema = z.object({ name: z.string().min(1, 'Name is required') });
+
+      const action = createAction({ name: 'async-placeholder-action-error', schema })
+        .form(
+          (c, { error }) => html`
+            <form>
+              <div>
+                ${placeholder(
+                  html`<span>Loading...</span>`,
+                  Promise.resolve(html`<p>Form ready</p>`)
+                )}
+              </div>
+              ${error ? html`<p class="error">${error.message}</p>` : ''}
+              <button type="submit">Submit</button>
+            </form>
+          `
+        )
+        .post(async () => html`<p>Action complete</p>`);
+
+      action._serverConfig = {
+        appDir: './app',
+        publicDir: './public',
+        plugins: [],
+        responseOptions: {
+          disableStreaming: () => true,
+        },
+      };
+
+      const response = await action.fetch(
+        new Request(`http://localhost:3000${action._path()}`, {
+          method: 'POST',
+          headers: {
+            Accept: 'text/html',
+            'X-Request-Type': 'partial',
+          },
+          body: new FormData(),
+        })
+      );
+
+      expect(response.status).toBe(400);
+      expect(response.headers.get('Transfer-Encoding')).not.toBe('chunked');
+
+      const text = await response.text();
+      expect(text).toContain('<p>Form ready</p>');
+      expect(text).not.toContain('Loading...');
+      expect(text).toContain('class="error"');
+    });
+  });
+});

package/src/actions.ts

@@ -8,7 +8,9 @@ import { validateBody, ZodValidationError } from './middleware';
 import { debug } from 'debug';
 
 const log = debug('hyperspan:actions');
-const actionsClientJS = await buildClientJS(import.meta.resolve('./client/_hs/hyperspan-actions.client'));
+const actionsClientJS = await buildClientJS(
+  import.meta.resolve('./client/_hs/hyperspan-actions.client')
+);
 
 /**
  * Actions = Form + route handler
@@ -23,59 +25,76 @@ 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<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> {
+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<S | undefined>['post']>[0] | null = null;
   let _errorHandler: Parameters<HS.Action<S | undefined>['errorHandler']>[0] | null = null;
 
+  function actionResponseOptions(status?: number) {
+    return {
+      ...(route._serverConfig?.responseOptions ?? {}),
+      ...(route._config?.responseOptions ?? {}),
+      ...(status !== undefined ? { status } : {}),
+    };
+  }
+
   const route = createRoute({ path, name })
     .get((c: HS.Context) => api.render(c))
-    .post(async (c: HS.Context) => {
-      if (!_handler) {
-        throw new Error('Action POST handler not set! Every action must have a POST handler.');
-      }
+    .post(
+      async (c: HS.Context) => {
+        if (!_handler) {
+          throw new Error('Action POST handler not set! Every action must have a POST handler.');
+        }
 
-      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 });
+        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 });
 
-      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');
+        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;
-    }, { middleware: schema ? [validateBody(schema)] : [] })
+        return response;
+      },
+      { middleware: schema ? [validateBody(schema as unknown as z.ZodObject | z.ZodAny)] : [] }
+    )
     /**
      * Custom error handler for the action since validateBody() throws a HTTPResponseException
      */
     .errorHandler(async (c: HS.Context, err: HTTPResponseException) => {
-      const data = c.vars.body as HS.InferActionData<S> || formDataToJSON(await c.req.formData()) || {};
-      const error = err._error as ZodValidationError || err;
+      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)
       c.res.status = err._error ? 400 : 500;
 
       log('errorHandler', { data, error });
 
-      return await returnHTMLResponse(c, () => {
-        return _errorHandler ? _errorHandler(c, { data, error }) : api.render(c, { data, error });
-      }, { status: 400 });
+      return await returnHTMLResponse(
+        c,
+        () => {
+          return _errorHandler ? _errorHandler(c, { data, error }) : api.render(c, { data, error });
+        },
+        actionResponseOptions(c.res.status ?? 400)
+      );
     });
 
   // Set the name of the action for the route
@@ -84,6 +103,12 @@ export function createAction<S extends z.ZodType>(
   const api: HS.Action<S | undefined> = {
     _kind: 'hsAction',
     _config: route._config,
+    get _serverConfig() {
+      return route._serverConfig;
+    },
+    set _serverConfig(config: HS.Config | undefined) {
+      route._serverConfig = config;
+    },
     _path() {
       return path;
     },
@@ -111,7 +136,10 @@ export function createAction<S extends z.ZodType>(
      */
     render(c, props) {
       const formContent = api._form ? api._form(c, props || {}) : null;
-      return formContent ? html`<hs-action url="${this._path()}">${formContent}</hs-action>${actionsClientJS.renderScriptTag()}` : null;
+      return formContent
+        ? html`<hs-action url="${this._path()}">${formContent}</hs-action
+            >${actionsClientJS.renderScriptTag()}`
+        : null;
     },
     errorHandler(handler) {
       _errorHandler = handler;
@@ -129,4 +157,4 @@ export function createAction<S extends z.ZodType>(
   };
 
   return api;
-}
+}