postal.linkChannels

postal.linkChannels

NOTE: As of postal v0.11.0, linkChannels was extracted to live in a postal add-on: postal.linked-channels. We'll keep this information here, but be aware you'll need to include this add-on if you want this behavior and are using postal v0.11 or greater.

description: creates one-to-one, one-to-many or many-to-many links between channels, so that messages sent to a source channel are forwarded to the linked channels.

returns: an array of SubscriptionDefinition objects, each one representing a linked channel.

Background

Sometimes - when it comes to abstracting 3rd party modules - you're faced with the choice of taking a hard dependency on a message you can't control, or adding a thin layer of abstraction by creating a custom message using the channel and/or topic you prefer. Use this option with great care, as it can and will obfuscate visibility into the message bus - but it's here for you when you're in a pinch...

postal.linkChannels( source, destination );

• source - an object (or an array of objects) that contains:
  • topic - (required) a topic string
  • channel - (optional) a channel name (string). Uses DEFAULT_CHANNEL if not provided.
• destination - an object (or an array of objects) that contains:
  • topic - (optional) a topic string OR a function which takes the source message's topic as an argument and returns a string value to be used as the new topic.
  • channel - (optional) a channel name (string). Uses DEFAULT_CHANNEL if not provided.

Example Usage:

// forwards any messages on the "greeting" channel, with a topic of "say.hello"
// to the "salutations" channel, keeping the same topic
var links = postal.linkChannels(
    { channel: "greeting", topic: "say.hello"},
    { channel: "salutations" }
);

// forwards any messages on the "greeting" channel, with a topic of "say.hello"
// to the "salutations" channel, with a new topic "say.hi"
var links = postal.linkChannels(
    { channel: "greeting", topic: "say.hello"},
    { channel: "salutations", topic: "say.hi" }
);

// forwards any messages on the "greeting" channel, with a topic of "say.hello"
// to the "salutations" channel, with a new topic determined by time of day
var links = postal.linkChannels(
    { channel: "greeting", topic: "say.hello"},
    {
        channel: "salutations",
        topic: function() {
            return (new Date()).getAMPM() === "PM" ?
                "say.good.evening" :
                "say.good.morning"
        }
    }
);