@hyperspan/framework 0.0.3 → 0.1.0

package/README.md

@@ -1,83 +1,5 @@
-# Hyperspan. Simple. Full-Stack. Streaming.
+# @hyperspan/framework
 
-> [!NOTE] > **Hyperspan is still in the early stages of development, your feedback is appreciated.**
+> [!NOTE] > **The Hyperspan framework package is still in the heavy development. APIs may change without notice.**
 
-Hyperspan is a full-stack framework built with [Bun](https://bun.sh) that is focused on simplicity and ease of use.
-
-No JSX. No Virtual DOM. No hydration time. No nonsense. Just blazing fast HTML strings with reactive templates.
-
-## Who Is Hyperspan For?
-
-Hyperspan is best for websites, web applications, and APIs that need fast streaming and dynamic server responses. It is
-great for performance critical applications and delivers no client-side JavaScript by default. This helps to ensure your
-website stays fast and lightweight for end users as it grows over time, since all client JavaScript is explicitly
-opt-in.
-
-## Why Bun?
-
-[Bun](https://bun.sh) is a Node-compatible runtime that offers better performance and built-in TypeScript support so
-transpiling is not required for writing type-safe server-side code. Bun also offers some other extras like built-in
-ultra fast testing utilities so extra dependencies are not required to write high-quality code.
-
-## React vs. Hyperspan
-
-Hyperspan is not a React replacement. React is a client-side library to build interactive JavaScript based UIs.
-Hyperspan is a full-stack server-side framework built to deliver high-performance streaming and dynamic responses, and
-does not deliver any JavaScript to the client by default.
-
-Hyperspan can be best thought of as an _alternative_ to React-based frameworks like Next.js. It has all the same types
-of things, like file-based page routes, API routes, middleware, components, etc. but Hyperspan has a very different
-runtime and execution model. React-based frameworks ship all React components and code to the client by default,
-resulting in surprisingly large JS bundle sizes that grow more over time as your site does. Hyperspan takes the opposite
-approach, and does not ship ANY components to the client by default. Client components are available, but are explicitly
-opt-in and should generally be used sparingly.
-
-React is all JavaScript, all the time, delivered to the client. Hyperspan is mostly static content and markup delivered
-to the client, with JavaScript sprinkles where needed.
-
-## Philosophy
-
-### P1: Server-Side First.
-
-Current JavaScript frameworks ship everything to the browser by default and use non-intuitive ways to opt-out of this.
-The first clue that this approach was backwards was when JavaScript bundle sizes started being measured in hundreds of
-kilobytes to megabytes.
-
-Keeping bundle sizes down in large projects over time can be challenging. A full stack framework should render as much
-as possible on the server by default for better performance. Sending JavaScript code to the client and increasing bundle
-sizes for all your users should be explicit and opt-in.
-
-Modern frameworks make it too easy to _accidentally_ ship code to the client that you don't want. They often mix client
-and server concerns in a way that is hard to understand and keep separate. They return cryptic and confusing errors when
-you make mistakes around client and server boundaries.
-
-We've lost the forrest from the trees. The complixity has become too much, and users are paying the price.
-
-This is the way back for a full-stack framework:
-
-- Server fetching and rendering by default.
-- Minimal client-side JavaScript by default. Code that ships to the client should be explicit and opt-in.
-- Most of the work and state should be maintained on the server. The framework should help make this easy.
-
-### P2: Performance Oriented.
-
-Server-side code is fast because it sends HTML strings to the client and lets the browser do its job - the job that is
-was built specifically to do. There is no sense in typing up the JavaScript thread for rendering markup that can just be
-sent directly.
-
-You don't need a Virtual DOM or expensive reconciliation diff calculations to make interactive web sites or
-applications. You just need a more intelligent template that knows the pieces that update.
-
-HTML strings are the fastest and easiest way to update the parts of the DOM that change. We have known this since the
-Web 1.0 days of AJAX and template partials. Modern JavaScript built-ins like Tagged Template Literals are an obvious
-choice to do do the same thing today, and are built into the language.
-
-### P3: Works the Same In Every Context.
-
-All templates and components should be rendered asynchronously to allow you to do any other kind of asynchronous work in
-them that you need to, in any context that you do it in. It's just JavaScript. Not special framework-flavored
-JavaScript.
-
-There should be no difference in how a template or component is rendered in one context vs. another. It should not
-matter if a component runs on the client or the server, or fetches data or streams in. The core conceptual semantics
-should be the same everywhere.
+Full Hyperspan framework docs coming soon...

package/package.json

@@ -1,51 +1,51 @@
 {
   "name": "@hyperspan/framework",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "Hyperspan Web Framework",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "type": "module",
+  "module": "src/server.ts",
   "public": true,
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "bun ./build.ts",
-    "clean": "rm -rf dist",
-    "test": "bun test",
-    "prepack": "npm run clean && npm run build"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/vlucas/hyperspan-framework"
-  },
+  "author": "Vance Lucas <vance@vancelucas.com>",
+  "license": "BSD-3-Clause",
   "keywords": [
     "framework",
     "node",
     "bun",
-    "web",
-    "framework",
+    "web framework",
     "javascript",
-    "typescript"
+    "typescript",
+    "streaming",
+    "hypermedia"
   ],
-  "author": "Vance Lucas <vance@vancelucas.com>",
-  "license": "BSD-3-Clause",
+  "homepage": "https://www.hyperspan.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vlucas/hyperspan-framework"
+  },
   "bugs": {
     "url": "https://github.com/vlucas/hyperspan-framework/issues"
   },
-  "homepage": "https://www.hyperspan.dev",
-  "dependencies": {
-    "@fastify/deepmerge": "^2.0.0",
-    "@mjackson/headers": "^0.7.2",
-    "escape-html": "^1.0.3",
-    "isbot": "^5.1.17",
-    "trek-middleware": "^1.2.0",
-    "trek-router": "^1.2.0"
+  "scripts": {
+    "test": "bun test"
   },
   "devDependencies": {
-    "@types/bun": "^1.1.11",
-    "@types/escape-html": "^1.0.4",
-    "@types/node": "^22.7.5",
-    "bun-plugin-dts": "^0.3.0",
-    "typescript": "^5.6.3"
+    "@types/bun": "^1.1.9",
+    "@types/node": "^22.5.5",
+    "@types/react": "^19.1.0",
+    "bun-types": "latest",
+    "prettier": "^3.2.5"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@hyperspan/html": "^0.1.0",
+    "@preact/compat": "^18.3.1",
+    "hono": "^4.7.4",
+    "isbot": "^5.1.25",
+    "valibot": "^1.0.0-rc.3"
   }
 }

package/src/assets.ts

@@ -0,0 +1,141 @@
+import { html } from '@hyperspan/html';
+import { md5 } from './clientjs/md5';
+import { readdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+export const IS_PROD = process.env.NODE_ENV === 'production';
+const PWD = import.meta.dir;
+
+/**
+ * Build client JS for end users (minimal JS for Hyperspan to work)
+ */
+export const clientJSFiles = new Map<string, { src: string; type?: string }>();
+export async function buildClientJS() {
+  const sourceFile = resolve(PWD, '../', './hyperspan/clientjs/hyperspan-client.ts');
+  const output = await Bun.build({
+    entrypoints: [sourceFile],
+    outdir: `./public/_hs/js`,
+    naming: IS_PROD ? '[dir]/[name]-[hash].[ext]' : undefined,
+    minify: IS_PROD,
+  });
+
+  const jsFile = output.outputs[0].path.split('/').reverse()[0];
+  clientJSFiles.set('_hs', { src: '/_hs/js/' + jsFile });
+  return jsFile;
+}
+
+/**
+ * Find client CSS file built for end users
+ * @TODO: Build this in code here vs. relying on tailwindcss CLI tool from package scripts
+ */
+export const clientCSSFiles = new Map<string, string>();
+export async function buildClientCSS() {
+  if (clientCSSFiles.has('_hs')) {
+    return clientCSSFiles.get('_hs');
+  }
+
+  // Find file already built from tailwindcss CLI
+  const cssDir = './public/_hs/css/';
+  const cssFiles = await readdir(cssDir);
+  let foundCSSFile: string = '';
+
+  for (const file of cssFiles) {
+    // Only looking for CSS files
+    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}`);
+  }
+}
+
+/**
+ * Output HTML style tag for Hyperspan app
+ */
+export function hyperspanStyleTags() {
+  const cssFiles = Array.from(clientCSSFiles.entries());
+  return html`${cssFiles.map(
+    ([key, file]) => html`<link rel="stylesheet" href="/_hs/css/${file}" />`
+  )}`;
+}
+
+/**
+ * Output HTML script tag for Hyperspan app
+ * Required for functioning streaming so content can pop into place properly once ready
+ */
+export function hyperspanScriptTags() {
+  const jsFiles = Array.from(clientJSFiles.entries());
+  return html`
+    <script type="importmap">
+      {
+        "imports": {
+          "preact": "https://esm.sh/preact@10.26.4",
+          "preact/": "https://esm.sh/preact@10.26.4/",
+          "react": "https://esm.sh/preact@10.26.4/compat",
+          "react/": "https://esm.sh/preact@10.26.4/compat/",
+          "react-dom": "https://esm.sh/preact@10.26.4/compat"
+        }
+      }
+    </script>
+    ${jsFiles.map(
+      ([key, file]) =>
+        html`<script
+          id="js-${key}"
+          type="${file.type || 'text/javascript'}"
+          src="${file.src}"
+        ></script>`
+    )}
+  `;
+}
+
+/**
+ * Return a Preact component, mounted as an island in a <script> tag so it can be embedded into the page response.
+ */
+export async function createPreactIsland(file: string) {
+  let filePath = file.replace('file://', '');
+
+  let resultStr = 'import{h,render}from"preact";';
+  const build = await Bun.build({
+    entrypoints: [filePath],
+    minify: true,
+    external: ['react', 'preact'],
+    // @ts-ignore
+    env: 'APP_PUBLIC_*', // Inlines any ENV that starts with 'APP_PUBLIC_'
+  });
+
+  for (const output of build.outputs) {
+    resultStr += await output.text(); // string
+  }
+
+  // Find default export - this is our component
+  const r = /export\{([a-zA-Z]+) as default\}/g;
+  const matchExport = r.exec(resultStr);
+  const jsId = md5(resultStr);
+
+  if (!matchExport) {
+    throw new Error(
+      'File does not have a default export! Ensure a function has export default to use this.'
+    );
+  }
+
+  // Preact render/mount component
+  const fn = matchExport[1];
+  let _mounted = false;
+
+  // Return HTML that will embed this component
+  return (props: any) => {
+    if (!_mounted) {
+      _mounted = true;
+      resultStr += `render(h(${fn}, ${JSON.stringify(props)}), document.getElementById("${jsId}"));`;
+    }
+    return html.raw(
+      `<div id="${jsId}"></div><script type="module" data-source-id="${jsId}">${resultStr}</script>`
+    );
+  };
+}

package/src/clientjs/hyperspan-client.ts

@@ -1,7 +1,10 @@
-import { html, renderToString } from '../html';
-import { Idiomorph } from './idomorph.esm';
+import { html } from '../html';
+import { Idiomorph } from './idiomorph.esm';
 
-function setupAsyncContentObserver() {
+/**
+ * Used for streaming content from the server to the client.
+ */
+function htmlAsyncContentObserver() {
   if (typeof MutationObserver != 'undefined') {
     // Hyperspan - Async content loader
     // Puts streamed content in its place immediately after it is added to the DOM
@@ -41,178 +44,7 @@ function setupAsyncContentObserver() {
     asyncContentObserver.observe(document.body, { childList: true, subtree: true });
   }
 }
-setupAsyncContentObserver();
-
-/**
- * Event binding for added/updated content
- */
-function setupEventBindingObserver() {
-  if (typeof MutationObserver != 'undefined') {
-    const eventBindingObserver = new MutationObserver((list) => {
-      bindHyperspanEvents(document.body);
-    });
-    eventBindingObserver.observe(document.body, { childList: true, subtree: true });
-  }
-}
-setupEventBindingObserver();
-
-/**
- * Global Window assignments...
- */
-
-// @ts-ignore
-const hyperspan: any = {
-  _fn: new Map(),
-  wc: new Map(),
-  compIdOrLast(id?: string) {
-    let comp = hyperspan.wc.get(id);
-
-    // Get last component if id lookup failed
-    if (!comp) {
-      const lastComp = Array.from(hyperspan.wc).pop();
-      // @ts-ignore - The value returned from a Map is a tuple. The second value (lastComp[1]) is the actual value
-      comp = lastComp ? lastComp[1] : false;
-    }
-
-    return comp || false;
-  },
-  fn(id: string, ufn: any) {
-    const comp = this.compIdOrLast(id);
-
-    const fnd = {
-      id,
-      cid: comp ? comp.id : null,
-      fn: comp ? ufn.bind(comp) : ufn,
-      comp,
-    };
-
-    this._fn.set(id, fnd);
-  },
-  // Binds function execution to the component instance so 'this' keyword works as expected inside event handlers
-  fnc(id: string, ...args: any[]) {
-    const fnd = this._fn.get(id);
-
-    if (!fnd) {
-      console.log('[Hyperspan] Unable to find function with id ' + id);
-      return;
-    }
-
-    if (fnd.comp) {
-      fnd.fn.call(fnd.comp, ...args);
-    } else {
-      fnd.fn(...args);
-    }
-  },
-};
-
-/**
- * Web component (foundation of client components)
- */
-class HyperspanComponent extends HTMLElement {
-  constructor() {
-    super();
-  }
-
-  static get observedAttributes() {
-    return ['data-state'];
-  }
-
-  randomId() {
-    return Math.random().toString(36).substring(2, 9);
-  }
-
-  async render() {
-    let content = '<div>Loading...</div>';
-
-    const comp = hyperspan.wc.get(this.id);
-
-    if (comp) {
-      content = await renderToString(comp.render());
-    }
-
-    Idiomorph.morph(this, content, { morphStyle: 'innerHTML' });
-  }
-
-  connectedCallback() {
-    const comp = hyperspan.wc.get(this.id);
-
-    if (comp) {
-      comp.mount && comp.mount();
-    }
-  }
-
-  attributeChangedCallback() {
-    this.render();
-  }
-}
-
-// Bind events
-function bindHyperspanEvents(webComponentEl: HTMLElement) {
-  const domEvents = [
-    'click',
-    'dblclick',
-    'contextmenu',
-    'hover',
-    'focus',
-    'blur',
-    'mouseup',
-    'mousedown',
-    'touchstart',
-    'touchend',
-    'touchcancel',
-    'touchmove',
-    'submit',
-    'change',
-    'scroll',
-    'keyup',
-    'keydown',
-  ];
-  const eventEls = Array.from(
-    webComponentEl.querySelectorAll('[on' + domEvents.join('], [on') + ']')
-  );
-
-  for (let i = 0; i < eventEls.length; i++) {
-    const el = eventEls[i] as HTMLElement;
-    const elEvents = el.getAttributeNames();
-
-    elEvents
-      .filter((ev) => ev.startsWith('on'))
-      .map((event) => {
-        const fnId = el.getAttribute(event)?.replace('hyperspan:', '');
-
-        if (fnId && el.dataset[event] !== fnId) {
-          const eventName = event.replace('on', '');
-          el.addEventListener(eventName, globalEventDispatch);
-          el.dataset[event] = fnId;
-          el.removeAttribute(event);
-        }
-      });
-  }
-}
-
-// Proxies all events to the function they go to by event type
-function globalEventDispatch(e: Event) {
-  let el = e.target as HTMLElement;
-
-  if (el) {
-    const dataName = 'on' + e.type;
-    let fnId = el.dataset[dataName];
-
-    if (!fnId) {
-      el = el.closest('[data-' + dataName + ']') || el;
-    }
-
-    fnId = el.dataset[dataName];
-
-    if (fnId) {
-      hyperspan.fnc(fnId, e, el);
-    }
-  }
-}
-
-customElements.define('hs-wc', HyperspanComponent);
+htmlAsyncContentObserver();
 
-// @ts-ignore
-window.hyperspan = hyperspan;
 // @ts-ignore
 window.html = html;