@b9g/platform 0.1.12 → 0.1.14-beta.0

package/package.json

@@ -1,28 +1,34 @@
 {
   "name": "@b9g/platform",
-  "version": "0.1.12",
-  "description": "ServiceWorker-first universal deployment platform. Write ServiceWorker apps once, deploy anywhere (Node/Bun/Cloudflare). Registry-based multi-app orchestration.",
+  "version": "0.1.14-beta.0",
+  "description": "The portable meta-framework built on web standards.",
   "keywords": [
-    "serviceworker",
+    "service-worker",
     "universal",
     "deployment",
     "platform",
-    "registry",
     "node",
     "bun",
     "cloudflare",
     "workers",
+    "cache",
+    "framework",
+    "meta-framework",
+    "esbuild",
     "shovel"
   ],
   "dependencies": {
-    "@b9g/async-context": "^0.1.4",
-    "@b9g/cache": "^0.1.5",
-    "@b9g/filesystem": "^0.1.7",
+    "@b9g/async-context": "^0.2.0-beta.0",
+    "@b9g/cache": "^0.2.0-beta.0",
+    "@b9g/filesystem": "^0.1.8",
+    "@b9g/zen": "^0.1.6",
     "@logtape/logtape": "^1.2.0"
   },
   "devDependencies": {
-    "@b9g/libuild": "^0.1.18",
-    "bun-types": "latest"
+    "@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"
   },
   "peerDependencies": {
     "@logtape/file": "^1.0.0",
@@ -65,14 +71,6 @@
       "types": "./src/runtime.d.ts",
       "import": "./src/runtime.js"
     },
-    "./worker": {
-      "types": "./src/worker.d.ts",
-      "import": "./src/worker.js"
-    },
-    "./worker.js": {
-      "types": "./src/worker.d.ts",
-      "import": "./src/worker.js"
-    },
     "./index": {
       "types": "./src/index.d.ts",
       "import": "./src/index.js"
@@ -80,6 +78,16 @@
     "./index.js": {
       "types": "./src/index.d.ts",
       "import": "./src/index.js"
+    },
+    "./globals.d.ts": "./src/globals.d.ts",
+    "./shovel-config.d.ts": "./src/shovel-config.d.ts",
+    "./config": {
+      "types": "./src/config.d.ts",
+      "import": "./src/config.js"
+    },
+    "./config.js": {
+      "types": "./src/config.d.ts",
+      "import": "./src/config.js"
     }
   }
 }

package/src/config.d.ts

@@ -0,0 +1,24 @@
+/// <reference path="./globals.d.ts" />
+/// <reference path="./shovel-config.d.ts" />
+/**
+ * Config Validation Utilities
+ *
+ * Helpers for validating config objects at runtime.
+ */
+/**
+ * Error thrown when config validation fails
+ */
+export declare class ConfigValidationError extends Error {
+    readonly path: string;
+    readonly issue: "undefined" | "NaN";
+    constructor(path: string, issue: "undefined" | "NaN");
+}
+/**
+ * Validate that a config object has no undefined or NaN values.
+ * Call this at runtime to fail fast on missing env vars.
+ *
+ * @param config - The config object to validate
+ * @param path - Current path for error messages (used in recursion)
+ * @throws ConfigValidationError if any value is undefined or NaN
+ */
+export declare function validateConfig(config: Record<string, unknown>, path?: string): void;

package/src/config.js

@@ -0,0 +1,29 @@
+/// <reference types="./config.d.ts" />
+// src/config.ts
+var ConfigValidationError = class extends Error {
+  constructor(path, issue) {
+    const message = issue === "undefined" ? `Config "${path}" is undefined. Ensure required environment variables are set.` : `Config "${path}" is NaN. Ensure the environment variable contains a valid number.`;
+    super(message);
+    this.path = path;
+    this.issue = issue;
+    this.name = "ConfigValidationError";
+  }
+};
+function validateConfig(config, path = "") {
+  for (const [key, value] of Object.entries(config)) {
+    const fullPath = path ? `${path}.${key}` : key;
+    if (value === void 0) {
+      throw new ConfigValidationError(fullPath, "undefined");
+    }
+    if (typeof value === "number" && Number.isNaN(value)) {
+      throw new ConfigValidationError(fullPath, "NaN");
+    }
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      validateConfig(value, fullPath);
+    }
+  }
+}
+export {
+  ConfigValidationError,
+  validateConfig
+};

package/src/globals.d.ts

