@b9g/platform 0.1.14-beta.3 → 0.1.15

package/README.md

@@ -203,8 +203,6 @@ const platform = new CloudflarePlatform({
 
 ### Types
 
-- `Platform` - Platform interface
-- `PlatformConfig` - Platform configuration options
 - `ServerOptions` - Server configuration options
 - `Handler` - Request handler function type
 - `Server` - Server interface

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/platform",
-  "version": "0.1.14-beta.3",
+  "version": "0.1.15",
   "description": "The portable meta-framework built on web standards.",
   "keywords": [
     "service-worker",
@@ -18,16 +18,16 @@
     "shovel"
   ],
   "dependencies": {
-    "@b9g/async-context": "^0.2.0-beta.0",
-    "@b9g/cache": "^0.2.0-beta.0",
+    "@b9g/async-context": "^0.2.0",
+    "@b9g/cache": "^0.2.0",
     "@b9g/filesystem": "^0.1.8",
     "@logtape/logtape": "^1.2.0"
   },
   "devDependencies": {
     "@b9g/libuild": "^0.1.20",
-    "@b9g/node-webworker": "^0.2.0-beta.1",
-    "@b9g/platform-bun": "^0.1.12-beta.0",
-    "@b9g/platform-node": "^0.1.14-beta.0"
+    "@b9g/node-webworker": "^0.2.0",
+    "@b9g/platform-bun": "^0.1.13",
+    "@b9g/platform-node": "^0.1.15"
   },
   "peerDependencies": {
     "@b9g/zen": "^0.1.6"
@@ -71,6 +71,14 @@
     "./config.js": {
       "types": "./src/config.d.ts",
       "import": "./src/config.js"
+    },
+    "./module": {
+      "types": "./src/module.d.ts",
+      "import": "./src/module.js"
+    },
+    "./module.js": {
+      "types": "./src/module.d.ts",
+      "import": "./src/module.js"
     }
   }
 }

package/src/index.d.ts

@@ -10,15 +10,8 @@
  * - Platform interface and base classes
  * - ServiceWorkerPool for multi-worker execution
  */
-import type { DirectoryStorage } from "@b9g/filesystem";
 import { CustomLoggerStorage, type LoggerStorage } from "./runtime.js";
 export { validateConfig, ConfigValidationError } from "./config.js";
-/**
- * Platform configuration
- * Extended by platform-specific implementations (NodePlatformOptions, etc.)
- */
-export interface PlatformConfig {
-}
 /**
  * Server options for platform implementations
  */
@@ -81,14 +74,16 @@ export interface ServiceWorkerInstance {
     dispose(): Promise<void>;
 }
 /**
- * Production entry points returned by getProductionEntryPoints().
+ * Entry points returned by getEntryPoints().
  * Each key is the output filename (without .js), value is the code.
  *
  * Examples:
  * - Cloudflare: { "worker": "<code>" } - single worker file
  * - Node/Bun: { "index": "<supervisor>", "worker": "<worker>" } - two files
  */
-export type ProductionEntryPoints = Record<string, string>;
+export type EntryPoints = Record<string, string>;
+/** @deprecated Use EntryPoints instead */
+export type ProductionEntryPoints = EntryPoints;
 /**
  * ESBuild configuration subset that platforms can customize
  */
@@ -138,100 +133,6 @@ export interface ShovelServiceWorkerContainer extends ServiceWorkerContainer {
     /** Internal: Reload workers (for hot reload) */
     reloadWorkers(entrypoint: string): Promise<void>;
 }
-/**
- * Platform interface - ServiceWorker entrypoint loader for JavaScript runtimes
- *
- * The core responsibility: "Take a ServiceWorker-style app file and make it run in this environment"
- */
-export interface Platform {
-    /**
-     * Platform name for identification
-     */
-    readonly name: string;
-    /**
-     * ServiceWorkerContainer for managing registrations (Node/Bun only)
-     * Similar to navigator.serviceWorker in browsers
-     */
-    readonly serviceWorker: ShovelServiceWorkerContainer;
-    /**
-     * Start HTTP server and route requests to ServiceWorker (Node/Bun only)
-     * Must call serviceWorker.register() first
-     */
-    listen(): Promise<Server>;
-    /**
-     * Close server and terminate workers (Node/Bun only)
-     */
-    close(): Promise<void>;
-    /**
-     * SUPPORTING UTILITY - Create server instance for this platform
-     */
-    createServer(handler: Handler, options?: ServerOptions): Server;
-    /**
-     * BUILD SUPPORT - Get production entry points for bundling
-     *
-     * Returns a map of output filenames to their source code.
-     * The build system creates one output file per entry point.
-     *
-     * Platform determines the structure:
-     * - Cloudflare: { "worker": "<code>" } - single worker file
-     * - Node/Bun: { "index": "<supervisor>", "worker": "<runtime + user code>" }
-     *
-     * The user's entrypoint code is statically imported into the appropriate file.
-     *
-     * @param userEntryPath - Path to user's entrypoint (will be imported)
-     */
-    getProductionEntryPoints(userEntryPath: string): ProductionEntryPoints;
-    /**
-     * 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;
-    /**
-     * BUILD SUPPORT - Get platform-specific defaults for config generation
-     *
-     * Returns defaults for directories, caches, etc. that get merged with
-     * user config at build time. These are used by generateConfigModule()
-     * to create static imports for the default implementations.
-     */
-    getDefaults(): PlatformDefaults;
-    /**
-     * Create cache storage for this platform
-     * Uses platform-specific defaults, overridable via shovel.json config
-     */
-    createCaches(): Promise<CacheStorage>;
-    /**
-     * Create directory storage for this platform
-     * Uses platform-specific defaults, overridable via shovel.json config
-     */
-    createDirectories(): Promise<DirectoryStorage>;
-    /**
-     * Create logger storage for this platform
-     * Uses platform-specific defaults, overridable via shovel.json config
-     */
-    createLoggers(): Promise<LoggerStorage>;
-    /**
-     * Dispose of platform resources (worker pools, connections, etc.)
-     */
-    dispose(): Promise<void>;
-    /**
-     * HOT RELOAD - Reload workers with a new entrypoint (development only)
-     * Optional - only Node and Bun platforms implement this
-     */
-    reloadWorkers?(entrypoint: string): Promise<void>;
-}
-/**
- * Platform registry - internal implementation
- */
-interface PlatformRegistry {
-    /** Register a platform implementation */
-    register(name: string, platform: any): void;
-    /** Get platform by name */
-    get(name: string): any | undefined;
-    /** Get all registered platforms */
-    list(): string[];
-}
 /**
  * Detect the current JavaScript runtime
  */
@@ -265,54 +166,6 @@ export declare function resolvePlatform(options: {
         platform?: string;
     };
 }): string;
