penpal 7.0.3 → 7.0.4

package/cjs/messengers/PortMessenger.js

@@ -1,47 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const PenpalError_js_1 = require("../PenpalError.js");
-/**
- * Handles the details of communicating on a MessagePort.
- */
-class PortMessenger {
-    #port;
-    #validateReceivedMessage;
-    #messageCallbacks = new Set();
-    constructor({ port }) {
-        if (!port) {
-            throw new PenpalError_js_1.default('INVALID_ARGUMENT', 'port must be defined');
-        }
-        this.#port = port;
-    }
-    initialize = ({ validateReceivedMessage }) => {
-        this.#validateReceivedMessage = validateReceivedMessage;
-        this.#port.addEventListener('message', this.#handleMessage);
-        this.#port.start();
-    };
-    sendMessage = (message, transferables) => {
-        this.#port?.postMessage(message, {
-            transfer: transferables,
-        });
-    };
-    addMessageHandler = (callback) => {
-        this.#messageCallbacks.add(callback);
-    };
-    removeMessageHandler = (callback) => {
-        this.#messageCallbacks.delete(callback);
-    };
-    destroy = () => {
-        this.#port.removeEventListener('message', this.#handleMessage);
-        this.#port.close();
-        this.#messageCallbacks.clear();
-    };
-    #handleMessage = ({ data }) => {
-        if (!this.#validateReceivedMessage?.(data)) {
-            return;
-        }
-        for (const callback of this.#messageCallbacks) {
-            callback(data);
-        }
-    };
-}
-exports.default = PortMessenger;

package/cjs/messengers/WindowMessenger.d.ts

@@ -1,29 +0,0 @@
-import { Message } from '../types.js';
-import Messenger, { InitializeMessengerOptions, MessageHandler } from './Messenger.js';
-type Options = {
-    /**
-     * The window with which the current window will communicate.
-     */
-    remoteWindow: Window;
-    /**
-     * An array of strings or regular expressions defining to which origins
-     * communication will be allowed. If not provided, communication will be
-     * restricted to the origin of the current page. You may specify an allowed
-     * origin of `*` to not restrict communication, but beware the risks of
-     * doing so.
-     */
-    allowedOrigins?: (string | RegExp)[];
-};
-/**
- * Handles the details of communicating with a child window.
- */
-declare class WindowMessenger implements Messenger {
-    #private;
-    constructor({ remoteWindow, allowedOrigins }: Options);
-    initialize: ({ log, validateReceivedMessage, }: InitializeMessengerOptions) => void;
-    sendMessage: (message: Message, transferables?: Transferable[]) => void;
-    addMessageHandler: (callback: MessageHandler) => void;
-    removeMessageHandler: (callback: MessageHandler) => void;
-    destroy: () => void;
-}
-export default WindowMessenger;

package/cjs/messengers/WindowMessenger.js

