@hyperspan/framework 1.0.29 → 2.0.0-alpha.13

package/src/types.ts

@@ -63,13 +63,63 @@ export namespace Hyperspan {
     disableStreaming?: DisableStreamingFn;
   };
 
+  export type AdapterAfterBuildContext = {
+    root: string;
+    appDir: string;
+    outDir: string;
+  };
+
+  export type DeployEntryContext = {
+    createHyperspanServer: () => Promise<Server>;
+    config: Config;
+  };
+
+  export type DeployEntry = {
+    start?(options?: { port?: number }): unknown | Promise<unknown>;
+    fetch?(request: Request, env?: unknown, ctx?: unknown): Response | Promise<Response>;
+  };
+
+  export type Adapter = {
+    /** Diagnostic name, e.g. `node`, `cloudflare`. */
+    name: string;
+    /**
+     * Native ESM specifier exporting `resolveDevEnv(root)`.
+     * Imported by the Vite plugin so platform SDKs like wrangler load correctly.
+     */
+    devModule?: string;
+    resolveDevEnv?(root: string): Promise<unknown>;
+    /** Platform entry (`start` and/or `fetch`). Called from generated `dist/server.ts`. */
+    createEntry(ctx: DeployEntryContext): DeployEntry;
+    afterBuild?(ctx: AdapterAfterBuildContext): void | Promise<void>;
+  };
+
+  /** Runtime adapter object (`nodeAdapter()`, `cloudflareAdapter()`, …). */
+  export type DeployAdapter = Adapter;
+
+  export type ServerCreateContext = {
+    env: unknown;
+  };
+
   export type Config = {
     appDir: string;
     publicDir: string;
-    plugins: Array<Hyperspan.Plugin>; // Loaders for client islands
+    /** Island plugins (`preactPlugin()`, `sveltePlugin()`, …). */
+    plugins: Array<Hyperspan.Plugin>;
+    /**
+     * Deployment adapter. Pass `cloudflareAdapter()` or `bunAdapter()`.
+     * Omit (or pass `nodeAdapter()`) to deploy to Node.
+     */
+    deployAdapter: Adapter;
+    /**
+     * Called before the server is created, with platform bindings.
+     * - Vite/`hyperspan dev`: adapter `devModule` `resolveDevEnv(root)` when present; else `process.env`
+     * - Node/Bun production entry: `process.env`
+     * - Cloudflare Workers entry: Worker `env` bindings
+     */
+    beforeServerCreate?: (ctx: ServerCreateContext) => void | Promise<void>;
     // For customizing the routes and adding your own...
-    beforeRoutesAdded?: (server: Hyperspan.Server) => void;
-    afterRoutesAdded?: (server: Hyperspan.Server) => void;
+    beforeRoutesAdded?: (server: Hyperspan.Server) => void | Promise<void>;
+    afterRoutesAdded?: (server: Hyperspan.Server) => void | Promise<void>;
     responseOptions?: ResponseOptions;
   };
 
@@ -119,11 +169,23 @@ export namespace Hyperspan {
     merge: (response: Response) => Promise<Response>;
   };
 
+  export type UrlDiff = {
+    pathname?: string | null;
+    searchParams?: Record<string, string | number | boolean | null | undefined> | null;
+    hash?: string | null;
+  };
+
+  export type UrlOptions = {
+    /** When true, start from pathname only (drop current query string and hash). */
+    clean?: boolean;
+  };
+
   export interface Context {
     vars: Record<string, any>;
     route: RouteConfig;
     req: HSRequest;
     res: HSResponse;
+    url: (diff?: UrlDiff, options?: UrlOptions) => string;
   }
 
   export type ClientIslandOptions = {
@@ -375,6 +437,13 @@ export namespace Hyperspan {
   }
 }
 