-/**
- * Base platform class with shared adapter loading logic
- * Platform implementations extend this and provide platform-specific methods
- */
-export declare abstract class BasePlatform implements Platform {
-    config: PlatformConfig;
-    constructor(config?: PlatformConfig);
-    abstract readonly name: string;
-    abstract readonly serviceWorker: ShovelServiceWorkerContainer;
-    abstract listen(): Promise<Server>;
-    abstract close(): Promise<void>;
-    abstract createServer(handler: any, options?: any): any;
-    /**
-     * Get production entry points for bundling
-     * Subclasses must override to provide platform-specific entry points
-     */
-    abstract getProductionEntryPoints(userEntryPath: string): ProductionEntryPoints;
-    /**
-     * Get platform-specific esbuild configuration
-     * Subclasses should override to provide platform-specific config
-     */
-    abstract getESBuildConfig(): PlatformESBuildConfig;
-    /**
-     * Get platform-specific defaults for config generation
-     * Subclasses should override to provide platform-specific defaults
-     */
-    abstract getDefaults(): PlatformDefaults;
-    /**
-     * Create cache storage for this platform
-     * Subclasses must override to provide platform-specific implementation
-     */
-    abstract createCaches(): Promise<CacheStorage>;
-    /**
-     * Create directory storage for this platform
-     * Subclasses must override to provide platform-specific implementation
-     */
-    abstract createDirectories(): Promise<DirectoryStorage>;
-    /**
-     * Create logger storage for this platform
-     * Subclasses must override to provide platform-specific implementation
-     */
-    abstract createLoggers(): Promise<LoggerStorage>;
-    /**
-     * Dispose of platform resources
-     * Subclasses should override to clean up worker pools, connections, etc.
-     */
-    dispose(): Promise<void>;
-}
 /**
  * Merge platform defaults with user config
  *
@@ -324,39 +177,6 @@ export declare abstract class BasePlatform implements Platform {
  * @returns Merged config with all entries
  */
 export declare function mergeConfigWithDefaults(defaults: Record<string, Record<string, unknown>>, userConfig: Record<string, Record<string, unknown>> | undefined): Record<string, Record<string, unknown>>;
