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

package/src/types.ts

@@ -1,3 +1,6 @@
+import { HSHtml } from '@hyperspan/html';
+import * as z from 'zod/v4';
+
 /**
  * Hyperspan Types
  */
@@ -26,6 +29,26 @@ export namespace Hyperspan {
     afterRoutesAdded?: (server: Hyperspan.Server) => void;
   };
 
+  export type CookieOptions = {
+    maxAge?: number;
+    domain?: string;
+    path?: string;
+    expires?: Date;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'lax' | 'strict' | true;
+  };
+  export type Cookies = {
+    _req: Request;
+    _responseHeaders: Headers | undefined;
+    _parsedCookies: Record<string, any>;
+    _encrypt: ((str: string) => string) | undefined;
+    _decrypt: ((str: string) => string) | undefined;
+    get: (name: string) => string | undefined;
+    set: (name: string, value: string, options?: CookieOptions) => void;
+    delete: (name: string) => void;
+  }
+
   export interface Context {
     vars: Record<string, any>;
     route: {
@@ -39,9 +62,14 @@ export namespace Hyperspan {
       method: string; // Always uppercase
       headers: Headers; // Case-insensitive
       query: URLSearchParams;
-      body: any;
+      cookies: Hyperspan.Cookies;
+      text: () => Promise<string>;
+      json<T = unknown>(): Promise<T>;
+      formData(): Promise<FormData>;
+      urlencoded(): Promise<URLSearchParams>;
     };
     res: {
+      cookies: Hyperspan.Cookies;
       headers: Headers; // Headers to merge with final outgoing response
       html: (html: string, options?: { status?: number; headers?: Record<string, string> }) => Response
       json: (json: any, options?: { status?: number; headers?: Record<string, string> }) => Response;
@@ -49,6 +77,7 @@ export namespace Hyperspan {
       redirect: (url: string, options?: { status?: number; headers?: Record<string, string> }) => Response;
       error: (error: Error, options?: { status?: number; headers?: Record<string, string> }) => Response;
       notFound: (options?: { status?: number; headers?: Record<string, string> }) => Response;
+      merge: (response: Response) => Response;
       raw: Response;
     };
   };
@@ -94,7 +123,6 @@ export namespace Hyperspan {
 
   export interface Route {
     _kind: 'hsRoute';
-    _name: string | undefined;
     _config: Hyperspan.RouteConfig;
     _path(): string;
     _methods(): string[];
@@ -104,7 +132,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.test.ts

@@ -0,0 +1,196 @@
+import { test, expect, describe } from 'bun:test';
+import { formDataToJSON, parsePath } from './utils';
+
+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('parsePath', () => {
+  test('parsePath returns root path for empty string', () => {
+    const result = parsePath('');
+    expect(result.path).toBe('/');
+    expect(result.params).toEqual([]);
+  });
+
+  test('parsePath handles simple path', () => {
+    const result = parsePath('users');
+    expect(result.path).toBe('/users');
+    expect(result.params).toEqual([]);
+  });
+
+  test('parsePath removes leading slash', () => {
+    const result = parsePath('/users');
+    expect(result.path).toBe('/users');
+    expect(result.params).toEqual([]);
+  });
+
+  test('parsePath removes trailing slash', () => {
+    const result = parsePath('users/');
+    expect(result.path).toBe('/users');
+    expect(result.params).toEqual([]);
+  });
+
+  test('parsePath removes both leading and trailing slashes', () => {
+    const result = parsePath('/users/');
+    expect(result.path).toBe('/users');
+    expect(result.params).toEqual([]);
+  });
+
+  test('parsePath handles nested paths', () => {
+    const result = parsePath('users/posts');
+    expect(result.path).toBe('/users/posts');
+    expect(result.params).toEqual([]);
+  });
+
+  test('parsePath lowercases path segments', () => {
+    const result = parsePath('Users/Posts');
+    expect(result.path).toBe('/users/posts');
+    expect(result.params).toEqual([]);
+  });
+
+  test('parsePath removes .ts extension', () => {
+    const result = parsePath('users.ts');
+    expect(result.path).toBe('/users');
+    expect(result.params).toEqual([]);
+  });
+
+  test('parsePath removes .js extension', () => {
+    const result = parsePath('users.js');
+    expect(result.path).toBe('/users');
+    expect(result.params).toEqual([]);
+  });
+
+  test('parsePath removes index from path', () => {
+    const result = parsePath('index');
+    expect(result.path).toBe('/');
+    expect(result.params).toEqual([]);
+  });
+
+  test('parsePath removes index.ts from path', () => {
+    const result = parsePath('index.ts');
+    expect(result.path).toBe('/');
+    expect(result.params).toEqual([]);
+  });
+
+  test('parsePath handles dynamic param with brackets', () => {
+    const result = parsePath('users/[userId]');
+    expect(result.path).toBe('/users/:userId');
+    expect(result.params).toEqual(['userId']);
+  });
+
+  test('parsePath handles multiple dynamic params', () => {
+    const result = parsePath('users/[userId]/posts/[postId]');
+    expect(result.path).toBe('/users/:userId/posts/:postId');
+    expect(result.params).toEqual(['userId', 'postId']);
+  });
+
+  test('parsePath handles catch-all param with spread', () => {
+    const result = parsePath('users/[...slug]');
+    expect(result.path).toBe('/users/*');
+    expect(result.params).toEqual(['slug']);
+  });
+
+  test('parsePath handles catch-all param at root', () => {
+    const result = parsePath('[...slug]');
+    expect(result.path).toBe('/*');
+    expect(result.params).toEqual(['slug']);
+  });
+
+  test('parsePath preserves param names in path but converts format', () => {
+    const result = parsePath('users/[userId]');
+    expect(result.path).toBe('/users/:userId');
+    expect(result.params).toEqual(['userId']);
+    // Param segment should not be lowercased
+    expect(result.path).toContain(':userId');
+  });
+
+  test('parsePath handles complex nested path with params', () => {
+    const result = parsePath('/api/users/[userId]/posts/[postId]/comments');
+    expect(result.path).toBe('/api/users/:userId/posts/:postId/comments');
+    expect(result.params).toEqual(['userId', 'postId']);
+  });
+
+  test('parsePath handles path with dots in param name', () => {
+    const result = parsePath('users/[user.id]');
+    expect(result.path).toBe('/users/:user.id');
+    expect(result.params).toEqual(['user.id']);
+  });
+
+  test('parsePath handles mixed case with params', () => {
+    const result = parsePath('Users/[UserId]/Posts');
+    expect(result.path).toBe('/users/:UserId/posts');
+    expect(result.params).toEqual(['UserId']);
+    // Non-param segments should be lowercased, but param name preserved
+    expect(result.path).toContain('/users/');
+    expect(result.path).toContain('/posts');
+  });
+
+  test('parsePath handles file path format', () => {
+    const result = parsePath('/routes/users/[userId].ts');
+    expect(result.path).toBe('/routes/users/:userId');
+    expect(result.params).toEqual(['userId']);
+  });
+});
+

package/src/utils.ts

@@ -1,5 +1,139 @@
-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');
+}
+
+
+/**
+ * Normalize URL path
+ * Removes trailing slash and lowercases path
+ */
+const ROUTE_SEGMENT_REGEX = /(\[[a-zA-Z_\.]+\])/g;
+export function parsePath(urlPath: string): { path: string, params: string[] } {
+  const params: string[] = [];
+  urlPath = urlPath.replace('index', '').replace('.ts', '').replace('.js', '');
+
+  if (urlPath.startsWith('/')) {
+    urlPath = urlPath.substring(1);
+  }
+
+  if (urlPath.endsWith('/')) {
+    urlPath = urlPath.substring(0, urlPath.length - 1);
+  }
+
+  if (!urlPath) {
+    return { path: '/', params: [] };
+  }
+
+  // Dynamic params
+  if (ROUTE_SEGMENT_REGEX.test(urlPath)) {
+    urlPath = urlPath.replace(ROUTE_SEGMENT_REGEX, (match: string) => {
+      const paramName = match.replace(/[^a-zA-Z_\.]+/g, '').replace('...', '');
+      params.push(paramName);
+
+      if (match.includes('...')) {
+        return '*';
+      } else {
+        return ':' + paramName;
+      }
+    });
+  }
+
+  // Only lowercase non-param segments (do not lowercase after ':')
+  return {
+    path: (
+      '/' +
+      urlPath
+        .split('/')
+        .map((segment) =>
+          segment.startsWith(':') || segment === '*' ? segment : segment.toLowerCase()
+        )
+        .join('/')
+    ),
+    params,
+  };
+}
+
+/**
+ * Is valid route path to add to server?
+ */
+export function isValidRoutePath(path: string): boolean {
+  const isHiddenRoute = path.includes('/__');
+  const isTestFile = path.includes('.test') || path.includes('.spec');
+
+  return !isHiddenRoute && !isTestFile && Boolean(path);
+}
+
+/**
+ * Return JSON data structure for a given FormData or URLSearchParams object
+ * Accounts for array fields (e.g. name="options[]" or <select multiple>)
+ *
+ * @link https://stackoverflow.com/a/75406413
+ */
+export function formDataToJSON(formData: FormData | URLSearchParams): 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/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;