@hyperspan/framework 1.0.29 → 2.0.0-alpha.13

package/src/client/js.ts

@@ -1,98 +1,322 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { html } from '@hyperspan/html';
 import { assetHash as assetHashFn } from '../utils';
-import { join } from 'node:path';
+import { getImportMap, registerImport, resolveImport } from './manifest';
 import type { Hyperspan as HS } from '../types';
 
-const CWD = process.cwd();
-const IS_PROD = process.env.NODE_ENV === 'production';
+export { registerImport, resolveImport, getImportMap } from './manifest';
 
 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 CLIENT_JS_BUILD_PROMISES = new Map<string, Promise<void>>();
-const EXPORT_REGEX = /export\{(.*)\}/g;
+
+export type ClientJSType = 'module' | 'iife';
+
+export type BuildClientJSOptions = {
+  /** `iife` emits a classic <script> (runs during HTML streaming). Default `module`. */
+  type?: ClientJSType;
+};
+
+export type ClientJSEntry = {
+  /** Original path/specifier passed to `buildClientJS`. */
+  modulePath: string;
+  absPath: string;
+  assetHash: string;
+  esmName: string;
+  publicPath: string;
+  exports: string;
+  fnArgs: string;
+  type: ClientJSType;
+};
+
+const CLIENT_JS_REGISTRY = Symbol.for('@hyperspan/client-js-entries');
+const PATH_ALIASES = Symbol.for('@hyperspan/path-aliases');
+
+function getPathAliases(): Record<string, string> {
+  const globalAliases = globalThis as {
+    [PATH_ALIASES]?: Record<string, string>;
+  };
+  if (!globalAliases[PATH_ALIASES]) {
+    globalAliases[PATH_ALIASES] = {};
+  }
+  return globalAliases[PATH_ALIASES];
+}
+
+/** Register tsconfig path aliases (`~/` → project root). Called by the Vite plugin. */
+export function registerPathAliases(aliases: Record<string, string>): void {
+  Object.assign(getPathAliases(), aliases);
+}
+
+function resolveWithAliases(specifier: string): string | undefined {
+  const aliases = getPathAliases();
+  const keys = Object.keys(aliases).sort((a, b) => b.length - a.length);
+  for (const key of keys) {
+    if (specifier === key || specifier.startsWith(key)) {
+      const rest = specifier.slice(key.length).replace(/^\//, '');
+      return join(aliases[key], rest);
+    }
+  }
+  return undefined;
+}
+
+function getClientJSRegistry(): Map<string, ClientJSEntry> {
+  const globalRegistry = globalThis as {
+    [CLIENT_JS_REGISTRY]?: Map<string, ClientJSEntry>;
+  };
+  if (!globalRegistry[CLIENT_JS_REGISTRY]) {
+    globalRegistry[CLIENT_JS_REGISTRY] = new Map();
+  }
+  return globalRegistry[CLIENT_JS_REGISTRY];
+}
 
 /**
- * Build a client JS module and return a Hyperspan.ClientJSBuildResult object
+ * Backward-compatible import map (backed by asset manifest).
  */
-export async function buildClientJS(modulePathResolved: string): Promise<HS.ClientJSBuildResult> {
-  const modulePath = modulePathResolved.replace('file://', '');
-  const assetHash = assetHashFn(modulePath);
-
-  // Cache: Avoid re-processing the same file
-  if (!CLIENT_JS_CACHE.has(assetHash)) {
-    const existingBuild = CLIENT_JS_BUILD_PROMISES.get(assetHash);
-    // Await the existing build promise if it exists (this can get called in parallel from Bun traversing imports)
-    if (existingBuild) {
-      await existingBuild;
-    } else {
-      const buildPromise = (async () => {
-        // 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 { exports, fnArgs } = extractExports(contents);
-
-        CLIENT_JS_CACHE.set(assetHash, { esmName, exports, fnArgs, publicPath });
-      })();
-
-      CLIENT_JS_BUILD_PROMISES.set(assetHash, buildPromise);
-      try {
-        await buildPromise;
-      } finally {
-        CLIENT_JS_BUILD_PROMISES.delete(assetHash);
-      }
+export const JS_IMPORT_MAP = {
+  get size() {
+    return Object.keys(getImportMap()).length;
+  },
+  keys() {
+    return Object.keys(getImportMap()).values();
+  },
+  has(key: string) {
+    return resolveImport(key) !== undefined;
+  },
+  get(key: string) {
+    return resolveImport(key);
+  },
+  set(key: string, value: string) {
+    registerImport(key, value);
+    return this;
+  },
+  entries() {
+    return Object.entries(getImportMap()).values();
+  },
+  [Symbol.iterator]() {
+    return Object.entries(getImportMap())[Symbol.iterator]();
+  },
+};
+
+/**
+ * Prefer a cwd-relative hash so `import.meta.resolve(...)` and `app/client/foo.ts`
+ * produce the same public URL. Absolute paths outside the project stay as-is.
+ */
+function stableHashKey(absPath: string): string {
+  const normalized = absPath.replace(/\\/g, '/');
+  if (typeof process !== 'undefined' && typeof process.cwd === 'function') {
+    const rel = relative(process.cwd(), absPath).replace(/\\/g, '/');
+    if (rel && !rel.startsWith('..') && !isAbsolute(rel)) {
+      return rel;
     }
   }
+  const marker = '/node_modules/';
+  const idx = normalized.lastIndexOf(marker);
+  if (idx !== -1) {
+    return normalized.slice(idx + marker.length);
+  }
+  return normalized;
+}
+
+function toFilePath(modulePath: string): string {
+  return modulePath.startsWith('file://') ? fileURLToPath(modulePath) : modulePath;
+}
+
+/**
+ * `import.meta.resolve('./file.ts')` → file URL or absolute path.
+ * `~/app/client/foo.ts` → registered tsconfig alias.
+ * `app/client/foo.ts` → project root.
+ * Relative `./` / `../` paths error — resolve them at the call site.
+ */
+function resolveClientModule(modulePath: string): { hashKey: string; absPath: string } {
+  if (modulePath.startsWith('file://') || isAbsolute(modulePath)) {
+    const absPath = toFilePath(modulePath);
+    return { hashKey: stableHashKey(absPath), absPath };
+  }
+
+  const specifier = modulePath.replace(/\\/g, '/');
+  if (specifier.startsWith('.')) {
+    throw new Error(
+      `[Hyperspan] buildClientJS(${JSON.stringify(modulePath)}) got a relative path. ` +
+        `Use import.meta.resolve(${JSON.stringify(modulePath)}) at the call site, ` +
+        `or a tsconfig alias like '~/app/client/file.ts'.`
+    );
+  }
+
+  const aliased = resolveWithAliases(specifier);
+  if (aliased) {
+    return { hashKey: specifier, absPath: aliased };
+  }
+
+  return { hashKey: specifier, absPath: join(process.cwd(), specifier) };
+}
+
+export function getClientJSEntries(): ClientJSEntry[] {
+  return [...getClientJSRegistry().values()];
+}
+
+export function getClientJSEntryByEsmName(esmName: string): ClientJSEntry | undefined {
+  return getClientJSRegistry().get(esmName);
+}
+
+export function resetClientJSEntriesForTests(): void {
+  getClientJSRegistry().clear();
+  const aliases = getPathAliases();
+  for (const key of Object.keys(aliases)) {
+    delete aliases[key];
+  }
+}
+
+function registerClientJS(
+  modulePathResolved: string,
+  options: BuildClientJSOptions = {}
+): HS.ClientJSBuildResult {
+  const type = options.type ?? 'module';
+  const { hashKey, absPath } = resolveClientModule(modulePathResolved);
+  const hash = assetHashFn(hashKey);
+  const esmName = `client-${hash}`;
+  const publicPath = resolveImport(esmName) ?? `${JS_PUBLIC_PATH}/${esmName}.js`;
+
+  let exports = '* as _module';
+  let fnArgs = '_module';
+  const sourcePath = existsSync(absPath) ? absPath : null;
+  if (sourcePath) {
+    const source = readFileSync(sourcePath, 'utf-8');
+    const discovered = discoverClientExports(source);
+    exports = discovered.exports;
+    fnArgs = discovered.fnArgs;
+  }
 
-  const { esmName, exports, fnArgs, publicPath } = CLIENT_JS_CACHE.get(assetHash)!;
+  getClientJSRegistry().set(esmName, {
+    modulePath: modulePathResolved,
+    absPath,
+    assetHash: hash,
+    esmName,
+    publicPath,
+    exports,
+    fnArgs,
+    type,
+  });
+  registerImport(esmName, publicPath);
 
   return {
-    assetHash,
+    assetHash: hash,
     esmName,
     publicPath,
     renderScriptTag: (loadScript) => {
+      if (type === 'iife') {
+        return html`<script src="${publicPath}"></script>`;
+      }
+
       const t = typeof loadScript;
 
       if (t === 'string') {
         return html`
-          <script type="module" data-source-id="${assetHash}">import ${exports} from "${esmName}";\n(${html.raw(loadScript as string)})(${fnArgs});</script>
+          <script type="module" data-source-id="${hash}">
+            import ${exports} from '${esmName}';
+            (${html.raw(loadScript as string)})(${fnArgs});
+          </script>
         `;
       }
       if (t === 'function') {
         return html`
-          <script type="module" data-source-id="${assetHash}">import ${exports} from "${esmName}";\n(${html.raw(functionToString(loadScript))})(${fnArgs});</script>
+          <script type="module" data-source-id="${hash}">
+            import ${exports} from '${esmName}';
+            (${html.raw(functionToString(loadScript))})(${fnArgs});
+          </script>
         `;
       }
 
       return html`
-        <script type="module" data-source-id="${assetHash}">import "${esmName}";</script>
+        <script type="module" data-source-id="${hash}">
+          import '${esmName}';
+        </script>
       `;
+    },
+  };
+}
+
+/**
+ * Register a client JS module for Vite to bundle.
+ * Prefer a tsconfig alias or project-root path (`~/app/client/foo.ts`,
+ * `app/client/foo.ts`). Relative `./` / `../` paths must be resolved at the
+ * call site with `import.meta.resolve('./file.ts')`.
+ */
+export async function buildClientJS(
+  modulePathResolved: string,
+  options: BuildClientJSOptions = {}
+): Promise<HS.ClientJSBuildResult> {
+  return registerClientJS(modulePathResolved, options);
+}
+
+export const streamingClient = registerClientJS(
+  import.meta.resolve('./_hs/hyperspan-streaming.client.ts'),
+  { type: 'iife' }
+);
+export const actionsClient = registerClientJS(
+  import.meta.resolve('./_hs/hyperspan-actions.client.ts')
+);
+
+/**
+ * Discover export names from source or bundled client JS.
+ * Prefers bundled `export{...}` form, then common source export patterns.
+ */
+export function discoverClientExports(contents: string): { exports: string; fnArgs: string } {
+  const bundled = extractExports(contents);
+  if (bundled.exports !== '* as _module') {
+    return bundled;
+  }
+
+  const names: string[] = [];
+  const seen = new Set<string>();
+
+  for (const re of [
+    /export\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/g,
+    /export\s+const\s+([A-Za-z_$][\w$]*)/g,
+    /export\s+class\s+([A-Za-z_$][\w$]*)/g,
+    /export\s+let\s+([A-Za-z_$][\w$]*)/g,
+  ]) {
+    let match: RegExpExecArray | null;
+    while ((match = re.exec(contents)) !== null) {
+      if (!seen.has(match[1])) {
+        names.push(match[1]);
+        seen.add(match[1]);
+      }
     }
   }
+
+  const exportBlock = /export\s*\{([^}]+)\}/g;
+  let block: RegExpExecArray | null;
+  while ((block = exportBlock.exec(contents)) !== null) {
+    for (const part of block[1].split(',')) {
+      const trimmed = part.trim();
+      if (!trimmed || trimmed.startsWith('type ')) continue;
+      const asMatch = trimmed.match(/^(?:([\w$]+)\s+as\s+)?([\w$]+)$/);
+      const name = asMatch?.[2] ?? trimmed;
+      if (name && name !== 'default' && !seen.has(name)) {
+        names.push(name);
+        seen.add(name);
+      }
+    }
+  }
+
+  if (names.length === 0) {
+    if (/export\s+default\b/.test(contents)) {
+      return { exports: 'DefaultExport', fnArgs: 'DefaultExport' };
+    }
+    return { exports: '* as _module', fnArgs: '_module' };
+  }
+
+  const exports = `{${names.join(', ')}}`;
+  return { exports, fnArgs: exports };
 }
 
 /**
- * Extract the exports from a client JS module
+ * Extract the exports from a client JS module (bundled `export{a as b}` form).
  */
-export function extractExports(contents: string): { exports: string, fnArgs: string } {
-  const exportLine = EXPORT_REGEX.exec(contents);
+export function extractExports(contents: string): { exports: string; fnArgs: string } {
+  const exportRegex = /export\{(.*)\}/g;
+  const exportLine = exportRegex.exec(contents);
   let exports = '{}';
   let fnArgs = '{}';
 
@@ -111,8 +335,8 @@ export function extractExports(contents: string): { exports: string, fnArgs: str
   fnArgs = exports.replace(/(\w+)\s*as\s*(\w+)/g, '$1: $2').trim();
 
   if (exports === '{}' && fnArgs === '{}') {
-    exports = '* as _module'
-    fnArgs = '_module'
+    exports = '* as _module';
+    fnArgs = '_module';
   }
 
   return { exports, fnArgs };
@@ -120,8 +344,7 @@ export function extractExports(contents: string): { exports: string, fnArgs: str
 
 /**
  * Convert a function to a string (results in loss of context!)
- * Handles named, async, and arrow functions
  */
-export function functionToString(fn: any) {
-  return fn.toString().trim();
-}
+export function functionToString(fn: unknown) {
+  return (fn as (...args: unknown[]) => unknown).toString().trim();
+}

package/src/client/manifest.ts

@@ -0,0 +1,83 @@
+import type { Hyperspan as HS } from '../types';
+
+export type AssetManifest = {
+  imports: Record<string, string>;
+  css: Record<string, string[]>;
+  clients: Record<string, string>;
+};
+
+let _manifest: AssetManifest = {
+  imports: {},
+  css: {},
+  clients: {},
+};
+
+/**
+ * Set the build-time asset manifest (called by Vite plugin or build step).
+ */
+export function setAssetManifest(manifest: AssetManifest): void {
+  _manifest = manifest;
+}
+
+/**
+ * Get the current asset manifest.
+ */
+export function getAssetManifest(): AssetManifest {
+  return _manifest;
+}
+
+/**
+ * Resolve a module import name to its public URL.
+ */
+export function resolveImport(name: string): string | undefined {
+  return _manifest.imports[name];
+}
+
+/**
+ * Get CSS files for a route path.
+ */
+export function getRouteCss(path: string): string[] {
+  return _manifest.css[path] ?? [];
+}
+
+/**
+ * Build import map object for layout script tags.
+ */
+export function getImportMap(): Record<string, string> {
+  return { ..._manifest.imports };
+}
+
+/**
+ * Register a client module URL at runtime (dev fallback).
+ */
+export function registerImport(name: string, publicPath: string): void {
+  _manifest.imports[name] = publicPath;
+}
+
+export type ClientJSBuildResult = HS.ClientJSBuildResult;
+
+/**
+ * Create a ClientJSBuildResult from manifest data (replaces runtime Bun.build).
+ */
+export function getClientJSFromManifest(
+  moduleId: string,
+  _exportNames = 'default'
+): ClientJSBuildResult {
+  const publicPath = _manifest.clients[moduleId];
+  if (!publicPath) {
+    throw new Error(
+      `[Hyperspan] Client module "${moduleId}" not found in asset manifest. Run hyperspan build or start dev server.`
+    );
+  }
+
+  const esmName = publicPath.split('/').pop()?.replace('.js', '') ?? moduleId;
+
+  return {
+    assetHash: moduleId,
+    esmName,
+    publicPath,
+    renderScriptTag: () => {
+      throw new Error('renderScriptTag requires html template - use layout helpers instead');
+    },
+  };
+}

package/src/dev-bindings.ts

@@ -0,0 +1,14 @@
+/** Dev-only platform bindings (D1, KV, etc.) shared across Vite SSR modules. */
+let devBindings: unknown;
+
+export function setDevBindings(env: unknown): void {
+  devBindings = env;
+}
+
+export function getDevBindings(): unknown {
+  return devBindings;
+}
+
+export function clearDevBindingsForTests(): void {
+  devBindings = undefined;
+}

package/src/fetch-handler.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test } from 'vitest';
+import { createRoute, createServer } from './server';
+import { createFetchHandler, compileRoutePath } from './fetch-handler';
+import type { Hyperspan as HS } from './types';
+
+describe('compileRoutePath', () => {
+  test('matches static paths', () => {
+    const { pattern } = compileRoutePath('/about');
+    expect('/about'.match(pattern)).toBeTruthy();
+    expect('/about/'.match(pattern)).toBeTruthy();
+  });
+
+  test('matches dynamic params', () => {
+    const { pattern, paramNames } = compileRoutePath('/users/:id');
+    expect(paramNames).toEqual(['id']);
+    const match = '/users/42'.match(pattern);
+    expect(match?.[1]).toBe('42');
+  });
+
+  test('matches wildcard routes', () => {
+    const { pattern, paramNames } = compileRoutePath('/blog/*');
+    expect(paramNames).toEqual(['...slug']);
+    const match = '/blog/hello/world'.match(pattern);
+    expect(match?.[1]).toBe('hello/world');
+  });
+});
+
+describe('createFetchHandler', () => {
+  test('routes GET requests to matching handler', async () => {
+    const server = await createServer({
+      appDir: './app',
+      publicDir: './public',
+      plugins: [],
+    });
+
+    server.get('/hello', (c: HS.Context) => c.res.html('<h1>Hello</h1>'));
+
+    const fetch = createFetchHandler(server);
+    const response = await fetch(new Request('http://localhost/hello'));
+
+    expect(response.status).toBe(200);
+    expect(await response.text()).toBe('<h1>Hello</h1>');
+  });
+
+  test('returns 404 for unknown paths', async () => {
+    const server = await createServer({
+      appDir: './app',
+      publicDir: './public',
+      plugins: [],
+    });
+
+    const fetch = createFetchHandler(server);
+    const response = await fetch(new Request('http://localhost/missing'));
+
+    expect(response.status).toBe(404);
+  });
+
+  test('passes route params to context', async () => {
+    const server = await createServer({
+      appDir: './app',
+      publicDir: './public',
+      plugins: [],
+    });
+
+    const route = createRoute({ path: '/items/:id' }).get((c: HS.Context) =>
+      c.res.text(c.route.params.id ?? '')
+    );
+    server._routes.push(route);
+
+    const fetch = createFetchHandler(server);
+    const response = await fetch(new Request('http://localhost/items/abc'));
+
+    expect(await response.text()).toBe('abc');
+  });
+
+  test('preserves Cookie on the request passed to the route', async () => {
+    const server = await createServer({
+      appDir: './app',
+      publicDir: './public',
+      plugins: [],
+    });
+
+    const route = createRoute({ path: '/session' }).get((c: HS.Context) =>
+      c.res.text(c.req.raw.headers.get('cookie') ?? '')
+    );
+    server._routes.push(route);
+
+    const headers = new Headers({ cookie: 'session=abc' });
+    const request = new Request('http://localhost/session', { headers });
+    // Node's Request constructor strips Cookie; re-attach like Vite's nodeToWebRequest.
+    Object.defineProperty(request, 'headers', { value: headers });
+
+    const fetch = createFetchHandler(server);
+    const response = await fetch(request);
+
+    expect(await response.text()).toBe('session=abc');
+  });
+
+  test('redirects trailing slashes', async () => {
+    const server = await createServer({
+      appDir: './app',
+      publicDir: './public',
+      plugins: [],
+    });
+
+    server.get('/page', (c: HS.Context) => c.res.text('ok'));
+
+    const fetch = createFetchHandler(server);
+    const response = await fetch(new Request('http://localhost/page/', { redirect: 'manual' }));
+
+    expect(response.status).toBe(308);
+  });
+});