penpal 7.0.3 → 7.0.4

package/cjs/shakeHands.js

@@ -1,190 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const PenpalError_js_1 = require("./PenpalError.js");
-const connectCallHandler_js_1 = require("./connectCallHandler.js");
-const connectRemoteProxy_js_1 = require("./connectRemoteProxy.js");
-const guards_js_1 = require("./guards.js");
-const getPromiseWithResolvers_js_1 = require("./getPromiseWithResolvers.js");
-const methodSerialization_js_1 = require("./methodSerialization.js");
-const generateId_js_1 = require("./generateId.js");
-const backwardCompatibility_js_1 = require("./backwardCompatibility.js");
-const namespace_js_1 = require("./namespace.js");
-/**
- * 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.
- */
-const shakeHands = ({ messenger, methods, timeout, channel, log, }) => {
-    const participantId = (0, generateId_js_1.default)();
-    let remoteParticipantId;
-    const destroyHandlers = [];
-    let isComplete = false;
-    const methodPaths = (0, methodSerialization_js_1.extractMethodPathsFromMethods)(methods);
-    const { promise, resolve, reject } = (0, getPromiseWithResolvers_js_1.default)();
-    const timeoutId = timeout !== undefined
-        ? setTimeout(() => {
-            reject(new PenpalError_js_1.default('CONNECTION_TIMEOUT', `Connection timed out after ${timeout}ms`));
-        }, timeout)
-        : undefined;
-    const destroy = () => {
-        for (const destroyHandler of destroyHandlers) {
-            destroyHandler();
-        }
-    };
-    const connectCallHandlerAndMethodProxies = () => {
-        if (isComplete) {
-            // If we get here, it means the remote is attempting to re-connect. While
-            // that's supported, we don't need to run the rest of this function again.
-            return;
-        }
-        destroyHandlers.push((0, connectCallHandler_js_1.default)(messenger, methods, channel, log));
-        const { remoteProxy, destroy: destroyMethodProxies } = (0, connectRemoteProxy_js_1.default)(messenger, channel, log);
-        destroyHandlers.push(destroyMethodProxies);
-        clearTimeout(timeoutId);
-        isComplete = true;
-        resolve({
-            remoteProxy,
-            destroy: destroy,
-        });
-    };
-    const sendSynMessage = () => {
-        const synMessage = {
-            namespace: namespace_js_1.default,
-            type: 'SYN',
-            channel,
-            participantId: participantId,
-        };
-        log?.(`Sending handshake SYN`, synMessage);
-        try {
-            messenger.sendMessage(synMessage);
-        }
-        catch (error) {
-            reject(new PenpalError_js_1.default('TRANSMISSION_FAILED', error.message));
-        }
-    };
-    const handleSynMessage = (message) => {
-        log?.(`Received handshake SYN`, message);
-        if (message.participantId === remoteParticipantId &&
-            // TODO: Used for backward-compatibility. Remove in next major version.
-            remoteParticipantId !== backwardCompatibility_js_1.DEPRECATED_PENPAL_PARTICIPANT_ID) {
-            return;
-        }
-        remoteParticipantId = message.participantId;
-        // We send another SYN message in case the other participant was not ready
-        // when we sent the first SYN message.
-        sendSynMessage();
-        const isHandshakeLeader = participantId > remoteParticipantId ||
-            // TODO: Used for backward-compatibility. Remove in next major version.
-            remoteParticipantId === backwardCompatibility_js_1.DEPRECATED_PENPAL_PARTICIPANT_ID;
-        if (!isHandshakeLeader) {
-            return;
-        }
-        const ack1Message = {
-            namespace: namespace_js_1.default,
-            channel,
-            type: 'ACK1',
-            methodPaths,
-        };
-        log?.(`Sending handshake ACK1`, ack1Message);
-        try {
-            messenger.sendMessage(ack1Message);
-        }
-        catch (error) {
-            reject(new PenpalError_js_1.default('TRANSMISSION_FAILED', error.message));
-            return;
-        }
-    };
-    const handleAck1Message = (message) => {
-        log?.(`Received handshake ACK1`, message);
-        const ack2Message = {
-            namespace: namespace_js_1.default,
-            channel,
-            type: 'ACK2',
-        };
-        log?.(`Sending handshake ACK2`, ack2Message);
-        try {
-            messenger.sendMessage(ack2Message);
-        }
-        catch (error) {
-            reject(new PenpalError_js_1.default('TRANSMISSION_FAILED', error.message));
-            return;
-        }
-        connectCallHandlerAndMethodProxies();
-    };
-    const handleAck2Message = (message) => {
-        log?.(`Received handshake ACK2`, message);
-        connectCallHandlerAndMethodProxies();
-    };
-    const handleMessage = (message) => {
-        if ((0, guards_js_1.isSynMessage)(message)) {
-            handleSynMessage(message);
-        }
-        if ((0, guards_js_1.isAck1Message)(message)) {
-            handleAck1Message(message);
-        }
-        if ((0, guards_js_1.isAck2Message)(message)) {
-            handleAck2Message(message);
-        }
-    };
-    messenger.addMessageHandler(handleMessage);
-    destroyHandlers.push(() => messenger.removeMessageHandler(handleMessage));
-    sendSynMessage();
-    return promise;
-};
-exports.default = shakeHands;

