TypeScript Typed Error Handling: Stop Using any in Catch Blocks

try {
  await paymentGateway.charge(user.id, amount);
} catch (err: any) {
  // Classic runtime crash: Cannot read properties of undefined (reading 'message')
  logger.error("Payment failed: " + err.response.data.message);
  showNotification(err.response.data.message);
}

throw "Something went wrong"; // Thrown as string
throw 500;                    // Thrown as number
throw null;                   // Thrown as null

interface CheckoutResponse {
  success: boolean;
  transactionId?: string;
}
 
// Unsafe service throwing arbitrary exceptions
class LegacyPaymentService {
  async processPayment(amount: number): Promise<CheckoutResponse> {
    if (amount <= 0) {
      throw new Error("INVALID_AMOUNT");
    }
    if (amount > 10000) {
      // Throwing an arbitrary object instead of an Error instance
      throw { code: "LIMIT_EXCEEDED", limit: 10000 };
    }
    return { success: true, transactionId: "tx_98765" };
  }
}
 
// Unsafe client consumption
async function handleCheckout(amount: number) {
  const service = new LegacyPaymentService();
  try {
    const result = await service.processPayment(amount);
    console.log(`Success: ${result.transactionId}`);
  } catch (err: any) { // Anti-pattern: explicit 'any'
    // CRASH RISK: err might not have a 'code' property
    if (err.code === "LIMIT_EXCEEDED") {
      console.error(`Failed: Amount exceeds limit of ${err.limit}`);
    } else {
      // CRASH RISK: err.message is undefined if a raw object was thrown
      console.error(`System error: ${err.message.toUpperCase()}`);
    }
  }
}

// ==========================================
// 1. Custom Error Classes & Type Guards
// ==========================================
 
export abstract class BaseApplicationError extends Error {
  abstract readonly code: string;
  abstract readonly statusCode: number;
 
  constructor(message: string, public readonly contextualData?: Record<string, unknown>) {
    super(message);
    // Restore prototype chain for custom errors in ES5 environments
    Object.setPrototypeOf(this, new.target.prototype);
    Error.captureStackTrace(this, this.constructor);
  }
}
 
export class PaymentLimitExceededError extends BaseApplicationError {
  readonly code = "PAYMENT_LIMIT_EXCEEDED";
  readonly statusCode = 400;
 
  constructor(public readonly limit: number, public readonly attempted: number) {
    super(`Payment limit exceeded. Maximum allowed is ${limit}, but attempted ${attempted}.`, {
      limit,
      attempted,
    });
  }
}
 
export class NetworkTimeoutError extends BaseApplicationError {
  readonly code = "NETWORK_TIMEOUT";
  readonly statusCode = 503;
}
 
// Runtime Type Guard to verify if an unknown error matches our base error architecture
export function isApplicationError(error: unknown): error is BaseApplicationError {
  return error instanceof BaseApplicationError;
}
 
// ==========================================
// 2. The Result Pattern for Expected Failures
// ==========================================
 
export type Result<T, E> = 
  | { success: true; value: T } 
  | { success: false; error: E };
 
export const ok = <T>(value: T): Result<T, never> => ({ success: true, value });
export const err = <E>(error: E): Result<never, E> => ({ success: false, error });
 
// Expected domain failure types
export type PaymentValidationFailure = 
  | { type: "INVALID_CURRENCY"; currency: string }
  | { type: "INSUFFICIENT_FUNDS"; balance: number; required: number };
 
// ==========================================
// 3. Resilient Implementation
// ==========================================
 
class ProductionPaymentService {
  // Expected failures are returned as values.
  // Unexpected system failures are thrown.
  async processPayment(
    amount: number, 
    balance: number,
    currency: string
  ): Promise<Result<{ transactionId: string }, PaymentValidationFailure>> {
    
    // Domain Validation (Expected)
    if (currency !== "USD") {
      return err({ type: "INVALID_CURRENCY", currency });
    }
    if (amount > balance) {
      return err({ type: "INSUFFICIENT_FUNDS", balance, required: amount });
    }
 
    // Exceptional Validation (Unexpected / System Limits)
    if (amount > 10000) {
      throw new PaymentLimitExceededError(10000, amount);
    }
 
    try {
      // Simulate an unstable network connection
      if (Math.random() > 0.9) {
        throw new Error("Socket hang up"); // Unhandled standard library exception
      }
      return ok({ transactionId: "tx_secure_12345" });
    } catch (networkErr) {
      // Wrap generic third-party errors immediately at the system boundary
      throw new NetworkTimeoutError("The upstream payment gateway timed out.", {
        originalError: networkErr instanceof Error ? networkErr.message : String(networkErr)
      });
    }
  }
}
 
// ==========================================
// 4. Safe Consumer Execution
// ==========================================
 
async function runCheckout() {
  const service = new ProductionPaymentService();
  
  try {
    const result = await service.processPayment(12000, 15000, "USD");
 
    // Handling Expected Failures via Result Monad
    if (!result.success) {
      switch (result.error.type) {
        case "INVALID_CURRENCY":
          console.warn(`User tried paying with unsupported currency: ${result.error.currency}`);
          break;
        case "INSUFFICIENT_FUNDS":
          console.warn(`Declined. User balance: ${result.error.balance}. Required: ${result.error.required}`);
          break;
        default:
          // Compile-time assertion of exhaustiveness
          const _exhaustiveCheck: never = result.error;
          throw new Error(`Unhandled failure type: ${JSON.stringify(_exhaustiveCheck)}`);
      }
      return;
    }
 
    console.log(`Successfully charged! Transaction ID: ${result.value.transactionId}`);
 
  } catch (error: unknown) {
    // Catch-all block handles ONLY exceptional, unexpected errors safely.
    // There are NO unsafe casts ("as any") here.
    
    if (isApplicationError(error)) {
      // The compiler now knows this is a structured BaseApplicationError
      console.error(`[${error.code}] Status: ${error.statusCode}. Details: ${error.message}`);
      
      if (error instanceof PaymentLimitExceededError) {
        // Specifically narrow to custom subclass properties
        console.error(`Attempted Limit: ${error.attempted}. Limit Cap: ${error.limit}`);
      }
    } else if (error instanceof Error) {
      // Handle standard JS errors (e.g., ReferenceError, TypeError)
      console.error(`Internal System Error: ${error.message}`, { stack: error.stack });
    } else {
      // Fallback for raw thrown objects, strings, or nulls
      console.error("An unhandled, non-standard error occurred:", String(error));
    }
  }
}