Venice JS

Manage your JS channels like a pro Venetian gondolier!

Installation

npm install --save @spindox/venice

Usage

Use venice instance in your application:

import venice from '@spindox/venice';

or create your own instance with the exported classes:

import { Venice, VeniceChannel } from '@spindox/venice';

Classes

VeniceChannel

A Venice channel.

An abstraction layer on top of js-channel instance.

Venice

Contains all Venice channels of the application.

VeniceChannel

A Venice channel.

An abstraction layer on top of js-channel instance.

Kind: global class

• VeniceChannel
  • new VeniceChannel(key, options)
  • .publish(topic, data, callback)
  • .subscribe(topic, handler)
  • .unsubscribe(topic)
  • .disconnect()

new VeniceChannel(key, options)

veniceChannel.publish(topic, data, callback)

Publishes a message related to the specified topic.

Kind: instance method of VeniceChannel

Example

const payload = { type: 'geolocation' };
channel.publish('event.hardware', payload, (err, data) => {
  if (err) return err;
  console.log('position', data);
});

veniceChannel.subscribe(topic, handler)

Subscribes a message handler for the specified topic.

Kind: instance method of VeniceChannel

Example

channel.subscribe('event.hardware', (data, tx) => {
  if (data.type === 'geolocation') {
    // async
    getCurrentPosition()
      .then((position) => {
        tx.complete(position);
      })
      .catch((ex) => {
        tx.error('fail', ex);
      });
      tx.delayReturn(true);
  } else {
    // sync
    return 'Sync data';
  }
});

veniceChannel.unsubscribe(topic)

Unsubscribes the handler for the specified topic.

Kind: instance method of VeniceChannel

Example

channel.unsubscribe('event.hardware');

veniceChannel.disconnect()

Destroys the channel

Kind: instance method of VeniceChannel
Example

channel.disconnect();

Venice

Contains all Venice channels of the application.

Kind: global class

• Venice
  • .channel(key, options) ⇒ object
  • .publish(params)
  • .subscribe(params)
  • .unsubscribe(params)
  • .disconnect(key)

venice.channel(key, options) ⇒ object

Creates a communication channel between the parent window and the iframe. If it's invoked without options, returns an existing channel.

Kind: instance method of Venice
Returns: object - - A VeniceChannel instance

Example

// Set Venice channel on parent
const channel = venice.channel('channel.sample', {
  window: iframe.contentWindow,
  onReady: () => {
    console.log('channel is ready!');
  },
});

Example

// Set Venice channel on iframe
const channel = venice.channel('channel.sample', {});

Example

// Get Venice channel
const channel = venice.channel('channel.sample');

venice.publish(params)

Publishes a message related to the specified topic on the specified channel.

Kind: instance method of Venice

Example

venice.publish({  
  channel: 'channel.sample',  
  topic: 'event.hardware',  
  data: { type: 'geolocation' },  
  callback: (err, data) => {  
    if (err) return err;  
    console.log('position', data);  
  });  
});  

venice.subscribe(params)

Subscribes a message handler for the specified topic on the specified channel.

Kind: instance method of Venice

Example

venice.subscribe({  
  channel: 'channel.sample',  
  topic: 'event.hardware',  
  handler: (data, tx) => {  
    if (data.type === 'geolocation') {  
      // async  
      getCurrentPosition()  
        .then((position) => {  
          tx.complete(position);  
        })  
        .catch((ex) => {  
          tx.error('fail', ex);  
        });  
        tx.delayReturn(true);  
    } else {  
      // sync  
      return 'Sync data';  
    }  
  }  
});  

venice.unsubscribe(params)

Unsubscribes the handler for the specified topic on the specified channel.

Kind: instance method of Venice

Example

venice.unsubscribe({
  channel: 'channel.sample',  
  topic: 'event.hardware',  
});

venice.disconnect(key)

Destroys the specified Venice channel.

Kind: instance method of Venice

Example

venice.disconnect('venice.channel');

Functions

SubscriptionHandler(data, transaction)

This method is invoked by the message topic listener. It receives data as the first argument.

If your implementation is asychronous, you'll have to use the transaction object that's automatically passed as the second argument.

Typedefs

ChannelOptions : object

Venice channel options.

By defaul window is equal to window.parent, origin is equal to *, and scope has the same value of key parameter.

VeniceCallback : function

This callback is invoked after that the subscribed listener received the message data, handled it, and, eventually, returned a response.

It's a node-style method, whit the error (or null) as the first argument and the response data as the second argument.

Transaction : object

Transaction object for asychronous implementations of message.

SubscriptionHandler(data, transaction)

This method is invoked by the message topic listener. It receives data as the first argument.

If your implementation is asychronous, you'll have to use the transaction object that's automatically passed as the second argument.

Kind: global function

ChannelOptions: object

Venice channel options.

By defaul window is equal to window.parent, origin is equal to *, and scope has the same value of key parameter.

Kind: global typedef
Properties

VeniceCallback: function

This callback is invoked after that the subscribed listener received the message data, handled it, and, eventually, returned a response.

It's a node-style method, whit the error (or null) as the first argument and the response data as the second argument.

Kind: global typedef

Transaction: object

Transaction object for asychronous implementations of message.

Kind: global typedef
Properties

Licence: MPL2.0

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.