@b9g/platform-bun 0.1.14 → 0.1.16

package/README.md

@@ -1,83 +1,124 @@
 # @b9g/platform-bun
 
-Bun platform adapter for Shovel. Runs ServiceWorker applications on Bun with native HTTP server integration and fast hot reloading.
+Bun platform adapter for Shovel. Runs ServiceWorker applications on [Bun](https://bun.sh) with native HTTP server, WebSocket support, and OS-level load balancing via `reusePort`.
 
 ## Features
 
-- Bun HTTP server integration
-- Fast hot module reloading
-- Worker thread support for concurrency
-- Memory and filesystem cache backends
-- File System Access API implementation via BunBucket
+- Native `Bun.serve()` HTTP + WebSocket server
+- Built-in TypeScript/JSX support (no transpilation step)
+- Worker threads with `reusePort` for zero-overhead load balancing
+- Hot module reloading for development
+- ServiceWorker lifecycle support (install, activate, fetch events)
+- File System Access API via `@b9g/filesystem`
 
 ## Installation
 
 ```bash
-bun install @b9g/platform-bun
+bun add @b9g/platform-bun
 ```
 
 ## Usage
 
-```javascript
-import BunPlatform from '@b9g/platform-bun';
+### ServiceWorker Application
 
-const platform = new BunPlatform({
-  cache: { type: 'memory' },
-  filesystem: { type: 'local', directory: './dist' }
-});
+```typescript
+import BunPlatform from "@b9g/platform-bun";
 
-const server = platform.createServer(async (request) => {
-  return new Response('Hello from Bun');
-}, { port: 7777, host: 'localhost' });
+const platform = new BunPlatform({port: 3000, workers: 4});
+await platform.serviceWorker.register("./dist/server/worker.js");
+await platform.serviceWorker.ready;
+await platform.listen();
+```
+
+### Standalone Server
+
+```typescript
+import BunPlatform from "@b9g/platform-bun";
 
+const platform = new BunPlatform();
+const server = platform.createServer(async (request) => {
+  return new Response("Hello from Bun");
+});
 await server.listen();
 ```
 
 ## Exports
 
-### Classes
+- **`BunPlatform`** (default) -- Main platform class
+- **`BunServiceWorkerContainer`** -- ServiceWorker container managing worker lifecycle
+- **`BunPlatformOptions`** -- Constructor options type
+- **`DefaultCache`** -- Re-exported `MemoryCache` for config references
 
-- `BunPlatform` - Bun platform implementation (extends BasePlatform)
+## API
 
-### Types
+### `new BunPlatform(options?)`
 
-- `BunPlatformOptions` - Configuration options for BunPlatform
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `port` | `number` | `7777` | Server port |
+| `host` | `string` | `"localhost"` | Server host |
+| `cwd` | `string` | `process.cwd()` | Working directory |
+| `workers` | `number` | `1` | Number of worker threads |
+| `config` | `ShovelConfig` | -- | Shovel config (caches, directories) |
 
-### Re-exports from @b9g/platform
+### `platform.createServer(handler, options?)`
 
-- `Platform`, `CacheConfig`, `StaticConfig`, `Handler`, `Server`, `ServerOptions`
+Creates a Bun HTTP server with WebSocket upgrade support.
 
-### Default Export
+- **`handler`**: `(request: Request) => Promise<Response | HandleResult>`
+- **`options.port`**: Override port
+- **`options.host`**: Override host
+- **`options.reusePort`**: Enable OS-level load balancing (used in multi-worker production)
 
-- `BunPlatform` - The platform class
+Returns a `Server` with `listen()`, `close()`, `url`, `address()`, and `ready`.
 
-## API
+### `platform.serviceWorker`
 
-### `new BunPlatform(options?)`
+`BunServiceWorkerContainer` implementing the standard `ServiceWorkerContainer` interface:
+
+- **`register(scriptURL, options?)`** -- Register a ServiceWorker, spawns worker threads
+- **`ready`** -- Promise resolving when registration is active
+- **`getRegistration(scope?)`** / **`getRegistrations()`** -- Query registrations
+
+### `platform.getEntryPoints(userEntryPath, mode)`
+
+Returns generated entry point code for bundling. Used by the build system.
+
+- **Development**: `{worker}` -- Single worker with message loop
+- **Production**: `{supervisor, worker}` -- Supervisor spawns workers with `reusePort`
 
-Creates a new Bun platform instance.
+### `platform.getESBuildConfig()`
 
-**Options:**
-- `cache`: Cache configuration (memory, filesystem)
-- `filesystem`: Filesystem configuration (local directory)
-- `port`: Default port (default: 7777)
-- `host`: Default host (default: localhost)
-- `cwd`: Working directory for file resolution
+Returns Bun-specific esbuild configuration: `platform: "node"`, externals for `node:*`, `bun`, `bun:*`, and Node.js builtins.
 
-### `platform.createServer(handler, options)`
+## Worker Architecture
 
-Creates a Bun HTTP server with the given request handler.
+### Development
 
-**Options:**
-- `port`: Port to listen on
-- `host`: Host to bind to
+Single worker managed by the `shovel develop` CLI. The develop command owns the HTTP server; the worker handles requests via message loop.
+
+### Production
+
+Each worker creates its own `Bun.serve()` with `reusePort`, letting the OS kernel load-balance connections. No message passing overhead between supervisor and workers.
+
+```
+Supervisor (index.js)
+  ├── Worker 1 (worker.js) ── Bun.serve(:3000, reusePort)
+  ├── Worker 2 (worker.js) ── Bun.serve(:3000, reusePort)
+  └── Worker N (worker.js) ── Bun.serve(:3000, reusePort)
+```
 
-Returns a Server instance with `listen()` and `close()` methods.
+The supervisor handles graceful shutdown (SIGINT/SIGTERM) and BroadcastChannel relay between workers.
 
-## Cache Backends
+## How It Differs from @b9g/platform-node
 
-- `memory`: In-memory caching using MemoryCache
-- `filesystem`: Filesystem-based caching using BunBucket
+| | Bun | Node.js |
+|---|---|---|
+| **HTTP** | `Bun.serve()` | `node:http` + `ws` |
+| **WebSocket** | Built-in | Requires `ws` package |
+| **Load balancing** | OS-level via `reusePort` | Round-robin message passing |
+| **TypeScript** | Native support | VM module transpilation |
+| **Multi-worker** | Each worker binds own port | Supervisor distributes requests |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/platform-bun",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Bun platform adapter for Shovel with hot reloading and built-in TypeScript/JSX support",
   "keywords": [
     "shovel",
@@ -13,14 +13,14 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/bikeshaving/shovel.git",
+    "url": "git+https://github.com/bikeshaving/shovel.git",
     "directory": "packages/platform-bun"
   },
   "dependencies": {
     "@b9g/assets": "^0.2.1",
-    "@b9g/cache": "^0.2.1",
+    "@b9g/cache": "^0.2.2",
     "@b9g/http-errors": "^0.2.1",
-    "@b9g/platform": "^0.1.16",
+    "@b9g/platform": "^0.1.17",
     "@logtape/logtape": "^1.2.0"
   },
   "devDependencies": {

package/src/index.js

@@ -270,8 +270,8 @@ self.onmessage = async (event) => {
 	}
 };
 
-// Initialize worker runtime (installs ServiceWorker globals)
-const result = await initWorkerRuntime({config});
+// Initialize worker runtime (usePostMessage: false \u2014 worker owns its server, no message loop)
+const result = await initWorkerRuntime({config, usePostMessage: false});
 const registration = result.registration;
 databases = result.databases;
 
@@ -301,7 +301,8 @@ import {config} from "shovel:config";
 await configureLogging(config.logging);
 
 // Initialize worker runtime (installs ServiceWorker globals)
-const {registration, databases} = await initWorkerRuntime({config});
+// Single-worker dev mode uses direct cache (no PostMessage overhead)
+const {registration, databases} = await initWorkerRuntime({config, usePostMessage: config.workers > 1});
 
 // Import user code (registers event handlers)
 await import("${userEntryPath}");
@@ -368,7 +369,7 @@ process.on("SIGTERM", handleShutdown);
   getDefaults() {
     return {
       caches: {
-        default: {
+        "*": {
           module: "@b9g/cache/memory",
           export: "MemoryCache"
         }

package/src/platform.js

@@ -13,7 +13,8 @@ import {config} from "shovel:config";
 await configureLogging(config.logging);
 
 // Initialize worker runtime (installs ServiceWorker globals)
-const {registration, databases} = await initWorkerRuntime({config});
+// Single-worker dev mode uses direct cache (no PostMessage overhead)
+const {registration, databases} = await initWorkerRuntime({config, usePostMessage: config.workers > 1});
 
 // Import user code (registers event handlers)
 await import(${safePath});
@@ -50,8 +51,8 @@ self.onmessage = async (event) => {
 	}
 };
 
-// Initialize worker runtime (installs ServiceWorker globals)
-const result = await initWorkerRuntime({config});
+// Initialize worker runtime (usePostMessage: false \u2014 worker owns its server, no message loop)
+const result = await initWorkerRuntime({config, usePostMessage: false});
 const registration = result.registration;
 databases = result.databases;
 
@@ -115,7 +116,7 @@ function getESBuildConfig() {
 function getDefaults() {
   return {
     caches: {
-      default: {
+      "*": {
         module: "@b9g/cache/memory",
         export: "MemoryCache"
       }