package/cjs/types.d.ts

@@ -1,89 +0,0 @@
-import CallOptions from './CallOptions.js';
-import Reply from './Reply.js';
-import namespace from './namespace.js';
-import ErrorCodeObj from './ErrorCodeObj.js';
-type ExtractValueFromReply<R> = R extends Reply ? Awaited<R['value']> : R;
-/**
- * An object representing methods exposed by the remote but that can be called
- * locally.
- */
-export type RemoteProxy<TMethods extends Methods = Methods> = {
-    [K in keyof TMethods]: TMethods[K] extends (...args: infer A) => infer R ? (...args: [...A, CallOptions?]) => Promise<ExtractValueFromReply<Awaited<R>>> : TMethods[K] extends Methods ? RemoteProxy<TMethods[K]> : never;
-};
-/**
- * An object representing the connection as a result of calling connect().
- */
-export type Connection<TMethods extends Methods = Methods> = {
-    /**
-     * A promise which will be resolved once the connection has been established.
-     */
-    promise: Promise<RemoteProxy<TMethods>>;
-    /**
-     * A method that, when called, will disconnect any communication.
-     * You may call this even before a connection has been established.
-     */
-    destroy: () => void;
-};
-/**
- * Methods to expose to the remote window. May contain nested objects
- * with methods as well.
- */
-export type Methods = {
-    [index: string]: Methods | Function;
-};
-/**
- * An array of path segments (object property keys) to use to find a method
- * within a Methods object. We avoid using a period-delimited string because
- * property names can have periods in them which could cause issues.
- */
-export type MethodPath = string[];
-export type ErrorCode = typeof ErrorCodeObj[keyof typeof ErrorCodeObj];
-export type SerializedError = {
-    name: string;
-    message: string;
-    stack?: string;
-    penpalCode?: ErrorCode;
-};
-type MessageBase = {
-    namespace: typeof namespace;
-    channel: string | undefined;
-};
-export type SynMessage = MessageBase & {
-    type: 'SYN';
-    participantId: string;
-};
-export type Ack1Message = MessageBase & {
-    type: 'ACK1';
-    methodPaths: MethodPath[];
-};
-export type Ack2Message = MessageBase & {
-    type: 'ACK2';
-};
-export type CallMessage = MessageBase & {
-    type: 'CALL';
-    id: string;
-    methodPath: MethodPath;
-    args: unknown[];
-};
-export type ReplyMessage = MessageBase & {
-    type: 'REPLY';
-    callId: string;
-} & ({
-    value: unknown;
-    isError?: false;
-    isSerializedErrorInstance?: false;
-} | {
-    value: unknown;
-    isError: true;
-    isSerializedErrorInstance?: false;
-} | {
-    value: SerializedError;
-    isError: true;
-    isSerializedErrorInstance: true;
-});
-export type DestroyMessage = MessageBase & {
-    type: 'DESTROY';
-};
-export type Message = SynMessage | Ack1Message | Ack2Message | CallMessage | ReplyMessage | DestroyMessage;
-export type Log = (...args: unknown[]) => void;
-export {};

