Skip to content

Latest commit

 

History

History
94 lines (72 loc) · 3.57 KB

README.md

File metadata and controls

94 lines (72 loc) · 3.57 KB
Raw

localMessage

This is a simple implementation of a Javascript class which passes messages between windows or tabs in a browser that share the same origin.

Messages are passed using only localStorage so it isn't necessary to have a window object in order to communicate and the mechanism survives a page reload.

If the consuming window is not open, or has not yet called receiveMessage on a name then the posted message will persist in local storage and be delivered when it does even some time later after the sending window is closed.

This is a neat way to get around the limitations of window.postMessage() with respect to needing a window reference and inter-tab issues, but should be used sparingly. It's (ab-)use of persistent localStorage may cause quite a lot of overhead in the browser as this is written down to disk. Probably not appropriate to use this class to send large or very frequent messages!

Uses Masquerade-js for Class implementation.

Basic Example (message sender):

    var queue = new localMessage();

    queue.postMessage("dial", number);

Basic Example (message receiver in another window):

    var queue = new localMessage();

    queue.receiveMessage("dial")
      .then((function(number){
        console.log('asked to dial '+number);
      }));

Both postMessage and receiveMessage return promises which resolve when a message is successfully received by the consumer. At present there are no circumstances that cause either the sender or receiver promise to reject (error). The message either gets received, it which case both sender and recipient are told, or it is lost silently. This is probably bad.

Additional Example (this() execution by sender on receipt):

    var queue = new localMessage();
    var message = { type:'new', priority:1, action:'fire'}

    queue.postMessage("doAction", message)
      .then((function(sent){
          console.log('receiver got message type: '+sent.value.type);
      }));

Class definition

localMessage

Kind: global class
Author: Rob Pickering [email protected]

new localMessage([prefix])

Param Type Description
[prefix] string unique namespace prefix for this instance of the message class in localStorage.

localMessage.postMessage(name, value) ⇒ Promise

Kind: static method of localMessage
Returns: Promise - a promise which resolves when the message is received by the consumer

Param Type Description
name string message name, used by receiving page to listen
value Object opaque object to pass to receiver

localMessage.receiveMessage(name) ⇒ Promise

Kind: static method of localMessage
Returns: Promise - a promise which resolves to the sent message object

Param Type Description
name string message name we want to listen for