@b9g/platform 0.1.4 → 0.1.6

package/src/runtime.d.ts

@@ -0,0 +1,426 @@
+/**
+ * ServiceWorker Runtime - Complete ServiceWorker API Implementation
+ *
+ * This module provides the complete ServiceWorker runtime environment for Shovel:
+ * - Base Event Classes (ExtendableEvent, FetchEvent, InstallEvent, ActivateEvent)
+ * - ServiceWorker API Type Shims (Client, Clients, ServiceWorkerRegistration, etc.)
+ * - ShovelGlobalScope (implements ServiceWorkerGlobalScope for 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";
+/** 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)
+ *
+ * Per spec, waitUntil() can be called:
+ * 1. Synchronously during event dispatch, OR
+ * 2. Asynchronously if there are pending promises from prior waitUntil/respondWith calls
+ *
+ * See: https://github.com/w3c/ServiceWorker/issues/771
+ */
+export declare class ExtendableEvent extends Event {
+    #private;
+    constructor(type: string, eventInitDict?: EventInit);
+    waitUntil(promise: Promise<any>): void;
+    getPromises(): Promise<any>[];
+    /** @internal Called after synchronous dispatch completes */
+    [kEndDispatchPhase](): void;
+    /** @internal Check if extensions are still allowed */
+    [kCanExtend](): boolean;
+}
+/**
+ * ServiceWorker-style fetch event
+ */
+export declare class FetchEvent extends ExtendableEvent {
+    #private;
+    readonly request: Request;
+    readonly cookieStore: RequestCookieStore;
+    constructor(request: Request, eventInitDict?: EventInit);
+    respondWith(response: Response | Promise<Response>): void;
+    getResponse(): Promise<Response> | null;
+    hasResponded(): boolean;
+}
+/**
+ * ServiceWorker-style install event
+ */
+export declare class InstallEvent extends ExtendableEvent {
+    constructor(eventInitDict?: EventInit);
+}
+/**
+ * ServiceWorker-style activate event
+ */
+export declare class ActivateEvent extends ExtendableEvent {
+    constructor(eventInitDict?: EventInit);
+}
+/**
+ * ShovelClient - Internal implementation of Client for Shovel runtime
+ * Note: Standard Client has no constructor - instances are created internally
+ */
+export declare class ShovelClient implements Client {
+    readonly frameType: "auxiliary" | "top-level" | "nested" | "none";
+    readonly id: string;
+    readonly type: "window" | "worker" | "sharedworker";
+    readonly url: string;
+    constructor(options: {
+        id: string;
+        url: string;
+        type?: "window" | "worker" | "sharedworker";
+    });
+    postMessage(message: any, transfer: Transferable[]): void;
+    postMessage(message: any, options?: StructuredSerializeOptions): void;
+}
+/**
+ * ShovelWindowClient - Internal implementation of WindowClient for Shovel runtime
+ * Note: Standard WindowClient has no constructor - instances are created internally
+ */
+export declare class ShovelWindowClient extends ShovelClient implements WindowClient {
+    readonly focused: boolean;
+    readonly visibilityState: DocumentVisibilityState;
+    constructor(options: {
+        id: string;
+        url: string;
+        focused?: boolean;
+        visibilityState?: DocumentVisibilityState;
+    });
+    focus(): Promise<WindowClient>;
+    navigate(_url: string): Promise<WindowClient | null>;
+}
+/**
+ * ShovelClients - Internal implementation of Clients for Shovel runtime
+ * Note: Standard Clients has no constructor - instances are created internally
+ */
+export declare class ShovelClients implements Clients {
+    claim(): Promise<void>;
+    get(_id: string): Promise<Client | undefined>;
+    matchAll<T extends ClientQueryOptions>(_options?: T): Promise<readonly (T["type"] extends "window" ? WindowClient : Client)[]>;
+    openWindow(_url: string): Promise<WindowClient | null>;
+}
+/**
+ * ExtendableMessageEvent represents message events with waitUntil support
+ */
+export interface ExtendableMessageEventInit extends EventInit {
+    data?: any;
+    origin?: string;
+    lastEventId?: string;
+    source?: Client | ServiceWorker | MessagePort | null;
+    ports?: MessagePort[];
+}
+export declare class ExtendableMessageEvent extends ExtendableEvent {
+    readonly data: any;
+    readonly origin: string;
+    readonly lastEventId: string;
+    readonly source: Client | ServiceWorker | MessagePort | null;
+    readonly ports: readonly MessagePort[];
+    constructor(type: string, eventInitDict?: ExtendableMessageEventInit);
+}
+/**
+ * ShovelServiceWorker - Internal implementation of ServiceWorker for Shovel runtime
+ * Note: Standard ServiceWorker has no constructor - instances are created internally
+ */
+export declare class ShovelServiceWorker extends EventTarget implements ServiceWorker {
+    scriptURL: string;
+    state: "parsed" | "installing" | "installed" | "activating" | "activated" | "redundant";
+    onstatechange: ((ev: Event) => any) | null;
+    onerror: ((ev: Event) => any) | null;
+    constructor(scriptURL: string, state?: "parsed" | "installing" | "installed" | "activating" | "activated" | "redundant");
+    postMessage(message: any, transfer: Transferable[]): void;
+    postMessage(message: any, options?: StructuredSerializeOptions): void;
+    _setState(newState: typeof this.state): void;
+}
+/**
+ * ShovelNavigationPreloadManager - Internal implementation of NavigationPreloadManager
+ * Note: Standard NavigationPreloadManager has no constructor - instances are created internally
+ */
+export declare class ShovelNavigationPreloadManager implements NavigationPreloadManager {
+    disable(): Promise<void>;
+    enable(): Promise<void>;
+    getState(): Promise<{
+        enabled: boolean;
+        headerValue: string;
+    }>;
+    setHeaderValue(_value: string): Promise<void>;
+}
+/**
+ * ShovelServiceWorkerRegistration - Internal implementation of ServiceWorkerRegistration
+ * This is also the Shovel ServiceWorker runtime - they are unified into one class
+ * Note: Standard ServiceWorkerRegistration has no constructor - instances are created internally
+ */
+export declare class ShovelServiceWorkerRegistration extends EventTarget implements ServiceWorkerRegistration {
+    readonly scope: string;
+    readonly updateViaCache: "imports" | "all" | "none";
+    readonly navigationPreload: NavigationPreloadManager;
+    _serviceWorker: ShovelServiceWorker;
+    readonly cookies: any;
+    readonly pushManager: any;
+    onupdatefound: ((ev: Event) => any) | null;
+    constructor(scope?: string, scriptURL?: string);
+    get active(): ServiceWorker | null;
+    get installing(): ServiceWorker | null;
+    get waiting(): ServiceWorker | null;
+    getNotifications(_options?: NotificationOptions): Promise<Notification[]>;
+    showNotification(_title: string, _options?: NotificationOptions): Promise<void>;
+    sync(): Promise<void>;
+    unregister(): Promise<boolean>;
+    update(): Promise<ServiceWorkerRegistration>;
+    /**
+     * Install the ServiceWorker (Shovel extension)
+     */
+    install(): Promise<void>;
+    /**
+     * Activate the ServiceWorker (Shovel extension)
+     */
+    activate(): Promise<void>;
+    /**
+     * Handle a fetch request (Shovel extension)
+     */
+    handleRequest(request: Request): Promise<Response>;
+    /**
+     * Check if ready to handle requests (Shovel extension)
+     */
+    get ready(): boolean;
+}
+/**
+ * ShovelServiceWorkerContainer - Internal implementation of ServiceWorkerContainer
+ * This is the registry that manages multiple ServiceWorkerRegistrations by scope
+ * Note: Standard ServiceWorkerContainer has no constructor - instances are created internally
+ */
+export declare class ShovelServiceWorkerContainer extends EventTarget implements ServiceWorkerContainer {
+    #private;
+    readonly controller: ServiceWorker | null;
+    readonly ready: Promise<ServiceWorkerRegistration>;
+    oncontrollerchange: ((ev: Event) => any) | null;
+    onmessage: ((ev: MessageEvent) => any) | null;
+    onmessageerror: ((ev: MessageEvent) => any) | null;
+    constructor();
+    /**
+     * Get registration for a specific scope
+     */
+    getRegistration(scope?: string): Promise<ServiceWorkerRegistration | undefined>;
+    /**
+     * Get all registrations
+     */
+    getRegistrations(): Promise<ServiceWorkerRegistration[]>;
+    /**
+     * Register a new ServiceWorker for a specific scope
+     */
+    register(scriptURL: string | URL, options?: {
+        scope?: string;
+        type?: "classic" | "module";
+        updateViaCache?: "imports" | "all" | "none";
+    }): Promise<ServiceWorkerRegistration>;
+    /**
+     * 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
+     */
+    installAll(): Promise<void>;
+    /**
+     * Get list of all scopes
+     */
+    getScopes(): string[];
+    startMessages(): void;
+}
+/**
+ * Notification interface for push notifications (server context stubs)
+ */
+export declare class Notification extends EventTarget {
+    readonly actions: readonly NotificationAction[];
+    readonly badge: string;
+    readonly body: string;
+    readonly data: any;
+    readonly dir: "auto" | "ltr" | "rtl";
+    readonly icon: string;
+    readonly image: string;
+    readonly lang: string;
+    readonly renotify: boolean;
+    readonly requireInteraction: boolean;
+    readonly silent: boolean;
+    readonly tag: string;
+    readonly timestamp: number;
+    readonly title: string;
+    readonly vibrate: readonly number[];
+    onclick: ((ev: Event) => any) | null;
+    onclose: ((ev: Event) => any) | null;
+    onerror: ((ev: Event) => any) | null;
+    onshow: ((ev: Event) => any) | null;
+    static permission: "default" | "denied" | "granted";
+    constructor(title: string, options?: NotificationOptions);
+    close(): void;
+    static requestPermission(): Promise<"default" | "denied" | "granted">;
+}
+/**
+ * NotificationEvent for notification interactions
+ */
+export interface NotificationEventInit extends EventInit {
+    action?: string;
+    notification: Notification;
+    reply?: string | null;
+}
+export declare class NotificationEvent extends ExtendableEvent {
+    readonly action: string;
+    readonly notification: Notification;
+    readonly reply: string | null;
+    constructor(type: string, eventInitDict: NotificationEventInit);
+}
+/**
+ * PushEvent for push message handling
+ */
+export interface PushEventInit extends EventInit {
+    data?: PushMessageData | null;
+}
+export declare class PushEvent extends ExtendableEvent {
+    readonly data: PushMessageData | null;
+    constructor(type: string, eventInitDict?: PushEventInit);
+}
+/**
+ * ShovelPushMessageData - Internal implementation of PushMessageData
+ * Note: Standard PushMessageData has no constructor - instances are created internally
+ */
+export declare class ShovelPushMessageData implements PushMessageData {
+    private _data;
+    constructor(_data: any);
+    arrayBuffer(): ArrayBuffer;
+    blob(): Blob;
+    bytes(): Uint8Array<ArrayBuffer>;
+    json(): any;
+    text(): string;
+}
+/**
+ * SyncEvent for background sync
+ */
+export interface SyncEventInit extends EventInit {
+    tag: string;
+    lastChance?: boolean;
+}
+export declare class SyncEvent extends ExtendableEvent {
+    readonly tag: string;
+    readonly lastChance: boolean;
+    constructor(type: string, eventInitDict: SyncEventInit);
+}
+interface NotificationAction {
+    action: string;
+    title: string;
+    icon?: string;
+}
+interface NotificationOptions {
+    actions?: NotificationAction[];
+    badge?: string;
+    body?: string;
+    data?: any;
+    dir?: "auto" | "ltr" | "rtl";
+    icon?: string;
+    image?: string;
+    lang?: string;
+    renotify?: boolean;
+    requireInteraction?: boolean;
+    silent?: boolean;
+    tag?: string;
+    timestamp?: number;
+    vibrate?: number[];
+}
+export interface ShovelGlobalScopeOptions {
+    /** ServiceWorker registration instance */
+    registration: ServiceWorkerRegistration;
+    /** Bucket storage (file system access) - REQUIRED */
+    buckets: BucketStorage;
+    /** Cache storage (required by ServiceWorkerGlobalScope) - REQUIRED */
+    caches: CacheStorage;
+    /** Development mode flag */
+    isDevelopment?: boolean;
+}
+/**
+ * Base class for all worker global scopes
+ * Part of the Web Worker standard - used for worker context detection
+ */
+export declare class WorkerGlobalScope {
+}
+/**
+ * Global scope for dedicated workers
+ * Part of the Web Worker standard - extends WorkerGlobalScope
+ */
+export declare class DedicatedWorkerGlobalScope extends WorkerGlobalScope {
+}
+/**
+ * ShovelGlobalScope implements ServiceWorkerGlobalScope
+ *
+ * This is the `self` object in Shovel ServiceWorker applications.
+ * It provides all standard ServiceWorker APIs plus Shovel-specific extensions.
+ */
+export declare class ShovelGlobalScope implements ServiceWorkerGlobalScope {
+    #private;
+    readonly self: any;
+    readonly registration: ServiceWorkerRegistration;
+    readonly caches: CacheStorage;
+    readonly buckets: BucketStorage;
+    readonly clients: Clients;
+    get cookieStore(): any;
+    readonly serviceWorker: any;
+    readonly location: WorkerLocation;
+    readonly navigator: WorkerNavigator;
+    readonly fonts: FontFaceSet;
+    readonly indexedDB: IDBFactory;
+    readonly isSecureContext: boolean;
+    readonly crossOriginIsolated: boolean;
+    readonly origin: string;
+    readonly performance: Performance;
+    readonly crypto: Crypto;
+    importScripts(..._urls: (string | URL)[]): void;
+    atob(data: string): string;
+    btoa(data: string): string;
+    clearInterval(id: number): void;
+    clearTimeout(id: number): void;
+    createImageBitmap(..._args: any[]): Promise<ImageBitmap>;
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    queueMicrotask(callback: VoidFunction): void;
+    reportError(e: any): void;
+    setInterval(handler: TimerHandler, timeout?: number, ...args: any[]): number;
+    setTimeout(handler: TimerHandler, timeout?: number, ...args: any[]): number;
+    structuredClone<T>(value: T, options?: StructuredSerializeOptions): T;
+    onactivate: ((this: ServiceWorkerGlobalScope, ev: globalThis.ExtendableEvent) => any) | null;
+    oncookiechange: ((this: ServiceWorkerGlobalScope, ev: Event) => any) | null;
+    onfetch: ((this: ServiceWorkerGlobalScope, ev: globalThis.FetchEvent) => any) | null;
+    oninstall: ((this: ServiceWorkerGlobalScope, ev: globalThis.ExtendableEvent) => any) | null;
+    onmessage: ((this: ServiceWorkerGlobalScope, ev: globalThis.ExtendableMessageEvent) => any) | null;
+    onmessageerror: ((this: ServiceWorkerGlobalScope, ev: MessageEvent) => any) | null;
+    onnotificationclick: ((this: ServiceWorkerGlobalScope, ev: globalThis.NotificationEvent) => any) | null;
+    onnotificationclose: ((this: ServiceWorkerGlobalScope, ev: globalThis.NotificationEvent) => any) | null;
+    onpush: ((this: ServiceWorkerGlobalScope, ev: globalThis.PushEvent) => any) | null;
+    onpushsubscriptionchange: ((this: ServiceWorkerGlobalScope, ev: Event) => any) | null;
+    onsync: ((this: ServiceWorkerGlobalScope, ev: SyncEvent) => any) | null;
+    onerror: OnErrorEventHandlerNonNull | null;
+    onlanguagechange: ((ev: Event) => any) | null;
+    onoffline: ((ev: Event) => any) | null;
+    ononline: ((ev: Event) => any) | null;
+    onrejectionhandled: ((ev: PromiseRejectionEvent) => any) | null;
+    onunhandledrejection: ((ev: PromiseRejectionEvent) => any) | null;
+    constructor(options: ShovelGlobalScopeOptions);
+    /**
+     * Standard ServiceWorker skipWaiting() implementation
+     * Allows the ServiceWorker to activate immediately
+     */
+    skipWaiting(): Promise<void>;
+    /**
+     * Event target delegation to registration
+     */
+    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
+     */
+    install(): void;
+}
+export {};