A module for inter-object message passing.
Prerequisites
npm install --save phosphor-messaging
Prerequisites
git clone https://github.com/phosphorjs/phosphor-messaging.git
cd phosphor-messaging
npm install
Rebuild
npm run clean
npm run build
Follow the source build instructions first.
npm test
Follow the source build instructions first.
npm run docs
Navigate to docs/index.html
.
The runtime versions which are currently known to work are listed below. Earlier versions may also work, but come with no guarantees.
- Node 0.12.7+
- IE 11+
- Firefox 32+
- Chrome 38+
Follow the package install instructions first.
npm install --save-dev browserify
browserify myapp.js -o mybundle.js
Note: This module is fully compatible with Node/Babel/ES6/ES5. Simply omit the type declarations when using a language other than TypeScript.
Send a message to a message handler for immediate processing:
The sendMessage
function delivers the messages synchronously, for
immediate processing by the message handler.
import { IMessageHandler, Message, sendMessage } from 'phosphor-messaging';
class Handler implements IMessageHandler {
processMessage(msg: Message): void {
console.log(msg.type);
}
}
let handler = new Handler();
sendMessage(handler, new Message('one')); // logs 'one'
sendMessage(handler, new Message('two')); // logs 'two'
sendMessage(handler, new Message('three')); // logs 'three'
Post a message to a message handler for future processing:
The postMessage
function delivers the messages asynchronously, for
processing by the message handler on the next cycle of the event loop.
import { postMessage } from 'phosphor-messaging';
postMessage(handler, new Message('one'));
postMessage(handler, new Message('two'));
postMessage(handler, new Message('three'));
// sometime later: logs 'one', 'two', then 'three'.
Create custom messages which hold extra data:
class ValueMessage extends Message {
constructor(value: number) {
super('value');
this._value = value;
}
get value(): number {
return this._value;
}
private _value: number;
}
class ValueHandler extends Handler {
processMessage(msg: Message): void {
if (msg.type === 'value') {
console.log('value: ', (<ValueMessage>msg).value);
} else {
super.processMessage(msg);
}
}
}
let handler = new ValueHandler();
sendMessage(handler, new Message('one')); // logs 'one'
postMessage(handler, new Message('two'));
sendMessage(handler, new ValueMessage(42)); // logs 42
postMessage(handler, new ValueMessage(43));
// sometime later: logs 'two' then 43
Compress posted messages to reduce duplicate work:
import { Queue } from 'phosphor-queue';
class ExpensiveWorker extends Handler {
processMessage(msg: Message): void {
if (msg.type === 'expensive') {
console.log('do something expensive');
} else {
super.processMessage(msg);
}
}
compressMessage(msg: Message, pending: Queue<Message>): boolean {
if (msg.type === 'expensive') {
return pending.some(other => other.type === 'expensive');
}
return false;
}
}
let handler = new ExpensiveWorker();
postMessage(handler, new Message('one'));
postMessage(handler, new Message('expensive'));
postMessage(handler, new Message('two'));
postMessage(handler, new Message('expensive'));
postMessage(handler, new Message('expensive'));
postMessage(handler, new Message('three'));
postMessage(handler, new Message('expensive'));
// sometime later: logs 'one', 'do something expensive', 'two', then 'three'
Test for, and preemptively deliver, posted messages:
import { hasPendingMessages, sendPendingMessage } from 'phosphor-messaging';
postMessage(handler, new Message('one'));
postMessage(handler, new Message('two'));
postMessage(handler, new Message('three'));
hasPendingMessages(handler); // true
sendPendingMessage(handler); // logs 'one'
sendPendingMessage(handler); // logs 'two'
// sometime later: logs 'three'.
Install message filters to spy on or restrict message processing:
import {
IMessageFilter, installMessageFilter, removeMessageFilter
} from 'phosphor-messaging';
class MessageSpy implements IMessageFilter {
filterMessage(handler: IMessageHandler, msg: Message): boolean {
console.log('spy:', msg.type);
return false;
}
}
class FilterTwo implements IMessageFilter {
filterMessage(handler: IMessageHandler, msg: Message): boolean {
return msg.type === 'two';
}
}
let handler = new Handler();
let spy = new MessageSpy();
let filter = new FilterTwo();
sendMessage(handler, new Message('two')); // logs 'two'
installMessageFilter(handler, spy);
sendMessage(handler, new Message('two')); // logs 'spy: two', then 'two'
installMessageFilter(handler, filter);
sendMessage(handler, new Message('two')); // logs nothing
installMessageFilter(handler, spy);
sendMessage(handler, new Message('two')); // logs 'spy: two'
removeMessageFilter(handler, filter);
sendMessage(handler, new Message('two')); // logs 'spy: two', 'spy: two', then 'two'
removeMessageFilter(handler, spy);
sendMessage(handler, new Message('two')); // logs 'two'
Clear all message data associated with a handler:
import { clearMessageData } from 'phosphor-messaging';
// clear everything - posted messages *and* filters
clearMessageData(handler);