@hyperspan/framework 1.0.29 → 2.0.0-alpha.13

package/src/fetch-handler.ts

@@ -0,0 +1,168 @@
+import { createContext } from './server';
+import type { Hyperspan as HS } from './types';
+
+export type FetchHandlerOptions = {
+  /** Called when no route matches (before 404). Return a Response to handle static assets etc. */
+  onNotMatched?: (request: Request) => Promise<Response | undefined>;
+};
+
+type CompiledRoute = {
+  route: HS.Route;
+  pattern: RegExp;
+  paramNames: string[];
+  isWildcard: boolean;
+};
+
+/**
+ * Convert a Hyperspan route path (`/users/:id`, `/blog/*`) into a RegExp + param names.
+ */
+export function compileRoutePath(path: string): {
+  pattern: RegExp;
+  paramNames: string[];
+  isWildcard: boolean;
+} {
+  const paramNames: string[] = [];
+  const isWildcard = path.endsWith('/*');
+
+  if (path === '/') {
+    return { pattern: /^\/$/, paramNames, isWildcard: false };
+  }
+
+  const segments = path.split('/').filter(Boolean);
+  const regexParts = segments.map((segment) => {
+    if (segment === '*') {
+      paramNames.push('...slug');
+      return '(.+)';
+    }
+    if (segment.startsWith(':')) {
+      paramNames.push(segment.slice(1));
+      return '([^/]+)';
+    }
+    return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  });
+
+  const pattern = new RegExp(`^/${regexParts.join('/')}${isWildcard ? '' : '/?'}$`);
+  return { pattern, paramNames, isWildcard };
+}
+
+function mergeRouteMiddleware(server: HS.Server, route: HS.Route): void {
+  route._serverConfig = server._config;
+
+  if (!server._middleware || !route._middleware) {
+    return;
+  }
+
+  for (const method of Object.keys(server._middleware) as HS.MiddlewareMethod[]) {
+    if (Array.isArray(server._middleware[method]) && Array.isArray(route._middleware[method])) {
+      route._middleware[method] = server._middleware[method].concat(route._middleware[method]);
+    }
+  }
+}
+
+function matchRoute(
+  compiledRoutes: CompiledRoute[],
+  pathname: string,
+  method: string
+): { route: HS.Route; params: Record<string, string | undefined> } | null {
+  for (const compiled of compiledRoutes) {
+    const match = pathname.match(compiled.pattern);
+    if (!match) {
+      continue;
+    }
+
+    // Actions and some custom handlers may not expose _methods(); treat as all methods.
+    const routeMethods =
+      typeof compiled.route._methods === 'function' ? compiled.route._methods() : ['*'];
+    const supportsMethod =
+      routeMethods.includes(method) ||
+      routeMethods.includes('*') ||
+      (method === 'HEAD' && routeMethods.includes('GET'));
+
+    if (!supportsMethod) {
+      continue;
+    }
+
+    const params: Record<string, string | undefined> = {};
+    compiled.paramNames.forEach((name, index) => {
+      const value = match[index + 1];
+      if (name.startsWith('...')) {
+        params[name] = value;
+      } else {
+        params[name] = value;
+      }
+    });
+
+    return { route: compiled.route, params };
+  }
+
+  return null;
+}
+
+function trailingSlashRedirect(pathname: string, request: Request): Response | null {
+  if (pathname.length > 1 && pathname.endsWith('/')) {
+    const url = new URL(request.url);
+    url.pathname = pathname.slice(0, -1);
+    return Response.redirect(url.toString(), 308);
+  }
+  return null;
+}
+
+/**
+ * Create a portable fetch handler for a Hyperspan server.
+ * Works on Node, Bun, Cloudflare Workers, and any runtime with Web Fetch API.
+ */
+export function createFetchHandler(
+  server: HS.Server,
+  options: FetchHandlerOptions = {}
+): (request: Request) => Promise<Response> {
+  const compiledRoutes: CompiledRoute[] = server._routes.map((route) => {
+    const path = route._path();
+    mergeRouteMiddleware(server, route);
+    const { pattern, paramNames, isWildcard } = compileRoutePath(path);
+    return { route, pattern, paramNames, isWildcard };
+  });
+
+  // Longer / more specific paths first (more segments wins)
+  compiledRoutes.sort((a, b) => {
+    const aSegments = a.route._path().split('/').filter(Boolean).length;
+    const bSegments = b.route._path().split('/').filter(Boolean).length;
+    return bSegments - aSegments;
+  });
+
+  return async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const pathname = url.pathname;
+    const method = request.method.toUpperCase();
+
+    const slashRedirect = trailingSlashRedirect(pathname, request);
+    if (slashRedirect) {
+      return slashRedirect;
+    }
+
+    const matched = matchRoute(compiledRoutes, pathname, method);
+    if (matched) {
+      // Attach params on the original request. `new Request(request)` clones
+      // through Node's Request constructor, which strips Cookie/Origin/Host.
+      (request as Request & { params?: Record<string, string | undefined> }).params =
+        matched.params;
+      return matched.route.fetch(request);
+    }
+
+    if (options.onNotMatched) {
+      const staticResponse = await options.onNotMatched(request);
+      if (staticResponse) {
+        return staticResponse;
+      }
+    }
+
+    return createContext(request).res.notFound();
+  };
+}
+
+/**
+ * Create an app object with a fetch method (adapter contract).
+ */
+export function createApp(server: HS.Server, options: FetchHandlerOptions = {}) {
+  const fetch = createFetchHandler(server, options);
+  return { fetch, server };
+}