package/cjs/types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/lib/CallOptions.d.ts

@@ -1,10 +0,0 @@
-declare class CallOptions {
-    #private;
-    readonly transferables?: Transferable[];
-    readonly timeout?: number;
-    constructor(options?: {
-        transferables?: Transferable[];
-        timeout?: number;
-    });
-}
-export default CallOptions;

package/lib/CallOptions.js

@@ -1,14 +0,0 @@
-const brand = Symbol('CallOptions');
-class CallOptions {
-    transferables;
-    timeout;
-    // Allows TypeScript to distinguish between an actual instance of this
-    // class versus an object that looks structurally similar.
-    // eslint-disable-next-line no-unused-private-class-members
-    #brand = brand;
-    constructor(options) {
-        this.transferables = options?.transferables;
-        this.timeout = options?.timeout;
-    }
-}
-export default CallOptions;

package/lib/ErrorCodeObj.d.ts

@@ -1,9 +0,0 @@
-declare const ErrorCodeObj: {
-    readonly ConnectionDestroyed: "CONNECTION_DESTROYED";
-    readonly ConnectionTimeout: "CONNECTION_TIMEOUT";
-    readonly InvalidArgument: "INVALID_ARGUMENT";
-    readonly MethodCallTimeout: "METHOD_CALL_TIMEOUT";
-    readonly MethodNotFound: "METHOD_NOT_FOUND";
-    readonly TransmissionFailed: "TRANSMISSION_FAILED";
-};
-export default ErrorCodeObj;

package/lib/ErrorCodeObj.js

@@ -1,12 +0,0 @@
-// Not intended to be used internally. Can be useful externally
-// in projects not using TypeScript. It has the `Obj` suffix to disambiguate
-// it from the ErrorCode string union.
-const ErrorCodeObj = {
-    ConnectionDestroyed: 'CONNECTION_DESTROYED',
-    ConnectionTimeout: 'CONNECTION_TIMEOUT',
-    InvalidArgument: 'INVALID_ARGUMENT',
-    MethodCallTimeout: 'METHOD_CALL_TIMEOUT',
-    MethodNotFound: 'METHOD_NOT_FOUND',
-    TransmissionFailed: 'TRANSMISSION_FAILED',
-};
-export default ErrorCodeObj;

package/lib/PenpalBugError.d.ts

@@ -1,8 +0,0 @@
-/**
- * Error class that is thrown when we've reached a situation that we believe to
- * be a bug in Penpal and not anything the consumer has done.
- */
-declare class PenpalBugError extends Error {
-    constructor(message: string);
-}
-export default PenpalBugError;

package/lib/PenpalBugError.js

@@ -1,10 +0,0 @@
-/**
- * Error class that is thrown when we've reached a situation that we believe to
- * be a bug in Penpal and not anything the consumer has done.
- */
-class PenpalBugError extends Error {
-    constructor(message) {
-        super(`You've hit a bug in Penpal. Please file an issue with the following information: ${message}`);
-    }
-}
-export default PenpalBugError;

package/lib/PenpalError.d.ts

@@ -1,6 +0,0 @@
-import { ErrorCode } from './types.js';
-declare class PenpalError extends Error {
-    code: ErrorCode;
-    constructor(code: ErrorCode, message: string);
-}
-export default PenpalError;

package/lib/PenpalError.js

@@ -1,9 +0,0 @@
-class PenpalError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.name = 'PenpalError';
-        this.code = code;
-    }
-}
-export default PenpalError;

package/lib/Reply.d.ts

@@ -1,9 +0,0 @@
-declare class Reply<T = unknown> {
-    #private;
-    readonly value: T;
-    readonly transferables?: Transferable[];
-    constructor(value: T, options?: {
-        transferables?: Transferable[];
-    });
-}
-export default Reply;

package/lib/Reply.js

