@b9g/platform 0.1.12 → 0.1.14-beta.0

package/src/runtime.d.ts

@@ -1,3 +1,5 @@
+/// <reference path="./globals.d.ts" />
+/// <reference path="./shovel-config.d.ts" />
 /**
  * ServiceWorker Runtime - Complete ServiceWorker API Implementation
  *
@@ -9,6 +11,8 @@
  *
  * Based on: https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API#interfaces
  */
+import { CustomDirectoryStorage } from "@b9g/filesystem";
+import { CustomCacheStorage, Cache } from "@b9g/cache";
 declare global {
     interface CookieListItem {
         domain?: string;
@@ -69,37 +73,137 @@ import type { DirectoryStorage } from "@b9g/filesystem";
 import { type Logger } from "@logtape/logtape";
 /**
  * Logger storage interface for accessing loggers by category path.
- * Unlike CacheStorage/DirectoryStorage which use a registry pattern,
- * LoggerStorage uses variadic categories since logging backends are
- * always LogTape and per-category config is in shovel.config.json.
+ * Uses array signature (matching LogTape) to allow future options parameter.
  */
 export interface LoggerStorage {
     /**
-     * Open a logger by category path - returns LogTape's Logger directly
-     * @example loggers.open("app") → getLogger(["app"])
-     * @example loggers.open("app", "db") → getLogger(["app", "db"])
+     * Get a logger by category path (sync)
+     * @example const logger = self.loggers.get(["app"])
+     * @example const logger = self.loggers.get(["app", "db"])
      */
-    open(...categories: string[]): Logger;
+    get(categories: string[]): Logger;
 }
 /**
- * Factory function type for creating loggers
+ * Factory function type for creating loggers (sync).
  */
-export type LoggerFactory = (...categories: string[]) => Logger;
+export type LoggerFactory = (categories: string[]) => Logger;
 /**
  * Custom logger storage implementation that wraps a factory function
  */
 export declare class CustomLoggerStorage implements LoggerStorage {
     #private;
     constructor(factory: LoggerFactory);
-    open(...categories: string[]): Logger;
+    get(categories: string[]): Logger;
 }
+import { Database } from "@b9g/zen";
+/**
+ * Database configuration from shovel.json.
+ * Uses the unified impl pattern like directories and caches.
+ */
+export interface DatabaseConfig {
+    /** Reified implementation (driver class from build-time code generation) */
+    impl?: new (url: string, options?: any) => any;
+    /** Database connection URL */
+    url?: string;
+    /** Additional driver-specific options */
+    [key: string]: unknown;
+}
+/**
+ * Upgrade event passed to onUpgrade callback during database.open().
+ */
+export interface DatabaseUpgradeEvent {
+    /** The database being upgraded */
+    db: Database;
+    /** 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;
+}
+/**
+ * DatabaseStorage interface - provides access to named database instances.
+ *
+ * @example
+ * ```typescript
+ * // In activate handler - open database with migrations
+ * self.addEventListener("activate", (event) => {
+ *   event.waitUntil(
+ *     self.databases.open("main", 2, (e) => {
+ *       e.waitUntil(runMigrations(e));
+ *     })
+ *   );
+ * });
+ *
+ * // In fetch handler - get the opened database (sync)
+ * self.addEventListener("fetch", (event) => {
+ *   const db = self.databases.get("main");
+ *   const users = await db.all(User)`WHERE active = ${true}`;
+ * });
+ * ```
+ */
+export interface DatabaseStorage {
+    /**
+     * Open a database at a specific version.
+     * Imports the driver, creates the Database, runs migrations if needed.
+     * Caches the opened instance for later get() calls.
+     */
+    open(name: string, version: number, onUpgrade?: (event: DatabaseUpgradeEvent) => void): Promise<Database>;
+    /**
+     * Get an already-opened database.
+     * Throws if the database hasn't been opened yet.
+     * This is synchronous for fast access in request handlers.
+     */
+    get(name: string): Database;
+    /** Close a specific database */
+    close(name: string): Promise<void>;
+    /** Close all databases */
+    closeAll(): Promise<void>;
+}
+/**
+ * Factory function type for creating database drivers.
+ * Returns the Database instance and a close function.
+ */
+export type DatabaseFactory = (name: string) => Promise<{
+    db: Database;
+    close: () => Promise<void>;
+}>;
+/**
+ * CustomDatabaseStorage implements DatabaseStorage.
+ */
+export declare class CustomDatabaseStorage implements DatabaseStorage {
+    #private;
+    constructor(factory: DatabaseFactory);
+    open(name: string, version: number, onUpgrade?: (event: DatabaseUpgradeEvent) => void): Promise<Database>;
+    get(name: string): Database;
+    close(name: string): Promise<void>;
+    closeAll(): Promise<void>;
+}
+/**
+ * Create a DatabaseFactory from declarative config.
+ *
+ * This dynamically imports the driver module at runtime, following
+ * the same pattern as createDirectoryFactory and createCacheFactory.
+ *
+ * @param configs - The databases config from shovel.json
+ * @returns An async factory function that creates databases by name
+ *
+ * @example
+ * ```typescript
+ * // In platform adapter:
+ * const factory = createDatabaseFactory(config.databases);
+ * return new CustomDatabaseStorage(factory);
+ * ```
+ */
+export declare function createDatabaseFactory(configs: Record<string, DatabaseConfig>): DatabaseFactory;
 /** Symbol for ending dispatch phase (internal use only) */
 declare const kEndDispatchPhase: unique symbol;
 /** Symbol for checking if extensions are allowed (internal use only) */
 declare const kCanExtend: unique symbol;
 /**
- * ExtendableEvent base class following ServiceWorker spec
- * Standard constructor: new ExtendableEvent(type) or new ExtendableEvent(type, options)
+ * Shovel's ExtendableEvent implementation following ServiceWorker spec.
+ *
+ * Standard constructor: new ShovelExtendableEvent(type) or new ShovelExtendableEvent(type, options)
  *
  * Per spec, waitUntil() can be called:
  * 1. Synchronously during event dispatch, OR
@@ -107,7 +211,7 @@ declare const kCanExtend: unique symbol;
  *
  * See: https://github.com/w3c/ServiceWorker/issues/771
  */
-export declare class ExtendableEvent extends Event {
+export declare class ShovelExtendableEvent extends Event implements ExtendableEvent {
     #private;
     constructor(type: string, eventInitDict?: EventInit);
     waitUntil(promise: Promise<any>): void;
@@ -118,27 +222,48 @@ export declare class ExtendableEvent extends Event {
     [kCanExtend](): boolean;
 }
 /**
- * ServiceWorker-style fetch event
+ * Options for ShovelFetchEvent constructor (non-standard Shovel extension)
  */
-export declare class FetchEvent extends ExtendableEvent {
+export interface ShovelFetchEventInit extends EventInit {
+    /**
+     * Platform-provided callback for extending request lifetime.
+     * Called automatically when waitUntil() is invoked.
+     * (e.g., Cloudflare's ctx.waitUntil)
+     */
+    platformWaitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * Shovel's FetchEvent implementation.
+ *
+ * Platforms can subclass this to add platform-specific properties (e.g., env bindings).
+ * The platformWaitUntil hook allows platforms to extend request lifetime properly.
+ */
+export declare class ShovelFetchEvent extends ShovelExtendableEvent implements FetchEvent {
     #private;
     readonly request: Request;
     readonly cookieStore: RequestCookieStore;
-    constructor(request: Request, eventInitDict?: EventInit);
+    readonly clientId: string;
+    readonly handled: Promise<undefined>;
+    readonly preloadResponse: Promise<any>;
+    readonly resultingClientId: string;
+    constructor(request: Request, options?: ShovelFetchEventInit);
+    waitUntil(promise: Promise<any>): void;
     respondWith(response: Response | Promise<Response>): void;
     getResponse(): Promise<Response> | null;
     hasResponded(): boolean;
+    /** The URL of the request (convenience property) */
+    get url(): string;
 }
 /**
- * ServiceWorker-style install event
+ * Shovel's InstallEvent implementation
  */
-export declare class InstallEvent extends ExtendableEvent {
+export declare class ShovelInstallEvent extends ShovelExtendableEvent {
     constructor(eventInitDict?: EventInit);
 }
 /**
- * ServiceWorker-style activate event
+ * Shovel's ActivateEvent implementation
  */
-export declare class ActivateEvent extends ExtendableEvent {
+export declare class ShovelActivateEvent extends ShovelExtendableEvent {
     constructor(eventInitDict?: EventInit);
 }
 /**
@@ -194,7 +319,7 @@ export interface ExtendableMessageEventInit extends EventInit {
     source?: Client | ServiceWorker | MessagePort | null;
     ports?: MessagePort[];
 }
-export declare class ExtendableMessageEvent extends ExtendableEvent {
+export declare class ExtendableMessageEvent extends ShovelExtendableEvent {
     readonly data: any;
     readonly origin: string;
     readonly lastEventId: string;
@@ -229,6 +354,14 @@ export declare class ShovelNavigationPreloadManager implements NavigationPreload
     }>;
     setHeaderValue(_value: string): Promise<void>;
 }
+/** @internal Symbol for accessing the internal ServiceWorker instance */
+export declare const kServiceWorker: unique symbol;
+/** @internal Symbol for dispatching the install lifecycle event */
+export declare const kDispatchInstall: unique symbol;
+/** @internal Symbol for dispatching the activate lifecycle event */
+export declare const kDispatchActivate: unique symbol;
+/** @internal Symbol for handling fetch requests */
+declare const kHandleRequest: unique symbol;
 /**
  * ShovelServiceWorkerRegistration - Internal implementation of ServiceWorkerRegistration
  * This is also the Shovel ServiceWorker runtime - they are unified into one class
@@ -238,7 +371,7 @@ export declare class ShovelServiceWorkerRegistration extends EventTarget impleme
     readonly scope: string;
     readonly updateViaCache: "imports" | "all" | "none";
     readonly navigationPreload: NavigationPreloadManager;
-    _serviceWorker: ShovelServiceWorker;
+    [kServiceWorker]: ShovelServiceWorker;
     readonly cookies: any;
     readonly pushManager: any;
     onupdatefound: ((ev: Event) => any) | null;
@@ -252,22 +385,71 @@ export declare class ShovelServiceWorkerRegistration extends EventTarget impleme
     unregister(): Promise<boolean>;
     update(): Promise<ServiceWorkerRegistration>;
     /**
-     * Install the ServiceWorker (Shovel extension)
+     * Dispatch the install lifecycle event
+     * @internal Use runLifecycle() instead of calling this directly
      */
-    install(): Promise<void>;
+    [kDispatchInstall](): Promise<void>;
     /**
-     * Activate the ServiceWorker (Shovel extension)
+     * Dispatch the activate lifecycle event
+     * @internal Use runLifecycle() instead of calling this directly
      */
-    activate(): Promise<void>;
+    [kDispatchActivate](): Promise<void>;
     /**
-     * Handle a fetch request (Shovel extension)
+     * Handle a fetch request
+     * @internal Use the kHandleRequest symbol to access this method
+     *
+     * Platforms create a ShovelFetchEvent (or subclass) with platform-specific
+     * properties and hooks, then pass it to this method for dispatching.
+     *
+     * @param event - The fetch event to handle (created by platform adapter)
      */
-    handleRequest(request: Request): Promise<Response>;
+    [kHandleRequest](event: ShovelFetchEvent): Promise<Response>;
     /**
      * Check if ready to handle requests (Shovel extension)
      */
     get ready(): boolean;
 }
+/**
+ * Run ServiceWorker lifecycle events on a registration.
+ *
+ * This is the proper way to trigger lifecycle events in Shovel's server-side runtime.
+ * Unlike browsers where lifecycle is automatic, server-side code must explicitly
+ * trigger these events after registering event handlers.
+ *
+ * @param registration - The ServiceWorkerRegistration to run lifecycle on
+ * @param stage - Which lifecycle stage to run:
+ *   - "install": Run only the install event
+ *   - "activate": Run install then activate (default)
+ *
+ * @example
+ * ```typescript
+ * const {registration} = await initWorkerRuntime({config});
+ * await import("./server.js"); // Register event handlers
+ * await runLifecycle(registration); // Runs install + activate
+ * ```
+ */
+export declare function runLifecycle(registration: ShovelServiceWorkerRegistration, stage?: "install" | "activate"): Promise<void>;
+/**
+ * Dispatch a fetch request to a ServiceWorker registration.
+ *
+ * This is the proper way to dispatch requests in Shovel's server-side runtime.
+ * Platforms should use this function rather than accessing internal methods directly.
+ *
+ * @param registration - The ServiceWorkerRegistration to dispatch to
+ * @param requestOrEvent - The Request to dispatch, or a pre-constructed ShovelFetchEvent
+ * @returns The Response from the ServiceWorker
+ *
+ * @example
+ * ```typescript
+ * // Simple usage with a Request
+ * const response = await dispatchRequest(registration, request);
+ *
+ * // Platform-specific usage with a custom FetchEvent subclass
+ * const event = new CloudflareFetchEvent(request, {env, platformWaitUntil});
+ * const response = await dispatchRequest(registration, event);
+ * ```
+ */
+export declare function dispatchRequest(registration: ShovelServiceWorkerRegistration, requestOrEvent: Request | ShovelFetchEvent): Promise<Response>;
 /**
  * ShovelServiceWorkerContainer - Internal implementation of ServiceWorkerContainer
  * This is the registry that manages multiple ServiceWorkerRegistrations by scope
@@ -301,10 +483,6 @@ export declare class ShovelServiceWorkerContainer extends EventTarget implements
      * Unregister a ServiceWorker registration
      */
     unregister(scope: string): Promise<boolean>;
-    /**
-     * Route a request to the appropriate registration based on scope matching
-     */
-    handleRequest(request: Request): Promise<Response | null>;
     /**
      * Install and activate all registrations
      */
@@ -351,7 +529,7 @@ export interface NotificationEventInit extends EventInit {
     notification: Notification;
     reply?: string | null;
 }
-export declare class NotificationEvent extends ExtendableEvent {
+export declare class NotificationEvent extends ShovelExtendableEvent {
     readonly action: string;
     readonly notification: Notification;
     readonly reply: string | null;
@@ -363,7 +541,7 @@ export declare class NotificationEvent extends ExtendableEvent {
 export interface PushEventInit extends EventInit {
     data?: PushMessageData | null;
 }
-export declare class PushEvent extends ExtendableEvent {
+export declare class PushEvent extends ShovelExtendableEvent {
     readonly data: PushMessageData | null;
     constructor(type: string, eventInitDict?: PushEventInit);
 }
@@ -387,7 +565,7 @@ export interface SyncEventInit extends EventInit {
     tag: string;
     lastChance?: boolean;
 }
-export declare class SyncEvent extends ExtendableEvent {
+export declare class SyncEvent extends ShovelExtendableEvent {
     readonly tag: string;
     readonly lastChance: boolean;
     constructor(type: string, eventInitDict: SyncEventInit);
@@ -418,6 +596,8 @@ export interface ServiceWorkerGlobalsOptions {
     registration: ServiceWorkerRegistration;
     /** Directory storage (file system access) - REQUIRED */
     directories: DirectoryStorage;
+    /** Database storage - OPTIONAL */
+    databases?: DatabaseStorage;
     /** Logger storage (logging access) - REQUIRED */
     loggers: LoggerStorage;
     /** Cache storage (required by ServiceWorkerGlobalScope) - REQUIRED */
@@ -452,6 +632,7 @@ export declare class ServiceWorkerGlobals implements ServiceWorkerGlobalScope {
     readonly registration: ServiceWorkerRegistration;
     readonly caches: CacheStorage;
     readonly directories: DirectoryStorage;
+    readonly databases?: DatabaseStorage;
     readonly loggers: LoggerStorage;
     readonly clients: Clients;
     get cookieStore(): any;
@@ -518,44 +699,20 @@ export declare class ServiceWorkerGlobals implements ServiceWorkerGlobalScope {
      */
     restore(): void;
 }
-/** Log level for filtering */
-export type LogLevel = "debug" | "info" | "warning" | "error";
-/** Sink configuration */
-export interface SinkConfig {
-    provider: string;
-    /** Pre-imported factory function (from build-time code generation) */
-    factory?: (options: Record<string, unknown>) => unknown;
-    /** Provider-specific options (path, maxSize, etc.) */
-    [key: string]: any;
-}
-/** Per-category logging configuration */
-export interface CategoryLoggingConfig {
-    level?: LogLevel;
-    sinks?: SinkConfig[];
-}
-export interface LoggingConfig {
-    /** Default log level. Defaults to "info" */
-    level?: LogLevel;
-    /** Default sinks. Defaults to console */
-    sinks?: SinkConfig[];
-    /** Per-category config (inherits from top-level, can override level and/or sinks) */
-    categories?: Record<string, CategoryLoggingConfig>;
-}
-/** Processed logging config with all defaults applied */
-export interface ProcessedLoggingConfig {
-    level: LogLevel;
-    sinks: SinkConfig[];
-    categories: Record<string, CategoryLoggingConfig>;
-}
 /** Cache provider configuration */
 export interface CacheConfig {
-    provider?: string;
+    /** Reified implementation (class or factory from build-time code generation) */
+    impl?: (new (name: string, options?: any) => Cache) | ((name: string, options?: any) => Cache);
+    /** Additional options passed to the constructor */
     [key: string]: unknown;
 }
 /** Directory (filesystem) provider configuration */
 export interface DirectoryConfig {
-    provider?: string;
+    /** Reified implementation (class or factory from build-time code generation) */
+    impl?: (new (name: string, options?: any) => FileSystemDirectoryHandle) | ((name: string, options?: any) => FileSystemDirectoryHandle);
+    /** Custom path for filesystem directories */
     path?: string;
+    /** Additional options passed to the constructor */
     [key: string]: unknown;
 }
 /** Shovel application configuration (from shovel.json) */
@@ -567,16 +724,159 @@ export interface ShovelConfig {
     logging?: LoggingConfig;
     caches?: Record<string, CacheConfig>;
     directories?: Record<string, DirectoryConfig>;
+    databases?: Record<string, DatabaseConfig>;
+}
+/**
+ * Creates a directory factory function for CustomDirectoryStorage.
+ *
+ * Configs must have impl pre-imported (from generated config module).
+ * Paths are expected to be already resolved at build time by the path syntax parser.
+ * Runtime paths (like [tmpdir]) are evaluated as expressions in the generated config.
+ */
+export declare function createDirectoryFactory(configs: Record<string, DirectoryConfig>): (name: string) => Promise<FileSystemDirectoryHandle>;
+export interface CacheFactoryOptions {
+    /** Cache configurations with pre-imported CacheClass (from generated config module) */
+    configs: Record<string, CacheConfig>;
+    /** If true, use PostMessageCache (for workers communicating with main thread) */
+    usePostMessage?: boolean;
+}
+/**
+ * Creates a cache factory function for CustomCacheStorage.
+ * Configs must have impl pre-imported (from generated config module).
+ */
+export declare function createCacheFactory(options: CacheFactoryOptions): (name: string) => Promise<Cache>;
+/**
+ * Worker message types for the message loop
+ */
+export interface WorkerRequestMessage {
+    type: "request";
+    request: {
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        body?: ArrayBuffer | null;
+    };
+    requestID: number;
+}
+export interface WorkerResponseMessage {
+    type: "response";
+    response: {
+        status: number;
+        statusText: string;
+        headers: Record<string, string>;
+        body: ArrayBuffer;
+    };
+    requestID: number;
+}
+export interface WorkerErrorMessage {
+    type: "error";
+    error: string;
+    stack?: string;
+    requestID?: number;
+}
+/**
+ * Options for initializing the worker runtime
+ */
+export interface InitWorkerRuntimeOptions {
+    /** Shovel configuration (from shovel:config) */
+    config: ShovelConfig;
+}
+/**
+ * Result from initializing the worker runtime
+ */
+export interface InitWorkerRuntimeResult {
+    /** The ServiceWorker registration instance */
+    registration: ShovelServiceWorkerRegistration;
+    /** The installed ServiceWorkerGlobals scope */
+    scope: ServiceWorkerGlobals;
+    /** Cache storage instance */
+    caches: CustomCacheStorage;
+    /** Directory storage instance */
+    directories: CustomDirectoryStorage;
+    /** Database storage instance (if configured) */
+    databases?: CustomDatabaseStorage;
+    /** Logger storage instance */
+    loggers: CustomLoggerStorage;
+}
+/**
+ * Initialize the worker runtime environment.
+ * Sets up ServiceWorkerGlobals, caches, directories, and logging.
+ *
+ * This should be called at the top of a worker entry point before importing user code.
+ *
+ * @example
+ * ```typescript
+ * import {config} from "shovel:config";
+ * import {initWorkerRuntime, runLifecycle, startWorkerMessageLoop} from "@b9g/platform/runtime";
+ *
+ * const {registration} = await initWorkerRuntime({config});
+ *
+ * // Import user code (registers event handlers)
+ * await import("./server.js");
+ *
+ * // Run lifecycle and start message loop
+ * await runLifecycle(registration);
+ * startWorkerMessageLoop(registration);
+ * ```
+ */
+export declare function initWorkerRuntime(options: InitWorkerRuntimeOptions): Promise<InitWorkerRuntimeResult>;
+/**
+ * Options for the worker message loop
+ */
+export interface WorkerMessageLoopOptions {
+    registration: ShovelServiceWorkerRegistration;
+    databases?: CustomDatabaseStorage;
+    caches?: CacheStorage;
+}
+/**
+ * Start the worker message loop for handling requests.
+ * This function sets up message handling for request/response communication
+ * with the main thread via postMessage.
+ *
+ * @param options - The registration and resources to manage
+ */
+export declare function startWorkerMessageLoop(options: ShovelServiceWorkerRegistration | WorkerMessageLoopOptions): void;
+/** Log level for filtering */
+export type LogLevel = "debug" | "info" | "warning" | "error";
+/** Sink configuration */
+export interface SinkConfig {
+    /** Reified implementation (factory function from build-time code generation) */
+    impl?: (...args: any[]) => unknown;
+    /** Additional options passed to the factory (path, maxSize, etc.) */
+    [key: string]: unknown;
+}
+/** Logger configuration - matches LogTape's logger config structure */
+export interface LoggerConfig {
+    /** Category as string or array for hierarchy. e.g. "myapp" or ["myapp", "db"] */
+    category: string | string[];
+    /** Log level for this category. Inherits from parent if not specified. */
+    level?: LogLevel;
+    /** Sink names to add. Inherits from parent by default. */
+    sinks?: string[];
+    /** Set to "override" to replace parent sinks instead of inherit */
+    parentSinks?: "override";
+}
+export interface LoggingConfig {
+    /** Named sinks. "console" is always available implicitly. */
+    sinks?: Record<string, SinkConfig>;
+    /** Logger configurations. Shovel provides defaults for ["shovel", ...] categories. */
+    loggers?: LoggerConfig[];
+}
+/** Processed logging config with all defaults applied */
+export interface ProcessedLoggingConfig {
+    sinks: Record<string, SinkConfig>;
+    loggers: LoggerConfig[];
 }
 /**
  * Configure LogTape logging based on Shovel config.
  * Call this in both main thread and workers.
  *
- * @param loggingConfig - The logging configuration (sinks defaults to console)
- * @param options - Additional options
- * @param options.reset - Whether to reset existing LogTape config (default: true)
+ * Uses LogTape-aligned config structure:
+ * - Named sinks (console is implicit)
+ * - Loggers array with category hierarchy support
+ * - Shovel provides default loggers for ["shovel", ...] categories
+ *
+ * @param loggingConfig - The logging configuration
  */
-export declare function configureLogging(loggingConfig: LoggingConfig, options?: {
-    reset?: boolean;
-}): Promise<void>;
+export declare function configureLogging(loggingConfig: LoggingConfig): Promise<void>;
 export {};