@hyperspan/framework 0.5.4 → 1.0.0-alpha.0

package/src/actions.test.ts

@@ -1,106 +0,0 @@
-import { z } from 'zod/v4';
-import { unstable__createAction } from './actions';
-import { describe, it, expect } from 'bun:test';
-import { html, render, type HSHtml } from '@hyperspan/html';
-import type { THSContext } from './server';
-
-describe('createAction', () => {
-  const formWithNameOnly = (c: THSContext, { data }: { data?: { name: string } }) => {
-    return html`
-      <form>
-        <p>
-          Name:
-          <input type="text" name="name" value="${data?.name || ''}" />
-        </p>
-        <button type="submit">Submit</button>
-      </form>
-    `;
-  };
-
-  describe('with form content', () => {
-    it('should create an action with a form that renders provided data', async () => {
-      const schema = z.object({
-        name: z.string(),
-      });
-      const action = unstable__createAction(schema, formWithNameOnly);
-      const mockContext = {
-        req: {
-          method: 'POST',
-          formData: async () => {
-            const formData = new FormData();
-            formData.append('name', 'John');
-            return formData;
-          },
-        },
-      } as THSContext;
-
-      const formResponse = render(action.render(mockContext, { data: { name: 'John' } }) as HSHtml);
-      expect(formResponse).toContain('value="John"');
-    });
-  });
-
-  describe('when data is valid', () => {
-    it('should run the handler and return the result', async () => {
-      const schema = z.object({
-        name: z.string().nonempty(),
-      });
-      const action = unstable__createAction(schema, formWithNameOnly)
-        .post((c, { data }) => {
-          return html`<div>Thanks for submitting the form, ${data?.name}!</div>`;
-        })
-        .error((c, { error }) => {
-          return html`<div>There was an error! ${error?.message}</div>`;
-        });
-
-      // Mock context to run action
-      const mockContext = {
-        req: {
-          method: 'POST',
-          formData: async () => {
-            const formData = new FormData();
-            formData.append('name', 'John');
-            return formData;
-          },
-        },
-      } as THSContext;
-
-      const response = await action.run(mockContext);
-
-      const formResponse = render(response as HSHtml);
-      expect(formResponse).toContain('Thanks for submitting the form, John!');
-    });
-  });
-
-  describe.skip('when data is invalid', () => {
-    it('should return the content of the form with error', async () => {
-      const schema = z.object({
-        name: z.string().nonempty(),
-      });
-      const action = unstable__createAction(schema)
-        .form(formWithNameOnly)
-        .post((c, { data }) => {
-          return html`<div>Thanks for submitting the form, ${data?.name}!</div>`;
-        })
-        .error((c, { error }) => {
-          return html`<div>There was an error! ${error?.message}</div>`;
-        });
-
-      // Mock context to run action
-      const mockContext = {
-        req: {
-          method: 'POST',
-          formData: async () => {
-            const formData = new FormData();
-            formData.append('name', ''); // No name = error
-            return formData;
-          },
-        },
-      } as THSContext;
-
-      const response = await action.run(mockContext);
-
-      const formResponse = render(response as HSHtml);
-      expect(formResponse).toContain('There was an error!');
-    });
-  });
-});

package/src/actions.ts