@@ -1,14 +0,0 @@
-const brand = Symbol('Reply');
-class Reply {
-    value;
-    transferables;
-    // Allows TypeScript to distinguish between an actual instance of this
-    // class versus an object that looks structurally similar.
-    // eslint-disable-next-line no-unused-private-class-members
-    #brand = brand;
-    constructor(value, options) {
-        this.value = value;
-        this.transferables = options?.transferables;
-    }
-}
-export default Reply;

package/lib/backwardCompatibility.d.ts

@@ -1,56 +0,0 @@
-import { Message } from './types.js';
-export declare const DEPRECATED_PENPAL_PARTICIPANT_ID = "deprecated-penpal";
-declare enum DeprecatedMessageType {
-    Call = "call",
-    Reply = "reply",
-    Syn = "syn",
-    SynAck = "synAck",
-    Ack = "ack"
-}
-declare enum DeprecatedResolution {
-    Fulfilled = "fulfilled",
-    Rejected = "rejected"
-}
-type DeprecatedSynMessage = {
-    penpal: DeprecatedMessageType.Syn;
-};
-type DeprecatedSynAckMessage = {
-    penpal: DeprecatedMessageType.SynAck;
-    methodNames: string[];
-};
-type DeprecatedAckMessage = {
-    penpal: DeprecatedMessageType.Ack;
-    methodNames: string[];
-};
-type DeprecatedCallMessage = {
-    penpal: DeprecatedMessageType.Call;
-    id: number;
-    methodName: string;
-    args: unknown[];
-};
-type DeprecatedSerializedError = {
-    name: string;
-    message: string;
-    stack?: string;
-};
-type DeprecatedReplyMessage = {
-    penpal: DeprecatedMessageType.Reply;
-    id: number;
-} & ({
-    resolution: DeprecatedResolution.Fulfilled;
-    returnValue: unknown;
-    returnValueIsError?: false;
-} | {
-    resolution: DeprecatedResolution.Rejected;
-    returnValue: unknown;
-    returnValueIsError?: false;
-} | {
-    resolution: DeprecatedResolution.Rejected;
-    returnValue: DeprecatedSerializedError;
-    returnValueIsError: true;
-});
-export type DeprecatedMessage = DeprecatedSynMessage | DeprecatedSynAckMessage | DeprecatedAckMessage | DeprecatedCallMessage | DeprecatedReplyMessage;
-export declare const isDeprecatedMessage: (data: unknown) => data is DeprecatedMessage;
-export declare const upgradeMessage: (message: DeprecatedMessage) => Message;
-export declare const downgradeMessage: (message: Message) => DeprecatedMessage;
-export {};

package/lib/backwardCompatibility.js