@@ -0,0 +1,119 @@
+/// <reference lib="webworker" />
+
+/**
+ * Global type declarations for Shovel ServiceWorker environment.
+ *
+ * These types augment the global scope with Shovel-specific APIs
+ * that are installed by ServiceWorkerGlobals.
+ *
+ * Usage: Include this file in your tsconfig.json "include" array
+ * or reference it with /// <reference types="@b9g/platform/globals" />
+ */
+
+import type {Logger} from "@logtape/logtape";
+import type {DirectoryStorage} from "@b9g/filesystem";
+
+declare global {
+	/**
+	 * Logger storage API for accessing named loggers.
+	 * @example const logger = self.loggers.get(["app"]);
+	 * @example const dbLogger = self.loggers.get(["app", "db"]);
+	 */
+	interface LoggerStorage {
+		get(categories: string[]): Logger;
+	}
+
+	/**
+	 * Upgrade event passed to onUpgrade callback during database.open().
+	 */
+	interface DatabaseUpgradeEvent {
+		/** The database being upgraded */
+		db: unknown;
+		/** Previous database version (0 if new) */
+		oldVersion: number;
+		/** Target version being opened */
+		newVersion: number;
+		/** Register a promise that must complete before open() resolves */
+		waitUntil(promise: Promise<unknown>): void;
+	}
+
+	/**
+	 * Database storage API for accessing named database instances.
+	 *
+	 * @example
+	 * // In activate - open with migrations
+	 * await self.databases.open("main", 2, (e) => {
+	 *   e.waitUntil(runMigrations(e));
+	 * });
+	 *
+	 * // In fetch - get opened database (sync)
+	 * const db = self.databases.get("main");
+	 */
+	interface DatabaseStorage {
+		/** Open a database at a specific version, running migrations if needed */
+		open(
+			name: string,
+			version: number,
+			onUpgrade?: (event: DatabaseUpgradeEvent) => void,
+		): Promise<unknown>;
+		/** Get an already-opened database (throws if not opened) */
+		get(name: string): unknown;
+		/** Close a specific database */
+		close(name: string): Promise<void>;
+		/** Close all databases */
+		closeAll(): Promise<void>;
+	}
+
+	/**
+	 * Directory storage API for accessing named directories.
+	 * @example const uploads = await directories.open("uploads");
+	 */
+	var directories: DirectoryStorage;
+
+	/**
+	 * Logger storage API for accessing named loggers.
+	 * @example const logger = self.loggers.get(["app"]);
+	 * @example const dbLogger = self.loggers.get(["app", "db"]);
+	 */
+	var loggers: LoggerStorage;
+
+	/**
+	 * Database storage API for accessing named database instances.
+	 * @example const db = self.databases.get("main");
+	 */
+	var databases: DatabaseStorage;
+
+	/**
+	 * Environment variables available via import.meta.env
+	 * Works across all platforms (Node/Bun via esbuild shim, Cloudflare natively)
+	 */
+	interface ImportMetaEnv {
+		readonly [key: string]: string | undefined;
+	}
+
+	interface ImportMeta {
+		readonly env: ImportMetaEnv;
+	}
+
+	/**
+	 * Augment WorkerGlobalScopeEventMap with ServiceWorker events.
+	 *
+	 * TypeScript's lib.webworker.d.ts declares `self` as `WorkerGlobalScope`, not
+	 * `ServiceWorkerGlobalScope`. This means `self.addEventListener("fetch", ...)`
+	 * doesn't know about FetchEvent. See: https://github.com/microsoft/TypeScript/issues/14877
+	 *
+	 * Rather than trying to redeclare `self` (which causes conflicts), we augment
+	 * the base WorkerGlobalScopeEventMap to include ServiceWorker-specific events.
+	 * This allows `self.addEventListener("fetch", (event) => ...)` to correctly
+	 * infer `event` as `FetchEvent`.
+	 */
+	interface WorkerGlobalScopeEventMap {
+		fetch: FetchEvent;
+		install: ExtendableEvent;
+		activate: ExtendableEvent;
+		message: ExtendableMessageEvent;
+		messageerror: MessageEvent;
+	}
+}
+
+export {};

package/src/index.d.ts

@@ -1,3 +1,5 @@
+/// <reference path="./globals.d.ts" />
+/// <reference path="./shovel-config.d.ts" />
 /**
  * @b9g/platform - Platform interface for ServiceWorker entrypoint loading
  *
@@ -6,11 +8,11 @@
  *
  * 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";
+export { validateConfig, ConfigValidationError } from "./config.js";
 /**
  * Platform configuration
  * Extended by platform-specific implementations (NodePlatformOptions, etc.)
@@ -25,13 +27,8 @@ export interface ServerOptions {
     port?: number;
     /** Host to bind to */
     host?: string;
