diff --git a/src/event/Evented.js b/src/event/Evented.js index 7821a00..52e7f11 100644 --- a/src/event/Evented.js +++ b/src/event/Evented.js @@ -27,26 +27,30 @@ var Trait = require( 'easejs' ).Trait, /** - * Flexible event system augmentation + * 1-N message dispatch system * * The class mixing in this trait will be endowed with a complete event - * system with which events may be registered, hooked, and emitted. The - * callback scheduler may be overridden to alter the algorithm for invoking - * callbacks. + * system with which events may be registered, hooked, and emitted. There is + * a 1-N relationship between an event and its listeners respectively. + * + * Various aspects of this system may be overridden to provide behaviors + * appropriate for a variety of systems; for example, the callback scheduler + * 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. + * implementation, but is more robust. */ module.exports = Trait( 'Evented', { /** - * Registered events and their callbacks + * Registered events and their listeners * @type {Object} */ _events: {}, /** - * List of gaps in event callback lists + * List of gaps in event listener lists * @type {Object} */ _gaps: {}, @@ -57,7 +61,7 @@ module.exports = Trait( 'Evented', * * If any of the given identifiers is already in use (or if duplicates * are provided), an error will be thrown; this is to prevent - * accidentally mixing callbacks when an event is assumed to have not + * accidentally mixing listeners when an event is assumed to have not * already been defined. * * @Theta {n} relative to number of events @@ -101,7 +105,7 @@ module.exports = Trait( 'Evented', throw Error( `Duplicate definition of event \`${id}'` ); } - // will contain each callback associated with this event + // will contain each listener associated with this event this._events[ id ] = []; this._gaps[ id ] = []; } @@ -109,7 +113,7 @@ module.exports = Trait( 'Evented', /** - * Schedules all callbacks for defined event EV + * Schedules all listener callbacks for defined event EV * * See documentation for the `scheduleCallbacks` method for information * on the default callback scheduler. @@ -139,9 +143,9 @@ module.exports = Trait( 'Evented', /** - * Invoke all callbacks for the given event + * Invoke all listeners for the given event * - * The default scheduler invokes the callbacks synchronously and in an + * The default scheduler invokes the listeners synchronously and in an * undefined order (that is, the implementation may change at any time); * this method can be overridden to provide a different scheduler that * provides different guarantees. @@ -149,8 +153,8 @@ module.exports = Trait( 'Evented', * @O {n} where n = <# registerd listeners> + <# gaps> for event EV * * @param {string} ev defined event id - * @param {Array.} evc event callbacks (listeners) - * @param {Array} args argument list to apply to callbacks + * @param {Array.} evc event listeners + * @param {Array} args argument list to apply to listeners * * @return {Evented} self */ @@ -171,7 +175,7 @@ module.exports = Trait( 'Evented', * Invoke listener when an event is emitted * * The event EV must be defined and LISTENER must be a function. The - * context in which the callback is invoked (the value of `this') is + * context in which the listener is invoked (the value of `this') is * undefined. * * @O {#hookEvent} depends on hooking algorithm diff --git a/test/event/EventedTest.js b/test/event/EventedTest.js index 77f4286..324e3bb 100644 --- a/test/event/EventedTest.js +++ b/test/event/EventedTest.js @@ -171,7 +171,7 @@ describe( 'event.Evented', () => } ); - it( 'requires that callback is a function', () => + it( 'requires that listener is a function', () => { var ev = 'foo'; stub.evDefineEvents( [ ev ] ); @@ -198,7 +198,7 @@ describe( 'event.Evented', () => } ); - it( 'invokes all callbacks attached with #on', () => + it( 'invokes all listeners attached with #on', () => { var ev = 'foo', called = 0; @@ -209,7 +209,7 @@ describe( 'event.Evented', () => expect( () => stub.evEmit( ev ) ) .to.not.throw( Error ); - // make sure the callback was invoked only once + // make sure the listener was invoked only once expect( called ).to.equal( 1 ); } ); @@ -219,7 +219,7 @@ describe( 'event.Evented', () => * are given. Otherwise, the emitter must take care to clone or * encapsulate the values if this is a concern. */ - it( 'passes all emit args by reference to callbacks', ( done ) => + it( 'passes all emit args by reference to listeners', ( done ) => { var ev = 'foo', a = {}, @@ -237,12 +237,12 @@ describe( 'event.Evented', () => /** - * The default event scheduler synchronously invokes all callbacks + * The default event scheduler synchronously invokes all listeners * in an undefined order (that is: the order may change in the * future). This is not desirable for all cases, but that's not the * point here. */ - it( 'invokes multiple callbacks synchronously', () => + it( 'invokes multiple listeners synchronously', () => { var ev = 'foo', called = [], @@ -250,15 +250,15 @@ describe( 'event.Evented', () => stub.evDefineEvents( [ ev ] ); - // add N callbacks for EV + // add N listeners for EV for ( let i = 0; i < n; i++ ) { stub.on( ev, () => called[ i ] = true ); } - // trigger callbacks + // trigger listeners stub.evEmit( ev ); - // by now, we care about two things: that all callbacks were + // by now, we care about two things: that all listeners were // invoked and that they have been invoked by this point, // meaning that they were done synchronously while ( n-- ) { @@ -268,10 +268,10 @@ describe( 'event.Evented', () => /** - * When we emit an event, only the callbacks for that specific event + * When we emit an event, only the listeners for that specific event * should be invoked. */ - it( 'does not mix callbacks from other events', () => + it( 'does not mix listeners from other events', () => { var ev = 'foo', wrongev = 'bar'; @@ -282,7 +282,7 @@ describe( 'event.Evented', () => stub.on( ev, () => called = true ); stub.on( wrongev, () => { throw Error( "Thar be demons" ) } ); - // wrongev callback should *not* be called + // wrongev listeners should *not* be called stub.evEmit( ev ); expect( called ).to.equal( true ); } ); @@ -334,7 +334,7 @@ describe( 'event.Evented', () => * The listeners are encapsulated within the trait, so they must be * passed to us for processing. */ - it( 'is provided with callbacks to invoke', ( done ) => + it( 'is provided with listeners to invoke', ( done ) => { var a = function() {}, b = function() {};