@@ -1,128 +0,0 @@
-import namespace from './namespace.js';
-import { isCallMessage, isReplyMessage, isAck1Message, isObject, } from './guards.js';
-import PenpalBugError from './PenpalBugError.js';
-export const DEPRECATED_PENPAL_PARTICIPANT_ID = 'deprecated-penpal';
-// TODO: This file is used for backward-compatibility. Remove in next major version.
-var DeprecatedMessageType;
-(function (DeprecatedMessageType) {
-    DeprecatedMessageType["Call"] = "call";
-    DeprecatedMessageType["Reply"] = "reply";
-    DeprecatedMessageType["Syn"] = "syn";
-    DeprecatedMessageType["SynAck"] = "synAck";
-    DeprecatedMessageType["Ack"] = "ack";
-})(DeprecatedMessageType || (DeprecatedMessageType = {}));
-var DeprecatedResolution;
-(function (DeprecatedResolution) {
-    DeprecatedResolution["Fulfilled"] = "fulfilled";
-    DeprecatedResolution["Rejected"] = "rejected";
-})(DeprecatedResolution || (DeprecatedResolution = {}));
-export const isDeprecatedMessage = (data) => {
-    return isObject(data) && 'penpal' in data;
-};
-const upgradeMethodPath = (methodPath) => methodPath.split('.');
-const downgradeMethodPath = (methodPath) => methodPath.join('.');
-const getUnexpectedMessageError = (message) => {
-    return new PenpalBugError(`Unexpected message to translate: ${JSON.stringify(message)}`);
-};
-export const upgradeMessage = (message) => {
-    if (message.penpal === DeprecatedMessageType.Syn) {
-        return {
-            namespace,
-            channel: undefined,
-            type: 'SYN',
-            participantId: DEPRECATED_PENPAL_PARTICIPANT_ID,
-        };
-    }
-    if (message.penpal === DeprecatedMessageType.Ack) {
-        return {
-            namespace,
-            channel: undefined,
-            type: 'ACK2',
-        };
-    }
-    if (message.penpal === DeprecatedMessageType.Call) {
-        return {
-            namespace,
-            channel: undefined,
-            type: 'CALL',
-            // Actually converting the ID to a string would break communication.
-            id: message.id,
-            methodPath: upgradeMethodPath(message.methodName),
-            args: message.args,
-        };
-    }
-    if (message.penpal === DeprecatedMessageType.Reply) {
-        if (message.resolution === DeprecatedResolution.Fulfilled) {
-            return {
-                namespace,
-                channel: undefined,
-                type: 'REPLY',
-                // Actually converting the ID to a string would break communication.
-                callId: message.id,
-                value: message.returnValue,
-            };
-        }
-        else {
-            return {
-                namespace,
-                channel: undefined,
-                type: 'REPLY',
-                // Actually converting the ID to a string would break communication.
-                callId: message.id,
-                isError: true,
-                ...(message.returnValueIsError
-                    ? {
-                        value: message.returnValue,
-                        isSerializedErrorInstance: true,
-                    }
-                    : {
-                        value: message.returnValue,
-                    }),
-            };
-        }
-    }
-    throw getUnexpectedMessageError(message);
-};
-export const downgradeMessage = (message) => {
-    if (isAck1Message(message)) {
-        return {
-            penpal: DeprecatedMessageType.SynAck,
-            methodNames: message.methodPaths.map(downgradeMethodPath),
-        };
-    }
-    if (isCallMessage(message)) {
-        return {
-            penpal: DeprecatedMessageType.Call,
-            // Actually converting the ID to a number would break communication.
-            id: message.id,
-            methodName: downgradeMethodPath(message.methodPath),
-            args: message.args,
-        };
-    }
-    if (isReplyMessage(message)) {
-        if (message.isError) {
-            return {
-                penpal: DeprecatedMessageType.Reply,
-                // Actually converting the ID to a number would break communication.
-                id: message.callId,
-                resolution: DeprecatedResolution.Rejected,
-                ...(message.isSerializedErrorInstance
-                    ? {
-                        returnValue: message.value,
-                        returnValueIsError: true,
-                    }
-                    : { returnValue: message.value }),
-            };
-        }
-        else {
-            return {
-                penpal: DeprecatedMessageType.Reply,
-                // Actually converting the ID to a number would break communication.
-                id: message.callId,
-                resolution: DeprecatedResolution.Fulfilled,
-                returnValue: message.value,
-            };
-        }
-    }
-    throw getUnexpectedMessageError(message);
-};

package/lib/connect.d.ts

@@ -1,33 +0,0 @@
-import { Connection, Log, Methods } from './types.js';
-import Messenger from './messengers/Messenger.js';
-type Options = {
-    /**
-     * Messenger in charge of handling communication with the remote.
-     */
-    messenger: Messenger;
-    /**
-     * Methods that may be called by the remote.
-     */
-    methods?: Methods;
-    /**
-     * The amount of time, in milliseconds, Penpal should wait
-     * for a connection to be established before rejecting the connection promise.
-     */
-    timeout?: number;
-    /**
-     * A string identifier that disambiguates communication when establishing
-     * multiple, parallel connections between two participants (e.g., two windows,
-     * a window and a worker).
-     */
-    channel?: string;
-    /**
-     * A function for logging debug messages. Debug messages will only be
-     * logged when this is defined.
-     */
-    log?: Log;
-};
-/**
- * Attempts to establish communication with the remote.
- */
-declare const connect: <TMethods extends Methods>({ messenger, methods, timeout, channel, log, }: Options) => Connection<TMethods>;
-export default connect;