1 # node-error-ex [![Travis-CI.org Build Status](https://img.shields.io/travis/Qix-/node-error-ex.svg?style=flat-square)](https://travis-ci.org/Qix-/node-error-ex) [![Coveralls.io Coverage Rating](https://img.shields.io/coveralls/Qix-/node-error-ex.svg?style=flat-square)](https://coveralls.io/r/Qix-/node-error-ex)
2 > Easily subclass and customize new Error types
5 To include in your project:
7 var errorEx = require('error-ex');
10 To create an error message type with a specific name (note, that `ErrorFn.name`
11 will not reflect this):
13 var JSONError = errorEx('JSONError');
15 var err = new JSONError('error');
16 err.name; //-> JSONError
17 throw err; //-> JSONError: error
22 var JSONError = errorEx('JSONError', {fileName: errorEx.line('in %s')});
24 var err = new JSONError('error')
25 err.fileName = '/a/b/c/foo.json';
26 throw err; //-> (line 2)-> in /a/b/c/foo.json
29 To append to the error message:
31 var JSONError = errorEx('JSONError', {fileName: errorEx.append('in %s')});
33 var err = new JSONError('error');
34 err.fileName = '/a/b/c/foo.json';
35 throw err; //-> JSONError: error in /a/b/c/foo.json
40 #### `errorEx([name], [properties])`
41 Creates a new ErrorEx error type
43 - `name`: the name of the new type (appears in the error message upon throw;
44 defaults to `Error.name`)
45 - `properties`: if supplied, used as a key/value dictionary of properties to
46 use when building up the stack message. Keys are property names that are
47 looked up on the error message, and then passed to function values.
48 - `line`: if specified and is a function, return value is added as a stack
49 entry (error-ex will indent for you). Passed the property value given
51 - `stack`: if specified and is a function, passed the value of the property
52 using the key, and the raw stack lines as a second argument. Takes no
53 return value (but the stack can be modified directly).
54 - `message`: if specified and is a function, return value is used as new
55 `.message` value upon get. Passed the property value of the property named
56 by key, and the existing message is passed as the second argument as an
57 array of lines (suitable for multi-line messages).
59 Returns a constructor (Function) that can be used just like the regular Error
63 var errorEx = require('error-ex');
65 var BasicError = errorEx();
67 var NamedError = errorEx('NamedError');
71 var AdvancedError = errorEx('AdvancedError', {
73 line: function (value, stack) {
75 return 'bar ' + value;
82 var err = new AdvancedError('hello, world');
87 AdvancedError: hello, world
89 at tryReadme() (readme.js:20:1)
93 #### `errorEx.line(str)`
94 Creates a stack line using a delimiter
96 > This is a helper function. It is to be used in lieu of writing a value object
97 > for `properties` values.
99 - `str`: The string to create
100 - Use the delimiter `%s` to specify where in the string the value should go
103 var errorEx = require('error-ex');
105 var FileError = errorEx('FileError', {fileName: errorEx.line('in %s')});
107 var err = new FileError('problem reading file');
108 err.fileName = '/a/b/c/d/foo.js';
112 FileError: problem reading file
114 at tryReadme() (readme.js:7:1)
118 #### `errorEx.append(str)`
119 Appends to the `error.message` string
121 > This is a helper function. It is to be used in lieu of writing a value object
122 > for `properties` values.
124 - `str`: The string to append
125 - Use the delimiter `%s` to specify where in the string the value should go
128 var errorEx = require('error-ex');
130 var SyntaxError = errorEx('SyntaxError', {fileName: errorEx.append('in %s')});
132 var err = new SyntaxError('improper indentation');
133 err.fileName = '/a/b/c/d/foo.js';
137 SyntaxError: improper indentation in /a/b/c/d/foo.js
138 at tryReadme() (readme.js:7:1)
143 Licensed under the [MIT License](http://opensource.org/licenses/MIT).
144 You can find a copy of it in [LICENSE](LICENSE).