@emkodev/emroute 1.6.1 → 1.6.2

package/README.md

@@ -22,7 +22,7 @@ GET /md/projects/42       → plain Markdown
 ## Install
 
 ```bash
-bun add @emkodev/emroute
+npm add @emkodev/emroute    # or bun add, pnpm add, yarn add
 ```
 
 > emroute ships TypeScript source. Your toolchain must handle `.ts` imports
@@ -116,18 +116,20 @@ export default new ProjectPage();
 - **Sitemap generation** — opt-in `sitemap.xml` from the routes manifest with support for dynamic route enumerators
 - **Dev server** — zero-config: auto-generates `main.ts`, `index.html`, and route/widget manifests. File watcher with hot reload and bundle serving
 
-## Why Bun?
+## Runtimes
 
-emroute 1.5.x shipped on JSR (Deno's registry). Starting with 1.6.0, emroute
-publishes to npm and targets Bun as the primary runtime.
+emroute ships two filesystem runtimes:
+
+- **`UniversalFsRuntime`** — uses only `node:` APIs and esbuild. Works on Node,
+  Deno, and Bun. The default choice for getting started.
+- **`BunFsRuntime`** — uses Bun-native APIs (`Bun.file()`, `Bun.write()`,
+  `Bun.Transpiler`) for better I/O performance in production on Bun.
 
-**TL;DR:** JSR's design freezes the entire module graph at publish time. This
-breaks dynamic `import()` of consumer dependencies, peer dependency
-deduplication, and runtime resolution of package entry points for bundling — all
-things a framework with plugin architecture needs. The npm/`node_modules` model
-handles them with zero friction.
+emroute ships TypeScript source. Your runtime must handle `.ts` imports natively
+(Bun, Deno) or via a loader (`tsx`, `node --experimental-strip-types`).
 
-Full analysis with documentation and issue references:
+emroute 1.5.x shipped on JSR (Deno's registry). Starting with 1.6.0, emroute
+publishes to npm. Full analysis:
 [ADR-0017 — Move to Bun ecosystem](doc/architecture/ADR-0017-move-to-bun-ecosystem.md).
 
 ## Getting Started
@@ -144,7 +146,7 @@ See [Setup](doc/01-setup.md) and [First Route](doc/02-first-route.md).
 - [Widgets](doc/06-widgets.md) — interactive islands with data lifecycle
 - [Server](doc/07-server.md) — `createEmrouteServer`, composition, static files
 - [Markdown renderers](doc/08-markdown-renderer.md) — pluggable parser interface and setup
-- [Runtime](doc/09-runtime.md) — abstract runtime, BunFsRuntime, BunSqliteRuntime
+- [Runtime](doc/09-runtime.md) — abstract runtime, UniversalFsRuntime, BunFsRuntime, BunSqliteRuntime
 - [SPA modes](doc/10-spa-mode.md) — none, leaf, root, only
 - [Error handling](doc/11-error-handling.md) — widget errors, boundaries, status pages
 - [Shadow DOM](doc/12-shadow-dom.md) — unified architecture, SSR hydration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emkodev/emroute",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "File-based router with triple rendering (SPA, SSR HTML, SSR Markdown). Zero dependencies.",
   "license": "BSD-3-Clause",
   "author": "emko.dev",
@@ -37,7 +37,8 @@
     "./runtime": "./runtime/abstract.runtime.ts",
     "./runtime/sitemap": "./runtime/sitemap.generator.ts",
     "./runtime/bun/fs": "./runtime/bun/fs/bun-fs.runtime.ts",
-    "./runtime/bun/sqlite": "./runtime/bun/sqlite/bun-sqlite.runtime.ts"
+    "./runtime/bun/sqlite": "./runtime/bun/sqlite/bun-sqlite.runtime.ts",
+    "./runtime/universal/fs": "./runtime/universal/fs/universal-fs.runtime.ts"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/runtime/universal/fs/universal-fs.runtime.ts

@@ -0,0 +1,253 @@
+import { readFile, writeFile, stat, readdir, mkdir } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import {
+  CONTENT_TYPES,
+  DEFAULT_ROUTES_DIR,
+  DEFAULT_WIDGETS_DIR,
+  EMROUTE_EXTERNALS,
+  type FetchParams,
+  type FetchReturn,
+  ROUTES_MANIFEST_PATH,
+  Runtime,
+  type RuntimeConfig,
+  WIDGETS_MANIFEST_PATH,
+} from '../../abstract.runtime.ts';
+import { createManifestPlugin } from '../../../server/esbuild-manifest.plugin.ts';
+import { createRuntimeLoaderPlugin } from '../../bun/esbuild-runtime-loader.plugin.ts';
+import { generateMainTs } from '../../../server/codegen.util.ts';
+
+/**
+ * Filesystem runtime using only `node:` APIs and esbuild. Works on Node,
+ * Deno, and Bun without platform-specific dependencies.
+ *
+ * Not recommended for production — `node:fs/promises` has higher overhead
+ * than platform-native alternatives (e.g. `Bun.file()`). Use
+ * {@link BunFsRuntime} on Bun for better I/O performance.
+ */
+export class UniversalFsRuntime extends Runtime {
+  private readonly root: string;
+
+  constructor(root: string, config: RuntimeConfig = {}) {
+    if (config.entryPoint && !config.bundlePaths) {
+      config.bundlePaths = { emroute: '/emroute.js', app: '/app.js' };
+    }
+    super(config);
+    const abs = resolve(root);
+    this.root = abs.endsWith('/') ? abs.slice(0, -1) : abs;
+  }
+
+  handle(
+    resource: FetchParams[0],
+    init?: FetchParams[1],
+  ): FetchReturn {
+    const [pathname, method, body] = this.parse(resource, init);
+    const path = `${this.root}${pathname}`;
+
+    switch (method) {
+      case 'PUT':
+        return this.write(path, body);
+      default:
+        return this.read(path);
+    }
+  }
+
+  query(
+    resource: FetchParams[0],
+    options: FetchParams[1] & { as: 'text' },
+  ): Promise<string>;
+  query(
+    resource: FetchParams[0],
+    options?: FetchParams[1],
+  ): FetchReturn;
+  query(
+    resource: FetchParams[0],
+    options?: FetchParams[1] & { as?: 'text' },
+  ): Promise<Response | string> {
+    if (options?.as === 'text') {
+      const pathname = this.parsePath(resource);
+      return readFile(`${this.root}${pathname}`, 'utf-8');
+    }
+    return this.handle(resource, options);
+  }
+
+  private parsePath(resource: FetchParams[0]): string {
+    if (typeof resource === 'string') return decodeURIComponent(resource);
+    if (resource instanceof URL) return decodeURIComponent(resource.pathname);
+    return decodeURIComponent(new URL(resource.url).pathname);
+  }
+
+  private parse(
+    resource: FetchParams[0],
+    init?: RequestInit,
+  ): [string, string, BodyInit | null] {
+    const pathname = this.parsePath(resource);
+    if (typeof resource === 'string' || resource instanceof URL) {
+      return [pathname, init?.method ?? 'GET', init?.body ?? null];
+    }
+    return [
+      pathname,
+      init?.method ?? resource.method,
+      init?.body ?? resource.body,
+    ];
+  }
+
+  private async read(path: string): Promise<Response> {
+    try {
+      const info = await stat(path);
+
+      if (info.isDirectory()) {
+        return this.list(path);
+      }
+
+      const content = new Uint8Array(await readFile(path));
+      const ext = path.slice(path.lastIndexOf('.')).toLowerCase();
+      const headers: HeadersInit = {
+        'Content-Type': CONTENT_TYPES.get(ext) ?? 'application/octet-stream',
+        'Content-Length': content.byteLength.toString(),
+      };
+
+      if (info.mtime) {
+        headers['Last-Modified'] = info.mtime.toUTCString();
+      }
+
+      return new Response(content, { status: 200, headers });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        const pathname = path.slice(this.root.length);
+        if (pathname === ROUTES_MANIFEST_PATH) return this.resolveRoutesManifest();
+        if (pathname === WIDGETS_MANIFEST_PATH) return this.resolveWidgetsManifest();
+        return new Response('Not Found', { status: 404 });
+      }
+      return new Response(`Internal Error: ${error}`, { status: 500 });
+    }
+  }
+
+  private async list(path: string): Promise<Response> {
+    const entries: string[] = [];
+    const dirents = await readdir(path, { withFileTypes: true });
+    for (const entry of dirents) {
+      entries.push(entry.name + (entry.isDirectory() ? '/' : ''));
+    }
+    return Response.json(entries);
+  }
+
+  private async write(path: string, body: BodyInit | null): Promise<Response> {
+    try {
+      const content = body
+        ? new Uint8Array(await new Response(body).arrayBuffer())
+        : new Uint8Array();
+      const dir = path.slice(0, path.lastIndexOf('/'));
+      if (dir) await mkdir(dir, { recursive: true });
+      await writeFile(path, content);
+      return new Response(null, { status: 204 });
+    } catch (error) {
+      return new Response(`Write failed: ${error}`, { status: 500 });
+    }
+  }
+
+  override loadModule(path: string): Promise<unknown> {
+    return import(this.root + path);
+  }
+
+  // ── Bundling ─────────────────────────────────────────────────────────
+
+  override async bundle(): Promise<void> {
+    if (this.config.spa === 'none') return;
+    const paths = this.config.bundlePaths;
+    if (!paths) return;
+
+    const esbuild = await UniversalFsRuntime.esbuild();
+    const builds: Promise<{ outputFiles: { path: string; contents: Uint8Array }[] }>[] = [];
+    const shared = { bundle: true, write: false, format: 'esm' as const, platform: 'browser' as const };
+    const runtimeLoader = createRuntimeLoaderPlugin({ runtime: this, root: this.root });
+
+    // Emroute SPA bundle — resolve from consumer's node_modules (no runtime loader needed)
+    const consumerRequire = createRequire(this.root + '/');
+    const spaEntry = consumerRequire.resolve('@emkodev/emroute/spa');
+    builds.push(esbuild.build({
+      ...shared,
+      entryPoints: [spaEntry],
+      outfile: `${this.root}${paths.emroute}`,
+    }));
+
+    // App bundle — generate main.ts if absent, virtual plugin resolves manifests
+    if (this.config.entryPoint) {
+      if ((await this.query(this.config.entryPoint)).status === 404) {
+        const hasRoutes = (await this.query((this.config.routesDir ?? DEFAULT_ROUTES_DIR) + '/')).status !== 404;
+        const hasWidgets = (await this.query((this.config.widgetsDir ?? DEFAULT_WIDGETS_DIR) + '/')).status !== 404;
+        const code = generateMainTs('root', hasRoutes, hasWidgets, '@emkodev/emroute');
+        await this.command(this.config.entryPoint, { body: code });
+      }
+      const manifestPlugin = createManifestPlugin({
+        runtime: this,
+        basePath: '/html',
+        resolveDir: this.root,
+      });
+      builds.push(esbuild.build({
+        ...shared,
+        entryPoints: [`${this.root}${this.config.entryPoint}`],
+        outfile: `${this.root}${paths.app}`,
+        external: [...EMROUTE_EXTERNALS],
+        plugins: [manifestPlugin, runtimeLoader],
+      }));
+    }
+
+    // Widgets bundle
+    if (paths.widgets) {
+      const widgetsTsPath = paths.widgets.replace('.js', '.ts');
+      if ((await this.query(widgetsTsPath)).status !== 404) {
+        builds.push(esbuild.build({
+          ...shared,
+          entryPoints: [`${this.root}${widgetsTsPath}`],
+          outfile: `${this.root}${paths.widgets}`,
+          external: [...EMROUTE_EXTERNALS],
+          plugins: [runtimeLoader],
+        }));
+      }
+    }
+
+    const results = await Promise.all(builds);
+
+    // Write all output files through the runtime
+    for (const result of results) {
+      for (const file of result.outputFiles) {
+        const runtimePath = file.path.startsWith(this.root)
+          ? file.path.slice(this.root.length)
+          : '/' + file.path;
+        await this.command(runtimePath, { body: file.contents as unknown as BodyInit });
+      }
+    }
+
+    await this.writeShell(paths);
+
+    await esbuild.stop();
+    UniversalFsRuntime._esbuild = null;
+  }
+
+  // ── Transpile / esbuild ───────────────────────────────────────────────
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private static _esbuild: any = null;
+
+  private static async esbuild() {
+    if (!UniversalFsRuntime._esbuild) {
+      const consumerRequire = createRequire(process.cwd() + '/');
+      UniversalFsRuntime._esbuild = consumerRequire('esbuild');
+    }
+    return UniversalFsRuntime._esbuild;
+  }
+
+  static override async transpile(source: string): Promise<string> {
+    const esbuild = await UniversalFsRuntime.esbuild();
+    const result = await esbuild.transform(source, { loader: 'ts' });
+    return result.code;
+  }
+
+  static override async stopBundler(): Promise<void> {
+    if (UniversalFsRuntime._esbuild) {
+      await UniversalFsRuntime._esbuild.stop();
+      UniversalFsRuntime._esbuild = null;
+    }
+  }
+}