114 lines
3.9 KiB
Markdown
114 lines
3.9 KiB
Markdown
|
# Ultron
|
||
|
|
|
||
|
|
[](http://unshift.io)[](http://browsenpm.org/package/ultron)[](https://travis-ci.org/unshiftio/ultron)[](https://david-dm.org/unshiftio/ultron)[](https://coveralls.io/r/unshiftio/ultron?branch=master)[](http://webchat.freenode.net/?channels=unshift)
|
||
|
|
|
||
|
|
Ultron is a high-intelligence robot. It gathers intelligence so it can start
|
||
|
|
improving upon his rudimentary design. It will learn your event emitting
|
||
|
|
patterns and find ways to exterminate them. Allowing you to remove only the
|
||
|
|
event emitters that **you** assigned and not the ones that your users or
|
||
|
|
developers assigned. This can prevent race conditions, memory leaks and even file
|
||
|
|
descriptor leaks from ever happening as you won't remove clean up processes.
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
The module is designed to be used in browsers using browserify and in Node.js.
|
||
|
|
You can install the module through the public npm registry by running the
|
||
|
|
following command in CLI:
|
||
|
|
|
||
|
|
```
|
||
|
|
npm install --save ultron
|
||
|
|
```
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
In all examples we assume that you've required the library as following:
|
||
|
|
|
||
|
|
```js
|
||
|
|
'use strict';
|
||
|
|
|
||
|
|
var Ultron = require('ultron');
|
||
|
|
```
|
||
|
|
|
||
|
|
Now that we've required the library we can construct our first `Ultron` instance.
|
||
|
|
The constructor requires one argument which should be the `EventEmitter`
|
||
|
|
instance that we need to operate upon. This can be the `EventEmitter` module
|
||
|
|
that ships with Node.js or `EventEmitter3` or anything else as long as it
|
||
|
|
follow the same API and internal structure as these 2. So with that in mind we
|
||
|
|
can create the instance:
|
||
|
|
|
||
|
|
```js
|
||
|
|
//
|
||
|
|
// For the sake of this example we're going to construct an empty EventEmitter
|
||
|
|
//
|
||
|
|
var EventEmitter = require('events').EventEmitter; // or require('eventmitter3');
|
||
|
|
var events = new EventEmitter();
|
||
|
|
|
||
|
|
var ultron = new Ultron(events);
|
||
|
|
```
|
||
|
|
|
||
|
|
You can now use the following API's from the Ultron instance:
|
||
|
|
|
||
|
|
### Ultron.on
|
||
|
|
|
||
|
|
Register a new event listener for the given event. It follows the exact same API
|
||
|
|
as `EventEmitter.on` but it will return itself instead of returning the
|
||
|
|
EventEmitter instance. If you are using EventEmitter3 it also supports the
|
||
|
|
context param:
|
||
|
|
|
||
|
|
```js
|
||
|
|
ultron.on('event-name', handler, { custom: 'function context' });
|
||
|
|
```
|
||
|
|
|
||
|
|
Just like you would expect, it can also be chained together.
|
||
|
|
|
||
|
|
```js
|
||
|
|
ultron
|
||
|
|
.on('event-name', handler)
|
||
|
|
.on('another event', handler);
|
||
|
|
```
|
||
|
|
|
||
|
|
### Ultron.once
|
||
|
|
|
||
|
|
Exactly the same as the [Ultron.on](#ultronon) but it only allows the execution
|
||
|
|
once.
|
||
|
|
|
||
|
|
Just like you would expect, it can also be chained together.
|
||
|
|
|
||
|
|
```js
|
||
|
|
ultron
|
||
|
|
.once('event-name', handler, { custom: 'this value' })
|
||
|
|
.once('another event', handler);
|
||
|
|
```
|
||
|
|
|
||
|
|
### Ultron.remove
|
||
|
|
|
||
|
|
This is where all the magic happens and the safe removal starts. This function
|
||
|
|
accepts different argument styles:
|
||
|
|
|
||
|
|
- No arguments, assume that all events need to be removed so it will work as
|
||
|
|
`removeAllListeners()` API.
|
||
|
|
- 1 argument, when it's a string it will be split on ` ` and `,` to create a
|
||
|
|
list of events that need to be cleared.
|
||
|
|
- Multiple arguments, we assume that they are all names of events that need to
|
||
|
|
be cleared.
|
||
|
|
|
||
|
|
```js
|
||
|
|
ultron.remove('foo, bar baz'); // Removes foo, bar and baz.
|
||
|
|
ultron.remove('foo', 'bar', 'baz'); // Removes foo, bar and baz.
|
||
|
|
ultron.remove(); // Removes everything.
|
||
|
|
```
|
||
|
|
|
||
|
|
If you just want to remove a single event listener using a function reference
|
||
|
|
you can still use the EventEmitter's `removeListener(event, fn)` API:
|
||
|
|
|
||
|
|
```js
|
||
|
|
function foo() {}
|
||
|
|
|
||
|
|
ultron.on('foo', foo);
|
||
|
|
events.removeListener('foo', foo);
|
||
|
|
```
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
MIT
|