README.md
1# assert-plus
2
3This library is a super small wrapper over node's assert module that has two
4things: (1) the ability to disable assertions with the environment variable
5NODE\_NDEBUG, and (2) some API wrappers for argument testing. Like
6`assert.string(myArg, 'myArg')`. As a simple example, most of my code looks
7like 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
27All methods that *aren't* part of node's core assert API are simply assumed to
28take an argument, and then a string 'name' that's not a message; `AssertionError`
29will 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
41from:
42
43```javascript
44 function test(foo) {
45 assert.string(foo, 'foo');
46 }
47```
48
49There 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
57You can assert IFF an argument is not `undefined` (i.e., an optional arg):
58
59```javascript
60 assert.optionalString(foo, 'foo');
61```
62
63Lastly, you can opt-out of assertion checking altogether by setting the
64environment variable `NODE_NDEBUG=1`. This is pseudo-useful if you have
65lots of assertions, and don't want to pay `typeof ()` taxes to v8 in
66production. Be advised: The standard functions re-exported from `assert` are
67also disabled in assert-plus if NDEBUG is specified. Using them directly from
68the `assert` module avoids this behavior.
69
70The 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
139The MIT License (MIT)
140Copyright (c) 2012 Mark Cavage
141
142Permission is hereby granted, free of charge, to any person obtaining a copy of
143this software and associated documentation files (the "Software"), to deal in
144the Software without restriction, including without limitation the rights to
145use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
146the Software, and to permit persons to whom the Software is furnished to do so,
147subject to the following conditions:
148
149The above copyright notice and this permission notice shall be included in all
150copies or substantial portions of the Software.
151
152THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
153IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
154FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
155AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
156LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
157OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
158SOFTWARE.
159
160## Bugs
161
162See <https://github.com/mcavage/node-assert-plus/issues>.
163