npm package: @simple-ui/cable
Description: Cable is a messaging utility with tree and graph message broadcasting combining the centricity of mediators with the semantic protections of signal-slot.
Author: Michael Jaworski
Latest version: 1.1.3

# Cable

[![Coverage Status](https://coveralls.io/repos/github/simple-ui/cable/badge.svg?branch=master)](https://coveralls.io/github/simple-ui/cable?branch=master)
[![Build Status](https://travis-ci.org/simple-ui/cable.svg?branch=master)](https://travis-ci.org/simple-ui/cable)
[![Dependency Status](https://david-dm.org/simple-ui/cable.svg)](https://david-dm.org/simple-ui/cable.svg?style=flat-square)
[![npm version](https://badge.fury.io/js/@simple-ui/cable.svg)](https://badge.fury.io/js/@simple-ui/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.

```sh
npm install --save @simple-ui/cable
```

Install with bower.

```sh
bower install --save @simple-ui/cable
```

### Lodash Dependency

This library requires a small set of lodash. Use [lodash-modularize](https://www.npmjs.com/package/lodash-modularize) to limit how much of lodash is included in your project.

## Quick Usage

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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:

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
_.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`.

```javascript
cable.component.form.broadcast();
```

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

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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

```javascript
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](http://simple-ui.io)

This software is released under the MIT license:

Copyright (c) 2017 mwjaworski mjaworski@acm.org

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.))