@hyperspan/framework 0.5.4 → 1.0.0-alpha.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@hyperspan/framework",
-  "version": "0.5.4",
+  "version": "1.0.0-alpha.0",
   "description": "Hyperspan Web Framework",
-  "main": "dist/server.ts",
+  "main": "src/server.ts",
   "types": "src/server.ts",
   "public": true,
   "publishConfig": {
@@ -11,23 +11,39 @@
   "exports": {
     ".": {
       "types": "./src/server.ts",
-      "default": "./dist/server.js"
+      "default": "./src/server.ts"
     },
     "./server": {
       "types": "./src/server.ts",
-      "default": "./dist/server.js"
-    },
-    "./assets": {
-      "types": "./src/assets.ts",
-      "default": "./dist/assets.js"
+      "default": "./src/server.ts"
     },
     "./middleware": {
       "types": "./src/middleware.ts",
-      "default": "./dist/middleware.js"
+      "default": "./src/middleware.ts"
+    },
+    "./middleware/zod": {
+      "types": "./src/middleware/zod.ts",
+      "default": "./src/middleware/zod.ts"
+    },
+    "./utils": {
+      "types": "./src/utils.ts",
+      "default": "./src/utils.ts"
+    },
+    "./layout": {
+      "types": "./src/layout.ts",
+      "default": "./src/layout.ts"
+    },
+    "./client/css": {
+      "types": "./src/client/css.ts",
+      "default": "./src/client/css.ts"
+    },
+    "./client/js": {
+      "types": "./src/client/js.ts",
+      "default": "./src/client/js.ts"
     },
-    "./unstable/actions": {
-      "types": "./src/actions.ts",
-      "default": "./src/actions.ts"
+    "./plugins": {
+      "types": "./src/plugins.ts",
+      "default": "./src/plugins.ts"
     }
   },
   "author": "Vance Lucas <vance@vancelucas.com>",
@@ -51,24 +67,16 @@
     "url": "https://github.com/vlucas/hyperspan/issues"
   },
   "scripts": {
-    "build": "bun ./build.ts && sed -i '' -e '$ d' dist/assets.js",
-    "clean": "rm -rf dist",
-    "test": "bun test",
-    "prepack": "bun run clean && bun run build"
+    "test": "bun test"
   },
   "devDependencies": {
-    "@types/bun": "^1.2.14",
-    "@types/node": "^22.15.20",
-    "@types/react": "^19.1.5",
-    "@types/timestring": "^7.0.0",
-    "prettier": "^3.5.3",
-    "typescript": "^5.8.3"
+    "@types/bun": "^1.3.1",
+    "@types/node": "^24.10.0",
+    "prettier": "^3.5.2",
+    "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@hyperspan/html": "0.1.7",
-    "hono": "^4.9.4",
-    "isbot": "^5.1.30",
-    "timestring": "^7.0.0",
-    "zod": "^4.1.5"
+    "@hyperspan/html": "0.2.0",
+    "zod": "^4.1.12"
   }
 }

package/src/callsites.ts

@@ -0,0 +1,17 @@
+
+export function callsites() {
+  const _prepareStackTrace = Error.prepareStackTrace;
+  try {
+    let result: NodeJS.CallSite[] = [];
+    Error.prepareStackTrace = (_, callSites) => {
+      const callSitesWithoutCurrent = callSites.slice(1);
+      result = callSitesWithoutCurrent;
+      return callSitesWithoutCurrent;
+    };
+
+    new Error().stack;
+    return result;
+  } finally {
+    Error.prepareStackTrace = _prepareStackTrace;
+  }
+}

package/src/client/css.ts

@@ -0,0 +1,2 @@
+export const CSS_PUBLIC_PATH = '/_hs/css';
+export const CSS_ROUTE_MAP = new Map<string, string[]>();

package/src/client/js.ts

