0.5.236 • Published 9 months ago

@opensea/vessel v0.5.236

Weekly downloads
-
License
ISC
Repository
-
Last release
9 months ago

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:

PropertyDescriptionDefault
iframeThe iframe element to communicate with. If not provided the constructed instance will be a child vessel.undefined (instance is child vessel)
applicationThe application name to use for vessel messages. Must be shared between parent and child."opensea-vessel"
defaultTimeoutDefault number of milliseconds to wait for a message response before throwing a TimeoutError5_000 (5s)
handshakeTimeoutNumber of milliseconds to wait for a handshake response before throwing a HandshakeTimeoutError10_000 (10s)
targetOriginThe target origin for the iframe or parent window to connect to. Directly used as postMessage targetOrigin."*" (Any origin)
debugWhether 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:

PropertyDescriptionDefault
timeoutNumber of milliseconds to wait for a response before throwing a TimeoutError5_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
  }
})
0.5.235

9 months ago

0.5.234

9 months ago

0.5.236

9 months ago

0.5.233

9 months ago

0.5.232

9 months ago

0.5.226

9 months ago

0.5.231

9 months ago

0.5.230

9 months ago

0.5.228

9 months ago

0.5.227

9 months ago

0.5.229

9 months ago

0.5.213

9 months ago

0.5.212

9 months ago

0.5.215

9 months ago

0.5.214

9 months ago

0.5.211

9 months ago

0.5.210

9 months ago

0.5.209

9 months ago

0.5.206

9 months ago

0.5.205

9 months ago

0.5.208

9 months ago

0.5.207

9 months ago

0.5.224

9 months ago

0.5.223

9 months ago

0.5.225

9 months ago

0.5.220

9 months ago

0.5.222

9 months ago

0.5.221

9 months ago

0.5.217

9 months ago

0.5.216

9 months ago

0.5.219

9 months ago

0.5.218

9 months ago

0.5.202

9 months ago

0.5.201

9 months ago

0.5.204

9 months ago

0.5.203

9 months ago

0.5.200

9 months ago

0.5.194

9 months ago

0.5.193

9 months ago

0.5.196

9 months ago

0.5.195

9 months ago

0.5.190

9 months ago

0.5.192

9 months ago

0.5.191

9 months ago

0.5.198

9 months ago

0.5.197

9 months ago

0.5.199

9 months ago

0.5.183

9 months ago

0.5.185

9 months ago

0.5.184

9 months ago

0.5.187

9 months ago

0.5.186

9 months ago

0.5.189

9 months ago

0.5.188

9 months ago

0.5.172

9 months ago

0.5.171

9 months ago

0.5.174

9 months ago

0.5.173

9 months ago

0.5.179

9 months ago

0.5.176

9 months ago

0.5.175

9 months ago

0.5.178

9 months ago

0.5.177

9 months ago

0.5.182

9 months ago

0.5.181

9 months ago

0.5.180

9 months ago

0.5.170

9 months ago

0.5.169

9 months ago

0.5.168

9 months ago

0.5.165

9 months ago

0.5.164

9 months ago

0.5.167

9 months ago

0.5.166

9 months ago

0.5.158

9 months ago

0.5.157

9 months ago

0.5.159

9 months ago

0.5.161

9 months ago

0.5.160

9 months ago

0.5.163

9 months ago

0.5.162

9 months ago

0.5.147

10 months ago

0.5.146

10 months ago

0.5.149

10 months ago

0.5.148

10 months ago

0.5.143

10 months ago

0.5.142

10 months ago

0.5.145

10 months ago

0.5.144

10 months ago

0.5.150

10 months ago

0.5.152

10 months ago

0.5.151

10 months ago

0.5.154

9 months ago

0.5.153

10 months ago

0.5.156

9 months ago

0.5.155

9 months ago

0.5.136

10 months ago

0.5.135

10 months ago

0.5.138

10 months ago

0.5.137

10 months ago

0.5.134

10 months ago

0.5.141

10 months ago

0.5.140

10 months ago

0.5.139

10 months ago

0.5.133

10 months ago

0.5.98

10 months ago

0.5.99

10 months ago

0.5.96

10 months ago

0.5.97

10 months ago

0.5.94

10 months ago

0.5.95

10 months ago

0.5.92

10 months ago

0.5.93

10 months ago

0.5.90

10 months ago

0.5.91

10 months ago

0.5.87

10 months ago

0.5.88

10 months ago

0.5.85

10 months ago

0.5.86

10 months ago

0.5.83

10 months ago

0.5.84

10 months ago

0.5.81

10 months ago

0.5.82

10 months ago

0.5.103

10 months ago

0.5.102

10 months ago

0.5.105

10 months ago

0.5.104

10 months ago

0.5.101

10 months ago

0.5.89

10 months ago

0.5.100

10 months ago

0.5.80

