@b9g/platform 0.1.11 → 0.1.13

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,9 +1,19 @@
+/// <reference path="./globals.d.ts" />
+/// <reference path="./shovel-config.d.ts" />
 /**
  * @b9g/platform - Platform interface for ServiceWorker entrypoint loading
  *
  * 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, type DatabaseStorage } from "./runtime.js";
+export { validateConfig, ConfigValidationError } from "./config.js";
 /**
  * Platform configuration
  * Extended by platform-specific implementations (NodePlatformOptions, etc.)
@@ -18,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)
@@ -76,6 +79,68 @@ export interface ServiceWorkerInstance {
     /** Dispose of resources */
     dispose(): Promise<void>;
 }
+/**
+ * Options for getEntryWrapper()
+ */
+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
+ */
+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;
+}
+/**
+ * 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
  *
@@ -92,14 +157,54 @@ export interface Platform {
      */
     loadServiceWorker(entrypoint: string, options?: ServiceWorkerOptions): Promise<ServiceWorkerInstance>;
     /**
-     * SUPPORTING UTILITY - Create cache storage
-     * Returns empty CacheStorage - applications create caches on-demand via caches.open()
+     * 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;
+    /**
+     * 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>;
     /**
-     * SUPPORTING UTILITY - Create server instance for this platform
+     * Create directory storage for this platform
+     * Uses platform-specific defaults, overridable via shovel.json config
      */
-    createServer(handler: Handler, options?: ServerOptions): Server;
+    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
@@ -126,11 +231,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;
 /**
@@ -164,10 +265,35 @@ export declare abstract class BasePlatform implements Platform {
     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()
+     * Get virtual entry wrapper template for user code
+     * Subclasses must override to provide platform-specific wrappers
      */
-    createCaches(): Promise<CacheStorage>;
+    abstract getEntryWrapper(entryPath: string, options?: EntryWrapperOptions): string;
+    /**
+     * 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>;
 }
 /**
  * Global platform registry
@@ -191,9 +317,152 @@ 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;
+    /** Database storage for the runtime */
+    databases?: DatabaseStorage;
+    /** 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 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
+ *
+ * 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);
+    /**
+     * Initialize workers (must be called after construction)
+     */
+    init(): Promise<void>;
+    /**
+     * Handle HTTP request using round-robin worker selection
+     */
+    handleRequest(request: Request): Promise<Response>;
+    /**
+     * 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>;
+    /**
+     * 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";
+export { CustomDatabaseStorage, createDatabaseFactory, type DatabaseStorage, type DatabaseConfig, type DatabaseFactory, type DatabaseUpgradeEvent, } from "./runtime.js";