@@ -1,178 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const backwardCompatibility_js_1 = require("../backwardCompatibility.js");
-const guards_js_1 = require("../guards.js");
-const PenpalError_js_1 = require("../PenpalError.js");
-const PenpalBugError_js_1 = require("../PenpalBugError.js");
-/**
- * Handles the details of communicating with a child window.
- */
-class WindowMessenger {
-    #remoteWindow;
-    #allowedOrigins;
-    #log;
-    #validateReceivedMessage;
-    #concreteRemoteOrigin;
-    #messageCallbacks = new Set();
-    #port;
-    // TODO: Used for backward-compatibility. Remove in next major version.
-    #isChildUsingDeprecatedProtocol = false;
-    constructor({ remoteWindow, allowedOrigins }) {
-        if (!remoteWindow) {
-            throw new PenpalError_js_1.default('INVALID_ARGUMENT', 'remoteWindow must be defined');
-        }
-        this.#remoteWindow = remoteWindow;
-        this.#allowedOrigins = allowedOrigins?.length
-            ? allowedOrigins
-            : [window.origin];
-    }
-    initialize = ({ log, validateReceivedMessage, }) => {
-        this.#log = log;
-        this.#validateReceivedMessage = validateReceivedMessage;
-        window.addEventListener('message', this.#handleMessageFromRemoteWindow);
-    };
-    sendMessage = (message, transferables) => {
-        if ((0, guards_js_1.isSynMessage)(message)) {
-            const originForSending = this.#getOriginForSendingMessage(message);
-            this.#remoteWindow.postMessage(message, {
-                targetOrigin: originForSending,
-                transfer: transferables,
-            });
-            return;
-        }
-        if ((0, guards_js_1.isAck1Message)(message) ||
-            // If the child is using a previous version of Penpal, we need to
-            // downgrade the message and send it through the window rather than
-            // the port because older versions of Penpal don't use MessagePorts.
-            this.#isChildUsingDeprecatedProtocol) {
-            const payload = this.#isChildUsingDeprecatedProtocol
-                ? (0, backwardCompatibility_js_1.downgradeMessage)(message)
-                : message;
-            const originForSending = this.#getOriginForSendingMessage(message);
-            this.#remoteWindow.postMessage(payload, {
-                targetOrigin: originForSending,
-                transfer: transferables,
-            });
-            return;
-        }
-        if ((0, guards_js_1.isAck2Message)(message)) {
-            const { port1, port2 } = new MessageChannel();
-            this.#port = port1;
-            port1.addEventListener('message', this.#handleMessageFromPort);
-            port1.start();
-            const transferablesToSend = [port2, ...(transferables || [])];
-            const originForSending = this.#getOriginForSendingMessage(message);
-            this.#remoteWindow.postMessage(message, {
-                targetOrigin: originForSending,
-                transfer: transferablesToSend,
-            });
-            return;
-        }
-        if (this.#port) {
-            this.#port.postMessage(message, {
-                transfer: transferables,
-            });
-            return;
-        }
-        throw new PenpalBugError_js_1.default('Port is undefined');
-    };
-    addMessageHandler = (callback) => {
-        this.#messageCallbacks.add(callback);
-    };
-    removeMessageHandler = (callback) => {
-        this.#messageCallbacks.delete(callback);
-    };
-    destroy = () => {
-        window.removeEventListener('message', this.#handleMessageFromRemoteWindow);
-        this.#destroyPort();
-        this.#messageCallbacks.clear();
-    };
-    #isAllowedOrigin = (origin) => {
-        return this.#allowedOrigins.some((allowedOrigin) => allowedOrigin instanceof RegExp
-            ? allowedOrigin.test(origin)
-            : allowedOrigin === origin || allowedOrigin === '*');
-    };
-    #getOriginForSendingMessage = (message) => {
-        // It's safe to send the SYN message to any origin because it doesn't contain
-        // anything sensitive. When Penpal receives a SYN message, the origin on
-        // the message (which we call the concrete origin) is validated against the
-        // configured allowed origins. All subsequent messages will be sent to the
-        // concrete origin.
-        // If you decide to change this, consider https://github.com/Aaronius/penpal/issues/103
-        if ((0, guards_js_1.isSynMessage)(message)) {
-            return '*';
-        }
-        if (!this.#concreteRemoteOrigin) {
-            throw new PenpalBugError_js_1.default('Concrete remote origin not set');
-        }
-        // If the concrete remote origin (the origin we received from the remote
-        // on a prior message) is 'null', it means the remote is within
-        // an "opaque origin". The only way to post a message to an
-        // opaque origin is by using '*'. This does carry some security risk,
-        // so we only do this if the consumer has specifically defined '*' as
-        // an allowed origin. Opaque origins occur, for example, when
-        // loading an HTML document directly from the filesystem (not a
-        // web server) or through a data URI.
-        return this.#concreteRemoteOrigin === 'null' &&
-            this.#allowedOrigins.includes('*')
-            ? '*'
-            : this.#concreteRemoteOrigin;
-    };
-    #destroyPort = () => {
-        this.#port?.removeEventListener('message', this.#handleMessageFromPort);
-        this.#port?.close();
-        this.#port = undefined;
-    };
-    #handleMessageFromRemoteWindow = ({ source, origin, ports, data, }) => {
-        if (source !== this.#remoteWindow) {
-            return;
-        }
-        // TODO: Used for backward-compatibility. Remove in next major version.
-        if ((0, backwardCompatibility_js_1.isDeprecatedMessage)(data)) {
-            this.#log?.('Please upgrade the child window to the latest version of Penpal.');
-            this.#isChildUsingDeprecatedProtocol = true;
-            data = (0, backwardCompatibility_js_1.upgradeMessage)(data);
-        }
-        if (!this.#validateReceivedMessage?.(data)) {
-            return;
-        }
-        if (!this.#isAllowedOrigin(origin)) {
-            this.#log?.(`Received a message from origin \`${origin}\` which did not match ` +
-                `allowed origins \`[${this.#allowedOrigins.join(', ')}]\``);
-            return;
-        }
-        if ((0, guards_js_1.isSynMessage)(data)) {
-            // If we receive a SYN message and already have a port, it means
-            // the child is re-connecting, in which case we'll receive a new port.
-            // For this reason, we always make sure we destroy the existing port.
-            this.#destroyPort();
-            this.#concreteRemoteOrigin = origin;
-        }
-        if ((0, guards_js_1.isAck2Message)(data) &&
-            // Previous versions of Penpal don't use MessagePorts and do all
-            // communication through the window.
-            !this.#isChildUsingDeprecatedProtocol) {
-            this.#port = ports[0];
-            if (!this.#port) {
-                throw new PenpalBugError_js_1.default('No port received on ACK2');
-            }
-            this.#port.addEventListener('message', this.#handleMessageFromPort);
-            this.#port.start();
-        }
-        for (const callback of this.#messageCallbacks) {
-            callback(data);
-        }
-    };
-    #handleMessageFromPort = ({ data }) => {
-        // Unlike in _handleMessageFromWindow, we don't need to check if
-        // the message is from a deprecated version of Penpal because older versions
-        // of Penpal don't use MessagePorts.
-        if (!this.#validateReceivedMessage?.(data)) {
-            return;
-        }
-        for (const callback of this.#messageCallbacks) {
-            callback(data);
-        }
-    };
-}
-exports.default = WindowMessenger;

