[refactor api] All transports will now be instances of `events.EventE…

…mitter`

lib/winston/transports/console.js

@@ -12,10 +12,13 @@ var events = require('events'),
     log = require('./../utils').log;
 
 //
-// function Console (options)
-//   Constructor for the Console transport object.
+// ### function Console (options)
+// #### @options {Object} Options for this instance.
+// Constructor function for the Console transport object responsible
+// for persisting log messages and metadata to a terminal or TTY.
 //
 var Console = exports.Console = function (options) {
+  events.EventEmitter.call(this);
   options = options || {};
 
   this.name      = 'console';
@@ -26,22 +29,33 @@ var Console = exports.Console = function (options) {
 };
 
 //
-// function log (level, msg, [meta], callback)
-//   Core logging method exposed to Winston. Metadata is optional.
+// Inherit from `events.EventEmitter`.
+//
+util.inherits(Console, events.EventEmitter);
+
+//
+// ### function log (level, msg, [meta], callback)
+// #### @level {string} Level at which to log the message.
+// #### @msg {string} Message to log
+// #### @meta {Object} **Optional** Additional metadata to attach
+// #### @callback {function} Continuation to respond to when complete.
+// Core logging method exposed to Winston. Metadata is optional.
 //
 Console.prototype.log = function (level, msg, meta, callback) {
-  if (!this.silent) {
-    var output = log(level, msg, meta, {
-      colorize: this.colorize, 
-      timestamp: this.timestamp
-    });
+  if (this.silent) {
+    return callback(null, true);
+  }
 
-    if (level === 'error' || level === 'debug') {
-      util.error(output);
-    }
-    else {
-      util.puts(output);
-    }
+  var output = log(level, msg, meta, {
+    colorize: this.colorize, 
+    timestamp: this.timestamp
+  });
+
+  if (level === 'error' || level === 'debug') {
+    util.error(output);
+  }
+  else {
+    util.puts(output);
   }
 
   callback(null, true);

lib/winston/transports/file.js

@@ -6,15 +6,18 @@
  *
  */
 
-var fs = require('fs'),
+var events = require('events'),
+    fs = require('fs'),
     path = require('path'),
     util = require('util'),
     colors = require('colors'),
     log = require('./../utils').log;
 
 //
-// function File (options)
-//   Constructor for the File transport object.
+// ### function File (options)
+// #### @options {Object} Options for this instance.
+// Constructor function for the File transport object responsible
+// for persisting log messages and metadata to one or more files.
 //
 var File = exports.File = function (options) {
   options = options || {};
@@ -63,8 +66,12 @@ var File = exports.File = function (options) {
 };
 
 //
-// function log (level, msg, [meta], callback)
-//   Core logging method exposed to Winston. Metadata is optional.
+// ### function log (level, msg, [meta], callback)
+// #### @level {string} Level at which to log the message.
+// #### @msg {string} Message to log
+// #### @meta {Object} **Optional** Additional metadata to attach
+// #### @callback {function} Continuation to respond to when complete.
+// Core logging method exposed to Winston. Metadata is optional.
 //
 File.prototype.log = function (level, msg, meta, callback) {
   if (this.silent) {
@@ -102,6 +109,12 @@ File.prototype.log = function (level, msg, meta, callback) {
   callback(null, true);
 };
 
+//
+// ### function open (callback)
+// #### @callback {function} Continuation to respond to when complete
+// Checks to see if a new file needs to be created based on the `maxsize`
+// (if any) and the current size of the file used.
+//
 File.prototype.open = function (callback) {
   var self = this;
 
@@ -117,6 +130,11 @@ File.prototype.open = function (callback) {
   callback();
 };
 
+//
+// ### function flush ()
+// Flushes any buffered messages to the current `stream`
+// used by this instance.
+//
 File.prototype.flush = function () {
   var self = this;
 
@@ -185,6 +203,11 @@ File.prototype._createStream = function () {
   })(this._basename);  
 };
 
+//
+// ### @private function _nextFile ()
+// Gets the next filename to use for this instance
+// in the case that log filesizes are being capped.
+//
 File.prototype._nextFile = function () {
   var self = this,
       ext = path.extname(this._basename),

lib/winston/transports/loggly.js

@@ -8,13 +8,17 @@
 
 var events = require('events'),
     loggly = require('loggly'),
+    util = require('util'),
     utils = require('./../utils'); 
 
 //
-// function Loggly (options)
-//   Constructor for the Loggly transport object.
+// ### function Loggly (options)
+// #### @options {Object} Options for this instance.
+// Constructor function for the Loggly transport object responsible
+// for persisting log messages and metadata to Loggly; 'LaaS'.
 //
 var Loggly = exports.Loggly = function (options) {
+  events.EventEmitter.call(this);
   options = options || {};
 
   if (!options.subdomain) {
@@ -59,8 +63,17 @@ var Loggly = exports.Loggly = function (options) {
 };
 
 //
-// function log (level, msg, [meta], callback)
-//   Core logging method exposed to Winston. Metadata is optional.
+// Inherit from `events.EventEmitter`.
+//
+util.inherits(Loggly, events.EventEmitter);
+
+//
+// ### function log (level, msg, [meta], callback)
+// #### @level {string} Level at which to log the message.
+// #### @msg {string} Message to log
+// #### @meta {Object} **Optional** Additional metadata to attach
+// #### @callback {function} Continuation to respond to when complete.
+// Core logging method exposed to Winston. Metadata is optional.
 //
 Loggly.prototype.log = function (level, msg, meta, callback) {
   var message = utils.clone(meta);

lib/winston/transports/webhook.js

@@ -8,64 +8,87 @@
 
 var events = require('events'),
     http = require('http'),
+    util = require('util'),
     utils = require('./../utils'); 
 
 //
-// function Webhook (options)
-//   Constructor for the Webhook transport object.
+// ### function WebHook (options)
+// #### @options {Object} Options for this instance.
+// Constructor function for the Console transport object responsible
+// for making arbitrary HTTP requests whenever log messages and metadata
+// are received.
 //
 var Webhook = exports.Webhook = function (options) {
+  events.EventEmitter.call(this);
   options = options || {};
 
-  this.host = options.host || 'localhost';
-  this.port = options.port || 8080;
-  this.path = options.path || '/winston-log';
+  this.name   = 'webhook'; 
+  this.level  = options.level  || 'info';
+  this.host   = options.host   || 'localhost';
+  this.port   = options.port   || 8080;
+  this.method = options.method || 'POST';
+  this.path   = options.path   || '/winston-log';
 
-  //
-  // TODO: add http basic auth options for outgoing HTTP requests
-  // 
-  if (options.auth) { }
-
-  //
-  //  TODO: add ssl support for outgoing HTTP requests
-  //
-  if (options.ssl) { }
+  if (options.auth) {
+    //
+    // TODO: add http basic auth options for outgoing HTTP requests
+    //     
+  }
 
-  this.name = 'webhook'; 
-  this.level = options.level || 'info';
+  if (options.ssl) {
+    //
+    //  TODO: add ssl support for outgoing HTTP requests
+    //
+  }  
 };
 
 //
-// function log (level, msg, [meta], callback)
-//   Core logging method exposed to Winston. Metadata is optional.
+// Inherit from `events.EventEmitter`.
 //
-Webhook.prototype.log = function (level, msg, meta, callback) {
+util.inherits(Webhook, events.EventEmitter);
 
-  var message = utils.clone(meta);
+//
+// ### function log (level, msg, [meta], callback)
+// #### @level {string} Level at which to log the message.
+// #### @msg {string} Message to log
+// #### @meta {Object} **Optional** Additional metadata to attach
+// #### @callback {function} Continuation to respond to when complete.
+// Core logging method exposed to Winston. Metadata is optional.
+//
+Webhook.prototype.log = function (level, msg, meta, callback) {
+  if (this.silent) {
+    return callback(null, true);
+  }
+
+  var self = this,
+      message = utils.clone(meta),
+      options,
+      req;
+
   message.level = level;
   message.message = msg;
 
   // Prepare options for outgoing HTTP request
-  var options = {
+  options = {
     host: this.host,
     port: this.port,
     path: this.path,
-    method: 'POST'
+    method: this.method
   };
 
   // Perform HTTP logging request
-  var req = http.request(options, function (res) { 
+  req = http.request(options, function (res) { 
     //
     // No callback on request, fire and forget about the response
     //
   }); 
 
-  req.on('error', function (e) {
+  req.on('error', function (err) {
     //
-    // TODO: Make transports instances of events.EventEmitter
-    // and propagate this error back up only if the logger has 
-    // `emitErrs` set.
+    // Propagate the `error` back up to the `Logger` that this
+    // instance belongs to.
     //
+    self.emit('error', err);
   });
 
   //

package.json

@@ -13,6 +13,7 @@
   },
   "keywords": ["logging", "sysadmin", "tools"],
   "dependencies": {
+    "async": "0.1.x",
     "colors": "0.x.x",
     "eyes": "0.1.x",
     "loggly": "0.3.x",

test/loggly-test.js

@@ -13,7 +13,7 @@ var path = require('path'),
     assert = require('assert'),
     winston = require('winston'),
     helpers = require('./helpers');
-    
+
 var config = helpers.loadConfig(),
     tokenTransport = new (winston.transports.Loggly)({ 
       subdomain: config.transports.loggly.subdomain,

test/webhook-test.js

@@ -42,6 +42,14 @@ vows.describe('winston/transports/webhook').addBatch({
   }
 }).addBatch({
   "When the tests are over": {
+    topic: function () {
+      //
+      // Delay destruction of the server since the 
+      // WebHook transport responds before the request
+      // has actually be completed.
+      //
+      setTimeout(this.callback, 1000);
+    },
     "the server should cleanup": function () {
       server.close();
     }