CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-verror

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/verror@1.10.x
Publish Source
CLI
Badge
tessl/npm-verror badge