10 months ago

0.5.76

10 months ago

0.5.77

10 months ago

0.5.74

10 months ago

0.5.75

10 months ago

0.5.72

10 months ago

0.5.73

10 months ago

0.5.71

10 months ago

0.5.78

10 months ago

0.5.79

10 months ago

0.5.130

10 months ago

0.5.132

10 months ago

0.5.131

10 months ago

0.5.129

10 months ago

0.5.128

10 months ago

0.5.114

10 months ago

0.5.113

10 months ago

0.5.116

10 months ago

0.5.115

10 months ago

0.5.110

10 months ago

0.5.112

10 months ago

0.5.111

10 months ago

0.5.107

10 months ago

0.5.106

10 months ago

0.5.109

10 months ago

0.5.108

10 months ago

0.5.125

10 months ago

0.5.124

10 months ago

0.5.127

10 months ago

0.5.126

10 months ago

0.5.121

10 months ago

0.5.120

10 months ago

0.5.123

10 months ago

0.5.122

10 months ago

0.5.118

10 months ago

0.5.117

10 months ago

0.5.119

10 months ago

0.5.70

10 months ago

0.5.65

10 months ago

0.5.66

10 months ago

0.5.63

10 months ago

0.5.64

10 months ago

0.5.61

10 months ago

0.5.62

10 months ago

0.5.60

10 months ago

0.5.69

10 months ago

0.5.67

10 months ago

0.5.68

10 months ago

0.5.54

11 months ago

0.5.55

11 months ago

0.5.52

11 months ago

0.5.53

11 months ago

0.5.50

11 months ago

0.5.51

11 months ago

0.5.58

11 months ago

0.5.59

10 months ago

0.5.56

11 months ago

0.5.57

11 months ago

0.5.43

11 months ago

0.5.44

11 months ago

0.5.41

11 months ago

0.5.42

11 months ago

0.5.49

11 months ago

0.5.47

11 months ago

0.5.48

11 months ago

0.5.45

11 months ago

0.5.46

11 months ago

0.5.40

11 months ago

0.5.38

11 months ago

0.5.39

11 months ago

0.5.36

11 months ago

0.5.37

11 months ago

0.5.35

11 months ago

0.5.34

11 months ago

0.5.32

11 months ago

0.5.33

11 months ago

0.5.31

11 months ago

0.5.30

11 months ago

0.5.29

11 months ago

0.5.27

11 months ago

0.5.28

11 months ago

0.5.25

11 months ago

0.5.26

11 months ago

0.5.24

11 months ago

0.5.23

11 months ago

0.5.22

11 months ago

0.5.21

11 months ago

0.5.18

11 months ago

0.5.19

11 months ago

0.5.17

11 months ago

0.5.20

11 months ago

0.5.16

11 months ago

0.5.14

11 months ago

0.5.15

11 months ago

0.5.12

11 months ago

0.5.13

11 months ago

0.5.10

11 months ago

0.5.11

11 months ago

0.5.9

11 months ago

0.4.86

12 months ago

0.4.87

12 months ago

0.4.84

12 months ago

0.4.85

12 months ago

0.4.82

12 months ago

0.4.83

12 months ago

0.4.80

12 months ago

0.4.81

12 months ago

0.4.88

12 months ago

0.4.89

12 months ago

0.4.102

11 months ago

0.4.101

11 months ago

0.4.100

12 months ago

0.4.105

11 months ago

0.4.104

11 months ago

0.4.103

11 months ago

0.4.79

12 months ago

0.5.4

11 months ago

0.5.3

11 months ago

0.5.6

11 months ago

0.5.5

11 months ago

0.5.0

11 months ago

0.5.2

11 months ago

0.5.1

11 months ago

0.5.8

11 months ago

0.5.7

11 months ago

0.4.97

12 months ago

0.4.98

12 months ago

0.4.95

12 months ago

0.4.96

12 months ago

0.4.93

12 months ago

0.4.94

12 months ago

0.4.91

12 months ago

0.4.92

12 months ago

0.4.99

12 months ago

0.2.1

1 year ago

0.2.0

1 year ago

0.4.90

12 months ago

0.2.2

1 year ago

0.1.0

1 year ago

0.0.22

1 year ago

0.0.21

1 year ago

0.0.20

2 years ago

0.0.19

2 years ago

0.0.18

2 years ago

0.0.17

2 years ago

0.0.16

2 years ago

0.0.15

2 years ago

0.0.14

2 years ago

0.0.13

2 years ago

0.0.12

2 years ago

0.0.11

2 years ago

0.0.10

2 years ago

0.0.9

2 years ago

0.0.8

2 years ago

0.0.7

2 years ago

0.0.6

2 years ago

0.0.5

2 years ago

0.0.4

2 years ago

0.0.3

2 years ago

0.0.2

2 years ago

0.0.1

2 years ago