www.aleph1.co.uk Git - yaffs-website/blob - node_modules/assert-plus/README.md

   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.object
  78 * assert.string
  79 * assert.stream
  80 * assert.date
  81 * assert.regex
  82 * assert.uuid
  83 * assert.arrayOfArray
  84 * assert.arrayOfBool
  85 * assert.arrayOfBuffer
  86 * assert.arrayOfFunc
  87 * assert.arrayOfNumber
  88 * assert.arrayOfObject
  89 * assert.arrayOfString
  90 * assert.arrayOfStream
  91 * assert.arrayOfDate
  92 * assert.arrayOfUuid
  93 * assert.optionalArray
  94 * assert.optionalBool
  95 * assert.optionalBuffer
  96 * assert.optionalFunc
  97 * assert.optionalNumber
  98 * assert.optionalObject
  99 * assert.optionalString
 100 * assert.optionalStream
 101 * assert.optionalDate
 102 * assert.optionalUuid
 103 * assert.optionalArrayOfArray
 104 * assert.optionalArrayOfBool
 105 * assert.optionalArrayOfBuffer
 106 * assert.optionalArrayOfFunc
 107 * assert.optionalArrayOfNumber
 108 * assert.optionalArrayOfObject
 109 * assert.optionalArrayOfString
 110 * assert.optionalArrayOfStream
 111 * assert.optionalArrayOfDate
 112 * assert.optionalArrayOfUuid
 113 * assert.AssertionError
 114 * assert.fail
 115 * assert.ok
 116 * assert.equal
 117 * assert.notEqual
 118 * assert.deepEqual
 119 * assert.notDeepEqual
 120 * assert.strictEqual
 121 * assert.notStrictEqual
 122 * assert.throws
 123 * assert.doesNotThrow
 124 * assert.ifError
 125
 126 # Installation
 127
 128     npm install assert-plus
 129
 130 ## License
 131
 132 The MIT License (MIT)
 133 Copyright (c) 2012 Mark Cavage
 134
 135 Permission is hereby granted, free of charge, to any person obtaining a copy of
 136 this software and associated documentation files (the "Software"), to deal in
 137 the Software without restriction, including without limitation the rights to
 138 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 139 the Software, and to permit persons to whom the Software is furnished to do so,
 140 subject to the following conditions:
 141
 142 The above copyright notice and this permission notice shall be included in all
 143 copies or substantial portions of the Software.
 144
 145 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 146 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 147 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 148 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 149 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 150 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 151 SOFTWARE.
 152
 153 ## Bugs
 154
 155 See <https://github.com/mcavage/node-assert-plus/issues>.