@@ -0,0 +1,82 @@
+import { html } from '@hyperspan/html';
+import type { Hyperspan as HS } from '../types';
+
+
+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>();
+
+/**
+ * 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;
+}
+
+/**
+ * Island defaults
+ */
+export const ISLAND_DEFAULTS: () => HS.ClientIslandOptions = () => ({
+  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 'islandPlugins' option in your hyperspan.config.ts file?`
+  );
+}

package/src/layout.ts

@@ -0,0 +1,31 @@
+import { html } from '@hyperspan/html';
+import { JS_IMPORT_MAP } from './client/js';
+import { CSS_PUBLIC_PATH, CSS_ROUTE_MAP } from './client/css';
+import type { Hyperspan as HS } from './types';
+
+/**
+ * Output the importmap for the client so we can use ESModules on the client to load JS files on demand
+ */
+export function hyperspanScriptTags() {
+  return html`
+    <script type="importmap">
+      {"imports": ${Object.fromEntries(JS_IMPORT_MAP)}}
+    </script>
+  `;
+}
+
+/**
+ * Output style tags for the current route's CSS imports
+ */
+export function hyperspanStyleTags(context: HS.Context) {
+  const styleTags = [];
+  const cssImports = context.route.cssImports ?? CSS_ROUTE_MAP.get(context.route.path) ?? [];
+
+  for (const cssFile of cssImports) {
+    styleTags.push(html`
+      <link rel="stylesheet" href="${CSS_PUBLIC_PATH}/${cssFile}" />
+    `);
+  }
+
+  return styleTags;
+}

package/src/middleware/zod.ts

@@ -0,0 +1,46 @@
+import type { Hyperspan as HS } from '../types';
+import type { ZodAny, ZodObject, ZodError } from 'zod/v4';
+import { flattenError } from 'zod/v4';
+
+export class ZodValidationError extends Error {
+  constructor(flattened: ReturnType<typeof flattenError>) {
+    super('Input validation error(s)');
+    this.name = 'ZodValidationError';
+
+    // Copy all properties from flattened error
+    Object.assign(this, flattened);
+  }
+}
+
+export function validateQuery(schema: ZodObject): HS.MiddlewareFunction {
+  return async (context: HS.Context, next: HS.NextFunction) => {
+    const query: Record<string, string> = Object.fromEntries(context.req.query.entries());
+    const validated = schema.safeParse(query);
+
+    if (!validated.success) {
+      const err = formatZodError(validated.error);
+      return context.res.error(err, { status: 400 });
+    }
+
+    return next();
+  }
+}
+
+export function validateBody(schema: ZodObject | ZodAny): HS.MiddlewareFunction {
+  return async (context: HS.Context, next: HS.NextFunction) => {
+    const body = await context.req.body;
+    const validated = schema.safeParse(body);
+
+    if (!validated.success) {
+      const err = formatZodError(validated.error);
+      return context.res.error(err, { status: 400 });
+    }
+
+    return next();
+  }
+}
+
+export function formatZodError(error: ZodError): ZodValidationError {
+  const zodError = flattenError(error);
+  return new ZodValidationError(zodError);
+}

package/src/middleware.ts

@@ -1,19 +1,58 @@
-import { Context, Next } from 'hono';
-import { etag } from 'hono/etag';
-import timestring from 'timestring';
+import type { Hyperspan as HS } from './types';
 
 /**
- * Cache the response for a given time length ('30s', '1d', '1w', '1m', etc) or given number of seconds
+ * Type guard to check if a handler is a middleware function
+ * Middleware functions have 2 parameters (context, next)
+ * Route handlers have 1 parameter (context)
  */
-export function cacheTime(timeStrOrSeconds: string | number) {
-  return (c: Context, next: Next) =>
-    etag()(c, () => {
-      // Only cache GET requests
-      if (c.req.method.toUpperCase() === 'GET') {
-        const timeInSeconds =
-          typeof timeStrOrSeconds === 'number' ? timeStrOrSeconds : timestring(timeStrOrSeconds);
-        c.header('Cache-Control', `public, max-age=${timeInSeconds}`);
+function isMiddlewareFunction(
+  handler: HS.MiddlewareFunction | HS.RouteHandler
+): handler is HS.MiddlewareFunction {
+  return handler.length === 2;
+}
+
+/**
+ * Execute an array of middleware functions and route handlers
+ * Middleware functions receive (context, next) and can call next() to continue
+ * Route handlers receive (context) and are executed at the end of the chain
+ * 
+ * @param context - The Hyperspan context
+ * @param handlers - Array of middleware functions and/or route handlers
+ * @returns Promise<Response>
+ */
+export async function executeMiddleware(
+  context: HS.Context,
+  handlers: Array<HS.MiddlewareFunction | HS.RouteHandler>
+): Promise<Response> {
+  if (handlers.length === 0) {
+    return context.res.notFound();
+  }
+
+  /**
+   * Create the next function for middleware
+   * This function will execute the next handler in the chain
+   */
+  const createNext = (index: number): HS.NextFunction => {
+    return async (): Promise<Response> => {
+      if (index >= handlers.length) {
+        return context.res.notFound();
       }
-      return next();
-    });
+
+      const handler = handlers[index];
+
+      // If it's middleware, execute it with the next function
+      if (isMiddlewareFunction(handler)) {
+        const next = createNext(index + 1);
+        const result = await handler(context, next);
+        return result instanceof Response ? result : context.res.html(String(result));
+      }
+
+      // If it's a route handler, execute it and convert to Response
+      return await handler(context) as Response;
+    };
+  };
+
+  // Start execution from the first handler
+  return await createNext(0)();
 }
+

package/src/plugins.ts

@@ -1,65 +1,70 @@
-import { assetHash, CLIENTJS_PUBLIC_PATH, clientImportMap } from './assets';
-import { IS_PROD, type THSServerConfig } from './server';
+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 async function clientJSPlugin(config: THSServerConfig) {
-  // 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);
+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',
-          };
-        }
+          // 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: `./public/${CLIENTJS_PUBLIC_PATH}`,
-          naming: IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined,
-          external: Array.from(clientImportMap.keys()),
-          minify: true,
-          format: 'esm',
-          target: 'browser',
-          env: 'APP_PUBLIC_*',
-        });
+          // 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', '');
-        clientImportMap.set(esmName, `${CLIENTJS_PUBLIC_PATH}/${esmName}.js`);
+          // 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`);
 
-        const contents = await result.outputs[0].text();
-        const exportLine = EXPORT_REGEX.exec(contents);
+          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');
+          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
+          // 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/assets';
 
 // Original file contents
@@ -78,13 +83,14 @@ export const __CLIENT_JS = {
 }
 `;
 
-        CLIENT_JS_CACHE.set(jsId, moduleCode);
+          CLIENT_JS_CACHE.set(jsId, moduleCode);
 
-        return {
-          contents: moduleCode,
-          loader: 'js',
-        };
-      });
-    },
-  });
-}
+          return {
+            contents: moduleCode,
+            loader: 'js',
+          };
+        });
+      },
+    });
+  };
+}

package/src/server.test.ts

@@ -0,0 +1,88 @@
+import { test, expect } from 'bun:test';
+import { createRoute, createServer } from './server';
+import type { Hyperspan as HS } from './types';
+
+test('route fetch() returns a Response', async () => {
+  const route = createRoute().get((context) => {
+    return context.res.html('<h1>Hello World</h1>');
+  });
+
+  const request = new Request('http://localhost:3000/');
+  const response = await route.fetch(request);
+
+  expect(response).toBeInstanceOf(Response);
+  expect(response.status).toBe(200);
+  expect(await response.text()).toBe('<h1>Hello World</h1>');
+});
+
+test('server with two routes can return Response from one', async () => {
+  const server = createServer({
+    appDir: './app',
+    staticFileRoot: './public',
+  });
+
+  // Add two routes to the server
+  server.get('/users', (context) => {
+    return context.res.html('<h1>Users Page</h1>');
+  });
+
+  server.get('/posts', (context) => {
+    return context.res.html('<h1>Posts Page</h1>');
+  });
+
+
+  // Test that we can get a Response from one of the routes
+  const request = new Request('http://localhost:3000/users');
+  const testRoute = server._routes.find((route) => route._path === '/users');
+  const response = await testRoute!.fetch(request);
+
+  expect(response).toBeInstanceOf(Response);
+  expect(response.status).toBe(200);
+  expect(await response.text()).toContain('Users Page');
+});
+
+test('server returns a route with a POST request', async () => {
+  const server = createServer({
+    appDir: './app',
+    staticFileRoot: './public',
+  });
+
+  // Add two routes to the server
+  server.get('/users', (context) => {
+    return context.res.html('<h1>GET /users</h1>');
+  });
+
+  server.post('/users', (context) => {
+    return context.res.html('<h1>POST /users</h1>');
+  });
+
+  const route = server._routes.find((route) => route._path === '/users' && route._methods().includes('POST')) as HS.Route;
+  const request = new Request('http://localhost:3000/', { method: 'POST' });
+  const response = await route.fetch(request);
+
+  expect(response).toBeInstanceOf(Response);
+  expect(response.status).toBe(200);
+  expect(await response.text()).toBe('<h1>POST /users</h1>');
+});
+
+test('returns 405 when route path matches but HTTP method does not', async () => {
+  const server = createServer({
+    appDir: './app',
+    staticFileRoot: './public',
+  });
+
+  // Route registered for GET only
+  server.get('/users', (context) => {
+    return context.res.html('<h1>Users Page</h1>');
+  });
+
+  // Attempt to POST to /users, which should return 405
+  const route = server._routes.find((route) => route._path === '/users')!;
+  const request = new Request('http://localhost:3000/users', { method: 'POST' });
+  const response = await route.fetch(request);
+
+  expect(response).toBeInstanceOf(Response);
+  expect(response.status).toBe(405);
+  const text = await response.text();
+  expect(text).toContain('Method not allowed');
+});