@hyperspan/framework 0.0.3 → 0.1.1

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/build.ts

@@ -1,29 +1,27 @@
+import {build} from 'bun';
 import dts from 'bun-plugin-dts';
 
-await Promise.all([
-  // Build JS
-  Bun.build({
-    entrypoints: ['./src/index.ts'],
-    outdir: './dist',
-    target: 'browser',
-  }),
-  Bun.build({
-    entrypoints: ['./src/server.ts'],
-    outdir: './dist',
-    target: 'node',
-  }),
+const filesToBuild = ['./src/index.ts', './src/server.ts', './src/assets.ts'];
+const outdir = './dist';
+const target = 'node';
 
-  // Build type files for TypeScript
-  Bun.build({
-    entrypoints: ['./src/index.ts'],
-    outdir: './dist',
-    target: 'browser',
-    plugins: [dts()],
-  }),
-  Bun.build({
-    entrypoints: ['./src/server.ts'],
-    outdir: './dist',
-    target: 'node',
-    plugins: [dts()],
-  }),
-]);
+await Promise.all(
+  filesToBuild.map((file) =>
+    Promise.all([
+      // Build JS
+      build({
+        entrypoints: [file],
+        outdir,
+        target,
+      }),
+
+      // Build type files for TypeScript
+      build({
+        entrypoints: [file],
+        outdir,
+        target,
+        plugins: [dts()],
+      }),
+    ])
+  )
+);

package/dist/assets.d.ts

@@ -0,0 +1,34 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/**
+ * Build client JS for end users (minimal JS for Hyperspan to work)
+ */
+export declare const clientJSFiles: Map<string, {
+	src: string;
+	type?: string;
+}>;
+export declare function buildClientJS(): Promise<string>;
+/**
+ * Find client CSS file built for end users
+ * @TODO: Build this in code here vs. relying on tailwindcss CLI tool from package scripts
+ */
+export declare const clientCSSFiles: Map<string, string>;
+export declare function buildClientCSS(): Promise<string | undefined>;
+/**
+ * Output HTML style tag for Hyperspan app
+ */
+export declare function hyperspanStyleTags(): import("@hyperspan/html").TmplHtml;
+/**
+ * Output HTML script tag for Hyperspan app
+ * Required for functioning streaming so content can pop into place properly once ready
+ */
+export declare function hyperspanScriptTags(): import("@hyperspan/html").TmplHtml;
+/**
+ * Return a Preact component, mounted as an island in a <script> tag so it can be embedded into the page response.
+ */
+export declare function createPreactIsland(file: string): Promise<(props: any) => {
+	_kind: string;
+	content: string;
+}>;
+
+export {};

package/dist/assets.js

