@b9g/platform 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,215 @@
+# @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
+
+```bash
+npm install @b9g/platform
+```
+
+## Platform Packages
+
+Install platform-specific implementations:
+
+```bash
+# 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
+
+```javascript
+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:
+
+```javascript
+// 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
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+import { createNodePlatform } from '@b9g/platform-node';
+
+const platform = await createNodePlatform({
+  // Node.js specific options
+});
+```
+
+### Bun Platform
+
+```javascript
+import { createBunPlatform } from '@b9g/platform-bun';
+
+const platform = await createBunPlatform({
+  // Bun specific options  
+});
+```
+
+### Cloudflare Workers Platform
+
+```javascript
+import { createCloudflarePlatform } from '@b9g/platform-cloudflare';
+
+const platform = await createCloudflarePlatform({
+  // Cloudflare specific options
+});
+```
+
+## API Reference
+
+### Platform Interface
+
+```typescript
+interface Platform {
+  loadServiceWorker(entrypoint: string, options: ServiceWorkerOptions): Promise<ServiceWorkerInstance>;
+  createServer(handler: Handler, options: ServerOptions): Server;
+  dispose(): Promise<void>;
+}
+```
+
+### ServiceWorker Options
+
+```typescript
+interface ServiceWorkerOptions {
+  workerCount?: number;
+  hotReload?: boolean;
+  caches?: CacheConfig;
+}
+```
+
+### Platform Detection
+
+```typescript
+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:
+
+```bash
+# 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/platform",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Base Platform interface and types for Shovel deployment adapters",
   "keywords": [
     "shovel",
@@ -104,6 +104,22 @@
     "./directory-storage.js": {
       "types": "./src/directory-storage.d.ts",
       "import": "./src/directory-storage.js"
+    },
+    "./worker-pool": {
+      "types": "./src/worker-pool.d.ts",
+      "import": "./src/worker-pool.js"
+    },
+    "./worker-pool.js": {
+      "types": "./src/worker-pool.d.ts",
+      "import": "./src/worker-pool.js"
+    },
+    "./worker-web": {
+      "types": "./src/worker-web.d.ts",
+      "import": "./src/worker-web.js"
+    },
+    "./worker-web.js": {
+      "types": "./src/worker-web.d.ts",
+      "import": "./src/worker-web.js"
     }
   }
 }

package/src/base-platform.d.ts

