vscode-extension-messaging-framework 1.0.0

package/README.md

@@ -0,0 +1,139 @@
+# vscode-extension-messaging-framework
+
+A TypeScript library that wraps VS Code's `postMessage` API with typed request/response semantics, timeout handling, and error propagation.
+
+## Why
+
+VS Code webview communication via `postMessage` is untyped and fire-and-forget. There's no built-in way to send a request and wait for a response, handle timeouts, or propagate errors. You end up writing boilerplate to correlate messages, track pending requests, and serialize errors.
+
+This library gives you:
+
+- **Request/response** - send a request, `await` the result
+- **Notifications** - fire-and-forget messages
+- **Bidirectional** - both extension and webview can send requests to each other
+- **Type safety** - define a schema once, get compile-time checks on method names, params, and results
+- **Timeout handling** - configurable per-request or per-messenger, with automatic cleanup
+- **Error propagation** - errors thrown in handlers are serialized, sent across the boundary, and re-thrown as `MessagingError` on the caller side
+
+## Install
+
+```
+npm install vscode-extension-messaging-framework
+```
+
+## Usage
+
+### 1. Define a schema
+
+Create a shared schema that both your extension and webview code can import:
+
+```ts
+import type { DefineRequest, DefineNotification, MessageSchema } from 'vscode-extension-messaging-framework/shared';
+
+type GetUser = DefineRequest<'getUser', { id: string }, { name: string; email: string }>;
+type SaveDraft = DefineRequest<'saveDraft', { content: string }, { saved: boolean }>;
+type ThemeChanged = DefineNotification<'themeChanged', { theme: 'light' | 'dark' }>;
+
+export interface MySchema extends MessageSchema {
+  webviewRequests: GetUser | SaveDraft;    // webview -> extension
+  extensionRequests: never;                 // extension -> webview (none in this example)
+  webviewNotifications: never;
+  extensionNotifications: ThemeChanged;
+}
+```
+
+### 2. Extension side
+
+```ts
+import { ExtensionMessenger } from 'vscode-extension-messaging-framework/extension';
+import type { MySchema } from './shared/schema';
+
+const messenger = new ExtensionMessenger<MySchema>(panel.webview, {
+  defaultTimeout: 5000,
+});
+
+// Handle requests from the webview
+messenger.onRequest('getUser', async ({ id }) => {
+  const user = await db.findUser(id);
+  return { name: user.name, email: user.email };
+});
+
+// Send a notification to the webview
+messenger.notify('themeChanged', { theme: 'dark' });
+```
+
+### 3. Webview side
+
+```ts
+import { WebviewMessenger } from 'vscode-extension-messaging-framework/webview';
+import type { MySchema } from '../shared/schema';
+
+const messenger = new WebviewMessenger<MySchema>();
+messenger.start();
+
+// Send a request to the extension
+const user = await messenger.request('getUser', { id: '123' });
+console.log(user.name);
+
+// Listen for notifications
+messenger.onNotification('themeChanged', ({ theme }) => {
+  document.body.className = theme;
+});
+```
+
+### Error handling
+
+Errors thrown in handlers are automatically propagated to the caller:
+
+```ts
+import { MessagingError, ErrorCode } from 'vscode-extension-messaging-framework/shared';
+
+// Extension side
+messenger.onRequest('saveDraft', ({ content }) => {
+  if (!content) {
+    throw new MessagingError(ErrorCode.InvalidParams, 'Content cannot be empty');
+  }
+  return { saved: true };
+});
+
+// Webview side
+try {
+  await messenger.request('saveDraft', { content: '' });
+} catch (err) {
+  // err is a MessagingError with code, message, and optional data
+}
+```
+
+Requests that exceed the timeout throw a `MessagingError` with `ErrorCode.Timeout`. You can override the timeout per request:
+
+```ts
+const result = await messenger.request('saveDraft', { content }, { timeout: 10000 });
+```
+
+### Cleanup
+
+Both messengers implement `dispose()` which removes listeners and cancels pending requests:
+
+```ts
+messenger.dispose();
+```
+
+## Demo
+
+The `demo/` directory contains a working VS Code extension that exercises the main features of the library:
+
+- **Request/response** - increment a counter by sending typed requests from the webview to the extension
+- **Bidirectional requests** - the extension requests an input value from the webview
+- **Timeout handling** - a slow operation that succeeds (2s) vs one that exceeds the 5s timeout
+- **Error propagation** - a handler that intentionally throws, demonstrating error serialization across the boundary
+- **Notifications** - real-time counter updates and log messages pushed from the extension to the webview
+
+To run the demo:
+
+```
+cd demo
+npm install
+npm run build
+```
+
+Then press F5 in VS Code to launch the Extension Development Host, and run the **Messaging Demo: Show Panel** command.

