@b9g/platform 0.1.0 → 0.1.2

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.0",
+  "version": "0.1.2",
   "description": "Base Platform interface and types for Shovel deployment adapters",
   "keywords": [
     "shovel",

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,37 @@
 /**
- * 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)
-     */
-    clearCache(): void;
 }
 /**
- * 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,47 @@
 /// <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();
-  }
-  /**
-   * Clear the cache (useful for hot reloading)
-   */
-  clearCache() {
-    this.cache.clear();
+    return await this.buckets.keys();
   }
 };
-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,9 @@
  */
 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";

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,13 @@ import {
   isPreflightRequest,
   createPreflightResponse
 } from "./utils.js";
-import { getFileSystemRoot } from "./filesystem.js";
+import { getDirectoryHandle, getBucket, getFileSystemRoot } from "./filesystem.js";
 export {
   BasePlatform,
-  PlatformDirectoryStorage,
+  PlatformBucketStorage,
   ServiceWorkerRuntime,
+  createBucketStorage,
   createCorsHeaders,
-  createDirectoryStorage,
   createPlatform,
   createPreflightResponse,
   createServiceWorkerGlobals,
@@ -49,6 +49,8 @@ export {
   detectRuntime,
   displayPlatformInfo,
   getBestPlatformDetection,
+  getBucket,
+  getDirectoryHandle,
   getFileSystemRoot,
   getPlatform,
   getPlatformAsync,

package/src/service-worker.d.ts

@@ -75,25 +75,25 @@ export declare class ServiceWorkerRuntime extends EventTarget {
     reset(): void;
 }
 /**
- * Directory storage interface - parallels CacheStorage for filesystem access
+ * Bucket storage interface - parallels CacheStorage for filesystem access
  * This could become a future web standard
  */
-export interface DirectoryStorage {
+export interface BucketStorage {
     /**
-     * Open a named directory - returns FileSystemDirectoryHandle
-     * Well-known names: 'assets', 'static', 'server', 'client'
+     * Open a named bucket - returns FileSystemDirectoryHandle (root of that bucket)
+     * Well-known names: 'assets', 'static', 'uploads', 'temp'
      */
     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[]>;
 }
@@ -102,7 +102,7 @@ export interface DirectoryStorage {
  */
 export declare function createServiceWorkerGlobals(runtime: ServiceWorkerRuntime, options?: {
     caches?: any;
-    dirs?: DirectoryStorage;
+    buckets?: BucketStorage;
 }): {
     self: ServiceWorkerRuntime;
     addEventListener: any;

package/src/service-worker.js

@@ -149,8 +149,8 @@ function createServiceWorkerGlobals(runtime, options = {}) {
   if (options.caches) {
     runtime.caches = options.caches;
   }
-  if (options.dirs) {
-    runtime.dirs = options.dirs;
+  if (options.buckets) {
+    runtime.buckets = options.buckets;
   }
   return {
     self: runtime,

package/src/types.d.ts

@@ -87,6 +87,8 @@ export interface FilesystemConfig {
         secretAccessKey?: string;
         token?: string;
     };
+    /** Factory function for creating directory storage */
+    factory?: any;
     /** Additional adapter-specific options */
     [key: string]: any;
 }
@@ -166,13 +168,18 @@ export interface ServiceWorkerInstance {
  */
 export interface Server {
     /** Start listening for requests */
-    listen(): Promise<void> | void;
+    listen(): Promise<void>;
     /** Stop the server */
-    close(): Promise<void> | void;
+    close(): Promise<void>;
+    /** Get server address information */
+    address(): {
+        port: number;
+        host: string;
+    };
     /** Get server URL */
-    url?: string;
-    /** Platform-specific server instance */
-    instance?: any;
+    readonly url: string;
+    /** Whether server is ready to accept requests */
+    readonly ready: boolean;
 }
 /**
  * Platform interface - ServiceWorker entrypoint loader for JavaScript runtimes
@@ -184,11 +191,6 @@ export interface Platform {
      * Platform name for identification
      */
     readonly name: string;
-    /**
-     * Build artifacts filesystem (install-time only)
-     * Available during install handlers to copy built files to runtime storage
-     */
-    readonly distDir: FileSystemDirectoryHandle;
     /**
      * THE MAIN JOB - Load and run a ServiceWorker-style entrypoint
      * This is where all the platform-specific complexity lives
@@ -202,16 +204,21 @@ export interface Platform {
      * - Bun: filesystem with optimized writes
      */
     createCaches(config?: CacheConfig): Promise<CacheStorage>;
+    /**
+     * SUPPORTING UTILITY - Create bucket storage with platform-optimized backends
+     * Uses factory pattern to route bucket names to different filesystem adapters
+     */
+    createBuckets(config?: FilesystemConfig): Promise<any>;
     /**
      * SUPPORTING UTILITY - Create server instance for this platform
      */
     createServer(handler: Handler, options?: ServerOptions): Server;
     /**
-     * SUPPORTING UTILITY - Get filesystem root for bucket/container name
+     * SUPPORTING UTILITY - Get filesystem directory handle
      * Maps directly to cloud storage buckets (S3, R2) or local directories
-     * @param bucketName - The bucket/container/directory name
+     * @param name - Directory name. Use "" for root directory
      */
-    getFileSystemRoot(bucketName: string): Promise<FileSystemDirectoryHandle>;
+    getDirectoryHandle(name: string): Promise<FileSystemDirectoryHandle>;
 }
 /**
  * Platform detection result