Deprecate Terror.ensureError in favor of Terror.createError

lib/terror.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var ERROR_CODE = 'Terror codes collision detected in the %name%&.extendCodes call for code "%code%"';
+var SPRINTF_RE = /%([^%\s]+)%/g;
 
 var has = Object.prototype.hasOwnProperty;
 
@@ -23,12 +24,12 @@ var has = Object.prototype.hasOwnProperty;
  *              .log();
  *      }
  *
- *      // try to use Terror#ensureError if catched error can be Terror successor or not
+ *      // use Terror#createError if caught error can be Terror successor or not
  *
  *      try {
  *          // dangerous code here
  *      } catch(err) {
- *          MyError.ensureError(err, MyError.CODES.MY_FAULT)
+ *          MyError.createError(MyError.CODES.MY_FAULT, err)
  *              .bind({ reason: 'i was sad when write code above' })
  *              .log();
  *      }
@@ -109,7 +110,7 @@ Terror.create = function(name, codes) {
 
     inherits(Inheritor, this);
 
-    // link contructors methods
+    // link methods of the constructor
     Inheritor.create = this.create;
     Inheritor.extendCodes = this.extendCodes;
     Inheritor.is = this.is;
@@ -158,33 +159,38 @@ Terror.extendCodes = function(codes) {
 
 /**
  * @param {String|Number} [code]
- * @param {String|Error|Object} [message] error message, Error or key-value hash for binding
+ * @param {String|Error|Terror|Object} [message] error message, Error or key-value hash for binding
  * @returns {Terror} new Terror instance
  */
 Terror.createError = function(code, message) {
-    var Const = this === Terror ? Terror : this;
+    var Ctor = this === Terror ? Terror : this;
     var msg;
     var data;
 
+    if (arguments.length === 1 && code instanceof Ctor) {
+        return code;
+    }
+
     if (isString(message) || isError(message)) {
         msg = message;
     } else {
         data = message;
     }
 
-    var error = new Const(code, msg).bind(data);
+    var error = new Ctor(code, msg).bind(data);
 
     return captureStackTrace(error, this.createError);
 };
 
 /**
+ * @deprecated Use `Terror.createError(code, error)`
  * @param {Error|Terror} error
  * @param {String|Number} [code]
  * @returns {Terror}
  */
-Terror.ensureError = function(error, code) {
+Terror.ensureError = deprecate(function(error, code) {
     return error instanceof this ? error : this.createError(code, error);
-};
+}, 'Terror.ensureError(): use Terror.createError(code, error) instead');
 
 /**
  * @param {*} error
@@ -374,9 +380,8 @@ function sPrintF(str, data) {
     var result = '';
     var m;
     var last = 0;
-    var regExp = /%([^%\s]+)%/g;
 
-    while ((m = regExp.exec(str))) {
+    while ((m = SPRINTF_RE.exec(str))) {
         result += str.substring(last, m.index) + (has.call(data, m[1]) ? data[m[1]] : m[0]);
         last = m.index + m[0].length;
     }
@@ -430,3 +435,14 @@ function Const(ctor) {
 
     Const.prototype = Object.prototype;
 }
+
+function deprecate(fn, msg) {
+    var warned = false;
+    return function deprecated() {
+        if ( ! warned) {
+            console.error(msg);
+            warned = true;
+        }
+        return fn.apply(this, arguments);
+    };
+}

test/terror.js

@@ -139,6 +139,16 @@ describe('Terror', function () {
             checkInstance('code', undefined, error);
         });
 
+        it('should not create new error if first argument is an instance of the context constructor', function () {
+            terror = new Terror();
+            assert.strictEqual(Terror.createError(terror), terror);
+
+            MyError = Terror.create('MyError');
+            terror = new MyError();
+            assert.strictEqual(MyError.createError(terror), terror);
+            assert.strictEqual(Terror.createError(terror), terror);
+        });
+
         it('should correctly capture the stacktrace', function () {
             var error = new Error().stack.split('\n')[1];
             var terror = Terror.createError().stack.split('\n')[1];
@@ -148,7 +158,7 @@ describe('Terror', function () {
                 terror.substr(0, terror.length - 7));
         });
 
-        it('should bind a data to instanace', function () {
+        it('should bind a data to instance', function () {
             data = {
                 name: 'value'
             };