package/dist/extension/index.d.ts

@@ -0,0 +1,3 @@
+export { ExtensionMessenger } from './messenger.js';
+export { PendingRequestsManager } from './pending-requests.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/extension/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extension/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/extension/index.js

@@ -0,0 +1,3 @@
+export { ExtensionMessenger } from './messenger.js';
+export { PendingRequestsManager } from './pending-requests.js';
+//# sourceMappingURL=index.js.map

package/dist/extension/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/extension/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/extension/messenger.d.ts

@@ -0,0 +1,72 @@
+import type { Webview, Disposable } from 'vscode';
+import { type MessageSchema, type EmptySchema, type WebviewRequestMethods, type WebviewRequestParams, type WebviewRequestResult, type ExtensionRequestMethods, type ExtensionRequestParams, type ExtensionRequestResult, type WebviewNotificationMethods, type WebviewNotificationParams, type ExtensionNotificationMethods, type ExtensionNotificationParams, type RequestHandler, type NotificationHandler, type RequestOptions } from '../shared/schema.js';
+/**
+ * Messenger for the VS Code extension host side.
+ * Handles communication with a webview via postMessage.
+ */
+export declare class ExtensionMessenger<S extends MessageSchema = EmptySchema> implements Disposable {
+    private readonly webview;
+    private readonly pendingRequests;
+    private readonly requestHandlers;
+    private readonly notificationHandlers;
+    private readonly messageListener;
+    private disposed;
+    constructor(webview: Webview, options?: {
+        defaultTimeout?: number;
+    });
+    /**
+     * Sends a request to the webview and waits for a response.
+     * @param method - The request method name
+     * @param params - The request parameters
+     * @param options - Optional request options (timeout)
+     * @returns A promise that resolves with the response result
+     */
+    request<M extends ExtensionRequestMethods<S>>(method: M, params: ExtensionRequestParams<S, M & string>, options?: RequestOptions): Promise<ExtensionRequestResult<S, M & string>>;
+    /**
+     * Sends a notification to the webview (fire-and-forget).
+     * @param method - The notification method name
+     * @param params - The notification parameters
+     */
+    notify<M extends ExtensionNotificationMethods<S>>(method: M, params: ExtensionNotificationParams<S, M & string>): void;
+    /**
+     * Registers a handler for incoming requests from the webview.
+     * Only one handler can be registered per method.
+     * @param method - The request method to handle
+     * @param handler - The handler function
+     * @returns A disposable to unregister the handler
+     */
+    onRequest<M extends WebviewRequestMethods<S>>(method: M, handler: RequestHandler<WebviewRequestParams<S, M & string>, WebviewRequestResult<S, M & string>>): Disposable;
+    /**
+     * Registers a handler for incoming notifications from the webview.
+     * Multiple handlers can be registered per method.
+     * @param method - The notification method to listen for
+     * @param handler - The handler function
+     * @returns A disposable to unregister the handler
+     */
+    onNotification<M extends WebviewNotificationMethods<S>>(method: M, handler: NotificationHandler<WebviewNotificationParams<S, M & string>>): Disposable;
+    /**
+     * Handles an incoming message from the webview.
+     */
+    private handleMessage;
+    /**
+     * Handles an incoming request from the webview.
+     */
+    private handleRequest;
+    /**
+     * Handles an incoming response to a previous request.
+     */
+    private handleResponse;
+    /**
+     * Handles an incoming notification from the webview.
+     */
+    private handleNotification;
+    /**
+     * Sends a response back to the webview.
+     */
+    private sendResponse;
+    /**
+     * Disposes the messenger, cancelling all pending requests.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=messenger.d.ts.map

package/dist/extension/messenger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messenger.d.ts","sourceRoot":"","sources":["../../src/extension/messenger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAelD,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,4BAA4B,EACjC,KAAK,2BAA2B,EAChC,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EAEpB,MAAM,qBAAqB,CAAC;AAG7B;;;GAGG;AACH,qBAAa,kBAAkB,CAAC,CAAC,SAAS,aAAa,GAAG,WAAW,CAAE,YAAW,UAAU;IAC1F,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IACzD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuD;IACvF,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAwD;IAC7F,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAa;IAC7C,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE;IAUnE;;;;;;OAMG;IACH,OAAO,CAAC,CAAC,SAAS,uBAAuB,CAAC,CAAC,CAAC,EAC1C,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,sBAAsB,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,EAC7C,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,sBAAsB,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC;IAyBjD;;;;OAIG;IACH,MAAM,CAAC,CAAC,SAAS,4BAA4B,CAAC,CAAC,CAAC,EAC9C,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,2BAA2B,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,GACjD,IAAI;IAcP;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,SAAS,qBAAqB,CAAC,CAAC,CAAC,EAC1C,MAAM,EAAE,CAAC,EACT,OAAO,EAAE,cAAc,CAAC,oBAAoB,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,GAChG,UAAU;IAUb;;;;;;OAMG;IACH,cAAc,CAAC,CAAC,SAAS,0BAA0B,CAAC,CAAC,CAAC,EACpD,MAAM,EAAE,CAAC,EACT,OAAO,EAAE,mBAAmB,CAAC,yBAAyB,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,GACrE,UAAU;IAsBb;;OAEG;IACH,OAAO,CAAC,aAAa;IAWrB;;OAEG;YACW,aAAa;IAmB3B;;OAEG;IACH,OAAO,CAAC,cAAc;IAStB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;OAEG;IACH,OAAO,CAAC,YAAY;IAcpB;;OAEG;IACH,OAAO,IAAI,IAAI;CAWhB"}

package/dist/extension/messenger.js

@@ -0,0 +1,191 @@
+import { isRequestMessage, isResponseMessage, isNotificationMessage, } from '../shared/protocol.js';
+import { ErrorCode, MessagingError, serializeError, deserializeError, } from '../shared/errors.js';
+import { DEFAULT_TIMEOUT, } from '../shared/schema.js';
+import { PendingRequestsManager } from './pending-requests.js';
+/**
+ * Messenger for the VS Code extension host side.
+ * Handles communication with a webview via postMessage.
+ */
+export class ExtensionMessenger {
+    webview;
+    pendingRequests;
+    requestHandlers = new Map();
+    notificationHandlers = new Map();
+    messageListener;
+    disposed = false;
+    constructor(webview, options) {
+        this.webview = webview;
+        this.pendingRequests = new PendingRequestsManager(options?.defaultTimeout ?? DEFAULT_TIMEOUT);
+        // Listen for messages from the webview
+        this.messageListener = this.webview.onDidReceiveMessage((message) => {
+            this.handleMessage(message);
+        });
+    }
+    /**
+     * Sends a request to the webview and waits for a response.
+     * @param method - The request method name
+     * @param params - The request parameters
+     * @param options - Optional request options (timeout)
+     * @returns A promise that resolves with the response result
+     */
+    request(method, params, options) {
+        if (this.disposed) {
+            return Promise.reject(new MessagingError(ErrorCode.Cancelled, 'Messenger has been disposed'));
+        }
+        const id = crypto.randomUUID();
+        const message = {
+            type: 'request',
+            id,
+            method: method,
+            params,
+        };
+        const promise = this.pendingRequests.add(id, method, options?.timeout);
+        this.webview.postMessage(message);
+        return promise;
+    }
+    /**
+     * Sends a notification to the webview (fire-and-forget).
+     * @param method - The notification method name
+     * @param params - The notification parameters
+     */
+    notify(method, params) {
+        if (this.disposed) {
+            return;
+        }
+        const message = {
+            type: 'notification',
+            method: method,
+            params,
+        };
+        this.webview.postMessage(message);
+    }
+    /**
+     * Registers a handler for incoming requests from the webview.
+     * Only one handler can be registered per method.
+     * @param method - The request method to handle
+     * @param handler - The handler function
+     * @returns A disposable to unregister the handler
+     */
+    onRequest(method, handler) {
+        this.requestHandlers.set(method, handler);
+        return {
+            dispose: () => {
+                this.requestHandlers.delete(method);
+            },
+        };
+    }
+    /**
+     * Registers a handler for incoming notifications from the webview.
+     * Multiple handlers can be registered per method.
+     * @param method - The notification method to listen for
+     * @param handler - The handler function
+     * @returns A disposable to unregister the handler
+     */
+    onNotification(method, handler) {
+        let handlers = this.notificationHandlers.get(method);
+        if (!handlers) {
+            handlers = new Set();
+            this.notificationHandlers.set(method, handlers);
+        }
+        handlers.add(handler);
+        return {
+            dispose: () => {
+                const h = this.notificationHandlers.get(method);
+                if (h) {
+                    h.delete(handler);
+                    if (h.size === 0) {
+                        this.notificationHandlers.delete(method);
+                    }
+                }
+            },
+        };
+    }
+    /**
+     * Handles an incoming message from the webview.
+     */
+    handleMessage(message) {
+        if (isRequestMessage(message)) {
+            this.handleRequest(message);
+        }
+        else if (isResponseMessage(message)) {
+            this.handleResponse(message);
+        }
+        else if (isNotificationMessage(message)) {
+            this.handleNotification(message);
+        }
+        // Ignore unknown message types
+    }
+    /**
+     * Handles an incoming request from the webview.
+     */
+    async handleRequest(message) {
+        const handler = this.requestHandlers.get(message.method);
+        if (!handler) {
+            this.sendResponse(message.id, undefined, {
+                code: ErrorCode.MethodNotFound,
+                message: `No handler registered for method '${message.method}'`,
+            });
+            return;
+        }
+        try {
+            const result = await handler(message.params);
+            this.sendResponse(message.id, result);
+        }
+        catch (error) {
+            this.sendResponse(message.id, undefined, serializeError(error));
+        }
+    }
+    /**
+     * Handles an incoming response to a previous request.
+     */
+    handleResponse(message) {
+        if (message.error) {
+            const error = deserializeError(message.error);
+            this.pendingRequests.reject(message.id, error);
+        }
+        else {
+            this.pendingRequests.resolve(message.id, message.result);
+        }
+    }
+    /**
+     * Handles an incoming notification from the webview.
+     */
+    handleNotification(message) {
+        const handlers = this.notificationHandlers.get(message.method);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(message.params);
+                }
+                catch {
+                    // Notification handlers should not throw, but we silently ignore if they do
+                }
+            }
+        }
+    }
+    /**
+     * Sends a response back to the webview.
+     */
+    sendResponse(id, result, error) {
+        const response = {
+            type: 'response',
+            id,
+            ...(error ? { error } : { result }),
+        };
+        this.webview.postMessage(response);
+    }
+    /**
+     * Disposes the messenger, cancelling all pending requests.
+     */
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        this.messageListener.dispose();
+        this.pendingRequests.cancelAll('Messenger disposed');
+        this.requestHandlers.clear();
+        this.notificationHandlers.clear();
+    }
+}
+//# sourceMappingURL=messenger.js.map

