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
|
3 |
|
4 | ## Examples
|
5 | To include in your project:
|
6 | ```javascript
|
7 | var errorEx = require('error-ex');
|
8 | ```
|
9 |
|
10 | To create an error message type with a specific name (note, that `ErrorFn.name`
|
11 | will not reflect this):
|
12 | ```javascript
|
13 | var JSONError = errorEx('JSONError');
|
14 |
|
15 | var err = new JSONError('error');
|
16 | err.name; //-> JSONError
|
17 | throw err; //-> JSONError: error
|
18 | ```
|
19 |
|
20 | To add a stack line:
|
21 | ```javascript
|
22 | var JSONError = errorEx('JSONError', {fileName: errorEx.line('in %s')});
|
23 |
|
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
|
27 | ```
|
28 |
|
29 | To append to the error message:
|
30 | ```javascript
|
31 | var JSONError = errorEx('JSONError', {fileName: errorEx.append('in %s')});
|
32 |
|
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
|
36 | ```
|
37 |
|
38 | ## API
|
39 |
|
40 | #### `errorEx([name], [properties])`
|
41 | Creates a new ErrorEx error type
|
42 |
|
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
|
50 | the key.
|
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).
|
58 |
|
59 | Returns a constructor (Function) that can be used just like the regular Error
|
60 | constructor.
|
61 |
|
62 | ```javascript
|
63 | var errorEx = require('error-ex');
|
64 |
|
65 | var BasicError = errorEx();
|
66 |
|
67 | var NamedError = errorEx('NamedError');
|
68 |
|
69 | // --
|
70 |
|
71 | var AdvancedError = errorEx('AdvancedError', {
|
72 | foo: {
|
73 | line: function (value, stack) {
|
74 | if (value) {
|
75 | return 'bar ' + value;
|
76 | }
|
77 | return null;
|
78 | }
|
79 | }
|
80 | }
|
81 |
|
82 | var err = new AdvancedError('hello, world');
|
83 | err.foo = 'baz';
|
84 | throw err;
|
85 |
|
86 | /*
|
87 | AdvancedError: hello, world
|
88 | bar baz
|
89 | at tryReadme() (readme.js:20:1)
|
90 | */
|
91 | ```
|
92 |
|
93 | #### `errorEx.line(str)`
|
94 | Creates a stack line using a delimiter
|
95 |
|
96 | > This is a helper function. It is to be used in lieu of writing a value object
|
97 | > for `properties` values.
|
98 |
|
99 | - `str`: The string to create
|
100 | - Use the delimiter `%s` to specify where in the string the value should go
|
101 |
|
102 | ```javascript
|
103 | var errorEx = require('error-ex');
|
104 |
|
105 | var FileError = errorEx('FileError', {fileName: errorEx.line('in %s')});
|
106 |
|
107 | var err = new FileError('problem reading file');
|
108 | err.fileName = '/a/b/c/d/foo.js';
|
109 | throw err;
|
110 |
|
111 | /*
|
112 | FileError: problem reading file
|
113 | in /a/b/c/d/foo.js
|
114 | at tryReadme() (readme.js:7:1)
|
115 | */
|
116 | ```
|
117 |
|
118 | #### `errorEx.append(str)`
|
119 | Appends to the `error.message` string
|
120 |
|
121 | > This is a helper function. It is to be used in lieu of writing a value object
|
122 | > for `properties` values.
|
123 |
|
124 | - `str`: The string to append
|
125 | - Use the delimiter `%s` to specify where in the string the value should go
|
126 |
|
127 | ```javascript
|
128 | var errorEx = require('error-ex');
|
129 |
|
130 | var SyntaxError = errorEx('SyntaxError', {fileName: errorEx.append('in %s')});
|
131 |
|
132 | var err = new SyntaxError('improper indentation');
|
133 | err.fileName = '/a/b/c/d/foo.js';
|
134 | throw err;
|
135 |
|
136 | /*
|
137 | SyntaxError: improper indentation in /a/b/c/d/foo.js
|
138 | at tryReadme() (readme.js:7:1)
|
139 | */
|
140 | ```
|
141 |
|
142 | ## License
|
143 | Licensed under the [MIT License](http://opensource.org/licenses/MIT).
|
144 | You can find a copy of it in [LICENSE](LICENSE).
|