@b9g/platform 0.1.3 → 0.1.5

package/README.md

@@ -1,14 +1,14 @@
 # @b9g/platform
 
-Universal platform abstraction for ServiceWorker-style applications with automatic platform detection and worker thread architecture.
+**ServiceWorker-first universal deployment platform. Write ServiceWorker apps once, deploy anywhere (Node/Bun/Cloudflare). Registry-based multi-app orchestration.**
 
 ## 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
+- **ServiceWorkerContainer Registry**: Manage multiple ServiceWorker apps by scope
+- **Complete ServiceWorker API**: Full MDN spec implementation for any JavaScript runtime
+- **Multi-App Orchestration**: Deploy multiple ServiceWorkers with scope-based routing
+- **Universal Platform Support**: Node.js, Bun, Cloudflare Workers with identical APIs
+- **Standards Compliance**: Full ServiceWorker specification compliance
 
 ## Installation
 
@@ -39,14 +39,19 @@ 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 ServiceWorker registry
+const container = await platform.createServiceWorkerContainer();
+
+// Register multiple ServiceWorker apps by scope
+await container.register('/api-worker.js', { scope: '/api/' });
+await container.register('/admin-worker.js', { scope: '/admin/' });
+await container.register('/app-worker.js', { scope: '/' });
 
