@dynamic-labs/message-transport 2.0.0-alpha.26

package/src/requestChannel/requestChannel.cjs

@@ -0,0 +1,112 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _tslib = require('../../_virtual/_tslib.cjs');
+
+/** Given a request event name, returns the event name for its resolve */
+const getResolveMessageType = (type) => `${type}__resolve`;
+/** Given a request event name, returns the event name for its reject */
+const getRejectMessageType = (type) => `${type}__reject`;
+/**
+ * Allows handling and submitting requests to and from a webview.
+ * Requests are messages that (can) expect some response.
+ *
+ * Functions similarly to an event emitter, but adds a response feature:
+ * - Emitting an event type is the act of making a "request" of a specific type,
+ * and it returns a promise that will resolve to the request's response.
+ * - Listening to an event type is the act of "handling" requests of a specific type.
+ * This handler callback must return a promise if this request type expects responses.
+ *
+ * Think of it this way:
+ * Whenever I emit an event, I am submitting a request.
+ * Whoever listens to the event will handle my request.
+ * If the request type expects some kind of response, they will
+ * return a promise that resolves (or rejects) after my request is fulfilled.
+ *
+ * This is an abstraction built on top of the MessageTransport interface.
+ */
+const createRequestChannel = (messageTransport) => {
+    /** Used to generated unique ids */
+    let uniqueIdCounter = 0;
+    /** Id prefix unique to this channel */
+    const idPrefix = Math.random().toString();
+    /** Always returns a different string */
+    const getUniqueId = () => `${idPrefix}-${uniqueIdCounter++}`;
+    return {
+        emit: (requestName, ...params) => {
+            // Generate the unique id for this message exchange session
+            // Although we won't listen for a response, it must still be unique
+            // to avoid tangling with other requests.
+            const messageSessionId = getUniqueId();
+            messageTransport.emit({
+                args: params,
+                messageSessionId,
+                type: requestName,
+            });
+        },
+        handle: (requestType, handler) => {
+            const messageHandler = ({ args, messageSessionId, type: incomingType, }) => _tslib.__awaiter(void 0, void 0, void 0, function* () {
+                if (requestType !== incomingType)
+                    return;
+                const result = handler(...args);
+                // If the handler doesn't return a promise,
+                // that means we don't need to respond.
+                if (!(result instanceof Promise))
+                    return;
+                try {
+                    const response = yield result;
+                    messageTransport.emit({
+                        args: [response],
+                        messageSessionId,
+                        type: getResolveMessageType(requestType),
+                    });
+                }
+                catch (error) {
+                    messageTransport.emit({
+                        args: [error],
+                        messageSessionId,
+                        type: getRejectMessageType(requestType),
+                    });
+                }
+            });
+            messageTransport.on(messageHandler);
+            return () => {
+                messageTransport.off(messageHandler);
+            };
+        },
+        request: (requestName, ...params) => new Promise((resolve, reject) => {
+            const requestType = requestName;
+            // Generate the unique id for this message exchange session
+            const messageSessionId = getUniqueId();
+            const resolveMessageType = getResolveMessageType(requestType);
+            const rejectMessageType = getRejectMessageType(requestType);
+            // Before actually emitting the event, we start listening to the
+            // response events
+            const handleMessage = ({ args: [result], messageSessionId: incomingSessionId, type: incomingType, }) => {
+                if (incomingSessionId !== messageSessionId)
+                    return;
+                if (incomingType === resolveMessageType) {
+                    resolve(result);
+                    cleanup();
+                }
+                if (incomingType === rejectMessageType) {
+                    reject(result);
+                    cleanup();
+                }
+            };
+            const cleanup = () => messageTransport.off(handleMessage);
+            messageTransport.on(handleMessage);
+            // Now we emit the event to set off the request
+            messageTransport.emit({
+                args: params,
+                messageSessionId,
+                type: requestType,
+            });
+        }),
+    };
+};
+
+exports.createRequestChannel = createRequestChannel;
+exports.getRejectMessageType = getRejectMessageType;
+exports.getResolveMessageType = getResolveMessageType;

package/src/requestChannel/requestChannel.d.ts