@@ -0,0 +1,394 @@
+// node_modules/@hyperspan/html/dist/html.js
+/*!
+ * escape-html
+ * Copyright(c) 2012-2013 TJ Holowaychuk
+ * Copyright(c) 2015 Andreas Lubbe
+ * Copyright(c) 2015 Tiancheng "Timothy" Gu
+ * MIT Licensed
+ */
+var matchHtmlRegExp = /["'&<>]/;
+function escapeHtml(string) {
+  const str = "" + string;
+  const match = matchHtmlRegExp.exec(str);
+  if (!match) {
+    return str;
+  }
+  let escape;
+  let html = "";
+  let index = 0;
+  let lastIndex = 0;
+  for (index = match.index;index < str.length; index++) {
+    switch (str.charCodeAt(index)) {
+      case 34:
+        escape = "&quot;";
+        break;
+      case 38:
+        escape = "&amp;";
+        break;
+      case 39:
+        escape = "&#39;";
+        break;
+      case 60:
+        escape = "&lt;";
+        break;
+      case 62:
+        escape = "&gt;";
+        break;
+      default:
+        continue;
+    }
+    if (lastIndex !== index) {
+      html += str.substring(lastIndex, index);
+    }
+    lastIndex = index + 1;
+    html += escape;
+  }
+  return lastIndex !== index ? html + str.substring(lastIndex, index) : html;
+}
+
+class TmplHtml {
+  content = "";
+  asyncContent;
+  constructor(props) {
+    this.content = props.content;
+    this.asyncContent = props.asyncContent;
+  }
+}
+var htmlId = 0;
+function html(strings, ...values) {
+  const asyncContent = [];
+  let content = "";
+  for (let i = 0;i < strings.length; i++) {
+    let value = values[i];
+    let renderValue;
+    if (value !== null && value !== undefined) {
+      let id = `async_loading_${htmlId++}`;
+      let kind = _typeOf(value);
+      if (!renderValue) {
+        renderValue = _renderValue(value, { id, kind, asyncContent }) || "";
+      }
+    }
+    content += strings[i] + (renderValue ? renderValue : "");
+  }
+  return new TmplHtml({ content, asyncContent });
+}
+html.raw = (content) => ({ _kind: "html_safe", content });
+function _renderValue(value, opts = {
+  kind: undefined,
+  id: undefined,
+  asyncContent: []
+}) {
+  if (value === null || value === undefined || Number.isNaN(value)) {
+    return "";
+  }
+  const kind = opts.kind || _typeOf(value);
+  const id = opts.id || "";
+  switch (kind) {
+    case "array":
+      return value.map((v) => _renderValue(v, { id, asyncContent: opts.asyncContent })).join("");
+    case "object":
+      if (value instanceof TmplHtml) {
+        opts.asyncContent.push(...value.asyncContent);
+        return value.content;
+      }
+      if (value?._kind === "html_safe") {
+        return value?.content || "";
+      }
+      if (typeof value.renderAsync === "function") {
+        opts.asyncContent.push({
+          id,
+          promise: value.renderAsync().then((result) => ({
+            id,
+            value: result,
+            asyncContent: opts.asyncContent
+          }))
+        });
+      }
+      if (typeof value.render === "function") {
+        return render(_htmlPlaceholder(id, value.render()));
+      }
+      return JSON.stringify(value);
+    case "promise":
+      opts.asyncContent.push({
+        id,
+        promise: value.then((result) => ({
+          id,
+          value: result,
+          asyncContent: opts.asyncContent
+        }))
+      });
+      return render(_htmlPlaceholder(id));
+    case "generator":
+      throw new Error("Generators are not supported as a template value at this time. Sorry :(");
+  }
+  return escapeHtml(String(value));
+}
+function _htmlPlaceholder(id, content = "Loading...") {
+  return html`<!--hs:loading:${id}--><slot id="${id}">${content}</slot><!--/hs:loading:${id}-->`;
+}
+function render(tmpl) {
+  return tmpl.content;
+}
+function _typeOf(obj) {
+  if (obj instanceof Promise)
+    return "promise";
+  if (obj instanceof Date)
+    return "date";
+  if (obj instanceof String)
+    return "string";
+  if (obj instanceof Number)
+    return "number";
+  if (obj instanceof Boolean)
+    return "boolean";
+  if (obj instanceof Function)
+    return "function";
+  if (Array.isArray(obj))
+    return "array";
+  if (Number.isNaN(obj))
+    return "NaN";
+  if (obj === undefined)
+    return "undefined";
+  if (obj === null)
+    return "null";
+  if (isGenerator(obj))
+    return "generator";
+  return typeof obj;
+}
+function isGenerator(obj) {
+  return obj && typeof obj.next == "function" && typeof obj.throw == "function";
+}
+
+// src/clientjs/md5.js
+function md5cycle(x, k) {
+  var a = x[0], b = x[1], c = x[2], d = x[3];
+  a = ff(a, b, c, d, k[0], 7, -680876936);
+  d = ff(d, a, b, c, k[1], 12, -389564586);
+  c = ff(c, d, a, b, k[2], 17, 606105819);
+  b = ff(b, c, d, a, k[3], 22, -1044525330);
+  a = ff(a, b, c, d, k[4], 7, -176418897);
+  d = ff(d, a, b, c, k[5], 12, 1200080426);
+  c = ff(c, d, a, b, k[6], 17, -1473231341);
+  b = ff(b, c, d, a, k[7], 22, -45705983);
+  a = ff(a, b, c, d, k[8], 7, 1770035416);
+  d = ff(d, a, b, c, k[9], 12, -1958414417);
+  c = ff(c, d, a, b, k[10], 17, -42063);
+  b = ff(b, c, d, a, k[11], 22, -1990404162);
+  a = ff(a, b, c, d, k[12], 7, 1804603682);
+  d = ff(d, a, b, c, k[13], 12, -40341101);
+  c = ff(c, d, a, b, k[14], 17, -1502002290);
+  b = ff(b, c, d, a, k[15], 22, 1236535329);
+  a = gg(a, b, c, d, k[1], 5, -165796510);
+  d = gg(d, a, b, c, k[6], 9, -1069501632);
+  c = gg(c, d, a, b, k[11], 14, 643717713);
+  b = gg(b, c, d, a, k[0], 20, -373897302);
+  a = gg(a, b, c, d, k[5], 5, -701558691);
+  d = gg(d, a, b, c, k[10], 9, 38016083);
+  c = gg(c, d, a, b, k[15], 14, -660478335);
+  b = gg(b, c, d, a, k[4], 20, -405537848);
+  a = gg(a, b, c, d, k[9], 5, 568446438);
+  d = gg(d, a, b, c, k[14], 9, -1019803690);
+  c = gg(c, d, a, b, k[3], 14, -187363961);
+  b = gg(b, c, d, a, k[8], 20, 1163531501);
+  a = gg(a, b, c, d, k[13], 5, -1444681467);
+  d = gg(d, a, b, c, k[2], 9, -51403784);
+  c = gg(c, d, a, b, k[7], 14, 1735328473);
+  b = gg(b, c, d, a, k[12], 20, -1926607734);
+  a = hh(a, b, c, d, k[5], 4, -378558);
+  d = hh(d, a, b, c, k[8], 11, -2022574463);
+  c = hh(c, d, a, b, k[11], 16, 1839030562);
+  b = hh(b, c, d, a, k[14], 23, -35309556);
+  a = hh(a, b, c, d, k[1], 4, -1530992060);
+  d = hh(d, a, b, c, k[4], 11, 1272893353);
+  c = hh(c, d, a, b, k[7], 16, -155497632);
+  b = hh(b, c, d, a, k[10], 23, -1094730640);
+  a = hh(a, b, c, d, k[13], 4, 681279174);
+  d = hh(d, a, b, c, k[0], 11, -358537222);
+  c = hh(c, d, a, b, k[3], 16, -722521979);
+  b = hh(b, c, d, a, k[6], 23, 76029189);
+  a = hh(a, b, c, d, k[9], 4, -640364487);
+  d = hh(d, a, b, c, k[12], 11, -421815835);
+  c = hh(c, d, a, b, k[15], 16, 530742520);
+  b = hh(b, c, d, a, k[2], 23, -995338651);
+  a = ii(a, b, c, d, k[0], 6, -198630844);
+  d = ii(d, a, b, c, k[7], 10, 1126891415);
+  c = ii(c, d, a, b, k[14], 15, -1416354905);
+  b = ii(b, c, d, a, k[5], 21, -57434055);
+  a = ii(a, b, c, d, k[12], 6, 1700485571);
+  d = ii(d, a, b, c, k[3], 10, -1894986606);
+  c = ii(c, d, a, b, k[10], 15, -1051523);
+  b = ii(b, c, d, a, k[1], 21, -2054922799);
+  a = ii(a, b, c, d, k[8], 6, 1873313359);
+  d = ii(d, a, b, c, k[15], 10, -30611744);
+  c = ii(c, d, a, b, k[6], 15, -1560198380);
+  b = ii(b, c, d, a, k[13], 21, 1309151649);
+  a = ii(a, b, c, d, k[4], 6, -145523070);
+  d = ii(d, a, b, c, k[11], 10, -1120210379);
+  c = ii(c, d, a, b, k[2], 15, 718787259);
+  b = ii(b, c, d, a, k[9], 21, -343485551);
+  x[0] = add32(a, x[0]);
+  x[1] = add32(b, x[1]);
+  x[2] = add32(c, x[2]);
+  x[3] = add32(d, x[3]);
+}
+function cmn(q, a, b, x, s, t) {
+  a = add32(add32(a, q), add32(x, t));
+  return add32(a << s | a >>> 32 - s, b);
+}
+function ff(a, b, c, d, x, s, t) {
+  return cmn(b & c | ~b & d, a, b, x, s, t);
+}
+function gg(a, b, c, d, x, s, t) {
+  return cmn(b & d | c & ~d, a, b, x, s, t);
+}
+function hh(a, b, c, d, x, s, t) {
+  return cmn(b ^ c ^ d, a, b, x, s, t);
+}
+function ii(a, b, c, d, x, s, t) {
+  return cmn(c ^ (b | ~d), a, b, x, s, t);
+}
+function md51(s) {
+  var txt = "";
+  var n = s.length, state = [1732584193, -271733879, -1732584194, 271733878], i;
+  for (i = 64;i <= s.length; i += 64) {
+    md5cycle(state, md5blk(s.substring(i - 64, i)));
+  }
+  s = s.substring(i - 64);
+  var tail = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
+  for (i = 0;i < s.length; i++)
+    tail[i >> 2] |= s.charCodeAt(i) << (i % 4 << 3);
+  tail[i >> 2] |= 128 << (i % 4 << 3);
+  if (i > 55) {
+    md5cycle(state, tail);
+    for (i = 0;i < 16; i++)
+      tail[i] = 0;
+  }
+  tail[14] = n * 8;
+  md5cycle(state, tail);
+  return state;
+}
+function md5blk(s) {
+  var md5blks = [], i;
+  for (i = 0;i < 64; i += 4) {
+    md5blks[i >> 2] = s.charCodeAt(i) + (s.charCodeAt(i + 1) << 8) + (s.charCodeAt(i + 2) << 16) + (s.charCodeAt(i + 3) << 24);
+  }
+  return md5blks;
+}
+var hex_chr = "0123456789abcdef".split("");
+function rhex(n) {
+  var s = "", j = 0;
+  for (;j < 4; j++)
+    s += hex_chr[n >> j * 8 + 4 & 15] + hex_chr[n >> j * 8 & 15];
+  return s;
+}
+function hex(x) {
+  for (var i = 0;i < x.length; i++)
+    x[i] = rhex(x[i]);
+  return x.join("");
+}
+function add32(a, b) {
+  return a + b & 4294967295;
+}
+function md5(s) {
+  return hex(md51(s));
+}
+
+// src/assets.ts
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+var IS_PROD = false;
+var PWD = import.meta.dir;
+var clientJSFiles = new Map;
+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;
+}
+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(([key, file]) => html`<link rel="stylesheet" href="/_hs/css/${file}" />`)}`;
+}
+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>`)}
+  `;
+}
+async function createPreactIsland(file) {
+  let filePath = file.replace("file://", "");
+  let resultStr = 'import{h,render}from"preact";';
+  const build = await Bun.build({
+    entrypoints: [filePath],
+    minify: true,
+    external: ["react", "preact"],
+    env: "APP_PUBLIC_*"
+  });
+  for (const output of build.outputs) {
+    resultStr += await output.text();
+  }
+  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.");
+  }
+  const fn = matchExport[1];
+  let _mounted = false;
+  return (props) => {
+    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>`);
+  };
+}
+export {
+  hyperspanStyleTags,
+  hyperspanScriptTags,
+  createPreactIsland,
+  clientJSFiles,
+  clientCSSFiles,
+  buildClientJS,
+  buildClientCSS
+};