-    /** Development mode settings */
-    development?: {
-        /** Source maps support */
-        sourceMaps?: boolean;
-        /** Verbose logging */
-        verbose?: boolean;
-    };
+    /** Enable SO_REUSEPORT for multi-worker deployments (Bun only) */
+    reusePort?: boolean;
 }
 /**
  * Request handler function (Web Fetch API compatible)
@@ -84,15 +81,18 @@ export interface ServiceWorkerInstance {
     dispose(): Promise<void>;
 }
 /**
- * Options for getEntryWrapper()
- * Reserved for future platform-specific options.
+ * Production entry points returned by getProductionEntryPoints().
+ * 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 interface EntryWrapperOptions {
-}
+export type ProductionEntryPoints = Record<string, string>;
 /**
- * Esbuild configuration subset that platforms can customize
+ * ESBuild configuration subset that platforms can customize
  */
-export interface PlatformEsbuildConfig {
+export interface PlatformESBuildConfig {
     /** Target platform: "node" or "browser" */
     platform?: "node" | "browser" | "neutral";
     /** Export conditions for package.json resolution */
@@ -101,16 +101,42 @@ export interface PlatformEsbuildConfig {
     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;
+}
+/**
+ * Default resource configuration for a named resource (cache, directory, etc.)
+ * Used by platforms to define built-in defaults that get merged with user config.
+ */
+export interface ResourceDefault {
+    /** Module path to import (e.g., "@b9g/cache/memory") */
+    module: string;
+    /** Named export to use (defaults to "default") */
+    export?: string;
+    /** Additional options (e.g., path for directories) */
+    [key: string]: unknown;
+}
+/**
+ * Platform-specific defaults for config generation.
+ * These are merged with user config at build time to provide
+ * sensible defaults for each platform.
+ */
+export interface PlatformDefaults {
+    /** Default directory configurations (server, public, tmp, etc.) */
+    directories?: Record<string, ResourceDefault>;
+    /** Default cache configuration (e.g., memory cache) */
+    caches?: Record<string, ResourceDefault>;
+}
+/**
+ * Extended ServiceWorkerContainer with internal methods for hot reload
+ */
+export interface ShovelServiceWorkerContainer extends ServiceWorkerContainer {
+    /** Internal: Get the worker pool for request handling */
+    readonly pool?: {
+        handleRequest(request: Request): Promise<Response>;
+    };
+    /** Internal: Terminate all workers */
+    terminate(): Promise<void>;
+    /** Internal: Reload workers (for hot reload) */
+    reloadWorkers(entrypoint: string): Promise<void>;
 }
 /**
  * Platform interface - ServiceWorker entrypoint loader for JavaScript runtimes
@@ -123,41 +149,77 @@ export interface Platform {
      */
     readonly name: string;
     /**
-     * Load and run a ServiceWorker-style entrypoint
-     * This is where all the platform-specific complexity lives
+     * ServiceWorkerContainer for managing registrations (Node/Bun only)
+     * Similar to navigator.serviceWorker in browsers
      */
-    loadServiceWorker(entrypoint: string, options?: ServiceWorkerOptions): Promise<ServiceWorkerInstance>;
+    readonly serviceWorker: ShovelServiceWorkerContainer;
     /**
-     * SUPPORTING UTILITY - Create cache storage
-     * Returns empty CacheStorage - applications create caches on-demand via caches.open()
+     * Start HTTP server and route requests to ServiceWorker (Node/Bun only)
+     * Must call serviceWorker.register() first
      */
-    createCaches(): Promise<CacheStorage>;
+    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 virtual entry wrapper template for user code
+     * 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.
      *
-     * 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)
+     * Platform determines the structure:
+     * - Cloudflare: { "worker": "<code>" } - single worker file
+     * - Node/Bun: { "index": "<supervisor>", "worker": "<runtime + user code>" }
      *
-     * 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.
+     * The user's entrypoint code is statically imported into the appropriate file.
      *
-     * @param entryPath - Absolute path to user's entrypoint file
-     * @param options - Additional options
+     * @param userEntryPath - Path to user's entrypoint (will be imported)
      */
-    getEntryWrapper(entryPath: string, options?: EntryWrapperOptions): string;
+    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;
+    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
@@ -206,7 +268,7 @@ export declare function resolvePlatform(options: {
 /**
  * Create platform instance based on name
  */
-export declare function createPlatform(platformName: string, options?: any): Promise<any>;
+export declare function createPlatform(platformName: string, options?: any): Promise<Platform>;
 /**
  * Base platform class with shared adapter loading logic
  * Platform implementations extend this and provide platform-specific methods
@@ -215,24 +277,57 @@ export declare abstract class BasePlatform implements Platform {
     config: PlatformConfig;
     constructor(config?: PlatformConfig);
     abstract readonly name: string;
-    abstract loadServiceWorker(entrypoint: string, options?: any): Promise<any>;
+    abstract readonly serviceWorker: ShovelServiceWorkerContainer;
+    abstract listen(): Promise<Server>;
+    abstract close(): Promise<void>;
     abstract createServer(handler: any, options?: any): any;
     /**
-     * Create cache storage
-     * Returns empty CacheStorage - applications create caches on-demand via caches.open()
+     * Get production entry points for bundling
+     * Subclasses must override to provide platform-specific entry points
      */
-    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;
+    abstract getProductionEntryPoints(userEntryPath: string): ProductionEntryPoints;
     /**
      * Get platform-specific esbuild configuration
      * Subclasses should override to provide platform-specific config
      */
-    abstract getEsbuildConfig(): PlatformEsbuildConfig;
+    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
+ *
+ * Deep merges each entry so user can override specific options without
+ * losing the platform's default implementation class.
+ *
+ * @param defaults - Platform's runtime defaults (with actual class refs)
+ * @param userConfig - User's config from shovel.json (may be partial)
+ * @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
  */
@@ -266,50 +361,6 @@ export interface ServiceWorkerRuntime {
     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
  */
@@ -320,6 +371,8 @@ export interface WorkerPoolOptions {
     requestTimeout?: number;
     /** Working directory for file resolution */
     cwd?: string;
+    /** Custom worker factory (if not provided, uses createWebWorker) */
+    createWorker?: (entrypoint: string) => Worker | Promise<Worker>;
 }
 export interface WorkerMessage {
     type: string;
@@ -345,13 +398,8 @@ export interface WorkerResponse extends WorkerMessage {
     };
     requestID: number;
 }
-export interface WorkerLoadMessage extends WorkerMessage {
-    type: "load";
-    entrypoint: string;
-}
 export interface WorkerReadyMessage extends WorkerMessage {
-    type: "ready" | "worker-ready";
-    entrypoint?: string;
+    type: "ready";
 }
 export interface WorkerErrorMessage extends WorkerMessage {
     type: "error";
@@ -359,21 +407,21 @@ export interface WorkerErrorMessage extends WorkerMessage {
     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
+ *
+ * With the unified build model, workers are self-contained bundles that:
+ * 1. Initialize their own runtime (via initWorkerRuntime)
+ * 2. Import user code
+ * 3. Run lifecycle events
+ * 4. Start message loop (via startWorkerMessageLoop)
+ *
+ * Hot reload is achieved by terminating old workers and creating new ones
+ * with the new bundle path.
  */
 export declare class ServiceWorkerPool {
     #private;
-    constructor(options?: WorkerPoolOptions, appEntrypoint?: string, cacheStorage?: CacheStorage, config?: any);
+    constructor(options: WorkerPoolOptions, appEntrypoint: string, cacheStorage?: CacheStorage);
     /**
      * Initialize workers (must be called after construction)
      */
@@ -383,8 +431,12 @@ export declare class ServiceWorkerPool {
      */
     handleRequest(request: Request): Promise<Response>;
     /**
-     * Reload ServiceWorker with new entrypoint (hot reload)
-     * The entrypoint path contains a content hash for cache busting
+     * Reload workers with new entrypoint (hot reload)
+     *
+     * With unified builds, hot reload means:
+     * 1. Gracefully shutdown existing workers (close databases, etc.)
+     * 2. Terminate workers after resources are closed
+     * 3. Create new workers with the new bundle
      */
     reloadWorkers(entrypoint: string): Promise<void>;
     /**
@@ -402,3 +454,4 @@ export declare class ServiceWorkerPool {
 }
 export { CustomLoggerStorage, type LoggerStorage };
 export type { LoggerFactory } from "./runtime.js";
+export { CustomDatabaseStorage, createDatabaseFactory, type DatabaseStorage, type DatabaseConfig, type DatabaseFactory, type DatabaseUpgradeEvent, } from "./runtime.js";