Messaging Bus

A cross frame/window messaging system

to use you may import/require the module directly or for direct use in browser use the dist module

How to Use

Add via a script tag or require in your code, then instantiate the class like so:

const messaging = new MessagingBus('some-unique-name');

you will then want to add handlers for any messages/request your app expects to handle like so:

//for a message
messaging.addCallback('INTERESTING_MESSAGE', (action, payload) => {
    alert('i got a message!', payload.message);
});

//for a request
messaging.addCallback('SOME_REQUEST', (action, payload) => {
    if(payload.something) {
        return 'yes';
    }
    return 'no';
})

//you can also return a promise to run async work and return the result
messaging.addCallback('DO_SOMETHING_ASYNC', (action, payload) => {
    return new Promsie(resolve => {
        setTimeout(() => {
            resolve({
                data: 'yey'
            });
        }, 100);
    })
});

Messages

to dispatch a message to a frame you have three options:

1. sendMessage | send a message to a specific window/frame knowing the exact handle (registered at class instantiation)
2. sendMessageToWindow | send a message to a specific window/frame knowing the contentWindow
3. sendMessageToAll | send a message to all other windows (or just direct descendants)
4. sendFilteredMessage | send a message to any registered instances that match a given regex pattern

to send a message to a specific instance by handle do the following:

messaging.sendMessage('specific-unique-id', 'INTERESTING_MESSAGE', {
    messgae: 'something interesting, no doubt'
});

Note:

the message sending methods return a promise, you may send and not listen to the resolve of this promise if you dont require message send acknowledgement, the promise will simply resolve empty once the message has been acknowledged by the receiving end, to ensure delivery listen for the promise resolution.

Requests

to dispatch a request to a frame and await its return you also have three almost identical options:

1. sendRequest | send a request to a specific window/frame knowing the exact handle (registered at class instantiation) and await a response
2. sendRequestToWindow | send a request to a specific window/frame knowing the contentWindow
3. sendRequestToAll | send a request to all other windows (or just direct descendants) and await a response from all
4. sendFilteredRequest | send a request to any registered instances that match a given regex pattern and await a response from all

all three of these methods returns a Promise with the response data and handle from the window/frame(s) that were requested.

to send a request to a specific instance by handle and parse the result do the following:

messaging.sendRequest('specific-unique-id', 'SOME_REQUEST', {
    data: 'something interesting, no doubt'
})
    .then(res => {
        alert(res.response.data);
    });

Request Specific Parameters

timeout requests have a timeout, by default this is set to 1 second

(1000ms) you may set this to a time limit you believe is more suitable for your request, by default if a request isn't returned within the timeout period the Promise is rejected. See allowPartialResponse property for allowing some responses to not return in a request to multiple frames/windows.

Multi Request Parameters

directDescendantsOnly

set this to true if you only want to dispatch requests to direct children and not grandchildren or deeper, this can be useful if you know you have deeper frames with instantiated handlers, but dont wish to accidentally trigger

allowPartialResponse

set this to true to allow some frames to not respond within the given timeout period, the default behaviour is to reject on any non returning response, but with this on your request will only reject if no responses are returned.

API Docs

find full API docs here

Debugging

to enable debugging set the localStorage value: messagingbus__debug to a MessagingBus instance handle or * for instance to log all messagingBus instances run the following in console:

localStorage.messagingbus__debug = '*';

you may also set a wild card beginning or end to your debug specifier for instance: *instance which would allow for windows with a handle ending in instance to show debugging.

Debug Levels

by default debug is enabled for sending messages and requests, you may also enable for internal messages and/or internal send events by setting the localstorage item: messagingbus__debugLevel

Allowed Values:

• send
• request
• internal
• internal_send

to set which log levels you wish to see use the following code:

localStorage.messagingbus__debugLevel = ['internal', 'request']; //this will enable internal messaging debugging and request debugging but disable send and internal send debugging