SubscriptionDefinition

The SubscriptionDefinition constructor function returns an instance of a subscription - providing facilities around the callback subscribed to the specified channel & topic, as well as additional configuration options for the subscription's behavior. You create new instances of a SubscriptionDefinition by either calling the postal.subscribe method, or by calling subscribe on a ChannelDefinition instance.

Be sure to read What are Subscriptions? for more background information.

SubscriptionDefinition instance members

Member	Description
channel	The channel name (string)
topic	The topic (string) binding. It can be a wildcard or plain string topic.
callback	The function to be invoked when the subscription receives a message. The callback takes two arguments: callback(data, envelope), where data is the data published, and envelope is the full message involve which includes (at a minimum) channel, topic, timeStamp and data.

SubscriptionDefinition prototype members

Member	Description
after	allows you to add a custom "post-subscription-invocation" step which fires after every message has been processed. See Conduit Integration for more info.
before	allows you to add a custom "pre-subscription-invocation" step which fires before every message is processed. See Conduit Integration for more info.
catch	catch(function(err) { */do something with err */ }); - allows you to add an error handler that will be invoked if an exception is thrown in the subscription callback (this wraps the subscription callback invocation in a try/catch).
constraint	constraint( predicate ) where the predicate argument is a function that returns true if the callback should fire, or false if it should not. The predicate takes two args: predicate( data, envelope );
constraints	constraints( [ predicate1, predicate2 ] ) - same as constraint, except it takes an array of predicates, not just one.
context	context( context ) - where the context argument is the object which should be used as the "this" context when the callback is invoked.
debounce	debounce( interval ) - where the interval argument is the milliseconds interval to use for debouncing the subscription callback. A debounced subscription will not fire the callback until after the interval has elapsed. If new messages arrive before the interval has elapsed, it starts over.
defer	configuration method that causes the subscription callback to be fired only when the current stack has cleared. It's equivalent to setTimeout( callback, 0 );.
delay	delay( waitTime ) - where waitTime is the milliseconds interval to delay every callback invocation. This is equivalent to a setTimeout( callback, interval ).
disposeAfter	disposeAfter( num ) - where the num argument is an integer value indicating the number of times you want the subscription callback to be invoked before auto-unsubscribing.
distinct	configuration method that causes identical messages to be ignored, firing the callback only once new data is published.
distinctUntilChanged	configuration method that causes identical consecutive messages to be ignored, firing the callback only once new data is published.
logError	effectively calls catch under the hood and passes in a function that will console.warn (if possible) or console.log any exception thrown in the subscription callback.
once	configuration method that causes the subscription to unsubscribe after it receives one message.
subscribe	subscribe( callback ) - sets the callback function which gets invoked if the subscription receives a message. (The callback is normally provided as an argument to the SubscriptionDefinition constructor function, but this helper method is provided to allow the original callback to be changed out.)
throttle	throttle( interval ) - where the interval argument is an integer specifying a time interval in milliseconds during which the callback should only be fired once.
unsubscribe	method that removes the subscription from the message bus so that the callback will no longer be invoked.
withConstraint	[ Deprecated @0.11.0, prefer constraint ]
withConstraints	[ Deprecated @0.11.0, prefer constraints ]
withContext	[ Deprecated @0.11.0, prefer context ]
withDebounce	[ Deprecated @0.11.0, prefer debounce ]
withDelay	[ Deprecated @0.11.0, prefer delay ]
withThrottle	[ Deprecated @0.11.0, prefer throttle ]