@@ -0,0 +1,55 @@
+import { MessageTransportWithDefaultOrigin } from '../messageTransport/decorators/applyDefaultMessageOrigin/applyDefaultMessageOrigin';
+/**
+ * An object that defines request types, and whether they expect a response
+ */
+export type RequestTypes = Record<string, (...params: any[]) => Promise<any> | void>;
+/**
+ * Only the request types from T that return promises
+ * i.e. those that expect a response
+ */
+type TypesExpectingResponse<T extends RequestTypes> = {
+    [K in keyof T]: ReturnType<T[K]> extends Promise<any> ? K : never;
+}[keyof T];
+export type RequestChannel<T extends RequestTypes> = {
+    /**
+     * Listens to incoming requests of this type, and calls the handler when they arrive.
+     * If the type of this request expects some response, the handler must return a promise
+     * that resolves to this response.
+     * @returns an unsubscribe function.
+     */
+    handle: <K extends keyof T>(requestType: K, handler: T[K]) => VoidFunction;
+    /**
+     * Triggers handlers for this request type, with the given params.
+     * Doesn't care whether this request will have a response or not, so returns void.
+     */
+    emit: <K extends keyof T>(requestName: K, ...params: Parameters<T[K]>) => void;
+    /**
+     * Triggers handlers for this request type, with the given params.
+     * @returns a promise that resolves/rejects when a handler fulfills this request.
+     */
+    request: <K extends TypesExpectingResponse<T>>(requestName: K, ...params: Parameters<T[K]>) => ReturnType<T[K]>;
+};
+/** Given a request event name, returns the event name for its resolve */
+export declare const getResolveMessageType: (type: string) => string;
+/** Given a request event name, returns the event name for its reject */
+export declare const getRejectMessageType: (type: string) => string;
+/**
+ * Allows handling and submitting requests to and from a webview.
+ * Requests are messages that (can) expect some response.
+ *
+ * Functions similarly to an event emitter, but adds a response feature:
+ * - Emitting an event type is the act of making a "request" of a specific type,
+ * and it returns a promise that will resolve to the request's response.
+ * - Listening to an event type is the act of "handling" requests of a specific type.
+ * This handler callback must return a promise if this request type expects responses.
+ *
+ * Think of it this way:
+ * Whenever I emit an event, I am submitting a request.
+ * Whoever listens to the event will handle my request.
+ * If the request type expects some kind of response, they will
+ * return a promise that resolves (or rejects) after my request is fulfilled.
+ *
+ * This is an abstraction built on top of the MessageTransport interface.
+ */
+export declare const createRequestChannel: <T extends RequestTypes = never>(messageTransport: MessageTransportWithDefaultOrigin) => RequestChannel<T>;
+export {};

package/src/requestChannel/requestChannel.js

