@hyperspan/framework 1.0.0-alpha.8 → 1.0.0

package/src/client/js.ts

@@ -1,61 +1,94 @@
 import { html } from '@hyperspan/html';
+import { assetHash as assetHashFn } from '../utils';
+import { join } from 'node:path';
+import type { Hyperspan as HS } from '../types';
+
+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;
 
 /**
- * Render a client JS module as a script tag
+ * Build a client JS module and return a Hyperspan.ClientJSBuildResult object
  */
-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 buildClientJS(modulePathResolved: string): Promise<HS.ClientJSBuildResult> {
+  const modulePath = modulePathResolved.replace('file://', '');
+  const assetHash = assetHashFn(modulePath);
 
-  return html.raw(
-    // @ts-ignore
-    module.__CLIENT_JS.renderScriptTag({
-      loadScript: loadScript
-        ? typeof loadScript === 'string'
-          ? loadScript
-          : functionToString(loadScript)
-        : undefined,
-    })
-  );
-}
+  // Cache: Avoid re-processing the same file
+  if (!CLIENT_JS_CACHE.has(assetHash)) {
+    // 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_*',
+    });
 
-/**
- * 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;
+    // 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(assetHash, { esmName, exports, fnArgs, publicPath });
   }
 
-  const lines = str.split('\n');
-  const firstLine = lines[0];
-  const lastLine = lines[lines.length - 1];
+  const { esmName, exports, fnArgs, publicPath } = CLIENT_JS_CACHE.get(assetHash)!;
 
-  // Arrow function conversion
-  if (!lastLine?.includes('}')) {
-    return str.replace('=> ', '{ return ') + '; }';
-  }
+  return {
+    assetHash,
+    esmName,
+    publicPath,
+    renderScriptTag: (loadScript) => {
+      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>
+        `;
+      }
+      if (t === 'function') {
+        return html`
+          <script type="module" data-source-id="${assetHash}">import ${exports} from "${esmName}";\n(${html.raw(functionToString(loadScript))})(${fnArgs});</script>
+        `;
+      }
 
-  // Cleanup arrow function
-  if (firstLine.includes('=>')) {
-    return str.replace('=> ', '');
+      return html`
+        <script type="module" data-source-id="${assetHash}">import "${esmName}";</script>
+      `;
+    }
   }
+}
 
-  return 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();
 }

package/src/cookies.ts

@@ -0,0 +1,234 @@
+import type { Hyperspan as HS } from './types';
+
+const REGEXP_PAIR_SPLIT = /; */;
+
+/**
+ * RegExp to match field-content in RFC 7230 sec 3.2
+ *
+ * field-content = field-vchar [ 1*( SP / HTAB ) field-vchar ]
+ * field-vchar   = VCHAR / obs-text
+ * obs-text      = %x80-FF
+ */
+
+const REGEXP_FIELD_CONTENT = /^[\u0009\u0020-\u007e\u0080-\u00ff]+$/;
+
+/**
+ * Cookie parsing and serialization
+ */
+export class Cookies implements HS.Cookies {
+  _req: Request;
+  _responseHeaders: HS.Cookies['_responseHeaders'];
+  _parsedCookies: HS.Cookies['_parsedCookies'] = {};
+  _encrypt: HS.Cookies['_encrypt'];
+  _decrypt: HS.Cookies['_decrypt'];
+  constructor(req: Request, responseHeaders: HS.Cookies['_responseHeaders'] = undefined) {
+    this._req = req;
+    this._responseHeaders = responseHeaders;
+    this._parsedCookies = parse(req.headers.get('Cookie') || '');
+  }
+
+  get(name: string): string | undefined {
+    const value = this._parsedCookies[name];
+    if (value && this._decrypt) {
+      return this._decrypt(value);
+    }
+    return value;
+  }
+
+  set(name: string, value: string, options?: HS.CookieOptions) {
+    if (!this._responseHeaders) {
+      throw new Error('Set cookies in the response object. Cookies can only be read from the request object.');
+    }
+    if (this._encrypt) {
+      value = this._encrypt(value);
+    }
+    this._responseHeaders.append('Set-Cookie', serialize(name, value, options));
+  }
+
+  delete(name: string) {
+    this.set(name, '', { expires: new Date(0) });
+  }
+
+  /**
+   * Set the encoder and decoder functions for the cookies and re-parse the cookie header
+   */
+  setEncryption(encrypt: HS.Cookies['_encrypt'], decrypt: HS.Cookies['_decrypt']) {
+    this._encrypt = encrypt;
+    this._decrypt = decrypt;
+    this._parsedCookies = parse(this._req.headers.get('Cookie') || '');
+  }
+}
+
+/*!
+ * cookie
+ * @source https://github.com/jkohrman/cookie-parse/blob/master/index.js
+ * Copyright(c) 2012-2014 Roman Shtylman
+ * Copyright(c) 2015 Douglas Christopher Wilson
+ * Copyright(c) 2016 Jeff Kohrman
+ * MIT Licensed
+ */
+
+/**
+ * Parse a cookie header.
+ *
+ * Parse the given cookie header string into an object
+ * The object has the various cookies as keys(names) => values
+ *
+ * @param {string} str
+ * @param {object} [options]
+ * @return {object}
+ * @public
+ */
+
+function parse(str: string): Record<string, string | any | undefined> {
+  if (typeof str !== 'string') {
+    throw new TypeError('argument str must be a string');
+  }
+
+  const obj = {}
+  const pairs = str.split(REGEXP_PAIR_SPLIT);
+
+  for (let i = 0; i < pairs.length; i++) {
+    const pair = pairs[i];
+    let eq_idx = pair.indexOf('=');
+
+    // set true for things that don't look like key=value
+    let key;
+    let val;
+    if (eq_idx < 0) {
+      key = pair.trim();
+      val = 'true';
+    } else {
+      key = pair.substring(0, eq_idx).trim()
+      val = pair.substring(eq_idx + 1, eq_idx + 1 + pair.length).trim();
+    };
+
+    // quoted values
+    if ('"' == val[0]) {
+      val = val.slice(1, -1);
+    }
+
+    // only assign once
+    // @ts-ignore
+    if (undefined == obj[key]) {
+      // @ts-ignore
+      obj[key] = tryDecode(val, decodeURIComponent);
+    }
+  }
+
+  return obj;
+}
+
+/**
+ * Serialize data into a cookie header.
+ *
+ * Serialize the a name value pair into a cookie string suitable for
+ * http headers. An optional options object specified cookie parameters.
+ *
+ * serialize('foo', 'bar', { httpOnly: true })
+ *   => "foo=bar; httpOnly"
+ *
+ * @param {string} name
+ * @param {string} val
+ * @param {object} [options]
+ * @return {string}
+ * @public
+ */
+type SerializeOptions = {
+  encrypt?: (str: string) => string;
+  maxAge?: number;
+  domain?: string;
+  path?: string;
+  expires?: Date;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: 'lax' | 'strict' | true;
+};
+function serialize(name: string, val: string, options: SerializeOptions = {}) {
+  const opt = options || {};
+
+  if (!REGEXP_FIELD_CONTENT.test(name)) {
+    throw new TypeError('argument name is invalid');
+  }
+
+  let value = encodeURIComponent(val);
+
+  if (value && !REGEXP_FIELD_CONTENT.test(value)) {
+    throw new TypeError('argument val is invalid');
+  }
+
+  let str = name + '=' + value;
+
+  if (null != opt.maxAge) {
+    const maxAge = opt.maxAge - 0;
+    if (isNaN(maxAge)) throw new Error('maxAge should be a Number');
+    str += '; Max-Age=' + Math.floor(maxAge);
+  }
+
+  if (opt.domain) {
+    if (!REGEXP_FIELD_CONTENT.test(opt.domain)) {
+      throw new TypeError('option domain is invalid');
+    }
+
+    str += '; Domain=' + opt.domain;
+  }
+
+  if (opt.path) {
+    if (!REGEXP_FIELD_CONTENT.test(opt.path)) {
+      throw new TypeError('option path is invalid');
+    }
+
+    str += '; Path=' + opt.path;
+  }
+
+  if (opt.expires) {
+    if (typeof opt.expires.toUTCString !== 'function') {
+      throw new TypeError('option expires must be a Date object');
+    }
+
+    str += '; Expires=' + opt.expires.toUTCString();
+  }
+
+  if (opt.httpOnly) {
+    str += '; HttpOnly';
+  }
+
+  if (opt.secure) {
+    str += '; Secure';
+  }
+
+  if (opt.sameSite) {
+    const sameSite = typeof opt.sameSite === 'string'
+      ? opt.sameSite.toLowerCase() : opt.sameSite;
+
+    switch (sameSite) {
+      case true:
+      case 'strict':
+        str += '; SameSite=Strict';
+        break;
+      case 'lax':
+        str += '; SameSite=Lax';
+        break;
+      default:
+        throw new TypeError('option sameSite is invalid');
+    }
+  }
+
+  return str;
+}
+
+/**
+ * Try decoding a string using a decoding function.
+ *
+ * @param {string} str
+ * @param {function} decode
+ * @private
+ */
+
+function tryDecode(str: string, decode: (str: string) => string) {
+  try {
+    return decode(str);
+  } catch (e) {
+    return str;
+  }
+}

