add async/nothrow variants of typeforce, with docs and tests

README.md

@@ -114,6 +114,31 @@ typeforce(typeforce.quacksLike('Foo'), new (function Foo() {}))
 // OK!
 ```
 
+**Pro**tips (no throw)
+``` javascript
+var typeforce = require('typeforce/nothrow')
+var value = 'foobar'
+
+if (typeforce(typeforce.Number, value)) {
+	// didn't throw!
+	console.log(`${value} is a number`) // never happens
+} else {
+	console.log(`Oops, ${typeforce.error.message}`)
+	// prints 'Oops, Expected Number, got String foobar'
+}
+```
+
+**Pro**tips (async)
+```
+var typeforce = require('typeforce/async')
+
+typeforce(typeforce.Number, value, function (err) {
+	if (err) return console.log(`Oops, ${typeforce.error.message}`)
+
+	console.log(`${value} is a number`) // never happens
+})
+```
+
 **WARNING**: Be very wary of using the `quacksLike` type, as it relies on the `Foo.name` property.
 If that property is mangled by a transpiler,  such as `uglifyjs`,  you will have a bad time.
 

async.js

@@ -0,0 +1,17 @@
+var typeforce = require('./')
+
+// async wrapper
+function tfAsync (type, value, strict, callback) {
+  // default to falsy strict if using shorthand overload
+  if (typeof strict === 'function') return tfAsync(type, value, false, strict)
+
+  try {
+    typeforce(type, value, strict)
+  } catch (e) {
+    return callback(e)
+  }
+
+  callback()
+}
+
+module.exports = Object.assign(tfAsync, typeforce)

index.js

@@ -230,21 +230,6 @@ for (typeName in EXTRA) {
   typeforce[typeName] = EXTRA[typeName]
 }
 
-// async wrapper
-function __async (type, value, strict, callback) {
-  // default to falsy strict if using shorthand overload
-  if (typeof strict === 'function') return __async(type, value, false, strict)
-
-  try {
-    typeforce(type, value, strict)
-  } catch (e) {
-    return callback(e)
-  }
-
-  callback()
-}
-
-typeforce.async = __async
 typeforce.compile = compile
 typeforce.TfTypeError = TfTypeError
 typeforce.TfPropertyTypeError = TfPropertyTypeError

nothrow.js

@@ -0,0 +1,12 @@
+var typeforce = require('./')
+
+function tfNoThrow (type, value, strict) {
+  try {
+    return typeforce(type, value, strict)
+  } catch (e) {
+    tfNoThrow.error = e
+    return false
+  }
+}
+
+module.exports = Object.assign(tfNoThrow, typeforce)

test/index.js

@@ -1,5 +1,7 @@
 var tape = require('tape')
 var typeforce = require('../')
+var typeforceAsync = require('../async')
+var typeforceNoThrow = require('../nothrow')
 var fixtures = require('./fixtures')
 var TYPES = require('./types')
 var VALUES = require('./values')
@@ -12,12 +14,14 @@ fixtures.valid.forEach(function (f) {
   var compiled = typeforce.compile(type)
 
   tape('passes ' + typeDescription + ' with ' + valueDescription, function (t) {
-    t.plan(4)
+    t.plan(6)
     t.doesNotThrow(function () { typeforce(type, value, f.strict) })
-    typeforce.async(type, value, f.strict, t.ifErr)
+    typeforceAsync(type, value, f.strict, t.ifErr)
+    t.equal(typeforceNoThrow(type, value, f.strict), true)
 
     t.doesNotThrow(function () { typeforce(compiled, value, f.strict) })
-    typeforce.async(compiled, value, f.strict, t.ifErr)
+    typeforceAsync(compiled, value, f.strict, t.ifErr)
+    t.equal(typeforceNoThrow(compiled, value, f.strict), true)
   })
 })
 
@@ -31,15 +35,27 @@ fixtures.invalid.forEach(function (f) {
   var compiled = typeforce.compile(type)
 
   tape('throws "' + f.exception + '" for type ' + typeDescription + ' with value of ' + valueDescription, function (t) {
-    t.plan(2)
+    t.plan(10)
 
     t.throws(function () {
       typeforce(type, value, f.strict)
     }, new RegExp(f.exception))
+    typeforceAsync(type, value, f.strict, (err) => {
+      t.ok(err)
+      t.throws(function () { throw err }, new RegExp(f.exception))
+    })
+    t.equal(typeforceNoThrow(type, value, f.strict), false)
+    t.throws(function () { throw typeforceNoThrow.error }, new RegExp(f.exception))
 
     t.throws(function () {
       typeforce(compiled, value, f.strict)
     }, new RegExp(f.exception))
+    typeforceAsync(compiled, value, f.strict, (err) => {
+      t.ok(err)
+      t.throws(function () { throw err }, new RegExp(f.exception))
+    })
+    t.equal(typeforceNoThrow(compiled, value, f.strict), false)
+    t.throws(function () { throw typeforceNoThrow.error }, new RegExp(f.exception))
   })
 })