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.

Kind: global class

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

new VeniceChannel(key, options)

| Param | Type | Description | | --- | --- | --- | | key | string | The channel identifier | | options | ChannelOptions | The channel configuration options |

veniceChannel.publish(topic, data, callback)

Publishes a message related to the specified topic.

Kind: instance method of VeniceChannel

Param | Type | Description --- | --- | --- topic | string | The message topic data | * | Data to be sent to the other window. The data is serialized using the structured clone algorithm. This means you can pass a broad variety of data objects safely to the destination window without having to serialize them yourself callback | VeniceCallback | The message publication callback

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

| Param | Type | Description | | --- | --- | --- | | topic | string | The message topic | | handler | SubscriptionHandler | The message handler |

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

| Param | Type | Description | | --- | --- | --- | | topic | string | The message topic |

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

| Param | Type | Default | Description | | --- | --- | --- | --- | | key | string | | The channel identifier | | options | ChannelOptions | | The channel configuration options |

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

| Param | Type | Description | | --- | --- | --- | | params | object | | | params.channel | string | The Venice channel identifier | | params.topic | string | The message topic | | params.data | * | Data to be sent to the other window. The data is serialized using the structured clone algorithm. This means you can pass a broad variety of data objects safely to the destination window without having to serialize them yourself | | params.callback | VeniceCallback | The message publication callback |

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

| Param | Type | Description | | --- | --- | --- | | params | object | | | params.channel | string | The Venice channel identifier | | params.topic | string | The message topic | | params.handler | SubscriptionHandler | The message handler |

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

| Param | Type | Description | | --- | --- | --- | | params | object | | | params.channel | string | The Venice channel identifier | | params.topic | string | The message topic |

Example

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

venice.disconnect(key)

Destroys the specified Venice channel.

Kind: instance method of Venice

| Param | Type | Description | | --- | --- | --- | | key | string | The Venice channel identifier |

Example

venice.disconnect('venice.channel');

Functions

Typedefs

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

| Param | Type | Description | | --- | --- | --- | | data | * | The message data | | transaction | Transaction | The transaction object |

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

| Name | Type | Description | | --- | --- | --- | | window | element | A reference to the window to communicate with | | origin | string | Specifies what the origin of other window must be for the event to be dispatched | | scope | string | All messages will be safely tucked under the namespace you provide. If omitted, it's equal to the channel key | | onReady | function | Callback called once actual communication has been established between the parent page and child frame. If the child frame hadn't set up its end of the channel, for instance, onReady would never get called |

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

| Param | Type | | --- | --- | | error | string | | result | * |

Transaction: object

Transaction object for asychronous implementations of message.

Kind: global typedef
Properties

| Name | Type | Description | | --- | --- | --- | | complete | function | Resolves transaction with data passed as argument | | completed | function | | | delayReturn | function | Indicates that the handler implementation is asynchronous | | error | function | Rejects transaction with error (code and message) passed as argument. e.g. tx.error('mega_fail', 'I could not get your stuff.'); | | invoke | function | | | origin | string | Contains the origin of the message |

##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/.