@b9g/platform 0.1.10 → 0.1.12

package/src/runtime.d.ts

@@ -2,14 +2,97 @@
  * 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.)
- * - ShovelGlobalScope (implements ServiceWorkerGlobalScope for any JavaScript runtime)
+ * - 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";
+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.
+ * 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.
+ */
+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"])
+     */
+    open(...categories: string[]): Logger;
+}
+/**
+ * Factory function type for creating loggers
+ */
+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;
+}
 /** Symbol for ending dispatch phase (internal use only) */
 declare const kEndDispatchPhase: unique symbol;
 /** Symbol for checking if extensions are allowed (internal use only) */
@@ -330,11 +413,13 @@ interface NotificationOptions {
     timestamp?: number;
     vibrate?: number[];
 }
-export interface ShovelGlobalScopeOptions {
+export interface ServiceWorkerGlobalsOptions {
     /** ServiceWorker registration instance */
     registration: ServiceWorkerRegistration;
-    /** Bucket storage (file system access) - REQUIRED */
-    buckets: BucketStorage;
+    /** Directory storage (file system access) - REQUIRED */
+    directories: DirectoryStorage;
+    /** Logger storage (logging access) - REQUIRED */
+    loggers: LoggerStorage;
     /** Cache storage (required by ServiceWorkerGlobalScope) - REQUIRED */
     caches: CacheStorage;
     /** Development mode flag */
@@ -353,17 +438,21 @@ export declare class WorkerGlobalScope {
 export declare class DedicatedWorkerGlobalScope extends WorkerGlobalScope {
 }
 /**
- * ShovelGlobalScope implements ServiceWorkerGlobalScope
+ * ServiceWorkerGlobals - Installs ServiceWorker globals onto globalThis
+ *
+ * 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.
  *
- * This is the `self` object in Shovel ServiceWorker applications.
- * It provides all standard ServiceWorker APIs plus Shovel-specific extensions.
+ * Use restore() to revert all patches (useful for testing).
  */
-export declare class ShovelGlobalScope implements ServiceWorkerGlobalScope {
+export declare class ServiceWorkerGlobals implements ServiceWorkerGlobalScope {
     #private;
     readonly self: any;
     readonly registration: ServiceWorkerRegistration;
     readonly caches: CacheStorage;
-    readonly buckets: BucketStorage;
+    readonly directories: DirectoryStorage;
+    readonly loggers: LoggerStorage;
     readonly clients: Clients;
     get cookieStore(): any;
     readonly serviceWorker: any;
@@ -405,22 +494,89 @@ export declare class ShovelGlobalScope implements ServiceWorkerGlobalScope {
     ononline: ((ev: Event) => any) | null;
     onrejectionhandled: ((ev: PromiseRejectionEvent) => any) | null;
     onunhandledrejection: ((ev: PromiseRejectionEvent) => any) | null;
-    constructor(options: ShovelGlobalScopeOptions);
+    constructor(options: ServiceWorkerGlobalsOptions);
     /**
      * Standard ServiceWorker skipWaiting() implementation
      * Allows the ServiceWorker to activate immediately
      */
     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;
     dispatchEvent(event: Event): boolean;
     /**
      * Install this scope as the global scope
-     * Sets up globalThis with all ServiceWorker globals
+     * Patches globalThis with ServiceWorker globals while maintaining self === globalThis
      */
     install(): void;
+    /**
+     * Restore original globals (for testing)
+     * Reverts all patched globals to their original values
+     */
+    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;
+    [key: string]: unknown;
+}
+/** Directory (filesystem) provider configuration */
+export interface DirectoryConfig {
+    provider?: string;
+    path?: string;
+    [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>;
+}
+/**
+ * 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)
+ */
+export declare function configureLogging(loggingConfig: LoggingConfig, options?: {
+    reset?: boolean;
+}): Promise<void>;
 export {};