Node.js Error Handling: async/await, Promises & Real Patterns

const fs = require('fs');
const { EventEmitter } = require('events');

// ─────────────────────────────────────────
// CHANNEL 1: Synchronous throw
// ─────────────────────────────────────────
function parsUserInput(rawJson) {
  // JSON.parse throws synchronously on invalid input
  return JSON.parse(rawJson);
}

try {
  const result = parsUserInput('{ invalid json }');
} catch (syncError) {
  // syncError is a SyntaxError instance — we can inspect it
  console.log('[Sync] Caught:', syncError.message);
}

// ─────────────────────────────────────────
// CHANNEL 2: Error-first callback (classic Node.js pattern)
// ─────────────────────────────────────────
fs.readFile('/tmp/does-not-exist.txt', 'utf8', (callbackError, fileContents) => {
  if (callbackError) {
    // Always check the FIRST argument — null means success, Error means failure
    console.log('[Callback] Caught:', callbackError.code); // e.g. ENOENT
    return; // CRITICAL: return here or code below runs with undefined fileContents
  }
  console.log('File contents:', fileContents);
});

// ─────────────────────────────────────────
// CHANNEL 3: Promise rejection
// ─────────────────────────────────────────
async function fetchUserData(userId) {
  // Simulating a database call that rejects
  return Promise.reject(new Error(`User ${userId} not found in database`));
}

async function loadUserProfile() {
  try {
    // Without this try/catch, the rejection becomes an UnhandledPromiseRejection
    const user = await fetchUserData(42);
    console.log('User:', user);
  } catch (promiseError) {
    console.log('[Promise] Caught:', promiseError.message);
  }
}

loadUserProfile();

// ─────────────────────────────────────────
// CHANNEL 4: EventEmitter 'error' event
// ─────────────────────────────────────────
const dataStream = new EventEmitter();

// If you remove this listener, the emit below CRASHES the process
dataStream.on('error', (emitterError) => {
  console.log('[EventEmitter] Caught:', emitterError.message);
});

// Simulate a stream error (e.g. a broken pipe or failed socket)
dataStream.emit('error', new Error('Connection to upstream service dropped'));

// ─────────────────────────────────────────
// Base application error — all custom errors extend this
// ─────────────────────────────────────────
class AppError extends Error {
  constructor(message, statusCode, errorCode) {
    super(message); // Pass message to the built-in Error constructor
    this.name = this.constructor.name; // 'ValidationError', 'DatabaseError', etc.
    this.statusCode = statusCode;      // HTTP status to return to the client
    this.errorCode = errorCode;        // Machine-readable string for programmatic checks
    this.isOperational = true;         // Marks this as a KNOWN error, not a bug

    // Preserves the correct stack trace in V8 (Node.js's JS engine)
    Error.captureStackTrace(this, this.constructor);
  }
}

// ─────────────────────────────────────────
// Specific error types — each carries its own domain context
// ─────────────────────────────────────────
class ValidationError extends AppError {
  constructor(message, fieldName) {
    super(message, 422, 'VALIDATION_ERROR');
    this.fieldName = fieldName; // Which form field caused the problem
  }
}

class DatabaseError extends AppError {
  constructor(message, queryDetails) {
    super(message, 503, 'DATABASE_ERROR');
    this.queryDetails = queryDetails; // Store the failing query for logging
    this.isRetryable = true;          // Hint to the caller: safe to retry
  }
}

class NotFoundError extends AppError {
  constructor(resourceType, resourceId) {
    super(`${resourceType} with ID ${resourceId} was not found`, 404, 'NOT_FOUND');
    this.resourceType = resourceType;
    this.resourceId = resourceId;
  }
}

// ─────────────────────────────────────────
// Simulated service layer that throws typed errors
// ─────────────────────────────────────────
async function createUserAccount(userData) {
  // Validate required fields before touching the database
  if (!userData.email || !userData.email.includes('@')) {
    throw new ValidationError('Email address is not valid', 'email');
  }

  if (!userData.password || userData.password.length < 8) {
    throw new ValidationError('Password must be at least 8 characters', 'password');
  }

  // Simulate a database connection failure
  const dbAvailable = false;
  if (!dbAvailable) {
    throw new DatabaseError(
      'Primary database is unreachable',
      { operation: 'INSERT', table: 'users' }
    );
  }
}