-/**
- * Global platform registry
- */
-declare class DefaultPlatformRegistry implements PlatformRegistry {
-    #private;
-    constructor();
-    register(name: string, platform: Platform): void;
-    get(name: string): Platform | undefined;
-    list(): string[];
-}
-/**
- * Global platform registry instance
- */
-export declare const platformRegistry: DefaultPlatformRegistry;
-/**
- * Get platform by name with error handling
- */
-export declare function getPlatform(name?: string): Platform;
-/**
- * Get platform with async auto-registration fallback
- */
-export declare function getPlatformAsync(name?: string): Promise<Platform>;
-/**
- * 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;
-}
 /**
  * Worker pool options
  */
@@ -370,39 +190,6 @@ export interface WorkerPoolOptions {
     /** Custom worker factory (if not provided, uses createWebWorker) */
     createWorker?: (entrypoint: string) => Worker | Promise<Worker>;
 }
-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 WorkerReadyMessage extends WorkerMessage {
-    type: "ready";
-}
-export interface WorkerErrorMessage extends WorkerMessage {
-    type: "error";
-    error: string;
-    stack?: string;
-    requestID?: number;
-}
 /**
  * ServiceWorkerPool - manages a pool of ServiceWorker instances
  *

package/src/index.js

@@ -55,18 +55,6 @@ function resolvePlatform(options) {
   }
   return detectDevelopmentPlatform();
 }
-var BasePlatform = class {
-  config;
-  constructor(config = {}) {
-    this.config = config;
-  }
-  /**
-   * Dispose of platform resources
-   * Subclasses should override to clean up worker pools, connections, etc.
-   */
-  async dispose() {
-  }
-};
 function mergeConfigWithDefaults(defaults, userConfig) {
   const user = userConfig ?? {};
   const allNames = /* @__PURE__ */ new Set([...Object.keys(defaults), ...Object.keys(user)]);
@@ -76,62 +64,6 @@ function mergeConfigWithDefaults(defaults, userConfig) {
   }
   return merged;
 }
