or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-aggregate-error

Create an error from multiple errors

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/aggregate-error@5.0.x

To install, run

npx @tessl/cli install tessl/npm-aggregate-error@5.0.0

index.mddocs/

Aggregate Error

Aggregate Error is a JavaScript utility that creates an error from multiple errors. It extends the native Error class to combine multiple errors into a single, formatted error with clean stack traces. This package is particularly useful for validation libraries, batch operations, or parallel processing scenarios where you want to report all failures rather than just the first one encountered.

Package Information

  • Package Name: aggregate-error
  • Package Type: npm
  • Language: JavaScript (ESM) with TypeScript definitions
  • Installation: npm install aggregate-error
  • Node.js: Requires Node.js 18+

Core Imports

import AggregateError from 'aggregate-error';

Note: This is an ESM-only package (Node.js 18+). CommonJS imports are not supported.

Basic Usage

import AggregateError from 'aggregate-error';

// Create an aggregate error from multiple error types
const error = new AggregateError([
  new Error('First error'),
  'String error message',
  { message: 'Object with message', code: 'ERR_CODE' }
]);

throw error;
// Throws formatted error with all sub-errors included

// Access individual errors
for (const individualError of error.errors) {
  console.log(individualError.message);
}

Capabilities

AggregateError Class

Creates an error from multiple errors with formatted stack traces and error normalization.

/**
 * Creates an error from multiple errors
 * @param {Array<Error|object|string>} errors - Array of errors to aggregate
 * @throws {TypeError} If errors parameter is not an Array
 */
class AggregateError extends Error {
  constructor(errors);
  
  /** Error name, always 'AggregateError' */
  readonly name: 'AggregateError';
  
  /** Read-only array of aggregated errors */
  readonly errors: Error[];
}

Parameters:

  • errors (Array): Array of errors to aggregate. Each item can be:
    • Error instance: Used as-is
    • string: Converted to new Error(string)
    • object: Properties copied to new Error(object.message)

Properties:

  • name: Always set to 'AggregateError'
  • errors: Read-only getter that returns a copy of the aggregated errors array
  • message: Formatted string containing all error messages with proper indentation
  • stack: Standard Error stack trace

Error Handling:

The constructor normalizes all input types to Error instances:

  • Error objects are used directly
  • Strings are converted to new Error(string)
  • Plain objects have their properties copied to a new Error instance
  • Objects without a message property create an Error with undefined message

Stack Trace Processing:

  • Automatically cleans internal stack traces from aggregate-error internals
  • Indents error messages for readability using 4 spaces
  • Handles errors without stack properties gracefully
  • Handles errors with empty stack properties gracefully

Usage Examples:

import AggregateError from 'aggregate-error';

// Mixed error types
const error = new AggregateError([
  new Error('Network timeout'),
  'Invalid input format',
  { message: 'Validation failed', field: 'email', code: 'INVALID_EMAIL' }
]);

console.log(error.message);
// Output will be formatted with indented error messages

// Access individual errors
const [networkError, formatError, validationError] = error.errors;
console.log(validationError.code); // 'INVALID_EMAIL'

// Error handling in async operations
async function processItems(items) {
  const errors = [];
  
  for (const item of items) {
    try {
      await processItem(item);
    } catch (err) {
      errors.push(err);
    }
  }
  
  if (errors.length > 0) {
    throw new AggregateError(errors);
  }
}

// Type checking
try {
  new AggregateError('not an array');
} catch (err) {
  console.log(err instanceof TypeError); // true
  console.log(err.message); // 'Expected input to be an Array, got string'
}

Types

For TypeScript users:

/**
 * Create an error from multiple errors.
 */
export default class AggregateError<T extends Error = Error> extends Error {
  readonly name: 'AggregateError';
  readonly errors: readonly [T]; // Actual TypeScript definition (buggy - should be readonly T[])
  
  /**
   * @param errors - Array of errors to aggregate  
   */
  constructor(errors: ReadonlyArray<T | Record<string, any> | string>);
}

Note on TypeScript Types: The TypeScript definition file contains a bug - it defines errors as readonly [T] (a single-element tuple) instead of the correct readonly T[] (array). The runtime implementation actually returns an array of errors. When using this library, treat errors as an array despite the incorrect TypeScript definition.

The generic type parameter T allows you to specify the type of Error instances:

import AggregateError from 'aggregate-error';

class CustomError extends Error {
  code: string;
  constructor(message: string, code: string) {
    super(message);
    this.code = code;
  }
}

const customErrors = [
  new CustomError('Error 1', 'E001'),
  new CustomError('Error 2', 'E002')
];

const aggregateError = new AggregateError<CustomError>(customErrors);
// aggregateError.errors is now typed as readonly CustomError[]