Name |
Date |
Size |
#Lines |
LOC |
||
---|---|---|---|---|---|---|
.. | - | - | ||||
lib/ | 12-May-2024 | - | 452 | 252 | ||
.npmignore | D | 12-May-2024 | 91 | 10 | 9 | |
CHANGES.md | D | 12-May-2024 | 505 | 29 | 16 | |
LICENSE | D | 12-May-2024 | 1.1 KiB | 20 | 16 | |
README.md | D | 12-May-2024 | 20.6 KiB | 529 | 399 | |
package.json | D | 12-May-2024 | 1.3 KiB | 52 | 51 |
README.md
1# verror: rich JavaScript errors 2 3This module provides several classes in support of Joyent's [Best Practices for 4Error Handling in Node.js](http://www.joyent.com/developers/node/design/errors). 5If you find any of the behavior here confusing or surprising, check out that 6document first. 7 8The error classes here support: 9 10* printf-style arguments for the message 11* chains of causes 12* properties to provide extra information about the error 13* creating your own subclasses that support all of these 14 15The classes here are: 16 17* **VError**, for chaining errors while preserving each one's error message. 18 This is useful in servers and command-line utilities when you want to 19 propagate an error up a call stack, but allow various levels to add their own 20 context. See examples below. 21* **WError**, for wrapping errors while hiding the lower-level messages from the 22 top-level error. This is useful for API endpoints where you don't want to 23 expose internal error messages, but you still want to preserve the error chain 24 for logging and debugging. 25* **SError**, which is just like VError but interprets printf-style arguments 26 more strictly. 27* **MultiError**, which is just an Error that encapsulates one or more other 28 errors. (This is used for parallel operations that return several errors.) 29 30 31# Quick start 32 33First, install the package: 34 35 npm install verror 36 37If nothing else, you can use VError as a drop-in replacement for the built-in 38JavaScript Error class, with the addition of printf-style messages: 39 40```javascript 41var err = new VError('missing file: "%s"', '/etc/passwd'); 42console.log(err.message); 43``` 44 45This prints: 46 47 missing file: "/etc/passwd" 48 49You can also pass a `cause` argument, which is any other Error object: 50 51```javascript 52var fs = require('fs'); 53var filename = '/nonexistent'; 54fs.stat(filename, function (err1) { 55 var err2 = new VError(err1, 'stat "%s"', filename); 56 console.error(err2.message); 57}); 58``` 59 60This prints out: 61 62 stat "/nonexistent": ENOENT, stat '/nonexistent' 63 64which resembles how Unix programs typically report errors: 65 66 $ sort /nonexistent 67 sort: open failed: /nonexistent: No such file or directory 68 69To match the Unixy feel, when you print out the error, just prepend the 70program's name to the VError's `message`. Or just call 71[node-cmdutil.fail(your_verror)](https://github.com/joyent/node-cmdutil), which 72does this for you. 73 74You can get the next-level Error using `err.cause()`: 75 76```javascript 77console.error(err2.cause().message); 78``` 79 80prints: 81 82 ENOENT, stat '/nonexistent' 83 84Of course, you can chain these as many times as you want, and it works with any 85kind of Error: 86 87```javascript 88var err1 = new Error('No such file or directory'); 89var err2 = new VError(err1, 'failed to stat "%s"', '/junk'); 90var err3 = new VError(err2, 'request failed'); 91console.error(err3.message); 92``` 93 94This prints: 95 96 request failed: failed to stat "/junk": No such file or directory 97 98The idea is that each layer in the stack annotates the error with a description 99of what it was doing. The end result is a message that explains what happened 100at each level. 101 102You can also decorate Error objects with additional information so that callers 103can not only handle each kind of error differently, but also construct their own 104error messages (e.g., to localize them, format them, group them by type, and so 105on). See the example below. 106 107 108# Deeper dive 109 110The two main goals for VError are: 111 112* **Make it easy to construct clear, complete error messages intended for 113 people.** Clear error messages greatly improve both user experience and 114 debuggability, so we wanted to make it easy to build them. That's why the 115 constructor takes printf-style arguments. 116* **Make it easy to construct objects with programmatically-accessible 117 metadata** (which we call _informational properties_). Instead of just saying 118 "connection refused while connecting to 192.168.1.2:80", you can add 119 properties like `"ip": "192.168.1.2"` and `"tcpPort": 80`. This can be used 120 for feeding into monitoring systems, analyzing large numbers of Errors (as 121 from a log file), or localizing error messages. 122 123To really make this useful, it also needs to be easy to compose Errors: 124higher-level code should be able to augment the Errors reported by lower-level 125code to provide a more complete description of what happened. Instead of saying 126"connection refused", you can say "operation X failed: connection refused". 127That's why VError supports `causes`. 128 129In order for all this to work, programmers need to know that it's generally safe 130to wrap lower-level Errors with higher-level ones. If you have existing code 131that handles Errors produced by a library, you should be able to wrap those 132Errors with a VError to add information without breaking the error handling 133code. There are two obvious ways that this could break such consumers: 134 135* The error's name might change. People typically use `name` to determine what 136 kind of Error they've got. To ensure compatibility, you can create VErrors 137 with custom names, but this approach isn't great because it prevents you from 138 representing complex failures. For this reason, VError provides 139 `findCauseByName`, which essentially asks: does this Error _or any of its 140 causes_ have this specific type? If error handling code uses 141 `findCauseByName`, then subsystems can construct very specific causal chains 142 for debuggability and still let people handle simple cases easily. There's an 143 example below. 144* The error's properties might change. People often hang additional properties 145 off of Error objects. If we wrap an existing Error in a new Error, those 146 properties would be lost unless we copied them. But there are a variety of 147 both standard and non-standard Error properties that should _not_ be copied in 148 this way: most obviously `name`, `message`, and `stack`, but also `fileName`, 149 `lineNumber`, and a few others. Plus, it's useful for some Error subclasses 150 to have their own private properties -- and there'd be no way to know whether 151 these should be copied. For these reasons, VError first-classes these 152 information properties. You have to provide them in the constructor, you can 153 only fetch them with the `info()` function, and VError takes care of making 154 sure properties from causes wind up in the `info()` output. 155 156Let's put this all together with an example from the node-fast RPC library. 157node-fast implements a simple RPC protocol for Node programs. There's a server 158and client interface, and clients make RPC requests to servers. Let's say the 159server fails with an UnauthorizedError with message "user 'bob' is not 160authorized". The client wraps all server errors with a FastServerError. The 161client also wraps all request errors with a FastRequestError that includes the 162name of the RPC call being made. The result of this failed RPC might look like 163this: 164 165 name: FastRequestError 166 message: "request failed: server error: user 'bob' is not authorized" 167 rpcMsgid: <unique identifier for this request> 168 rpcMethod: GetObject 169 cause: 170 name: FastServerError 171 message: "server error: user 'bob' is not authorized" 172 cause: 173 name: UnauthorizedError 174 message: "user 'bob' is not authorized" 175 rpcUser: "bob" 176 177When the caller uses `VError.info()`, the information properties are collapsed 178so that it looks like this: 179 180 message: "request failed: server error: user 'bob' is not authorized" 181 rpcMsgid: <unique identifier for this request> 182 rpcMethod: GetObject 183 rpcUser: "bob" 184 185Taking this apart: 186 187* The error's message is a complete description of the problem. The caller can 188 report this directly to its caller, which can potentially make its way back to 189 an end user (if appropriate). It can also be logged. 190* The caller can tell that the request failed on the server, rather than as a 191 result of a client problem (e.g., failure to serialize the request), a 192 transport problem (e.g., failure to connect to the server), or something else 193 (e.g., a timeout). They do this using `findCauseByName('FastServerError')` 194 rather than checking the `name` field directly. 195* If the caller logs this error, the logs can be analyzed to aggregate 196 errors by cause, by RPC method name, by user, or whatever. Or the 197 error can be correlated with other events for the same rpcMsgid. 198* It wasn't very hard for any part of the code to contribute to this Error. 199 Each part of the stack has just a few lines to provide exactly what it knows, 200 with very little boilerplate. 201 202It's not expected that you'd use these complex forms all the time. Despite 203supporting the complex case above, you can still just do: 204 205 new VError("my service isn't working"); 206 207for the simple cases. 208 209 210# Reference: VError, WError, SError 211 212VError, WError, and SError are convenient drop-in replacements for `Error` that 213support printf-style arguments, first-class causes, informational properties, 214and other useful features. 215 216 217## Constructors 218 219The VError constructor has several forms: 220 221```javascript 222/* 223 * This is the most general form. You can specify any supported options 224 * (including "cause" and "info") this way. 225 */ 226new VError(options, sprintf_args...) 227 228/* 229 * This is a useful shorthand when the only option you need is "cause". 230 */ 231new VError(cause, sprintf_args...) 232 233/* 234 * This is a useful shorthand when you don't need any options at all. 235 */ 236new VError(sprintf_args...) 237``` 238 239All of these forms construct a new VError that behaves just like the built-in 240JavaScript `Error` class, with some additional methods described below. 241 242In the first form, `options` is a plain object with any of the following 243optional properties: 244 245Option name | Type | Meaning 246---------------- | ---------------- | ------- 247`name` | string | Describes what kind of error this is. This is intended for programmatic use to distinguish between different kinds of errors. Note that in modern versions of Node.js, this name is ignored in the `stack` property value, but callers can still use the `name` property to get at it. 248`cause` | any Error object | Indicates that the new error was caused by `cause`. See `cause()` below. If unspecified, the cause will be `null`. 249`strict` | boolean | If true, then `null` and `undefined` values in `sprintf_args` are passed through to `sprintf()`. Otherwise, these are replaced with the strings `'null'`, and '`undefined`', respectively. 250`constructorOpt` | function | If specified, then the stack trace for this error ends at function `constructorOpt`. Functions called by `constructorOpt` will not show up in the stack. This is useful when this class is subclassed. 251`info` | object | Specifies arbitrary informational properties that are available through the `VError.info(err)` static class method. See that method for details. 252 253The second form is equivalent to using the first form with the specified `cause` 254as the error's cause. This form is distinguished from the first form because 255the first argument is an Error. 256 257The third form is equivalent to using the first form with all default option 258values. This form is distinguished from the other forms because the first 259argument is not an object or an Error. 260 261The `WError` constructor is used exactly the same way as the `VError` 262constructor. The `SError` constructor is also used the same way as the 263`VError` constructor except that in all cases, the `strict` property is 264overriden to `true. 265 266 267## Public properties 268 269`VError`, `WError`, and `SError` all provide the same public properties as 270JavaScript's built-in Error objects. 271 272Property name | Type | Meaning 273------------- | ------ | ------- 274`name` | string | Programmatically-usable name of the error. 275`message` | string | Human-readable summary of the failure. Programmatically-accessible details are provided through `VError.info(err)` class method. 276`stack` | string | Human-readable stack trace where the Error was constructed. 277 278For all of these classes, the printf-style arguments passed to the constructor 279are processed with `sprintf()` to form a message. For `WError`, this becomes 280the complete `message` property. For `SError` and `VError`, this message is 281prepended to the message of the cause, if any (with a suitable separator), and 282the result becomes the `message` property. 283 284The `stack` property is managed entirely by the underlying JavaScript 285implementation. It's generally implemented using a getter function because 286constructing the human-readable stack trace is somewhat expensive. 287 288## Class methods 289 290The following methods are defined on the `VError` class and as exported 291functions on the `verror` module. They're defined this way rather than using 292methods on VError instances so that they can be used on Errors not created with 293`VError`. 294 295### `VError.cause(err)` 296 297The `cause()` function returns the next Error in the cause chain for `err`, or 298`null` if there is no next error. See the `cause` argument to the constructor. 299Errors can have arbitrarily long cause chains. You can walk the `cause` chain 300by invoking `VError.cause(err)` on each subsequent return value. If `err` is 301not a `VError`, the cause is `null`. 302 303### `VError.info(err)` 304 305Returns an object with all of the extra error information that's been associated 306with this Error and all of its causes. These are the properties passed in using 307the `info` option to the constructor. Properties not specified in the 308constructor for this Error are implicitly inherited from this error's cause. 309 310These properties are intended to provide programmatically-accessible metadata 311about the error. For an error that indicates a failure to resolve a DNS name, 312informational properties might include the DNS name to be resolved, or even the 313list of resolvers used to resolve it. The values of these properties should 314generally be plain objects (i.e., consisting only of null, undefined, numbers, 315booleans, strings, and objects and arrays containing only other plain objects). 316 317### `VError.fullStack(err)` 318 319Returns a string containing the full stack trace, with all nested errors recursively 320reported as `'caused by:' + err.stack`. 321 322### `VError.findCauseByName(err, name)` 323 324The `findCauseByName()` function traverses the cause chain for `err`, looking 325for an error whose `name` property matches the passed in `name` value. If no 326match is found, `null` is returned. 327 328If all you want is to know _whether_ there's a cause (and you don't care what it 329is), you can use `VError.hasCauseWithName(err, name)`. 330 331If a vanilla error or a non-VError error is passed in, then there is no cause 332chain to traverse. In this scenario, the function will check the `name` 333property of only `err`. 334 335### `VError.hasCauseWithName(err, name)` 336 337Returns true if and only if `VError.findCauseByName(err, name)` would return 338a non-null value. This essentially determines whether `err` has any cause in 339its cause chain that has name `name`. 340 341### `VError.errorFromList(errors)` 342 343Given an array of Error objects (possibly empty), return a single error 344representing the whole collection of errors. If the list has: 345 346* 0 elements, returns `null` 347* 1 element, returns the sole error 348* more than 1 element, returns a MultiError referencing the whole list 349 350This is useful for cases where an operation may produce any number of errors, 351and you ultimately want to implement the usual `callback(err)` pattern. You can 352accumulate the errors in an array and then invoke 353`callback(VError.errorFromList(errors))` when the operation is complete. 354 355 356### `VError.errorForEach(err, func)` 357 358Convenience function for iterating an error that may itself be a MultiError. 359 360In all cases, `err` must be an Error. If `err` is a MultiError, then `func` is 361invoked as `func(errorN)` for each of the underlying errors of the MultiError. 362If `err` is any other kind of error, `func` is invoked once as `func(err)`. In 363all cases, `func` is invoked synchronously. 364 365This is useful for cases where an operation may produce any number of warnings 366that may be encapsulated with a MultiError -- but may not be. 367 368This function does not iterate an error's cause chain. 369 370 371## Examples 372 373The "Demo" section above covers several basic cases. Here's a more advanced 374case: 375 376```javascript 377var err1 = new VError('something bad happened'); 378/* ... */ 379var err2 = new VError({ 380 'name': 'ConnectionError', 381 'cause': err1, 382 'info': { 383 'errno': 'ECONNREFUSED', 384 'remote_ip': '127.0.0.1', 385 'port': 215 386 } 387}, 'failed to connect to "%s:%d"', '127.0.0.1', 215); 388 389console.log(err2.message); 390console.log(err2.name); 391console.log(VError.info(err2)); 392console.log(err2.stack); 393``` 394 395This outputs: 396 397 failed to connect to "127.0.0.1:215": something bad happened 398 ConnectionError 399 { errno: 'ECONNREFUSED', remote_ip: '127.0.0.1', port: 215 } 400 ConnectionError: failed to connect to "127.0.0.1:215": something bad happened 401 at Object.<anonymous> (/home/dap/node-verror/examples/info.js:5:12) 402 at Module._compile (module.js:456:26) 403 at Object.Module._extensions..js (module.js:474:10) 404 at Module.load (module.js:356:32) 405 at Function.Module._load (module.js:312:12) 406 at Function.Module.runMain (module.js:497:10) 407 at startup (node.js:119:16) 408 at node.js:935:3 409 410Information properties are inherited up the cause chain, with values at the top 411of the chain overriding same-named values lower in the chain. To continue that 412example: 413 414```javascript 415var err3 = new VError({ 416 'name': 'RequestError', 417 'cause': err2, 418 'info': { 419 'errno': 'EBADREQUEST' 420 } 421}, 'request failed'); 422 423console.log(err3.message); 424console.log(err3.name); 425console.log(VError.info(err3)); 426console.log(err3.stack); 427``` 428 429This outputs: 430 431 request failed: failed to connect to "127.0.0.1:215": something bad happened 432 RequestError 433 { errno: 'EBADREQUEST', remote_ip: '127.0.0.1', port: 215 } 434 RequestError: request failed: failed to connect to "127.0.0.1:215": something bad happened 435 at Object.<anonymous> (/home/dap/node-verror/examples/info.js:20:12) 436 at Module._compile (module.js:456:26) 437 at Object.Module._extensions..js (module.js:474:10) 438 at Module.load (module.js:356:32) 439 at Function.Module._load (module.js:312:12) 440 at Function.Module.runMain (module.js:497:10) 441 at startup (node.js:119:16) 442 at node.js:935:3 443 444You can also print the complete stack trace of combined `Error`s by using 445`VError.fullStack(err).` 446 447```javascript 448var err1 = new VError('something bad happened'); 449/* ... */ 450var err2 = new VError(err1, 'something really bad happened here'); 451 452console.log(VError.fullStack(err2)); 453``` 454 455This outputs: 456 457 VError: something really bad happened here: something bad happened 458 at Object.<anonymous> (/home/dap/node-verror/examples/fullStack.js:5:12) 459 at Module._compile (module.js:409:26) 460 at Object.Module._extensions..js (module.js:416:10) 461 at Module.load (module.js:343:32) 462 at Function.Module._load (module.js:300:12) 463 at Function.Module.runMain (module.js:441:10) 464 at startup (node.js:139:18) 465 at node.js:968:3 466 caused by: VError: something bad happened 467 at Object.<anonymous> (/home/dap/node-verror/examples/fullStack.js:3:12) 468 at Module._compile (module.js:409:26) 469 at Object.Module._extensions..js (module.js:416:10) 470 at Module.load (module.js:343:32) 471 at Function.Module._load (module.js:300:12) 472 at Function.Module.runMain (module.js:441:10) 473 at startup (node.js:139:18) 474 at node.js:968:3 475 476`VError.fullStack` is also safe to use on regular `Error`s, so feel free to use 477it whenever you need to extract the stack trace from an `Error`, regardless if 478it's a `VError` or not. 479 480# Reference: MultiError 481 482MultiError is an Error class that represents a group of Errors. This is used 483when you logically need to provide a single Error, but you want to preserve 484information about multiple underying Errors. A common case is when you execute 485several operations in parallel and some of them fail. 486 487MultiErrors are constructed as: 488 489```javascript 490new MultiError(error_list) 491``` 492 493`error_list` is an array of at least one `Error` object. 494 495The cause of the MultiError is the first error provided. None of the other 496`VError` options are supported. The `message` for a MultiError consists the 497`message` from the first error, prepended with a message indicating that there 498were other errors. 499 500For example: 501 502```javascript 503err = new MultiError([ 504 new Error('failed to resolve DNS name "abc.example.com"'), 505 new Error('failed to resolve DNS name "def.example.com"'), 506]); 507 508console.error(err.message); 509``` 510 511outputs: 512 513 first of 2 errors: failed to resolve DNS name "abc.example.com" 514 515See the convenience function `VError.errorFromList`, which is sometimes simpler 516to use than this constructor. 517 518## Public methods 519 520 521### `errors()` 522 523Returns an array of the errors used to construct this MultiError. 524 525 526# Contributing 527 528See separate [contribution guidelines](CONTRIBUTING.md). 529