@@ -12,10 +12,9 @@ export declare abstract class BasePlatform implements Platform {
     protected config: PlatformConfig;
     constructor(config?: PlatformConfig);
     abstract readonly name: string;
-    abstract readonly distDir: FileSystemDirectoryHandle;
     abstract loadServiceWorker(entrypoint: string, options?: any): Promise<any>;
     abstract createServer(handler: any, options?: any): any;
-    abstract getFileSystemRoot(bucketName: string): Promise<FileSystemDirectoryHandle>;
+    abstract getDirectoryHandle(name: string): Promise<FileSystemDirectoryHandle>;
     /**
      * Create cache storage with dynamic adapter loading
      * Uses platform defaults when specific cache types aren't configured

package/src/directory-storage.d.ts

@@ -1,41 +1,41 @@
 /**
- * Directory Storage implementation for ServiceWorker self.dirs API
+ * Bucket Storage implementation for ServiceWorker self.buckets API
  *
  * This implements the proposed web standard interface that parallels CacheStorage
  * for structured filesystem access in ServiceWorkers.
  */
-import type { DirectoryStorage } from "./service-worker.js";
+import type { BucketStorage as BucketStorageInterface } from "./service-worker.js";
 /**
- * Platform-agnostic directory storage implementation
- * Uses a single root directory with well-known subdirectories
+ * Platform-agnostic bucket storage implementation
+ * Uses bucket pattern where each bucket name maps to a separate filesystem root
  */
-export declare class PlatformDirectoryStorage implements DirectoryStorage {
-    private rootDir;
-    private cache;
-    constructor(rootDir: FileSystemDirectoryHandle);
+export declare class PlatformBucketStorage implements BucketStorageInterface {
+    private buckets;
+    constructor(rootPath?: string);
     /**
-     * Open a named directory - creates if it doesn't exist
-     * Well-known names: 'assets', 'static', 'server', 'client'
+     * Open a named bucket - creates if it doesn't exist
+     * Well-known names: 'assets', 'static', 'uploads', 'temp'
+     * Special values: '', '/', '.' return the root bucket
      */
     open(name: string): Promise<FileSystemDirectoryHandle>;
     /**
-     * Check if a named directory exists
+     * Check if a named bucket exists
      */
     has(name: string): Promise<boolean>;
     /**
-     * Delete a named directory and all its contents
+     * Delete a named bucket and all its contents
      */
     delete(name: string): Promise<boolean>;
     /**
-     * List all available directory names
+     * List all available bucket names
      */
     keys(): Promise<string[]>;
     /**
-     * Clear the cache (useful for hot reloading)
+     * Alias for open() - for compatibility with File System Access API naming
      */
-    clearCache(): void;
+    getDirectoryHandle(name: string): Promise<FileSystemDirectoryHandle>;
 }
 /**
- * Create a DirectoryStorage instance from a root directory
+ * Create a BucketStorage instance from a root path
  */
-export declare function createDirectoryStorage(rootDir: FileSystemDirectoryHandle): DirectoryStorage;
+export declare function createBucketStorage(rootPath?: string): BucketStorageInterface;

package/src/directory-storage.js

@@ -1,78 +1,53 @@
 /// <reference types="./directory-storage.d.ts" />
 // src/directory-storage.ts
-var PlatformDirectoryStorage = class {
-  rootDir;
-  cache = /* @__PURE__ */ new Map();
-  constructor(rootDir) {
-    this.rootDir = rootDir;
+import { BucketStorage, LocalBucket } from "@b9g/filesystem";
+var PlatformBucketStorage = class {
+  buckets;
+  constructor(rootPath = "./dist") {
+    this.buckets = new BucketStorage((name) => {
+      if (name === "" || name === "/" || name === ".") {
+        return new LocalBucket(rootPath);
+      }
+      return new LocalBucket(`${rootPath}/${name}`);
+    });
   }
   /**
-   * Open a named directory - creates if it doesn't exist
-   * Well-known names: 'assets', 'static', 'server', 'client'
+   * Open a named bucket - creates if it doesn't exist
+   * Well-known names: 'assets', 'static', 'uploads', 'temp'
+   * Special values: '', '/', '.' return the root bucket
    */
   async open(name) {
-    if (this.cache.has(name)) {
-      return this.cache.get(name);
-    }
-    try {
-      const dirHandle = await this.rootDir.getDirectoryHandle(name);
-      this.cache.set(name, dirHandle);
-      return dirHandle;
-    } catch (error) {
-      const dirHandle = await this.rootDir.getDirectoryHandle(name, { create: true });
-      this.cache.set(name, dirHandle);
-      return dirHandle;
-    }
+    return await this.buckets.open(name);
   }
   /**
-   * Check if a named directory exists
+   * Check if a named bucket exists
    */
   async has(name) {
-    try {
-      await this.rootDir.getDirectoryHandle(name);
-      return true;
-    } catch {
-      return false;
-    }
+    return await this.buckets.has(name);
   }
   /**
-   * Delete a named directory and all its contents
+   * Delete a named bucket and all its contents
    */
   async delete(name) {
-    try {
-      await this.rootDir.removeEntry(name, { recursive: true });
-      this.cache.delete(name);
-      return true;
-    } catch {
-      return false;
-    }
+    return await this.buckets.delete(name);
   }
   /**
-   * List all available directory names
+   * List all available bucket names
    */
   async keys() {
-    const keys = [];
-    try {
-      for await (const [name, handle] of this.rootDir.entries()) {
-        if (handle.kind === "directory") {
-          keys.push(name);
-        }
-      }
-    } catch {
-    }
-    return keys.sort();
+    return await this.buckets.keys();
   }
   /**
-   * Clear the cache (useful for hot reloading)
+   * Alias for open() - for compatibility with File System Access API naming
    */
-  clearCache() {
-    this.cache.clear();
+  async getDirectoryHandle(name) {
+    return await this.open(name);
   }
 };
-function createDirectoryStorage(rootDir) {
-  return new PlatformDirectoryStorage(rootDir);
+function createBucketStorage(rootPath = "./dist") {
+  return new PlatformBucketStorage(rootPath);
 }
 export {
-  PlatformDirectoryStorage,
-  createDirectoryStorage
+  PlatformBucketStorage,
+  createBucketStorage
 };

package/src/filesystem.d.ts

@@ -2,7 +2,15 @@
  * File System Access API implementation
  */
 /**
- * Get the file system root handle for the specified name
+ * Get the file system directory handle for the specified name
  * Auto-registers Node.js platform if no platform is detected
  */
+export declare function getDirectoryHandle(name: string): Promise<FileSystemDirectoryHandle>;
+/**
+ * @deprecated Use getDirectoryHandle() instead
+ */
+export declare function getBucket(name?: string): Promise<FileSystemDirectoryHandle>;
+/**
+ * @deprecated Use getDirectoryHandle() instead
+ */
 export declare function getFileSystemRoot(name?: string): Promise<FileSystemDirectoryHandle>;

package/src/filesystem.js

@@ -1,10 +1,20 @@
 /// <reference types="./filesystem.d.ts" />
 // src/filesystem.ts
 import { getPlatformAsync } from "./registry.js";
+async function getDirectoryHandle(name) {
+  const platform = await getPlatformAsync();
+  return await platform.getDirectoryHandle(name);
+}
+async function getBucket(name) {
+  const platform = await getPlatformAsync();
+  return await platform.getDirectoryHandle(name || "");
+}
 async function getFileSystemRoot(name) {
   const platform = await getPlatformAsync();
-  return await platform.getFileSystemRoot(name);
+  return await platform.getDirectoryHandle(name || "");
 }
 export {
+  getBucket,
+  getDirectoryHandle,
   getFileSystemRoot
 };

package/src/index.d.ts

@@ -6,9 +6,10 @@
  */
 export type { Platform, CacheConfig, CacheBackendConfig, ServerOptions, CorsConfig, Handler, Server, ServiceWorkerOptions, ServiceWorkerInstance, PlatformDetection, PlatformRegistry, } from "./types.js";
 export { BasePlatform } from "./types.js";
-export { ServiceWorkerRuntime, createServiceWorkerGlobals, type ShovelFetchEvent, type ShovelInstallEvent, type ShovelActivateEvent, type ShovelStaticEvent, type DirectoryStorage, } from "./service-worker.js";
-export { PlatformDirectoryStorage, createDirectoryStorage, } from "./directory-storage.js";
+export { ServiceWorkerRuntime, createServiceWorkerGlobals, type ShovelFetchEvent, type ShovelInstallEvent, type ShovelActivateEvent, type ShovelStaticEvent, type BucketStorage as BucketStorageInterface, } from "./service-worker.js";
+export { PlatformBucketStorage, createBucketStorage, } from "./directory-storage.js";
 export { platformRegistry, detectPlatform, getPlatform, getPlatformAsync, } from "./registry.js";
 export { detectRuntime, detectDevelopmentPlatform, detectPlatforms, getBestPlatformDetection, resolvePlatform, createPlatform, displayPlatformInfo, } from "./detection.js";
 export { parseTTL, mergeCacheConfig, validateCacheConfig, createCorsHeaders, mergeHeaders, isPreflightRequest, createPreflightResponse, } from "./utils.js";
-export { getFileSystemRoot } from "./filesystem.js";
+export { getDirectoryHandle, getBucket, getFileSystemRoot } from "./filesystem.js";
+export { WorkerPool, type WorkerFactory, type PlatformWorker, type WorkerPoolOptions } from "./worker-pool.js";

package/src/index.js

@@ -6,8 +6,8 @@ import {
   createServiceWorkerGlobals
 } from "./service-worker.js";
 import {
-  PlatformDirectoryStorage,
-  createDirectoryStorage
+  PlatformBucketStorage,
+  createBucketStorage
 } from "./directory-storage.js";
 import {
   platformRegistry,
@@ -33,13 +33,15 @@ import {
   isPreflightRequest,
   createPreflightResponse
 } from "./utils.js";
-import { getFileSystemRoot } from "./filesystem.js";
+import { getDirectoryHandle, getBucket, getFileSystemRoot } from "./filesystem.js";
+import { WorkerPool } from "./worker-pool.js";
 export {
   BasePlatform,
-  PlatformDirectoryStorage,
+  PlatformBucketStorage,
   ServiceWorkerRuntime,
+  WorkerPool,
+  createBucketStorage,
   createCorsHeaders,
-  createDirectoryStorage,
   createPlatform,
   createPreflightResponse,
   createServiceWorkerGlobals,
@@ -49,6 +51,8 @@ export {
   detectRuntime,
   displayPlatformInfo,
   getBestPlatformDetection,
+  getBucket,
+  getDirectoryHandle,
   getFileSystemRoot,
   getPlatform,
   getPlatformAsync,