package/src/index.ts

@@ -1,2 +1,2 @@
-export { createConfig, createContext, createRoute, createServer, getRunnableRoute, StreamResponse, IS_PROD, HTTPException } from './server';
+export { createConfig, createContext, createRoute, createServer, getRunnableRoute, StreamResponse, IS_PROD, HTTPResponseException } from './server';
 export type { Hyperspan } from './types';

package/src/layout.ts

@@ -1,8 +1,10 @@
 import { html } from '@hyperspan/html';
-import { JS_IMPORT_MAP } from './client/js';
+import { JS_IMPORT_MAP, buildClientJS } from './client/js';
 import { CSS_PUBLIC_PATH, CSS_ROUTE_MAP } from './client/css';
 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
  */
@@ -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/middleware.ts

@@ -1,4 +1,91 @@
+import { formDataToJSON } from './utils';
+import { z, flattenError } from 'zod/v4';
+
+import type { ZodAny, ZodObject, ZodError } from 'zod/v4';
 import type { Hyperspan as HS } from './types';
+import { HTTPResponseException } from './server';
+
+export type TValidationType = 'json' | 'form' | 'urlencoded';
+
+/**
+ * Infer the validation type from the request Content-Type header
+ */
+function inferValidationType(headers: Headers): TValidationType {
+  const contentType = headers.get('content-type')?.toLowerCase() || '';
+
+  if (contentType.includes('application/json')) {
+    return 'json';
+  } else if (contentType.includes('multipart/form-data')) {
+    return 'form';
+  } else if (contentType.includes('application/x-www-form-urlencoded')) {
+    return 'urlencoded';
+  }
+
+  // Default to json if content-type is not recognized
+  return 'json';
+}
+
+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 | ZodAny): HS.MiddlewareFunction {
+  return async (context: HS.Context, next: HS.NextFunction) => {
+    const query = formDataToJSON(context.req.query);
+    const validated = schema.safeParse(query);
+
+    if (!validated.success) {
+      const err = formatZodError(validated.error);
+      return context.res.error(err, { status: 400 });
+    }
+
+    // Store the validated query in the context variables
+    context.vars.query = validated.data as z.infer<typeof schema>;
+
+    return next();
+  }
+}
+
+export function validateBody(schema: ZodObject | ZodAny, type?: TValidationType): HS.MiddlewareFunction {
+  return async (context: HS.Context, next: HS.NextFunction) => {
+    // Infer type from Content-Type header if not provided
+    const validationType = type || inferValidationType(context.req.headers);
+
+    let body: unknown = {};
+    if (validationType === 'json') {
+      body = await context.req.raw.json();
+    } else if (validationType === 'form') {
+      const formData = await context.req.formData();
+      body = formDataToJSON(formData as FormData);
+    } else if (validationType === 'urlencoded') {
+      const urlencoded = await context.req.urlencoded();
+      body = formDataToJSON(urlencoded);
+    }
+    const validated = schema.safeParse(body);
+
+    if (!validated.success) {
+      const err = formatZodError(validated.error);
+      throw new HTTPResponseException(err, { status: 400 });
+      //return context.res.error(err, { status: 400 });
+    }
+
+    // Store the validated body in the context variables
+    context.vars.body = validated.data as z.infer<typeof schema>;
+
+    return next();
+  }
+}
+
+export function formatZodError(error: ZodError): ZodValidationError {
+  const zodError = flattenError(error);
+  return new ZodValidationError(zodError);
+}
 
 /**
  * Type guard to check if a handler is a middleware function
@@ -55,4 +142,3 @@ export async function executeMiddleware(
   // Start execution from the first handler
   return await createNext(0)();
 }
-

package/src/server.test.ts

@@ -1,5 +1,5 @@
 import { test, expect } from 'bun:test';
-import { createRoute, createServer } from './server';
+import { createRoute, createServer, createContext } from './server';
 import type { Hyperspan as HS } from './types';
 
 test('route fetch() returns a Response', async () => {
@@ -89,3 +89,118 @@ test('returns 405 when route path matches but HTTP method does not', async () =>
   const text = await response.text();
   expect(text).toContain('Method not allowed');
 });
+
+test('createContext() can get and set cookies', () => {
+  // Create a request with cookies in the Cookie header
+  const request = new Request('http://localhost:3000/', {
+    headers: {
+      'Cookie': 'sessionId=abc123; theme=dark; userId=42',
+    },
+  });
+
+  // Create context from the request
+  const context = createContext(request);
+
+  // Test reading cookies from request
+  expect(context.req.cookies.get('sessionId')).toBe('abc123');
+  expect(context.req.cookies.get('theme')).toBe('dark');
+  expect(context.req.cookies.get('userId')).toBe('42');
+  expect(context.req.cookies.get('nonExistent')).toBeUndefined();
+
+  // Test setting a simple cookie in response
+  context.res.cookies.set('newCookie', 'newValue');
+  let setCookieHeader = context.res.headers.get('Set-Cookie');
+  expect(setCookieHeader).toBeTruthy();
+  expect(setCookieHeader).toContain('newCookie=newValue');
+
+  // Test setting a cookie with options (this should NOT overwrite the previous Set-Cookie header)
+  context.res.cookies.set('secureCookie', 'secureValue', {
+    httpOnly: true,
+    secure: true,
+    sameSite: 'strict',
+    maxAge: 3600,
+  });
+
+  // Verify Set-Cookie header contains the last cookie set
+  setCookieHeader = context.res.headers.get('Set-Cookie');
+  expect(setCookieHeader).toBeTruthy();
+  expect(setCookieHeader).toContain('secureCookie=secureValue');
+  expect(setCookieHeader).toContain('newCookie=newValue');
+
+  // Test deleting a cookie
+  context.res.cookies.delete('sessionId');
+  setCookieHeader = context.res.headers.get('Set-Cookie');
+  expect(setCookieHeader).toBeTruthy();
+  if (setCookieHeader) {
+    expect(setCookieHeader).toContain('sessionId=');
+    expect(setCookieHeader).toContain('Expires=');
+    // Verify it's set to expire in the past (deleted)
+    const expiresMatch = setCookieHeader.match(/Expires=([^;]+)/);
+    expect(expiresMatch).toBeTruthy();
+    if (expiresMatch) {
+      const expiresDate = new Date(expiresMatch[1]);
+      expect(expiresDate.getTime()).toBeLessThanOrEqual(new Date(0).getTime());
+    }
+  }
+});
+
+test('createContext() merge() function preserves custom headers when using response methods', () => {
+  // Create a request
+  const request = new Request('http://localhost:3000/');
+
+  // Create context from the request
+  const context = createContext(request);
+
+  // Set custom headers on the context response
+  context.res.headers.set('X-Custom-Header', 'custom-value');
+  context.res.headers.set('X-Another-Header', 'another-value');
+  context.res.headers.set('Authorization', 'Bearer token123');
+
+  // Use html() method which should merge headers
+  const response = context.res.html('<h1>Test</h1>');
+
+  // Verify the response has both the custom headers and the Content-Type header
+  expect(response.headers.get('X-Custom-Header')).toBe('custom-value');
+  expect(response.headers.get('X-Another-Header')).toBe('another-value');
+  expect(response.headers.get('Authorization')).toBe('Bearer token123');
+  expect(response.headers.get('Content-Type')).toBe('text/html; charset=UTF-8');
+
+  // Verify response body is correct
+  expect(response.status).toBe(200);
+});
+
+test('createContext() merge() function preserves custom headers with json() method', () => {
+  const request = new Request('http://localhost:3000/');
+  const context = createContext(request);
+
+  // Set custom headers
+  context.res.headers.set('X-API-Version', 'v1');
+  context.res.headers.set('X-Request-ID', 'req-123');
+
+  // Use json() method
+  const response = context.res.json({ message: 'Hello' });
+
+  // Verify headers are merged
+  expect(response.headers.get('X-API-Version')).toBe('v1');
+  expect(response.headers.get('X-Request-ID')).toBe('req-123');
+  expect(response.headers.get('Content-Type')).toBe('application/json');
+});
+
+test('createContext() merge() function allows response headers to override context headers', () => {
+  const request = new Request('http://localhost:3000/');
+  const context = createContext(request);
+
+  // Set a header on context
+  context.res.headers.set('X-Header', 'context-value');
+
+  // Use html() with options that include the same header (should override)
+  const response = context.res.html('<h1>Test</h1>', {
+    headers: {
+      'X-Header': 'response-value',
+    },
+  });
+
+  // Response header should override context header
+  expect(response.headers.get('X-Header')).toBe('response-value');
+  expect(response.headers.get('Content-Type')).toBe('text/html; charset=UTF-8');
+});