README.md (4791B)
1 # assert-plus 2 3 This library is a super small wrapper over node's assert module that has two 4 things: (1) the ability to disable assertions with the environment variable 5 NODE\_NDEBUG, and (2) some API wrappers for argument testing. Like 6 `assert.string(myArg, 'myArg')`. As a simple example, most of my code looks 7 like this: 8 9 ```javascript 10 var assert = require('assert-plus'); 11 12 function fooAccount(options, callback) { 13 assert.object(options, 'options'); 14 assert.number(options.id, 'options.id'); 15 assert.bool(options.isManager, 'options.isManager'); 16 assert.string(options.name, 'options.name'); 17 assert.arrayOfString(options.email, 'options.email'); 18 assert.func(callback, 'callback'); 19 20 // Do stuff 21 callback(null, {}); 22 } 23 ``` 24 25 # API 26 27 All methods that *aren't* part of node's core assert API are simply assumed to 28 take an argument, and then a string 'name' that's not a message; `AssertionError` 29 will be thrown if the assertion fails with a message like: 30 31 AssertionError: foo (string) is required 32 at test (/home/mark/work/foo/foo.js:3:9) 33 at Object.<anonymous> (/home/mark/work/foo/foo.js:15:1) 34 at Module._compile (module.js:446:26) 35 at Object..js (module.js:464:10) 36 at Module.load (module.js:353:31) 37 at Function._load (module.js:311:12) 38 at Array.0 (module.js:484:10) 39 at EventEmitter._tickCallback (node.js:190:38) 40 41 from: 42 43 ```javascript 44 function test(foo) { 45 assert.string(foo, 'foo'); 46 } 47 ``` 48 49 There you go. You can check that arrays are of a homogeneous type with `Arrayof$Type`: 50 51 ```javascript 52 function test(foo) { 53 assert.arrayOfString(foo, 'foo'); 54 } 55 ``` 56 57 You can assert IFF an argument is not `undefined` (i.e., an optional arg): 58 59 ```javascript 60 assert.optionalString(foo, 'foo'); 61 ``` 62 63 Lastly, you can opt-out of assertion checking altogether by setting the 64 environment variable `NODE_NDEBUG=1`. This is pseudo-useful if you have 65 lots of assertions, and don't want to pay `typeof ()` taxes to v8 in 66 production. Be advised: The standard functions re-exported from `assert` are 67 also disabled in assert-plus if NDEBUG is specified. Using them directly from 68 the `assert` module avoids this behavior. 69 70 The complete list of APIs is: 71 72 * assert.array 73 * assert.bool 74 * assert.buffer 75 * assert.func 76 * assert.number 77 * assert.finite 78 * assert.object 79 * assert.string 80 * assert.stream 81 * assert.date 82 * assert.regexp 83 * assert.uuid 84 * assert.arrayOfArray 85 * assert.arrayOfBool 86 * assert.arrayOfBuffer 87 * assert.arrayOfFunc 88 * assert.arrayOfNumber 89 * assert.arrayOfFinite 90 * assert.arrayOfObject 91 * assert.arrayOfString 92 * assert.arrayOfStream 93 * assert.arrayOfDate 94 * assert.arrayOfRegexp 95 * assert.arrayOfUuid 96 * assert.optionalArray 97 * assert.optionalBool 98 * assert.optionalBuffer 99 * assert.optionalFunc 100 * assert.optionalNumber 101 * assert.optionalFinite 102 * assert.optionalObject 103 * assert.optionalString 104 * assert.optionalStream 105 * assert.optionalDate 106 * assert.optionalRegexp 107 * assert.optionalUuid 108 * assert.optionalArrayOfArray 109 * assert.optionalArrayOfBool 110 * assert.optionalArrayOfBuffer 111 * assert.optionalArrayOfFunc 112 * assert.optionalArrayOfNumber 113 * assert.optionalArrayOfFinite 114 * assert.optionalArrayOfObject 115 * assert.optionalArrayOfString 116 * assert.optionalArrayOfStream 117 * assert.optionalArrayOfDate 118 * assert.optionalArrayOfRegexp 119 * assert.optionalArrayOfUuid 120 * assert.AssertionError 121 * assert.fail 122 * assert.ok 123 * assert.equal 124 * assert.notEqual 125 * assert.deepEqual 126 * assert.notDeepEqual 127 * assert.strictEqual 128 * assert.notStrictEqual 129 * assert.throws 130 * assert.doesNotThrow 131 * assert.ifError 132 133 # Installation 134 135 npm install assert-plus 136 137 ## License 138 139 The MIT License (MIT) 140 Copyright (c) 2012 Mark Cavage 141 142 Permission is hereby granted, free of charge, to any person obtaining a copy of 143 this software and associated documentation files (the "Software"), to deal in 144 the Software without restriction, including without limitation the rights to 145 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 146 the Software, and to permit persons to whom the Software is furnished to do so, 147 subject to the following conditions: 148 149 The above copyright notice and this permission notice shall be included in all 150 copies or substantial portions of the Software. 151 152 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 153 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 154 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 155 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 156 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 157 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 158 SOFTWARE. 159 160 ## Bugs 161 162 See <https://github.com/mcavage/node-assert-plus/issues>.