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.