package/cjs/messengers/WorkerMessenger.d.ts

@@ -1,23 +0,0 @@
-import { Message } from '../types.js';
-import Messenger, { InitializeMessengerOptions, MessageHandler } from './Messenger.js';
-type Options = {
-    /**
-     * The web worker receiving/sending communication from/to the parent window.
-     * If this messenger is being used within the worker, `worker` should
-     * typically be set to `self`.
-     */
-    worker: Worker | DedicatedWorkerGlobalScope;
-};
-/**
- * Handles the details of communicating with a child web worker.
- */
-declare class WorkerMessenger implements Messenger {
-    #private;
-    constructor({ worker }: Options);
-    initialize: ({ validateReceivedMessage }: InitializeMessengerOptions) => void;
-    sendMessage: (message: Message, transferables?: Transferable[]) => void;
-    addMessageHandler: (callback: MessageHandler) => void;
-    removeMessageHandler: (callback: MessageHandler) => void;
-    destroy: () => void;
-}
-export default WorkerMessenger;

package/cjs/messengers/WorkerMessenger.js

@@ -1,86 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const guards_js_1 = require("../guards.js");
-const PenpalError_js_1 = require("../PenpalError.js");
-const PenpalBugError_js_1 = require("../PenpalBugError.js");
-/**
- * Handles the details of communicating with a child web worker.
- */
-class WorkerMessenger {
-    #worker;
-    #validateReceivedMessage;
-    #messageCallbacks = new Set();
-    #port;
-    constructor({ worker }) {
-        if (!worker) {
-            throw new PenpalError_js_1.default('INVALID_ARGUMENT', 'worker must be defined');
-        }
-        this.#worker = worker;
-    }
-    initialize = ({ validateReceivedMessage }) => {
-        this.#validateReceivedMessage = validateReceivedMessage;
-        this.#worker.addEventListener('message', this.#handleMessage);
-    };
-    sendMessage = (message, transferables) => {
-        if ((0, guards_js_1.isSynMessage)(message) || (0, guards_js_1.isAck1Message)(message)) {
-            this.#worker.postMessage(message, { transfer: transferables });
-            return;
-        }
-        if ((0, guards_js_1.isAck2Message)(message)) {
-            const { port1, port2 } = new MessageChannel();
-            this.#port = port1;
-            port1.addEventListener('message', this.#handleMessage);
-            port1.start();
-            this.#worker.postMessage(message, {
-                transfer: [port2, ...(transferables || [])],
-            });
-            return;
-        }
-        if (this.#port) {
-            this.#port.postMessage(message, {
-                transfer: transferables,
-            });
-            return;
-        }
-        throw new PenpalBugError_js_1.default('Port is undefined');
-    };
-    addMessageHandler = (callback) => {
-        this.#messageCallbacks.add(callback);
-    };
-    removeMessageHandler = (callback) => {
-        this.#messageCallbacks.delete(callback);
-    };
-    destroy = () => {
-        this.#worker.removeEventListener('message', this.#handleMessage);
-        this.#destroyPort();
-        this.#messageCallbacks.clear();
-    };
-    #destroyPort = () => {
-        this.#port?.removeEventListener('message', this.#handleMessage);
-        this.#port?.close();
-        this.#port = undefined;
-    };
-    #handleMessage = ({ ports, data }) => {
-        if (!this.#validateReceivedMessage?.(data)) {
-            return;
-        }
-        if ((0, guards_js_1.isSynMessage)(data)) {
-            // If we receive a SYN message and already have a port, it means
-            // the child is re-connecting, in which case we'll receive a new port.
-            // For this reason, we always make sure we destroy the existing port.
-            this.#destroyPort();
-        }
-        if ((0, guards_js_1.isAck2Message)(data)) {
-            this.#port = ports[0];
-            if (!this.#port) {
-                throw new PenpalBugError_js_1.default('No port received on ACK2');
-            }
-            this.#port.addEventListener('message', this.#handleMessage);
-            this.#port.start();
-        }
-        for (const callback of this.#messageCallbacks) {
-            callback(data);
-        }
-    };
-}
-exports.default = WorkerMessenger;

