www.aleph1.co.uk Git - yaffs-website/blob - node_modules/eventemitter2/README.md

   1 [![build-status](https://www.codeship.io/projects/3ad58940-4c7d-0131-15d5-5a8cd3f550f8/status)](https://www.codeship.io/projects/11259)
   2
   3 # SYNOPSIS
   4
   5 EventEmitter2 is an implementation of the EventEmitter found in Node.js
   6
   7 # DESCRIPTION
   8
   9 ### FEATURES
  10  - Namespaces/Wildcards.
  11  - Times To Listen (TTL), extends the `once` concept with `many`.
  12  - Browser environment compatibility.
  13  - Demonstrates good performance in benchmarks
  14
  15 ```
  16 EventEmitterHeatUp x 3,728,965 ops/sec \302\2610.68% (60 runs sampled)
  17 EventEmitter x 2,822,904 ops/sec \302\2610.74% (63 runs sampled)
  18 EventEmitter2 x 7,251,227 ops/sec \302\2610.55% (58 runs sampled)
  19 EventEmitter2 (wild) x 3,220,268 ops/sec \302\2610.44% (65 runs sampled)
  20 Fastest is EventEmitter2
  21 ```
  22
  23 ### Differences (Non breaking, compatible with existing EventEmitter)
  24
  25  - The constructor takes a configuration object.
  26
  27 ```javascript
  28     var EventEmitter2 = require('eventemitter2').EventEmitter2;
  29     var server = new EventEmitter2({
  30
  31       //
  32       // use wildcards.
  33       //
  34       wildcard: true,
  35
  36       //
  37       // the delimiter used to segment namespaces, defaults to `.`.
  38       //
  39       delimiter: '::',
  40
  41       //
  42       // if you want to emit the newListener event set to true.
  43       //
  44       newListener: false,
  45
  46       //
  47       // max listeners that can be assigned to an event, default 10.
  48       //
  49       maxListeners: 20
  50     });
  51 ```
  52
  53  - Getting the actual event that fired.
  54
  55 ```javascript
  56     server.on('foo.*', function(value1, value2) {
  57       console.log(this.event, value1, value2);
  58     });
  59 ```
  60
  61  - Fire an event N times and then remove it, an extension of the `once` concept.
  62
  63 ```javascript
  64     server.many('foo', 4, function() {
  65       console.log('hello');
  66     });
  67 ```
  68
  69  - Pass in a namespaced event as an array rather than a delimited string.
  70
  71 ```javascript
  72     server.many(['foo', 'bar', 'bazz'], function() {
  73       console.log('hello');
  74     });
  75 ```
  76
  77
  78 # API
  79
  80 When an `EventEmitter` instance experiences an error, the typical action is
  81 to emit an `error` event. Error events are treated as a special case.
  82 If there is no listener for it, then the default action is to print a stack
  83 trace and exit the program.
  84
  85 All EventEmitters emit the event `newListener` when new listeners are
  86 added.
  87
  88
  89 **Namespaces** with **Wildcards**
  90 To use namespaces/wildcards, pass the `wildcard` option into the EventEmitter
  91 constructor. When namespaces/wildcards are enabled, events can either be
  92 strings (`foo.bar`) separated by a delimiter or arrays (`['foo', 'bar']`). The
  93 delimiter is also configurable as a constructor option.
  94
  95 An event name passed to any event emitter method can contain a wild card (the
  96 `*` character). If the event name is a string, a wildcard may appear as `foo.*`.
  97 If the event name is an array, the wildcard may appear as `['foo', '*']`.
  98
  99 If either of the above described events were passed to the `on` method,
 100 subsequent emits such as the following would be observed...
 101
 102 ```javascript
 103    emitter.emit('foo.bazz');
 104    emitter.emit(['foo', 'bar']);
 105 ```
 106
 107
 108 ### emitter.addListener(event, listener)
 109 ### emitter.on(event, listener)
 110
 111 Adds a listener to the end of the listeners array for the specified event.
 112
 113 ```javascript
 114     server.on('data', function(value1, value2, value3, ...) {
 115       console.log('The event was raised!');
 116     });
 117 ```
 118
 119 ```javascript
 120     server.on('data', function(value) {
 121       console.log('The event was raised!');
 122     });
 123 ```
 124
 125 ### emitter.onAny(listener)
 126
 127 Adds a listener that will be fired when any event is emitted.
 128
 129 ```javascript
 130     server.onAny(function(value) {
 131       console.log('All events trigger this.');
 132     });
 133 ```
 134
 135 ### emitter.offAny(listener)
 136
 137 Removes the listener that will be fired when any event is emitted.
 138
 139 ```javascript
 140     server.offAny(function(value) {
 141       console.log('The event was raised!');
 142     });
 143 ```
 144
 145 #### emitter.once(event, listener)
 146
 147 Adds a **one time** listener for the event. The listener is invoked
 148 only the first time the event is fired, after which it is removed.
 149
 150 ```javascript
 151     server.once('get', function (value) {
 152       console.log('Ah, we have our first value!');
 153     });
 154 ```
 155
 156 ### emitter.many(event, timesToListen, listener)
 157
 158 Adds a listener that will execute **n times** for the event before being
 159 removed. The listener is invoked only the first **n times** the event is
 160 fired, after which it is removed.
 161
 162 ```javascript
 163     server.many('get', 4, function (value) {
 164       console.log('This event will be listened to exactly four times.');
 165     });
 166 ```
 167
 168
 169 ### emitter.removeListener(event, listener)
 170 ### emitter.off(event, listener)
 171
 172 Remove a listener from the listener array for the specified event.
 173 **Caution**: changes array indices in the listener array behind the listener.
 174
 175 ```javascript
 176     var callback = function(value) {
 177       console.log('someone connected!');
 178     };
 179     server.on('get', callback);
 180     // ...
 181     server.removeListener('get', callback);
 182 ```
 183
 184
 185 ### emitter.removeAllListeners([event])
 186
 187 Removes all listeners, or those of the specified event.
 188
 189
 190 ### emitter.setMaxListeners(n)
 191
 192 By default EventEmitters will print a warning if more than 10 listeners
 193 are added to it. This is a useful default which helps finding memory leaks.
 194 Obviously not all Emitters should be limited to 10. This function allows
 195 that to be increased. Set to zero for unlimited.
 196
 197
 198 ### emitter.listeners(event)
 199
 200 Returns an array of listeners for the specified event. This array can be
 201 manipulated, e.g. to remove listeners.
 202
 203 ```javascript
 204     server.on('get', function(value) {
 205       console.log('someone connected!');
 206     });
 207     console.log(server.listeners('get')); // [ [Function] ]
 208 ```
 209
 210 ### emitter.listenersAny()
 211
 212 Returns an array of listeners that are listening for any event that is
 213 specified. This array can be manipulated, e.g. to remove listeners.
 214
 215 ```javascript
 216     server.onAny(function(value) {
 217       console.log('someone connected!');
 218     });
 219     console.log(server.listenersAny()[0]); // [ [Function] ]
 220 ```
 221
 222 ### emitter.emit(event, [arg1], [arg2], [...])
 223
 224 Execute each of the listeners that may be listening for the specified event
 225 name in order with the list of arguments.
 226
 227 # LICENSE
 228
 229 (The MIT License)
 230
 231 Copyright (c) 2011 hij1nx <http://www.twitter.com/hij1nx>
 232
 233 Permission is hereby granted, free of charge, to any person obtaining a copy
 234 of this software and associated documentation files (the 'Software'), to deal
 235 in the Software without restriction, including without limitation the rights
 236 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 237 copies of the Software, and to permit persons to whom the Software is furnished
 238 to do so, subject to the following conditions:
 239
 240 The above copyright notice and this permission notice shall be included in all
 241 copies or substantial portions of the Software.
 242
 243 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 244 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 245 FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 246 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
 247 AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 248 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.