@b9g/platform-node

Node.js platform adapter for Shovel. Runs ServiceWorker applications on Node.js with HTTP server integration, hot reloading, and worker thread concurrency.

Features

- Node.js HTTP server with Web API Request/Response conversion
- Hot module reloading for development via VM module system
- Worker thread pool for concurrent request handling
- Memory and filesystem cache backends
- File System Access API implementation via NodeFSDirectory
- ServiceWorker lifecycle support (install, activate, fetch events)

Installation

``bash
npm install @b9g/platform-node @b9g/platform @b9g/cache @b9g/filesystem
`

Usage

$3

`javascript
import NodePlatform from '@b9g/platform-node';

const platform = new NodePlatform({
caches: { type: 'memory' },
filesystem: { type: 'local', directory: './dist' }
});

const server = platform.createServer(async (request) => {
return new Response('Hello from Node.js');
}, { port: 7777, host: 'localhost' });

await server.listen();
console.log('Server running at http://localhost:7777');
`

$3

`javascript
import NodePlatform from '@b9g/platform-node';

const platform = new NodePlatform({
cwd: process.cwd()
});

// Load ServiceWorker entrypoint
const instance = await platform.loadServiceWorker('./src/server.js', {
workerCount: 4 // Number of worker threads
});

// ServiceWorker is now handling requests
`

Exports

$3

- NodePlatform - Node.js platform implementation (extends BasePlatform)

$3

- Platform, CacheConfig, StaticConfig, Handler, Server, ServerOptions

$3

- NodePlatform - The platform class

API

$3

Creates a new Node.js platform instance.

Options:
- caches: Cache configuration object (see @b9g/platform)
- filesystem: Filesystem configuration object
- port: Default port for servers (default: 7777)
- host: Default host for servers (default: localhost)
- cwd: Working directory for file resolution (default: process.cwd())

$3

Creates an HTTP server with automatic Request/Response conversion.

Parameters:
- handler: (request: Request) => Promise - Request handler function
- options: Server options (port, host)

Returns: Server instance with:
- listen(): Start the server
- close(): Stop the server
- url: Server URL (after listen)
- ready: Promise that resolves when server is ready

$3

Loads and runs a ServiceWorker entrypoint.

Parameters:
- entrypoint: Path to ServiceWorker entry file
- options: ServiceWorker options (workerCount, caches, etc.)

Returns: ServiceWorkerInstance with:
- handleRequest(request): Handle a request through the ServiceWorker
- ready: Promise that resolves when ServiceWorker is ready

Cache Backends

Configured via caches option:

- memory: In-memory caching (MemoryCache)
- filesystem`: File-based caching (NodeFSDirectory)

Worker Thread Architecture

The Node.js platform uses worker threads for true concurrency:

- Each worker runs the ServiceWorker code in isolation
- Round-robin load balancing across workers
- Shared cache storage coordinated via PostMessage
- Automatic request timeout (30s default)

License

MIT