v3.0.4

Improved TypeScript support.

v3.0.3

Improved TypeScript support.

v3.0.2

Fixed issue where reconnection was not properly disconnecting old receivers.

v3.0.1

Improved TypeScript support.

v3.0.0

parentOrigin no longer supports an array

The parentOrigin option passed to connectToParent() may no longer be an array containing multiple origins. It must be a string containing a single origin.

Added connection timeout support

Penpal.connectToChild() and Penpal.connectToParent() now accept a timeout option. If the timeout elapses before a connection is established, the connection promise will be rejected.

Added reconnection support

If the child iframe attempts to reconnect with the parent, the parent will accept the new connection. This could happen, for example, if a user refreshes the child iframe or navigates within the iframe to a different page that also uses Penpal. In this case, the child object the parent received when the initial connection was established will be updated with the new methods provided by the child iframe.

NOTE: Currently there is no API to notify consumers of a reconnection. If this is important for you, please file an issue and explain why it would be beneficial to you.

Improved error reporting

Penpal will throw (or reject promises with) errors in certain situations. Each error will have a code property which may be used for programmatic decisioning (e.g., do something if the error was due to a connection timing out) along with a message describing the problem. Errors may be thrown with the following codes:

• Penpal.ERR_CONNECTION_DESTROYED
  • connection.promise will be rejected with this error if the connection is destroyed (by calling connection.destroy()) while Penpal is attempting to establish the connection.
  • This error will be thrown when attempting to call a method on child or parent objects and the connection was previously destroyed.
• Penpal.ERR_CONNECTION_TIMEOUT
  • connection.promise will be rejected with this error after the timeout duration has elapsed and a connection has not been established.
• Penpal.ERR_NOT_IN_IFRAME
  • This error will be thrown when attempting to call Penpal.connectToParent() from outside of an iframe context.

While these error codes are on the Penpal object itself, they are also named exports. You may import them as follows:

import {
  ERR_CONNECTION_DESTROYED,
  ERR_CONNECTION_TIMEOUT,
  ERR_NOT_IN_IFRAME
} from 'penpal';

This provides an opportunity for build optimization (using tools like Webpack or Rollup) in cases where code only needs access to the error constants and not the rest of Penpal.

In addition to errors that originate from Penpal, Penpal also communicates consumer errors as well as possible. For example, if the parent were to call a method on a child and the child's method were to throw an error (e.g., throw new Error()), Penpal would catch the error, serialize it (including the error's type, message, and stack), and send it to the parent. Penpal would then deserialize the error on the parent side and use the deserialized error to reject the promise the parent was initially provided when calling the child's method. From the parent, this might look as follows:

connection.promise.then((child) => {
  child.multiply(2, 5).catch((error) => {
    console.log(error instanceof Error); // true
  });
});

This handling of consumer errors is provided in both parent-to-child and child-to-parent communication.

Added handling of unclonable return values.

Fixes #11. Ensures that a call's promise gets rejected when a response value cannot be cloned.

v2.7.0

Added TypeScript typings.

v2.6.0

Before, the parent would begin the handshake as soon as the child iframe loaded. Penpal now begins that handshake from the child to the parent. This allows some flexibility like loading Penpal asynchronously in the child iframe.

v2.5.0

Added support for defining parentOrigin as an array. This is useful if you expect your iframe view to potentially communicate with multiple different parent origins.

v2.0.0

PenPal has been renamed to Penpal (notice the capitalization). For those using the npm package, the package name was and is still penpal so this shouldn't be a breaking change for you. For those using the UMD distribution, the global variable set on window is now Penpal instead of PenPal.

The connectToChild and connectToParent methods no longer return a promise. They instead return an object that has a promise property. In the case of connectToChild, the object also has iframe and destroy properties. The iframe and destroy properties were previously provided on the child object that came through the resolved promise once the connection was established. It turns out that it's important to be able to destroy/cancel the process of connecting to the child before the connection has been established. This was the driving force behind releasing a major version.