Name: js-handler/node_modules/restify/node_modules/verror/README.md 
1:
# verror: richer JavaScript errors
2:
 
3:
This module provides two classes: VError, for accretive errors, and WError, for
4:
wrapping errors.  Both support printf-style error messages using extsprintf.
5:
 
6:
## Printf-style errors
7:
 
8:
At the most basic level, VError is just like JavaScript's Error class, but with
9:
printf-style arguments:
10:
 
11:
    var verror = require('verror');
12:
 
13:
    var opname = 'read';
14:
    var err = new verror.VError('"%s" operation failed', opname);
15:
    console.log(err.message);
16:
    console.log(err.stack);
17:
 
18:
This prints:
19:
 
20:
    "read" operation failed
21:
    "read" operation failed
22:
        at Object.<anonymous> (/Users/dap/node-verror/examples/varargs.js:4:11)
23:
        at Module._compile (module.js:449:26)
24:
        at Object.Module._extensions..js (module.js:467:10)
25:
        at Module.load (module.js:356:32)
26:
        at Function.Module._load (module.js:312:12)
27:
        at Module.runMain (module.js:492:10)
28:
        at process.startup.processNextTick.process._tickCallback (node.js:244:9)
29:
 
30:
 
31:
## VError for accretive error messages
32:
 
33:
More interestingly, you can use VError to build up an error describing what
34:
happened at various levels in the stack.  For example, suppose you have a
35:
request handler that stats a file and fails if it doesn't exist:
36:
 
37:
    var fs = require('fs');
38:
    var verror = require('verror');
39:
 
40:
    function checkFile(filename, callback) {
41:
        fs.stat(filename, function (err) {
42:
            if (err)
43:
    /* Annotate the "stat" error with what we were doing. */
44:
        return (callback(new verror.VError(err,
45:
        'failed to check "%s"', filename)));
46:
 
47:
      /* ... */
48:
        });
49:
    }
50:
 
51:
    function handleRequest(filename, callback) {
52:
      checkFile('/nonexistent', function (err) {
53:
          if (err) {
54:
            /* Annotate the "checkFile" error with what we were doing. */
55:
            return (callback(new verror.VError(err, 'request failed')));
56:
          }
57:
 
58:
          /* ... */
59:
      });
60:
    }
61:
 
62:
    handleRequest('/nonexistent', function (err) {
63:
  if (err)
64:
    console.log(err.message);
65:
  /* ... */
66:
    });
67:
 
68:
Since the file "/nonexistent" doesn't exist, this prints out:
69:
 
70:
    request failed: failed to check "/nonexistent": ENOENT, stat '/nonexistent'
71:
 
72:
The idea here is that the lowest level (Node's "fs.stat" function) generates an
73:
arbitrary error, and each higher level (request handler and stat callback)
74:
creates a new VError that annotates the previous error with what it was doing,
75:
so that the result is a clear message explaining what failed at each level.
76:
 
77:
This plays nicely with extsprintf's "%r" specifier, which prints out a
78:
Java-style stacktrace with the whole chain of exceptions:
79:
 
80:
    EXCEPTION: VError: request failed: failed to check "/nonexistent": ENOENT, stat '/nonexistent'
81:
        at /Users/dap/work/node-verror/examples/levels.js:21:21
82:
        at /Users/dap/work/node-verror/examples/levels.js:9:12
83:
        at Object.oncomplete (fs.js:297:15)
84:
    Caused by: EXCEPTION: VError: failed to check "/nonexistent": ENOENT, stat '/nonexistent'
85:
        at /Users/dap/work/node-verror/examples/levels.js:9:21
86:
        at Object.oncomplete (fs.js:297:15)
87:
    Caused by: EXCEPTION: Error: Error: ENOENT, stat '/nonexistent'
88:
 
89:
 
90:
## WError for wrapped errors
91:
 
92:
Sometimes you don't want an Error's "message" field to include the details of
93:
all of the low-level errors, but you still want to be able to get at them
94:
programmatically.  For example, in an HTTP server, you probably don't want to
95:
spew all of the low-level errors back to the client, but you do want to include
96:
them in the audit log entry for the request.  In that case, you can use a
97:
WError, which is created exactly like VError (and also supports both
98:
printf-style arguments and an optional cause), but the resulting "message" only
99:
contains the top-level error.  It's also more verbose, including the class
100:
associated with each error in the cause chain.  Using the same example above,
101:
but replacing the VError in handleRequest with WError, we get this output:
102:
 
103:
    request failed
104:
 
105:
That's what we wanted -- just a high-level summary for the client.  But we can
106:
get the object's toString() for the full details:
107:
 
108:
    WError: request failed; caused by WError: failed to check "/nonexistent";
109:
    caused by Error: ENOENT, stat '/nonexistent'
110:
 
111:
# Contributing
112:
 
113:
Contributions welcome.  Code should be "make check" clean.  To run "make check",
114:
you'll need these tools:
115:
 
116:
* https://github.com/davepacheco/jsstyle
117:
* https://github.com/davepacheco/javascriptlint
118:
 
119:
If you're changing something non-trivial or user-facing, you may want to submit
120:
an issue first.