1.0.3 • Published 2 years ago

postdoc-lib v1.0.3

Weekly downloads
-
License
MIT
Repository
github
Last release
2 years ago

Build Status Published on npm Downloads License Version GitHub stars

Overview

A PostDoc JS library that simplifies message passing between iframes, web workers, or anything that has a postMessage interface and and offers multiple handshakes.

Initially created to simplify communication with an iframe that reloads often.

Getting Started

Install

npm i postdoc-lib

Usage

Postdoc must be instantiated in both ends. e.g. Main Window and iframe or Main Window and Web Worker.

This is an example of how you would set up postdoc in the host window:

// In main window
import { PostDoc } from 'postdoc';

(async () => {
  const onMessage = (e: MessageEvent) => {
    console.log(`Parent received message: ${e.data}`);
  };

  const postdoc = new PostDoc({
    // Where to listen for handshake messages
    messageReceiver: window,
    // [optional] origin used for postMessage for Window targets
    origin: 'https://my-domain.com',
    onMessage
  });

  await postdoc.handshake;
  postdoc.postMessage('Message from parent');
})()

This is how you would set up postdoc in an iframe that reloads often:

// In iframe that reloads often
import { PostDoc } from 'postdoc';

(async () => {
  const onMessage = (e: MessageEvent) => {
    console.log(`iframe received message: ${e.data}`);
  };

  const postdoc = new PostDoc({
    // Where to listen for handshake messages
    messageReceiver: window,
    messageTarget: window.top!,
    onMessage
  });

  await postdoc.handshake;
  postdoc.postMessage('Message message from iframe');
})()

API

Properties

PropertyTypeDescription
handshakePromise<PostDoc>Promise that resolves when the pairing is complete between the given PostDoc instance and the instance at the other end of the messageTarget
onMessage<T = unknown>(message: MessageEvent<T>) => unknownThe function to be called when a message is received from the paired PostDoc
messageReceiverMessageReceiver\|null*The source that should be listened to for hanshake messages. e.g. winow when communicating with an iframe that will post on window.top or Worker when communicating with a worker that will post on self
messageTargetPostMessageTarget\|null**The target for handhsake messages. If inferTarget*** is true and messageTarget is omitted, messageTarget will be set to the first MessageEventSource that fires a handshake message to the given messageReceiver. NOTE: If handshake message is fired to receiver before PostDoc is instantiated, the handshake will not resolve. This can be prevented in most cases by setting messageTarget in both message sources. Additionally, messageReceiver should be set before messageTarget or set in the constructor.

* See MessageReceiver for more information.

** PostMessageTarget is a MessageEventSource which is a WindowProxy,MessagePort, or a ServiceWorker object.

* See inferTarget in MessageReceiver for more information.

Methods

MethodSignatureDescription
constructorconstructor(config?: PosdocConfig)*Constructs the Postdoc instance
postMessagepostMessage<T = unknown>(message: T, options?: StructuredSerializeOptions)Posts a message to the paired postdoc instance. NOTE: await postdoc.handshake to ensure that postdoc pairing is complete and ready for postMessage

* See PostdocConfig for more information.

MessageReceiver

MessageReceiver is an interface that is common with objects such as Window, Worker, ServiceWorker, etc. The interface has the following structure:

MemberType
addEventListenertypeof Window.prototype.addEventListener
removeEventListenertypeof Window.prototype.removeEventListener

PostdocConfig

PostdocConfig is the type of the object that is passed to the constructor.

MemberTypeDefaultDescription
originstring'*'The origin used for postMessage for Window targets
onMessage<T = unknown>(message: MessageEvent<T>) => unknown() => {}See onMessage in Properties for more information.
inferTargetbooleanfalseIf true, and messageTarget is not defined, the messageTarget will be inferred to be the first MessageEventSource that fires a handshake message to the given messageReceiver. If false, messageTarget must be set by the user.
messageTargetPostMessageTarget|undefinedundefinedSee messageTarget in Properties for more information.
messageReceiverMessageReceiver|undefinedundefinedSee messageReceiver in Properties for more information.

Contribution

Development

Start the build an start the server:

npm run dev

Testing

To run the tests:

npm run build
npm run test

To Dev with the tests, run npm run dev in one terminal and the following command in another:

npm run test:watch
1.0.3

2 years ago

1.0.2

2 years ago

1.0.1

2 years ago

1.0.0

2 years ago