@b9g/platform 0.1.12 → 0.1.13

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.13",
+  "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/async-context": "^0.2.0-beta.0",
+    "@b9g/cache": "^0.2.0-beta.0",
     "@b9g/filesystem": "^0.1.7",
+    "@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.10",
+    "@b9g/platform-node": "^0.1.12"
   },
   "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
  *
@@ -10,7 +12,8 @@
  * - ServiceWorkerPool for multi-worker execution
  */
 import type { DirectoryStorage } from "@b9g/filesystem";
-import { CustomLoggerStorage, type LoggerStorage } from "./runtime.js";
+import { CustomLoggerStorage, type LoggerStorage, type DatabaseStorage } from "./runtime.js";
+export { validateConfig, ConfigValidationError } from "./config.js";
 /**
  * Platform configuration
  * Extended by platform-specific implementations (NodePlatformOptions, etc.)
@@ -25,13 +28,6 @@ export interface ServerOptions {
     port?: number;
     /** Host to bind to */
     host?: string;
-    /** Development mode settings */
-    development?: {
-        /** Source maps support */
-        sourceMaps?: boolean;
-        /** Verbose logging */
-        verbose?: boolean;
-    };
 }
 /**
  * Request handler function (Web Fetch API compatible)
@@ -85,14 +81,24 @@ export interface ServiceWorkerInstance {
 }
 /**
  * Options for getEntryWrapper()
- * Reserved for future platform-specific options.
  */
 export interface EntryWrapperOptions {
+    /**
+     * Type of entry wrapper to generate:
+     * - "production": Production server entry (default) - runs the server directly
+     * - "worker": Worker entry for ServiceWorkerPool - sets up runtime and message loop
+     */
+    type?: "production" | "worker";
+    /**
+     * Output directory for the build. Used to generate absolute paths for
+     * directory defaults (server, public). Required for "worker" type.
+     */
+    outDir?: 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 */
@@ -112,6 +118,29 @@ export interface PlatformEsbuildConfig {
      */
     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>;
+}
 /**
  * Platform interface - ServiceWorker entrypoint loader for JavaScript runtimes
  *
@@ -127,11 +156,6 @@ export interface Platform {
      * This is where all the platform-specific complexity lives
      */
     loadServiceWorker(entrypoint: string, options?: ServiceWorkerOptions): Promise<ServiceWorkerInstance>;
-    /**
-     * SUPPORTING UTILITY - Create cache storage
-     * Returns empty CacheStorage - applications create caches on-demand via caches.open()
-     */
-    createCaches(): Promise<CacheStorage>;
     /**
      * SUPPORTING UTILITY - Create server instance for this platform
      */
@@ -157,7 +181,30 @@ export interface Platform {
      * 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>;
 }
 /**
  * Platform registry - internal implementation
@@ -217,11 +264,6 @@ export declare abstract class BasePlatform implements Platform {
     abstract readonly name: string;
     abstract loadServiceWorker(entrypoint: string, options?: any): Promise<any>;
     abstract createServer(handler: any, options?: any): any;
-    /**
-     * Create cache storage
-     * 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
@@ -231,7 +273,27 @@ export declare abstract class BasePlatform implements Platform {
      * 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>;
 }
 /**
  * Global platform registry
@@ -271,6 +333,8 @@ export interface SingleThreadedRuntimeOptions {
     caches: CacheStorage;
     /** Directory storage for the runtime */
     directories: DirectoryStorage;
+    /** Database storage for the runtime */
+    databases?: DatabaseStorage;
     /** Logger storage for the runtime */
     loggers: LoggerStorage;
 }
@@ -345,13 +409,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 +418,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 +442,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 +465,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";