@b9g/platform 0.1.11 → 0.1.12

package/README.md

@@ -213,7 +213,7 @@ const platform = new CloudflarePlatform({
 
 ### Re-exports from @b9g/filesystem
 
-- `BucketStorage`, `Bucket`, `BucketFactory`, `CustomBucketStorage`
+- `DirectoryStorage`, `Directory`, `DirectoryFactory`, `CustomDirectoryStorage`
 
 ### Re-exports from @b9g/cache
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/platform",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "ServiceWorker-first universal deployment platform. Write ServiceWorker apps once, deploy anywhere (Node/Bun/Cloudflare). Registry-based multi-app orchestration.",
   "keywords": [
     "serviceworker",
@@ -57,14 +57,6 @@
       "import": "./src/index.js"
     },
     "./package.json": "./package.json",
-    "./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"
-    },
     "./runtime": {
       "types": "./src/runtime.d.ts",
       "import": "./src/runtime.js"
@@ -73,21 +65,13 @@
       "types": "./src/runtime.d.ts",
       "import": "./src/runtime.js"
     },
-    "./config": {
-      "types": "./src/config.d.ts",
-      "import": "./src/config.js"
-    },
-    "./config.js": {
-      "types": "./src/config.d.ts",
-      "import": "./src/config.js"
+    "./worker": {
+      "types": "./src/worker.d.ts",
+      "import": "./src/worker.js"
     },
-    "./cookie-store": {
-      "types": "./src/cookie-store.d.ts",
-      "import": "./src/cookie-store.js"
-    },
-    "./cookie-store.js": {
-      "types": "./src/cookie-store.d.ts",
-      "import": "./src/cookie-store.js"
+    "./worker.js": {
+      "types": "./src/worker.d.ts",
+      "import": "./src/worker.js"
     },
     "./index": {
       "types": "./src/index.d.ts",
@@ -96,14 +80,6 @@
     "./index.js": {
       "types": "./src/index.d.ts",
       "import": "./src/index.js"
-    },
-    "./single-threaded": {
-      "types": "./src/single-threaded.d.ts",
-      "import": "./src/single-threaded.js"
-    },
-    "./single-threaded.js": {
-      "types": "./src/single-threaded.d.ts",
-      "import": "./src/single-threaded.js"
     }
   }
 }

package/src/index.d.ts

@@ -3,7 +3,14 @@
  *
  * Platform = "ServiceWorker entrypoint loader for JavaScript runtimes"
  * Core responsibility: Take a ServiceWorker-style app file and make it run in this environment.
+ *
+ * This module contains:
+ * - Platform interface and base classes
+ * - SingleThreadedRuntime for main-thread execution
+ * - ServiceWorkerPool for multi-worker execution
  */
+import type { DirectoryStorage } from "@b9g/filesystem";
+import { CustomLoggerStorage, type LoggerStorage } from "./runtime.js";
 /**
  * Platform configuration
  * Extended by platform-specific implementations (NodePlatformOptions, etc.)
@@ -76,6 +83,35 @@ export interface ServiceWorkerInstance {
     /** Dispose of resources */
     dispose(): Promise<void>;
 }
+/**
+ * Options for getEntryWrapper()
+ * Reserved for future platform-specific options.
+ */
+export interface EntryWrapperOptions {
+}
+/**
+ * Esbuild configuration subset that platforms can customize
+ */
+export interface PlatformEsbuildConfig {
+    /** Target platform: "node" or "browser" */
+    platform?: "node" | "browser" | "neutral";
+    /** Export conditions for package.json resolution */
+    conditions?: string[];
+    /** External modules to exclude from bundle */
+    external?: string[];
+    /** Compile-time defines */
+    define?: Record<string, string>;
+    /**
+     * Whether the entry wrapper imports user code inline (bundled together)
+     * or references it as a separate file (loaded at runtime).
+     *
+     * - true: User code is imported inline (e.g., Cloudflare: `import "user-entry"`)
+     * - false: User code is loaded separately (e.g., Node/Bun: `loadServiceWorker("./server.js")`)
+     *
+     * Default: false (separate build)
+     */
+    bundlesUserCodeInline?: boolean;
+}
 /**
  * Platform interface - ServiceWorker entrypoint loader for JavaScript runtimes
  *
@@ -100,6 +136,28 @@ export interface Platform {
      * SUPPORTING UTILITY - Create server instance for this platform
      */
     createServer(handler: Handler, options?: ServerOptions): Server;
+    /**
+     * BUILD SUPPORT - Get virtual entry wrapper template for user code
+     *
+     * Returns a JavaScript/TypeScript string that:
+     * 1. Initializes platform-specific runtime (polyfills, globals)
+     * 2. Imports the user's entrypoint
+     * 3. Exports any required handlers (e.g., ES module export for Cloudflare)
+     *
+     * The CLI uses this to create a virtual entry point for bundling.
+     * Every platform must provide a wrapper - there is no "raw user code" mode.
+     *
+     * @param entryPath - Absolute path to user's entrypoint file
+     * @param options - Additional options
+     */
+    getEntryWrapper(entryPath: string, options?: EntryWrapperOptions): string;
+    /**
+     * BUILD SUPPORT - Get platform-specific esbuild configuration
+     *
+     * Returns partial esbuild config that the CLI merges with common settings.
+     * Includes platform target, conditions, externals, and defines.
+     */
+    getEsbuildConfig(): PlatformEsbuildConfig;
 }
 /**
  * Platform registry - internal implementation
@@ -126,11 +184,7 @@ export declare function detectRuntime(): "bun" | "deno" | "node";
  */
 export declare function detectDeploymentPlatform(): string | null;
 /**
- * Detect platform for development
- *
- * Priority:
- * 1. Check package.json for installed @b9g/platform-* package
- * 2. Fallback to current runtime (bun/node/deno)
+ * Detect platform for development based on current runtime
  */
 export declare function detectDevelopmentPlatform(): string;
 /**
@@ -168,6 +222,16 @@ export declare abstract class BasePlatform implements Platform {
      * Returns empty CacheStorage - applications create caches on-demand via caches.open()
      */
     createCaches(): Promise<CacheStorage>;