+export type DeployAdapter = Hyperspan.DeployAdapter;
+export type ServerCreateContext = Hyperspan.ServerCreateContext;
+export type Adapter = Hyperspan.Adapter;
+export type AdapterAfterBuildContext = Hyperspan.AdapterAfterBuildContext;
+export type DeployEntry = Hyperspan.DeployEntry;
+export type DeployEntryContext = Hyperspan.DeployEntryContext;
+
 declare global {
   interface DocumentEventMap {
     'hs:action:before-fetch': CustomEvent<Hyperspan.ActionFetchDetail>;

package/src/utils.test.ts

@@ -1,5 +1,5 @@
-import { test, expect, describe } from 'bun:test';
-import { formDataToJSON, parsePath } from './utils';
+import { test, expect, describe } from 'vitest';
+import { buildUrl, formDataToJSON, parsePath } from './utils';
 
 describe('formDataToJSON', () => {
   test('formDataToJSON returns empty object for empty FormData', () => {
@@ -228,3 +228,73 @@ describe('parsePath', () => {
   });
 });
 
+describe('buildUrl', () => {
+  test('returns a new URL and does not mutate the base', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc#top');
+    const result = buildUrl(base, { searchParams: { page: 2 } });
+
+    expect(result).toBeInstanceOf(URL);
+    expect(result.pathname).toBe('/posts');
+    expect(result.search).toBe('?sort=asc&page=2');
+    expect(result.hash).toBe('#top');
+    expect(base.search).toBe('?sort=asc');
+    expect(base.hash).toBe('#top');
+  });
+
+  test('adds and overwrites search params', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc#top');
+    const result = buildUrl(base, { searchParams: { page: 2 } });
+
+    expect(`${result.pathname}${result.search}${result.hash}`).toBe('/posts?sort=asc&page=2#top');
+  });
+
+  test('removes search params with null values', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc&page=1#top');
+    const result = buildUrl(base, { searchParams: { sort: null, page: 3 } });
+
+    expect(`${result.pathname}${result.search}${result.hash}`).toBe('/posts?page=3#top');
+  });
+
+  test('clears all search params when searchParams is null', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc#top');
+    const result = buildUrl(base, { searchParams: null });
+
+    expect(`${result.pathname}${result.search}${result.hash}`).toBe('/posts#top');
+  });
+
+  test('changes pathname and clears hash', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc#top');
+    const result = buildUrl(base, { pathname: '/archive', hash: null, searchParams: null });
+
+    expect(`${result.pathname}${result.search}${result.hash}`).toBe('/archive');
+  });
+
+  test('preserves relative parts when diff is omitted', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc#top');
+    const result = buildUrl(base);
+
+    expect(`${result.pathname}${result.search}${result.hash}`).toBe('/posts?sort=asc#top');
+  });
+
+  test('stringifies boolean and number search values', () => {
+    const base = new URL('http://localhost:3000/posts');
+    const result = buildUrl(base, { searchParams: { active: true, page: 2 } });
+
+    expect(result.searchParams.get('active')).toBe('true');
+    expect(result.searchParams.get('page')).toBe('2');
+  });
+
+  test('clean: true drops existing query and hash before applying diff', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc#top');
+    const result = buildUrl(base, { searchParams: { page: 2 } }, { clean: true });
+
+    expect(`${result.pathname}${result.search}${result.hash}`).toBe('/posts?page=2');
+  });
+
+  test('pathname null resets to root', () => {
+    const base = new URL('http://localhost:3000/posts?sort=asc');
+    const result = buildUrl(base, { pathname: null });
+
+    expect(result.pathname).toBe('/');
+  });
+});

package/src/utils.ts

@@ -1,20 +1,36 @@
-import { createHash, randomBytes } from "node:crypto";
+import type { Hyperspan as HS } from './types';
+
+/**
+ * FNV-1a 64-bit hash — portable sync hash for asset IDs (works on Node, Bun, Workers).
+ */
+function fnv1a64(input: string): string {
+  let hash = BigInt('0xcbf29ce484222325');
+  const prime = BigInt('0x100000001b3');
+  const mask = BigInt('0xffffffffffffffff');
+  for (let i = 0; i < input.length; i++) {
+    hash ^= BigInt(input.charCodeAt(i));
+    hash = (hash * prime) & mask;
+  }
+  return hash.toString(16).padStart(16, '0');
+}
 
 export function assetHash(content: string): string {
-  return createHash('md5').update(content).digest('hex');
+  return fnv1a64(content);
 }
 
 export function randomHash(): string {
-  return createHash('md5').update(randomBytes(32).toString('hex')).digest('hex');
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+  return fnv1a64(hex);
 }
 