// ─────────────────────────────────────────
// Centralized error handler — uses instanceof to route by type
// ─────────────────────────────────────────
async function handleCreateUser(requestBody) {
  try {
    await createUserAccount(requestBody);
    console.log('User created successfully');
  } catch (error) {
    if (error instanceof ValidationError) {
      // Client made a bad request — tell them exactly what's wrong
      console.log(`[${error.statusCode}] Validation failed on field '${error.fieldName}': ${error.message}`);
    } else if (error instanceof DatabaseError) {
      // Infrastructure problem — log details, maybe retry
      console.log(`[${error.statusCode}] Database error: ${error.message}`);
      console.log('  Query context:', JSON.stringify(error.queryDetails));
      console.log('  Retryable:', error.isRetryable);
    } else {
      // Unknown bug — escalate and don't expose internals to the client
      console.log('[500] Unexpected error — this is a bug:', error.message);
    }
  }
}

// Test with bad email
await handleCreateUser({ email: 'not-an-email', password: 'securepassword123' });

// Test with db down
await handleCreateUser({ email: 'user@example.com', password: 'securepassword123' });

const express = require('express');

const app = express();
app.use(express.json());

// ─────────────────────────────────────────
// Re-use custom error classes from previous section
// ─────────────────────────────────────────
class AppError extends Error {
  constructor(message, statusCode, errorCode) {
    super(message);
    this.name = this.constructor.name;
    this.statusCode = statusCode;
    this.errorCode = errorCode;
    this.isOperational = true;
    Error.captureStackTrace(this, this.constructor);
  }
}

class NotFoundError extends AppError {
  constructor(resourceType, resourceId) {
    super(`${resourceType} with id '${resourceId}' does not exist`, 404, 'NOT_FOUND');
  }
}

// ─────────────────────────────────────────
// asyncHandler: wraps async routes so rejections reach next()
// Without this, unhandled promise rejections crash Express silently
// ─────────────────────────────────────────
const asyncHandler = (routeFunction) => {
  return (req, res, next) => {
    // If routeFunction returns a rejected promise, .catch(next) calls next(error)
    Promise.resolve(routeFunction(req, res, next)).catch(next);
  };
};

// ─────────────────────────────────────────
// Simulated database call — returns a Promise
// ─────────────────────────────────────────
async function findUserById(userId) {
  const mockDatabase = {
    '101': { id: 101, name: 'Alice Nakamura', role: 'admin' },
    '202': { id: 202, name: 'Ben Okafor', role: 'viewer' },
  };
  const user = mockDatabase[String(userId)];
  if (!user) {
    // Throw a typed error — the global handler will format the response
    throw new NotFoundError('User', userId);
  }
  return user;
}

// ─────────────────────────────────────────
// Route handlers — clean, no error formatting logic here
// ─────────────────────────────────────────
app.get(
  '/users/:userId',
  asyncHandler(async (req, res) => {
    // If findUserById throws, asyncHandler catches it and calls next(error)
    const user = await findUserById(req.params.userId);
    res.status(200).json({ success: true, data: user });
  })
);

app.get(
  '/users/:userId/permissions',
  asyncHandler(async (req, res) => {
    const user = await findUserById(req.params.userId);
    // Simulate an unexpected runtime error (a genuine bug)
    if (user.role === 'admin') {
      throw new Error('Permissions module failed to load — internal bug');
    }
    res.status(200).json({ success: true, permissions: ['read'] });
  })
);

// ─────────────────────────────────────────
// Global error handling middleware — MUST be registered LAST
// Express recognises the 4-argument signature (err, req, res, next)
// ─────────────────────────────────────────
app.use((err, req, res, next) => { // eslint-disable-line no-unused-vars
  // Log everything — even operational errors need an audit trail
  console.error(`[${new Date().toISOString()}] ${err.name}: ${err.message}`);

  // Operational errors: we know what this is, safe to tell the client
  if (err.isOperational) {
    return res.status(err.statusCode).json({
      success: false,
      error: {
        code: err.errorCode,
        message: err.message,
      },
    });
  }

  // Non-operational (unexpected bugs): hide internals, alert your team
  console.error('CRITICAL — non-operational error, needs investigation:', err.stack);
  return res.status(500).json({
    success: false,
    error: {
      code: 'INTERNAL_ERROR',
      message: 'An unexpected error occurred. Our team has been notified.',
    },
  });
});

// ─────────────────────────────────────────
// Process-level safety net — last resort for anything that slips through
// ─────────────────────────────────────────
process.on('unhandledRejection', (reason, promise) => {
  // Log it but DON'T crash — an http server should stay up if possible
  console.error('Unhandled Promise Rejection at:', promise, 'reason:', reason);
  // In a real app: alert via PagerDuty/Sentry here
});

process.on('uncaughtException', (error) => {
  // This means something bypassed ALL error handling — the process is unstable
  console.error('Uncaught Exception — process will restart:', error.stack);
  // Give in-flight requests a moment to finish, then restart cleanly via PM2/Docker
  process.exit(1);
});