package/cjs/methodSerialization.d.ts

@@ -1,22 +0,0 @@
-import { MethodPath, Methods } from './types.js';
-/**
- * Given an object of (nested) keys to functions, extract paths to each function.
- *
- * @example
- * Given this Method object:
- * {
- *   one: {
- *     two: () => {}
- *   }
- *   three: () => {}
- * }
- *
- * the extracted MethodPath[] would be:
- * [
- *   ['one', 'two'],
- *   ['three']
- * ]
- */
-export declare const extractMethodPathsFromMethods: (methods: Methods, currentPath?: MethodPath) => MethodPath[];
-export declare const getMethodAtMethodPath: (methodPath: MethodPath, methods: Methods) => Function | undefined;
-export declare const formatMethodPath: (methodPath: MethodPath) => string;

package/cjs/methodSerialization.js

@@ -1,48 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatMethodPath = exports.getMethodAtMethodPath = exports.extractMethodPathsFromMethods = void 0;
-const guards_js_1 = require("./guards.js");
-// TODO: Used for backward-compatibility. Remove in next major version.
-/**
- * Given an object of (nested) keys to functions, extract paths to each function.
- *
- * @example
- * Given this Method object:
- * {
- *   one: {
- *     two: () => {}
- *   }
- *   three: () => {}
- * }
- *
- * the extracted MethodPath[] would be:
- * [
- *   ['one', 'two'],
- *   ['three']
- * ]
- */
-const extractMethodPathsFromMethods = (methods, currentPath = []) => {
-    const methodPaths = [];
-    for (const key of Object.keys(methods)) {
-        const value = methods[key];
-        if ((0, guards_js_1.isFunction)(value)) {
-            methodPaths.push([...currentPath, key]);
-        }
-        else if ((0, guards_js_1.isObject)(value)) {
-            methodPaths.push(...(0, exports.extractMethodPathsFromMethods)(value, [...currentPath, key]));
-        }
-    }
-    return methodPaths;
-};
-exports.extractMethodPathsFromMethods = extractMethodPathsFromMethods;
-const getMethodAtMethodPath = (methodPath, methods) => {
-    const result = methodPath.reduce((acc, pathSegment) => {
-        return (0, guards_js_1.isObject)(acc) ? acc[pathSegment] : undefined;
-    }, methods);
-    return (0, guards_js_1.isFunction)(result) ? result : undefined;
-};
-exports.getMethodAtMethodPath = getMethodAtMethodPath;
-const formatMethodPath = (methodPath) => {
-    return methodPath.join('.');
-};
-exports.formatMethodPath = formatMethodPath;

package/cjs/namespace.d.ts

@@ -1,2 +0,0 @@
-declare const _default: "penpal";
-export default _default;

package/cjs/namespace.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = 'penpal';

package/cjs/once.d.ts

