0
# VError
1

2
VError provides enhanced JavaScript error classes that support printf-style error messages, error chaining with causes, and programmatically-accessible metadata properties. It includes multiple error classes designed for different use cases and a comprehensive set of static utility methods for error handling and analysis.
3

4
## Package Information
5

6
- **Package Name**: verror
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install verror`
10

11
## Core Imports
12

13
```javascript
14
const VError = require('verror');
15
```
16

17
Access to other error classes:
18

19
```javascript
20
const VError = require('verror');
21
const SError = VError.SError;
22
const WError = VError.WError;
23
const MultiError = VError.MultiError;
24
```
25

26
## Basic Usage
27

28
```javascript
29
const VError = require('verror');
30

31
// Basic error with printf-style message
32
const err1 = new VError('missing file: "%s"', '/etc/passwd');
33
console.log(err1.message); // "missing file: "/etc/passwd""
34

35
// Error chaining with cause
36
const fs = require('fs');
37
fs.stat('/nonexistent', function (originalErr) {
38
    const err2 = new VError(originalErr, 'stat "%s" failed', '/nonexistent');
39
    console.log(err2.message); // "stat "/nonexistent" failed: ENOENT, stat '/nonexistent'"
40
    console.log(VError.cause(err2)); // Returns originalErr
41
});
42

43
// Error with metadata
44
const err3 = new VError({
45
    name: 'ConnectionError',
46
    cause: originalErr,
47
    info: { 
48
        hostname: '127.0.0.1', 
49
        port: 80,
50
        errno: 'ECONNREFUSED'
51
    }
52
}, 'connection failed to %s:%d', '127.0.0.1', 80);
53

54
console.log(VError.info(err3)); // Returns merged info from entire cause chain
55
```
56

57
## Architecture
58

59
VError is built around several key components:
60

61
- **Error Classes**: Four specialized error classes (VError, SError, WError, MultiError) with different behaviors for message handling and cause display
62
- **Cause Chaining**: Systematic error chaining that preserves original error information while adding contextual messages
63
- **Metadata System**: Structured information properties that can be attached to errors and retrieved programmatically
64
- **Static Utilities**: Comprehensive set of utility methods for error analysis, cause traversal, and error manipulation
65
- **Printf Integration**: Built-in printf-style message formatting with configurable strictness
66

67
## Capabilities
68

69
### VError Class
70

71
Primary error class for chaining errors while preserving each error's message. Supports printf-style formatting and flexible constructor options.
72

73
```javascript { .api }
74
/**
75
 * Main error constructor with multiple signatures
76
 * @param {Error|Object|string} [causeOrOptionsOrMessage] - Cause error, options object, or message
77
 * @param {...*} args - Printf-style arguments for message formatting
78
 */
79
function VError(causeOrOptionsOrMessage, ...args);
80

81
// Constructor options
82
interface VErrorOptions {
83
    cause?: Error;              // Underlying cause error
84
    name?: string;              // Error name override
85
    info?: Object;              // Additional structured metadata
86
    skipCauseMessage?: boolean; // Skip appending cause message
87
    strict?: boolean;           // Force strict printf interpretation (like SError)
88
    constructorOpt?: Function;  // Constructor for stack trace capture
89
}
90
```
91

92
[VError Class](./verror-class.md)
93

94
### SError Class
95

96
Strict version of VError that enforces strict printf argument interpretation, throwing errors for null/undefined values instead of converting them to strings.
97

98
```javascript { .api }
99
/**
100
 * Strict error constructor - same signatures as VError but with strict printf parsing
101
 * @param {Error|Object|string} [causeOrOptionsOrMessage] - Cause error, options object, or message
102
 * @param {...*} args - Printf-style arguments (strict interpretation)
103
 */
104
function SError(causeOrOptionsOrMessage, ...args);
105
```
106

107
[Error Classes](./error-classes.md)
108

109
### WError Class
110

111
Wrapped error class that hides lower-level error messages from the top-level error while preserving the error chain for debugging.
112

113
```javascript { .api }
114
/**
115
 * Wrapping error constructor that hides cause messages
116
 * @param {Error|Object|string} [causeOrOptionsOrMessage] - Cause error, options object, or message
117
 * @param {...*} args - Printf-style arguments for message formatting
118
 */
119
function WError(causeOrOptionsOrMessage, ...args);
120
```
121

122
[Error Classes](./error-classes.md)
123

124
### MultiError Class
125

126
Container for multiple errors, useful for parallel operations that may generate multiple errors that need to be reported together.
127

128
```javascript { .api }
129
/**
130
 * Multi-error container constructor
131
 * @param {Error[]} errors - Array of Error objects (at least 1 required)
132
 */
133
function MultiError(errors);
134

135
interface MultiError {
136
    /** Returns copy of the errors array */
137
    errors(): Error[];
138
}
139
```
140

141
[Error Classes](./error-classes.md)
142

143
### Static Utility Methods
144

145
Comprehensive set of utility methods for error analysis, cause traversal, and error manipulation that work with any Error objects.
146

147
```javascript { .api }
148
/**
149
 * Get the cause of any Error object
150
 * @param {Error} err - Error to inspect
151
 * @returns {Error|null} Cause error or null if no cause
152
 */
153
VError.cause(err);
154

155
/**
156
 * Get accumulated info properties from entire error chain
157
 * @param {Error} err - Error to inspect  
158
 * @returns {Object} Merged info properties from cause chain
159
 */
160
VError.info(err);
161

162
/**
163
 * Find first error in cause chain with specific name
164
 * @param {Error} err - Error to search from
165
 * @param {string} name - Error name to find
166
 * @returns {Error|null} First matching error or null
167
 */
168
VError.findCauseByName(err, name);
169

170
/**
171
 * Check if cause chain contains error with specific name
172
 * @param {Error} err - Error to search from
173
 * @param {string} name - Error name to find  
174
 * @returns {boolean} True if found
175
 */
176
VError.hasCauseWithName(err, name);
177
```
178

179
[Static Utilities](./static-utilities.md)
180

181
## Types
182

183
```javascript { .api }
184
// Error constructor options
185
interface VErrorOptions {
186
    cause?: Error;              // Underlying cause error
187
    name?: string;              // Error name override  
188
    info?: Object;              // Additional structured metadata
189
    skipCauseMessage?: boolean; // Skip appending cause message
190
    strict?: boolean;           // Force strict printf interpretation (like SError)
191
    constructorOpt?: Function;  // Constructor for stack trace capture
192
}
193

194
// Common error properties
195
interface VErrorInstance {
196
    name: string;           // Error name
197
    message: string;        // Complete error message including causes
198
    jse_shortmsg: string;   // Original short message without causes
199
    jse_cause?: Error;      // Reference to cause error
200
    jse_info: Object;       // Additional information properties
201
    stack: string;          // Stack trace
202
}
203
```