introduce debug.id helper method

When debugging the applications that work with pools of streams
or sockets, the debug stream often comes out interleaved making it
impossible to distinguish between streams. It is a common knowledge
that unique `id`s could be assigned to each stream and be used in
logging to solve this. However, this solution is rather ad-hoc and
usually applied only during manual debugging.

This commit introduces standard function `debug.id()` that
increments the internal counter only when debugging is enabled, and
otherwise returns `undefined`.

src/common.js

@@ -65,6 +65,7 @@ module.exports = function setup(env) {
 
   function createDebug(namespace) {
     var prevTime;
+    var lastId = 0;
 
     function debug() {
       // disabled?
@@ -118,11 +119,19 @@ module.exports = function setup(env) {
       logFn.apply(self, args);
     }
 
+    function id () {
+      // disabled?
+      if (!debug.enabled) return;
+
+      return lastId++;
+    }
+
     debug.namespace = namespace;
     debug.enabled = createDebug.enabled(namespace);
     debug.useColors = createDebug.useColors();
     debug.color = selectColor(namespace);
     debug.destroy = destroy;
+    debug.id = id;
     //debug.formatArgs = formatArgs;
     //debug.rawLog = rawLog;
 

test/debug_spec.js

@@ -62,6 +62,21 @@ describe('debug', function () {
         expect(log.log).to.have.been.calledOnce;
       });
     });
+
+    context('with `log.id` function', function () {
+      it('increments internal id when enabled', function () {
+        expect(log.id()).to.equal(0);
+        expect(log.id()).to.equal(1);
+        expect(log.id()).to.equal(2);
+      });
+
+      it('does not increment internal id when disabled', function () {
+        debug.disable('test');
+
+        expect(log.id()).to.equal(undefined);
+        expect(log.id()).to.equal(undefined);
+      });
+    });
   });
 
 });