vanage v1.6.0
Handling events in the microservice way without any dependencies in a really compact format - only 16.6KB (54.5KB unminified) - for the Browser and Node.js applications. Vanage is a fully transparent open-source framework, offering you that you can review and check the code coverage or even the code quality before you use it in production. It also benefits from continous development and improvements, if you are interested to make vanage better simply create a new pull request on this GitHub repository.
Installation
You can install this package via bower if you're using it in your client or via NPM to use it
on your server-side. If you're planning to use it on your server and the client install the module
via NPM to ensure you have the dist folder and the whole modular structure.
npm install --save vanage
bower install --save vanageIf you want to install a specific version, take a look at the tags in this repository.
Compatibility
| IE | Chrome | Firefox | Opera | Safari | Node.js | io.js |
|---|---|---|---|---|---|---|
| 8+ | 5+ | 4.0+ | 12+ | 5+ | 4 | n.a. |
n.a. means not available or not tested yet
If you want to use it in a browser which isn't supported by the module itself, you can add the polyfill from polyfill.io with the small HTML snippet below.
<!doctype html>
<html>
<head></head>
<body>
...
<!-- content -->
<script src="https://cdn.polyfill.io/v2/polyfill.min.js"></script>
<script src="/vendor/vanage/dist/vanage.min.js"></script>
</body>
</html>ToDo's
- Adding the method API to Readme
- Create API docs out of the Readme content
- Adding async possibility to all methods
- Check compatibility with Node.js v5 and v6
- Improve code quality and test coverage
Usage
You can try vanage in your browser with a live example with Tonic Dev
const Manager = Vanage.create({
debug: true
});
Manager.register({
role: 'user',
action: 'create'
}, (args, done) => {
if(args.permission = 'allowed') {
/* do some stuff with args.data ... */
return done();
}
done(new Error('Access denied'));
});
let permission = $.get('/api/v1/getPermission');
Manager.act({
role: 'user',
action: 'create'
}, {
permission: await permission,
data: { /* user data */ }
}, err => {
if(err) {
alert(err.message);
return false;
}
alert('User created!');
});API
Vanage
Properties
Cache
Represents the Cache class, new instances can be created by using the new keyword. If you want to learn more about the vanage cache, take a look at the cache chapter itself down below.
Service
The Barebone class which will be instanciated with the create method. Be careful if you create
instances via direct access. We recommend use the create method to create new vanage instances!
Methods
create
Creates a new service with a pair of (default-) options for you and provides you the whole API presented in the example above.
Service
Methods
register
service.register(endpoint: Object, handler: Function): SignatureRegisters a new endpoint for an actor or arbitrator, specified by a certain factory and internal signature.
| Number | Parameter | Type | Signature | |
|---|---|---|---|---|
| 1 | params | Object | - | |
| 2 | done | Function | (error: Error | null, result?: Any) |
| 3 | delegate | Function | (target: Object, data?: Any, done?: Function) |
service.register({
any: 'key',
to: 'identify'
}, (params, done, delegate) => {
return done(null, params);
});unregister
Will unregister a specific endpoint by passing a signature object into the unregister method. A signature can be received by the register method. It will return a boolean which represents the internal result of the method, while true means the unregistration process was successfull and false means there was no handler or delegate found with this signature.
| Number | Parameter | Type |
|---|---|---|
| 1 | sign | Signature |
var sign = service.register({}, /* ... */);
service.unregister(sign);delegate
service.delegate(target: Object, delegator: Function): SignatureThe delegate is a kind of forwarder or job-taker (you could take a look at the iOS development strategy). With this tiny function events will be delegated from an endpoint to another endpoint, while saving your passed data hierarchically.
service.delegate({
any: 'key'
}, (delegate, data) => {
delegate({ module: 'error' }, { any: 'data' });
});
/**
* The error module will receive the following data:
* { any: 'data', __delegate__: { ... original data ... } }
*/ act
service.act(target: Object, data: Object, done?: Function, settings?: Object): SignatureExecutes a certain factory and handles the result of the registered process. You can also delegate to another target, for example depending on the result.
| Number | Parameter | Type | Signature |
|---|---|---|---|
| 1 | err | Any | - |
| 2 | results | Any | - |
| 3 | delegate | Function | (target: Object, data?: Any, done?: Function) |
service.act({
any: 'key',
to: 'identify'
}, (err, results, delegate) => {
if(err) {
return delegate({
handle: 'error'
}, { failed: err });
}
$.get(results.apiUrl + '/users', res => {
// do something with the results
});
});actOnce
service.actOnce(target: Object, data: Object, done?: Function): Signaturequeue
service.queue(items: [], autorun?: boolean): Queue
delay
waitFor
service.waitFor(sign: Signature, handler?: Function): voidCache
Properties
size
Counts the current item size of the internal cache list.
entries
Get all keys of the unique cache factory.
Methods
set
Set a new key-value pair for caching.
unset
Remove a key-value pair from the cache.
get
Get the value of a key matching the key in the cache.
flush
Delete the whole in-memory cache.
dump
Get the whole cache object in key-value format.
isDirty
If the cache is dirty, means if something has changed in the cache itself.
Pattern
Properties
id
signature
Methods
match
Signature
Properties
identifier
identifierKeys
unique
value
Methods
match
Queue
Properties
size
Get the amount of actions which has been registred at the initialization part of the queue. This property is represtend in an numeral integer value.
Methods
run
queue.run(callback?: Function): Boolean