-var DefaultPlatformRegistry = class {
-  #platforms;
-  constructor() {
-    this.#platforms = /* @__PURE__ */ new Map();
-  }
-  register(name, platform) {
-    this.#platforms.set(name, platform);
-  }
-  get(name) {
-    return this.#platforms.get(name);
-  }
-  list() {
-    return Array.from(this.#platforms.keys());
-  }
-};
-var platformRegistry = new DefaultPlatformRegistry();
-function getPlatform(name) {
-  if (name) {
-    const platform2 = platformRegistry.get(name);
-    if (!platform2) {
-      const available = platformRegistry.list();
-      throw new Error(
-        `Platform '${name}' not found. Available platforms: ${available.join(", ")}`
-      );
-    }
-    return platform2;
-  }
-  const platformName = detectDeploymentPlatform() || detectDevelopmentPlatform();
-  const platform = platformRegistry.get(platformName);
-  if (!platform) {
-    throw new Error(
-      `Detected platform '${platformName}' not registered. Please register it manually or specify a platform name.`
-    );
-  }
-  return platform;
-}
-async function getPlatformAsync(name) {
-  if (name) {
-    const platform2 = platformRegistry.get(name);
-    if (!platform2) {
-      const available = platformRegistry.list();
-      throw new Error(
-        `Platform '${name}' not found. Available platforms: ${available.join(", ")}`
-      );
-    }
-    return platform2;
-  }
-  const platformName = detectDeploymentPlatform() || detectDevelopmentPlatform();
-  const platform = platformRegistry.get(platformName);
-  if (!platform) {
-    throw new Error(
-      `Detected platform '${platformName}' not registered. Please register it manually using platformRegistry.register().`
-    );
-  }
-  return platform;
-}
 async function createWebWorker(workerScript) {
   if (typeof Worker !== "undefined") {
     return new Worker(workerScript, { type: "module" });
@@ -454,7 +386,9 @@ var ServiceWorkerPool = class {
         createPromises.push(this.#createWorker(entrypoint));
       }
       await Promise.all(createPromises);
-      logger.debug("All workers reloaded", { entrypoint });
+      logger.info("Reloaded {count} workers", {
+        count: this.#options.workerCount
+      });
     } catch (error) {
       const waiters = this.#workerAvailableWaiters;
       this.#workerAvailableWaiters = [];
@@ -500,7 +434,6 @@ var ServiceWorkerPool = class {
   }
 };
 export {
-  BasePlatform,
   ConfigValidationError,
   CustomDatabaseStorage,
   CustomLoggerStorage,
@@ -509,10 +442,7 @@ export {
   detectDeploymentPlatform,
   detectDevelopmentPlatform,
   detectRuntime,
-  getPlatform,
-  getPlatformAsync,
   mergeConfigWithDefaults,
-  platformRegistry,
   resolvePlatform,
   validateConfig
 };

package/src/module.d.ts

@@ -0,0 +1,142 @@
+/// <reference path="./globals.d.ts" />
+/// <reference path="./shovel-config.d.ts" />
+/**
+ * Platform Module Interface
+ *
+ * Platforms are modules, not classes. Each platform exports functions
+ * that the CLI and generated entry code use.
+ *
+ * Build-time functions: Used by CLI/bundler, never bundled into prod
+ * Runtime functions: Imported by generated entry code, bundled into prod
+ *
+ * This separation enables tree-shaking - dev dependencies like Miniflare
+ * never end up in production bundles.
+ */
+/**
+ * Entry points returned by getEntryPoints().
+ * Maps output filename (without .js) to source code.
+ */
+export type EntryPoints = Record<string, string>;
+/**
+ * ESBuild configuration that platforms can customize.
+ */
+export interface ESBuildConfig {
+    /** Target platform: "node" or "browser" */
+    platform?: "node" | "browser";
+    /** Export conditions for package.json resolution */
+    conditions?: string[];
+    /** Modules to exclude from bundling */
+    external?: string[];
+    /** Define replacements */
+    define?: Record<string, string>;
+}
+/**
+ * Platform defaults for config generation.
+ * Module paths that get statically imported at build time.
+ */
+export interface PlatformDefaults {
+    caches?: Record<string, {
+        module: string;
+        export?: string;
+        [key: string]: unknown;
+    }>;
+    directories?: Record<string, {
+        module: string;
+        export?: string;
+        [key: string]: unknown;
+    }>;
+}
+/**
+ * Options for creating a dev server.
+ */
+export interface DevServerOptions {
+    /** Port to listen on */
+    port: number;
+    /** Host to bind to */
+    host: string;
+    /** Path to the built worker entry */
+    workerPath: string;
+    /** Number of workers (Node/Bun only) */
+    workers?: number;
+}
+/**
+ * Dev server instance returned by createDevServer().
+ * Abstracts over Miniflare, worker pools, etc.
+ */
+export interface DevServer {
+    /** Server URL */
+    readonly url: string;
+    /** Reload workers with new entry */
+    reload(workerPath: string): Promise<void>;
+    /** Shut down the server */
+    close(): Promise<void>;
+}
+/**
+ * Result from installGlobals().
+ */
+export interface RuntimeContext {
+    /** ServiceWorker registration for dispatching events */
+    registration: ServiceWorkerRegistration;
+}
+/**
+ * Server instance for Node/Bun.
+ */
+export interface Server {
+    /** Start listening */
+    listen(): Promise<void>;
+    /** Stop the server */
+    close(): Promise<void>;
+    /** Server address */
+    readonly url: string;
+}
+/**
+ * Handler function type for HTTP requests.
+ */
+export type RequestHandler = (request: Request) => Response | Promise<Response>;
+/**
+ * Fetch handler for Cloudflare Workers.
+ * ExecutionContext is Cloudflare-specific, so we use a generic type here.
+ */
+export type FetchHandler = (request: Request, env: unknown, ctx: {
+    waitUntil(promise: Promise<unknown>): void;
+    passThroughOnException(): void;
+}) => Response | Promise<Response>;
+/**
+ * What a platform module exports.
+ *
+ * This is not enforced at runtime - it's documentation of the contract.
+ * Each platform module should export these functions.
+ *
+ * Build-time exports (from main module):
+ *   - name: string
+ *   - getEntryPoints(userPath, mode): EntryPoints
+ *   - getESBuildConfig(): ESBuildConfig
+ *   - getDefaults(): PlatformDefaults
+ *   - createDevServer(options): Promise<DevServer>
+ *
+ * Runtime exports (from /runtime subpath):
+ *   - installGlobals(config): Promise<RuntimeContext>
+ *   - Platform-specific: createServer, createFetchHandler, etc.
+ */
+export interface PlatformModule {
+    /** Platform identifier */
+    readonly name: string;
+    /** Generate entry point code for bundling */
+    getEntryPoints(userEntryPath: string, mode: "development" | "production"): EntryPoints;
+    /** Get ESBuild configuration for this platform */
+    getESBuildConfig(): ESBuildConfig;
+    /** Get default configs for caches, directories, etc. */
+    getDefaults(): PlatformDefaults;
+    /** Create a dev server (imports heavy deps like Miniflare) */
+    createDevServer(options: DevServerOptions): Promise<DevServer>;
+}
+/**
+ * What a platform runtime module exports.
+ *
+ * Each platform's /runtime subpath exports these.
+ * The specific functions vary by platform.
+ */
+export interface PlatformRuntimeModule {
+    /** Install ServiceWorker globals (caches, directories, loggers) */
+    installGlobals(config: unknown): Promise<RuntimeContext>;
+}

package/src/module.js

@@ -0,0 +1 @@
+/// <reference types="./module.d.ts" />

package/src/runtime.js

@@ -324,9 +324,10 @@ function createDatabaseFactory(configs) {
     let Database;
     try {
       ({ Database } = await import("@b9g/zen"));
-    } catch {
+    } catch (e) {
       throw new Error(
-        "@b9g/zen is required for database support. Install it with: npm install @b9g/zen"
+        "@b9g/zen is required for database support. Install it with: npm install @b9g/zen",
+        { cause: e }
       );
     }
     const driver = new impl(url, driverOptions);
@@ -634,11 +635,11 @@ var ShovelServiceWorkerRegistration = class extends EventTarget {
     this[kServiceWorker]._setState("installing");
     return new Promise((resolve, reject) => {
       const event = new ShovelInstallEvent();
-      process.nextTick(() => {
+      queueMicrotask(() => {
         try {
           this.dispatchEvent(event);
         } catch (error) {
-          process.nextTick(() => {
+          queueMicrotask(() => {
             throw error;
           });
         }
@@ -670,11 +671,11 @@ var ShovelServiceWorkerRegistration = class extends EventTarget {
     this[kServiceWorker]._setState("activating");
     return new Promise((resolve, reject) => {
       const event = new ShovelActivateEvent();
-      process.nextTick(() => {
+      queueMicrotask(() => {
         try {
           this.dispatchEvent(event);
         } catch (error) {
-          process.nextTick(() => {
+          queueMicrotask(() => {
             throw error;
           });
         }
@@ -705,8 +706,8 @@ var ShovelServiceWorkerRegistration = class extends EventTarget {
    * @param event - The fetch event to handle (created by platform adapter)
    */
   async [kHandleRequest](event) {
-    if (this[kServiceWorker].state !== "activated") {
-      throw new Error("ServiceWorker not activated");
+    if (this[kServiceWorker].state === "parsed") {
+      throw new Error("ServiceWorker not initialized");
     }
     return cookieStoreStorage.run(event.cookieStore, async () => {
       this.dispatchEvent(event);