@hyperspan/framework 0.5.5 → 1.0.0-alpha.1

package/src/types.ts

@@ -0,0 +1,110 @@
+/**
+ * Hyperspan Types
+ */
+export namespace Hyperspan {
+  export interface Server {
+    _config: Hyperspan.Config;
+    _routes: Array<Hyperspan.Route>;
+    _middleware: Array<Hyperspan.MiddlewareFunction>;
+    use: (middleware: Hyperspan.MiddlewareFunction) => Hyperspan.Server;
+    get: (path: string, handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
+    post: (path: string, handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
+    put: (path: string, handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
+    patch: (path: string, handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
+    delete: (path: string, handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
+    options: (path: string, handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
+  };
+
+  export type Plugin = (config: Hyperspan.Config) => Promise<void> | void;
+
+  export type Config = {
+    appDir: string;
+    publicDir: string;
+    plugins: Array<Hyperspan.Plugin>; // Loaders for client islands
+    // For customizing the routes and adding your own...
+    beforeRoutesAdded?: (server: Hyperspan.Server) => void;
+    afterRoutesAdded?: (server: Hyperspan.Server) => void;
+  };
+
+  export interface Context {
+    vars: Record<string, any>;
+    route: {
+      path: string;
+      params: Record<string, string>;
+      cssImports?: string[];
+    }
+    req: {
+      url: URL;
+      raw: Request;
+      method: string; // Always uppercase
+      headers: Headers; // Case-insensitive
+      query: URLSearchParams;
+      body: any;
+    };
+    res: {
+      headers: Headers; // Headers to merge with final outgoing response
+      html: (html: string, options?: { status?: number; headers?: Record<string, string> }) => Response
+      json: (json: any, options?: { status?: number; headers?: Record<string, string> }) => Response;
+      text: (text: string, options?: { status?: number; headers?: Record<string, string> }) => Response;
+      redirect: (url: string, options?: { status?: number; headers?: Record<string, string> }) => Response;
+      error: (error: Error, options?: { status?: number; headers?: Record<string, string> }) => Response;
+      notFound: (options?: { status?: number; headers?: Record<string, string> }) => Response;
+      raw: Response;
+    };
+  };
+
+  export type ClientIslandOptions = {
+    ssr?: boolean;
+    loading?: 'lazy' | undefined;
+  };
+
+  export type RouteConfig = {
+    name?: string;
+    path?: string;
+    cssImports?: string[];
+  };
+  export type RouteHandler = (context: Hyperspan.Context) => unknown;
+  export type RouteHandlerOptions = {
+    middleware?: Hyperspan.MiddlewareFunction[];
+  }
+
+  // TypeScript inference for typed   route params
+  // Source - https://stackoverflow.com/a/78170543
+  // Posted by jcalz
+  // Retrieved 2025-11-12, License - CC BY-SA 4.0
+  export type RouteParamsParser<T extends string, A = unknown> =
+    T extends `${string}:${infer F}/${infer R}` ? RouteParamsParser<R, A & Record<F, string>> :
+    (A & (T extends `${string}:${infer F}` ? Record<F, string> : unknown)) extends
+    infer U ? { [K in keyof U]: U[K] } : never
+
+
+  /**
+   * Next function type for middleware
+   */
+  export type NextFunction = () => Promise<Response>;
+
+  /**
+   * Middleware function signature
+   * Accepts context and next function, returns a Response
+   */
+  export type MiddlewareFunction = (
+    context: Hyperspan.Context,
+    next: Hyperspan.NextFunction
+  ) => Promise<Response> | Response;
+
+  export interface Route {
+    _kind: 'hsRoute';
+    _name: string | undefined;
+    _config: Hyperspan.RouteConfig;
+    _path(): string;
+    _methods(): string[];
+    get: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
+    post: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
+    put: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
+    patch: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
+    delete: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
+    options: (handler: Hyperspan.RouteHandler, handlerOptions?: Hyperspan.RouteHandlerOptions) => Hyperspan.Route;
+    middleware: (middleware: Array<Hyperspan.MiddlewareFunction>) => Hyperspan.Route;
+    fetch: (request: Request) => Promise<Response>;
+  };
+}

package/src/utils.ts

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto";
+
+export function assetHash(content: string): string {
+  return createHash('md5').update(content).digest('hex');
+}

package/build.ts

@@ -1,16 +0,0 @@
-import { build } from 'bun';
-
-const entrypoints = ['./src/server.ts', './src/assets.ts', './src/middleware.ts'];
-const external = ['@hyperspan/html'];
-const outdir = './dist';
-const target = 'node';
-const splitting = true;
-
-// Build JS
-await build({
-  entrypoints,
-  external,
-  outdir,
-  target,
-  splitting,
-});

package/dist/assets.js

@@ -1,120 +0,0 @@
-import"./chunk-atw8cdg1.js";
-
-// src/assets.ts
-import { html } from "@hyperspan/html";
-import { createHash } from "node:crypto";
-import { readdir } from "node:fs/promises";
-import { resolve } from "node:path";
-var IS_PROD = false;
-var PWD = import.meta.dir;
-var CLIENTJS_PUBLIC_PATH = "/_hs/js";
-var ISLAND_PUBLIC_PATH = "/_hs/js/islands";
-var clientImportMap = new Map;
-var clientJSFiles = new Map;
-async function buildClientJS() {
-  const sourceFile = resolve(PWD, "../", "./src/clientjs/hyperspan-client.ts");
-  const output = await Bun.build({
-    entrypoints: [sourceFile],
-    outdir: `./public/${CLIENTJS_PUBLIC_PATH}`,
-    naming: IS_PROD ? "[dir]/[name]-[hash].[ext]" : undefined,
-    minify: IS_PROD
-  });
-  const jsFile = output.outputs[0].path.split("/").reverse()[0];
-  clientJSFiles.set("_hs", { src: `${CLIENTJS_PUBLIC_PATH}/${jsFile}` });
-}
-function renderClientJS(module, loadScript) {
-  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(module.__CLIENT_JS.renderScriptTag({
-    loadScript: loadScript ? typeof loadScript === "string" ? loadScript : functionToString(loadScript) : undefined
-  }));
-}
-function functionToString(fn) {
-  let str = fn.toString().trim();
-  if (!str.includes("function ")) {
-    if (str.includes("async ")) {
-      str = "async function " + str.replace("async ", "");
-    } else {
-      str = "function " + str;
-    }
-  }
-  const lines = str.split(`
-`);
-  const firstLine = lines[0];
-  const lastLine = lines[lines.length - 1];
-  if (!lastLine?.includes("}")) {
-    return str.replace("=> ", "{ return ") + "; }";
-  }
-  if (firstLine.includes("=>")) {
-    return str.replace("=> ", "");
-  }
-  return str;
-}
-var clientCSSFiles = new Map;
-async function buildClientCSS() {
-  if (clientCSSFiles.has("_hs")) {
-    return clientCSSFiles.get("_hs");
-  }
-  const cssDir = "./public/_hs/css/";
-  const cssFiles = await readdir(cssDir);
-  let foundCSSFile = "";
-  for (const file of cssFiles) {
-    if (!file.endsWith(".css")) {
-      continue;
-    }
-    foundCSSFile = file.replace(cssDir, "");
-    clientCSSFiles.set("_hs", foundCSSFile);
-    break;
-  }
-  if (!foundCSSFile) {
-    console.log(`Unable to build CSS files from ${cssDir}`);
-  }
-}
-function hyperspanStyleTags() {
-  const cssFiles = Array.from(clientCSSFiles.entries());
-  return html`${cssFiles.map(([_, file]) => html`<link rel="stylesheet" href="/_hs/css/${file}" />`)}`;
-}
-function hyperspanScriptTags() {
-  const jsFiles = Array.from(clientJSFiles.entries());
-  return html`
-    <script type="importmap">
-      {"imports": ${Object.fromEntries(clientImportMap)}}
-    </script>
-    ${jsFiles.map(([key, file]) => html`<script
-          id="js-${key}"
-          type="${file.type || "text/javascript"}"
-          src="${file.src}"
-        ></script>`)}
-  `;
-}
-function assetHash(content) {
-  return createHash("md5").update(content).digest("hex");
-}
-var ISLAND_DEFAULTS = () => ({
-  ssr: true,
-  loading: undefined
-});
-function renderIsland(Component, props, options = ISLAND_DEFAULTS()) {
-  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 createServer() 'islandPlugins' config?`);
-}
-export {
-  renderIsland,
-  renderClientJS,
-  hyperspanStyleTags,
-  hyperspanScriptTags,
-  functionToString,
-  clientJSFiles,
-  clientImportMap,
-  clientCSSFiles,
-  buildClientJS,
-  buildClientCSS,
-  assetHash,
-  ISLAND_PUBLIC_PATH,
-  ISLAND_DEFAULTS,
-  CLIENTJS_PUBLIC_PATH
-};
-

package/dist/chunk-atw8cdg1.js

@@ -1,19 +0,0 @@
-var __create = Object.create;
-var __getProtoOf = Object.getPrototypeOf;
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __toESM = (mod, isNodeMode, target) => {
-  target = mod != null ? __create(__getProtoOf(mod)) : {};
-  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  for (let key of __getOwnPropNames(mod))
-    if (!__hasOwnProp.call(to, key))
-      __defProp(to, key, {
-        get: () => mod[key],
-        enumerable: true
-      });
-  return to;
-};
-var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
-
-export { __toESM, __commonJS };

package/dist/middleware.js

@@ -1,179 +0,0 @@
-import {
-  __commonJS,
-  __toESM
-} from "./chunk-atw8cdg1.js";
-
-// node_modules/timestring/index.js
-var require_timestring = __commonJS((exports, module) => {
-  module.exports = parseTimestring;
-  var DEFAULT_OPTS = {
-    hoursPerDay: 24,
-    daysPerWeek: 7,
-    weeksPerMonth: 4,
-    monthsPerYear: 12,
-    daysPerYear: 365.25
-  };
-  var UNIT_MAP = {
-    ms: ["ms", "milli", "millisecond", "milliseconds"],
-    s: ["s", "sec", "secs", "second", "seconds"],
-    m: ["m", "min", "mins", "minute", "minutes"],
-    h: ["h", "hr", "hrs", "hour", "hours"],
-    d: ["d", "day", "days"],
-    w: ["w", "week", "weeks"],
-    mth: ["mon", "mth", "mths", "month", "months"],
-    y: ["y", "yr", "yrs", "year", "years"]
-  };
-  function parseTimestring(value, returnUnit, opts) {
-    opts = Object.assign({}, DEFAULT_OPTS, opts || {});
-    if (typeof value === "number" || value.match(/^[-+]?[0-9.]+$/g)) {
-      value = parseInt(value) + "ms";
-    }
-    let totalSeconds = 0;
-    const unitValues = getUnitValues(opts);
-    const groups = value.toLowerCase().replace(/[^.\w+-]+/g, "").match(/[-+]?[0-9.]+[a-z]+/g);
-    if (groups === null) {
-      throw new Error(`The value [${value}] could not be parsed by timestring`);
-    }
-    groups.forEach((group) => {
-      const value2 = group.match(/[0-9.]+/g)[0];
-      const unit = group.match(/[a-z]+/g)[0];
-      totalSeconds += getSeconds(value2, unit, unitValues);
-    });
-    if (returnUnit) {
-      return convert(totalSeconds, returnUnit, unitValues);
-    }
-    return totalSeconds;
-  }
-  function getUnitValues(opts) {
-    const unitValues = {
-      ms: 0.001,
-      s: 1,
-      m: 60,
-      h: 3600
-    };
-    unitValues.d = opts.hoursPerDay * unitValues.h;
-    unitValues.w = opts.daysPerWeek * unitValues.d;
-    unitValues.mth = opts.daysPerYear / opts.monthsPerYear * unitValues.d;
-    unitValues.y = opts.daysPerYear * unitValues.d;
-    return unitValues;
-  }
-  function getUnitKey(unit) {
-    for (const key of Object.keys(UNIT_MAP)) {
-      if (UNIT_MAP[key].indexOf(unit) > -1) {
-        return key;
-      }
-    }
-    throw new Error(`The unit [${unit}] is not supported by timestring`);
-  }
-  function getSeconds(value, unit, unitValues) {
-    return value * unitValues[getUnitKey(unit)];
-  }
-  function convert(value, unit, unitValues) {
-    return value / unitValues[getUnitKey(unit)];
-  }
-});
-
-// node_modules/hono/dist/middleware/etag/digest.js
-var mergeBuffers = (buffer1, buffer2) => {
-  if (!buffer1) {
-    return buffer2;
-  }
-  const merged = new Uint8Array(new ArrayBuffer(buffer1.byteLength + buffer2.byteLength));
-  merged.set(new Uint8Array(buffer1), 0);
-  merged.set(buffer2, buffer1.byteLength);
-  return merged;
-};
-var generateDigest = async (stream, generator) => {
-  if (!stream) {
-    return null;
-  }
-  let result = undefined;
-  const reader = stream.getReader();
-  for (;; ) {
-    const { value, done } = await reader.read();
-    if (done) {
-      break;
-    }
-    result = await generator(mergeBuffers(result, value));
-  }
-  if (!result) {
-    return null;
-  }
-  return Array.prototype.map.call(new Uint8Array(result), (x) => x.toString(16).padStart(2, "0")).join("");
-};
-
-// node_modules/hono/dist/middleware/etag/index.js
-var RETAINED_304_HEADERS = [
-  "cache-control",
-  "content-location",
-  "date",
-  "etag",
-  "expires",
-  "vary"
-];
-var stripWeak = (tag) => tag.replace(/^W\//, "");
-function etagMatches(etag2, ifNoneMatch) {
-  return ifNoneMatch != null && ifNoneMatch.split(/,\s*/).some((t) => stripWeak(t) === stripWeak(etag2));
-}
-function initializeGenerator(generator) {
-  if (!generator) {
-    if (crypto && crypto.subtle) {
-      generator = (body) => crypto.subtle.digest({
-        name: "SHA-1"
-      }, body);
-    }
-  }
-  return generator;
-}
-var etag = (options) => {
-  const retainedHeaders = options?.retainedHeaders ?? RETAINED_304_HEADERS;
-  const weak = options?.weak ?? false;
-  const generator = initializeGenerator(options?.generateDigest);
-  return async function etag2(c, next) {
-    const ifNoneMatch = c.req.header("If-None-Match") ?? null;
-    await next();
-    const res = c.res;
-    let etag3 = res.headers.get("ETag");
-    if (!etag3) {
-      if (!generator) {
-        return;
-      }
-      const hash = await generateDigest(res.clone().body, generator);
-      if (hash === null) {
-        return;
-      }
-      etag3 = weak ? `W/"${hash}"` : `"${hash}"`;
-    }
-    if (etagMatches(etag3, ifNoneMatch)) {
-      c.res = new Response(null, {
-        status: 304,
-        statusText: "Not Modified",
-        headers: {
-          ETag: etag3
-        }
-      });
-      c.res.headers.forEach((_, key) => {
-        if (retainedHeaders.indexOf(key.toLowerCase()) === -1) {
-          c.res.headers.delete(key);
-        }
-      });
-    } else {
-      c.res.headers.set("ETag", etag3);
-    }
-  };
-};
-
-// src/middleware.ts
-var import_timestring = __toESM(require_timestring(), 1);
-function cacheTime(timeStrOrSeconds) {
-  return (c, next) => etag()(c, () => {
-    if (c.req.method.toUpperCase() === "GET") {
-      const timeInSeconds = typeof timeStrOrSeconds === "number" ? timeStrOrSeconds : import_timestring.default(timeStrOrSeconds);
-      c.header("Cache-Control", `public, max-age=${timeInSeconds}`);
-    }
-    return next();
-  });
-}
-export {
-  cacheTime
-};