### Table of Contents - [VErrorOptions][1] - [Parameters][2] - [VError][3] - [Parameters][4] - [Properties][5] - [Examples][6] - [assignInfo][7] - [Parameters][8] - [info][9] - [toString][10] - [isVError][11] - [Parameters][12] - [assignInfo][13] - [Parameters][14] - [cause][15] - [Parameters][16] - [info][17] - [Parameters][18] - [findCauseByName][19] - [Parameters][20] - [hasCauseWithName][21] - [Parameters][22] - [fullStack][23] - [Parameters][24] - [errorFromList][25] - [Parameters][26] - [errorForEach][27] - [Parameters][28] - [PError][29] - [Parameters][30] - [SError][31] - [Parameters][32] - [MultiError][33] - [Parameters][34] - [Examples][35] - [errors][36] - [WError][37] - [Parameters][38] - [toString][39] ## VErrorOptions Type: [Object][40] ### Parameters - `name` **[String][41]** Name of the error. - `cause` **[Error][42]?** Indicates that the new error was caused by `cause`. - `strict` **[Boolean][43]** If true, then `null` and `undefined` values in `sprintf_args` are passed through to `sprintf()` (optional, default `false`) - `constructorOpt` **[Function][44]?** \-If specified, then the stack trace for this error ends at function `constructorOpt`. - `info` **[Object][40]?** Specifies arbitrary informational properties. - `skipPrintf` **[Boolean][43]** If true, then `sprintf()` is not called (optional, default `false`) ## VError About Constructor: All of these forms construct a new VError that behaves just like the built-in JavaScript `Error` class, with some additional methods described below. About Properties: For all of these classes except `PError`, the printf-style arguments passed to the constructor are processed with `sprintf()` to form a message. For `WError`, this becomes the complete `message` property. For `SError` and `VError`, this message is prepended to the message of the cause, if any (with a suitable separator), and the result becomes the `message` property. The `stack` property is managed entirely by the underlying JavaScript implementation. It's generally implemented using a getter function because constructing the human-readable stack trace is somewhat expensive. ### Parameters - `arg` **...([String][41] \| [VErrorOptions][45] \| [Error][42])?** sprintf args, options or cause - `args` **...[String][41]?** sprintf args ### Properties - `name` **[String][41]** Programmatically-usable name of the error. - `message` **[String][41]** Human-readable summary of the failure. Programmatically-accessible details are provided through `VError.info(err)` class method. - `stack` **[String][41]** Human-readable stack trace where the Error was constructed. ### Examples ```javascript // This is the most general form. You can specify any supported options // including "cause" and "info") this way. new VError(options, sprintf_args...) ``` ```javascript // This is a useful shorthand when the only option you need is "cause". new VError(cause, sprintf_args...) ``` ```javascript // This is a useful shorthand when you don't need any options at all. new VError(sprintf_args...) ``` ### assignInfo Appends any keys/fields to the existing jse_info. this can stomp over any existing fields. #### Parameters - `obj` **[Object][40]** source obj to assign fields from Returns **[Object][40]** new info object ### info Instance level convenience method vs using the static methods on VError. Returns **[Object][40]** info object ### toString A string representing the VError. Returns **[String][41]** string representation ### isVError Checks if an error is a VError or VError sub-class. #### Parameters - `err` **[Error][42]** error Returns **[Boolean][43]** is a VError or VError sub-class ### assignInfo Appends any keys/fields to the `jse_info`. This can stomp over any existing fields. Note: This method is static because in this way we don't need to check on VError versions to be sure `assignInfo` method is supported. #### Parameters - `err` **[Error][42]** error - `obj` **[Object][40]** source obj to assign fields from Returns **[Object][40]** new info object ### cause Returns the next Error in the cause chain for `err`, or `null` if there is no next error. See the `cause` argument to the constructor. Errors can have arbitrarily long cause chains. You can walk the `cause` chain by invoking `VError.cause(err)` on each subsequent return value. If `err` is not a `VError`, the cause is `null`. #### Parameters - `err` **[VError][46]** error Returns **([undefined][47] \| [Error][42])** Error cause if any ### info Returns an object with all of the extra error information that's been associated with this Error and all of its causes. These are the properties passed in using the `info` option to the constructor. Properties not specified in the constructor for this Error are implicitly inherited from this error's cause. These properties are intended to provide programmatically-accessible metadata about the error. For an error that indicates a failure to resolve a DNS name, informational properties might include the DNS name to be resolved, or even the list of resolvers used to resolve it. The values of these properties should generally be plain objects (i.e., consisting only of null, undefined, numbers, booleans, strings, and objects and arrays containing only other plain objects). #### Parameters - `err` **[VError][46]** error Returns **[Object][40]** info object ### findCauseByName The `findCauseByName()` function traverses the cause chain for `err`, looking for an error whose `name` property matches the passed in `name` value. If no match is found, `null` is returned. If all you want is to know _whether_ there's a cause (and you don't care what it is), you can use `VError.hasCauseWithName(err, name)`. If a vanilla error or a non-VError error is passed in, then there is no cause chain to traverse. In this scenario, the function will check the `name` property of only `err`. #### Parameters - `err` **[VError][46]** error - `name` **[String][41]** name of cause Error Returns **(null | [Error][42])** cause if any ### hasCauseWithName Returns true if and only if `VError.findCauseByName(err, name)` would return a non-null value. This essentially determines whether `err` has any cause in its cause chain that has name `name`. #### Parameters - `err` **[VError][46]** error - `name` **[String][41]** name of cause Error Returns **[Boolean][43]** has cause ### fullStack Returns a string containing the full stack trace, with all nested errors recursively reported as `'caused by:' + err.stack`. #### Parameters - `err` **[VError][46]** error Returns **[String][41]** full stack trace ### errorFromList Given an array of Error objects (possibly empty), return a single error representing the whole collection of errors. If the list has: - 0 elements, returns `null` - 1 element, returns the sole error - more than 1 element, returns a MultiError referencing the whole list This is useful for cases where an operation may produce any number of errors, and you ultimately want to implement the usual `callback(err)` pattern. You can accumulate the errors in an array and then invoke `callback(VError.errorFromList(errors))` when the operation is complete. #### Parameters - `errors` **[Array][48]<[Error][42]>** errors Returns **(null | [Error][42] \| [MultiError][49])** single or multi error if any ### errorForEach Convenience function for iterating an error that may itself be a MultiError. In all cases, `err` must be an Error. If `err` is a MultiError, then `func` is invoked as `func(errorN)` for each of the underlying errors of the MultiError. If `err` is any other kind of error, `func` is invoked once as `func(err)`. In all cases, `func` is invoked synchronously. This is useful for cases where an operation may produce any number of warnings that may be encapsulated with a MultiError -- but may not be. This function does not iterate an error's cause chain. #### Parameters - `err` **[Error][42]** error - `func` **[Function][44]** iterator Returns **[undefined][47]** no return value ## PError **Extends VError** PError is like VError, but the message is not run through printf-style templating. ### Parameters - `arg` **...([String][41] \| [VErrorOptions][45] \| [Error][42])?** sprintf args, options or cause - `args` **...[String][41]?** sprintf args ## SError **Extends VError** SError is like VError, but stricter about types. You cannot pass "null" or "undefined" as string arguments to the formatter. ### Parameters - `arg` **...([String][41] \| [VErrorOptions][45] \| [Error][42])?** sprintf args, options or cause - `args` **...[String][41]?** sprintf args ## MultiError **Extends VError** Represents a collection of errors for the purpose of consumers that generally only deal with one error. Callers can extract the individual errors contained in this object, but may also just treat it as a normal single error, in which case a summary message will be printed. ### Parameters - `errors` **[Array][48]<[Error][42]>** errors ### Examples ```javascript // `error_list` is an array of at least one `Error` object. new MultiError(error_list) // The cause of the MultiError is the first error provided. None of the // other `VError` options are supported. The `message` for a MultiError // consists the `message` from the first error, prepended with a message // indicating that there were other errors. //For example: err = new MultiError([ new Error('failed to resolve DNS name "abc.example.com"'), new Error('failed to resolve DNS name "def.example.com"'), ]); console.error(err.message); // outputs: // first of 2 errors: failed to resolve DNS name "abc.example.com" ``` ### errors Returns an array of the errors used to construct this MultiError. Returns **[Array][48]<[Error][42]>** errors ## WError **Extends VError** WError for wrapping errors while hiding the lower-level messages from the top-level error. This is useful for API endpoints where you don't want to expose internal error messages, but you still want to preserve the error chain for logging and debugging ### Parameters - `arg` **...([String][41] \| [VErrorOptions][45] \| [Error][42])?** sprintf args, options or cause - `args` **...[String][41]?** sprintf args ### toString A string representing the WError. Returns **[String][41]** string representation [1]: #verroroptions [2]: #parameters [3]: #verror [4]: #parameters-1 [5]: #properties [6]: #examples [7]: #assigninfo [8]: #parameters-2 [9]: #info [10]: #tostring [11]: #isverror [12]: #parameters-3 [13]: #assigninfo-1 [14]: #parameters-4 [15]: #cause [16]: #parameters-5 [17]: #info-1 [18]: #parameters-6 [19]: #findcausebyname [20]: #parameters-7 [21]: #hascausewithname [22]: #parameters-8 [23]: #fullstack [24]: #parameters-9 [25]: #errorfromlist [26]: #parameters-10 [27]: #errorforeach [28]: #parameters-11 [29]: #perror [30]: #parameters-12 [31]: #serror [32]: #parameters-13 [33]: #multierror [34]: #parameters-14 [35]: #examples-1 [36]: #errors [37]: #werror [38]: #parameters-15 [39]: #tostring-1 [40]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object [41]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String [42]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error [43]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean [44]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function [45]: #verroroptions [46]: #verror [47]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined [48]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array [49]: #multierror