app.listen(3000, () => console.log('Server running on port 3000'));

// ─────────────────────────────────────────
// Example responses (simulate with curl or a test):
// GET /users/101   → 200 { success: true, data: { id: 101, name: 'Alice Nakamura' } }
// GET /users/999   → 404 { success: false, error: { code: 'NOT_FOUND', message: "User with id '999' does not exist" } }
// GET /users/101/permissions → 500 { success: false, error: { code: 'INTERNAL_ERROR', message: '...' } }
// ─────────────────────────────────────────

// ─────────────────────────────────────────
// Simulated async operations with realistic error scenarios
// ─────────────────────────────────────────
async function fetchOrderFromDatabase(orderId) {
  if (orderId <= 0) throw new Error(`Invalid order ID: ${orderId}`);
  return { id: orderId, product: 'Wireless Keyboard', quantity: 2, price: 79.99 };
}

async function fetchInventoryLevel(productName) {
  if (productName === 'Out of Stock Item') {
    throw new Error(`No inventory record found for: ${productName}`);
  }
  return { product: productName, available: 150 };
}

async function sendConfirmationEmail(emailAddress) {
  if (!emailAddress.includes('@')) {
    throw new Error(`Invalid email address: ${emailAddress}`);
  }
  return { sent: true, to: emailAddress };
}

// ─────────────────────────────────────────
// PATTERN 1: Sequential operations — one failure stops the chain
// Use when each step DEPENDS on the previous result
// ─────────────────────────────────────────
async function processOrderSequentially(orderId, customerEmail) {
  console.log('\n--- Sequential Processing ---');
  try {
    // Each await pauses here — if any throw, we jump to catch immediately
    const order = await fetchOrderFromDatabase(orderId);
    console.log(`Order fetched: ${order.product}`);

    const inventory = await fetchInventoryLevel(order.product);
    console.log(`Inventory confirmed: ${inventory.available} units available`);

    const emailResult = await sendConfirmationEmail(customerEmail);
    console.log(`Confirmation sent to: ${emailResult.to}`);

  } catch (processingError) {
    // One catch handles ALL three operations — clean and maintainable
    console.error(`Order processing failed: ${processingError.message}`);
  }
}

// ─────────────────────────────────────────
// PATTERN 2: Parallel operations — run independent tasks concurrently
// Use when steps DON'T depend on each other (faster than sequential)
// ─────────────────────────────────────────
async function loadDashboardData(userId) {
  console.log('\n--- Parallel Processing with Promise.allSettled ---');

  // Promise.all fails fast if ANY promise rejects — good for all-or-nothing scenarios
  // Promise.allSettled waits for ALL and reports each result — good for dashboards
  const [ordersResult, inventoryResult] = await Promise.allSettled([
    fetchOrderFromDatabase(userId),
    fetchInventoryLevel('Out of Stock Item'), // This will fail
  ]);

  // allSettled gives us { status: 'fulfilled' | 'rejected', value/reason }
  if (ordersResult.status === 'fulfilled') {
    console.log('Orders loaded:', ordersResult.value.product);
  } else {
    console.error('Orders failed to load:', ordersResult.reason.message);
  }

  if (inventoryResult.status === 'fulfilled') {
    console.log('Inventory loaded:', inventoryResult.value.available);
  } else {
    // Dashboard still renders — just without this section
    console.warn('Inventory unavailable, showing cached data:', inventoryResult.reason.message);
  }
}

// ─────────────────────────────────────────
// PATTERN 3: The floating promise trap — the silent killer
// ─────────────────────────────────────────
function demonstrateFloatingPromiseDanger() {
  console.log('\n--- Floating Promise (DANGER) ---');

  // BAD: This async call is NOT awaited and has NO .catch()
  // The error disappears. In older Node versions this was fully silent.
  // In Node 15+ it becomes an UnhandledPromiseRejection and CRASHES the process.
  // fetchOrderFromDatabase(-1); // <- DO NOT DO THIS

  // GOOD: Always attach a .catch() if you can't await
  fetchOrderFromDatabase(-1).catch((floatingError) => {
    console.error('Caught floating promise error:', floatingError.message);
  });

  // ALSO GOOD: Fire-and-forget with an async IIFE if you need async context
  (async () => {
    try {
      await sendConfirmationEmail('not-a-valid-email');
    } catch (iifError) {
      console.error('Caught IIFE async error:', iifError.message);
    }
  })();
}

// ─────────────────────────────────────────
// Run all patterns
// ─────────────────────────────────────────
(async () => {
  await processOrderSequentially(5, 'customer@shop.com');
  await loadDashboardData(5);
  demonstrateFloatingPromiseDanger();
})();