From 701a49226c597c98fafb4811cf146f9098489b99 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Wed, 6 Aug 2014 01:08:07 -0400 Subject: [PATCH] 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). --- src/event/Evented.js | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/src/event/Evented.js b/src/event/Evented.js index 532c472..4388c1c 100644 --- a/src/event/Evented.js +++ b/src/event/Evented.js @@ -39,17 +39,28 @@ var Trait = require( 'easejs' ).Trait, * can be overridden to provide an alternative algorithm for invoking * listeners. * - * The API is motivated by (and is a replacement for) Node.js' event emitter - * implementation, but is more robust. Note, however, that it differs - * significantly in a number of implementation details: + * The API is motivated by Node.js' EventEmitter implementation, but is more + * lean and robust. Note, however, that it differs significantly in a number + * of implementation details: * * - All events must be pre-registered, and all listeners must hook a * registered event; * - The same listener cannot be attached to the same event multiple * times (will produce an exception); * - 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. + * + * 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' ) .implement( Eventable )