or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

error-classes.mdindex.mdstatic-utilities.mdverror-class.md
tile.json

tessl/npm-verror

Rich JavaScript errors with printf-style messages, error chaining, and structured metadata

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/verror@1.10.x

To install, run

npx @tessl/cli install tessl/npm-verror@1.10.0

index.mddocs/

VError

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.

Package Information

  • Package Name: verror
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install verror

Core Imports

const VError = require('verror');

Access to other error classes:

const VError = require('verror');
const SError = VError.SError;
const WError = VError.WError;
const MultiError = VError.MultiError;

Basic Usage

const VError = require('verror');

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

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

// Error with metadata
const err3 = new VError({
    name: 'ConnectionError',
    cause: originalErr,
    info: { 
        hostname: '127.0.0.1', 
        port: 80,
        errno: 'ECONNREFUSED'
    }
}, 'connection failed to %s:%d', '127.0.0.1', 80);

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

Architecture

VError is built around several key components:

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

Capabilities

VError Class

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

/**
 * Main error constructor with multiple signatures
 * @param {Error|Object|string} [causeOrOptionsOrMessage] - Cause error, options object, or message
 * @param {...*} args - Printf-style arguments for message formatting
 */
function VError(causeOrOptionsOrMessage, ...args);

// Constructor options
interface VErrorOptions {
    cause?: Error;              // Underlying cause error
    name?: string;              // Error name override
    info?: Object;              // Additional structured metadata
    skipCauseMessage?: boolean; // Skip appending cause message
    strict?: boolean;           // Force strict printf interpretation (like SError)
    constructorOpt?: Function;  // Constructor for stack trace capture
}

VError Class

SError Class

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

/**
 * Strict error constructor - same signatures as VError but with strict printf parsing
 * @param {Error|Object|string} [causeOrOptionsOrMessage] - Cause error, options object, or message
 * @param {...*} args - Printf-style arguments (strict interpretation)
 */
function SError(causeOrOptionsOrMessage, ...args);

Error Classes

WError Class

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

/**
 * Wrapping error constructor that hides cause messages
 * @param {Error|Object|string} [causeOrOptionsOrMessage] - Cause error, options object, or message
 * @param {...*} args - Printf-style arguments for message formatting
 */
function WError(causeOrOptionsOrMessage, ...args);

Error Classes

MultiError Class

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

/**
 * Multi-error container constructor
 * @param {Error[]} errors - Array of Error objects (at least 1 required)
 */
function MultiError(errors);

interface MultiError {
    /** Returns copy of the errors array */
    errors(): Error[];
}

Error Classes

Static Utility Methods

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

/**
 * Get the cause of any Error object
 * @param {Error} err - Error to inspect
 * @returns {Error|null} Cause error or null if no cause
 */
VError.cause(err);

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

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

/**
 * Check if cause chain contains error with specific name
 * @param {Error} err - Error to search from
 * @param {string} name - Error name to find  
 * @returns {boolean} True if found
 */
VError.hasCauseWithName(err, name);

Static Utilities

Types

// Error constructor options
interface VErrorOptions {
    cause?: Error;              // Underlying cause error
    name?: string;              // Error name override  
    info?: Object;              // Additional structured metadata
    skipCauseMessage?: boolean; // Skip appending cause message
    strict?: boolean;           // Force strict printf interpretation (like SError)
    constructorOpt?: Function;  // Constructor for stack trace capture
}

// Common error properties
interface VErrorInstance {
    name: string;           // Error name
    message: string;        // Complete error message including causes
    jse_shortmsg: string;   // Original short message without causes
    jse_cause?: Error;      // Reference to cause error
    jse_info: Object;       // Additional information properties
    stack: string;          // Stack trace
}