package/dist/extension/messenger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messenger.js","sourceRoot":"","sources":["../../src/extension/messenger.ts"],"names":[],"mappings":"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"}

package/dist/extension/pending-requests.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Manages pending requests with timeout handling.
+ */
+export declare class PendingRequestsManager {
+    private readonly pending;
+    private readonly defaultTimeout;
+    constructor(defaultTimeout: number);
+    /**
+     * Adds a new pending request.
+     * @param id - Unique request ID
+     * @param method - The method name for error messages
+     * @param timeout - Timeout in milliseconds (optional, uses default if not specified)
+     * @returns A promise that resolves with the result or rejects on timeout/error
+     */
+    add<T>(id: string, method: string, timeout?: number): Promise<T>;
+    /**
+     * Resolves a pending request with a result.
+     * @param id - The request ID
+     * @param result - The result value
+     * @returns true if the request was found and resolved, false otherwise
+     */
+    resolve(id: string, result: unknown): boolean;
+    /**
+     * Rejects a pending request with an error.
+     * @param id - The request ID
+     * @param error - The error to reject with
+     * @returns true if the request was found and rejected, false otherwise
+     */
+    reject(id: string, error: Error): boolean;
+    /**
+     * Cancels all pending requests with a cancellation error.
+     * @param reason - Optional reason for cancellation
+     */
+    cancelAll(reason?: string): void;
+    /**
+     * Returns the number of pending requests.
+     */
+    get size(): number;
+    /**
+     * Checks if a request ID is pending.
+     */
+    has(id: string): boolean;
+}
+//# sourceMappingURL=pending-requests.d.ts.map

