@hyperspan/framework 1.0.0-alpha.12 → 1.0.0-alpha.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspan/framework",
-  "version": "1.0.0-alpha.12",
+  "version": "1.0.0-alpha.14",
   "description": "Hyperspan Web Framework",
   "main": "src/server.ts",
   "types": "src/server.ts",
@@ -37,10 +37,6 @@
       "types": "./src/client/js.ts",
       "default": "./src/client/js.ts"
     },
-    "./plugins": {
-      "types": "./src/plugins.ts",
-      "default": "./src/plugins.ts"
-    },
     "./actions": {
       "types": "./src/actions.ts",
       "default": "./src/actions.ts"

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

@@ -1,68 +1,5 @@
-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.
@@ -91,4 +28,39 @@ async function waitForContent(
       reject(new Error(`[Hyperspan] Timeout waiting for end of streaming content ${el.id}`));
     }, options.timeoutMs || 10000);
   });
-}
+}
+
+function renderStreamChunk(chunk: { id: string }) {
+  const slotId = chunk.id;
+  const slotEl = document.getElementById(slotId);
+  const templateEl = document.getElementById(`${slotId}_content`) as HTMLTemplateElement;
+
+  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 as unknown as HTMLElement, (el2) => {
+      return Array.from(el2.childNodes).find(
+        (node) => node.nodeType === Node.COMMENT_NODE && node.nodeValue === 'end'
+      );
+    })
+      .then((endComment) => {
+        templateEl.content.removeChild(endComment as Node);
+        const content = templateEl.content.cloneNode(true);
+        slotEl.replaceWith(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) => {
+      (slotEl as HTMLElement)?.replaceWith(templateEl.content.cloneNode(true));
+      lazyLoadScripts();
+    });
+  }
+}
+
+// @ts-ignore
+window._hscc = renderStreamChunk;

package/src/client/js.test.ts