package/src/index.ts

@@ -3,10 +3,36 @@ export {
   createContext,
   createRoute,
   createServer,
+  initServerRoutes,
   getRunnableRoute,
   StreamResponse,
   IS_PROD,
   HTTPResponseException,
   hyperspanDisableStreaming,
 } from './server';
-export type { Hyperspan } from './types';
+export { createFetchHandler, createApp, compileRoutePath } from './fetch-handler';
+export type { FetchHandlerOptions } from './fetch-handler';
+export {
+  setAssetManifest,
+  getAssetManifest,
+  resolveImport,
+  getRouteCss,
+  getImportMap,
+  registerImport,
+} from './client/manifest';
+export { buildClientJS, registerPathAliases } from './client/js';
+export type { BuildClientJSOptions, ClientJSType } from './client/js';
+export { registerRouteModule, registerRouteModules } from './register-routes';
+export type { RouteModuleEntry } from './register-routes';
+export type { AssetManifest } from './client/manifest';
+export { renderIsland } from './island';
+export type { IslandRenderOptions } from './island';
+export type {
+  Hyperspan,
+  ServerCreateContext,
+  DeployAdapter,
+  Adapter,
+  AdapterAfterBuildContext,
+  DeployEntry,
+  DeployEntryContext,
+} from './types';

package/src/island.test.ts

@@ -0,0 +1,30 @@
+import { describe, test, expect } from 'vitest';
+import { renderIsland } from './island';
+
+describe('renderIsland', () => {
+  test('throws when component has no __HS_ISLAND', () => {
+    expect(() => renderIsland({ name: 'Bare' } as never, {})).toThrow(/not a Hyperspan island/i);
+  });
+
+  test('returns html.raw for sync island render', () => {
+    const component = {
+      name: 'Counter',
+      __HS_ISLAND: {
+        render: () => '<div id="x">1</div>',
+      },
+    };
+    const result = renderIsland(component, { count: 1 });
+    expect(result).toHaveProperty('_kind', 'html_safe');
+    expect((result as { content: string }).content).toContain('<div id="x">1</div>');
+  });
+
+  test('awaits async island render', async () => {
+    const component = {
+      __HS_ISLAND: {
+        render: async () => '<div>async</div>',
+      },
+    };
+    const result = await renderIsland(component, {});
+    expect(result.content).toContain('<div>async</div>');
+  });
+});

package/src/island.ts

@@ -0,0 +1,37 @@
+import { html } from '@hyperspan/html';
+
+type IslandComponent = {
+  __HS_ISLAND?: {
+    render: (props: unknown, options: unknown) => string | Promise<string>;
+  };
+  name?: string;
+};
+
+export type IslandRenderOptions = {
+  ssr?: boolean;
+  loading?: 'lazy' | undefined;
+};
+
+/**
+ * Render any Hyperspan island component (Preact, Svelte, Vue).
+ * Proxies to `Component.__HS_ISLAND.render` injected by the island Vite plugin.
+ */
+export function renderIsland(
+  Component: IslandComponent,
+  props: Record<string, unknown> = {},
+  options: IslandRenderOptions = { ssr: true }
+) {
+  if (!Component?.__HS_ISLAND?.render) {
+    const label = Component?.name ?? 'Component';
+    throw new Error(
+      `${label} is not a Hyperspan island. Import it with \`with { island: 'preact' | 'svelte' | 'vue' }\` ` +
+        `and ensure the matching plugin is listed in hyperspan.config.ts plugins.`
+    );
+  }
+
+  const result = Component.__HS_ISLAND.render(props, options);
+  if (result != null && typeof (result as Promise<string>).then === 'function') {
+    return (result as Promise<string>).then((s) => html.raw(s));
+  }
+  return html.raw(result as string);
+}

