events-ex
Browser-friendly enhanced events most compatible with standard node.js and coffee-script. It's modified from event-emitter mainly. It can add event-able to your class directly.
Features
- rewrite the core architecture
- keep most compatible with node events and event-emitter
- more powerful event-able ability
- hookable event system
Differences
- Difference with node events
- domain is not supported yet(TODO)
broken change
: The event object bubbling Supports- the event object as listener's "this" object.
- return the result property of event object to emitter.
- prevent the rest of listener from be excuted if set the stopped property of event object to true
broken change
: theemit
return the result of listeners's callback function instead of the successful state.broken change
: thethis
object of listeners' callback function is theEvent
Object instead of the emitter object.- the emitter object is put into the
target
property of theEvent
Object.
- the emitter object is put into the
- Difference with event-emitter
broken change
: The event object bubbling Supports(see above)- add the defaultMaxListeners class property to keep compatible with node events.
- add the setMaxListeners method to keep compatible with node events.
- add
error
,newListener
andremoveListener
events to keep compatible with node events. - add listeners() method to keep compatible with node events.
- add listenerCount() class method to keep compatible with node events.
Installation
$ npm install events-ex
To port it to Browser or any other (non CJS) environment, use your favorite CJS bundler. No favorite yet? Try: Browserify, Webmake or Webpack
Usage
Add the event-able feature to your class directly:
eventable = require'events-ex/eventable' # advanced usage see API topic. eventable MyClass my = myon 'event'-> consolelog 'event occur' # be care: @(this) is the event object. not the `my` instance. # the my instance is @target. myemit 'event'
the following is javascript:
var eventable = ; {} ; var my = ; my; my;
Node JS events Usage:
## Coffee-script demo bubbling usage: EventEmitter = require'events-ex'inherits = require'inherits-ex'ABORT = -1DONE = 0 inherits MyDbEventEmitter : # Demo the event object bubbling usage: result = @emit 'getting'key if isObject result return if resultstate is ABORT return resultresult if resultstate is DONE _getkey db = dbon 'getting' result = myGetkey; if result? # get the key succ this.result = state: DONE result: result else if result is null # abort default get key. this.result = state: ABORT; # this.stopped = true # it will skip other listeners if true
// js demo bubbling usage:let EventEmitter = let isObject = const ABORT = -1const DONE = 0 { // Demo the event object bubbling usage: let result = this if if resultstate === ABORT return if resultstate === DONE return resultresult return } let db = db
event-emitter usage:
var ee = ; var { /* .. */ };; // All instances of MyClass will expose event-emitter interface var emitter = listener; emitter; emitter; emitter; // Two above listeners invokedemitter; // Only first listener invoked emitter; // Removed first listeneremitter; // No listeners invoked
API
eventable(class[, options]) (events-ex/eventable)
Add the event-able ability to the class directly.
class
: the class to be injected the ability.options
(object): optional optionsinclude
(string[]|string): only these emitter methods will be added to the class- NOTE: static method should use the prefix '@' with name.
exclude
(string[]|string): theses emitter methods would not be added to the class- NOTE: static method should use the prefix '@' with name.
methods
(object): hooked methods to the class- key: the method name to hook.
- value: the new method function
- use
this.super()
to call the original method. this.self
is the originalthis
object.
- use
classMethods
(object): hooked class methods to the class
eventable = require'events-ex/eventable' #OtherClass = require('OtherClass') : -> consolelog "my original exec" # only 'on', 'off', 'emit' and static methods 'listenerCount' added to the class eventable MyClassinclude: 'on''off''emit''@listenerCount' # add the eventable ability to OtherClass and inject the exec method of OtherClass. eventable OtherClassmethods: : -> consolelog "new exec" @super # call the original method
allOff(obj) (events-ex/all-off)
keep compatible only: the removeAllListeners
has already been buildin.
Removes all listeners from given event emitter object
hasListeners(obj[, name]) (events-ex/has-listeners)
Whether object has some listeners attached to the object.
When name
is provided, it checks listeners for specific event name
var emitter = ;var hasListeners = ;var {}; ; // false emitter;; // true; // true; // false emitter;; // false
pipe(source, target[, emitMethodName]) (events-ex/pipe)
Pipes all events from source emitter onto target emitter (all events from source emitter will be emitted also on target emitter, but not other way).
Returns pipe object which exposes pipe.close
function. Invoke it to close configured pipe.
It works internally by redefinition of emit
method, if in your interface this method is referenced differently, provide its name (or symbol) with third argument.
unify(emitter1, emitter2) (events-ex/unify)
Unifies event handling for two objects. Events emitted on emitter1 would be also emitter on emitter2, and other way back. Non reversible.
var eeUnify = ; var emitter1 = listener1 listener3;var emitter2 = listener2 listener4; emitter1;emitter2; emitter1; // Invoked listener1emitter2; // Invoked listener2 var unify = ; emitter1; // Invoked listener1 and listener2emitter2; // Invoked listener1 and listener2 emitter1;emitter2; emitter1; // Invoked listener1, listener2, listener3 and listener4emitter2; // Invoked listener1, listener2, listener3 and listener4