Cable

@simple-ui/cable

Cable is a messaging utility focused on supporting complex (tree and graph) connections between user interface components. It supports the signal-slot paradigm for message passing.

Install

Install with npm.

npm install --save @simple-ui/cable

Install with bower.

bower install --save @simple-ui/cable

Lodash Dependency

This library requires a small set of lodash. Use lodash-modularize to limit how much of lodash is included in your project.

Quick Usage

import Cable from "@simple-ui/cable"

const cable = new Cable();

cable.channel('opened');
cable.channel('closed');

cable.closed.subscribe(function(a, b) {
  assert(a === 'info');
}).publish('info');

Usage

Cable Vocabulary

• Every Cable object is a signal (to publish with) and can add slots (to subscribe with)
• A Cable is Mediator
• Children connections to a Cable objects are defined with channel
• Graph connections to a Cable objects are defined with bridge
• A signal is created with channel
• A slot is registered with subscribe
• A message is sent with flood, emit, publish, or broadcast

Cable API

Initializing

A cable object is Mediator. It is a hub for messaging multiple events along channels.

const cable = new Cable();

The Cable object takes the following configuration properties.

| Property | Type | Default Value | Purpose | |:---------------|:------------|:--------------|:-----------------------------------------------------------| | asynchronous | boolean | true | All publish calls happen after the current stack has ended |

Channels

A Cable object is a signal which can have slots (methods to invoke) attached to it. Every channel defined on a Cable creates a new Cable with a channelName.

A Cable improves reliability because each exists as an object; there is less chance of a communication break down.

cable.channel('initialized');
cable.channel('opened');
cable.channel('closed');
assert(cable.closed instanceof Cable);

Cables can be built into communication hierarchies, so that published messages at the top of the communication tree propagate down or up the channel tree.

cable.channel('chat:send');
cable.channel('chat:startup');
cable.channel('chat:shutdown');
cable.channel('file/send');
cable.channel('file/startup');
cable.channel('file/shutdown');

The characters /, ., : can be used to split channel strings. Whichever you choose must be used through the entire channel string. You cannot define a channel with different split characters like a/b:c.d, but a.b.c.d or a:b:c:d or a/b/c/d.

Messaging

There are three directions messages can be passed in the hierarchy: everywhere, up, across, and down.

| Direction | Method | |:-----------|:------------| | Everywhere | flood | | Up | emit | | Across | publish | | Down | broadcast |

To invoke all subscribers that the cable has a hierarchical relationship with you would call:

cable.flood()     // invoke subscribers on all cables
cable.emit()      // invoke subscribers on parent cables
cable.publish()   // invoke subscribers on cable
cable.broadcast() // invoke subscribers on child cables

Publishing

Once a cable channel is defined we can publish messages. You can send as many parameters as needed.

cable.channel('opened');
cable.opened.publish('p1', 'p2');

If a channel hierarchy is defined, then it is important to understand the difference between publishing, emitting, and broadcasting.

We will define component validation events.

cable.channel('component:form:text:validate');
cable.channel('component:form:select:validate');
cable.channel('component:form:radio:validate');
cable.channel('component:form:checkbox:validate');

We can validate each component by looping over the types of form components.

_.each(cable.component.form, function(type) {
  type.validate.publish();
});

Broadcasting

While a publish will invoke all subscribes on a Cable, a broadcast will invoke all subscribers on all channels (i.e. children cables) on that cable, indefinitely.

The loop above which published to all validation methods could be re-written as the following with a broadcast.

cable.component.form.broadcast();

If we define four nested Cable objects (i.e. four channels) we can invoke each of these manually.

cable.channel('p1.p2.p3.p4');   // Equal(1)
cable.p1.publish('1');          // Equal(2)
cable.p1.p2.publish('1');       // Equal(3)
cable.p1.p2.p3.publish('1');    // Equal(3)
cable.p1.p2.p3.p4.publish('1'); // Equal(3)

We can accomplish the same with the following; notice that broadcast does not call the current cable's subscribers.

cable.channel('p1.p2.p3.p4');   // Equal(1)
cable.p1.publish('1');          // Equal(2)
cable.p1.broadcast('1');        // Equal(3)

Emitting

Emitting sends messages from a cable to all of it's parents, but similar to broadcasting it does not invoke subscribers on the Cable.

If we define four nested Cable objects (i.e. four channels) we can invoke each of these manually.

cable.channel('p1.p2.p3.p4');   // Equal(1)
cable.p1.publish('1');          // Equal(2)
cable.p1.p2.publish('1');       // Equal(2)
cable.p1.p2.p3.publish('1');    // Equal(2)
cable.p1.p2.p3.p4.publish('1'); // Equal(3)

We can accomplish the same with the following; notice that emit does not call the current cable's subscribers.

cable.channel('p1.p2.p3.p4');   // Equal(1)
cable.p1.p2.p3.p4.emit('1');    // Equal(2)
cable.p1.p2.p3.p4.publish('1'); // Equal(3)

Subscribing

We want to respond to messages sent. The subscribe object mirrors the publish object; every channel exists on the subscribe object.

cable.channel('closed');
cable.closed.subscribe(function(v) {
  assert(v === 1);
}).publish(1);

As many subscribers can be added to any channel. A subscription also works like slots, where the object and method are provided and not just a function.

const component = {
  onClosed() {}
};

cable.closed.subscribe(component, 'onClosed');
cable.closed.subscribe(component, component.onClosed);

A child subscriber will be called either by a direct publisher call or a parent broadcast.

cable.channel('component/select/closed');
cable.component.subscribe(function(v) { /* will be called */ });
cable.component.select.subscribe(function(v) { /* will be called */ });
cable.component.select.closed.subscribe(function(v) { /* will be called */ });
cable.component.publish('send to only components');
cable.component.broadcast.publish('send to all components and child channels');

Bridging

Bridging is a mechanism to create graphs of messaging inside of a cable or spanning multiple cables.

cable.channel('a.b.c.d');
cable.channel('w.x.y.z');

cable.bridge('a.b', 'w');

// this will call subscribers on a, a.b, w, w.x, w.x.y, w.x.y.z
cable.a.broadcast();

Two different cable objects can be bridged so messages in one will trigger subscribers in the other.

cable1.channel('a.b.c.d');
cable2.channel('w.x.y.z');

cable1.bridge('a.b', cable2.lookup('w.x'));

cable2.w.x.subscribe(function() { /* will be called */ });
cable1.a.b.publish();

Channels can be chained in graphs as well as tree structures.

cable1.channel('A');
cable2.channel('B');

cable1.bridge('A', cable2.B);
cable2.bridge('B', cable1.A);

cable2.B.subscribe(function() { /* will be called */ });
cable1.A.publish();

cable1.A.subscribe(function() { /* will be called */ });
cable2.B.publish();

Flooding

Flooding is a mechanism which invokes all subscribers on all cables, if a bridge is established the flood will spill over into that graph of cables.

cable.channel('A:B:C');
cable.channel('A:D:E');
cable.flood();

The flood would invoke each subscriber on each cable (A, B, C, D, E) in that order.

Tapping

A tap can be placed on Cable to debug or respond to all cable invocations. It is called for every cable involved in a signal method (publish, emit, broadcast, and flood).

Useful for debugging

Cable.tap(function(cable) {
  // all cables A through E will be called once on the flood
});
cable.channel('A:B:C');
cable.channel('A:D:E');
cable.flood();

License

MIT © mwjaworski

This software is released under the MIT license:

Copyright (c) 2017 mwjaworski [email protected]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.))