Return the target of successful checks, release version 0.2.0

README.md

@@ -29,6 +29,8 @@ var blah = null;
 check(blah).is.a.string(); //Throws "Check failed: null was not a String"
 check(blah, "blah").is.a.string(); //Throws "Check failed: blah (null) was not a String"
 check(blah).is.not.a.string(); //OK!
+
+var result = check(blah).is.null(); //OK! All checks return the value passed in, so result === blah.
 ```
 
 A check will throw when its assertion fails and will otherwise do nothing. For instance, `check(null).is.a.string()`
@@ -38,7 +40,8 @@ will throw an Error, where `check(null).is.null()` will not.
 
 `not` negates the check, so `check(null).is.not.a.string()` will not throw.
 
-An optional name can be given with the object to check and will be included in the Error when thrown.
+An optional name can be given with the object to check and will be included in the Error when thrown. All checks return
+the original value passed in and typing is preserved for TypeScript consumers.
 
 #### Named instances
 
@@ -52,14 +55,16 @@ var blah = null;
 check(blah).is.a.string(); //Throws "[Logger] Check failed: null was not a String"
 check(blah, "blah").is.a.string(); //Throws "[Logger] Check failed: blah (null) was not a String"
 check(blah).is.not.a.string(); //OK!
+
+var result = check(blah).is.null(); //OK! All checks return the value passed in, so result === blah.
 ```
-   
+
 ## API
 
 See [check-preconditions.d.ts](check-preconditions.d.ts) for TypeScript type definitions.
 
 ```javascript
-interface Check {
+interface Check<T> {
 
     /**
      * Passthrough properties, these have no affect on the instance. They can be called ad nauseum and in any order.
@@ -68,9 +73,9 @@ interface Check {
      * check(blah).is.an.object();
      * //etc.
      */
-    is: Check;
-    a: Check;
-    an: Check;
+    is: Check<T>;
+    a: Check<T>;
+    an: Check<T>;
 
     /**
      * Inverts the instance's check. This can only be used once per Check instance, so you can't not not something.
@@ -80,33 +85,33 @@ interface Check {
      * check(blah).is.a.string(); //OK!
      * check(blah).is.not.a.string(); //Throws
      */
-    not: Check;
+    not: Check<T>;
 
     /**
      * Type checks. These will throw if the target is not of the given type. Number includes NaN.
      */
-    function(): void;
-    object(): void;
-    number(): void;
-    string(): void;
-    array(): void;
-    null(): void;
-    undefined(): void;
-    true(): void;
-    false(): void;
+    function(): T;
+    object(): T;
+    number(): T;
+    string(): T;
+    array(): T;
+    null(): T;
+    undefined(): T;
+    true(): T;
+    false(): T;
 
     /**
      * Check that the target is empty. This check passes if the target is any of the following:
      *  - an object with no enumerable own properties.
      *  - an array with no elements
      *  - an empty string
      */
-    empty(): void;
+    empty(): T;
 
     /**
      * Check whether the target exists. This is defined as being neither null nor undefined.
      */
-    exists(): void;
+    exists(): T;
 }
 
 declare module "check-preconditions" {
@@ -116,16 +121,16 @@ declare module "check-preconditions" {
      *
      * @param {string} baseName - A baseName to link created Checks to. Usually a Class or Module name.
      */
-    export function of(baseName: string): (target: any, name?: string) => Check
+    export function of(baseName: string): <T>(target: T, name?: string) => Check<T>
 
     /**
      * Check the given target with an optional name. If a name is given it will be included in the Error thrown
      * when the Check fails.
      *
-     * @param {any} target - A thing to check against.
+     * @param {T} target - A thing to check against.
      * @param {string} [name] - An optional name for the target.
      */
-    export function check(target: any, name?: string): Check
+    export function check<T>(target: T, name?: string): Check<T>
 }
 ```
 

check-preconditions.d.ts

@@ -1,4 +1,4 @@
-interface Check {
+interface Check<T> {
 
     /**
      * Passthrough properties, these have no affect on the instance. They can be called ad nauseum and in any order.
@@ -7,9 +7,9 @@ interface Check {
      * check(blah).is.an.object();
      * //etc.
      */
-    is: Check;
-    a: Check;
-    an: Check;
+    is: Check<T>;
+    a: Check<T>;
+    an: Check<T>;
 
     /**
      * Inverts the instance's check. This can only be used once per Check instance, so you can't not not something.
@@ -19,33 +19,33 @@ interface Check {
      * check(blah).is.a.string(); //OK!
      * check(blah).is.not.a.string(); //Throws
      */
-    not: Check;
+    not: Check<T>;
 
     /**
      * Type checks. These will throw if the target is not of the given type. Number includes NaN.
      */
-    function(): void;
-    object(): void;
-    number(): void;
-    string(): void;
-    array(): void;
-    null(): void;
-    undefined(): void;
-    true(): void;
-    false(): void;
+    function(): T;
+    object(): T;
+    number(): T;
+    string(): T;
+    array(): T;
+    null(): T;
+    undefined(): T;
+    true(): T;
+    false(): T;
 
     /**
      * Check that the target is empty. This check passes if the target is any of the following:
      *  - an object with no enumerable own properties.
      *  - an array with no elements
      *  - an empty string
      */
-    empty(): void;
+    empty(): T;
 
     /**
      * Check whether the target exists. This is defined as being neither null nor undefined.
      */
-    exists(): void;
+    exists(): T;
 }
 
 declare module "check-preconditions" {
@@ -55,14 +55,14 @@ declare module "check-preconditions" {
      *
      * @param {string} baseName - A baseName to link created Checks to. Usually a Class or Module name.
      */
-    export function of(baseName: string): (target: any, name?: string) => Check
+    export function of(baseName: string): <T>(target: T, name?: string) => Check<T>
 
     /**
      * Check the given target with an optional name. If a name is given it will be included in the Error thrown
      * when the Check fails.
      *
-     * @param {any} target - A thing to check against.
+     * @param {T} target - A thing to check against.
      * @param {string} [name] - An optional name for the target.
      */
-    export function check(target: any, name?: string): Check
+    export function check<T>(target: T, name?: string): Check<T>
 }

lib/src/Check.js

@@ -84,6 +84,7 @@ var Check = (function () {
             var target = this.targetName ? this.targetName + " (" + this.target + ")" : "" + this.target;
             throw new Error(prefix + "Check failed: " + target + " was " + (this.negated ? "" : "not ") + caseString);
         }
+        return this.target;
     };
     return Check;
 })();

package.json

@@ -1,6 +1,6 @@
 {
   "name": "check-preconditions",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A small and simple ES3 compatible preconditions library for Node and the browser.",
   "author": "Paul Nann",
   "license": "MIT",