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