glob-events.js

Event emitter with glob support on event names, for node and the browser

Features

• Node.js EventEmitter compatible API
• Register listeners with glob event names (* and **)
• Emit events with glob event names (* and **)
• 100% test coverage

Install with npm

npm install glob-events

Browser support

Use Browserify to create a standalone file.

Usage

var Emitter = require('glob-events').Emitter;
var emitter = new Emitter();

API

• Emitter([opts]): Constructor function, accepting these options:
  • reverse: Whether to invoke listeners in reverse insertion order. Defaults to false.
  • addEvent: The event to fire when new listeners are added. Defaults to "newListener".
  • removeEvent: The event to fire when listeners are removed. Defaults to "removeListener".
  • internalEvents: An array of internal events. Listeners that are registered for internal events are not invoked when emitting *. The newListener, removeListener and "error" events are always internal.
  • internalEmitter: An emitter to use for internal events. Defaults to this
• toScope(args[, emitter]): Converts the given arguments array into a scope object that can be used with invoke. If an emitter is given, it is added to the scope object.

The constructor opts are passed to the glob-store constructor.

Emitter API

• emit(event[, ...]): Invokes all listeners registered for the given event with the optional arguments. Matching rules are applied on the event name as described in the glob-tree match expressions.
• addListener(event, fn) / on(event, fn): Registers a listener for an event
• once(event, fn): Registers a listener for an event that is automatically removed on the first invocation
• removeListener(event, fn): Unregisters a listener for an event
• removeAllListeners([event]): Unregisters all listeners, or all listeners for the given event. Matching rules are not applied.
• removeMatchingListeners(event): Unregisters all listeners matching the given event name as described in the glob-tree match expressions.
• listeners([event][, options]): Returns all listeners, or all listeners for the given event. Matching rules are applied on the event name as described in the glob-tree match expressions.
• iterator([event][, options]): Exposes the iterator used to retrieve all listeners, or all listeners for a given event. Each iterator entry has these properties:
  • event: The event name that was used to register the function
  • fn: The registered function. Note: When using once, this is not the same as the registered function.
  • orig: The original registered function, only available for entries that where added with once.
  • scope: The scope to use when invoking the function.
• invoke(iterator, scope): Invokes the functions returned by an iterator on the given scope with the arguments from scope.args. This function is internally used by emit. If a listener throws, emitError is used to emit an error event.
• isInternalEvent(event): Returns true if the given event is an internal event. These are the "error" event, the add and remove events and the configured internal events.
• emitError(error, cause): Emits an "error" event with the given error as the only argument. If cause is given, it is accessible in error listeners via this.cause. A cause object should have these entries: - event: The event that caused the exception - fn: The function that threw the exception - scope: The scope the function was executed with - args: The arguments that where passed to the function

Options

The options argument can have these properties:

• matchers: Emit to matchers, defaults to true
• listeners: Emit to listeners, defaults to true

The first argument passed to emit can be an object with an event property and any of the above options.

Scope

Listeners are invoked with a special scope object. If an object is passed to emit as the event (see Options), that object is used as the scope object. The scope object always has these properties:

• event: The event that was emitted
• args: The arguments that where passed after the event name.
• emitter: The event emitter instance

It is also possible to bind individual listeners to specific scope objects:

emitter.addListener({
  event : 'some.event',
  scope : this
}, function () { ... });

Events

• newListener: Emitted by addListener, on and once with the event name and the new listener function. Matchers will not receive this event.
• removeListener: Emitted by removeListener and removeAllListeners with the event name and the removed listener function. Matchers will not receive this event.
• error: Emitted by emit if a listener throws an exception. The only argument is the caught exception. The original event's scope is exposed on this.cause with these properties:
  • event: The event that caused the exception
  • fn: The function that threw the exception
  • scope: The scope the function was executed with
  • args: The arguments that where passed to the function

TODO

• setMaxListeners(n)

License

MIT