@@ -0,0 +1,106 @@
+import { __awaiter } from '../../_virtual/_tslib.js';
+
+/** Given a request event name, returns the event name for its resolve */
+const getResolveMessageType = (type) => `${type}__resolve`;
+/** Given a request event name, returns the event name for its reject */
+const getRejectMessageType = (type) => `${type}__reject`;
+/**
+ * Allows handling and submitting requests to and from a webview.
+ * Requests are messages that (can) expect some response.
+ *
+ * Functions similarly to an event emitter, but adds a response feature:
+ * - Emitting an event type is the act of making a "request" of a specific type,
+ * and it returns a promise that will resolve to the request's response.
+ * - Listening to an event type is the act of "handling" requests of a specific type.
+ * This handler callback must return a promise if this request type expects responses.
+ *
+ * Think of it this way:
+ * Whenever I emit an event, I am submitting a request.
+ * Whoever listens to the event will handle my request.
+ * If the request type expects some kind of response, they will
+ * return a promise that resolves (or rejects) after my request is fulfilled.
+ *
+ * This is an abstraction built on top of the MessageTransport interface.
+ */
+const createRequestChannel = (messageTransport) => {
+    /** Used to generated unique ids */
+    let uniqueIdCounter = 0;
+    /** Id prefix unique to this channel */
+    const idPrefix = Math.random().toString();
+    /** Always returns a different string */
+    const getUniqueId = () => `${idPrefix}-${uniqueIdCounter++}`;
+    return {
+        emit: (requestName, ...params) => {
+            // Generate the unique id for this message exchange session
+            // Although we won't listen for a response, it must still be unique
+            // to avoid tangling with other requests.
+            const messageSessionId = getUniqueId();
+            messageTransport.emit({
+                args: params,
+                messageSessionId,
+                type: requestName,
+            });
+        },
+        handle: (requestType, handler) => {
+            const messageHandler = ({ args, messageSessionId, type: incomingType, }) => __awaiter(void 0, void 0, void 0, function* () {
+                if (requestType !== incomingType)
+                    return;
+                const result = handler(...args);
+                // If the handler doesn't return a promise,
+                // that means we don't need to respond.
+                if (!(result instanceof Promise))
+                    return;
+                try {
+                    const response = yield result;
+                    messageTransport.emit({
+                        args: [response],
+                        messageSessionId,
+                        type: getResolveMessageType(requestType),
+                    });
+                }
+                catch (error) {
+                    messageTransport.emit({
+                        args: [error],
+                        messageSessionId,
+                        type: getRejectMessageType(requestType),
+                    });
+                }
+            });
+            messageTransport.on(messageHandler);
+            return () => {
+                messageTransport.off(messageHandler);
+            };
+        },
+        request: (requestName, ...params) => new Promise((resolve, reject) => {
+            const requestType = requestName;
+            // Generate the unique id for this message exchange session
+            const messageSessionId = getUniqueId();
+            const resolveMessageType = getResolveMessageType(requestType);
+            const rejectMessageType = getRejectMessageType(requestType);
+            // Before actually emitting the event, we start listening to the
+            // response events
+            const handleMessage = ({ args: [result], messageSessionId: incomingSessionId, type: incomingType, }) => {
+                if (incomingSessionId !== messageSessionId)
+                    return;
+                if (incomingType === resolveMessageType) {
+                    resolve(result);
+                    cleanup();
+                }
+                if (incomingType === rejectMessageType) {
+                    reject(result);
+                    cleanup();
+                }
+            };
+            const cleanup = () => messageTransport.off(handleMessage);
+            messageTransport.on(handleMessage);
+            // Now we emit the event to set off the request
+            messageTransport.emit({
+                args: params,
+                messageSessionId,
+                type: requestType,
+            });
+        }),
+    };
+};
+
+export { createRequestChannel, getRejectMessageType, getResolveMessageType };

package/src/utils/parseMessageTransportData/index.d.ts

@@ -0,0 +1 @@
+export * from './parseMessageTransportData';

package/src/utils/parseMessageTransportData/parseMessageTransportData.cjs

@@ -0,0 +1,26 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const parseMessageTransportData = (
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+parsedData) => {
+    if (!parsedData || typeof parsedData !== 'object') {
+        return undefined;
+    }
+    const message = {
+        args: parsedData.args,
+        messageSessionId: parsedData.messageSessionId,
+        origin: parsedData.origin,
+        type: parsedData.type,
+    };
+    if (!Array.isArray(message.args) ||
+        typeof message.messageSessionId !== 'string' ||
+        typeof message.origin !== 'string' ||
+        typeof message.type !== 'string') {
+        return undefined;
+    }
+    return message;
+};
+
+exports.parseMessageTransportData = parseMessageTransportData;

package/src/utils/parseMessageTransportData/parseMessageTransportData.d.ts

@@ -0,0 +1,2 @@
+import { MessageTransportData } from '../../messageTransport';
+export declare const parseMessageTransportData: (parsedData: any) => MessageTransportData | undefined;

package/src/utils/parseMessageTransportData/parseMessageTransportData.js

@@ -0,0 +1,22 @@
+const parseMessageTransportData = (
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+parsedData) => {
+    if (!parsedData || typeof parsedData !== 'object') {
+        return undefined;
+    }
+    const message = {
+        args: parsedData.args,
+        messageSessionId: parsedData.messageSessionId,
+        origin: parsedData.origin,
+        type: parsedData.type,
+    };
+    if (!Array.isArray(message.args) ||
+        typeof message.messageSessionId !== 'string' ||
+        typeof message.origin !== 'string' ||
+        typeof message.type !== 'string') {
+        return undefined;
+    }
+    return message;
+};
+
+export { parseMessageTransportData };