README.md (3707B)
1# Ultron 2 3[](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) 4 5Ultron is a high-intelligence robot. It gathers intelligence so it can start 6improving upon his rudimentary design. It will learn your event emitting 7patterns and find ways to exterminate them. Allowing you to remove only the 8event emitters that **you** assigned and not the ones that your users or 9developers assigned. This can prevent race conditions, memory leaks and even file 10descriptor leaks from ever happening as you won't remove clean up processes. 11 12## Installation 13 14The module is designed to be used in browsers using browserify and in Node.js. 15You can install the module through the public npm registry by running the 16following command in CLI: 17 18``` 19npm install --save ultron 20``` 21 22## Usage 23 24In all examples we assume that you've required the library as following: 25 26```js 27'use strict'; 28 29var Ultron = require('ultron'); 30``` 31 32Now that we've required the library we can construct our first `Ultron` instance. 33The constructor requires one argument which should be the `EventEmitter` 34instance that we need to operate upon. This can be the `EventEmitter` module 35that ships with Node.js or `EventEmitter3` or anything else as long as it 36follow the same API and internal structure as these 2. So with that in mind we 37can create the instance: 38 39```js 40// 41// For the sake of this example we're going to construct an empty EventEmitter 42// 43var EventEmitter = require('events').EventEmitter; // or require('eventmitter3'); 44var events = new EventEmitter(); 45 46var ultron = new Ultron(events); 47``` 48 49You can now use the following API's from the Ultron instance: 50 51### Ultron.on 52 53Register a new event listener for the given event. It follows the exact same API 54as `EventEmitter.on` but it will return itself instead of returning the 55EventEmitter instance. If you are using EventEmitter3 it also supports the 56context param: 57 58```js 59ultron.on('event-name', handler, { custom: 'function context' }); 60``` 61 62### Ultron.once 63 64Exactly the same as the [Ultron.on](#ultronon) but it only allows the execution 65once. 66 67### Ultron.remove 68 69This is where all the magic happens and the safe removal starts. This function 70accepts different argument styles: 71 72- No arguments, assume that all events need to be removed so it will work as 73 `removeAllListeners()` API. 74- 1 argument, when it's a string it will be split on ` ` and `,` to create a 75 list of events that need to be cleared. 76- Multiple arguments, we assume that they are all names of events that need to 77 be cleared. 78 79```js 80ultron.remove('foo, bar baz'); // Removes foo, bar and baz. 81ultron.remove('foo', 'bar', 'baz'); // Removes foo, bar and baz. 82ultron.remove(); // Removes everything. 83``` 84 85If you just want to remove a single event listener using a function reference 86you can still use the EventEmitter's `removeListener(event, fn)` API: 87 88```js 89function foo() {} 90 91ulton.on('foo', foo); 92events.removeListener('foo', foo); 93``` 94 95## License 96 97MIT