www.aleph1.co.uk Git - yaffs-website/blob - node_modules/getpass/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.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>.