@@ -1,256 +0,0 @@
-import { html, HSHtml } from '@hyperspan/html';
-import * as z from 'zod/v4';
-import { HTTPException } from 'hono/http-exception';
-import { assetHash } from './assets';
-import { IS_PROD, returnHTMLResponse, type THSContext, type THSResponseTypes } from './server';
-import type { MiddlewareHandler } from 'hono';
-import type { HandlerResponse, Next, TypedResponse } from 'hono/types';
-
-/**
- * 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 type TActionResponse =
-  | THSResponseTypes
-  | HandlerResponse<any>
-  | TypedResponse<any, any, any>;
-export interface HSAction<T extends z.ZodTypeAny> {
-  _kind: string;
-  _route: string;
-  _form: Parameters<HSAction<T>['form']>[0];
-  form(
-    renderForm: (
-      c: THSContext,
-      { data, error }: { data?: Partial<z.infer<T>>; error?: z.ZodError | Error }
-    ) => HSHtml | void | null | Promise<HSHtml | void | null>
-  ): HSAction<T>;
-  post(
-    handler: (
-      c: THSContext,
-      { data }: { data?: Partial<z.infer<T>> }
-    ) => TActionResponse | Promise<TActionResponse>
-  ): HSAction<T>;
-  error(
-    handler: (
-      c: THSContext,
-      { data, error }: { data?: Partial<z.infer<T>>; error?: z.ZodError | Error }
-    ) => TActionResponse
-  ): HSAction<T>;
-  render(
-    c: THSContext,
-    props?: { data?: Partial<z.infer<T>>; error?: z.ZodError | Error }
-  ): TActionResponse;
-  run(c: THSContext): TActionResponse | Promise<TActionResponse>;
-  middleware: (
-    middleware: Array<
-      | MiddlewareHandler
-      | ((context: THSContext) => TActionResponse | Promise<TActionResponse> | void | Promise<void>)
-    >
-  ) => HSAction<T>;
-  _getRouteHandlers: () => Array<
-    | MiddlewareHandler
-    | ((context: THSContext, next: Next) => TActionResponse | Promise<TActionResponse>)
-    | ((context: THSContext) => TActionResponse | Promise<TActionResponse>)
-  >;
-}
-
-export function unstable__createAction<T extends z.ZodTypeAny>(
-  schema: T | null = null,
-  form: Parameters<HSAction<T>['form']>[0]
-) {
-  let _handler: Parameters<HSAction<T>['post']>[0] | null = null,
-    _form: Parameters<HSAction<T>['form']>[0] = form,
-    _errorHandler: Parameters<HSAction<T>['error']>[0] | null = null,
-    _middleware: Array<
-      | MiddlewareHandler
-      | ((context: THSContext, next: Next) => TActionResponse | Promise<TActionResponse>)
-      | ((context: THSContext) => TActionResponse | Promise<TActionResponse>)
-    > = [];
-
-  const api: HSAction<T> = {
-    _kind: 'hsAction',
-    _route: `/__actions/${assetHash(_form.toString())}`,
-    _form,
-    form(renderForm) {
-      _form = renderForm;
-      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) {
-      _middleware = middleware;
-      return api;
-    },
-    /**
-     * Get form renderer method
-     */
-    render(c: THSContext, formState?: { data?: Partial<z.infer<T>>; error?: z.ZodError | Error }) {
-      const form = _form ? _form(c, formState || {}) : null;
-      return form ? html`<hs-action url="${this._route}">${form}</hs-action>` : null;
-    },
-
-    _getRouteHandlers() {
-      return [
-        ..._middleware,
-        async (c: THSContext) => {
-          const response = await returnHTMLResponse(c, () => api.run(c));
-
-          // 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;
-        },
-      ];
-    },
-
-    /**
-     * Run action
-     *
-     * Returns result from form processing if successful
-     * Re-renders form with data and error information otherwise
-     */
-    async run(c) {
-      const method = c.req.method;
-
-      if (method === 'GET') {
-        return await api.render(c);
-      }
-
-      if (method !== 'POST') {
-        throw new HTTPException(405, { message: 'Actions only support GET and POST requests' });
-      }
-
-      const formData = await c.req.formData();
-      const jsonData = unstable__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.');
-        }
-
-        return await _handler(c, { data });
-      } catch (e) {
-        error = e as Error | z.ZodError;
-        !IS_PROD && console.error(error);
-      }
-
-      if (error && _errorHandler) {
-        // @ts-ignore
-        return await returnHTMLResponse(c, () => _errorHandler(c, { data, error }), {
-          status: 400,
-        });
-      }
-
-      return await returnHTMLResponse(c, () => api.render(c, { data, error }), { status: 400 });
-    },
-  };
-
-  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 unstable__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/assets.ts