@@ -1,2 +0,0 @@
-declare const once: <T extends (...args: any[]) => any>(fn: T) => ((...args: Parameters<T>) => ReturnType<T>);
-export default once;

package/cjs/once.js

@@ -1,15 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const once = (fn) => {
-    let isCalled = false;
-    let result;
-    return (...args) => {
-        if (!isCalled) {
-            isCalled = true;
-            result = fn(...args);
-        }
-        return result;
-    };
-};
-exports.default = once;

package/cjs/shakeHands.d.ts

@@ -1,76 +0,0 @@
-import Messenger from './messengers/Messenger.js';
-import { Methods, RemoteProxy, Log } from './types.js';
-type Options = {
-    messenger: Messenger;
-    methods: Methods;
-    timeout: number | undefined;
-    channel: string | undefined;
-    log: Log | undefined;
-};
-type HandshakeResult<TMethods extends Methods> = {
-    remoteProxy: RemoteProxy<TMethods>;
-    destroy: () => void;
-};
-/**
- * Attempts to establish communication with the remote via a handshake protocol.
- * The handshake protocol fulfills a few requirements:
- *
- * 1. One participant in the handshake may not be available when the other
- *    participant starts the handshake. For example, a document inside an iframe
- *    may not be loaded when the parent window starts a handshake.
- * 2. While #1 could be solved by having the consumer of Penpal specify which
- *    participant should initiate the handshake, we'd rather avoid this
- *    unnecessary cognitive load.
- * 3. While #1 could be solved by having the consumer of Penpal specify which
- *    participant is the "parent" or "child" and then having Penpal assume
- *    the child should initiate the handshake, we'd rather avoid parent-child
- *    terminology since Penpal can support communication between two
- *    participants where neither would be considered a parent nor child. It may
- *    also be too presumptive that the child should always initiate the
- *    handshake.
- * 4. For robustness, each participant must know that the other participant is
- *    receiving its messages for the handshake to be considered complete.
- * 5. The handshake should support a participant attempting to
- *    re-establish the connection. This can occur, for example, if an end user
- *    were to right-click within an iframe and click reload.
- * 6. The handshake should allow a Messenger to easily attach something to
- *    a handshake message from one participant to the other unidirectionally
- *    (rather than from both participants to each other).
- *    This is important when a participant needs to be in charge of, for
- *    example, creating a MessageChannel and sending one MessagePort from the
- *    MessagePort pair to the other participant. If both participants attempted
- *    to do this it could lead to confusion.
- * 7. The handshake ideally shouldn't require sending handshake messages on an
- *    interval (retrying until the other participant is ready to receive them).
- *    Intervals can increase compute resources if the interval is too short
- *    or increase latency if the interval is too long. While we could make this
- *    configurable, it's additional mental load for the consumer. Additionally,
- *    setInterval and setTimeout are not available within some contexts
- *    (like AudioWorklet), where a consumer may like to use Penpal.
- *
- * To accomplish these requirements, the handshake protocol is as follows:
- * 1. Each participant generates a random participant ID.
- * 2. As soon as possible, each participant sends a SYN message containing its
- *    participant ID to the other participant.
- * 3. When the SYN messages were sent, one of the participants may not have
- *    been ready to receive the SYN message from the other. At least one
- *    of the participants was ready, however, and should have received a SYN
- *    message from the other participant. Each participant that did receive
- *    a SYN message knows for sure that the other participant is now ready
- *    to receive a SYN message, so it will send another SYN message in case
- *    the other participant did not receive the first SYN message. This
- *    ultimately results in each participant sending two SYN messages.
- * 4. Each participant now should have received at least one SYN message from
- *    the other participant. Each participant compares their own ID with the
- *    other participant's ID. Whichever participant has the higher ID
- *    (using a simple string comparison) is considered the handshake leader
- *    and will send an ACK1 message to the other participant.
- * 5. At this point, the handshake leader does not know whether the other
- *    participant is actually receiving messages. The participant receiving
- *    the ACK1 message will respond with an ACK2, informing the handshake
- *    leader that it is indeed receiving messages.
- * 6. At this point, both participants know the other is receiving messages
- *    and the handshake is complete.
- */
-declare const shakeHands: <TMethods extends Methods>({ messenger, methods, timeout, channel, log, }: Options) => Promise<HandshakeResult<TMethods>>;
-export default shakeHands;