-// Create server
-const server = platform.createServer(serviceWorker.handleRequest, {
+// Install and activate all ServiceWorkers
+await container.installAll();
+
+// Create server that routes to appropriate ServiceWorker
+const server = platform.createServer(container.handleRequest.bind(container), {
   port: 3000,
   host: 'localhost'
 });
@@ -54,18 +59,39 @@ const server = platform.createServer(serviceWorker.handleRequest, {
 await server.listen();
 ```
 
-## ServiceWorker Pattern
+## ServiceWorker Registry Pattern
 
-Write your app as a ServiceWorker entrypoint:
+Deploy multiple ServiceWorker applications with scope-based routing:
 
 ```javascript
-// app.js - ServiceWorker-style entrypoint
+// api-worker.js - API ServiceWorker
+import { Router } from '@b9g/router';
+
+const router = new Router();
+router.get('/users', () => Response.json({ users: [] }));
+router.get('/posts', () => Response.json({ posts: [] }));
+
+addEventListener('install', event => {
+  console.log('API service installing...');
+});
+
+addEventListener('activate', event => {
+  console.log('API service activated!');
+});
+
+addEventListener('fetch', event => {
+  event.respondWith(router.handler(event.request));
+});
+```
+
+```javascript
+// app-worker.js - Main app ServiceWorker
 import { Router } from '@b9g/router';
 
 const router = new Router();
 router.get('/', () => new Response('Hello World!'));
+router.get('/about', () => new Response('About page'));
 
-// ServiceWorker lifecycle events
 addEventListener('install', event => {
   console.log('App installing...');
 });
@@ -74,12 +100,17 @@ addEventListener('activate', event => {
   console.log('App activated!');
 });
 
-// Handle fetch events
 addEventListener('fetch', event => {
   event.respondWith(router.handler(event.request));
 });
 ```
 
+**Registry automatically routes requests:**
+- `/api/users` → `api-worker.js` 
+- `/api/posts` → `api-worker.js`
+- `/` → `app-worker.js`
+- `/about` → `app-worker.js`
+
 ## Platform Detection
 
 ```javascript
@@ -107,7 +138,7 @@ displayPlatformInfo(detected);
 ```javascript
 const platform = await createPlatform('node');
 
-const serviceWorker = await platform.loadServiceWorker('./app.js', {
+const serviceWorker = await platform.loadServiceWorker('./server.js', {
   workerCount: 4,           // Number of worker threads
   hotReload: true,          // Enable hot reloading
   caches: {
@@ -126,9 +157,9 @@ const serviceWorker = await platform.loadServiceWorker('./app.js', {
 ### Node.js Platform
 
 ```javascript
-import { createNodePlatform } from '@b9g/platform-node';
+import NodePlatform from '@b9g/platform-node';
 
-const platform = await createNodePlatform({
+const platform = new NodePlatform({
   // Node.js specific options
 });
 ```
@@ -136,9 +167,9 @@ const platform = await createNodePlatform({
 ### Bun Platform
 
 ```javascript
-import { createBunPlatform } from '@b9g/platform-bun';
+import BunPlatform from '@b9g/platform-bun';
 
-const platform = await createBunPlatform({
+const platform = new BunPlatform({
   // Bun specific options  
 });
 ```
@@ -146,13 +177,48 @@ const platform = await createBunPlatform({
 ### Cloudflare Workers Platform
 
 ```javascript
-import { createCloudflarePlatform } from '@b9g/platform-cloudflare';
+import CloudflarePlatform from '@b9g/platform-cloudflare';
 
-const platform = await createCloudflarePlatform({
+const platform = new CloudflarePlatform({
   // Cloudflare specific options
 });
 ```
 
+## Exports
+
+### Classes
+
+- `BasePlatform` - Abstract base class for platform implementations
+- `platformRegistry` - Default platform registry singleton
+
+### Functions
+
+- `createPlatform(name, options?)` - Create a platform instance by name
+- `getPlatform(name?)` - Get a registered platform synchronously
+- `getPlatformAsync(name?)` - Get a registered platform asynchronously
+- `detectRuntime()` - Detect current JavaScript runtime ('bun' | 'deno' | 'node')
+- `detectDeploymentPlatform()` - Detect deployment platform (Cloudflare, Vercel, etc.)
+- `detectDevelopmentPlatform()` - Detect development platform
+- `resolvePlatform(options)` - Resolve platform from options
+
+### Types
+
+- `Platform` - Platform interface
+- `PlatformConfig` - Platform configuration options
+- `ServerOptions` - Server configuration options
+- `Handler` - Request handler function type
+- `Server` - Server interface
+- `ServiceWorkerOptions` - ServiceWorker loading options
+- `ServiceWorkerInstance` - Loaded ServiceWorker instance
+
+### Re-exports from @b9g/filesystem
+
+- `BucketStorage`, `Bucket`, `BucketFactory`, `CustomBucketStorage`
+
+### Re-exports from @b9g/cache
+
+- `Cache`, `CacheFactory`, `CacheQueryOptions`, `CustomCacheStorage`
+
 ## API Reference
 
 ### Platform Interface
@@ -201,13 +267,13 @@ The platform abstraction powers the Shovel CLI:
 
 ```bash
 # Auto-detect and run
-shovel develop app.js
+shovel develop server.js
 
 # Explicit platform targeting
-shovel develop app.js --platform=bun --workers=4
+shovel develop server.js --platform=bun --workers=4
 
 # Platform-specific builds
-shovel build app.js --platform=cloudflare
+shovel build server.js --platform=cloudflare
 ```
 
 ## License

package/package.json

@@ -1,19 +1,25 @@
 {
   "name": "@b9g/platform",
-  "version": "0.1.3",
-  "description": "Base Platform interface and types for Shovel deployment adapters",
+  "version": "0.1.5",
+  "description": "ServiceWorker-first universal deployment platform. Write ServiceWorker apps once, deploy anywhere (Node/Bun/Cloudflare). Registry-based multi-app orchestration.",
   "keywords": [
-    "shovel",
-    "platform",
+    "serviceworker",
+    "universal",
     "deployment",
-    "adapter",
-    "interface"
+    "platform",
+    "registry",
+    "node",
+    "bun",
+    "cloudflare",
+    "workers",
+    "shovel"
   ],
   "dependencies": {
-    "@types/wicg-file-system-access": "^2023.10.7"
+    "@b9g/async-context": "^0.1.1",
+    "@logtape/logtape": "^1.2.0"
   },
   "devDependencies": {
-    "@b9g/libuild": "^0.1.10",
+    "@b9g/libuild": "^0.1.11",
     "bun-types": "latest"
   },
   "type": "module",
@@ -24,38 +30,38 @@
       "types": "./src/index.d.ts",
       "import": "./src/index.js"
     },
-    "./types": {
-      "types": "./src/types.d.ts",
-      "import": "./src/types.js"
+    "./package.json": "./package.json",
+    "./worker-pool": {
+      "types": "./src/worker-pool.d.ts",
+      "import": "./src/worker-pool.js"
     },
-    "./types.js": {
-      "types": "./src/types.d.ts",
-      "import": "./src/types.js"
+    "./worker-pool.js": {
+      "types": "./src/worker-pool.d.ts",
+      "import": "./src/worker-pool.js"
     },
-    "./package.json": "./package.json",
-    "./adapter-registry": {
-      "types": "./src/adapter-registry.d.ts",
-      "import": "./src/adapter-registry.js"
+    "./runtime": {
+      "types": "./src/runtime.d.ts",
+      "import": "./src/runtime.js"
     },
-    "./adapter-registry.js": {
-      "types": "./src/adapter-registry.d.ts",
-      "import": "./src/adapter-registry.js"
+    "./runtime.js": {
+      "types": "./src/runtime.d.ts",
+      "import": "./src/runtime.js"
     },
-    "./base-platform": {
-      "types": "./src/base-platform.d.ts",
-      "import": "./src/base-platform.js"
+    "./config": {
+      "types": "./src/config.d.ts",
+      "import": "./src/config.js"
     },
-    "./base-platform.js": {
-      "types": "./src/base-platform.d.ts",
-      "import": "./src/base-platform.js"
+    "./config.js": {
+      "types": "./src/config.d.ts",
+      "import": "./src/config.js"
     },
-    "./filesystem": {
-      "types": "./src/filesystem.d.ts",
-      "import": "./src/filesystem.js"
+    "./cookie-store": {
+      "types": "./src/cookie-store.d.ts",
+      "import": "./src/cookie-store.js"
     },
-    "./filesystem.js": {
-      "types": "./src/filesystem.d.ts",
-      "import": "./src/filesystem.js"
+    "./cookie-store.js": {
+      "types": "./src/cookie-store.d.ts",
+      "import": "./src/cookie-store.js"
     },
     "./index": {
       "types": "./src/index.d.ts",
@@ -65,61 +71,13 @@
       "types": "./src/index.d.ts",
       "import": "./src/index.js"
     },
-    "./registry": {
-      "types": "./src/registry.d.ts",
-      "import": "./src/registry.js"
-    },
-    "./registry.js": {
-      "types": "./src/registry.d.ts",
-      "import": "./src/registry.js"
-    },
-    "./service-worker": {
-      "types": "./src/service-worker.d.ts",
-      "import": "./src/service-worker.js"
-    },
-    "./service-worker.js": {
-      "types": "./src/service-worker.d.ts",
-      "import": "./src/service-worker.js"
-    },
-    "./utils": {
-      "types": "./src/utils.d.ts",
-      "import": "./src/utils.js"
-    },
-    "./utils.js": {
-      "types": "./src/utils.d.ts",
-      "import": "./src/utils.js"
-    },
-    "./detection": {
-      "types": "./src/detection.d.ts",
-      "import": "./src/detection.js"
-    },
-    "./detection.js": {
-      "types": "./src/detection.d.ts",
-      "import": "./src/detection.js"
-    },
-    "./directory-storage": {
-      "types": "./src/directory-storage.d.ts",
-      "import": "./src/directory-storage.js"
-    },
-    "./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"
+    "./single-threaded": {
+      "types": "./src/single-threaded.d.ts",
+      "import": "./src/single-threaded.js"
     },
-    "./worker-web.js": {
-      "types": "./src/worker-web.d.ts",
-      "import": "./src/worker-web.js"
+    "./single-threaded.js": {
+      "types": "./src/single-threaded.d.ts",
+      "import": "./src/single-threaded.js"
     }
   }
 }

package/src/config.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Configuration expression parser
+ *
+ * Embeddable JavaScript-like expressions for JSON config:
+ * - ALL_CAPS = env var reference (e.g., NODE_ENV, PORT)
+ * - Everything else = string literal (kebab-case, URLs, camelCase, PascalCase)
+ * - Quoted strings = explicit strings (escape hatch)
+ * - JavaScript keywords: true, false, null, undefined
+ * - Operators: ||, &&, ===, !==, ==, !=, ? :, !
+ * - No eval - uses recursive descent parser
+ *
+ * Examples:
+ *   "PORT || 3000"
+ *   "NODE_ENV === production ? redis : memory"
+ *   "REDIS_URL || redis://localhost:6379"
+ *   "S3_BUCKET || my-bucket-name"
+ *   "BASE_PATH || ./uploads"
+ */
+/**
+ * Parse a configuration expression with the DSL
+ */
+export declare function parseConfigExpr(expr: string, env?: Record<string, string | undefined>, options?: {
+    strict?: boolean;
+}): any;
+/**
+ * Process a config value (handles nested objects/arrays)
+ */
+export declare function processConfigValue(value: any, env?: Record<string, string | undefined>, options?: {
+    strict?: boolean;
+}): any;
+/**
+ * Match a name against config patterns
+ *
+ * Priority:
+ * 1. Exact match: "sessions" matches "sessions"
+ * 2. Prefix patterns: "api-*" matches "api-v1", "api-v2" (longest first)
+ * 3. Catch-all: "*" matches everything
+ *
+ * Examples:
+ *   matchPattern("sessions", {"sessions": {...}, "*": {...}})  → sessions config
+ *   matchPattern("api-v1", {"api-*": {...}, "*": {...}})       → api-* config
+ *   matchPattern("random", {"*": {...}})                        → * config
+ */
+export declare function matchPattern<T>(name: string, config: Record<string, T>): T | undefined;
+export interface CacheConfig {
+    provider?: string | number;
+    url?: string | number;
+    maxEntries?: string | number;
+    TTL?: string | number;
+}
+export interface BucketConfig {
+    provider?: string | number;
+    path?: string | number;
+    bucket?: string | number;
+    region?: string | number;
+    endpoint?: string | number;
+}
+export interface ShovelConfig {
+    port?: number | string;
+    host?: string;
+    workers?: number | string;
+    caches?: Record<string, CacheConfig>;
+    buckets?: Record<string, BucketConfig>;
+}
+export interface ProcessedShovelConfig {
+    port: number;
+    host: string;
+    workers: number;
+    caches: Record<string, CacheConfig>;
+    buckets: Record<string, BucketConfig>;
+}
+/**
+ * Load Shovel configuration from shovel.json or package.json
+ * Priority: shovel.json > package.json "shovel" field > defaults
+ * @param cwd - Current working directory (must be provided by runtime adapter)
+ */
+export declare function loadConfig(cwd: string): ProcessedShovelConfig;
+/**
+ * Get cache config for a specific cache name (with pattern matching)
+ */
+export declare function getCacheConfig(config: ProcessedShovelConfig, name: string): CacheConfig;
+/**
+ * Get bucket config for a specific bucket name (with pattern matching)
+ */
+export declare function getBucketConfig(config: ProcessedShovelConfig, name: string): BucketConfig;
+export interface BucketFactoryOptions {
+    /** Base directory for path resolution (entrypoint directory) - REQUIRED */
+    baseDir: string;
+    /** Shovel configuration for overrides */
+    config?: ProcessedShovelConfig;
+}
+/**
+ * Creates a bucket factory function for CustomBucketStorage.
+ * Lazily imports bucket implementations.
+ */
+export declare function createBucketFactory(options: BucketFactoryOptions): (name: string) => Promise<FileSystemDirectoryHandle>;
+export interface CacheFactoryOptions {
+    /** Shovel configuration for cache settings */
+    config?: ProcessedShovelConfig;
+}
+/**
+ * Creates a cache factory function for CustomCacheStorage.
+ * Lazily imports cache implementations.
+ */
+export declare function createCacheFactory(options?: CacheFactoryOptions): (name: string) => Promise<Cache>;