Permalink
Browse files

first commit

  • Loading branch information...
0 parents commit 5dbded8c7a5c00ca30113fae5b1a41dec9fed6dc @caolan committed Nov 2, 2012
Showing with 449 additions and 0 deletions.
  1. +116 −0 README.md
  2. +326 −0 events.js
  3. +7 −0 package.json
116 README.md
@@ -0,0 +1,116 @@
+## Events module
+
+This is a AMD port of the node.js events module. Many objects and
+modules emit events and these are instances of events.EventEmitter.
+
+
+Functions can be attached to objects, to be executed when an event is
+emitted. These functions are called listeners.
+
+
+### API
+
+
+#### events.EventEmitter
+
+
+When an EventEmitter instance experiences an error, the typical action is to
+emit an 'error' event. Error events are treated as a special case. If there
+is no listener for it, then the default action is for the error to throw.
+
+All EventEmitters emit the event 'newListener' when new listeners are added.
+
+```javascript
+define('myModule', ['events'], function(events) {
+
+// create an event emitter
+var emitter = new events.EventEmitter();
+
+});
+```
+
+
+#### emitter.setMaxListeners(n)
+
+By default EventEmitters will print a warning if more than 10 listeners are
+added for a particular event. This is a useful default which helps finding
+memory leaks. Obviously not all Emitters should be limited to 10. This
+function allows that to be increased. Set to zero for unlimited.
+
+* __n__ - _Number_ - The maximum number of listeners
+
+
+#### emitter.emit(event, [arg1], [arg2], [...])
+
+Execute each of the listeners in order with the supplied arguments.
+
+* __event__ - _String_ - The event name/id to fire
+
+
+#### emitter.on(event, listener) | emitter.addListener(event, listener)
+
+Adds a listener to the end of the listeners array for the specified event.
+
+* __event__ - _String_ - The event name/id to listen for
+* __listener__ - _Function_ - The function to bind to the event
+
+```javascript
+session.on('change', function (userCtx) {
+ console.log('session changed!');
+});
+```
+
+
+#### emitter.once(event, listener)
+
+Adds a one time listener for the event. This listener is invoked only the
+next time the event is fired, after which it is removed.
+
+* __event-__ - _String_ - The event name/id to listen for
+* __listener__ - _Function_ - The function to bind to the event
+
+```javascript
+db.once('unauthorized', function (req) {
+ // this event listener will fire once, then be unbound
+});
+```
+
+
+#### emitter.removeListener(event, listener)
+
+Remove a listener from the listener array for the specified event. Caution:
+changes array indices in the listener array behind the listener.
+
+* __event__ - _String_ - The event name/id to remove the listener from
+* __listener__ - _Function_ - The listener function to remove
+
+```javascript
+var callback = function (init) {
+ console.log('duality app loaded');
+};
+devents.on('init', callback);
+// ...
+devents.removeListener('init', callback);
+```
+
+
+#### emitter.removeAllListeners([event])
+
+Removes all listeners, or those of the specified event.
+
+* __event__ - _String_ - Event name/id to remove all listeners for (optional)
+
+
+#### emitter.listeners(event)
+
+Returns an array of listeners for the specified event. This array can be
+manipulated, e.g. to remove listeners.
+
+* __events__ - _String_ - The event name/id to return listeners for
+
+```javascript
+session.on('change', function (stream) {
+ console.log('session changed');
+});
+console.log(util.inspect(session.listeners('change'))); // [ [Function] ]
+```
326 events.js
@@ -0,0 +1,326 @@
+/**
+ * ## Events module
+ *
+ * This is a browser port of the node.js events module. Many objects and
+ * modules emit events and these are instances of events.EventEmitter.
+ *
+
+ *
+ * Functions can then be attached to objects, to be executed when an event is
+ * emitted. These functions are called listeners.
+ *
+ * @module
+ */
+
+
+define(function(require, exports, module) {
+/**
+ * To access the EventEmitter class, require('events').EventEmitter.
+ *
+ * When an EventEmitter instance experiences an error, the typical action is to
+ * emit an 'error' event. Error events are treated as a special case. If there
+ * is no listener for it, then the default action is for the error to throw.
+ *
+ * All EventEmitters emit the event 'newListener' when new listeners are added.
+ *
+ * @name events.EventEmitter
+ * @api public
+ *
+ * ```javascript
+ *
+ * // create an event emitter
+ * var emitter = new EventEmitter();
+ * ```
+ */
+
+var EventEmitter = exports.EventEmitter = function () {};
+
+var toString = Object.prototype.toString;
+
+var isArray = Array.isArray || function (obj) {
+ return toString.call(obj) === '[object Array]';
+};
+
+var _indexOf = function (arr, el) {
+ if (arr.indexOf) {
+ return arr.indexOf(el);
+ }
+ for (var i = 0; i < arr.length; i++) {
+ if (arr[i] === el) {
+ return i;
+ }
+ }
+ return -1;
+};
+
+
+/**
+ * By default EventEmitters will print a warning if more than 10 listeners are
+ * added for a particular event. This is a useful default which helps finding
+ * memory leaks. Obviously not all Emitters should be limited to 10. This
+ * function allows that to be increased. Set to zero for unlimited.
+ *
+ * @name emitter.setMaxListeners(n)
+ * @param {Number} n - The maximum number of listeners
+ * @api public
+ */
+
+// By default EventEmitters will print a warning if more than
+// 10 listeners are added to it. This is a useful default which
+// helps finding memory leaks.
+//
+// Obviously not all Emitters should be limited to 10. This function allows
+// that to be increased. Set to zero for unlimited.
+var defaultMaxListeners = 10;
+EventEmitter.prototype.setMaxListeners = function(n) {
+ if (!this._events) this._events = {};
+ this._events.maxListeners = n;
+};
+
+
+/**
+ * Execute each of the listeners in order with the supplied arguments.
+ *
+ * @name emitter.emit(event, [arg1], [arg2], [...])
+ * @param {String} event - The event name/id to fire
+ * @api public
+ */
+
+EventEmitter.prototype.emit = function(type) {
+ // If there is no 'error' event listener then throw.
+ if (type === 'error') {
+ if (!this._events || !this._events.error ||
+ (isArray(this._events.error) && !this._events.error.length))
+ {
+ if (arguments[1] instanceof Error) {
+ throw arguments[1]; // Unhandled 'error' event
+ } else {
+ throw new Error("Uncaught, unspecified 'error' event.");
+ }
+ return false;
+ }
+ }
+
+ if (!this._events) return false;
+ var handler = this._events[type];
+ if (!handler) return false;
+
+ if (typeof handler == 'function') {
+ switch (arguments.length) {
+ // fast cases
+ case 1:
+ handler.call(this);
+ break;
+ case 2:
+ handler.call(this, arguments[1]);
+ break;
+ case 3:
+ handler.call(this, arguments[1], arguments[2]);
+ break;
+ // slower
+ default:
+ var args = Array.prototype.slice.call(arguments, 1);
+ handler.apply(this, args);
+ }
+ return true;
+
+ } else if (isArray(handler)) {
+ var args = Array.prototype.slice.call(arguments, 1);
+
+ var listeners = handler.slice();
+ for (var i = 0, l = listeners.length; i < l; i++) {
+ listeners[i].apply(this, args);
+ }
+ return true;
+
+ } else {
+ return false;
+ }
+};
+
+
+/**
+ * Adds a listener to the end of the listeners array for the specified event.
+ *
+ * @name emitter.on(event, listener) | emitter.addListener(event, listener)
+ * @param {String} event - The event name/id to listen for
+ * @param {Function} listener - The function to bind to the event
+ * @api public
+ *
+ * ```javascript
+ * session.on('change', function (userCtx) {
+ * console.log('session changed!');
+ * });
+ * ```
+ */
+
+// EventEmitter is defined in src/node_events.cc
+// EventEmitter.prototype.emit() is also defined there.
+EventEmitter.prototype.addListener = function(type, listener) {
+ if ('function' !== typeof listener) {
+ throw new Error('addListener only takes instances of Function');
+ }
+
+ if (!this._events) this._events = {};
+
+ // To avoid recursion in the case that type == "newListeners"! Before
+ // adding it to the listeners, first emit "newListeners".
+ this.emit('newListener', type, listener);
+
+ if (!this._events[type]) {
+ // Optimize the case of one listener. Don't need the extra array object.
+ this._events[type] = listener;
+ } else if (isArray(this._events[type])) {
+
+ // Check for listener leak
+ if (!this._events[type].warned) {
+ var m;
+ if (this._events.maxListeners !== undefined) {
+ m = this._events.maxListeners;
+ } else {
+ m = defaultMaxListeners;
+ }
+
+ if (m && m > 0 && this._events[type].length > m) {
+ this._events[type].warned = true;
+ console.error('(node) warning: possible EventEmitter memory ' +
+ 'leak detected. %d listeners added. ' +
+ 'Use emitter.setMaxListeners() to increase limit.',
+ this._events[type].length);
+ console.trace();
+ }
+ }
+
+ // If we've already got an array, just append.
+ this._events[type].push(listener);
+ } else {
+ // Adding the second element, need to change to array.
+ this._events[type] = [this._events[type], listener];
+ }
+
+ return this;
+};
+
+EventEmitter.prototype.on = EventEmitter.prototype.addListener;
+
+/**
+ * Adds a one time listener for the event. This listener is invoked only the
+ * next time the event is fired, after which it is removed.
+ *
+ * @name emitter.once(event, listener)
+ * @param {String} event- The event name/id to listen for
+ * @param {Function} listener - The function to bind to the event
+ * @api public
+ *
+ * ```javascript
+ * db.once('unauthorized', function (req) {
+ * // this event listener will fire once, then be unbound
+ * });
+ * ```
+ */
+
+EventEmitter.prototype.once = function(type, listener) {
+ var self = this;
+ self.on(type, function g() {
+ self.removeListener(type, g);
+ listener.apply(this, arguments);
+ });
+
+ return this;
+};
+
+/**
+ * Remove a listener from the listener array for the specified event. Caution:
+ * changes array indices in the listener array behind the listener.
+ *
+ * @name emitter.removeListener(event, listener)
+ * @param {String} event - The event name/id to remove the listener from
+ * @param {Function} listener - The listener function to remove
+ * @api public
+ *
+ * ```javascript
+ * var callback = function (init) {
+ * console.log('duality app loaded');
+ * };
+ * devents.on('init', callback);
+ * // ...
+ * devents.removeListener('init', callback);
+ * ```
+ */
+
+EventEmitter.prototype.removeListener = function(type, listener) {
+ if ('function' !== typeof listener) {
+ throw new Error('removeListener only takes instances of Function');
+ }
+
+ // does not use listeners(), so no side effect of creating _events[type]
+ if (!this._events || !this._events[type]) return this;
+
+ var list = this._events[type];
+
+ if (isArray(list)) {
+ var i = _indexOf(list, listener);
+ if (i < 0) return this;
+ list.splice(i, 1);
+ if (list.length == 0)
+ delete this._events[type];
+ } else if (this._events[type] === listener) {
+ delete this._events[type];
+ }
+
+ return this;
+};
+
+/**
+ * Removes all listeners, or those of the specified event.
+ *
+ * @name emitter.removeAllListeners([event])
+ * @param {String} event - Event name/id to remove all listeners for (optional)
+ * @api public
+ */
+
+EventEmitter.prototype.removeAllListeners = function(type) {
+ // does not use listeners(), so no side effect of creating _events[type]
+ if (type && this._events && this._events[type]) this._events[type] = null;
+ return this;
+};
+
+/**
+ * Returns an array of listeners for the specified event. This array can be
+ * manipulated, e.g. to remove listeners.
+ *
+ * @name emitter.listeners(event)
+ * @param {String} events - The event name/id to return listeners for
+ * @api public
+ *
+ * ```javascript
+ * session.on('change', function (stream) {
+ * console.log('session changed');
+ * });
+ * console.log(util.inspect(session.listeners('change'))); // [ [Function] ]
+ * ```
+ */
+
+EventEmitter.prototype.listeners = function(type) {
+ if (!this._events) this._events = {};
+ if (!this._events[type]) this._events[type] = [];
+ if (!isArray(this._events[type])) {
+ this._events[type] = [this._events[type]];
+ }
+ return this._events[type];
+};
+
+
+/**
+ * @name emitter Event: 'newListener'
+ *
+ * This event is emitted any time someone adds a new listener.
+ *
+ * ```javascript
+ * emitter.on('newListener', function (event, listener) {
+ * // new listener added
+ * });
+ * ```
+ */
+
+});
7 package.json
@@ -0,0 +1,7 @@
+{
+ "name": "events",
+ "version": "0.0.2",
+ "categories": ["node.js", "utils"],
+ "main": "events.js",
+ "description": "Browser port of the node.js events module"
+}

0 comments on commit 5dbded8

Please sign in to comment.