@opensea/vessel
v0.6.18
Published
Promise based wrapper for postMessage API 🚢
Downloads
19,235
Keywords
Readme
OpenSea Vessel 🚢
A promise based wrapper for the postMessage API for communications between a parent app and an iframed child app.
OpenSea Vessel can be used to send messages between a parent app and an iframed app, and await responses to messages. Example: Confirmation of receipt, result of RPC call.
Installation
You guessed it!
pnpm install @opensea/vessel
Getting Started
Import the Vessel
class
import { Vessel } from "@opensea/vessel"
Vessel
class contains logic for sending and receiving messages via the postMessage. It can be used in both the parent app and child app.
Parent app
The parent app mounts the iframe that loads the child app.
The parent app must pass a reference to the child iframe element into the Vessel
class constructor.
It is used to access the postMessage method of the iframe window.
// NOTE: Replace with reference to your iframe
const iframe = document.createElement("iframe")
const vessel = new Vessel({ iframe })
Child app
The child app is mounted in an iframe and has access to the postMessage API of its parent app's window by default. It does not require any extra params to be initialized.
const vessel = new Vessel()
Vessel
Constructor
Vessel
instances can be constructed with an options object. It includes the following properties:
| Property | Description | Default |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| iframe
| The iframe element to communicate with. If not provided the constructed instance will be a child vessel. | undefined
(instance is child vessel) |
| application
| The application name to use for vessel messages. Must be shared between parent and child. | "opensea-vessel"
|
| defaultTimeout
| Default number of milliseconds to wait for a message response before throwing a TimeoutError
| 5_000
(5s) |
| handshakeTimeout
| Number of milliseconds to wait for a handshake response before throwing a HandshakeTimeoutError
| 10_000
(10s) |
| targetOrigin
| The target origin for the iframe or parent window to connect to. Directly used as postMessage targetOrigin
. | "*"
(Any origin) |
| debug
| Whether to log debug messages to the console. | false
|
Sending messages
Sending messages from parent and child via a Vessel
class instance is the same.
// Examples
const response = await vessel.send("Any payload!")
const objectPayload = await vessel.send({
foo: "bar",
baz: { odee: ["nested", "is", "fine"] },
})
const customTimeout = await vessel.send(
"If no response in 3 seconds this promise will reject.",
{ timeout: 3_000 },
)
const noTimeout = await vessel.send("This promise might never resolve.", {
timeout: undefined,
})
The send method takes any JSON serializable payload as first param and an options object as the second. The options object includes the following properties:
| Property | Description | Default |
| --------- | ------------------------------------------------------------------------------ | ------------ |
| timeout
| Number of milliseconds to wait for a response before throwing a TimeoutError
| 5_000
(5s) |
Handling incoming messages
The Vessel
class can be used to add message listeners and exposes a convenient reply function for listeners to use. Message listener must return a boolean to indicate whether they handled the message or not.
type VesselMessageListener = (
message: VesselMessage,
reply: (response: unknown, options: ReplyOptions) => void,
) => boolean
// Example listener
vessel.addMessageListener((message, reply) => {
if (message.shouldBeHandledHere) {
const result = handleThisMessage(message)
reply(result)
return true
} else {
return false
}
})
Replying with errors
Sometimes the response to a message is an error and it is preferrable for the send
method to throw an error for the sender to handle.
Replying to a message with the options error
boolean set to true will cause sender to reject the send promise with the payload as an error when teh response is received.
interface ReplyOptions {
error?: boolean
}
// Example reply error
vessel.addMessageListener((message, reply) => {
if (message.shouldBeHandledHere) {
try {
const result = handleThisMessage(message)
reply(result)
} catch (error) {
reply(
{ reason: "Handling failed", stepsToFix: [1, 2, 3] },
{ error: true },
)
}
return true
} else {
return false
}
})