@b9g/platform 0.1.11 → 0.1.13

package/src/runtime.d.ts

@@ -1,22 +1,209 @@
+/// <reference path="./globals.d.ts" />
+/// <reference path="./shovel-config.d.ts" />
 /**
  * ServiceWorker Runtime - Complete ServiceWorker API Implementation
  *
  * This module provides the complete ServiceWorker runtime environment for Shovel:
+ * - Cookie Store API (RequestCookieStore for per-request cookie management)
  * - Base Event Classes (ExtendableEvent, FetchEvent, InstallEvent, ActivateEvent)
  * - ServiceWorker API Type Shims (Client, Clients, ServiceWorkerRegistration, etc.)
  * - ServiceWorkerGlobals (installs ServiceWorker globals onto any JavaScript runtime)
  *
  * Based on: https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API#interfaces
  */
-import { RequestCookieStore } from "./cookie-store.js";
-import type { BucketStorage } from "@b9g/filesystem";
+import { CustomDirectoryStorage } from "@b9g/filesystem";
+import { CustomCacheStorage, Cache } from "@b9g/cache";
+declare global {
+    interface CookieListItem {
+        domain?: string;
+        path?: string;
+        expires?: number;
+        secure?: boolean;
+        sameSite?: CookieSameSite;
+        partitioned?: boolean;
+    }
+}
+export type CookieSameSite = globalThis.CookieSameSite;
+export type CookieInit = globalThis.CookieInit;
+export type CookieStoreGetOptions = globalThis.CookieStoreGetOptions;
+export type CookieStoreDeleteOptions = globalThis.CookieStoreDeleteOptions;
+export type CookieListItem = globalThis.CookieListItem;
+export type CookieList = CookieListItem[];
+/**
+ * Parse Cookie header value into key-value pairs
+ * Cookie: name=value; name2=value2
+ */
+export declare function parseCookieHeader(cookieHeader: string): Map<string, string>;
+/**
+ * Serialize cookie into Set-Cookie header value
+ */
+export declare function serializeCookie(cookie: CookieInit): string;
+/**
+ * Parse Set-Cookie header into CookieListItem
+ */
+export declare function parseSetCookieHeader(setCookieHeader: string): CookieListItem;
+/**
+ * RequestCookieStore - Cookie Store implementation for ServiceWorker contexts
+ *
+ * This implementation:
+ * - Reads cookies from the incoming Request's Cookie header
+ * - Tracks changes (set/delete operations)
+ * - Exports changes as Set-Cookie headers for the Response
+ *
+ * It follows the Cookie Store API spec but is designed for server-side
+ * request handling rather than browser contexts.
+ */
+export declare class RequestCookieStore extends EventTarget {
+    #private;
+    onchange: ((this: RequestCookieStore, ev: Event) => any) | null;
+    constructor(request?: Request);
+    get(nameOrOptions: string | CookieStoreGetOptions): Promise<CookieListItem | null>;
+    getAll(nameOrOptions?: string | CookieStoreGetOptions): Promise<CookieList>;
+    set(nameOrOptions: string | CookieInit, value?: string): Promise<void>;
+    delete(nameOrOptions: string | CookieStoreDeleteOptions): Promise<void>;
+    /**
+     * Get Set-Cookie headers for all changes
+     * This should be called when constructing the Response
+     */
+    getSetCookieHeaders(): string[];
+    hasChanges(): boolean;
+    clearChanges(): void;
+}
+import type { DirectoryStorage } from "@b9g/filesystem";
+import { type Logger } from "@logtape/logtape";
+/**
+ * Logger storage interface for accessing loggers by category path.
+ * Uses array signature (matching LogTape) to allow future options parameter.
+ */
+export interface LoggerStorage {
+    /**
+     * Get a logger by category path (sync)
+     * @example const logger = self.loggers.get(["app"])
+     * @example const logger = self.loggers.get(["app", "db"])
+     */
+    get(categories: string[]): Logger;
+}
+/**
+ * Factory function type for creating loggers (sync).
+ */
+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);
+    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
@@ -24,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;
@@ -35,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);
 }
 /**
@@ -111,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;
@@ -178,8 +386,13 @@ export declare class ShovelServiceWorkerRegistration extends EventTarget impleme
     activate(): Promise<void>;
     /**
      * Handle a fetch request (Shovel extension)
+     *
+     * 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>;
+    handleRequest(event: ShovelFetchEvent): Promise<Response>;
     /**
      * Check if ready to handle requests (Shovel extension)
      */
@@ -268,7 +481,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;
@@ -280,7 +493,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);
 }
@@ -304,7 +517,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);
@@ -333,8 +546,12 @@ interface NotificationOptions {
 export interface ServiceWorkerGlobalsOptions {
     /** ServiceWorker registration instance */
     registration: ServiceWorkerRegistration;
-    /** Bucket storage (file system access) - REQUIRED */
-    buckets: BucketStorage;
+    /** 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 */
     caches: CacheStorage;
     /** Development mode flag */
@@ -355,7 +572,7 @@ export declare class DedicatedWorkerGlobalScope extends WorkerGlobalScope {
 /**
  * ServiceWorkerGlobals - Installs ServiceWorker globals onto globalThis
  *
- * This class holds ServiceWorker API implementations (caches, buckets, clients, etc.)
+ * This class holds ServiceWorker API implementations (caches, directories, clients, etc.)
  * and patches them onto globalThis via install(). It maintains the browser invariant
  * that self === globalThis while providing ServiceWorker APIs.
  *
@@ -366,7 +583,9 @@ export declare class ServiceWorkerGlobals implements ServiceWorkerGlobalScope {
     readonly self: any;
     readonly registration: ServiceWorkerRegistration;
     readonly caches: CacheStorage;
-    readonly buckets: BucketStorage;
+    readonly directories: DirectoryStorage;
+    readonly databases?: DatabaseStorage;
+    readonly loggers: LoggerStorage;
     readonly clients: Clients;
     get cookieStore(): any;
     readonly serviceWorker: any;
@@ -415,7 +634,8 @@ export declare class ServiceWorkerGlobals implements ServiceWorkerGlobalScope {
      */
     skipWaiting(): Promise<void>;
     /**
-     * Event target delegation to registration
+     * Event target delegation - ServiceWorker events go to registration,
+     * other events (like "message" for worker threads) go to native handler
      */
     addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
     removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
@@ -431,4 +651,185 @@ export declare class ServiceWorkerGlobals implements ServiceWorkerGlobalScope {
      */
     restore(): void;
 }
+/** Cache provider configuration */
+export interface CacheConfig {
+    /** 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 {
+    /** 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) */
+export interface ShovelConfig {
+    port?: number;
+    host?: string;
+    workers?: number;
+    platform?: string;
+    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, startWorkerMessageLoop} from "@b9g/platform/runtime";
+ *
+ * const {registration} = await initWorkerRuntime({config});
+ *
+ * // Import user code (registers event handlers)
+ * import "./server.js";
+ *
+ * // Run lifecycle and start message loop
+ * await registration.install();
+ * await registration.activate();
+ * 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.
+ *
+ * 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): Promise<void>;
 export {};