-
 /**
  * Normalize URL path
  * Removes trailing slash and lowercases path
  */
 const ROUTE_SEGMENT_REGEX = /(\[[a-zA-Z_\.]+\])/g;
-export function parsePath(urlPath: string): { path: string, params: string[] } {
+export function parsePath(urlPath: string): { path: string; params: string[] } {
   const params: string[] = [];
   urlPath = urlPath.replace('index', '').replace('.ts', '').replace('.js', '');
 
@@ -46,15 +62,14 @@ export function parsePath(urlPath: string): { path: string, params: string[] } {
 
   // Only lowercase non-param segments (do not lowercase after ':')
   return {
-    path: (
+    path:
       '/' +
       urlPath
         .split('/')
         .map((segment) =>
           segment.startsWith(':') || segment === '*' ? segment : segment.toLowerCase()
         )
-        .join('/')
-    ),
+        .join('/'),
     params,
   };
 }
@@ -75,7 +90,9 @@ export function isValidRoutePath(path: string): boolean {
  *
  * @link https://stackoverflow.com/a/75406413
  */
-export function formDataToJSON(formData: FormData | URLSearchParams): Record<string, string | string[]> {
+export function formDataToJSON(
+  formData: FormData | URLSearchParams
+): Record<string, string | string[]> {
   let object = {};
 
   /**
@@ -170,4 +187,43 @@ export function formDataToJSON(formData: FormData | URLSearchParams): Record<str
  */
 export function removeUndefined(obj: Record<string, any>): Record<string, any> {
   return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
-}
+}
+
+/**
+ * Build a new URL from a base URL and an optional diff.
+ * Does not mutate the base URL.
+ */
+export function buildUrl(base: URL, diff?: HS.UrlDiff, options?: HS.UrlOptions): URL {
+  const next = new URL(base);
+
+  if (options?.clean) {
+    next.search = '';
+    next.hash = '';
+  }
+
+  if (diff?.pathname === null) {
+    next.pathname = '/';
+  } else if (diff?.pathname !== undefined) {
+    next.pathname = diff.pathname;
+  }
+
+  if (diff?.searchParams === null) {
+    next.search = '';
+  } else if (diff?.searchParams !== undefined) {
+    for (const [key, value] of Object.entries(diff.searchParams)) {
+      if (value === null || value === undefined) {
+        next.searchParams.delete(key);
+      } else {
+        next.searchParams.set(key, String(value));
+      }
+    }
+  }
+
+  if (diff?.hash === null) {
+    next.hash = '';
+  } else if (diff?.hash !== undefined) {
+    next.hash = diff.hash;
+  }
+
+  return next;
+}

package/tsconfig.json

@@ -1,8 +1,9 @@
 {
   "compileOnSave": true,
+  "include": ["src/**/*.ts"],
   "compilerOptions": {
     "outDir": "dist",
-    "target": "es2019",
+    "target": "ES2020",
     "lib": ["ESNext", "dom", "dom.iterable"],
     "module": "esnext",
     "moduleResolution": "bundler",
@@ -10,7 +11,6 @@
     "esModuleInterop": true,
     "allowImportingTsExtensions": true,
     "noEmit": true,
-    "composite": true,
     "strict": true,
     "declaration": true,
     "sourceMap": true,
@@ -19,11 +19,7 @@
     "allowSyntheticDefaultImports": true,
     "forceConsistentCasingInFileNames": true,
     "allowJs": true,
-    "baseUrl": ".",
-    "paths": {
-      "@hyperspan/html": ["../html/src/html.ts"]
-    }
+    "baseUrl": "."
   },
-  "references": [{ "path": "../html" }],
-  "exclude": ["node_modules", "__tests__", "*.test.ts"]
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
 }