Evented documentation elaborating on Node.js compatibility

Some of these features will be introduced into jsTonic through additional
traits: for example, the magic `error` event that produces exceptions if
unhooked can be implemented using stackable traits or Evented trait
overrides (the former is superior and more generalized/independent).
events
Mike Gerwitz 2014-08-06 01:08:07 -04:00
parent a5ac05b73d
commit 701a49226c
1 changed files with 15 additions and 4 deletions

View File

@ -39,17 +39,28 @@ var Trait = require( 'easejs' ).Trait,
* can be overridden to provide an alternative algorithm for invoking * can be overridden to provide an alternative algorithm for invoking
* listeners. * listeners.
* *
* The API is motivated by (and is a replacement for) Node.js' event emitter * The API is motivated by Node.js' EventEmitter implementation, but is more
* implementation, but is more robust. Note, however, that it differs * lean and robust. Note, however, that it differs significantly in a number
* significantly in a number of implementation details: * of implementation details:
* *
* - All events must be pre-registered, and all listeners must hook a * - All events must be pre-registered, and all listeners must hook a
* registered event; * registered event;
* - The same listener cannot be attached to the same event multiple * - The same listener cannot be attached to the same event multiple
* times (will produce an exception); * times (will produce an exception);
* - There is no special `error' event that will, if unhooked, trigger an * - There is no special `error' event that will, if unhooked, trigger an
* exception when emitted; and * exception when emitted;
* - #emit is not public;
* - It contains no introspective methods (no #listeners, `newListener`
* and `removeListener` events, or static #listenerCount);
* - It respects listeners' sovereignty (no #removeAllListeners or #once);
* - Defers restrictions to implementor (no #setMaxListeners);
* - It is implemented as a trait. * - It is implemented as a trait.
*
* So, while EventEmitter can be used wherever this trait (or Eventable) is
* expected, the reverse isn't necessarily true. Of course, implementors are
* free to implement these features if they so choose, overriding this
* trait's behavior where appropriate or creating their own Eventable
* class/trait.
*/ */
module.exports = Trait( 'Evented' ) module.exports = Trait( 'Evented' )
.implement( Eventable ) .implement( Eventable )