BlueGit

blue-star danique-bot

Files

danique-bot / node_modules / ultron / README.md

README.md

Import template
timfa Tim · pushed by timfa · 4 years ago
c788ad20 History
README.md 3.6 KiB Download Raw

Ultron

Made by unshiftVersion npmBuild StatusDependenciesCoverage StatusIRC channel

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:

'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:

//
// 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:

ultron.on('event-name', handler, { custom: 'function context' });

Ultron.once

Exactly the same as the Ultron.on but it only allows the execution once.

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.

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:

function foo() {}

ulton.on('foo', foo);
events.removeListener('foo', foo);

License

MIT

Source
1# Ultron
2
3[![Made by unshift](https://img.shields.io/badge/made%20by-unshift-00ffcc.svg?style=flat-square)](http://unshift.io)[![Version npm](http://img.shields.io/npm/v/ultron.svg?style=flat-square)](http://browsenpm.org/package/ultron)[![Build Status](http://img.shields.io/travis/unshiftio/ultron/master.svg?style=flat-square)](https://travis-ci.org/unshiftio/ultron)[![Dependencies](https://img.shields.io/david/unshiftio/ultron.svg?style=flat-square)](https://david-dm.org/unshiftio/ultron)[![Coverage Status](http://img.shields.io/coveralls/unshiftio/ultron/master.svg?style=flat-square)](https://coveralls.io/r/unshiftio/ultron?branch=master)[![IRC channel](http://img.shields.io/badge/IRC-irc.freenode.net%23unshift-00a8ff.svg?style=flat-square)](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