@livechat/postmessenger

A library which makes postMessage communication easier. It's responsible for:

- establishing a connection between a parent page and a child iframe,
- allowing promisified remote procedure calls,
- allowing events to be dispatched to the listener on the other side.

It's using a custom protocol for a communication - it's using a distinct shape of passed frames. The protocol was designed with different frame types in mind (currently handshake, response, call & emit). Given global nature of window.postMessage communication, it annotates all sent frames with:

- "unique" fingerprint (namespaced string),
- owner ID (allows multiple copies of the library to coexist on a single page),
- instance ID (allows multiple instances to be created on a single page).

Terminology

$3

Handshake is the point in time when we know that the connection has been established and it's safe to send data between parties.

Both sides of the communication receive a promise object which resolves after the so-called handshake. It's the point in time when we know that the connection has been established and it's safe to send data to the "other side".

$3

Object consisting of data & methods given to the initialization function.

Data (plain values) are being sent to the "other side" and are given to the consumer on the "other side" when initialization promise resolves.

Methods are being registered within instance and can be called remotely by the instance existing on the other side of the communication using instance.call('methodName', ...args).

Types

``ts
type Api = {
call: (method: string, ...args: any[]) => Promise,
emit: (event: string, data: any) => void,
off: (event: string, callback: (...args: any[]) => any) => void,
on: (event: string, callback: (...args: any[]) => any) => void,
once: (event: string, callback: (...args: any[]) => any) => void,
}

type Model = { [key: string]: string | number | (...args: any[]) => any }

type Destroy = () => void

type IframeInstance = {
destroy: Destroy,
frame: HTMLIFrameElement,
promise: Promise destroy: Destroy,
frame: HTMLIFrameElement,
data: { [key: string]: string | number }
}>
}

type ParentInstance = {
promise: Promise data: { [key: string]: string | number }
}>
}
`

API

$3

`ts
function createIframe(
{
container,
url,
targetOrigin,
handshakeRetry,
}: {
container: string
url: string
targetOrigin?: string
handshakeRetry?: { interval?: number; count?: number }
},
model?: Model,
): IframeInstance
`

$3

`ts
function connectToParent(
model?: Model,
options?: { handshakeTimeout?: number },
): IframeInstance
``

Inspired by

- postmate