+    /**
+     * Get virtual entry wrapper template for user code
+     * Subclasses must override to provide platform-specific wrappers
+     */
+    abstract getEntryWrapper(entryPath: string, options?: EntryWrapperOptions): string;
+    /**
+     * Get platform-specific esbuild configuration
+     * Subclasses should override to provide platform-specific config
+     */
+    abstract getEsbuildConfig(): PlatformEsbuildConfig;
 }
 /**
  * Global platform registry
@@ -191,9 +255,150 @@ export declare function getPlatform(name?: string): Platform;
  * Get platform with async auto-registration fallback
  */
 export declare function getPlatformAsync(name?: string): Promise<Platform>;
-export { ServiceWorkerPool, type WorkerPoolOptions, type WorkerMessage, type WorkerRequest, type WorkerResponse, type WorkerLoadMessage, type WorkerReadyMessage, type WorkerErrorMessage, type WorkerInitMessage, type WorkerInitializedMessage, } from "./worker-pool.js";
-export { SingleThreadedRuntime, type SingleThreadedRuntimeOptions, } from "./single-threaded.js";
-export { ShovelServiceWorkerRegistration, ServiceWorkerGlobals, FetchEvent, InstallEvent, ActivateEvent, ExtendableEvent, } from "./runtime.js";
-export { RequestCookieStore, type CookieListItem, type CookieInit, type CookieStoreGetOptions, type CookieStoreDeleteOptions, type CookieSameSite, type CookieList, parseCookieHeader, serializeCookie, parseSetCookieHeader, } from "./cookie-store.js";
-export { CustomBucketStorage } from "@b9g/filesystem";
-export { loadConfig, configureLogging, getCacheConfig, getBucketConfig, parseConfigExpr, processConfigValue, matchPattern, createBucketFactory, createCacheFactory, type ShovelConfig, type CacheConfig, type BucketConfig, type LoggingConfig, type LogLevel, type BucketFactoryOptions, type CacheFactoryOptions, type ProcessedShovelConfig, } from "./config.js";
+/**
+ * Common interface for ServiceWorker runtimes
+ */
+export interface ServiceWorkerRuntime {
+    init(): Promise<void>;
+    load(entrypoint: string): Promise<void>;
+    handleRequest(request: Request): Promise<Response>;
+    terminate(): Promise<void>;
+    readonly workerCount: number;
+    readonly ready: boolean;
+}
+export interface SingleThreadedRuntimeOptions {
+    /** Cache storage for the runtime */
+    caches: CacheStorage;
+    /** Directory storage for the runtime */
+    directories: DirectoryStorage;
+    /** Logger storage for the runtime */
+    loggers: LoggerStorage;
+}
+/**
+ * Single-threaded ServiceWorker runtime
+ *
+ * Runs ServiceWorker code directly in the main thread.
+ * Implements ServiceWorkerRuntime interface for interchangeability with ServiceWorkerPool.
+ */
+export declare class SingleThreadedRuntime implements ServiceWorkerRuntime {
+    #private;
+    constructor(options: SingleThreadedRuntimeOptions);
+    /**
+     * Initialize the runtime (install ServiceWorker globals)
+     */
+    init(): Promise<void>;
+    /**
+     * Load (or reload) a ServiceWorker entrypoint
+     * @param entrypoint - Path to the entrypoint file (content-hashed filename)
+     */
+    load(entrypoint: string): Promise<void>;
+    /**
+     * Handle an HTTP request
+     * This is the key method - direct call, no postMessage!
+     */
+    handleRequest(request: Request): Promise<Response>;
+    /**
+     * Graceful shutdown
+     */
+    terminate(): Promise<void>;
+    /**
+     * Get the number of workers (always 1 for single-threaded)
+     */
+    get workerCount(): number;
+    /**
+     * Check if ready to handle requests
+     */
+    get ready(): boolean;
+}
+/**
+ * Worker pool options
+ */
+export interface WorkerPoolOptions {
+    /** Number of workers in the pool (default: 1) */
+    workerCount?: number;
+    /** Request timeout in milliseconds (default: 30000) */
+    requestTimeout?: number;
+    /** Working directory for file resolution */
+    cwd?: string;
+}
+export interface WorkerMessage {
+    type: string;
+    [key: string]: any;
+}
+export interface WorkerRequest extends WorkerMessage {
+    type: "request";
+    request: {
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        body?: ArrayBuffer | null;
+    };
+    requestID: number;
+}
+export interface WorkerResponse extends WorkerMessage {
+    type: "response";
+    response: {
+        status: number;
+        statusText: string;
+        headers: Record<string, string>;
+        body: ArrayBuffer;
+    };
+    requestID: number;
+}
+export interface WorkerLoadMessage extends WorkerMessage {
+    type: "load";
+    entrypoint: string;
+}
+export interface WorkerReadyMessage extends WorkerMessage {
+    type: "ready" | "worker-ready";
+    entrypoint?: string;
+}
+export interface WorkerErrorMessage extends WorkerMessage {
+    type: "error";
+    error: string;
+    stack?: string;
+    requestID?: number;
+}
+export interface WorkerInitMessage extends WorkerMessage {
+    type: "init";
+    config: any;
+    baseDir: string;
+}
+export interface WorkerInitializedMessage extends WorkerMessage {
+    type: "initialized";
+}
+/**
+ * ServiceWorkerPool - manages a pool of ServiceWorker instances
+ * Handles HTTP request/response routing, cache coordination, and hot reloading
+ */
+export declare class ServiceWorkerPool {
+    #private;
+    constructor(options?: WorkerPoolOptions, appEntrypoint?: string, cacheStorage?: CacheStorage, config?: any);
+    /**
+     * Initialize workers (must be called after construction)
+     */
+    init(): Promise<void>;
+    /**
+     * Handle HTTP request using round-robin worker selection
+     */
+    handleRequest(request: Request): Promise<Response>;
+    /**
+     * Reload ServiceWorker with new entrypoint (hot reload)
+     * The entrypoint path contains a content hash for cache busting
+     */
+    reloadWorkers(entrypoint: string): Promise<void>;
+    /**
+     * Graceful shutdown of all workers
+     */
+    terminate(): Promise<void>;
+    /**
+     * Get the number of active workers
+     */
+    get workerCount(): number;
+    /**
+     * Check if the pool is ready to handle requests
+     */
+    get ready(): boolean;
+}
+export { CustomLoggerStorage, type LoggerStorage };
+export type { LoggerFactory } from "./runtime.js";