package/dist/extension/pending-requests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-requests.d.ts","sourceRoot":"","sources":["../../src/extension/pending-requests.ts"],"names":[],"mappings":"AAYA;;GAEG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,cAAc,EAAE,MAAM;IAIlC;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAuBhE;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO;IAY7C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO;IAYzC;;;OAGG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAchC;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAGzB"}

package/dist/extension/pending-requests.js

@@ -0,0 +1,90 @@
+import { ErrorCode, MessagingError } from '../shared/errors.js';
+/**
+ * Manages pending requests with timeout handling.
+ */
+export class PendingRequestsManager {
+    pending = new Map();
+    defaultTimeout;
+    constructor(defaultTimeout) {
+        this.defaultTimeout = defaultTimeout;
+    }
+    /**
+     * Adds a new pending request.
+     * @param id - Unique request ID
+     * @param method - The method name for error messages
+     * @param timeout - Timeout in milliseconds (optional, uses default if not specified)
+     * @returns A promise that resolves with the result or rejects on timeout/error
+     */
+    add(id, method, timeout) {
+        return new Promise((resolve, reject) => {
+            const timeoutMs = timeout ?? this.defaultTimeout;
+            const timeoutId = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new MessagingError(ErrorCode.Timeout, `Request '${method}' timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: resolve,
+                reject,
+                timeoutId,
+                method,
+            });
+        });
+    }
+    /**
+     * Resolves a pending request with a result.
+     * @param id - The request ID
+     * @param result - The result value
+     * @returns true if the request was found and resolved, false otherwise
+     */
+    resolve(id, result) {
+        const pending = this.pending.get(id);
+        if (!pending) {
+            return false;
+        }
+        clearTimeout(pending.timeoutId);
+        this.pending.delete(id);
+        pending.resolve(result);
+        return true;
+    }
+    /**
+     * Rejects a pending request with an error.
+     * @param id - The request ID
+     * @param error - The error to reject with
+     * @returns true if the request was found and rejected, false otherwise
+     */
+    reject(id, error) {
+        const pending = this.pending.get(id);
+        if (!pending) {
+            return false;
+        }
+        clearTimeout(pending.timeoutId);
+        this.pending.delete(id);
+        pending.reject(error);
+        return true;
+    }
+    /**
+     * Cancels all pending requests with a cancellation error.
+     * @param reason - Optional reason for cancellation
+     */
+    cancelAll(reason) {
+        const error = new MessagingError(ErrorCode.Cancelled, reason ?? 'All pending requests cancelled');
+        for (const [id, pending] of this.pending) {
+            clearTimeout(pending.timeoutId);
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+    /**
+     * Returns the number of pending requests.
+     */
+    get size() {
+        return this.pending.size;
+    }
+    /**
+     * Checks if a request ID is pending.
+     */
+    has(id) {
+        return this.pending.has(id);
+    }
+}
+//# sourceMappingURL=pending-requests.js.map

package/dist/extension/pending-requests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-requests.js","sourceRoot":"","sources":["../../src/extension/pending-requests.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAYhE;;GAEG;AACH,MAAM,OAAO,sBAAsB;IAChB,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC5C,cAAc,CAAS;IAExC,YAAY,cAAsB;QAChC,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,CAAC;IAED;;;;;;OAMG;IACH,GAAG,CAAI,EAAU,EAAE,MAAc,EAAE,OAAgB;QACjD,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,MAAM,SAAS,GAAG,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC;YAEjD,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;gBAChC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACxB,MAAM,CACJ,IAAI,cAAc,CAChB,SAAS,CAAC,OAAO,EACjB,YAAY,MAAM,qBAAqB,SAAS,IAAI,CACrD,CACF,CAAC;YACJ,CAAC,EAAE,SAAS,CAAC,CAAC;YAEd,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE;gBACnB,OAAO,EAAE,OAAmC;gBAC5C,MAAM;gBACN,SAAS;gBACT,MAAM;aACP,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,EAAU,EAAE,MAAe;QACjC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,KAAK,CAAC;QACf,CAAC;QAED,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACxB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,EAAU,EAAE,KAAY;QAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,KAAK,CAAC;QACf,CAAC;QAED,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,MAAe;QACvB,MAAM,KAAK,GAAG,IAAI,cAAc,CAC9B,SAAS,CAAC,SAAS,EACnB,MAAM,IAAI,gCAAgC,CAC3C,CAAC;QAEF,KAAK,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACzC,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;CACF"}

package/dist/shared/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Standard error codes for messaging errors.
+ */
+export declare enum ErrorCode {
+    /** The request timed out waiting for a response */
+    Timeout = "TIMEOUT",
+    /** No handler registered for the requested method */
+    MethodNotFound = "METHOD_NOT_FOUND",
+    /** The handler threw an error */
+    HandlerError = "HANDLER_ERROR",
+    /** The request was cancelled */
+    Cancelled = "CANCELLED",
+    /** Invalid request parameters */
+    InvalidParams = "INVALID_PARAMS",
+    /** Internal error */
+    InternalError = "INTERNAL_ERROR"
+}
+/**
+ * Serialized error format for transmission over postMessage.
+ */
+export interface SerializedError {
+    code: string;
+    message: string;
+    data?: unknown;
+    stack?: string;
+}
+/**
+ * Error class for messaging errors with error codes.
+ */
+export declare class MessagingError extends Error {
+    readonly code: string;
+    readonly data?: unknown;
+    constructor(code: string, message: string, data?: unknown);
+    /**
+     * Creates a MessagingError from a SerializedError.
+     */
+    static fromSerialized(serialized: SerializedError): MessagingError;
+    /**
+     * Serializes this error for transmission.
+     */
+    toSerialized(): SerializedError;
+}
+/**
+ * Serializes an error for transmission over postMessage.
+ * Handles MessagingError specially, converting other errors to HANDLER_ERROR.
+ */
+export declare function serializeError(error: unknown): SerializedError;
+/**
+ * Deserializes an error from transmission.
+ */
+export declare function deserializeError(serialized: SerializedError): MessagingError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/shared/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,SAAS;IACnB,mDAAmD;IACnD,OAAO,YAAY;IACnB,qDAAqD;IACrD,cAAc,qBAAqB;IACnC,iCAAiC;IACjC,YAAY,kBAAkB;IAC9B,gCAAgC;IAChC,SAAS,cAAc;IACvB,iCAAiC;IACjC,aAAa,mBAAmB;IAChC,qBAAqB;IACrB,aAAa,mBAAmB;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,IAAI,CAAC,EAAE,OAAO,CAAC;gBAEnB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAYzD;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,eAAe,GAAG,cAAc;IAQlE;;OAEG;IACH,YAAY,IAAI,eAAe;CAGhC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAuB9D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,eAAe,GAAG,cAAc,CAE5E"}