@@ -1,176 +0,0 @@
-import { html } from '@hyperspan/html';
-import { createHash } from 'node:crypto';
-import { readdir } from 'node:fs/promises';
-import { resolve } from 'node:path';
-
-export type THSIslandOptions = {
-  ssr?: boolean;
-  loading?: 'lazy' | undefined;
-};
-
-const IS_PROD = process.env.NODE_ENV === 'production';
-const PWD = import.meta.dir;
-
-export const CLIENTJS_PUBLIC_PATH = '/_hs/js';
-export const ISLAND_PUBLIC_PATH = '/_hs/js/islands';
-export const clientImportMap = new Map<string, string>();
-
-/**
- * Build client JS for end users (minimal JS for Hyperspan to work)
- */
-export const clientJSFiles = new Map<string, { src: string; type?: string }>();
-export async function buildClientJS() {
-  const sourceFile = resolve(PWD, '../', './src/clientjs/hyperspan-client.ts');
-  const output = await Bun.build({
-    entrypoints: [sourceFile],
-    outdir: `./public/${CLIENTJS_PUBLIC_PATH}`,
-    naming: IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined,
-    minify: IS_PROD,
-  });
-
-  const jsFile = output.outputs[0].path.split('/').reverse()[0];
-
-  clientJSFiles.set('_hs', { src: `${CLIENTJS_PUBLIC_PATH}/${jsFile}` });
-}
-
-/**
- * Render a client JS module as a script tag
- */
-export function renderClientJS<T>(module: T, loadScript?: ((module: T) => void) | string) {
-  // @ts-ignore
-  if (!module.__CLIENT_JS) {
-    throw new Error(
-      `[Hyperspan] Client JS was not loaded by Hyperspan! Ensure the filename ends with .client.ts to use this render method.`
-    );
-  }
-
-  return html.raw(
-    // @ts-ignore
-    module.__CLIENT_JS.renderScriptTag({
-      loadScript: loadScript
-        ? typeof loadScript === 'string'
-          ? loadScript
-          : functionToString(loadScript)
-        : undefined,
-    })
-  );
-}
-
-/**
- * Convert a function to a string (results in loss of context!)
- * Handles named, async, and arrow functions
- */
-export function functionToString(fn: any) {
-  let str = fn.toString().trim();
-
-  // Ensure consistent output & handle async
-  if (!str.includes('function ')) {
-    if (str.includes('async ')) {
-      str = 'async function ' + str.replace('async ', '');
-    } else {
-      str = 'function ' + str;
-    }
-  }
-
-  const lines = str.split('\n');
-  const firstLine = lines[0];
-  const lastLine = lines[lines.length - 1];
-
-  // Arrow function conversion
-  if (!lastLine?.includes('}')) {
-    return str.replace('=> ', '{ return ') + '; }';
-  }
-
-  // Cleanup arrow function
-  if (firstLine.includes('=>')) {
-    return str.replace('=> ', '');
-  }
-
-  return str;
-}
-
-/**
- * Find client CSS file built for end users
- * @TODO: Build this in code here vs. relying on tailwindcss CLI tool from package scripts
- */
-export const clientCSSFiles = new Map<string, string>();
-export async function buildClientCSS() {
-  if (clientCSSFiles.has('_hs')) {
-    return clientCSSFiles.get('_hs');
-  }
-
-  // Find file already built from tailwindcss CLI
-  const cssDir = './public/_hs/css/';
-  const cssFiles = await readdir(cssDir);
-  let foundCSSFile: string = '';
-
-  for (const file of cssFiles) {
-    // Only looking for CSS files
-    if (!file.endsWith('.css')) {
-      continue;
-    }
-
-    foundCSSFile = file.replace(cssDir, '');
-    clientCSSFiles.set('_hs', foundCSSFile);
-    break;
-  }
-
-  if (!foundCSSFile) {
-    console.log(`Unable to build CSS files from ${cssDir}`);
-  }
-}
-
-/**
- * Output HTML style tag for Hyperspan app
- */
-export function hyperspanStyleTags() {
-  const cssFiles = Array.from(clientCSSFiles.entries());
-  return html`${cssFiles.map(
-    ([_, file]) => html`<link rel="stylesheet" href="/_hs/css/${file}" />`
-  )}`;
-}
-
-/**
- * Output HTML script tag for Hyperspan app
- * Required for functioning streaming so content can pop into place properly once ready
- */
-export function hyperspanScriptTags() {
-  const jsFiles = Array.from(clientJSFiles.entries());
-
-  return html`
-    <script type="importmap">
-      {"imports": ${Object.fromEntries(clientImportMap)}}
-    </script>
-    ${jsFiles.map(
-      ([key, file]) =>
-        html`<script
-          id="js-${key}"
-          type="${file.type || 'text/javascript'}"
-          src="${file.src}"
-        ></script>`
-    )}
-  `;
-}
-
-export function assetHash(content: string): string {
-  return createHash('md5').update(content).digest('hex');
-}
-
-/**
- * Island defaults
- */
-export const ISLAND_DEFAULTS: () => THSIslandOptions = () => ({
-  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 createServer() 'islandPlugins' config?`
-  );
-}