npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@rajnandan1/ruto

v1.0.1

Published

Ruto is a lightweight(4KB), fast and easy-to-use JS library that streamlines the communication between parent and child window(iframe/popup).

Downloads

5

Readme

Ruto

Ruto is a lightweight(4KB), fast and easy-to-use JS library that streamlines the communication between parent and child window(iframe/popup).

It uses client-server design pattern to communicate between parent and child window. Any window can become the client or the server depending on who wants to send. It abstracts out the complications of postMessage API and provides a simple API to send and receive messages.

Scenarios where it can be used

  1. Parent window wants to send a message to child window and wants to wait for the response from the child window.
  2. Parent window wants to send a message to child window and expects a reply within x seconds.

Demo

Table of Contents

Installation

CDN

<script src="https://cdn.jsdelivr.net/gh/rajnandan1/ruto/dist/ruto.min.js"></script>

ES6

npm i @rajnandan1/ruto

API

The library exposes two methods send and receive.

send

The send method is used to send a message from parent window to child window or vice versa. It returns a promise which resolves with the response from the child window.

send(route: string, node: Window | HTMLIFrameElement, message: string, options: WindowMQOptions): Promise<string>

route

The route is a unique identifier for the message. It has three parts

  • origin: The origin of the child window. Example if iframe or popup is located at http://example.com/iframe.html, then the origin will be http://example.com
  • type: The type of the window communication
    • parent-to-iframe: When you want to send a message from parent to iframe
    • parent-to-window: When you want to send a message from parent to popup
    • iframe-to-parent: When you want to send a message from iframe to parent
    • window-to-parent: When you want to send a message from popup to parent
  • topic: The topic of the message. Can be any string

Example: http://example.com/parent-to-iframe/sometopic

node

The node is the child window to which the message is to be sent. It can be either a window object or an iframe element. Example: document.getElementById('iframe') or window.open('popup.html', 'popup', 'width=600,height=400)

message

The message is the data that is to be sent to the child window. It has to be a string. If you want to send JSON, you have to stringify it before sending.

options

The options is an object that can have the following properties. It is optional

  • timeout: The time in milliseconds to wait for the response from the child window. If the response is not received within the timeout, the promise will be rejected with a timeout error. Example: {timeout: 5000}

receive

The receive method is used to receive a message from a window. It is used by the child window to receive messages from the parent window. It can also be used by parent to receive message from child window. It is a callback function that is called when a message is received.

receive(subpath: string, node: Window | HTMLIFrameElement, callback: (res: Response, message: string) => void)

subpath

The subpath is a unique identifier for the message. It has two parts

  • type: The type of the window communication
    • parent-to-iframe: When you want to send a message from parent to iframe
    • parent-to-window: When you want to send a message from parent to popup
    • iframe-to-parent: When you want to send a message from iframe to parent
    • window-to-parent: When you want to send a message from popup to parent
  • topic: The topic of the message. Can be any string

[!IMPORTANT]
The subpath should be the same as the route of the sender. If the subpath is different, the message will not be received. It does not need the origin part of the route.

Example: parent-to-iframe/sometopic

node

The node is the window from which the message is to be received. It can be

  • iframe element
  • popup window reference
  • window.parent
  • window.opener

Example: document.getElementById('iframe') or window.parent

callback

The callback is a function that is called when a message is received. It has two parameters

  • response: The response object that is used to send a response back to the sender using response.send
  • message: The message that is sent by the sender. It is a string.

Example:

ruto.receive('http://localhost:3000/parent-to-iframe/sometopic', window.parent, (response, message) => {
    const newMessage = message + ' edited by child';
    return response.send(newMessage);
});

Usage

⭐ Parent to Iframe Example

Parent Window

//<iframe id="http://localhost:3000/somePath/someiframe.html" src="iframe.html" width="100%" height="800" frameborder="0"></iframe>

const options = {
    timeout: 5000,
};
ruto.send('http://localhost:3000/parent-to-iframe/sometopic', document.getElementById('iframe'), 'Your message', options)
    .then((response) => {
        console.log(response); //Your message edited by iframe
    })
    .catch((error) => {
        console.log(error);
    });

Child Window

ruto.receive('/parent-to-iframe/sometopic', window.parent, (response, message) => {
    const newMessage = message + ' edited by iframe';
    return response.send(newMessage);
});

⭐ Parent to Popup Example

Parent Window

//const popup = window.open('popup.html', 'popup', 'width=600,height=400');

const options = {
    timeout: 5000,
};
ruto.send('http://localhost:3000/parent-to-window/sometopic', popup, 'Your message', options)
    .then((response) => {
        console.log(response); //Your message edited by popup
    })
    .catch((error) => {
        console.log(error);
    });

Popup Window

ruto.receive('/parent-to-window/sometopic', window.opener, (response, message) => {
    const newMessage = message + ' edited by popup';
    return response.send(newMessage);
});

⭐ Iframe to Parent Example

Iframe Window

const options = {
    timeout: 5000,
};
ruto.send('http://localhost:3000/iframe-to-parent/sometopic', window.parent, 'Your message', options)
    .then((response) => {
        console.log(response); //Your message edited by parent
    })
    .catch((error) => {
        console.log(error);
    });

Parent Window

ruto.receive('/iframe-to-parent/sometopic', window.parent, (response, message) => {
    const newMessage = message + ' edited by parent';
    return response.send(newMessage);
});

⭐ Popup to Parent Example

Popup Window

const options = {
    timeout: 5000,
};
ruto.send('http://localhost:3000/window-to-parent/sometopic', window.opener, 'Your message', options)
    .then((response) => {
        console.log(response); //Your message edited by parent
    })
    .catch((error) => {
        console.log(error);
    });

Parent Window

ruto.receive('/window-to-parent/sometopic', window.opener, (response, message) => {
    const newMessage = message + ' edited by parent';
    return response.send(newMessage);
});