Package Exports

@b9g/platform
@b9g/platform/adapter-registry
@b9g/platform/adapter-registry.js
@b9g/platform/base-platform
@b9g/platform/base-platform.js
@b9g/platform/detection
@b9g/platform/detection.js
@b9g/platform/directory-storage
@b9g/platform/directory-storage.js
@b9g/platform/filesystem
@b9g/platform/filesystem.js
@b9g/platform/index
@b9g/platform/index.js
@b9g/platform/package.json
@b9g/platform/registry
@b9g/platform/registry.js
@b9g/platform/service-worker
@b9g/platform/service-worker.js
@b9g/platform/types
@b9g/platform/types.js
@b9g/platform/utils
@b9g/platform/utils.js
@b9g/platform/worker-pool
@b9g/platform/worker-pool.js
@b9g/platform/worker-web
@b9g/platform/worker-web.js

Readme

@b9g/platform

Universal platform abstraction for ServiceWorker-style applications with automatic platform detection and worker thread architecture.

Features

ServiceWorker Pattern: Load applications as ServiceWorker entrypoints
Multi-Platform: Node.js, Bun, Cloudflare Workers support
Auto-Detection: Automatic runtime detection with explicit override
Worker Architecture: Multi-worker concurrency with coordinated caching
Hot Reloading: VM module isolation for clean development reloads

Installation

npm install @b9g/platform

Platform Packages

Install platform-specific implementations:

# For Node.js
npm install @b9g/platform-node

# For Bun
npm install @b9g/platform-bun  

# For Cloudflare Workers
npm install @b9g/platform-cloudflare

Quick Start

import { createPlatform } from '@b9g/platform';

// Auto-detect platform
const platform = await createPlatform('auto');

// Load ServiceWorker app
const serviceWorker = await platform.loadServiceWorker('./app.js', {
  workerCount: 2,
  hotReload: true
});

// Create server
const server = platform.createServer(serviceWorker.handleRequest, {
  port: 3000,
  host: 'localhost'
});

await server.listen();

ServiceWorker Pattern

Write your app as a ServiceWorker entrypoint:

// app.js - ServiceWorker-style entrypoint
import { Router } from '@b9g/router';

const router = new Router();
router.get('/', () => new Response('Hello World!'));

// ServiceWorker lifecycle events
addEventListener('install', event => {
  console.log('App installing...');
});

addEventListener('activate', event => {
  console.log('App activated!');
});

// Handle fetch events
addEventListener('fetch', event => {
  event.respondWith(router.handler(event.request));
});

Platform Detection

import { 
  detectPlatform, 
  createPlatform,
  displayPlatformInfo 
} from '@b9g/platform';

// Detect current runtime
const detected = detectPlatform();
console.log(detected); // { runtime: 'bun', platforms: ['bun', 'node'] }

// Create platform instance
const platform = await createPlatform('bun', {
  // Platform-specific options
});

// Display platform information
displayPlatformInfo(detected);

Worker Architecture

const platform = await createPlatform('node');

const serviceWorker = await platform.loadServiceWorker('./app.js', {
  workerCount: 4,           // Number of worker threads
  hotReload: true,          // Enable hot reloading
  caches: {
    pages: { type: 'memory', maxEntries: 1000 },
    api: { type: 'memory', ttl: 300 }
  }
});

// Workers coordinate through PostMessage
// Each worker loads your ServiceWorker app
// Cache operations are coordinated across workers

Platform-Specific Features

Node.js Platform

import { createNodePlatform } from '@b9g/platform-node';

const platform = await createNodePlatform({
  // Node.js specific options
});

Bun Platform

import { createBunPlatform } from '@b9g/platform-bun';

const platform = await createBunPlatform({
  // Bun specific options  
});

Cloudflare Workers Platform

import { createCloudflarePlatform } from '@b9g/platform-cloudflare';

const platform = await createCloudflarePlatform({
  // Cloudflare specific options
});

API Reference

Platform Interface

interface Platform {
  loadServiceWorker(entrypoint: string, options: ServiceWorkerOptions): Promise<ServiceWorkerInstance>;
  createServer(handler: Handler, options: ServerOptions): Server;
  dispose(): Promise<void>;
}

ServiceWorker Options

interface ServiceWorkerOptions {
  workerCount?: number;
  hotReload?: boolean;
  caches?: CacheConfig;
}

Platform Detection

function detectPlatform(): PlatformDetection;
function createPlatform(platformName: string, options?: any): Promise<Platform>;
function displayPlatformInfo(detection: PlatformDetection): void;

Development vs Production

Development (2 workers default)

Encourages concurrency thinking from the start
Hot reloading with VM module isolation
Verbose logging and error reporting

Production (CPU count workers)

Maximum throughput with worker-per-core
Optimized cache coordination
Minimal logging overhead

Integration with CLI

The platform abstraction powers the Shovel CLI:

# Auto-detect and run
shovel develop app.js

# Explicit platform targeting
shovel develop app.js --platform=bun --workers=4

# Platform-specific builds
shovel build app.js --platform=cloudflare

License

MIT