package/src/layout.test.ts

@@ -0,0 +1,12 @@
+import { test, expect } from 'vitest';
+import { render } from '@hyperspan/html';
+import { hyperspanScriptTags } from './layout';
+import { streamingClient } from './client/js';
+
+test('streaming bootstrap injects a classic script so chunks swap in during parse', () => {
+  const html = render(hyperspanScriptTags());
+  expect(html).toContain("document.createElement('script')");
+  expect(html).toContain(`script.src = '${streamingClient.publicPath}'`);
+  expect(html).not.toContain("type = 'module'");
+  expect(html).not.toContain(`import('${streamingClient.publicPath}')`);
+});

package/src/layout.ts

@@ -1,19 +1,24 @@
 import { html } from '@hyperspan/html';
-import { JS_IMPORT_MAP, buildClientJS } from './client/js';
-import { CSS_PUBLIC_PATH, CSS_ROUTE_MAP } from './client/css';
+import { CSS_PUBLIC_PATH } from './client/css';
+import { getImportMap, getRouteCss } from './client/manifest';
+import { actionsClient, streamingClient } from './client/js';
 import type { Hyperspan as HS } from './types';
 
-const clientStreamingJS = await buildClientJS(
-  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
+ * Output the importmap for the client so we can use ESModules on the client to load JS files on demand.
+ *
+ * The streaming client MUST be loaded as a classic <script>, not type=module.
+ * Browsers defer all ESM until the document finishes parsing, which would hold
+ * every streaming chunk until the whole page is done. A dynamically inserted
+ * classic script runs as soon as it downloads.
  */
 export function hyperspanScriptTags() {
+  const imports = getImportMap();
+  const streamingPath = streamingClient.publicPath;
+
   return html`
     <script type="importmap">
-      {"imports": ${Object.fromEntries(JS_IMPORT_MAP)}}
+      {"imports": ${imports}}
     </script>
     <script id="hyperspan-streaming-script">
       // [Hyperspan] Streaming - Load the client streaming JS module only when the first chunk is loaded
@@ -25,7 +30,7 @@ export function hyperspanScriptTags() {
           if (!window._hscLoading) {
             window._hscLoading = true;
             const script = document.createElement('script');
-            script.src = '${clientStreamingJS.publicPath}';
+            script.src = '${streamingPath}';
             document.body.appendChild(script);
           }
         };
@@ -39,11 +44,23 @@ export function hyperspanScriptTags() {
  */
 export function hyperspanStyleTags(context: HS.Context) {
   const styleTags = [];
-  const cssImports = context.route.cssImports ?? CSS_ROUTE_MAP.get(context.route.path) ?? [];
+  const cssImports = context.route.cssImports?.length
+    ? context.route.cssImports
+    : getRouteCss(context.route.path);
 
   for (const cssFile of cssImports) {
-    styleTags.push(html` <link rel="stylesheet" href="${CSS_PUBLIC_PATH}/${cssFile}" /> `);
+    // Absolute Vite/dev URLs (e.g. /app/styles/globals.css) are used as-is;
+    // hashed build artifacts are served under /_hs/css/.
+    const href = cssFile.startsWith('/') ? cssFile : `${CSS_PUBLIC_PATH}/${cssFile}`;
+    styleTags.push(html` <link rel="stylesheet" href="${href}" /> `);
   }
 
   return styleTags;
 }
+
+/**
+ * Render the actions client script tag (used by createAction).
+ */
+export function hyperspanActionsScriptTag() {
+  return html`<script type="module" src="${actionsClient.publicPath}"></script>`;
+}

package/src/register-routes.ts

@@ -0,0 +1,64 @@
+import { getRunnableRoute } from './server';
+import { isValidRoutePath, parsePath } from './utils';
+import type { AssetManifest } from './client/manifest';
+import type { Hyperspan as HS } from './types';
+
+export type RouteModuleEntry = {
+  file: string;
+  mod: unknown;
+};
+
+/**
+ * Register a route or action module on a Hyperspan server.
+ * Shared by the CLI, Vite plugin, and the generated production server entry.
+ */
+export function registerRouteModule(
+  server: HS.Server,
+  relativeFilePath: string,
+  mod: unknown,
+  manifest?: AssetManifest
+): HS.Route | null {
+  if (!isValidRoutePath(relativeFilePath)) {
+    return null;
+  }
+
+  const route = getRunnableRoute(mod);
+  const parsedPath = parsePath(relativeFilePath);
+
+  let path = parsedPath.path;
+  if (typeof route._path === 'function') {
+    const routePath = route._path();
+    if (routePath && routePath !== '/') path = routePath;
+  }
+
+  if (!route._config.path) {
+    route._config.path = path;
+    if (parsedPath.params.length > 0) {
+      const params = route._config.params ?? {};
+      parsedPath.params.forEach((param) => {
+        params[param] = undefined;
+      });
+      route._config.params = params;
+    }
+  }
+
+  if (manifest) {
+    const cssFiles = manifest.css?.[path] ?? manifest.css?.['*'];
+    if (cssFiles?.length) {
+      route._config.cssImports = cssFiles;
+    }
+  }
+
+  server._routes.push(route);
+  return route;
+}
+
+export function registerRouteModules(
+  server: HS.Server,
+  modules: RouteModuleEntry[],
+  manifest?: AssetManifest
+): void {
+  for (const { file, mod } of modules) {
+    registerRouteModule(server, file, mod, manifest);
+  }
+}

package/src/server.test.ts

@@ -1,5 +1,5 @@
-import { test, expect, describe } from 'bun:test';
-import { createRoute, createServer, createContext } from './server';
+import { test, expect, describe } from 'vitest';
+import { createRoute, createServer, createContext, initServerRoutes } from './server';
 import { createAction } from './actions';
 import { html, placeholder } from '@hyperspan/html';
 import type { Hyperspan as HS } from './types';
@@ -92,6 +92,25 @@ test('server returns a route with a POST request', async () => {
   expect(await response.text()).toBe('<h1>POST /users</h1>');
 });
 
+test('POST HTML response does not inherit request Content-Length', async () => {
+  const route = createRoute().post((context: HS.Context) => {
+    return context.res.html('<h1>hello world this is longer than the form body</h1>');
+  });
+  const body = 'email=a@b.com&password=secret';
+  const request = new Request('http://localhost:3000/', {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/x-www-form-urlencoded',
+      'content-length': String(body.length),
+    },
+    body,
+  });
+  const response = await route.fetch(request);
+  const text = await response.text();
+  expect(text).toBe('<h1>hello world this is longer than the form body</h1>');
+  expect(Number(response.headers.get('content-length') ?? text.length)).toBe(text.length);
+});
+
 test('server returns a route with a ALL request', async () => {
   const server = await createServer({
     appDir: './app',
@@ -199,6 +218,17 @@ test('createContext() can get and set cookies', () => {
   }
 });
 
+test('createContext() url() returns a relative URL string', () => {
+  const request = new Request('http://localhost:3000/posts?sort=asc#top');
+  const context = createContext(request);
+
+  expect(typeof context.url()).toBe('string');
+  expect(context.url()).toBe('/posts?sort=asc#top');
+  expect(context.url({ searchParams: { page: 2 } })).toBe('/posts?sort=asc&page=2#top');
+  expect(context.url({ searchParams: { page: 2 } }, { clean: true })).toBe('/posts?page=2');
+  expect(context.req.url.search).toBe('?sort=asc');
+});
+
 test('createContext() merge() function preserves custom headers when using response methods', async () => {
   // Create a request
   const request = new Request('http://localhost:3000/');
@@ -555,3 +585,31 @@ describe('when streaming is disabled', () => {
     expect(text).not.toContain('hs:loading');
   });
 });
+
+test('initServerRoutes runs beforeRoutesAdded, then addRoutes, then afterRoutesAdded', async () => {
+  const order: string[] = [];
+  const server = await createServer({
+    appDir: './app',
+    publicDir: './public',
+    plugins: [],
+  });
+
+  await initServerRoutes(
+    server,
+    {
+      beforeRoutesAdded(s) {
+        order.push('before');
+        s.use(async (_c, next) => next());
+      },
+      afterRoutesAdded() {
+        order.push('after');
+      },
+    },
+    () => {
+      order.push('routes');
+    }
+  );
+
+  expect(order).toEqual(['before', 'routes', 'after']);
+  expect(server._middleware['*']).toHaveLength(1);
+});

package/src/server.ts

@@ -10,8 +10,9 @@ import {
 } from '@hyperspan/html';
 import { isbot } from 'isbot';
 import { executeMiddleware } from './middleware';
-import { parsePath, removeUndefined } from './utils';
+import { buildUrl, parsePath, removeUndefined } from './utils';
 import { Cookies } from './cookies';
+import { nodeAdapter } from '@hyperspan/adapter-node';
 
 import type { Hyperspan as HS } from './types';
 
@@ -51,6 +52,7 @@ export function createConfig(config: Partial<HS.Config> = {}): HS.Config {
     appDir: './app',
     publicDir: './public',
     plugins: [],
+    deployAdapter: config.deployAdapter ?? nodeAdapter(),
     responseOptions: {
       disableStreaming: hyperspanDisableStreaming,
     },
@@ -58,6 +60,7 @@ export function createConfig(config: Partial<HS.Config> = {}): HS.Config {
   return {
     ...defaultConfig,
     ...config,
+    deployAdapter: config.deployAdapter ?? defaultConfig.deployAdapter,
     responseOptions: {
       ...defaultConfig.responseOptions,
       ...config.responseOptions,
@@ -72,7 +75,8 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
   const url = new URL(req.url);
   const query = new URLSearchParams(url.search);
   const method = req.method.toUpperCase();
-  const headers = new Headers(req.headers);
+  const requestHeaders = new Headers(req.headers);
+  const responseHeaders = new Headers();
   const path = route?._path() || '/';
   const requestParams = (req as Request & { params?: Record<string, string | undefined> }).params;
   const params: Record<string, string | undefined> = Object.assign(
@@ -92,12 +96,21 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
   // Status override for the response. Will use if set. (e.g. c.res.status = 400)
   let status: number | undefined = undefined;
 
+  const copyHeaders = (source: Headers, target: Headers) => {
+    source.forEach((value, key) => {
+      if (key.toLowerCase() === 'set-cookie') return;
+      target.set(key, value);
+    });
+    const cookies = typeof source.getSetCookie === 'function' ? source.getSetCookie() : [];
+    for (const cookie of cookies) {
+      target.append('Set-Cookie', cookie);
+    }
+  };
+
   const merge = async (response: Response) => {
-    // Convert headers to plain objects and merge (response headers override context headers)
-    const mergedHeaders = {
-      ...Object.fromEntries(headers.entries()),
-      ...Object.fromEntries(response.headers.entries()),
-    };
+    const mergedHeaders = new Headers();
+    copyHeaders(responseHeaders, mergedHeaders);
+    copyHeaders(response.headers, mergedHeaders);
 
     return new Response(await response.text(), {
       status: context.res.status ?? response.status,
@@ -107,6 +120,10 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
 
   const context: HS.Context = {
     vars: {},
+    url: (diff, options) => {
+      const next = buildUrl(url, diff, options);
+      return `${next.pathname}${next.search}${next.hash}`;
+    },
     route: {
       name: route?._config.name || undefined,
       path,
@@ -117,7 +134,7 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
       raw: req,
       url,
       method,
-      headers,
+      headers: requestHeaders,
       query,
       cookies: new Cookies(req),
       async text() {
@@ -134,8 +151,8 @@ export function createContext(req: Request, route?: HS.Route): HS.Context {
       },
     },
     res: {
-      cookies: new Cookies(req, headers),
-      headers,
+      cookies: new Cookies(req, responseHeaders),
+      headers: responseHeaders,
       status,
       html: (html: string, options?: ResponseInit) =>
         merge(
@@ -497,6 +514,20 @@ export async function createServer(config: HS.Config = {} as HS.Config): Promise
   return api;
 }
 
+/**
+ * Shared route lifecycle for Vite dev, production entries, and `hyperspan start`.
+ * Always: `beforeRoutesAdded` → add routes → `afterRoutesAdded`.
+ */
+export async function initServerRoutes(
+  server: HS.Server,
+  config: Pick<HS.Config, 'beforeRoutesAdded' | 'afterRoutesAdded'>,
+  addRoutes: (server: HS.Server) => void | Promise<void>
+): Promise<void> {
+  await config.beforeRoutesAdded?.(server);
+  await addRoutes(server);
+  await config.afterRoutesAdded?.(server);
+}
+
 /**
  * Checks if a response is HTML content
  */
@@ -537,7 +568,7 @@ export async function returnHTMLResponse(
       if (!disableStreaming && (routeContent as HSHtml).asyncContent?.length > 0) {
         return new StreamResponse(
           renderStream(routeContent as HSHtml, {
-            renderChunk: (chunk) => {
+            renderChunk: (chunk: { id: string; content: string }) => {
               // Trailing <!--/hs:chunk--> marks the end of a streaming chunk boundary.
               return html`
                 <template id="${chunk.id}_content">${html.raw(chunk.content)}<!--end--></template>

package/src/ssr/mock-dom.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from 'bun:test';
+import { describe, expect, test } from 'vitest';
 import { MOCK_DOM_MARK, installMockDom, stubElement } from './mock-dom';
 
 describe('stubElement', () => {