Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/knalli/angular-vertxbus
AngularJS 1.x service wrapper for the Vert.x Event Bus
https://github.com/knalli/angular-vertxbus
angularjs babeljs cdnjs javascript messaging vertx vertxbus
Last synced: 42 minutes ago
JSON representation
AngularJS 1.x service wrapper for the Vert.x Event Bus
- Host: GitHub
- URL: https://github.com/knalli/angular-vertxbus
- Owner: knalli
- License: mit
- Archived: true
- Created: 2013-12-15T02:55:12.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2019-06-13T21:56:45.000Z (over 5 years ago)
- Last Synced: 2025-01-14T18:48:53.999Z (7 days ago)
- Topics: angularjs, babeljs, cdnjs, javascript, messaging, vertx, vertxbus
- Language: JavaScript
- Homepage: https://knalli.github.io/angular-vertxbus.docs/docs/
- Size: 5.16 MB
- Stars: 79
- Watchers: 10
- Forks: 24
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# angular-vertxbus
 [](https://www.npmjs.com/package/angular-vertxbus) [](https://cdnjs.com/libraries/angular-vertxbus) [](https://travis-ci.org/knalli/angular-vertxbus) [](https://saucelabs.com/u/angular-vertxbus) [](http://gruntjs.com/) [](https://greenkeeper.io/)
Client side library using VertX Event Bus as an Angular Service module
## Status
| Branch | Stability | Status |
| --- | --- | --- |
| Canary | unstable | [](https://travis-ci.org/knalli/angular-vertxbus) |
| Master | stable | [](https://travis-ci.org/knalli/angular-vertxbus) |
Automatic tests running against the latest version of the major browsers:
[](https://saucelabs.com/)
## How to get
Either download it manually or install it automatically with Bower `bower install -D angular-vertxbus` or npm `npm install -D angular-vertxbus`.
Then only import `dist/angular-vertxbus.js` or `dist/angular-vertxbus.min.js`. The file itself comes with a CJS header.
Alternatively you can use the cdnjs: [cdnjs.com/libraries/angular-vertxbus](https://cdnjs.com/libraries/angular-vertxbus).
## Dependencies
### JavaScript (Polyfill)
The source code is written using newer JavaScript ([ECMAScript 2015+](https://babeljs.io/learn-es2015/))and is using the JavaScript transpiler [BabelJS](https://babeljs.io).
Depending on your target clients, you probably need to include a browser polyfill (for ES5 clients). BabelJS itself
recommends the [requirement of its own polyfill](https://babeljs.io/docs/usage/polyfill/). Either you use the explained
way using npm modules and/or browserify, or you can use the alternative artifact variant `dist/angular-vertxbus.withpolyfill.js`.
### AngularJS 1.x
This library performs integration tests for *AngularJS 1.2 - 1.6*!
### Vert.x
This library is being developed against the `eventbus.js` from Vert.x 3.
## How to use
### API
An [Api Documentation](https://knalli.github.io/angular-vertxbus.docs/docs/#/api/knalli.angular-vertxbus) is available.
### Quick start
You have to define the module dependency, this module is named `knalli.angular-vertxbus`.
```javascript
angular.module('app', ['knalli.angular-vertxbus'])
.controller('MyCtrl', function(vertxEventBus, vertxEventBusService) {
// using the EventBus directly
vertxEventBus.send('my.address', {data: 123});
// using the service
vertxEventBusService.send('my.address', {data: 123})
});
```
### Consume messages
```javascript
vertxEventBusService.on('myaddress', function(err, message) {
console.log('Received a message: ', message);
});
```
### Publish a message
```javascript
vertxEventBusService.publish('myaddress', {data: 123});
```
### Send a message
```javascript
vertxEventBusService.send('myaddress', {data: 123})
.then(function(reply) {
console.log('A reply received: ', reply);
})
.catch(function() {
console.warn('No message');
});
// The "No reply message found" is controlled via a timeout (default 10000ms)
vertxEventBusService.send('myaddress', {data: 123}, {timeout: 3000})
.then(function(reply) {
console.log('A reply received: ', reply);
})
.catch(function() {
console.warn('No message within 3 seconds');
});
// If the reply is an error, this will be the payload
vertxEventBusService.send('myaddress', {data: 123})
.then(function(reply) {
console.log('A reply received: ', reply);
})
.catch(function(err) {
console.warn(err);
});
```
## Advanced configuration
The module has some advanced configuration options. Perhaps you do not have to change them, but at least you should know them!
Each module configuration option must be defined in the `run` phase, i.e.:
```javascript
angular.module('app', ['knalli.angular-vertxbus'])
.config(function(vertxEventBusProvider) {
vertxEventBusProvider
.enable()
.useReconnect()
.useUrlServer('http://live.example.org:8888');
});
```
Please have a look at the API documentation for [vertxEventBusProvider](https://knalli.github.io/angular-vertxbus.docs/docs/#/api/knalli.angular-vertxbus.vertxEventBusProvider)
and [vertxEventBusServiceProvider](https://knalli.github.io/angular-vertxbus.docs/docs/#/api/knalli.angular-vertxbus.vertxEventBusServiceProvider) for further options.
## Architecture details
The module contains two items: the stub holder `vertxEventBus` for the Vert.x EventBus and a more comfortbale high level service `vertxEventBusService`.
*The stub* is required because the Vert.x Event Bus cannot handle a reconnect. The reason is the underlaying SockJS which cannot handle a reconnect, too. A reconnect means to create a new instance of `SockJS`, therefore a new instance of `EventBus`. The stub ensures only one single instance exists. Otherwise a global module was not possible.
More or less the stub supports the same API calls like the original `EventBus`.
Based on the stub, the *high level service* `vertxEventBusService` detects disconnects, handles reconnects and ensures re-registrations of subscriptions. Furthermore, the service provides some neat aliases for the usage of handlers.
```javascript
// Same as EventBus.registerHandler()
service.registerHandler('myaddress', callback);
service.on('myaddress', callback);
service.addListener('myaddress', callback);
// Same as EventBus.unregisterHandler()
service.unregisterHandler('myaddress', callback);
service.un('myaddress', callback);
service.removeListener('myaddress', callback);
// Same as EventBus.send()
service.send('myaddress', data)
// Same as EventBus.publish
service.publish('myaddress', data)
service.emit('myaddress', data)
// Same as EventBus.readyState()
service.readyState()
```
In addition to this, when sending a message with an expected reply:
```javascript
// Same as EventBus.send() but with a promise
service.send('myaddress', data)
.then(function(reply) {})
.catch(function(err) {})
```
For each connect or disconnect, a global broadcast will be emitted (on `$rootScope` with `'vertx-eventbus.system.connected'`, `'vertx-eventbus.system.disconnected'`)
## Tests
### Unit tests
Note: Check that dependencies are be installed (`npm install`).
The *unit tests* are available with `npm test` which is actually a shortcut for `grunt test`. It performs tests under the current primary target version of AngularJS. Use `npm run test-scopes` for testing other scoped versions as well.
### Local test environment
Note: Check that dependencies are be installed (`npm install`).
The *local test environment* starts and utilizes a full Vert.x node and a NodeJS based web server.
**Easy:** Just run `npm run -s start-server` and open `http://localhost:3000/` in your preferred browser.
If you have changed something, just invoke `npm run -s compile` in parallel and refresh the browser.
Alternatively:
1. `npm run install-it-vertx-server` downloads and installs a Vert.x locally. This will store a cached download artifact at `test/e2e//vertx/`.
2. `npm run start-it-vertx-server` starts an Vert.x on port `8080`.
3. `npm run start-it-web-server` starts a web server on port `3000`.
4. Ensure at least `npm run -s compile` has been invoked so there is a `dist/angular-vertxbus.js`.
5. Open http://localhost:3000/ in your browser.
## License
Copyright 2017 by Jan Philipp. Licensed under MIT.