Extending the JavaScript Error Class: Full Guide

class CustomError extends Error {
  constructor(message) {
    super(message);                        // (1) Call Error constructor
    this.name = this.constructor.name;     // (2) Set name to class name
    if (Error.captureStackTrace) {         // (3) V8 stack optimization
      Error.captureStackTrace(this, this.constructor);
    }
  }
}
 
const err = new CustomError("test");
console.log(err.name);              // "CustomError"
console.log(err.message);          // "test"
console.log(err instanceof Error); // true
console.log(err.stack);            // Stack starting at the throw site

// This works in native ES6 but BREAKS with Babel ES5 output:
class MyError extends Error {}
 
const err = new MyError("oops");
console.log(err instanceof MyError); // false (!) — Babel bug
console.log(err instanceof Error);   // true

// Safe for ES5 transpilation AND native ES6
class SafeCustomError extends Error {
  constructor(message) {
    super(message);
    // Fix prototype chain for Babel/TypeScript ES5 output
    Object.setPrototypeOf(this, new.target.prototype);
    this.name = this.constructor.name;
  }
}
 
// Now instanceof works correctly even in transpiled code:
const err = new SafeCustomError("test");
console.log(err instanceof SafeCustomError); // true (everywhere)

class AppError extends Error {
  constructor(message: string) {
    super(message);
    Object.setPrototypeOf(this, new.target.prototype); // Required for ES5 target
    this.name = new.target.name;
  }
}

class AppError extends Error {
  /**
   * @param {string} message - Human-readable error description
   * @param {object} [options]
   * @param {string} [options.code] - Machine-readable error code
   * @param {Error} [options.cause] - Original error (ES2022 error chaining)
   * @param {object} [options.context] - Extra diagnostic data
   * @param {number} [options.statusCode] - HTTP status (for API errors)
   */
  constructor(message, options = {}) {
    super(message, { cause: options.cause });
    Object.setPrototypeOf(this, new.target.prototype);
    this.name = this.constructor.name;
    this.code = options.code ?? this.constructor.name.toUpperCase();
    this.context = options.context ?? {};
    this.statusCode = options.statusCode ?? 500;
    this.timestamp = new Date().toISOString();
    if (Error.captureStackTrace) {
      Error.captureStackTrace(this, this.constructor);
    }
  }
 
  toJSON() {
    return {
      name: this.name,
      code: this.code,
      message: this.message,
      statusCode: this.statusCode,
      timestamp: this.timestamp,
      context: this.context,
      cause: this.cause
        ? (this.cause instanceof Error
          ? { name: this.cause.name, message: this.cause.message }
          : this.cause)
        : undefined,
    };
  }
 
  toString() {
    return `${this.name} [${this.code}]: ${this.message}`;
  }
}

class ValidationError extends AppError {
  constructor(message, violations = []) {
    super(message, { statusCode: 400, code: "VALIDATION_FAILED" });
    this.violations = violations;
  }
 
  toJSON() {
    return { ...super.toJSON(), violations: this.violations };
  }
}
 
class NotFoundError extends AppError {
  constructor(resource, id) {
    super(`${resource} '${id}' not found`, {
      statusCode: 404,
      code: "NOT_FOUND",
      context: { resource, id },
    });
  }
}
 
class NetworkError extends AppError {
  constructor(message, { statusCode = 503, cause } = {}) {
    super(message, { statusCode, cause, code: "NETWORK_ERROR" });
  }
}

// Built-in AggregateError
const agg = new AggregateError(
  [new Error("First"), new Error("Second")],
  "Multiple operations failed"
);
console.log(agg.errors.length); // 2
console.log(agg instanceof Error); // true
 
// Custom aggregate for application domain
class BatchError extends AppError {
  constructor(message, errors = []) {
    super(message, { code: "BATCH_FAILED", statusCode: 500 });
    this.errors = errors;
    this.successCount = 0;
    this.failureCount = errors.length;
  }
 
  addFailure(item, error) {
    this.errors.push({ item, error });
    this.failureCount++;
    return this;
  }
 
  addSuccess() {
    this.successCount++;
    return this;
  }
 
  toJSON() {
    return {
      ...super.toJSON(),
      successCount: this.successCount,
      failureCount: this.failureCount,
      errors: this.errors.map(({ item, error }) => ({
        item,
        error: error instanceof AppError ? error.toJSON() : error.message,
      })),
    };
  }
}

// Mixin: adds HTTP-related properties
const HttpMixin = (Base) => class extends Base {
  constructor(message, statusCode, options) {
    super(message, options);
    this.statusCode = statusCode;
    this.isClientError = statusCode >= 400 && statusCode < 500;
    this.isServerError = statusCode >= 500;
  }
};
 
// Mixin: adds retry information
const RetryMixin = (Base) => class extends Base {
  constructor(message, retryable = true, options) {
    super(message, options);
    this.retryable = retryable;
    this.retryAfter = null;
  }
};
 
// Compose mixins
class ApiError extends HttpMixin(RetryMixin(AppError)) {
  constructor(message, statusCode) {
    const retryable = statusCode >= 500 || statusCode === 429;
    super(message, retryable);
    this.statusCode = statusCode; // Override from HttpMixin
  }
}
 
const err = new ApiError("Rate limited", 429);
console.log(err.retryable);    // true
console.log(err.isClientError); // true