@@ -0,0 +1,200 @@
+import { test, expect, describe } from 'bun:test';
+import { functionToString } from './js';
+
+describe('functionToString', () => {
+  describe('named functions', () => {
+    test('converts named function to string', () => {
+      function myFunction() {
+        return 'hello';
+      }
+
+      const result = functionToString(myFunction);
+      expect(result).toContain('function');
+      expect(result).toContain('myFunction');
+      expect(result).toContain("return 'hello'");
+    });
+
+    test('converts named function with parameters', () => {
+      function add(a: number, b: number) {
+        return a + b;
+      }
+
+      const result = functionToString(add);
+      expect(result).toContain('function');
+      expect(result).toContain('add');
+      expect(result).toContain('a');
+      expect(result).toContain('b');
+    });
+
+    test('converts named async function', () => {
+      async function fetchData() {
+        const response = await fetch('/api/data');
+        return response.json();
+      }
+
+      const result = functionToString(fetchData);
+      expect(result).toContain('async function');
+      expect(result).toContain('fetchData');
+      expect(result).toContain('await');
+    });
+  });
+
+  describe('anonymous functions', () => {
+    test('converts anonymous function to string', () => {
+      const fn = function () {
+        return 'anonymous';
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain("return 'anonymous'");
+    });
+
+    test('converts anonymous function with parameters', () => {
+      const fn = function (x: number, y: number) {
+        return x * y;
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain('x');
+      expect(result).toContain('y');
+    });
+
+    test('converts anonymous async function', () => {
+      const fn = async function () {
+        await new Promise(resolve => setTimeout(resolve, 100));
+        return 'done';
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('async function');
+      expect(result).toContain('await');
+    });
+  });
+
+  describe('arrow functions', () => {
+    test('converts single-line arrow function without braces', () => {
+      const fn = (x: number) => x * 2;
+
+      const result = functionToString(fn);
+      expect(result).toContain('function(x) { return x * 2; }');
+    });
+
+    test('converts single-line arrow function with single parameter', () => {
+      const fn = (name: string) => `Hello, ${name}!`;
+
+      const result = functionToString(fn);
+      expect(result).toContain('function(name) { return `Hello, ${name}!`; }');
+    });
+
+    test('converts single-line arrow function with multiple parameters', () => {
+      const fn = (a: number, b: number) => a + b;
+
+      const result = functionToString(fn);
+      expect(result).toContain('function(a, b) { return a + b; }');
+    });
+
+    test('converts arrow function with braces', () => {
+      const fn = (x: number) => {
+        const doubled = x * 2;
+        return doubled;
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain('x');
+      expect(result).toContain('doubled');
+    });
+
+    test('converts multi-line arrow function', () => {
+      const fn = (items: string[]) => {
+        const filtered = items.filter(item => item.length > 0);
+        return filtered.map(item => item.toUpperCase());
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain('items');
+      expect(result).toContain('filtered');
+    });
+
+    test('converts async arrow function without braces', () => {
+      const fn = async (id: number) => await fetch(`/api/${id}`);
+
+      const result = functionToString(fn);
+      expect(result).toContain('async function');
+      expect(result).toContain('id');
+      expect(result).toContain('await');
+    });
+
+    test('converts async arrow function with braces', () => {
+      const fn = async (id: number) => {
+        const response = await fetch(`/api/${id}`);
+        return response.json();
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('async function');
+      expect(result).toContain('id');
+      expect(result).toContain('await');
+    });
+
+    test('converts arrow function with no parameters', () => {
+      const fn = () => 'no params';
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain("return 'no params'");
+    });
+
+    test('converts arrow function with complex expression', () => {
+      const fn = (obj: { x: number; y: number }) => obj.x + obj.y;
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain('return');
+      expect(result).toContain('obj.x + obj.y');
+    });
+  });
+
+  describe('edge cases', () => {
+    test('handles function with whitespace', () => {
+      const fn = function () {
+        return 'test';
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain("return 'test'");
+    });
+
+    test('handles arrow function with whitespace', () => {
+      const fn = (x) => x * 2;
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain('return');
+    });
+
+    test('handles function with comments', () => {
+      const fn = function () {
+        // This is a comment
+        return 'commented';
+      };
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      expect(result).toContain("return 'commented'");
+    });
+
+    test('handles nested arrow functions', () => {
+      const fn = (arr: number[]) => arr.map(x => x * 2);
+
+      const result = functionToString(fn);
+      expect(result).toContain('function');
+      // The nested arrow function should also be converted
+      expect(result).toContain('x * 2');
+    });
+  });
+});

package/src/client/js.ts

@@ -1,30 +1,95 @@
-import { html } from '@hyperspan/html';
+import { HSHtml, html } from '@hyperspan/html';
+import { assetHash } from '../utils';
+import { join } from 'node:path';
+
+const CWD = process.cwd();
+const IS_PROD = process.env.NODE_ENV === 'production';
 
 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>();
+const CLIENT_JS_CACHE = new Map<string, { esmName: string, exports: string, fnArgs: string, publicPath: string }>();
+const EXPORT_REGEX = /export\{(.*)\}/g;
+
+type ClientJSModuleReturn = {
+  esmName: string;
+  jsId: string;
+  publicPath: string;
+  renderScriptTag: (loadScript?: ((module: unknown) => HSHtml | string) | string) => HSHtml;
+}
 
 /**
- * Render a client JS module as a script tag
+ * Load a client JS module
  */
-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.`
-    );
+export async function loadClientJS(modulePathResolved: string): Promise<ClientJSModuleReturn> {
+  const modulePath = modulePathResolved.replace('file://', '');
+  const jsId = assetHash(modulePath);
+
+  // Cache: Avoid re-processing the same file
+  if (!CLIENT_JS_CACHE.has(jsId)) {
+
+    // Build the client JS module
+    const result = await Bun.build({
+      entrypoints: [modulePath],
+      outdir: join(CWD, './public', JS_PUBLIC_PATH), // @TODO: Make this configurable... should be read from config file...
+      naming: IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined,
+      external: Array.from(JS_IMPORT_MAP.keys()),
+      minify: true,
+      format: 'esm',
+      target: 'browser',
+      env: 'APP_PUBLIC_*',
+    });
+
+    // Add output file to import map
+    const esmName = String(result.outputs[0].path.split('/').reverse()[0]).replace('.js', '');
+    const publicPath = `${JS_PUBLIC_PATH}/${esmName}.js`;
+    JS_IMPORT_MAP.set(esmName, publicPath);
+
+    // Get the contents of the file to extract the exports
+    const contents = await result.outputs[0].text();
+    const exportLine = EXPORT_REGEX.exec(contents);
+
+    let exports = '{}';
+    if (exportLine) {
+      const exportName = exportLine[1];
+      exports =
+        '{' +
+        exportName
+          .split(',')
+          .map((name) => name.trim().split(' as '))
+          .map(([name, alias]) => `${alias === 'default' ? 'default as ' + name : alias}`)
+          .join(', ') +
+        '}';
+    }
+    const fnArgs = exports.replace(/(\w+)\s*as\s*(\w+)/g, '$1: $2');
+    CLIENT_JS_CACHE.set(jsId, { esmName, exports, fnArgs, publicPath });
   }
 
-  return html.raw(
-    // @ts-ignore
-    module.__CLIENT_JS.renderScriptTag({
-      loadScript: loadScript
-        ? typeof loadScript === 'string'
-          ? loadScript
-          : functionToString(loadScript)
-        : undefined,
-    })
-  );
+  const { esmName, exports, fnArgs, publicPath } = CLIENT_JS_CACHE.get(jsId)!;
+
+  return {
+    esmName,
+    jsId,
+    publicPath,
+    renderScriptTag: (loadScript) => {
+      const t = typeof loadScript;
+
+      if (t === 'string') {
+        return html`
+          <script type="module" data-source-id="${jsId}">import ${exports} from "${esmName}";\n(${html.raw(loadScript as string)})(${fnArgs});</script>
+        `;
+      }
+      if (t === 'function') {
+        return html`
+          <script type="module" data-source-id="${jsId}">import ${exports} from "${esmName}";\n(${html.raw(functionToString(loadScript))})(${fnArgs});</script>
+        `;
+      }
+
+      return html`
+        <script type="module" data-source-id="${jsId}">import "${esmName}";</script>
+      `;
+    }
+  }
 }
 
 /**
@@ -34,28 +99,5 @@ export function renderClientJS<T>(module: T, loadScript?: ((module: T) => void)
 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;
 }

package/src/layout.ts

@@ -1,8 +1,10 @@
 import { html } from '@hyperspan/html';
-import { JS_IMPORT_MAP } from './client/js';
+import { JS_IMPORT_MAP, loadClientJS } from './client/js';
 import { CSS_PUBLIC_PATH, CSS_ROUTE_MAP } from './client/css';
 import type { Hyperspan as HS } from './types';
 
+const clientStreamingJS = await loadClientJS(import.meta.resolve('./client/_hs/hyperspan-streaming.client'));
+
 /**
  * Output the importmap for the client so we can use ESModules on the client to load JS files on demand
  */
@@ -11,6 +13,27 @@ export function hyperspanScriptTags() {
     <script type="importmap">
       {"imports": ${Object.fromEntries(JS_IMPORT_MAP)}}
     </script>
+    <script id="hyperspan-streaming-script">
+      // [Hyperspan] Streaming - Load the client streaming JS module only when the first chunk is loaded
+      window._hsc = window._hsc || [];
+      var hscc = function(e) {
+        if (window._hscc !== undefined) {
+          window._hscc(e);
+        }
+      };
+      window._hsc.push = function(e) {
+        Array.prototype.push.call(window._hsc, e);
+        if (window._hsc.length === 1) {
+          const script = document.createElement('script');
+          script.src = "${clientStreamingJS.publicPath}";
+          document.body.appendChild(script);
+          script.onload = function() {
+            hscc(e);
+          };
+        }
+        hscc(e);
+      };
+    </script>
   `;
 }
 

package/src/server.ts

@@ -1,11 +1,9 @@
-import { HSHtml, html, isHSHtml, renderStream, renderAsync, render } from '@hyperspan/html';
+import { HSHtml, html, isHSHtml, renderStream, renderAsync, render, _typeOf } from '@hyperspan/html';
 import { executeMiddleware } from './middleware';
-import { clientJSPlugin } from './plugins';
 import { parsePath } from './utils';
 import { Cookies } from './cookies';
 
 import type { Hyperspan as HS } from './types';
-import { RequestOptions } from 'node:http';
 
 export const IS_PROD = process.env.NODE_ENV === 'production';
 
@@ -25,7 +23,7 @@ export function createConfig(config: Partial<HS.Config> = {}): HS.Config {
     ...config,
     appDir: config.appDir ?? './app',
     publicDir: config.publicDir ?? './public',
-    plugins: [clientJSPlugin(), ...(config.plugins ?? [])],
+    plugins: config.plugins ?? [],
   };
 }
 
@@ -65,6 +63,7 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
   return {
     vars: {},
     route: {
+      name: route?._config.name || undefined,
       path,
       params: params,
       cssImports: route ? route._config.cssImports ?? [] : [],
@@ -101,7 +100,7 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
  * Define a route that can handle a direct HTTP request.
  * Route handlers should return a HSHtml or Response object
  */
-export function createRoute(config: HS.RouteConfig = {}): HS.Route {
+export function createRoute(config: Partial<HS.RouteConfig> = {}): HS.Route {
   const _handlers: Record<string, HS.RouteHandler> = {};
   let _middleware: Record<string, Array<HS.MiddlewareFunction>> = { '*': [] };
 
@@ -227,6 +226,11 @@ export function createRoute(config: HS.RouteConfig = {}): HS.Route {
           return returnHTMLResponse(context, () => routeContent);
         }
 
+        const contentType = _typeOf(routeContent);
+        if (contentType === 'generator') {
+          return new StreamResponse(routeContent as AsyncGenerator);
+        }
+
         return routeContent;
       };
 
@@ -337,13 +341,23 @@ export async function returnHTMLResponse(
     // Render HSHtml if returned from route handler
     if (isHSHtml(routeContent)) {
       // @TODO: Move this to config or something...
-      const streamOpt = context.req.query.get('__nostream');
-      const streamingEnabled = (streamOpt !== undefined ? streamOpt : true);
+      const disableStreaming = context.req.query.get('__nostream') ?? '0';
+      const streamingEnabled = disableStreaming !== '1';
 
       // Stream only if enabled and there is async content to stream
       if (streamingEnabled && (routeContent as HSHtml).asyncContent?.length > 0) {
         return new StreamResponse(
-          renderStream(routeContent as HSHtml),
+          renderStream(routeContent as HSHtml, {
+            renderChunk: (chunk) => {
+              return html`
+              <template id="${chunk.id}_content">${html.raw(chunk.content)}<!--end--></template>
+              <script>
+                window._hsc = window._hsc || [];
+                window._hsc.push({id: "${chunk.id}" });
+              </script>
+            `;
+            }
+          }),
           responseOptions
         ) as Response;
       } else {

package/src/types.ts

@@ -88,10 +88,10 @@ export namespace Hyperspan {
   };
 
   export type RouteConfig = {
-    name?: string;
-    path?: string;
-    params?: Record<string, string | undefined>;
-    cssImports?: string[];
+    name: string | undefined;
+    path: string;
+    params: Record<string, string | undefined>;
+    cssImports: string[];
   };
   export type RouteHandler = (context: Hyperspan.Context) => unknown;
   export type RouteHandlerOptions = {
@@ -124,7 +124,7 @@ export namespace Hyperspan {
 
   export interface Route {
     _kind: 'hsRoute';
-    _config: Hyperspan.RouteConfig;
+    _config: Partial<Hyperspan.RouteConfig>;
     _path(): string;
     _methods(): string[];
     get: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;

package/src/plugins.ts

@@ -1,94 +0,0 @@
-import type { Hyperspan as HS } from './types';
-import { JS_PUBLIC_PATH, JS_IMPORT_MAP } from './client/js';
-import { assetHash } from './utils';
-import { IS_PROD } from './server';
-import { join } from 'node:path';
-
-export const CSS_PUBLIC_PATH = '/_hs/css';
-const CLIENT_JS_CACHE = new Map<string, string>();
-const EXPORT_REGEX = /export\{(.*)\}/g;
-
-/**
- * Hyperspan Client JS Plugin
- */
-export function clientJSPlugin(): HS.Plugin {
-  return async (config: HS.Config) => {
-    // Define a Bun plugin to handle .client.ts files
-    await Bun.plugin({
-      name: 'Hyperspan Client JS Loader',
-      async setup(build) {
-        // when a .client.ts file is imported...
-        build.onLoad({ filter: /\.client\.ts$/ }, async (args) => {
-          const jsId = assetHash(args.path);
-
-          // Cache: Avoid re-processing the same file
-          if (IS_PROD && CLIENT_JS_CACHE.has(jsId)) {
-            return {
-              contents: CLIENT_JS_CACHE.get(jsId) || '',
-              loader: 'js',
-            };
-          }
-
-          // We need to build the file to ensure we can ship it to the client with dependencies
-          // Ironic, right? Calling Bun.build() inside of a plugin that runs on Bun.build()?
-          const result = await Bun.build({
-            entrypoints: [args.path],
-            outdir: join(config.publicDir, JS_PUBLIC_PATH),
-            naming: IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined,
-            external: Array.from(JS_IMPORT_MAP.keys()),
-            minify: IS_PROD,
-            format: 'esm',
-            target: 'browser',
-            env: 'APP_PUBLIC_*',
-          });
-
-          // Add output file to import map
-          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);
-
-          let exports = '{}';
-          if (exportLine) {
-            const exportName = exportLine[1];
-            exports =
-              '{' +
-              exportName
-                .split(',')
-                .map((name) => name.trim().split(' as '))
-                .map(([name, alias]) => `${alias === 'default' ? 'default as ' + name : alias}`)
-                .join(', ') +
-              '}';
-          }
-          const fnArgs = exports.replace(/(\w+)\s*as\s*(\w+)/g, '$1: $2');
-
-          // 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/client/js';
-
-// hyperspan:client-js-plugin
-export const __CLIENT_JS = {
-  id: "${jsId}",
-  esmName: "${esmName}",
-  sourceFile: "${args.path}",
-  outputFile: "${result.outputs[0].path}",
-  renderScriptTag: ({ loadScript }) => {
-    const fn = loadScript ? (typeof loadScript === 'string' ? loadScript : \`const fn = \${functionToString(loadScript)}; fn(${fnArgs});\`) : '';
-    return \`<script type="module" data-source-id="${jsId}">import ${exports} from "${esmName}";\n\${fn}</script>\`;
-  },
-}
-`;
-
-          CLIENT_JS_CACHE.set(jsId, moduleCode);
-
-          return {
-            contents: moduleCode,
-            loader: 'js',
-          };
-        });
-      },
-    });
-  };
-}